Explainer

Tunnelcat: How a Peer-to-Peer Tunnel Works Without a Control Plane

A practical map of Tunnelcat and its Tailcat foundation: out-of-band connection tokens, WireGuard, NAT traversal, DERP relays, and the limits of a first release.

On this page

Two machines can share an encrypted stream without signing in to a VPN service. The interesting question is what still has to happen between “here is a token” and a working connection.

Tunnelcat is a small project built on the networking components used by Tailscale’s Tailcat. Its first public release describes a one-to-one tunnel: one side starts a listener, shares a connection token, and the other side dials it. There is no Tailscale account or central account-management service in that basic workflow.

No control plane does not mean no outside infrastructure. The connection can start through a DERP relay and, when NAT traversal succeeds, move to a direct UDP path. If direct connectivity fails, a relay can remain in the data path. This distinction is the useful part of the design.

A tunnel is several problems stacked together

“Connect A to B” hides at least four separate jobs:

JobQuestionMechanism in this family of tools
Introduce peersWhich key and rendezvous information belongs to the other side?Exchange a connection token out of band
Protect trafficWho is the peer, and can an intermediary read the packets?WireGuard’s authenticated encrypted tunnel
Find a pathCan both machines exchange packets through their networks?Endpoint discovery and UDP hole punching, with relay fallback
Carry an application streamHow does an application use the tunnel?A userspace networking stack and a TCP connection

These are related but not interchangeable. Encryption does not discover a route through a firewall. A relay can carry packets without becoming an account system. A token can identify a cryptographic endpoint without proving that the person who sent it is the person you intended to contact.

The connection token replaces a lookup, not trust

In the upstream Tailcat design, the connection token encodes the server’s WireGuard public key and relay information. It can be passed over an existing channel rather than looked up through Tailscale’s control plane. The server keeps its private key; a public key is not the private key.

That out-of-band exchange becomes a trust decision. If a token is substituted before it reaches the client, the client may connect to the wrong endpoint. Verify the token or public key through a trusted channel, and do not publish tokens for a live service casually. Depending on the configuration, knowledge of a token may be enough to reach a listener; authorization still needs to be designed explicitly.

The current project README documents saved identities and an --allow option for restricting clients. Those details are version-specific. Consult the README for the version in use rather than assuming every example applies to the first release.

Why the relay comes before the direct path

Each peer may be behind a router that translates private addresses and blocks unsolicited inbound packets. A machine can learn how its outbound UDP traffic appears from the outside using STUN, but that mapping is not guaranteed to work for every destination. Both sides also need a way to exchange endpoint candidates.

Tailcat uses DERP as a rendezvous and fallback path. Once peers know about one another, Tailscale’s transport attempts direct UDP connectivity. If hole punching succeeds, traffic can take the direct path; otherwise, an available relay can keep the connection working. A restrictive firewall, an unavailable relay, or a network that blocks the relevant traffic can still prevent a connection.

Start:   client  ── encrypted packets ── relay ── encrypted packets ── server
Possible upgrade: client  ─────────────── direct UDP ──────────────── server

The diagram shows alternatives, not two independent sessions. DERP forwards encrypted traffic; it is not a promise that every network will connect, or that relayed throughput equals a direct connection.

Where WireGuard and TCP fit

WireGuard handles peer authentication and encrypted packet transport. Tailcat reuses Tailscale’s userspace networking components, including its transport and a userspace TCP/IP stack. An application can therefore interact with a TCP stream while the underlying encrypted packets travel over either the relay or a direct UDP path.

This is also why a one-to-one application tunnel should not be described as a complete machine-wide VPN. The upstream Tailcat README describes a userspace tool that does not install system routes or DNS settings. A stream reaching one chosen service is not, by itself, a managed network joining every device and application.

What the first release actually claimed

The Tunnelcat v0.1.0 release, published on 30 August 2026, describes an initial one-to-one case: tunnelcat up starts the server, and tunnelcat dial uses the shared token. Its release notes report a WireGuard handshake, NAT traversal and an echo round-trip in its end-to-end test.

That is a useful milestone, not evidence that all network combinations work or that a full multi-device mesh was already complete. The release notes explicitly list the mesh and coordination features as future work. The reported test time and test count belong to that release’s own record; they are not a new benchmark or an independent reproduction for this article.

A practical checklist

  1. Agree on the version. Read the matching release notes and verify downloaded artifacts before running them.
  2. Exchange the connection token safely. Check the peer’s identity out of band; protect any private key on disk.
  3. Limit what is exposed. Use peer restrictions where available and expose only the service that needs access.
  4. Check the path. A working stream may be relayed rather than direct. Test both conditions before making latency or bandwidth claims.
  5. Keep the scope honest. A successful echo test shows a particular connection worked; it does not establish an audited security posture or a production-ready mesh.

The central lesson is architectural: removing a centralized control plane simplifies one part of the problem, but it moves peer introduction and trust to the participants. Cryptography, traversal and application-level access still need explicit answers.

Sources