Headscale — Overview#

Identity#

Purpose#

Headscale is an open-source, self-hosted reimplementation of the Tailscale control server — the closed-source coordination plane that manages WireGuard-based mesh VPN networks (tailnets). It solves the problem of vendor lock-in for users who want the Tailscale client ecosystem (NAT traversal, MagicDNS, subnet routing, DERP relays) without relying on Tailscale’s hosted infrastructure. Its target audience is self-hosters, hobbyists, and small organisations running a single private tailnet.

Significance#

Headscale is one of the most prominent examples in the Go ecosystem of a clean-room reimplementation of a proprietary protocol. With over 26,000 GitHub stars (as of early 2026), active FOSDEM presentations, and one maintainer employed by Tailscale itself, it has evolved from a side project into a community-endorsed complement to the official service. Its existence has influenced Tailscale to open up more documentation and even encouraged cross-collaboration. It demonstrates how the Go ecosystem enables production-quality protocol reimplementations by directly consuming the official client library (tailscale.com v1.94.1) while implementing the undocumented server side.

Key metrics#

  • Go files: 237
  • Top-level directories: cmd, docs, gen, hscontrol, integration, nix, packaging, proto, tools
  • Direct dependencies: 54 (from go.mod)
  • First commit / age: Copyright 2020 (Juan Font); ~6 years old as of analysis date

Notable characteristics#

  • Protocol reverse-engineering at scale: Headscale implements Tailscale’s undocumented coordination protocol (MapRequest/MapResponse, Noise handshake, capability negotiation) by reading the OSS Tailscale client source and maintaining version compatibility through a capver/ capability version subsystem.
  • Dual-database design with careful migration governance: Ships with both SQLite (via modernc pure-Go driver) and PostgreSQL support through GORM, with an immutable ordered migration list and explicit rules about never reordering or disabling foreign keys — a pragmatic pattern for supporting both embedded and production deployments from a single codebase.
  • Performance-critical in-memory NodeStore: A copy-on-write, thread-safe node cache (hscontrol/state/node_store.go) sits between the database and the hot path (MapRequest processing every 15–60 seconds per client), with deadlock detection via go-deadlock — a notable architectural investment for a project of this size.
  • Protocol Buffer management API with gRPC-Gateway: The admin API is defined in .proto files, code-generated into gen/, and served simultaneously as gRPC and REST via grpc-gateway — a clean dual-protocol pattern that keeps the single source of truth in Protobuf.
  • Docker-based integration testing with custom test runner: The cmd/hi binary is a full Docker orchestration harness that spins up real Tailscale client containers to validate end-to-end behavior, with per-run isolation, artifact collection, and EventuallyWithT patterns for handling distributed eventual consistency — an unusually rigorous test culture for an open-source side project.
Backward frp — Testing Headscale — Structure Forward