🌐 Setup Headscale — Self-Hosted Tailscale Control Server
Deploy Headscale, an open-source implementation of the Tailscale control server. Build your own private mesh VPN network fully under your control.
📦 Resources & Setup Scripts
Grab the automated bash script from GitHub to follow along.
Quick Install:
wget https://raw.githubusercontent.com/mhmdali94/Docker/main/vpn/headscale/headscale-ubuntu.sh
chmod +x headscale-ubuntu.sh
sudo bash headscale-ubuntu.shTutorial Steps
1 Download & Run the Script
The script installs Docker, configures Headscale with your server domain or IP, and starts the control server and web UI.
wget https://raw.githubusercontent.com/mhmdali94/Docker/main/vpn/headscale/headscale-ubuntu.sh
chmod +x headscale-ubuntu.sh
sudo bash headscale-ubuntu.sh2 Access the Web UI
Open your browser and navigate to the Headscale UI:
http://YOUR-SERVER-IP:80903 Create a User and Generate Auth Key
Use the Headscale CLI or web UI to create a user namespace and generate a pre-auth key. Clients use this key to register with your control server.
4 Connect Tailscale Clients
Install Tailscale on each device and point it to your Headscale server. Run: tailscale up --login-server http://YOUR-SERVER-IP:8090 --authkey YOUR-KEY
Ports Used
| Port | Protocol | Purpose |
|---|---|---|
| 8090 | TCP | Headscale Control Server |
| 8091 | TCP | Headscale Web UI |
Files Location
/root/docker/headscale/docker-compose.ymlOverview
Headscale is a self-hosted, open-source implementation of the Tailscale control server. Tailscale builds a WireGuard mesh VPN between devices, but its control plane runs on Tailscale's servers. Headscale replaces that control plane entirely, so you own the coordination layer. All registered devices communicate peer-to-peer over WireGuard with no traffic passing through your server.
Why Use It
Headscale gives you everything Tailscale offers — zero-config WireGuard mesh VPN, stable 100.x.x.x IP addresses per device, and official Tailscale clients on every OS — without your device list, keys, or network topology ever touching Tailscale's cloud. For compliance-driven teams, privacy-conscious homelabbers, or organizations that simply cannot send internal network metadata to a third party, Headscale is the only viable self-hosted option.
When You Need It
Who Should Use It
Real Use Cases
Main Features
How to Use After Installation
Security Best Practices
Ports and Firewall Notes
Headscale uses port 8090 for the control server API (where Tailscale clients register) and port 8091 for the optional web UI. In production, expose neither directly — place both behind Nginx Proxy Manager and forward HTTPS traffic. The WireGuard tunnels established between client devices use UDP port 41641 (the Tailscale default) and do not pass through your server, so that port does not need to be opened on the Headscale server itself.
Backup and Maintenance
Common Mistakes
Troubleshooting
Alternatives
The main alternative is Tailscale itself (cloud-hosted, free tier for up to 3 users / 100 devices, paid plans beyond that) — far simpler to operate but your network metadata lives on Tailscale's servers. NetBird is a direct self-hosted competitor with a built-in management UI, access control policies, and a more modern architecture, but it is heavier to deploy. ZeroTier is another self-hostable option with its own protocol (not WireGuard) and a more complex routing model. WireGuard Easy is a simpler choice if you just need a single-server VPN with no mesh routing.
When Not to Use It
Skip Headscale if you just need a VPN to protect a single device or access a home network — WireGuard Easy is far simpler. If you have fewer than 3 users and 100 devices, Tailscale's free cloud plan saves all the operational overhead. Headscale is also not ideal if you need enterprise features like SAML SSO, detailed audit logs, or SOC 2 compliance guarantees — Tailscale Business or a commercial solution is more appropriate for those requirements.
PrismaTechWork Professional Help
PrismaTechWork provides end-to-end infrastructure services — from initial deployment and security hardening to ongoing monitoring, automated backups, and dedicated support. Whether you need a single-server setup or a multi-site network, our team ensures your infrastructure is built right, secured properly, and maintained reliably.
Frequently Asked Questions
Can I use the official Tailscale app with Headscale?
Yes. Headscale is designed to be compatible with official Tailscale clients on all platforms — Windows, macOS, Linux, iOS, and Android. You point the client at your Headscale server URL instead of the Tailscale cloud: tailscale up --login-server https://your-headscale-domain.com. The user experience is identical to regular Tailscale.
Does traffic pass through the Headscale server?
No. Headscale is a control plane only — it coordinates device registration and key exchange, but all actual VPN traffic flows directly between devices over WireGuard peer-to-peer tunnels. Your server does not see or relay user data. The exception is DERP relay traffic when two devices cannot establish a direct tunnel (strict NAT), which routes through a relay server.
What is the difference between Headscale and NetBird?
Both are self-hosted WireGuard mesh VPN solutions. Headscale is a drop-in replacement for Tailscale's control plane — it uses Tailscale's official clients and protocol. NetBird is an independent project with its own client app, management UI, and richer access control policies. Choose Headscale if you're already in the Tailscale ecosystem; choose NetBird for a more feature-complete self-hosted solution with a built-in dashboard.
How do I register a new device to my Headscale network?
Generate a pre-auth key: docker exec headscale headscale preauthkeys create --user myuser --expiration 1h. Install Tailscale on the new device and run: tailscale up --login-server https://your-headscale-domain.com --authkey YOUR-KEY. The device appears in your node list immediately and gets a stable 100.x.x.x address.
Does Headscale support MagicDNS (resolving devices by hostname)?
Partially. Headscale has experimental DNS configuration support. You can define nameservers and search domains in headscale's config, and the Tailscale client will configure split DNS on the device. However, full MagicDNS (automatic hostname resolution like device.tailnet.ts.net) is not 100% feature-complete in Headscale — test it in your environment before relying on it.
Can I run Headscale for multiple organizations or teams?
Yes, using Headscale's user/namespace system. Each user or namespace is a logical group — devices in different namespaces cannot reach each other by default. You can create separate namespaces for different teams, customers, or environments on the same Headscale instance. ACL rules can selectively allow cross-namespace traffic.
How do I update Headscale?
Back up the SQLite database first, then run: docker compose -f /root/docker/headscale/docker-compose.yml pull && docker compose -f /root/docker/headscale/docker-compose.yml up -d. Headscale runs automatic database migrations on startup. Check docker logs headscale after the update to confirm no migration errors.
Is Headscale production-ready?
Headscale is widely used in production by homelabbers and small organizations, but it is not officially supported by Tailscale and does not have a commercial SLA. The project is actively maintained on GitHub. For critical business infrastructure where downtime has financial consequences, evaluate whether the operational overhead of self-hosting is acceptable, or consider Tailscale's paid cloud offering instead.