Skip to content

Headscale: self-hosting the Tailscale control plane

How to deploy Headscale as an open-source coordination server for Tailscale clients — install, OIDC, DERP, and the operational trade-offs versus the managed control plane.

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:

  1. HTTP control flow — long-polling registration, key exchange, ACL fetch, status. This is what Headscale implements.
  2. 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

  1. 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
  2. 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
  3. Front it with Caddy for TLS:

    headscale.example.org {
        reverse_proxy 127.0.0.1:8080
    }
  4. 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
  5. 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.org interactively and is redirected to the IdP login.

  6. Load ACL policy.

    headscale policy set -f /etc/headscale/acl.json
    headscale policy get
  7. 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@latest

    Then run derper behind Caddy on a public FQDN with TLS, and add it to derp.paths in config.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.key and noise_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_url to 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.