Headscale — Open Source Self-Hosted Tailscale Control Server

What Headscale Does

• Coordination Server: Manages connections between Tailscale clients
• Key Distribution: Handles WireGuard key exchange between nodes
• ACL Management: Fine-grained access control with Tailscale-compatible ACLs
• Pre-Auth Keys: Generate auth keys for headless device registration
• DNS Integration: Built-in MagicDNS support for easy device addressing
• Subnet Routing: Advertise and use local network subnets
• Exit Nodes: Route all traffic through a designated node
• OIDC Auth: Integrate with Keycloak, Authentik, Auth0 for user authentication
• Multi-User: Separate namespaces for different users/teams

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ Tailscale    │     │  Headscale   │     │ Tailscale    │
│ Client       │────▶│  Server      │◀────│ Client       │
│ (Phone)      │     │  (Go)        │     │ (Laptop)     │
└──────┬───────┘     └──────────────┘     └──────┬───────┘
       │                                          │
       │         Direct WireGuard P2P            │
       └──────────────────────────────────────────┘
            Encrypted mesh network

Headscale handles coordination only. Actual network traffic flows directly between clients via encrypted WireGuard tunnels.

Self-Hosting

Docker Compose

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

volumes:
  headscale-data:

Basic Config

# config/config.yaml
server_url: https://headscale.yourdomain.com
listen_addr: 0.0.0.0:8080
metrics_listen_addr: 127.0.0.1:9090
grpc_listen_addr: 0.0.0.0:50443

private_key_path: /var/lib/headscale/private.key

noise:
  private_key_path: /var/lib/headscale/noise_private.key

prefixes:
  v6: fd7a:115c:a1e0::/48
  v4: 100.64.0.0/10
  allocation: sequential

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

database:
  type: sqlite
  sqlite:
    path: /var/lib/headscale/db.sqlite

log:
  level: info

dns_config:
  override_local_dns: true
  nameservers:
    - 1.1.1.1
    - 8.8.8.8
  magic_dns: true
  base_domain: headscale.local

Usage Guide

1. Create a User (Namespace)

docker exec headscale headscale users create myuser

2. Generate Pre-Auth Key

docker exec headscale headscale preauthkeys create 
  --user myuser --reusable --expiration 24h
# Output: your-preauth-key

3. Connect Tailscale Client

# On any Linux/Mac/iOS/Android/Windows device
# Install Tailscale first, then:
tailscale up --login-server=https://headscale.yourdomain.com 
  --authkey=your-preauth-key

4. Verify Connection

# On the Headscale server
docker exec headscale headscale nodes list

# On the client
tailscale status

Key Features

MagicDNS

Automatic DNS resolution for all nodes in your network:

my-laptop.myuser.headscale.local
my-phone.myuser.headscale.local
home-server.myuser.headscale.local

SSH or ping devices by name instead of IP address.

ACL (Access Control Lists)

{
  "groups": {
    "group:admins": ["alice@example.com", "bob@example.com"],
    "group:devs": ["charlie@example.com"]
  },
  "tagOwners": {
    "tag:prod": ["group:admins"],
    "tag:dev": ["group:devs"]
  },
  "acls": [
    {
      "action": "accept",
      "src": ["group:admins"],
      "dst": ["*:*"]
    },
    {
      "action": "accept",
      "src": ["group:devs"],
      "dst": ["tag:dev:*"]
    }
  ]
}

Subnet Routing

Advertise your local network through a Headscale node:

# On the router node
tailscale up --advertise-routes=192.168.1.0/24 
  --login-server=https://headscale.yourdomain.com

# Approve route in Headscale
docker exec headscale headscale routes enable -r 1

Now all Headscale clients can access your home network (192.168.1.0/24).

Exit Nodes

Use any node as an exit node to route all internet traffic through it:

# Configure a node as exit node
tailscale up --advertise-exit-node 
  --login-server=https://headscale.yourdomain.com

# Use it on another device
tailscale up --exit-node=home-server

Headscale vs Alternatives

常见问题

Q: 可以用官方 Tailscale 客户端吗？ A: 是的！Headscale 的最大优势就是与官方 Tailscale 客户端完全兼容。你只需要在 tailscale up 时指定 --login-server 指向你的 Headscale 服务器即可。

Q: Headscale 和 NetBird 怎么选？ A: Headscale 兼容官方 Tailscale 客户端（iOS/Android 体验更好），但 Web UI 不如 NetBird。NetBird 有完整的 Web UI 但需要自己的客户端。Tailscale 生态成熟度选 Headscale，管理体验选 NetBird。

Q: 适合企业使用吗？ A: 适合。Headscale 支持 OIDC 认证（集成 Keycloak、Authentik 等），ACL 配置完整，支持用户和群组管理。小到中型企业（100-1000 用户）运行良好。

来源与致谢

• GitHub: juanfont/headscale — 37.3K+ ⭐ | BSD-3
• 文档: headscale.net