How Tailcat Replaces the Tailscale Coordination Server: A Control-Plane-Free Architecture

Tailcat replaces the Tailscale coordination server by encoding all necessary peer metadata into a URL-safe ConnBlob token and bootstrapping connections through DERP relays, eliminating the need for centralized control-plane services while maintaining full WireGuard functionality.

Tailcat is an experimental package within the Tailscale ecosystem (tailscale/tailcat) that demonstrates how to establish secure WireGuard tunnels without requiring a Tailscale account, API keys, or the traditional coordination server. By repurposing existing Tailscale components like DERP relays and magicsock, Tailcat implements a zero-configuration bootstrap mechanism that distributes node maps and endpoint information peer-to-peer. This article examines the source code to explain exactly how Tailcat replaces the Tailscale coordination server with a lightweight, local control plane.

Eliminating the Control Plane with Data-Plane-Only Architecture

The fundamental shift in Tailcat is its complete removal of control-plane dependencies. According to the package documentation in tailcat.go (lines 4-7), Tailcat runs a WireGuard tunnel "with no Tailscale account or coordination server required".

Instead of relying on Tailscale's hosted control plane to distribute node maps and public keys, Tailcat operates entirely on the data plane. The locoBackend struct—defined in tailcat.go (lines 42-69)—acts as a miniature local backend that manages the WireGuard engine, DERP map, and networking subsystems without external coordination services.

Bootstrapping via DERP Relays and ConnBlob Tokens

Fetching the DERP Map

Since Tailcat cannot rely on the control plane to provide relay information, it fetches DERP maps directly from public URLs. The FetchDERPMap function and its internal implementation fetchDERPMap in tailcat.go (lines 98-101 and 382-406) retrieve a JSON list of available relay regions from DefaultDERPMapURL or a custom endpoint. This allows nodes to discover relay infrastructure without coordination server authentication.

The ConnBlob Token Structure

The ConnBlob is the critical innovation that replaces centralized peer distribution. Defined in tailcat.go (lines 36-40 and 44-53), this compact URL-safe token encodes:

• The server's WireGuard public key
• A separate "disco" public key for endpoint discovery
• The selected DERP region for initial relay communication

Servers generate this blob via Server.ConnBlob(), which clients parse using ParseConnBlob (lines 332-340) to obtain all metadata necessary for establishing a connection—no additional network fetches required.

Server Implementation: Starting Without a Coordination Server

Ephemeral Identity and locoBackend Initialization

When Server.Start is called (lines 90-108), Tailcat creates an ephemeral node identity and initializes the internal locoBackend. This backend holds references to the WireGuard engine, the fetched DERP map, and the node's cryptographic keys. Unlike standard Tailscale clients that register with a control server, the server immediately begins listening on the selected DERP region without authentication handshakes (lines 120-132).

Advertising Endpoints Over DERP

In place of the control plane's peer map distribution, Tailcat uses the advertiseEndpoints function (lines 190-199 and 295-306) to broadcast UDP endpoint information through the DERP relay. This function mimics the standard Tailscale magicsock "call-me-maybe" messages but operates locally, pushing endpoint updates directly to connected peers rather than through a centralized service.

Client Connection: Parsing ConnBlob and Peer Registration

Decoding Peer Metadata

The client initiates connections by parsing the server's ConnBlob via ParseConnBlob (lines 332-340). This extracts the server's public keys and DERP region, allowing the client to create its own locoBackend and WireGuard engine using createEngine and newNetstack (lines 514-534 and 540-562).

The Meow Handshake

Rather than using the control plane to exchange peer information, Tailcat implements a "meow" handshake protocol. The onMeow and onDERPRecv functions (lines 447-452 and 469-481) handle incoming handshake messages over the DERP relay, registering each party as WireGuard peers. This handshake substitutes the traditional control-plane peer exchange by directly configuring the WireGuard interface with the remote node's public key and endpoints.

Direct Path Upgrade and Magicsock Integration

Once the initial DERP bootstrap completes and both sides have exchanged endpoint information through advertiseEndpoints, the magicsock layer (part of the wgengine package) attempts to establish direct UDP paths between peers. This behavior mirrors standard Tailscale operation but occurs without coordination server involvement. Because the ConnBlob bootstrap embeds all necessary endpoint discovery keys, the magicsock layer can perform NAT traversal and upgrade to direct connections autonomously.

Implementation Example

The following example demonstrates starting a Tailcat server and connecting a client without any coordination server:

// Start a Tailcat server (listens on DERP relay, no coordination server)
srv := &tailcat.Server{
    // Optional: specify a DERP region; if nil the nearest region is auto-selected
    Region: nil,
}
if err := srv.Start(); err != nil {
    log.Fatalf("server start: %v", err)
}
fmt.Printf("Server ConnBlob (share with client): %s\n", srv.ConnBlob())

// Connect a client to the server using the ConnBlob obtained above
client := tailcat.NewClient(srv.ConnBlob())
if err := client.Dial(context.Background()); err != nil {
    log.Fatalf("dial: %v", err)
}
// Example: open a TCP connection through the tunnel
conn, err := client.DialTCPPort(context.Background(), 22) // SSH port
if err != nil {
    log.Fatalf("ssh: %v", err)
}
defer conn.Close()

// Server-side handling of incoming TCP connections
srv.OnTCP = func(port uint16) func(net.Conn) {
    if port == 22 {
        return func(c net.Conn) {
            // Run an SSH server on the tunneled connection
            handleSSH(c)
        }
    }
    return nil // other ports will be RST'd
}

Summary

• Tailcat eliminates the coordination server by operating a data-plane-only architecture where locoBackend manages local WireGuard state.
• ConnBlob tokens encode all peer metadata, including WireGuard public keys, disco keys, and DERP regions, removing the need for centralized node maps.
• DERP relays bootstrap connections via the FetchDERPMap and advertiseEndpoints functions, handling initial discovery without control-plane authentication.
• The "meow" handshake (onMeow and onDERPRecv) registers peers directly over DERP, substituting the standard control-plane peer exchange mechanism.
• Magicsock upgrades to direct paths once endpoints are known, maintaining full Tailscale data-plane performance characteristics without external coordination.

Frequently Asked Questions

What is a ConnBlob in Tailcat?

A ConnBlob is a URL-safe token generated by the server that encodes the WireGuard public key, discovery public key, and selected DERP region. Defined in tailcat.go (lines 36-53), this compact string allows clients to parse all necessary connection metadata via ParseConnBlob without contacting a coordination server, effectively replacing the traditional node map distribution.

How does Tailcat handle peer discovery without a coordination server?

Tailcat replaces the coordination server's peer discovery with a combination of DERP relay bootstrap and local endpoint advertisement. The advertiseEndpoints function in tailcat.go (lines 190-199) broadcasts UDP endpoint information over DERP, while the onMeow handshake (lines 447-452) registers peers directly, allowing both sides to discover each other's network locations without centralized tracking.

Can Tailcat establish direct connections without going through DERP?

Yes. After the initial bootstrap through DERP relays, Tailcat uses the standard Tailscale magicsock layer to attempt direct UDP path establishment. Once endpoints are exchanged via advertiseEndpoints, the magicsock implementation performs NAT traversal and upgrades connections to direct paths, maintaining the same performance characteristics as traditional Tailscale but without coordination server involvement.

What components replace the control plane's key distribution?

The locoBackend struct (lines 42-69) acts as a local miniature control plane, managing the WireGuard engine and peer configuration. Key distribution is handled through the out-of-band exchange of ConnBlob tokens, which contain the server's public keys, while the DERP relay infrastructure handles the initial rendezvous that the coordination server would normally provide.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}