Headscale — Open Source Self-Hosted Tailscale Control Server

What it is

Headscale is an open-source implementation of the Tailscale control server (coordination server). Tailscale clients connect to Headscale instead of Tailscale's SaaS control plane, giving you a fully self-hosted WireGuard mesh VPN. Devices authenticate, exchange keys, and establish encrypted peer-to-peer connections through your own server.

It targets privacy-conscious users, organizations with data sovereignty requirements, and anyone who wants Tailscale's ease of use without depending on a third-party coordination service.

How it saves time or tokens

Setting up a traditional VPN (OpenVPN, WireGuard manually) requires configuring each peer, managing key distribution, and maintaining routing tables. Headscale with Tailscale clients automates all of this. Devices join the network by authenticating against Headscale, and the mesh topology is managed automatically.

The Tailscale client handles NAT traversal, so devices behind firewalls can connect directly without port forwarding. This removes the common pain point of VPN setup for remote workers and distributed teams.

How to use

1. Deploy Headscale on a server with a public IP. Install from the package repository or run with Docker. Configure the config.yaml with your domain name and authentication settings.
2. Install the Tailscale client on each device. Point it to your Headscale server: tailscale up --login-server https://headscale.example.com.
3. Authenticate the device from the Headscale server, and it joins the mesh VPN. All connected devices can reach each other over encrypted WireGuard tunnels.

Example

# Deploy Headscale with Docker
docker run -d --name headscale \
  -p 8080:8080 -p 9090:9090 \
  -v headscale-data:/var/lib/headscale \
  -v headscale-config:/etc/headscale \
  headscale/headscale:latest serve

# Create a user (namespace)
docker exec headscale headscale users create myuser

# On a client device, connect to your Headscale server
tailscale up --login-server https://headscale.example.com

# Approve the device on the server
docker exec headscale headscale nodes register \
  --user myuser --key nodekey:abc123...

# Check connected nodes
docker exec headscale headscale nodes list

Related on TokRepo

• AI tools for security — VPN and zero-trust networking tools
• AI tools for self-hosted — Self-hosted infrastructure alternatives

Common pitfalls

• Not configuring HTTPS for the Headscale server. Tailscale clients require a secure connection to the control server. Place Headscale behind a reverse proxy with a valid TLS certificate (Let's Encrypt works well).
• Forgetting to open the required ports. Headscale needs its HTTP/gRPC port accessible to clients. The Tailscale clients also need UDP port 41641 for direct WireGuard connections between peers.
• Running an outdated Headscale version with a newer Tailscale client. Headscale tracks Tailscale's protocol changes. Version mismatches can cause connection failures. Keep both Headscale and Tailscale clients reasonably up to date.