Headscale is an open-source reimplementation of the Tailscale coordination server. It speaks the same protocol as the Tailscale agent, so unmodified clients (Linux, macOS, Windows, iOS, Android) point at your Headscale instance instead of login.tailscale.com. We use it where regulatory constraints or air-gapped deployments rule out the managed control plane — but it does mean you now run the control plane yourself, including its outages.
How to verify
Before installing, confirm the host is reachable on a public FQDN with a working TLS cert (clients will refuse non-TLS), and that you have a plan for the OIDC provider that will gate user logins.
dig +short headscale.example.org
curl -sI https://headscale.example.org/health
ss -lntp | grep -E ':(80|443|8080)\b'
systemctl list-units | grep -E 'caddy|nginx|traefik'
Headscale needs a reverse proxy in front of it for TLS termination in real deployments. We default to Caddy because the on-demand TLS story is the simplest of the three.
What’s happening
The Tailscale client speaks two flows to its coordination server:
- HTTP control flow — long-polling registration, key exchange, ACL fetch, status. This is what Headscale implements.
- DERP relay — fallback data path when peers cannot establish a direct WireGuard connection due to NAT. Headscale can use Tailscale’s public DERP map (default) or you can self-host DERP servers.
Headscale stores state in SQLite by default; PostgreSQL is supported and is what we use for anything beyond a homelab. The ACL grammar is a near-superset of Tailscale’s (HuJSON), and there is a CLI (headscale) for user, namespace, and route management. Authentication can be pre-shared key (single-use registration tokens) or OIDC (Authentik, Keycloak, Google Workspace, Microsoft Entra).
The trade-off: you own the uptime. If Headscale is down, new sessions cannot authenticate and key rotation stalls. Existing tunnels keep working — clients hold the keys they last fetched — but the system enters a degraded state.
The procedure
-
Install Headscale. The Debian package is the cleanest path on Ubuntu.
curl -fsSL https://github.com/juanfont/headscale/releases/latest/download/headscale_linux_amd64.deb \ -o /tmp/headscale.deb apt install -y /tmp/headscale.deb systemctl enable headscale -
Configure
/etc/headscale/config.yaml. Production-shaped:server_url: https://headscale.example.org listen_addr: 127.0.0.1:8080 metrics_listen_addr: 127.0.0.1:9090 private_key_path: /var/lib/headscale/private.key noise: private_key_path: /var/lib/headscale/noise_private.key ip_prefixes: - fd7a:115c:a1e0::/48 - 100.64.0.0/10 database: type: postgres postgres: host: 127.0.0.1 port: 5432 name: headscale user: headscale password: <replace-me> derp: server: enabled: false urls: - https://controlplane.tailscale.com/derpmap/default oidc: only_start_if_oidc_is_available: true issuer: https://auth.example.org/realms/main client_id: headscale client_secret_path: /etc/headscale/oidc.secret scope: ["openid", "profile", "email"] extra_params: domain_hint: example.org strip_email_domain: true -
Front it with Caddy for TLS:
headscale.example.org { reverse_proxy 127.0.0.1:8080 } -
Start the service and create a namespace. “Namespace” is Headscale’s grouping primitive (think Tailscale “tailnet” but multi-tenant on one Headscale instance).
systemctl start headscale headscale users create engineering -
Register a client without OIDC, using a pre-auth key:
headscale --user engineering preauthkeys create --reusable --expiration 24h # On the client: tailscale up \ --login-server=https://headscale.example.org \ --authkey=<preauth-key>With OIDC enabled, the client runs
tailscale up --login-server=https://headscale.example.orginteractively and is redirected to the IdP login. -
Load ACL policy.
headscale policy set -f /etc/headscale/acl.json headscale policy get -
Self-host DERP (optional, but recommended for regulated deployments). The default config relays through Tailscale’s public DERP map; for jurisdictional or air-gapped builds, run your own:
apt install -y golang-go go install tailscale.com/cmd/derper@latestThen run
derperbehind Caddy on a public FQDN with TLS, and add it toderp.pathsinconfig.yaml.
Common pitfalls
- Pointing Headscale at SQLite for a real fleet — fine for a few nodes, but write contention shows up fast around 50 active devices. Use PostgreSQL.
- Forgetting to back up
private.keyandnoise_private.key— losing either invalidates every registered node and you re-enroll the entire fleet. - Letting the public DERP map drift — Tailscale rotates DERP server IPs occasionally; if you blocked outbound 80/443 to specific addresses, run your own DERP.
- Skipping OIDC and managing users via CLI — works on day one, becomes a liability the moment HR adds a new engineer at 16:55 on a Friday.
- Not setting
server_urlto match the actual hostname clients reach — Headscale embeds this in handshake messages; mismatch causes silent registration failures.
In the engagements we run, Headscale is the pattern for clients who need a Tailscale-style mesh but cannot send identity metadata to a third party — typically multi-region environments with data-sovereignty constraints. The control plane is a real piece of infrastructure: monitored, backed up, and on-call covered, the same as the database it sits next to.