# Headscale — Open Source Self-Hosted Tailscale Control Server > Headscale is an open-source implementation of the Tailscale control server. Run your own private mesh VPN with WireGuard, no Tailscale subscription needed. ## Install Save in your project root: ## Quick Use ```bash docker run -d --name headscale -p 8080:8080 -v headscale-config:/etc/headscale -v headscale-data:/var/lib/headscale headscale/headscale:latest headscale serve ``` Create a namespace and register your Tailscale clients to point to your Headscale server. ## Intro **Headscale** is an open-source, self-hosted implementation of the Tailscale control server. Tailscale is a beautiful zero-config VPN built on WireGuard, but the official service uses a proprietary control server. Headscale lets you run your own control server, giving you a fully self-hosted Tailscale experience with no subscription fees and complete data sovereignty. With 37.3K+ GitHub stars and BSD-3-Clause license, Headscale is the most popular open-source mesh VPN solution, perfect for homelab users, privacy-conscious individuals, and organizations that need VPN without external dependencies. ## 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 ```yaml 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 ```yaml # 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) ```bash docker exec headscale headscale users create myuser ``` ### 2. Generate Pre-Auth Key ```bash docker exec headscale headscale preauthkeys create --user myuser --reusable --expiration 24h # Output: your-preauth-key ``` ### 3. Connect Tailscale Client ```bash # 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 ```bash # 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) ```json { "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: ```bash # 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: ```bash # 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 | Feature | Headscale | Tailscale | NetBird | ZeroTier | |---------|-----------|-----------|---------|----------| | Open Source | Yes (BSD-3) | Client only | Yes (BSD-3) | Yes (BSL) | | Self-hosted | Yes | No (SaaS) | Yes | Yes | | Protocol | WireGuard | WireGuard | WireGuard | Custom | | Mobile apps | Yes (via TS) | Yes | Yes | Yes | | Setup complexity | Medium | Very easy | Easy | Easy | | Free users | Unlimited | 100 (free tier) | Unlimited | 50 (free) | | ACL | Yes | Yes | Yes | Yes | | Use official apps | Yes (Tailscale) | Yes | Custom apps | Custom apps | ## 常见问题 **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](https://github.com/juanfont/headscale) — 37.3K+ ⭐ | BSD-3 - 文档: [headscale.net](https://headscale.net) --- Source: https://tokrepo.com/en/workflows/d339dece-3530-11f1-9bc6-00163e2b0d79 Author: AI Open Source