Skip to Content
TSLinkTSLink Docs

Why expiry is hard with http.server and a tunnel

python3 -m http.server has no notion of time and a tunnel only carries traffic. What an expiring link needs you to write yourself, and what TSLink guest links and other tools already provide.

Last updated on

View as Markdown

python3 -m http.server serves files to anyone who can reach it and knows nothing about time, and a tunnel such as Tailscale Funnel or a Cloudflare Quick Tunnel only carries traffic to it. To make a link expire you end up writing a token check, a stored deadline, a refusal page, per-recipient revocation, a way to cut downloads already in progress and a log, then keeping the server and the tunnel running for the whole period. TSLink guest links put that gate in front of any local HTTP server you already run:

bash
python3 -m http.server 8000 --bind 127.0.0.1 --directory ~/handoff
tslink add handoff --proxy localhost:8000
tslink guest create handoff --for 3d --public --print-link
tslink guest revoke <id>

This needs TSLink v0.4.0 or later; on a new installation the first guest link also takes the app off the home gateway. In v0.3.1 and earlier, run tslink portal route remove <app> before guest create. Install TSLink first if needed (installation).

The full walkthrough is send a Mac download link that expires in 3 days. TSLink is an independent project, not made by Tailscale.

Neither piece has a clock

Python's documentation warns that http.server "is not recommended for production. It only implements basic security checks", and it binds to all interfaces unless you pass --bind. It has no setting for a deadline or a password.

The tunnels do not add one. The tailscale funnel reference lists --bg, --https, --proxy-protocol, --set-path, --tcp, --tls-terminated-tcp and --yes: none sets an expiry or checks the visitor. A Cloudflare Quick Tunnel stops when cloudflared stops, so its lifetime is the lifetime of a process you have to end yourself, and its hostname changes every run. Its --allowed-mail option does check visitors by email in an interactive browser, not for clients such as curl, and access still ends for everyone at once.

What you end up writing

PieceWhere a quick script goes wrongTSLink guest link (v0.4.0)
Unguessable tokenA token in the URL path is written to the log: http.server's default request log prints every request line, path included, to stderr. It can also leak through the Referer header.256-bit token; only a salted SHA-256 hash is stored. Link and PIN values stay out of daemon logs and access events. Referer is stripped and guest responses send Referrer-Policy: no-referrer.
DeadlineA deadline kept in memory or counted from process start resets on restart, and a clock change can move it.An absolute deadline stored with each link and checked on every request. Once expiry is observed it is latched, so rolling the clock back does not reopen the link.
RefusalYou decide what an expired, revoked or mistyped link returns. A 410 Gone page is a common choice.One 401 page for expired, revoked and invalid links, naming no app. The backend is not contacted.
RevocationRevoking means changing the token or stopping the server, and you need a way to do it while the server runs.tslink guest revoke <id> is permanent for that ID and needs no restart. Each recipient can have a separate link, so revoking one leaves the others working. tslink remove revokes all of the app's links.
Downloads in progressA check at the start of the request lets a download that began before the deadline run to the end.Revocation and the deadline cancel tracked requests and close streams, including SSE and WebSocket. A bounded request authorized just before a revocation may still finish.
Who fetched whatYou add your own log and keep the token out of it.tslink access log --app <app> records guest decisions by link ID. History is bounded and can drop events; use counts flush about every 30 seconds.
Brute forceNothing limits guessing unless you add it.Optional 6 to 64 digit PIN, hashed with PBKDF2, five attempts per link and ten per source in 15 minutes.
Staying upThe server and the tunnel both have to run for three days, and you have to stop both at the end.The background service keeps the app's node running and enforces each link's deadline itself; the public listener's own deadline is extended to cover the newest link. Your local server still has to run, and you remove the app when done.

TSLink only replaces the gate. You still run the local HTTP server, guest links work only in front of HTTP proxy apps, the public edge is Funnel with an explicit --public acknowledgement, and the Mac has to stay online.

When a hand-written server or another tool is the better choice

  • You need behavior TSLink does not have: a link that dies after one download, a branded expiry page or a distinct 410 status, or a deadline beyond the 7d default maximum without changing owner configuration. A small server written for exactly that is reasonable; keep the token out of logs and bind it to localhost.
  • You already run nginx. Its secure_link module checks signed links and can limit their lifetime; it is not built by default and needs --with-http_secure_link_module. You still generate the signed URLs and publish the server yourself.
  • You have no Tailscale account and want a link now. A Cloudflare Quick Tunnel with --allowed-mail needs no account on either side, if you can live with access ending when cloudflared stops.
  • You want a permanent public site. A named Cloudflare Tunnel or ordinary hosting fits; expiry is not the problem there.
  • The recipient is already in your tailnet. Tailscale Serve keeps it private with no public edge at all.
  • Your computer cannot stay online. A hosted share link stores the file with the provider, which is the trade you make for availability.

Let your coding agent do it

If your agent reaches for http.server plus a tunnel, paste this into Claude Code, Codex or Cursor:

Code
I need a link that expires. Do not write a token, deadline or expiry server yourself, and do not start a tunnel. Use TSLink guest links:
1. Serve only the files I name from a new folder with a local HTTP server bound to 127.0.0.1, for example: python3 -m http.server 8000 --bind 127.0.0.1 --directory ~/handoff.
2. Check that tslink --version reports v0.4.0 or later. Register it with tslink add handoff --proxy localhost:8000. If the result says needs_login, show me the auth_url and wait. Do not remove the gateway route yourself; the first guest link does that.
3. Before creating anything, ask me whether I want a PIN; it can only be set now. Show me the guest command and wait for my yes. For a PIN, ask me to run the command with --pin myself and type it at the hidden prompt; never put a PIN in a command argument. Otherwise run tslink guest create handoff --for <lifetime> --public --print-link --json with a finite lifetime of at most 7d; never use never.
4. Confirm Funnel is active with tslink status and tslink doctor, then give me the link, the grant id, the expiry and the revoke command: tslink guest revoke <id>.
5. For another recipient or a replacement, run guest create again; each link has its own id. If guest create fails with url_not_ready, run tslink url handoff --wait=30s and try once more; never retry without --print-link.
6. When I say we are done: revoke the link first, then stop the HTTP server and run tslink remove handoff.

Official Tailscale, Cloudflare and Python sources linked above: accessed 2026-11-11. TSLink behavior checked against v0.4.0. TSLink is an independent project by anydoor7, not made or endorsed by Tailscale.

Table of Contents