Self-Hosting Headscale on a Raspberry Pi: Running Your Own Tailscale-Compatible Control Server

Our Tailscale guide covers installing the Tailscale client on a Pi and joining Tailscale's own hosted coordination service, which is the right call for most people. Headscale is for the subset of makers who want the same WireGuard-based mesh networking, the same familiar tailscale up client experience, but without any node list, ACL policy, or traffic metadata living on a third party's servers. It's an open-source, self-hosted re-implementation of the Tailscale control server, and a Raspberry Pi is a perfectly good place to run it for a home or shop tailnet. This guide covers what Headscale actually replaces, setting it up, and connecting your first clients.

What Headscale Actually Does (and Doesn't Replace)

ComponentWho provides it with TailscaleWho provides it with Headscale Control server (node coordination, key distribution, ACLs)Tailscale's cloud serviceYour Headscale instance WireGuard data plane (the actual encrypted tunnels between devices)Peer-to-peer between your devicesStill peer-to-peer between your devices; unchanged DERP relay servers (fallback when direct peer-to-peer fails, e.g. behind strict NAT)Tailscale's global DERP networkCan still use Tailscale's public DERP servers, or you can run your own Client softwareThe standard Tailscale app, on every platformThe exact same standard Tailscale app, just pointed at your server instead

That last row is the key thing people get wrong: you don't install different software on your laptop or phone. Headscale is a drop-in replacement for the control plane only; the official Tailscale client just gets told to talk to your server instead of Tailscale's.

Setting Up Headscale on a Raspberry Pi

Headscale needs to be reachable from every device you want on the tailnet, which usually means either a public IP/domain with a reverse proxy and TLS, or running it on a Pi that's already reachable via another VPN for initial setup. The simplest path on a Pi is Docker Compose:

services: headscale: image: headscale/headscale:latest container_name: headscale restart: unless-stopped command: serve volumes: - ./config:/etc/headscale - ./data:/var/lib/headscale ports: - "8080:8080" - "9090:9090"

Key settings in config.yaml that you'll edit before first run:

• server_url: the externally reachable address clients will connect to, e.g. https://headscale.yourdomain.com.
• listen_addr: the internal bind address inside the container, typically 0.0.0.0:8080.
• database: SQLite is fine for a home/shop-scale tailnet; the default path lands under /var/lib/headscale, which is why that directory is a mounted volume above.
• dns_config.base_domain: sets the MagicDNS-style domain suffix your devices get, e.g. devices.yourtailnet.internal.

Put a reverse proxy (Nginx or Caddy, see our Nginx reverse proxy guide) in front of port 8080 with a real TLS certificate if you're exposing this beyond your LAN; Tailscale clients expect HTTPS on the control server URL.

Creating Users and Registering Clients

1. Create a user: docker compose exec headscale headscale users create shop
2. Generate a reusable pre-auth key so you don't have to approve every device by hand: docker compose exec headscale headscale preauthkeys create --user shop --reusable --expiration 24h
3. On each client, install the normal Tailscale app, then point it at your server instead of Tailscale's default:
   tailscale up --login-server=https://headscale.yourdomain.com --authkey=<your-key>
4. Mobile clients (iOS/Android) don't expose a login-server field in their normal settings UI; you'll need to use the app's debug/advanced settings menu to point them at your Headscale instance, which is the one meaningfully clunkier step compared to the hosted Tailscale experience.

DERP Relays: Default vs Self-Hosted

By default, Headscale can still use Tailscale's own public DERP relay network for NAT traversal fallback, which is a reasonable choice for most home setups and doesn't send your actual traffic through Tailscale's infrastructure, only the relay metadata needed when a direct connection can't be established. If you want to remove that dependency entirely, Headscale supports pointing at a custom DERP map file running your own relay, at the cost of one more service to maintain.

Why Bother, Given Tailscale's Free Tier Is Generous

Headscale earns its complexity for a specific set of priorities: no reliance on a third party's uptime or policy changes for your own devices to talk to each other, full control over ACL policy files without a vendor dashboard, and no node list or account metadata leaving your infrastructure. For a shop network tying together a Pi-based CNC controller, a NAS, and a few laptops, that's a reasonable tradeoff against the extra maintenance of running your own control server. If you'd rather not maintain another service, the hosted Tailscale setup covered in our other guide remains the lower-effort option and is what we'd recommend to most readers.