VPN and private networking
What is Headscale? An introduction to Juan Font's self-hosted Tailscale control server
Headscale is an open source, self-hosted implementation of the Tailscale control server. It aims to be a self-hosted, open source alternative to that control server for WireGuard-based private networks. The project is not associated with Tailscale Inc.
- Tool
- Headscale
- Made by
- Juan Font
- Official site
- github.com/juanfont/headscale
- Category
- VPN and private networking
Who makes Headscale
Headscale is developed by Juan Font, and its official home is the GitHub repository linked below. The project is not associated with Tailscale Inc., even though it is designed to work with Tailscale's networking model.
Official website: github.com/juanfont/headscale
What Headscale is for
Tailscale is a WireGuard-based VPN that works as an overlay network using NAT traversal. Headscale provides a self-hosted implementation of the control server for that kind of network, so the coordination role is run by the user rather than by a third party.
The control server exchanges WireGuard public keys between nodes, which lets them establish encrypted connections with one another. It also assigns IPs, separates users, enables machine sharing, and exposes advertised routes.
Who Headscale is for
Headscale's stated goal is to serve self-hosters and hobbyists with projects and labs. It supports a single tailnet, which makes it suited to personal use or a small open-source organisation.
The single-tailnet design is a real boundary. Readers who need several separate networks under one control server should take it into account when evaluating the project.
Notable capabilities
Headscale's functions are those of a control server, plus a few packaging and development details.
- Exchange of WireGuard public keys between nodes.
- Assignment of IPs to nodes in the network.
- Separation of users within the tailnet.
- Machine sharing between nodes.
- Exposure of advertised routes.
- A NixOS module for deployment on NixOS.
- Development builds from the main branch published as container images and binaries.
How Headscale fits VPN and private networking
In VPN and private networking, Headscale occupies the self-hosted, community-run end of the WireGuard overlay-network approach. It does not carry traffic itself in the way a conventional VPN server does; it coordinates nodes so that they can connect using WireGuard.
The project states that it does not support or encourage running Headscale behind reverse proxies or in containers, even though development builds are published as container images and binaries. Anyone planning a deployment should read that guidance before choosing an architecture. Contributing to the project requires Go and Buf, the Protobuf generator.
Within Cipherholt's wider niche of encryption, cryptography, secure messaging, VPN, and secrets management, Headscale is a networking tool for people who want to control the coordination layer of their private network themselves.
Frequently asked questions
What is Headscale used for?
Headscale is used to run a self-hosted control server for a Tailscale-style, WireGuard-based private network. It exchanges WireGuard public keys between nodes, assigns IPs, separates users, enables machine sharing, and exposes advertised routes.
Is Headscale made by Tailscale?
No. Headscale is developed by Juan Font, and the project is not associated with Tailscale Inc.
Does Headscale support multiple tailnets?
No. It supports a single tailnet, which suits personal use or a small open-source organisation.
Can Headscale run in a container or behind a reverse proxy?
The project does not support or encourage running Headscale behind reverse proxies or in containers. Development builds from the main branch are, however, published as container images and binaries.
Cipherholt is independent and is not affiliated with Juan Font. Product names belong to their owners. Features change; confirm details on the official website.