Share a Local Web App
Give someone a link to a web app that runs on your laptop: no deploy, no port forwarding, no firewall change. The link works while nfltr http runs and stops the moment you stop it.
Goal
A reviewer opens a public https://….nfltr.xyz/ link and sees the app on your localhost:8080. Then you protect the link with a generated password, and finally revoke it.
Prerequisites
- The
nfltrCLI on your laptop (Getting Started, step 2). - This machine enrolled in your account once:
nfltr config login. - The reviewer needs only a browser (or
curl). They do not need an account or the CLI.
1. Start the app
Use your own app on any port. This tutorial uses a one-file page served by Python on port 8080:
$ echo '<h1>Hello from my laptop</h1>' > index.html
$ python3 -u -m http.server 8080
Serving HTTP on :: port 8080 (http://[::]:8080/) ...
Leave it running and open a second terminal.
2. Share it
$ nfltr http 8080
Agent ID you.apple-local-5bef
Share URL https://k3vq7mzt2xw4hn5rbsd6jyfa2e.nfltr.page/
Access Public
Policy public link
Expires 2026-09-30T07:59:31Z
Encryption /browse/ and share links: the relay can read this
Connected — waiting for requests... (press Ctrl+C to stop)
Send the Share URL to the reviewer. Anyone with the link can open it while the command runs; it expires after 24 hours without a visit (--share-ttl 2h for 2 hours), and each visit starts that time again. The relay ends the share link's TLS, so the relay can read this traffic, as the banner says; for a path it can't read, reach the agent from a machine of your organisation (nfltr cat pipe from an enrolled machine: nfltr org join).
Check it yourself ($URL stands for the Share URL printed above):
$ curl -s "$URL"
<h1>Hello from my laptop</h1>
3. Revoke it: stop the command
Press Ctrl+C in the terminal running nfltr http. The link stops working at once:
$ curl -s -o /dev/null -w '%{http_code}\n' "$URL"
503
Revoking the machine that shares (nfltr machines revoke) ends the link too: a visit still open (a page loading, a WebSocket) ends at once, and the next visit finds the machine offline.
The link is tied to its agent: nfltr http's own, this machine's name followed by -http (work-laptop-http), so a nfltr cat serve or nfltr up (the machine's name) and a nfltr share (-share) run beside it with no flag. If you share again from the same machine under the same name within its lifetime, the same link comes back. To hand out a link the earlier reviewer cannot reuse, start the new share with a different name: nfltr http 8080 --agent review-2.
4. Protect the link with a password
--share-preset review puts HTTP Basic Auth in front of the link and generates the credentials for you:
$ nfltr http 8080 --share-preset review
Share URL https://k3vq7mzt2xw4hn5rbsd6jyfa2e.nfltr.page/
Access Review Share
Policy browser-friendly Basic Auth
Expires 2026-09-30T08:11:06Z
Basic Auth curl -u "review:5e24e5cd2bb6" <url>
Send the reviewer the link and the review:… user and password (a browser prompts for them). Without them the link answers 401; with them it serves the app ($CRED stands for the review:… pair):
$ curl -s -o /dev/null -w '%{http_code}\n' "$URL"
401
$ curl -s -u "$CRED" "$URL"
<h1>Hello from my laptop</h1>
Other ways to restrict a link: --share-auth user:password (your own credentials), --share-bearer TOKEN (for API clients), --share-ip-allowlist 203.0.113.0/24, --share-header X-Api-Key=value. --no-share creates no public link at all.
Only people you choose: sign-in
--share-login puts sign-in in front of the link: only a visitor signed in to nfltr as you (the link's owner), or as an email you list with --share-login-allow, gets through. Anyone else is sent to sign in and then refused, with nothing about your machine in the answer:
nfltr http 8080 --mode inspectable --share-login --share-login-allow ana@example.com,ben@example.com
Sign-in needs --mode inspectable: the relay checks who is visiting, and an end-to-end encrypted link hides every request from the relay (it sees only that someone connects). nfltr refuses --share-login without it rather than pretend. Signing out ends that browser's access at its next request; revoking the link, or issuing it again without an email, ends access within a minute. nfltr share --share-login and the nfltr up service keys share_login: true and share_login_allow: [..] do the same, and the dashboard's Share card (an agent's Manage panel) issues the same link: pick a service, link only, password or sign-in, and an idle expiry.
5. Clean up
Press Ctrl+C in the nfltr http terminal. Even with the password, the link now answers 503:
$ curl -s -u "$CRED" -o /dev/null -w '%{http_code}\n' "$URL"
503
Then stop the web server with Ctrl+C too.
Share several apps from one process
Since v1.0.679, nfltr up runs several tunnels at once: list them in a file instead of starting one nfltr http or nfltr cat serve per app. Each service takes the options of its command, with _ for -, and its name is its agent name:
services:
web: { http: 3000 }
api: { http: 8080, share_auth: "alice:${API_PASS}" }
db: { tcp: 5432 }
$ nfltr up -c nfltr.yaml
nfltr up checks every service before it connects any, prints one table of share URLs and nfltr cat forward commands, and stops them all on Ctrl+C. Write passwords and tokens as ${ENV_VAR}; a password written into the file itself is refused unless only you can read the file (chmod 600). One process serves an agent on a machine (nfltr http and nfltr share default to their own agents, <machine>-http and <machine>-share; nfltr up and nfltr cat serve to the machine's name): a second nfltr up, nfltr http, nfltr share or nfltr cat serve of an agent already served here is refused (exit 14) and names the running one; --replace hands the agent to the new process, and the running one stops (exit 13 once none of its services is left). See nfltr up --help.
To run every service under one agent over one connection, add agent: home to the file. Each http service still gets its own share URL, which reaches that service only; a tcp service is reached with nfltr cat forward home/db --listen 127.0.0.1:5432. The agent connects only to the ports and addresses the file lists.
agent: home
services:
web: { http: 3000 }
api: { http: 8080, share_auth: "alice:${API_PASS}" }
db: { tcp: 5432 }
Under agent: a service takes only the share options (share, no_share, share_auth, share_bearer, share_header, share_ip_allowlist, share_preset, share_ttl, share_login, share_login_allow), for http its own certificate (e2ee_cert, e2ee_key: that service's alone; a share without one keeps its automatic public certificate) and, for tcp, forward, e2ee and allow_group (organisation mode); set mode at the top of the file. A service that needs basic_auth, allow_path, route or passthrough is refused there: leave out agent: to run it as its own agent. The relay must support services (v1.0.679 or newer, on a single relay instance); an older relay is refused with an error, never served another way.
To share a folder of static files instead of an app, give a path instead of a port: nfltr http ./public, or { http: ./public } in the file. The agent serves the folder itself: index.html for a directory, page.html for /page, and every response asks the browser to revalidate, so replacing the folder's files is live at once.
What your app receives
nfltr forwards each request the way a standard reverse proxy does, so frameworks that check where a request came from (CSRF protection in Django, Rails or Express, Go's http.CrossOriginProtection) and apps that build absolute URLs work behind a share link:
Hostis the link's host name (….nfltr.xyz), as the visitor asked for it.Origin,RefererandCookiearrive exactly as the browser sent them.Authorizationarrives as the client sent it, so an API that takes its ownBearertoken works behind a share. nfltr removes only its own credentials: the password of a--share-authlink (and a share's bearer token), which nfltr checks before your app sees the request, and any nfltr credential.X-Forwarded-Hostis the link's host name,X-Forwarded-Protoishttps, andX-Forwarded-ForandX-Real-IPare the visitor's IP address, as the relay accepted the visitor's connection. nfltr sets these itself and drops any copies the visitor sent (andForwarded), so your app can trust them. In--mode verified(end-to-end encrypted) your agent ends the visitor's TLS and sets them; the relay tells it the visitor's address.- Hop-by-hop headers (
Connection,Keep-Alive,Proxy-Authorizationand the headersConnectionnames) are not forwarded.
Tell your framework to trust these headers from the proxy, for example SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https") and the link's host in ALLOWED_HOSTS in Django, or app.set("trust proxy", "loopback") in Express.
Some apps accept only their own host name: development servers that check the host (Vite's allowedHosts, webpack's "Invalid Host header") or a server with name-based virtual hosts. Allow the link's host name there, or send your app its own host instead:
$ nfltr http 5173 --host-header rewrite
X-Forwarded-Host still carries the link's host name. In an nfltr up file the option is host_header: rewrite on a service; it is not available under agent:.
If it goes wrong
| You see | Meaning and fix |
|---|---|
this session was replaced by a newer one with the same agent ID and key | Another nfltr command started with the same name and key and took the name over. One key runs any number of commands, each under its own name: give this one another --agent, or stop the other. |
The link answers 502 with tunnel error: Get "http://localhost:8080": dial tcp [::1]:8080: connect: connection refused | The tunnel is up but nothing listens on that port. Start the app, or pass the port it really uses (nfltr http 3000, or a full URL such as nfltr http https://myapp.local:3000). |
The link answers 503 with agent "…" registered but no pod currently holds its connection | nfltr http is not running (stopped, or reconnecting after a network drop). Start it again; the same link comes back. |
An upload answers 413 with request body too large: the relay accepts at most 1 GiB (http.server.max_request_body_size) | Request bodies are limited to 1 GiB. Split the upload, or move the file between your own machines with nfltr cat cp (Send files and messages). If the message says the agent reads request bodies whole, the agent is an old nfltr: update it. |
Your app answers Blocked request. This host is not allowed, Invalid Host header or DisallowedHost | The app accepts only its own host names, and the request carries the link's. Add the link's host name to the app's allowed hosts, or start the tunnel with --host-header rewrite (see What your app receives). |
The link answers 401 Unauthorized | The share has a password (--share-preset review or --share-auth). Use the credentials nfltr printed. |
health server error: listen tcp :29501: bind: address already in use | Harmless when two tunnels run on one machine: only the local health endpoint of the second one is off. Pass --health-addr :29502 to move it. |
Next
- Share a log file or command output
- HTTP tunnels: routes, recording
- Diagnose connection problems