The example app
| Route | What it does |
|---|---|
| / | Returns 404: the app has no home page |
| /dashboard/summary?review=1 | The page to review, with sample data only |
| /login | Redirects to /dashboard/summary after sign-in, with a relative Location header |
| /dashboard/summary/assets/app.css and /dashboard/summary/assets/chart.js | Loaded from paths below /dashboard/summary |
Publishing an origin, opening a page
qurl publish takes the origin your app listens on, such as http://127.0.0.1:3000, and refuses a path, a query or a fragment. That rule covers only the publish target: it does not limit which routes the shared app serves.
When the recipient opens their link or invitation, the session starts at the app’s root on its own qurl.site address. Until the session ends, every path of the app answers, so the recipient can go on to /dashboard/summary?review=1 in the same tab.
Through the API, a link’s target_path opens one path directly and limits the session to that path and the paths below it: /dashboard permits /dashboard/summary but not /dashboardx. The query part does not restrict access.
Steps
Publish the app’s origin with qURL™, not the page: qurl publish http://127.0.0.1:3000. The recipient opens their link or invitation and lands on /, and during the session every path answers, so they go on to /dashboard/summary?review=1 in the same tab. With an account, a link made through the API can open that page directly.
Install the qURL CLI
On macOS, install it with Homebrew. On Linux and Windows, download the package for your platform from the latest release; the CLI page lists each one. Nothing asks you to sign up.
brew install layervai/tap/qurl qurl --versionCheck the page on this machine first
Load the page locally. If the page, its styles and its redirect all work here, anything that breaks through qURL comes from hostnames, and the table below names the fix.
curl -sS -o /dev/null -w '%{http_code}\n' 'http://127.0.0.1:3000/dashboard/summary?review=1'Check: The command prints 200.
Choose who gets in
An email invitation names the person: only the invited address gets in, after verifying that mailbox and saving a passkey, and they come back with it. A one-time link is a bearer link for one visit: it opens once, for whoever holds it. Decide before you publish, because the invitation needs an invite-only publish.
Publish the origin, not the page
Leave the path off:
qurl publish http://127.0.0.1:3000/dashboard/summary is refused. The first publish creates this device’s identity, starts a background service that keeps serving after you close the terminal, and prints the app’s CRID.For one-time links: Publish plainly. The resource is private and opens for nobody until you share a link.
qurl publish http://127.0.0.1:3000For an email invitation: Publish invite-only, then check that the reply has private: true and the invite_only policy.
qurl publish http://127.0.0.1:3000 --access invite_only -o jsonLet the recipient in
Use the option that matches how you published.
A one-time link: Give the session enough time to reach the page and use it. Check that the expiry line says “single use”.
qurl share <CRID> --ttl 4h --session-duration 2hSend it in a direct message, not a public channel: whoever opens it first uses it. Avoid email and apps that preview links, because a scanner that runs the page could use its one opening. Don’t open it yourself to check it, for the same reason.
An email invitation: qURL emails the invitation. The recipient verifies the mailbox in their browser and saves a passkey.
qurl access invite <CRID> --email reviewer@example.com -o jsonTell the recipient where to go
Send the path as a written instruction beside the link or invitation. Change the path and the task to your own.
Open the link (or your emailed invitation) in a browser. The app's home page is empty on purpose. Once the app opens, replace everything after the site name in the address bar with /dashboard/summary?review=1 and press Enter. That is the page to review.Or open the page directly with an API link
With an account and API key, mint a link whose target_path is the page. The recipient lands on it after opening the link, and the session is limited to that path and the paths below it, so give target_path the shortest prefix that still covers the page’s own assets, or the styles and scripts outside it are refused. If sign-in or its callback uses a route outside that scope, use an unscoped link or invitation. Send the qurl_link from the reply, once, to the recipient.
curl -X POST https://api.layerv.ai/v1/qurls/<CRID>/mint_link \ -H "Authorization: Bearer $QURL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"target_path": "/dashboard/summary?review=1", "expires_in": "4h", "session_duration": "2h"}'Keep redirects and assets relative
A redirect whose Location is a path, such as /dashboard/summary, stays on the recipient’s qurl.site address. A redirect built from a configured base URL, such as http://localhost:3000/dashboard/summary, sends the recipient’s browser to their own machine. Use a path such as /dashboard/summary/assets/app.css so the asset stays within the scope of the example link; an absolute http://localhost URL does not. Use relative redirects and asset paths for the review, or build the base URL from the incoming request.
Allow the qurl.site hostnames in a dev server
The browser opens the app on an r_….qurl.site address, while the app receives Host c-….qurl.site with X-Forwarded-For and the other forwarding headers. A Host check needs .qurl.site allowed, as Vite’s server.allowedHosts does; a browser-origin check, such as Next.js allowedDevOrigins, needs the exact browser hostname.
Keep your app’s own sign-in
qURL decides who reaches the app. It does not sign anyone in, passes no identity or cookie of its own to your app, and leaves your login page in place. If /dashboard asks for a login, give the recipient an account with only the permissions the review needs. A sign-in provider whose callback is registered for localhost sends the browser back to localhost after login, so use a local username-and-password test account for the review. Never put a backend token in a URL you send.
End access
An unopened link stops at its --ttl and an opened session at its --session-duration.
qurl access revoke_invitation removes one invited person.qurl stopstops serving the app untilqurl start, andqurl deleteretires it for good after asking you to confirm.qurl stop <CRID> # pause; qurl start <CRID> resumes qurl delete <CRID> # permanent; asks you to confirm
What the recipient sees
The recipient opens the link or invitation and lands on the app’s root on its qurl.site address.
More
They go to /dashboard/summary?review=1 in the same tab and see the page with its styles and charts, as you do. A link minted with target_path opens that page directly.
Symptoms, causes and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| The page works locally, but the recipient sees a 404 | The app has no page at /, where every session starts | Send the path in your note, make / redirect there for the review, or mint a target_path link |
| A redirect lands on localhost | The app built an absolute URL from a configured base address | Use a relative redirect, or build the base URL from the request |
| Styles or scripts fail to load | Absolute localhost URLs in the page, or assets outside a target_path scope | Use relative asset paths; give target_path the shortest prefix that covers the assets, or omit it |
| “Blocked request. This host … is not allowed” | The dev server rejects the c-….qurl.site Host | Allow .qurl.site in the dev server’s host check |
| Sign-in loops back to the login page | A cookie set for another host, a callback to localhost, or a login route outside the link scope | Use the request host for cookies and a local test account if the callback points to localhost. Use an unscoped link if the login route is outside the link scope. |
| “Access link invalid” | The link was already used or has expired | Run qurl share again; the app does not need publishing again |
| Pages stop loading partway through the review | The session reached its --session-duration | Send a new link with a longer --session-duration, up to 24 hours |
Sources: Agent skill, API reference, qURL access behaviour.
Troubleshooting
| If you see | Do this |
|---|---|
| The recipient lands on a 404 at the root | Every session starts at /. Tell them the path to open in the same tab, or make / redirect there for the review. |
| qurl publish says the local app is not accepting TCP connections | Start the app first and check that curl works on the same address. qurl publish connects to localhost as 127.0.0.1, so if your app listens only on IPv6 (on macOS or Linux, lsof -iTCP -sTCP:LISTEN -nP shows [::1]), publish 'http://[::1]:PORT' instead, or start the dev server with --host 127.0.0.1 and publish that address. Neither requires listening on your LAN. Keep the quotes: zsh treats the brackets as a pattern. |
Show 5 more fixes
| If you see | Do this |
|---|---|
| The recipient sees “Access link invalid” | The link was already used or has expired. Run qurl share again and send the new link. |
| The recipient sees “Resource not found” | The resource was deleted after the link was made. Publish the app again, then run qurl share and send the new link. |
| publish rejects http://127.0.0.1 with “only HTTPS URLs are allowed”, asks you to log in, or prints no Access: line | Your qURL CLI is out of date. On macOS run brew update, then brew upgrade qurl; elsewhere install the latest release. After updating, qurl --version prints 3.4.1 or later, and every publish is private by default. |
| publish says this Linux session “can’t reach a systemd user manager” | You are in a container or sandbox without a user service manager. Run qurl publish with --foreground; sharing lasts as long as that process runs. Container and CI setup → |
| publish says “Quota Exceeded” with “protected resource limit reached”, or “Your qURL account has reached a plan limit” | You can see this without an account: a device with no account can keep up to 3 active resources, with links that last up to 24 hours. Run qurl list --status active, then qurl delete <CRID> for any you no longer need (it asks you to confirm; --yes skips that). qurl stop keeps the resource, so it does not free a slot. |
Frequently Asked Questions
Can I publish one page instead of the whole app?
qurl publish takes an origin only, so the app is shared from its root. To narrow a visit, mint a link through the API with target_path: the recipient lands on that path, and the session covers it and the paths below it.
Does the query string reach my app?
Yes. During the session the recipient’s requests reach your app with their path and query, so /dashboard/summary?review=1 arrives as it does locally. In a target_path link the query is carried to the landing page but does not restrict access.
Why does my app redirect the recipient to localhost?
It builds absolute URLs from a configured base address. The browser follows them to the recipient’s own machine. Use relative redirects, or build the base URL from the incoming request.
Does qURL replace my app’s login?
No. qURL decides who reaches the app; your login decides what each person can do inside it. Give the recipient an account with only the permissions the review needs.
Who else can reach my app while the link is open?
Opening the link starts a session for that browser, which lasts 1 hour by default. After a browser opens it, another browser on the same public IP cannot use its access. A script or agent that opens the link without a browser is admitted by its network address instead, which other devices on that public IP share until the session ends. A link admits whoever opens it: the API’s IP and country rules do not apply to the signed links qurl share issues. Keep your app’s own sign-in for anything sensitive.
Does my computer have to stay on?
Yes. The app is served from your machine, so the machine and the app must be running and connected. The background service reconnects after sleep, but the app is unavailable while the machine is asleep.