Self-hosted service
juanfont/headscale avatar
juanfont/headscale

Headscale: A Self-Hosted Tailscale Control Server for Single-Tailnet Deployments

An open source, self-hosted implementation of the Tailscale control server

45,734 stars2,643 forksGoBSD-3-Clause

At a glance

What is it?
Headscale is an open source, BSD-licensed implementation of the Tailscale control server. It targets self-hosters and hobbyists who need a single tailnet without relying on Tailscale's hosted coordination service.
Who is it for?
Adopt Headscale if you are a self-hoster or small organization that wants full control over a single Tailscale network and accepts the maintenance burden of running your own coordination server. Do not adopt it if you need multi-tailnet support, commercial-grade support, or prefer not to manage a server with TLS and database upkeep.
Can I use it commercially?
Yes. BSD-3-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Go, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • juanfont/headscale45,734 ★ · +2,755
Star history
Repository2026-08-182026-11-15
juanfont/headscale43k45.7k

2,755 Stars in the last 89 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What Headscale Actually Replaces

Tailscale is a modern VPN built on WireGuard. Most of the client software is open source, but the GUI clients for Windows and macOS/iOS and the control server are not. That control server is the coordination point: it exchanges WireGuard public keys between nodes, assigns IP addresses, defines user boundaries, enables machine sharing, and exposes advertised routes. Headscale is a self-hosted reimplementation of that control server. It does not replace the Tailscale client on your devices. It replaces the hosted service that those clients talk to. The project's stated design goal is narrow: it implements a single Tailscale network, a tailnet, suitable for personal use or a small open-source organization. If you need multiple isolated tailnets, Headscale is not built for that. The README is explicit about this scope, and that honesty is refreshing in a space where projects often promise everything.

The Architecture: A Key Exchange Point, Not a Data Plane

Headscale sits in the control plane, not the data plane. It handles the exchange of WireGuard public keys and the assignment of IP addresses. Once nodes have the keys and addresses, they communicate directly over WireGuard, using NAT traversal where needed. This is the same architecture as Tailscale's own control server. Headscale does not relay your traffic, and it does not see your encrypted packets. That means the security and performance of your VPN depend on WireGuard and NAT traversal, not on Headscale's throughput. The control server is still a single point of failure for coordination: if it is down, new nodes cannot join and key rotations may fail. Existing tunnels, however, will keep working because they are peer-to-peer. This distinction matters when you plan your deployment. The README does not describe a fallback or clustering option, so you should assume a single-server setup.

Getting It Running: Commands and Config Keys

The README points to the documentation for installation, but it gives clear guidance on one critical practice: always select the same GitHub tag as the released version you use. The main branch may contain unreleased changes, and the example configuration is version-specific. This is a real operational constraint. The documentation is split into stable and development versions, at headscale.net/stable and headscale.net/development. For NixOS users, a module is available in the nix/ directory. For everyone else, the README does not list the exact install commands; it defers to the documentation. What it does show is the development workflow: nix develop sets up a reproducible shell with Go, Buf, and Protobuf tools. Then make generate, make test, and make build handle code generation, testing, and compilation. The Makefile will warn you if required tools are missing and suggest nix develop. If you prefer manual dependency management, you can run make directly. The README also contains a notable warning: the project does not support nor encourage the use of reverse proxies and containers to run Headscale. That is a strong statement. The warning is worth heeding if you are tempted to put it behind nginx or a Docker Compose file.

Client Support: The Real Constraint

Headscale is a control server, so its value depends on which clients can talk to it. The README does not list the supported clients; it links to a documentation page titled 'Client and operating system support.' That omission is significant. Tailscale's own clients are open source except for the GUI clients on Windows, macOS, and iOS. Headscale must work with those clients, but the exact compatibility matrix is not in the README. You need to check the documentation before committing. The project has been under active development for years, and the maintainers have given talks at FOSDEM about using integration testing to reimplement Tailscale. That suggests a serious effort to keep client compatibility working. But the absence of a quick list in the README is a warning sign: you cannot assume every Tailscale client will work out of the box. Verify your specific OS version and client version against the documentation.

A Genuine Limitation: Single Tailnet and No Commercial Support

The most obvious limitation is the single-tailnet scope. Headscale implements one Tailscale network. If you are an organization with multiple teams, each needing its own isolated tailnet, you would need to run multiple Headscale instances. The README is upfront about this: it aims to serve self-hosters and hobbyists, not large enterprises. Another limitation is the lack of commercial support. There is a Discord server for community help, and the maintainers include someone employed by Tailscale who contributes during work hours. The project is BSD-3-Clause licensed, so you can use it freely, but you are responsible for your own deployment. The README also warns against reverse proxies and containers, which means you are expected to run it as a bare binary or via the NixOS module. That reduces deployment flexibility and increases the barrier for users who are comfortable with Docker but not with systemd services.

Alternatives: The Hosted Tailscale vs. Other Self-Hosted Control Servers

The most direct alternative is the hosted Tailscale service itself. It is free for personal use and handles all the coordination, key management, and NAT traversal for you. You get multi-tailnet support, official clients, and no server to maintain. The trade-off is that you do not control the control server. Your tailnet's coordination data lives on Tailscale's infrastructure. Headscale gives you that control but at the cost of running and maintaining a server. There are other self-hosted control server projects, such as Netbird or Innernet, but the README does not mention them. Netbird is a full mesh VPN with its own coordination server and client, while Innernet is a simpler wireguard-based tool that uses a different approach to key distribution. The key difference is that Headscale is designed to work with the existing Tailscale client ecosystem, so you do not need to install a different client on every device. That is a significant advantage if you already use Tailscale clients. But it also means you are dependent on Tailscale's client behavior, which is outside your control.

Maintenance and Upgrade Costs

Headscale is actively maintained, with recent releases v0.29.5 (13 October 2026), v0.29.6 (24 October) and v0.29.7 (30 October). The README does not describe a migration path between versions, but the instruction to match your config to your release tag implies that configs can change between versions. You should expect to read the changelog for each release and update your configuration accordingly. The project uses Go and Protobuf, and the development workflow requires code generation from proto files if you change them. For users, that means the binary is a single Go executable, which is easy to deploy. The NixOS module is a plus for Nix users, but it ties you to NixOS. The BSD-3-Clause license is permissive, so you can modify and redistribute the code with attribution. There are no obvious license traps. The maintenance cost is mostly operational: you need to run a server, keep it updated, and monitor its health. The README does not describe a built-in backup or migration tool, so you should plan your own backup strategy for the database and configuration.

Editorial conclusion

Adopt Headscale if you are a self-hoster or small organization that wants full control over a single Tailscale network and accepts the maintenance burden of running your own coordination server. Do not adopt it if you need multi-tailnet support, commercial-grade support, or prefer not to manage a server with TLS and database upkeep. Before deploying, verify that your client OS is supported in the official documentation, and always use the example config matching your exact release tag, not the main branch. Headscale is a focused tool: it deliberately implements one tailnet, and that boundary is both its strength and its limitation.

Frequently asked questions

What is a headscale?

It is a self-hosted, open source implementation of the Tailscale control server, written in Go and released under BSD-3-Clause. The control server is the component that exchanges Wireguard public keys, assigns client IP addresses, draws the boundaries between users, allows machines to be shared and exposes advertised routes, and headscale implements a single tailnet for personal or small-organisation use.

What is the difference between Tailscale and headscale?

Tailscale operates the control server as a hosted service, while headscale is your own. The README notes that everything in Tailscale is open source except the GUI clients for Windows and macOS/iOS and the control server, which is the part headscale replaces. The client side is unchanged: you still run Tailscale clients against a headscale server.

how to install headscale

The README gives no install command. It links the documentation at headscale.net/stable/ and, for contributors, nix develop followed by make build. It also states plainly that the project does not support or encourage running Headscale with a reverse proxy or in a container, even though development builds are published as container images and binaries.

Is Headscale free to use?

Yes, it is open source under the BSD-3-Clause licence, with a LICENSE file at the repository root. The project asks for sponsorship or donations rather than charging, and it is not associated with Tailscale Inc., although one active maintainer is employed by Tailscale and is allowed to spend work hours on contributions that other maintainers review.

Official sources

  1. Official README
  2. Project repository
  3. Release notes
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/juanfont-headscale.svg)](https://hysenlabs.com/projects/juanfont-headscale)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/juanfont-headscale.svg)](https://hysenlabs.com/projects/juanfont-headscale)

Was this useful?