From c22086f4bc765fdad3470550e88b7a770e6fa80e Mon Sep 17 00:00:00 2001 From: DontBlameMe Date: Fri, 20 Nov 2026 00:32:29 +0100 Subject: [PATCH 1/6] docs: add Tailcat reachability guidance --- docs/peer-host-relay.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/peer-host-relay.md b/docs/peer-host-relay.md index cff4fbf..f2360bf 100644 --- a/docs/peer-host-relay.md +++ b/docs/peer-host-relay.md @@ -34,6 +34,13 @@ exactly as it carries a standalone server's address today. router port forward is then the host's own choice, and the invite exposes that address to anyone who holds the link. +Tailcat is an alternative when the host has no tailnet. Run `tailcat serve ` in front of +a loopback relay and hand out the printed `tc...` address. A guest runs +`tailcat forward 18080:` and joins the room through the local port. Tailcat +carries WireGuard-encrypted traffic over DERP and NAT traversal. The address is a capability, +so keep it with the rest of the invite. Browsers cannot use a `tc...` address as a hostname. + + Every invite leaks the address it carries. Treat the invite as the secret it already is: the room key, the host public key and now the host's reachable address travel together. From 0c1218242abfa6c16fd86aeb409d7eeb26e3a8a4 Mon Sep 17 00:00:00 2001 From: DontBlameMe Date: Fri, 20 Nov 2026 00:39:40 +0100 Subject: [PATCH 2/6] docs: complete the Tailcat guest flow --- docs/peer-host-relay.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/peer-host-relay.md b/docs/peer-host-relay.md index f2360bf..a9093e8 100644 --- a/docs/peer-host-relay.md +++ b/docs/peer-host-relay.md @@ -34,11 +34,13 @@ exactly as it carries a standalone server's address today. router port forward is then the host's own choice, and the invite exposes that address to anyone who holds the link. -Tailcat is an alternative when the host has no tailnet. Run `tailcat serve ` in front of -a loopback relay and hand out the printed `tc...` address. A guest runs -`tailcat forward 18080:` and joins the room through the local port. Tailcat -carries WireGuard-encrypted traffic over DERP and NAT traversal. The address is a capability, -so keep it with the rest of the invite. Browsers cannot use a `tc...` address as a hostname. +Tailcat is an alternative when the host has no tailnet. Put the TLS terminator and rate limit in +front of the relay and run `tailcat serve ` against that protected port. Hand the guest the +printed `tc...` address and the relay port. The guest runs +`tailcat forward 18080:` and replaces only the invite's host and port with +`127.0.0.1:18080`, keeping the `/session` path, query and fragment. Tailcat carries +WireGuard-encrypted traffic over DERP and NAT traversal. The address is a capability, so keep it +with the rest of the invite. Browsers cannot use a `tc...` address as a hostname. Every invite leaks the address it carries. Treat the invite as the secret it already is: From f164933555ffff507b92842797cba4f1ff6417de Mon Sep 17 00:00:00 2001 From: DontBlameMe Date: Fri, 20 Nov 2026 00:43:03 +0100 Subject: [PATCH 3/6] docs: spell out the Tailcat invite rewrite --- docs/peer-host-relay.md | 36 ++++++++++++++++++++++++++++++------ 1 file changed, 30 insertions(+), 6 deletions(-) diff --git a/docs/peer-host-relay.md b/docs/peer-host-relay.md index a9093e8..4eb5483 100644 --- a/docs/peer-host-relay.md +++ b/docs/peer-host-relay.md @@ -35,12 +35,36 @@ exactly as it carries a standalone server's address today. to anyone who holds the link. Tailcat is an alternative when the host has no tailnet. Put the TLS terminator and rate limit in -front of the relay and run `tailcat serve ` against that protected port. Hand the guest the -printed `tc...` address and the relay port. The guest runs -`tailcat forward 18080:` and replaces only the invite's host and port with -`127.0.0.1:18080`, keeping the `/session` path, query and fragment. Tailcat carries -WireGuard-encrypted traffic over DERP and NAT traversal. The address is a capability, so keep it -with the rest of the invite. Browsers cannot use a `tc...` address as a hostname. +front of the relay and run `tailcat serve ` against that protected port. Tailcat prints a +`tc...` address. Send the guest three things: that address, the protected port, and the complete +invite URL the host's client copied. The invite URL looks like this, with real values in place of +the angle brackets: + +``` +ws://:/session?room=&token=#k=&h= +``` + +The part after `#` is the fragment. It holds `k`, the room key, and `h`, the host public key. The +guest must copy it exactly. It never travels in an HTTP request, but the client needs it to read +and verify the room's frames. + +The guest forwards Tailcat to a local port and changes only the invite's host and port. If the +host sent the URL above and the protected port is `8080`: + +```sh +tailcat forward 18080:8080 +``` + +The guest then joins with this URL: + +``` +ws://127.0.0.1:18080/session?room=&token=#k=&h= +``` + +Keep `/session`, the whole `?room=…&token=…` query and the whole `#k=…&h=…` fragment. Change +nothing else. A browser cannot use a `tc...` address as a hostname, so use Tailscale Serve when +the guest is a page. Treat the tailcat address and the invite as one secret. Anyone who holds +both can reach the room. Every invite leaks the address it carries. Treat the invite as the secret it already is: From 2d0ca24daadf96c343952e7dd925733a2e251926 Mon Sep 17 00:00:00 2001 From: DontBlameMe Date: Fri, 20 Nov 2026 00:45:21 +0100 Subject: [PATCH 4/6] docs: correct the Tailcat protected port and path --- docs/peer-host-relay.md | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/docs/peer-host-relay.md b/docs/peer-host-relay.md index 4eb5483..ce83a7e 100644 --- a/docs/peer-host-relay.md +++ b/docs/peer-host-relay.md @@ -34,37 +34,42 @@ exactly as it carries a standalone server's address today. router port forward is then the host's own choice, and the invite exposes that address to anyone who holds the link. -Tailcat is an alternative when the host has no tailnet. Put the TLS terminator and rate limit in -front of the relay and run `tailcat serve ` against that protected port. Tailcat prints a -`tc...` address. Send the guest three things: that address, the protected port, and the complete -invite URL the host's client copied. The invite URL looks like this, with real values in place of -the angle brackets: +Tailcat is an alternative when the host has no tailnet. It carries WireGuard-encrypted traffic +through DERP and NAT traversal. Put rate limiting in front of the relay. If a TLS terminator is +also used, its certificate must name the host that appears in the invite. Run +`tailcat serve ` against the protected endpoint. Tailcat prints a `tc...` address. + +Send the guest three things: the `tc...` address, the protected port, and the complete invite URL +the host's client copied. A wire invite looks like this, with real values in place of the angle +brackets: ``` -ws://:/session?room=&token=#k=&h= +ws://:/session?room=&token=#k=&h= ``` -The part after `#` is the fragment. It holds `k`, the room key, and `h`, the host public key. The -guest must copy it exactly. It never travels in an HTTP request, but the client needs it to read -and verify the room's frames. +The part after `#` is the fragment. It holds `k`, the room key, and `h`, the host public key. Copy +it exactly. It never travels in an HTTP request, but the client needs it to read and verify the +room's frames. -The guest forwards Tailcat to a local port and changes only the invite's host and port. If the -host sent the URL above and the protected port is `8080`: +The guest forwards the protected port to a local port. If the host sent the URL above and the +protected port is `8080`: ```sh tailcat forward 18080:8080 ``` -The guest then joins with this URL: +Then the guest changes only the invite's host and port: ``` ws://127.0.0.1:18080/session?room=&token=#k=&h= ``` -Keep `/session`, the whole `?room=…&token=…` query and the whole `#k=…&h=…` fragment. Change -nothing else. A browser cannot use a `tc...` address as a hostname, so use Tailscale Serve when -the guest is a page. Treat the tailcat address and the invite as one secret. Anyone who holds -both can reach the room. +Keep the invite's path, the whole query and the whole fragment. Change nothing else. A page-link +invite keeps its `/page/` path. For a `wss://` invite, keep the hostname in the certificate and +route it to `127.0.0.1` locally; replacing it with the IP would fail certificate verification. +Browsers cannot use a `tc...` address as a hostname, so use Tailscale Serve when the guest is a +page. Treat the tailcat address and the invite as one secret. Anyone who holds both can reach the +room. Every invite leaks the address it carries. Treat the invite as the secret it already is: From a01317f10abde333d80a60bed1336f9fb8a80d04 Mon Sep 17 00:00:00 2001 From: DontBlameMe Date: Fri, 20 Nov 2026 00:47:34 +0100 Subject: [PATCH 5/6] docs: make Tailcat steps imperative --- docs/peer-host-relay.md | 42 +++++++++++++++++------------------------ 1 file changed, 17 insertions(+), 25 deletions(-) diff --git a/docs/peer-host-relay.md b/docs/peer-host-relay.md index ce83a7e..05cf473 100644 --- a/docs/peer-host-relay.md +++ b/docs/peer-host-relay.md @@ -34,42 +34,34 @@ exactly as it carries a standalone server's address today. router port forward is then the host's own choice, and the invite exposes that address to anyone who holds the link. -Tailcat is an alternative when the host has no tailnet. It carries WireGuard-encrypted traffic -through DERP and NAT traversal. Put rate limiting in front of the relay. If a TLS terminator is -also used, its certificate must name the host that appears in the invite. Run -`tailcat serve ` against the protected endpoint. Tailcat prints a `tc...` address. +## Tailcat without a tailnet -Send the guest three things: the `tc...` address, the protected port, and the complete invite URL -the host's client copied. A wire invite looks like this, with real values in place of the angle -brackets: +Tailcat carries the relay over WireGuard through DERP and NAT traversal. Use a wire invite, the +`ws://…/session?…` form, for these steps. A browser guest needs Tailscale Serve instead. -``` -ws://:/session?room=&token=#k=&h= -``` +Host: -The part after `#` is the fragment. It holds `k`, the room key, and `h`, the host public key. Copy -it exactly. It never travels in an HTTP request, but the client needs it to read and verify the -room's frames. +1. Start the room in the host client. Copy the invite URL. +2. Read the port from the invite. In `ws://host:8080/session?…` it is `8080`. +3. Run `tailcat serve 8080` with that port. +4. Send the guest the printed `tc...` address, the port `8080`, and the full invite URL. -The guest forwards the protected port to a local port. If the host sent the URL above and the -protected port is `8080`: +The invite ends with a fragment such as `#k=&h=`. It is part of the URL. The +guest must copy it unchanged. -```sh -tailcat forward 18080:8080 -``` +Guest: -Then the guest changes only the invite's host and port: +1. Run `tailcat forward 18080:8080`. +2. Insert `127.0.0.1:18080` in place of the invite's `host:port`. Keep `/session`, the `?room=…&token=…` + query and the `#k=…&h=…` fragment. +3. Open the new URL in the client: ``` ws://127.0.0.1:18080/session?room=&token=#k=&h= ``` -Keep the invite's path, the whole query and the whole fragment. Change nothing else. A page-link -invite keeps its `/page/` path. For a `wss://` invite, keep the hostname in the certificate and -route it to `127.0.0.1` locally; replacing it with the IP would fail certificate verification. -Browsers cannot use a `tc...` address as a hostname, so use Tailscale Serve when the guest is a -page. Treat the tailcat address and the invite as one secret. Anyone who holds both can reach the -room. +Treat the `tc...` address and the invite as one secret. Rate-limit the relay. Restrict inbound +access to the host with a firewall. Every invite leaks the address it carries. Treat the invite as the secret it already is: From 80c029fd3823688fda234e4912e6337dd1af8a74 Mon Sep 17 00:00:00 2001 From: DontBlameMe Date: Fri, 20 Nov 2026 00:50:35 +0100 Subject: [PATCH 6/6] docs: let page guests use the Tailcat forward --- docs/peer-host-relay.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/peer-host-relay.md b/docs/peer-host-relay.md index 05cf473..be8315a 100644 --- a/docs/peer-host-relay.md +++ b/docs/peer-host-relay.md @@ -36,8 +36,9 @@ exactly as it carries a standalone server's address today. ## Tailcat without a tailnet -Tailcat carries the relay over WireGuard through DERP and NAT traversal. Use a wire invite, the -`ws://…/session?…` form, for these steps. A browser guest needs Tailscale Serve instead. +Tailcat carries the relay over WireGuard through DERP and NAT traversal. An editor or agent guest +uses the wire invite, the `ws://…/session?…` form. A page guest uses the same forward and keeps the +invite's `/page/` path. Host: