Headscale self-host: the sovereign Tailscale control plane (2026)

Affiliate disclosure — This post contains Contabo affiliate links. If you grab a VPS through them, we earn a commission at no extra cost to you. We only document what we actually run in production on our own VPS.

If you've read our Tailscale vs WireGuard self-host comparison, you already know Headscale is the third path — the one that combines Tailscale-grade UX with WireGuard self-host sovereignty. The question is no longer "is it possible?" but "is it worth the setup time?". This guide answers concretely, based on the Headscale instance we've been running in production on Contabo since February 2026.

Plan: what Headscale really is, when it makes sense (and when it doesn't), step-by-step install on Contabo with PostgreSQL and OIDC, ACL configuration, the production traps nobody warns you about, and 36-month costs vs Tailscale Premium. By the end, you'll be able to decide in 5 minutes whether to invest the 2-3 days a clean setup demands.

What Headscale actually is

Headscale is an open-source reimplementation of the Tailscale coordinator API, written in Go, maintained primarily by Juan Font and a tight contributor community. Source code: github.com/juanfont/headscale. License: BSD-3.

It's not a fork of Tailscale. It's a server that speaks the same protocol as the Tailscale SaaS coordinator — meaning the official Tailscale clients (iOS, Android, macOS, Windows, Linux) can be pointed at your Headscale instance and they'll behave normally. There's no patched client, no shady custom binary.

What Headscale handles:

• Peer discovery and key distribution — exactly like the SaaS coordinator.
• NAT traversal coordination — via DERP relays (you can use Tailscale's public DERP relays for free, or self-host your own).
• Declarative ACLs — accepts the same JSON ACL format as Tailscale. Same syntax, same semantics.
• MagicDNS — resolution of node.tailnet.example.com (or whatever domain you configure).
• Subnet routes — to expose a VPC or LAN behind one node.
• Exit nodes — to route all internet traffic through a chosen node.

What Headscale does NOT handle (the honest limits):

• No official Premium features: no Tailscale SSH session recording, no native SSO console (you wire up OIDC yourself), no proprietary GUI admin (a separate headscale-ui project exists, third-party).
• Mobile client management is more manual — auth keys must be generated CLI-side.
• Tailscale Inc. support is non-existent — community support only, GitHub Discussions and Discord.

The promise is precise: 90% of Tailscale Premium's value, for ~5% of the cash cost, with 100% data sovereignty.

When Headscale actually makes sense

Headscale isn't always the right answer. Here's the decision matrix from 8 months of production:

The two main reasons people deploy Headscale in production:

1. Sovereignty / compliance: legal department or DSI bans uncontrolled SaaS dependency. Headscale checks the "European hosted, GDPR-compliant, no US transfer" box. It's the case in growing EU regulated B2B SaaS.
2. Cash optimization at scale: at 15+ users, Tailscale Premium becomes 4-figure monthly invoices. A Contabo VPS S at €60/year + 2-3 days of sysadmin time pays back in less than 2 months.

If neither of those drives your situation, stay on Tailscale Premium or raw WireGuard. The middle ground only makes sense if it's actually justified.

Architecture chosen for production

Here's the architecture we deployed in February 2026 and that still runs today:

[Tailscale client iOS/Android/Linux]
            │
            │ HTTPS (port 443)
            ▼
[Caddy reverse proxy] ──► [Headscale]
            │                    │
            │                    ▼
            │            [PostgreSQL 15]
            │
            └──► [Tailscale DERP relays - free public]

Components:

• Contabo VPS S Nuremberg (4 vCPU, 8 GB RAM, 200 GB NVMe, €4.99/month) — see our Contabo review 2026 and the step-by-step setup tutorial for getting the VPS ready.
• Headscale 0.24 as the coordinator.
• PostgreSQL 15 as backend (vs default SQLite, more robust above 20 nodes).
• Caddy 2 as reverse proxy with automatic Let's Encrypt TLS — Headscale needs HTTPS, the official clients require it.
• OIDC via Authentik (also self-hosted, but Auth0 or Keycloak work too).
• Tailscale public DERP relays for NAT traversal — free, no need to self-host DERP unless you have specific paranoia constraints.

Step-by-step install on Contabo

Setup time on a freshly provisioned VPS: about 90 minutes if you follow the steps without hesitation. We'll assume Debian 12 (the Contabo default).

1. System prep

apt update && apt upgrade -y
apt install -y postgresql postgresql-contrib caddy curl wget

2. Create the Headscale PostgreSQL database

sudo -u postgres psql <<EOF
CREATE USER headscale WITH PASSWORD 'PUT_A_STRONG_PASSWORD_HERE';
CREATE DATABASE headscale OWNER headscale;
GRANT ALL PRIVILEGES ON DATABASE headscale TO headscale;
EOF

3. Install Headscale

The official .deb package is the cleanest path. Latest release: github.com/juanfont/headscale/releases.

HS_VERSION="0.24.0"
wget https://github.com/juanfont/headscale/releases/download/v${HS_VERSION}/headscale_${HS_VERSION}_linux_amd64.deb
dpkg -i headscale_${HS_VERSION}_linux_amd64.deb

4. Headscale configuration

Edit /etc/headscale/config.yaml. The minimum required settings:

server_url: https://headscale.your-domain.com
listen_addr: 127.0.0.1:8080
metrics_listen_addr: 127.0.0.1:9090

database:
  type: postgres
  postgres:
    host: localhost
    port: 5432
    name: headscale
    user: headscale
    password: PUT_A_STRONG_PASSWORD_HERE

derp:
  server:
    enabled: false
  urls:
    - https://controlplane.tailscale.com/derpmap/default

ip_prefixes:
  - 100.64.0.0/10

acl_policy_path: /etc/headscale/acl.json

oidc:
  issuer: https://auth.your-domain.com/application/o/headscale/
  client_id: headscale
  client_secret: OIDC_SECRET_HERE
  scope: ["openid", "profile", "email"]

Critical points:

• server_url must be HTTPS. The official Tailscale clients refuse to talk plain HTTP.
• ip_prefixes: 100.64.0.0/10 is the CGNAT range Tailscale uses by default. Don't change unless you know what you're doing.
• oidc: optional but strongly recommended in production. Without it you fall back to headscale users create and pre-shared keys.

5. Caddy as reverse proxy

/etc/caddy/Caddyfile:

headscale.your-domain.com {
    reverse_proxy 127.0.0.1:8080
}

Reload: systemctl reload caddy. Caddy automatically grabs the Let's Encrypt cert. Verify the chain is valid before going further — official Tailscale clients refuse self-signed.

6. Start Headscale

systemctl enable --now headscale
journalctl -u headscale -f

You should see startup logs, then "Listening on 127.0.0.1:8080".

7. Create a first user and a pre-auth key

headscale users create eric
headscale preauthkeys create --user eric --reusable --expiration 24h

The output gives a tskey-auth-xxxxxxxxxxxx key. Note it.

8. Connect a Tailscale client

On a Linux client with the official Tailscale client installed:

tailscale up \
  --login-server https://headscale.your-domain.com \
  --authkey tskey-auth-xxxxxxxxxxxx

The node appears in headscale nodes list. From there you can pull its 100.x.x.x IP and start using it.

For iOS/Android: install the official Tailscale app, settings → custom login server → enter your Headscale URL. Tap "Sign in", you'll be redirected to your OIDC provider.

Critical ACL configuration

ACLs are where Headscale shows it really is "Tailscale-compatible". The JSON file accepts the same syntax as Tailscale Premium ACLs.

Production example (5-user team with dev/staging segregation):

{
  "acls": [
    {
      "action": "accept",
      "src": ["group:admins"],
      "dst": ["*:*"]
    },
    {
      "action": "accept",
      "src": ["group:devs"],
      "dst": ["tag:dev:*", "tag:staging:22,80,443"]
    },
    {
      "action": "accept",
      "src": ["group:devs"],
      "dst": ["tag:prod:80,443"]
    }
  ],
  "groups": {
    "group:admins": ["eric@vpnsmith.com"],
    "group:devs": ["alice@vpnsmith.com", "bob@vpnsmith.com"]
  },
  "tagOwners": {
    "tag:dev": ["group:admins"],
    "tag:staging": ["group:admins"],
    "tag:prod": ["group:admins"]
  }
}

Reload after each edit: headscale acls reload. Headscale validates the JSON before applying, so a syntax error never breaks the prod mesh.

Production traps nobody mentions

Eight months of operating Headscale, here are the four traps that cost us a weekend or more:

1. PostgreSQL connection pool exhaustion. The default Headscale pool size is 25 connections. Past 50 simultaneous nodes with frequent reconnections (think Wi-Fi roaming on phones), you hit the limit and connections start dropping. Fix: bump database.postgres.max_open_conns to 100, and configure max_idle_conns: 10.

2. Tailscale public DERP relays can be capricious in Asia/Australia. If you have nodes in those zones, latency can balloon. Solution: self-host a DERP relay on a VPS in the region. Headscale handles it transparently — see the official DERP setup docs.

3. PostgreSQL backup is mandatory and underrated. Headscale stores everything in PostgreSQL: nodes, public keys, ACL state, OIDC mappings. Lose the DB, lose the entire mesh. Set up pg_dump daily + automated S3-compatible backup (we use Hetzner Object Storage at €1/month for that). Restore tested every 3 months.

4. Headscale binary upgrades are gentle but breaking changes happen between minor versions. Read the CHANGELOG before bumping from 0.23 to 0.24. The dev team is responsive on GitHub but Headscale is in active development — assume breaking changes about every 6 months.

Real costs over 36 months — Headscale vs Tailscale Premium

The math at 10 users, 25 nodes, with cautious assumptions:

Headscale wins by ~€2,250 over 36 months at 10 users. Not enormous, but real — and the gap widens linearly with team size. At 20 users you're saving ~€8,000/3 years. At 50 users it's serious money.

If your time is worth more than €100/h, that gap shrinks fast. If it's worth less than €50/h (junior, side project, learning), Headscale wins easily.

Verdict — when to deploy Headscale in 2026

Deploy Headscale if:

• You have a sovereignty / GDPR / no US transfer constraint
• Your team is 10+ users with 12+ months horizon
• You have an in-house sysadmin or sysadmin instinct
• Tailscale Premium feels expensive but raw WireGuard feels too primitive

Stay on Tailscale Premium if:

• Your time is worth more than €100/h
• No specific compliance constraint
• You'd rather spend that 2-3 days on your product

Stay on raw WireGuard if:

• You're under 5 nodes, simple setup, learning mood
• Hub-and-spoke fits all your use cases

Headscale is the most underrated answer in the self-hosted VPN ecosystem in 2026. It does 90% of Tailscale's job, on a Contabo VPS at €4.99/month, with full data sovereignty. The price is 2-3 days of setup and a sysadmin reflex — that pays for itself in less than 2 months at 10 users.

Going further

• Tailscale vs WireGuard self-host: which one in 2026
• Self-host VPN on Contabo: full WireGuard guide 2026
• Contabo VPS step-by-step setup for VPN 2026
• VPS VPN monitoring with Prometheus + Grafana
• Contabo review 2026: honest production feedback

Sources and references:

• Headscale — official source code and docs
• Headscale documentation site
• Tailscale ACL syntax reference
• DERP server setup guide

Published 2026-06-05. Production analysis based on a Headscale 0.24 instance deployed on a Contabo VPS S Nuremberg in February 2026 (12 nodes, 5 users, PostgreSQL backend, OIDC via Authentik). Costs from May 2026 Contabo and Tailscale pricing — verify before deciding. Real performance and savings depend on team size and existing infrastructure.

Reminder: Headscale, Tailscale and VPN self-hosting are perfectly legal in the EU, US, Canada and most democratic countries. VPNSmith publishes this content for educational purposes.