Headscale

intermediate

Self-hosted Tailscale control server.

Overview

Headscale is an open-source, self-hosted implementation of the Tailscale control server that enables organizations to create their own mesh VPN networks without relying on Tailscale's hosted service. Originally developed as a reverse-engineered alternative to Tailscale's proprietary coordination server, Headscale provides complete control over your WireGuard-based mesh network infrastructure while maintaining compatibility with official Tailscale clients. The control server handles device authentication, key distribution, and network topology management, acting as the central coordination point for all nodes in your private mesh network. This Docker deployment creates a centralized Headscale server that manages node registration, user authentication, and network routing for your mesh VPN. The containerized approach simplifies deployment while maintaining the security and privacy benefits of self-hosting your VPN coordination infrastructure. Headscale communicates with standard Tailscale clients on user devices, handling the complex orchestration of peer-to-peer connections, NAT traversal, and encryption key management that makes mesh networking possible. This stack is ideal for privacy-conscious organizations, homelab enthusiasts, and enterprises requiring complete control over their VPN infrastructure without vendor lock-in. System administrators managing distributed teams, developers needing secure access to multiple environments, and security teams implementing zero-trust networking architectures will find Headscale particularly valuable for maintaining granular control over network access policies and user management while avoiding the recurring costs and data sharing implications of commercial mesh VPN services.

Key Features

Complete Tailscale control server replacement with full client compatibility
Multi-user namespace support for organizational segregation and access control
Built-in DERP relay server for NAT traversal and connection optimization
RESTful API for programmatic node management and automation workflows
Pre-authentication key generation for streamlined device onboarding
Access Control Lists (ACLs) for fine-grained network segmentation policies
Machine expiry management with automatic cleanup of stale connections
Prometheus metrics endpoint for monitoring mesh network health and performance

Common Use Cases

1Enterprise organizations replacing commercial Tailscale subscriptions with self-hosted infrastructure
2Homelab environments connecting remote servers, IoT devices, and personal computers
3Development teams requiring secure access to staging and production environments
4Remote work scenarios where employees need private network access without traditional VPN overhead
5Multi-cloud deployments connecting resources across AWS, Azure, and on-premises infrastructure
6Privacy-focused organizations avoiding third-party VPN providers and data sharing agreements
7Educational institutions providing secure network access for students and faculty across campuses

Prerequisites

Docker and Docker Compose installed with at least 512MB available memory
Public IP address or domain name for client connectivity and DERP functionality
TCP ports 8080 and 9090 available and accessible from client networks
Basic understanding of Tailscale concepts including nodes, users, and pre-authentication keys
SSL/TLS certificate management knowledge for production HTTPS deployments
Network administration experience for configuring firewalls and DNS records

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  headscale: 
3    image: headscale/headscale:latest
4    container_name: headscale
5    restart: unless-stopped
6    command: serve
7    volumes: 
8      - headscale_config:/etc/headscale
9      - headscale_data:/var/lib/headscale
10    ports: 
11      - "8080:8080"
12      - "9090:9090"
13
14volumes: 
15  headscale_config: 
16  headscale_data:

.env Template

.env

1# Create config.yaml in headscale_config volume
2# See headscale.net for configuration

Usage Notes

1Docs: https://headscale.net/
2Generate config: docker run headscale/headscale generate config > config.yaml
3Create user: docker exec headscale headscale users create myuser
4Register node: docker exec headscale headscale nodes register --user myuser --key nodekey:xxx
5Clients use standard Tailscale app with --login-server=http://your-headscale:8080
6API on port 8080, metrics on port 9090

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  headscale:
5    image: headscale/headscale:latest
6    container_name: headscale
7    restart: unless-stopped
8    command: serve
9    volumes:
10      - headscale_config:/etc/headscale
11      - headscale_data:/var/lib/headscale
12    ports:
13      - "8080:8080"
14      - "9090:9090"
15
16volumes:
17  headscale_config:
18  headscale_data:
19EOF
20
21# 2. Create the .env file
22cat > .env << 'EOF'
23# Create config.yaml in headscale_config volume
24# See headscale.net for configuration
25EOF
26
27# 3. Start the services
28docker compose up -d
29
30# 4. View logs
31docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/headscale/run | bash

Troubleshooting

Clients failing to connect with 'failed to connect to control server': Verify port 8080 is accessible and --login-server URL is correct in client configuration
Node registration hanging or timing out: Check that Headscale container can resolve client DNS names and firewall rules allow bidirectional communication
DERP relay connection failures: Ensure your Headscale server has a public IP or properly configured port forwarding for embedded DERP functionality
Permission denied errors during config generation: Run config generation command with proper volume mounting and check Docker socket permissions
Metrics endpoint returning 404 errors: Verify port 9090 is properly exposed and Headscale is compiled with metrics support enabled
Pre-authentication keys not working: Check key expiry with 'headscale preauthkeys list' and ensure keys match the correct user namespace

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

headscale

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download