Migrating from Tailscale to Headscale: the break-even point

Why reconsider your mesh network in 2026

• Full data control: no list of your machines, internal IP addresses, node names or connection logs passes through a third-party server.
• No node or user limits imposed by the software: Headscale is bounded only by your VPS resources.
• Full compatibility with official Tailscale clients: the --login-server flag is all you need to point to your own control plane.
• MagicDNS on your own domain: each node is reachable by its short name under the suffix you choose.
• Optional OIDC: delegate authentication to Keycloak, Authelia, or any compatible OIDC provider.
• Operational durability: your mesh network no longer depends on a third-party pricing decision or outage.
• Reasonable maintenance: a package update every few weeks, a SQLite backup schedulable in one cron line.

Financial analysis: the break-even point

Tailscale Standard vs Headscale on VPS

Scroll the table

Technical prerequisites

• VPS running Debian 11/12 or Ubuntu 22.04/24.04 — 1 vCPU, 512 MB RAM minimum (Headscale runs under 64 MB idle; 1 GB recommended for headroom).
• TCP port 443 open inbound: clients connect here for registration and configuration retrieval over HTTPS.
• UDP port 3478 open: used for STUN negotiation (discovery of candidate addresses for direct connections).
• UDP port 41641 open: WireGuard signaling port that Tailscale clients use to contact the coordinator.
• A domain name or subdomain pointing to the VPS: required for a valid TLS certificate. Let's Encrypt works via certbot or the integrated nginx module.
• Embedded SQLite: Headscale requires no external database — a single SQLite file in /var/lib/headscale/ is sufficient for hundreds of nodes.

Installing Headscale on a ServOrbit VPS

1. 01

   Update the system and install dependencies

   Connect via SSH and update packages:

   apt update && apt upgrade -y

   Install nginx and certbot for the HTTPS reverse proxy:

   apt install -y nginx certbot python3-certbot-nginx

2. 02

   Download and install the Headscale package

   Headscale v0.29.4 (September 2026) provides .deb packages for amd64 and arm64. Download and install:

   curl -Lo /tmp/headscale.deb https://github.com/juanfont/headscale/releases/download/v0.29.4/headscale_0.29.4_linux_amd64.deb

   dpkg -i /tmp/headscale.deb

   Verify the installation: headscale version should return 0.29.4. On ARM64, replace linux_amd64 with linux_arm64.

3. 03

   Configure Headscale

   The package creates the headscale system user and /etc/headscale/. Edit the minimal configuration:

   nano /etc/headscale/config.yaml

   Set at minimum: server_url: https://headscale.your-domain.com, listen_addr: 0.0.0.0:8080, db_type: sqlite3, db_path: /var/lib/headscale/db.sqlite, and in dns_config: magic_dns: true, base_domain: your-domain.com. Create the data directory: mkdir -p /var/lib/headscale && chown headscale:headscale /var/lib/headscale.

4. 04

   Enable and start the service

   The package installs the systemd unit automatically:

   systemctl enable --now headscale

   Check status: systemctl status headscale. Output should show Active: active (running). If there is an error, check logs: journalctl -u headscale -f. The most common error at first start is a malformed server_url — it must start with https://.

5. 05

   Set up the HTTPS reverse proxy

   Obtain a Let's Encrypt certificate and configure nginx:

   certbot --nginx -d headscale.your-domain.com

   In the generated nginx vhost, add to the location / block:

   proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;

   Reload nginx: systemctl reload nginx. Verify that https://headscale.your-domain.com/health returns {"status":"pass"}.

6. 06

   Create a first user and an authentication pre-key

   Headscale organizes nodes by users. Create your first user:

   headscale users create my-team

   Generate an authentication pre-key (preauthkey) to register machines without manual approval:

   headscale preauthkeys create --user my-team --expiration 24h

   Copy the returned key — you will need it when migrating clients. The --reusable option allows reusing the same key for multiple machines.

7. 07

   Open required ports in the firewall

   If your VPS uses ufw, open the required ports:

   ufw allow 443/tcp
ufw allow 3478/udp
ufw allow 41641/udp

   If you use iptables directly or a security panel (CSF, Imunify360), add these ports to the allowed inbound port list. Verify from an external machine that the UDP ports are reachable before migrating your clients.

Migrating clients from Tailscale in 3 steps

1. 08

   Disconnect the client from the existing Tailscale network

   On each machine to migrate, disconnect the client from the Tailscale network:

   tailscale logout

   On macOS and Windows, use the system tray menu: right-click the Tailscale icon → Log out. On iOS and Android, go to app settings → Log out. This step revokes authentication on the old network but does not uninstall the client.

2. 09

   Reconnect the client to your Headscale server

   Reconnect the client pointing to your new Headscale server. On Linux:

   tailscale up --login-server https://headscale.your-domain.com --authkey YOUR_PREAUTHKEY

   On macOS, from the terminal:

   tailscale up --login-server https://headscale.your-domain.com --authkey YOUR_PREAUTHKEY

   If you do not pass a preauthkey, the client displays an authentication URL to validate on the server side with: headscale nodes register --user my-team --key <NODE_KEY>. Verify registration: headscale nodes list should show the node with online status.

3. 10

   Verify connectivity between migrated nodes

   From a migrated node, verify that other nodes are visible:

   tailscale status

   The list should show all nodes registered on your Headscale server with their mesh IPs (100.64.x.x). Test direct connectivity with a ping: ping 100.64.0.2. A status of active (direct) confirms the WireGuard connection is established without a relay. If you enabled MagicDNS, test resolution: ping node-name.your-domain.com.

4. 11

   Migrate remaining nodes and close the Tailscale account

   Repeat the previous two steps for each machine. Migrate development or test machines first to validate the process, then production machines. Once all nodes are migrated and verified, you can close your Tailscale account or downgrade to the Personal plan if you still have personal use cases (six users max, free). Keep the preauthkey used or generate a new one for future nodes.

ACL and internal DNS configuration

• Edit the policy file: headscale policy set --policy-file /etc/headscale/policy.hujson
• Define user groups (groups) and per-port ACLs to segment access between dev, staging, and prod environments.
• Enable split DNS to resolve internal names: in dns_config, define nameservers with your internal DNS servers and search_domains for search suffixes.
• Export and version your policy file in a private Git repository — this simplifies audits and rollbacks.
• Test policy changes on a test node before applying them to the entire network: headscale policy check.

Troubleshooting common issues

• Node shows offline in headscale nodes list: verify that UDP ports 3478 and 41641 are open on the VPS side. Test from an external machine with nc -vzu headscale.your-domain.com 41641.
• Connection shows relay instead of direct: indirect connections via DERP occur when two nodes cannot reach each other directly (strict NAT, firewall). Run tailscale netcheck on both nodes to identify network constraints.
• MagicDNS does not resolve names: verify that magic_dns: true and base_domain are defined in the Headscale config, and that the client retrieved the new DNS configuration after reconnecting (tailscale status --self).
• Invalid TLS certificate at startup: the server_url in config.yaml must exactly match the certificate domain. A URL starting with http:// when nginx expects https:// triggers an infinite redirect loop.
• macOS or Windows clients do not see a --login-server option in the GUI: always use the terminal for migration. The Tailscale GUI does not allow changing the coordination server; only the command line supports this.

What Headscale does not replace