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

> Share a local app whose useful page sits below the root: publish the origin with qURL, send the recipient to the path, and fix redirects, assets and sign-in.

Source: https://layerv.ai/guides/share-local-app-nested-routes/

---

[← All guides](https://layerv.ai/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 →](https://layerv.ai/compare/qurl-vs-zrok/)

Copies a prompt for any agent that runs commands. 

## What you need

- An app running on this machine, listening on 127.0.0.1, ::1 or localhost
- The qURL CLI 3.4.1 or later
- For an email invitation: qurl 3.6.0 or later
- For a link that opens a page directly: a LayerV account and API key

Content updated November 15, 2026.

## The example app

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

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. ### 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"}'
```
8. ### 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.
9. ### 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 →](https://layerv.ai/guides/allow-tunnel-hostname-in-dev-server/)
10. ### 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.
11. ### 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.

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__
| 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](https://layerv.ai/skills/qurl/SKILL.md) , [API reference](https://layerv.ai/docs/qurls.md) , [qURL access behaviour](https://layerv.ai/guides/share-localhost-with-temporary-access-link/#access-behaviour).

## Troubleshooting

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

__More troubleshooting__
| 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 →](https://layerv.ai/guides/share-from-a-container-or-ci/)                                                                                          |
| 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.

## Related Resources

[Guide: Share a dev server with a client →](https://layerv.ai/guides/share-dev-server-with-client/) [Guide: Give an external reviewer temporary access to localhost →](https://layerv.ai/guides/share-localhost-with-temporary-access-link/) [Guide: Allow a tunnel’s hostname in your dev server →](https://layerv.ai/guides/allow-tunnel-hostname-in-dev-server/) [Fix Vite “Blocked request. This host is not allowed” →](https://layerv.ai/guides/fix-vite-blocked-request-host-not-allowed/) [Fix Next.js blocked cross-origin dev requests →](https://layerv.ai/guides/fix-nextjs-blocked-cross-origin-dev-request/) [Guide: Revoke access to a shared app →](https://layerv.ai/guides/revoke-access-to-a-shared-app/) [qURL vs zrok →](https://layerv.ai/compare/qurl-vs-zrok/) [qURL API reference →](https://layerv.ai/docs/)

## Publish your app now

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

[Install the CLI →](https://layerv.ai/cli/)



---

*This markdown version is auto-generated from [https://layerv.ai/guides/share-local-app-nested-routes/](https://layerv.ai/guides/share-local-app-nested-routes/) for AI agents. Curated agent resources: [llms.txt](https://layerv.ai/llms.txt). For the full interactive experience, visit the HTML version.*

