# Share a frontend and its local API with one link

> A shared React or Next.js app that calls localhost:8000 breaks for the viewer. Proxy the API (FastAPI, Express, Django) in the dev server; share one qURL link.

Source: https://layerv.ai/guides/share-a-frontend-and-its-local-api/

---

[← All guides](https://layerv.ai/guides/) 

# Share a frontend and its local API with one link

## Why qURL here

Share the frontend and its local API through one qURL™ resource. A same-origin /api proxy keeps browser requests and cookies on the address the recipient opened.

Copies a prompt for any agent that runs commands. 

## What you need

- A frontend dev server (Vite or Next.js here) and an API on another port, both on this machine
- Access to the frontend’s code and dev-server config

Content updated November 4, 2026.

## Steps

In someone else’s browser, http://localhost:8000 means their computer, so a frontend that calls your API there fails. Call the API with a relative path such as /api, proxy that path to the API in your dev server (Vite’s server.proxy or Next.js rewrites), and publish only the frontend’s port with qURL. The API stays on 127.0.0.1, and the browser sees one origin.

1. ### Find the absolute API addresses in the frontend  
Look for the API’s address in the frontend’s code and env files, often as a base URL such as VITE\_API\_URL or NEXT\_PUBLIC\_API\_URL. Change each one to a path on the frontend’s own origin, such as /api. The request then goes to whatever address the page was opened from: localhost on your machine, the qURL address in theirs.  
```  
grep -rnE "(localhost|127\.0\.0\.1):[0-9]+" src .env*
```
2. ### Vite: proxy /api to the API  
server.proxy forwards every request whose path starts with /api to the API, keeping the path, so /api/users reaches http://127.0.0.1:8000/api/users. Add rewrite: (path) => path.replace(/^\\/api/, '') if the API serves at its root. changeOrigin: true sends the API Host: 127.0.0.1:8000 instead of the qurl.site host, which an API with a host check rejects. Add ws: true to an entry that carries WebSockets. The proxy runs in vite dev only, not vite preview.  
```  
// vite.config.js (merge into your existing config)
export default {
  server: {
    allowedHosts: ['.qurl.site'],
    proxy: {
      '/api': { target: 'http://127.0.0.1:8000', changeOrigin: true },
    },
  },
}
```
3. ### Next.js: rewrite /api to the API instead  
For Next.js, a rewrite to another URL proxies the request and keeps the address in the browser. Next.js sets the Host header to the API’s address and passes WebSockets through. Put the rewrite in fallback: a plain array runs before dynamic routes, so it would take requests from a handler such as app/api/\[id\]/route.ts, while fallback runs only after every page and route handler of your own. next dev through qURL also needs the recipient’s exact browser hostname in allowedDevOrigins; the Next.js fix guide shows how.  
```  
// next.config.js (merge into your existing config)
module.exports = {
  async rewrites() {
    return {
      fallback: [{ source: '/api/:path*', destination: 'http://127.0.0.1:8000/api/:path*' }],
    }
  },
}
```
4. ### 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
```
5. ### Publish only the frontend  
Restart the dev server so it loads the proxy, then publish its port: 5173 for Vite, 3000 for next dev. Don’t publish the API: the dev server reaches it on 127.0.0.1, and it stays off the network. The Access line says private.  
```  
qurl publish http://127.0.0.1:5173
```
6. ### Create a link for each person  
`qurl share` prints an access link (https://qurl.link/#…). On a terminal, the lines below it say who published the resource and when the link expires, for example “Expires in 1d (single use)”. A publisher LayerV has verified is shown as verified by LayerV; any other name is marked UNVERIFIED. With no flags the link can be opened once and expires within 24 hours. If the expiry line does not say “single use”, don’t send the link. Add --ttl 1h for a shorter window.  
```  
qurl share <CRID>
```
7. ### Send the link to one person  
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. Run `qurl share` again whenever you need a fresh link.

## What the recipient sees

They open the link and use the whole app: pages come from the frontend, and every /api call goes through the same qurl.site address to your API.

Nothing in their browser points at localhost.

## The setting that puts a frontend and its API on one origin

Each row sends /api to the API on 127.0.0.1:8000 so the browser sees one address. Checked against each project’s docs on 2026-11-04.

__The setting that puts a frontend and its API on one origin__
| Tool                      | Setting                          | Example                                                                                    | Note                                                                                |
| ------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| Vite                      | server.proxy                     | '/api': { target: 'http://127.0.0.1:8000', changeOrigin: true }                            | vite dev only, not vite preview; add ws: true for WebSockets                        |
| Next.js                   | rewrites() with fallback         | fallback: \[{ source: '/api/:path\*', destination: 'http://127.0.0.1:8000/api/:path\*' }\] | fallback runs after your own pages and route handlers, dynamic ones included        |
| create-react-app          | "proxy" in package.json          | "proxy": "http://127.0.0.1:8000"                                                           | npm start only; proxies requests that don’t ask for text/html                       |
| Caddy                     | handle\_path with reverse\_proxy | handle\_path /api/\* { reverse\_proxy 127.0.0.1:8000 }                                     | strips /api before forwarding; publish Caddy’s port instead of the frontend’s       |
| Cloudflare Tunnel (named) | ingress rule with path           | path: ^/api, service: http://localhost:8000                                                | locally managed config.yml; needs a catch-all rule last, and an account and domain  |
| ngrok                     | Traffic Policy forward-internal  | req.url.path.startsWith('/api') → an internal endpoint                                     | needs an ngrok account; the public endpoint stays open unless a policy adds a login |

Sources: [Vite: server.proxy](https://vite.dev/config/server-options#server-proxy) , [Next.js: rewrites](https://nextjs.org/docs/app/api-reference/config/next-config-js/rewrites) , [create-react-app: proxying API requests](https://create-react-app.dev/docs/proxying-api-requests-in-development/) , [Caddy: handle\_path](https://caddyserver.com/docs/caddyfile/directives/handle%5Fpath) , [Cloudflare Tunnel: configuration file](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/local-management/configuration-file/) , [ngrok: route requests by path](https://ngrok.com/docs/traffic-policy/examples/route-requests/).

## Troubleshooting

__Troubleshooting__
| If you see                                                                                               | Do this                                                                                                                                                                 |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The page loads, but data never appears, and the browser console shows a failed request to localhost:8000 | Some code still calls the API by its absolute address. Search again, including env files and the API client’s base URL, and change it to /api.                          |
| API calls answer 404 through the proxy                                                                   | The API serves at its root, not under /api. In Vite, add rewrite: (path) => path.replace(/^\\/api/, '') to the proxy entry; in Next.js, drop /api from the destination. |

__More troubleshooting__
| If you see                                                                                                             | Do this                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sign-in works locally, but through the link the session is lost                                                        | The API sets its cookie with Domain=localhost, which a browser on a qurl.site address refuses. Leave the Domain attribute off in development, so the cookie belongs to whichever address the page was opened from.                                                                                                                                                                                                                    |
| A POST answers 403 with an origin or CSRF error                                                                        | The browser sends the qurl.site address it opened as the Origin header, for example the exact https origin from the recipient’s address bar, while the API receives a different Host. A framework that checks Origin, such as Django, needs that exact origin trusted in development; the Django fix guide shows the setting. Do not trust all qurl.site origins: that also trusts other publishers’ pages.                           |
| Chrome asks the viewer to allow access to devices on their local network, or the API call is blocked                   | The page still calls localhost. Chrome’s Local Network Access, whose prompt launched in Chrome 142, makes a site ask permission before it sends requests to the viewer’s local network or their own machine. Granting it would only reach their computer, not your API: change the call to /api.                                                                                                                                      |
| 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. |
| 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

Why not publish the API as well? 

Each published port is a resource of its own, with its own links and browser address. The frontend would then call a second origin: the API needs CORS for that exact address, and each viewer needs two links. A proxy keeps it to one origin and one link.

Do I still need CORS settings on the API? 

Not for the proxied calls. The browser sees the page and /api on the same origin, so it makes no cross-origin request. Keep your CORS settings for anything else that calls the API directly.

Does this work for WebSockets and streamed replies? 

Yes. qURL carries WebSockets and Server-Sent Events. In Vite, add ws: true to the proxy entry for the WebSocket path; Next.js rewrites pass WebSockets through.

Does this work with create-react-app, Express, FastAPI or Django? 

Yes. The API can be any server on 127.0.0.1; only the frontend’s dev server changes. create-react-app has a "proxy" field in package.json that forwards requests that don’t ask for HTML. Django and other frameworks that check Origin on form posts need the viewer’s exact browser origin trusted in development.

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.

How do I stop sharing? 

Run qurl stop <CRID> to pause serving the app, and qurl start <CRID> to resume it; a stopped app still counts toward your resource limit. qurl delete <CRID> removes the resource for good after asking you to confirm; its CRID can never be shared again.

## Related Resources

[Guide: Allow a tunnel’s hostname in your dev server →](https://layerv.ai/guides/allow-tunnel-hostname-in-dev-server/) [Guide: Fix Next.js blocked cross-origin dev requests →](https://layerv.ai/guides/fix-nextjs-blocked-cross-origin-dev-request/) [Guide: Fix Django “Invalid HTTP\_HOST header” →](https://layerv.ai/guides/fix-django-disallowedhost-invalid-http-host/) [Guide: Share a streaming AI chatbot →](https://layerv.ai/guides/share-streaming-ai-demo/) [Guide: Share a dev server with a client →](https://layerv.ai/guides/share-dev-server-with-client/) [qURL vs ngrok →](https://layerv.ai/compare/qurl-vs-ngrok/) [qURL vs Cloudflare Tunnel →](https://layerv.ai/compare/qurl-vs-cloudflare-tunnel/) [Vite docs: server.proxy ↗](https://vite.dev/config/server-options#server-proxy) [Next.js docs: rewrites ↗](https://nextjs.org/docs/app/api-reference/config/next-config-js/rewrites)

## 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-a-frontend-and-its-local-api/](https://layerv.ai/guides/share-a-frontend-and-its-local-api/) for AI agents. Curated agent resources: [llms.txt](https://layerv.ai/llms.txt). For the full interactive experience, visit the HTML version.*

