Skip to main content
← All guides

Share a local app with nested routes, redirects and sign-in

Why qURL here

Publish the whole app once and the recipient can open any page of it during their session, with no public URL and nothing deployed. Send them the path in a note, or mint a link that lands on the page itself.

See how qURL compares to zrok for outside reviewers →

The example app

The example app
RouteWhat it does
/Returns 404: the app has no home page
/dashboard/summary?review=1The page to review, with sample data only
/loginRedirects to /dashboard/summary after sign-in, with a relative Location header
/dashboard/summary/assets/app.css and /dashboard/summary/assets/chart.jsLoaded 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.

  1. 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 --version
  2. Check 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.

  3. 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.

  4. 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:3000

    For 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 json
  5. Let 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 2h

    Send 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 json
  6. Tell 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.
  7. 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.

  8. 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.

    Allow a tunnel’s hostname in your dev server →

  9. 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.

  10. 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 stop stops serving the app until qurl start, and qurl delete retires 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

Symptoms, causes and fixes
SymptomLikely causeFix
The page works locally, but the recipient sees a 404The app has no page at /, where every session startsSend the path in your note, make / redirect there for the review, or mint a target_path link
A redirect lands on localhostThe app built an absolute URL from a configured base addressUse a relative redirect, or build the base URL from the request
Styles or scripts fail to loadAbsolute localhost URLs in the page, or assets outside a target_path scopeUse 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 HostAllow .qurl.site in the dev server’s host check
Sign-in loops back to the login pageA cookie set for another host, a callback to localhost, or a login route outside the link scopeUse 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 expiredRun qurl share again; the app does not need publishing again
Pages stop loading partway through the reviewThe session reached its --session-durationSend a new link with a longer --session-duration, up to 24 hours

Sources: Agent skill, API reference, qURL access behaviour.

Troubleshooting

Troubleshooting
If you seeDo this
The recipient lands on a 404 at the rootEvery 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 connectionsStart 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
More troubleshooting
If you seeDo 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: lineYour 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.

Publish your app now

Install the CLI, then run one command. No sign-up, no API key.

Install the CLI →

Book a pilot

Tell us what to hide. We’ll scope a pilot.

Enterprise starts with a paid pilot on one application, typically 60 to 90 days, credited in full toward year one if you convert within 60 days. After that, an annual package sized to what you protect, not per seat.