Self-Host Headscale on a VPS: Your Own Tailscale Control Server

Why self-host the control server

What self-hosted Headscale gives you

• Users and devices without a cap: no limit imposed by the software, no per-seat pricing — your mesh grows with your team, bounded only by the VPS resources.
• Official Tailscale clients everywhere: Linux, macOS, Windows, iOS, Android — no custom fork or alternative client required.
• WireGuard peer-to-peer tunnels: Headscale only handles key exchange and ACL distribution; all actual traffic flows directly over WireGuard between peers.
• Magic DNS: resolve every node in your mesh by hostname (laptop.mesh.yourdomain.com) without touching your public DNS.
• HuJSON policies: the same policy file format as Tailscale, with ACLs and Grants — define which users and devices can reach which services.
• DERP relay support: use Tailscale's public DERP map for NAT traversal, or enable Headscale's embedded DERP server to keep the relays in-house too.
• headscale API and CLI: create users, issue pre-auth keys and manage nodes programmatically.
• Registration without a tailscale.com account: your colleagues join the network with a key you generate, or through the OpenID Connect provider you already use (Keycloak, Authelia, Google Workspace…).
• Subnet routers, exit nodes, Taildrop and Tailscale SSH: Tailscale's base features are supported by the server.
• Under 50 MB of RAM at idle — runs comfortably on a 1 GB VPS alongside other workloads.

Requirements

Ports to open on the VPS

• TCP 443: mandatory. Clients register and receive the network map over HTTPS; it is the only port the coordination server cannot do without.
• TCP 80: only for Let's Encrypt HTTP-01 validation and the redirect to HTTPS.
• UDP 3478: only if you enable the embedded DERP server, which needs it for STUN. With Tailscale's public DERP map there is no need to open it.
• TCP 8080 (Headscale), 9090 (metrics) and 50443 (gRPC): keep them on 127.0.0.1. The reverse proxy talks to 8080 locally; never expose the gRPC admin interface unless you need it.

Deploy Headscale with Docker Compose

1. 01

   Write the Compose file

   The stack is a single service: the official docker.io/headscale/headscale:0.29.7 image, the latest stable release as of 7 November 2026, started with the serve command. Headscale keeps everything — keys, database, node records — in two host directories: the configuration, mounted read-only at /etc/headscale, and the data, at /var/lib/headscale. No external database or cache service is needed; SQLite is built in.

   mkdir -p /opt/headscale/config /opt/headscale/lib
   cat > /opt/headscale/compose.yaml <<'EOF'
   services:
     headscale:
       image: docker.io/headscale/headscale:0.29.7
       container_name: headscale
       restart: unless-stopped
       read_only: true
       tmpfs:
         - /var/run/headscale
       ports:
         - "127.0.0.1:8080:8080"
       volumes:
         - /opt/headscale/config:/etc/headscale:ro
         - /opt/headscale/lib:/var/lib/headscale
       command: serve
       healthcheck:
         test: ["CMD", "headscale", "health"]
   EOF

   The port is only published on 127.0.0.1: the reverse proxy is what faces the internet.

2. 02

   Generate the configuration

   Start from the example file of the exact version you deploy, then change only the keys below. server_url is the HTTPS URL your Tailscale clients will connect to; listen_addr must listen on 0.0.0.0 inside the container. The database is declared under database (type: sqlite). Only the noise key path remains to set: Headscale generates it on first start if the file does not exist.

   curl -Lo /opt/headscale/config/config.yaml \
     https://raw.githubusercontent.com/juanfont/headscale/v0.29.7/config-example.yaml

   server_url: https://vpn.yourdomain.com
   listen_addr: 0.0.0.0:8080
   noise:
     private_key_path: /var/lib/headscale/noise_private.key
   database:
     type: sqlite
     sqlite:
       path: /var/lib/headscale/db.sqlite
   dns:
     magic_dns: true
     base_domain: mesh.yourdomain.com

   On ServOrbit, the provisioning job writes config.yaml from your domain automatically.

3. 03

   Start the container and verify

   Run docker compose up -d from /opt/headscale. Headscale generates its noise key, then starts listening on port 8080. Check the health endpoint: curl -s http://127.0.0.1:8080/health should return {"status":"pass"}. The image is built on a distroless base with no shell, but the headscale CLI can be called directly: docker exec headscale headscale version confirms the running version, and docker logs --follow headscale shows the logs.

4. 04

   Create a user and generate an auth key

   Headscale organizes devices into 'users' (formerly called namespaces). Create one, then note its numeric identifier: the --user option of preauthkeys create expects that ID, not the name.

   docker exec headscale headscale users create myteam
   docker exec headscale headscale users list
   docker exec headscale headscale preauthkeys create --user 1 --reusable --expiration 24h

   Without --reusable the key works only once, and without --expiration it expires after one hour. Copy the printed key — you will use it when registering each device.

5. 05

   Register a device

   On any device with the official Tailscale client, point it at your Headscale instance: tailscale up --login-server https://vpn.yourdomain.com --authkey <your-preauth-key>. The device appears in Headscale's node list within seconds: docker exec headscale headscale nodes list. Without a key, the client opens a page showing an authentication ID; approve it on the server with docker exec headscale headscale auth register --user myteam --auth-id <AUTH_ID>. Once registered, devices reach each other by their mesh IP (100.64.x.y) or by magic DNS hostname.

6. 06

   Define access control policies

   As long as no policy is loaded, Headscale lets all traffic flow between nodes — fine for a small trusted team, not once developer laptops, contractors and production servers share the network. Create /opt/headscale/config/policy.hujson and declare it in config.yaml with policy.path: /etc/headscale/policy.hujson. Headscale uses the same HuJSON format as Tailscale: define user groups, tag devices as servers or workstations, and write rules stating which groups can reach which ports. The project recommends Grants over ACLs, which Tailscale considers legacy. Validate the file with headscale policy check --file <file>, then reload: the policy is only re-read on reload (docker kill --signal=HUP headscale, or systemctl reload headscale on a native install). Keep the file in a private Git repository to retain a history of access changes.

7. 07

   Logging in for the first time

   Headscale has no web interface and no account: it is the control server of your private network, driven from the command line. Over SSH: docker exec -it headscale headscale users create monuser, then the key with preauthkeys create --user <ID> --reusable --expiration 24h, and connect your machines with tailscale up --login-server https://<your-domain> --authkey <key>. The graphical apps can target a custom server too: on macOS, Option + click the Tailscale icon, open the Debug menu, then Custom Login Server; on iOS, Use custom coordination server in the login menu; on Android, Use an alternate server; on Windows, tailscale login --login-server in PowerShell.

Without Docker: the official .deb package

Install Headscale from the .deb package

1. 08

   Download and install the package

   Fetch the package for the version you want from the GitHub releases page, for your architecture (amd64 or arm64), and install it with apt, which resolves dependencies:

   HEADSCALE_VERSION="0.29.7"
   HEADSCALE_ARCH="amd64"
   wget --output-document=headscale.deb \
     "https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_${HEADSCALE_ARCH}.deb"
   sudo apt install ./headscale.deb

   Then check: headscale version should print 0.29.7.

2. 09

   Adapt the configuration

   The package puts the configuration in /etc/headscale/config.yaml and an up-to-date example in /usr/share/doc/headscale/examples/config-example.yaml. Change the same keys as for Docker (server_url, database, dns.base_domain), but keep listen_addr: 127.0.0.1:8080: the service runs on the host, and only the reverse proxy should reach it. Data lives in /var/lib/headscale.

3. 10

   Restart and check the service

   Restart the service so it re-reads the configuration, then check its state and logs:

   sudo systemctl restart headscale
   sudo systemctl status headscale
   sudo journalctl -u headscale -f

   The output should show Active: active (running). On first start, the most common errors are a server_url without the https:// scheme and a MagicDNS domain identical to the server's.

4. 11

   Use the CLI without being root

   The CLI talks to the service through the Unix socket /var/run/headscale/headscale.sock, which by default only the headscale user and root can access. Use sudo, run the commands as the headscale user, or add your account to the headscale group. Check access with headscale users list.

Serve Headscale over HTTPS behind Nginx

map $http_upgrade $connection_upgrade {
  default keep-alive;
  ''      close;
}

server {
  listen 80;
  server_name vpn.yourdomain.com;
  location = /generate_204 { return 204; }
  location / { return 301 https://$server_name$request_uri; }
}

server {
  listen 443 ssl;
  http2 on;
  server_name vpn.yourdomain.com;
  ssl_certificate     /etc/letsencrypt/live/vpn.yourdomain.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/vpn.yourdomain.com/privkey.pem;

  location / {
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    proxy_pass http://127.0.0.1:8080;
  }
}

trusted_proxies:
  - 127.0.0.1/32
  - ::1/128

Check that nodes can see each other

Check the mesh from a client

1. 12

   Read the network state

   On a registered node, run tailscale status. It lists peers with their mesh IP, name and link type: direct means the WireGuard tunnel is established with no intermediary, relay means it goes through a DERP relay — working, but with higher latency.

2. 13

   Test connectivity

   Take a peer's IP from tailscale status, then ping 100.64.0.2, or better tailscale ping <node-name>, which tells you whether the reply arrives directly or through a relay. If the peer is listed but does not answer, tailscale netcheck measures latency to each DERP region and reports filtered outbound UDP.

3. 14

   Test MagicDNS resolution

   With dns.magic_dns: true, every node answers to its short and full names: ping node-name or ping node-name.mesh.yourdomain.com. No public DNS record is needed for these internal names. If resolution fails, tailscale dns status shows the DNS configuration the client received from the server.

Use case: SSH between VPSs without exposing port 22

Restrict SSH to the mesh network

1. 15

   Find the mesh interface and address

   On each VPS, the Tailscale client creates the tailscale0 interface. tailscale ip -4 prints the machine's mesh address; note the production server's, for example 100.64.0.3.

2. 16

   Allow SSH only through tailscale0

   On the production VPS, allow SSH on the mesh interface before denying it elsewhere — UFW applies the first matching rule:

   ufw allow in on tailscale0 to any port 22 proto tcp
   ufw deny 22/tcp
   ufw enable
   ufw status verbose

   Port 22 is no longer reachable from the internet, but stays open to every mesh node your policy allows.

3. 17

   Connect through the mesh

   From the development VPS or your registered workstation, connect by IP or MagicDNS name: ssh [email protected] or ssh [email protected]. Everything travels inside the encrypted tunnel; then restrict in the Headscale policy which groups can reach this server's port 22.

Migrate a team already on Tailscale

Move clients over to Headscale

1. 18

   Carry over the access policy

   Copy your tailnet's policy file from the Access controls editor in the Tailscale console and start from it: the HuJSON format is the same. Check it with headscale policy check before the switch — some features, such as IP sets, are not supported, and only a subset of autogroups exists.

2. 19

   Log each client out, then back in

   On Linux or from the command line, chain the logout and the reconnection with a pre-auth key:

   tailscale logout
   tailscale up --login-server https://vpn.yourdomain.com --authkey <PREAUTHKEY>

   On macOS, iOS, Android and Windows, log the account out in the app, then add the custom server as described above.

3. 20

   Start with test machines

   Switch a test workstation and a test server first, check tailscale status and name resolution, then the development machines and, last, production. While some machines remain on the other side, the two networks cannot see each other: plan to move a service and its clients in the same window.

4. 21

   Close or downgrade the Tailscale account

   Once all nodes are migrated and verified, close the tailnet or move back to the Personal plan if you keep a personal use. Generate a fresh pre-auth key for future registrations rather than keeping the migration key forever.

Headscale vs Tailscale Cloud

Tailscale Personal, Tailscale Standard and Headscale

Scroll the table

What Headscale does not replace

Backups and upgrades

• Back up before every upgrade: Headscale applies its database migrations when the new version starts. Stop the service, copy the configuration and data, then start it again: cd /opt/headscale && docker compose stop, cp -aR /opt/headscale /opt/headscale.backup-$(date +%Y%m%d%H%M%S), docker compose up -d.
• The data directory holds db.sqlite and noise_private.key: losing that key changes the server's identity and forces every node to re-register. Copy it off the VPS as well, for example to object storage.
• Upgrade one version at a time: the project requires going through each stable minor version (for example 0.27, then 0.28, then 0.29), always at its latest patch, without skipping any.
• Read the release notes on GitHub before each upgrade: they flag breaking configuration changes. Then compare your config.yaml with the new version's example file.

Troubleshooting: the most common errors

• The client cannot register: check that https://vpn.yourdomain.com/health answers from outside, that server_url exactly matches the certificate's domain, and that the proxy passes the Upgrade and Connection headers.
• Connections in relay instead of direct: a strict NAT or a firewall blocks UDP between the two nodes. Run tailscale netcheck on both sides to see what is filtered; traffic still flows, through the DERP relays.
• Node listed as offline: the client reached the server but does not keep the session. Check systemctl status tailscaled and journalctl -u tailscaled on the node; a local firewall cutting outbound connections is the most common cause.
• Headscale refuses to start after an upgrade: a configuration key was renamed or removed. The log names it; refer to the example file of the installed version.
• MagicDNS does not resolve: check that dns.magic_dns is true and that dns.base_domain differs from the server_url domain, then reconnect the client so it fetches the new DNS configuration.