headscale: Self-Host the Tailscale Control Server for Your WireGuard Mesh

TL;DR

• headscale is a self-hosted, open-source implementation of the Tailscale control server, the coordination point that ties a WireGuard mesh network together.
• It is an independent open-source BSD-3-Clause project by Juan Font and the headscale community, NOT by Navanem. This page is a community spotlight. Source: github.com/juanfont/headscale.
• It exchanges WireGuard public keys for your nodes, assigns client IP addresses, sets the boundaries between users, enables sharing machines, and exposes advertised routes.
• You run it yourself and connect the official Tailscale clients to it; for setup and client support, the maintainers point you to the headscale documentation.

What is headscale?

headscale is an open-source, self-hosted implementation of the Tailscale control server. Tailscale is a modern VPN built on top of WireGuard that works like an overlay network between your computers using NAT traversal. Everything in Tailscale is open source except the GUI clients for proprietary operating systems (Windows and macOS/iOS) and the control server. That control server is the exchange point of WireGuard public keys for the nodes: it assigns client IP addresses, creates the boundaries between users, enables sharing machines between them, and exposes the advertised routes of your nodes.

headscale reimplements that control server so the coordination of your own WireGuard mesh runs on infrastructure you own. Its stated design goal is to give self-hosters and hobbyists an open-source server for their projects and labs, and the official Tailscale clients are what connect to it.

A note on this page: headscale is an independent open-source project by Juan Font and the headscale community, NOT by Navanem, and it is NOT affiliated with or endorsed by Tailscale Inc. (the project itself states it is not associated with Tailscale Inc.). We are spotlighting it purely as a useful self-hosting tool, and all credit belongs to its authors and contributors. If you find it useful, star and support it on GitHub, where the repo has sponsorship and donation buttons.

How is headscale different from Tailscale's own control server?

In Tailscale's hosted product, the control server is the one proprietary piece that is not open source. headscale is an open-source, self-hosted alternative to it: your nodes coordinate through a server you operate instead of through Tailscale's hosted infrastructure. The maintainers describe it as a complementary open-source clone, not a drop-in replacement for everything Tailscale offers as a company.

Which clients work with headscale?

headscale is the control server, not a VPN client; you use the official Tailscale clients with it. The maintainers keep an up-to-date list in the documentation rather than in the README; see "Client and operating system support" for current details.

How do you deploy headscale?

The maintainers direct you to the documentation at headscale.net for installation and configuration. One README note is worth repeating: they state they do not support nor encourage the use of reverse proxies and containers to run headscale. A NixOS module is available in the `nix/` directory, and development builds from the main branch are published as container images and binaries (see development builds). The README adds that you should select the same GitHub tag as the version you run so the example configuration matches.

What scope does headscale cover (single vs multi-tailnet)?

headscale deliberately keeps a narrow scope. It implements a single tailnet, intended for personal use or a small open-source organisation, while supporting multiple users within that network, including the boundaries between users and the sharing of machines between them. It is aimed at self-hosters and hobbyists, not at replacing a large managed deployment.

Why feature headscale?

Self-hosted networking is a recurring need for the labs and small teams many IT and security practitioners run. headscale matters because it opens up the one closed piece of the Tailscale stack, the control server, so coordinating a WireGuard mesh can live on infrastructure you own. It is open source under BSD-3-Clause, community-maintained, and focused on a clear, narrow use case. We feature it as an independent project worth knowing about, not as anything Navanem built.

FAQ

Is headscale made by Navanem?

No. headscale is an independent open-source project by Juan Font and the headscale community, released under the BSD-3-Clause license. Navanem did not build it and is only spotlighting it. The source lives at github.com/juanfont/headscale.

Is headscale affiliated with Tailscale?

No. headscale is an independent open-source reimplementation of the control server and is not associated with Tailscale Inc., as the project itself states. The official Tailscale clients connect to a headscale server, but it is not a Tailscale product. The project does note that one active maintainer is employed by Tailscale and is allowed to spend work hours contributing, with those contributions reviewed by others.

What language is headscale written in?

headscale is written in Go. Contributing requires recent Go and Buf for Protobuf generation, and the maintainers recommend a Nix development environment via nix develop.

Where do I get it?

The code and releases are on GitHub at github.com/juanfont/headscale. Documentation for stable and development versions is at headscale.net.