Headscale 0.29.6

Option A: AWS Marketplace console

• Open the SecureAnyCloud Hardened WireGuard VPN & VPN, Proxy and Remote Access AMIs listing on AWS Marketplace. Choose View purchase options, then Subscribe. One subscription covers every version in the listing.
• Once the subscription is active, choose Launch your software.
• Choose Launch from EC2 Console. In Version, choose Headscale 0.29.6 on Ubuntu 24.04, then choose your Region.
• Pick an instance type and your key pair. We recommend m5.large. The software charge is $0.04 per vCPU per hour.
• Configure the security group to allow SSH (22) from your own IP address only. Allow HTTPS (443) and HTTP (80) from the networks your devices connect from (0.0.0.0/0 for laptops and phones that roam).
• Choose a subnet with internet access and a public IP. Leave the metadata defaults, because the image already requires IMDSv2. Then choose Launch.
• For a stable address, allocate an Elastic IP and associate it before the first boot finishes. Alternatively, run sudo headscale-set-server-url afterwards (Step 9).

Option B: AWS CLI

Run this on your own workstation. It creates a security group that allows SSH from your management address and HTTPS/HTTP from anywhere, then launches the instance.

Replace the AMI ID with the one shown for your Region on the Marketplace launch page. Replace the VPC, subnet, key pair and address range with your own:

SG=$(aws ec2 create-security-group --group-name headscale \
  --description "Headscale control server" --vpc-id vpc-0123456789abcdef0 \
  --query GroupId --output text)
aws ec2 authorize-security-group-ingress --group-id "$SG" --protocol tcp --port 22 --cidr <your-mgmt-cidr>
aws ec2 authorize-security-group-ingress --group-id "$SG" --protocol tcp --port 443 --cidr 0.0.0.0/0
aws ec2 authorize-security-group-ingress --group-id "$SG" --protocol tcp --port 80 --cidr 0.0.0.0/0
aws ec2 run-instances \
  --image-id ami-0123456789abcdef0 \
  --instance-type m5.large \
  --key-name my-key-pair \
  --security-group-ids "$SG" \
  --subnet-id subnet-0123456789abcdef0 \
  --associate-public-ip-address \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=headscale}]'

You do not need --metadata-options, because the AMI already requires IMDSv2.

Connect as ubuntu with the key pair you chose:

ssh -i ~/.ssh/my-key-pair.pem ubuntu@<public-ip>

First boot finishes within a minute of launch. It sets the server URL, creates the certificate, starts Headscale and nginx, creates the REST API key and proves that the key works.

The details are in /root/headscale-credentials.txt, which only root can read. This command shows everything except the API key:

sudo grep -v '^HEADSCALE_API_KEY=' /root/headscale-credentials.txt

# Headscale 0.29.6 (Tailscale control server) - generated on first boot by headscale-firstboot.service.
# Every value below is unique to this instance; nothing was baked into the image. Keep this file private.
# Control server URL: point Tailscale clients at it with tailscale up --login-server <URL>
# Change it (your own DNS name):
sudo headscale-set-server-url <dns-name> HEADSCALE_SERVER_URL=https://3.82.98.168 HEADSCALE_HOST=3.82.98.168
# REST API key (Authorization: Bearer <key>), valid until 2027-10-27. Manage keys:
sudo headscale apikeys list HEADSCALE_API_KEY_EXPIRES=2027-10-27
# The certificate is self-signed and unique to this instance (/etc/headscale/tls/headscale.crt); clients must
# trust it (see the guide) or you install a CA-signed certificate for your own DNS name. TLS_CERT_SHA256=84:FB:65:69:64:6A:35:35:97:64:9E:4A:84:A0:40:AD:29:49:13:19:00:EF:0A:24:F5:3A:3E:C6:3C:C2:75:AE
# Fingerprint (sha256 prefix) of this instance's Noise private key file (the key itself never leaves the server). HEADSCALE_NOISE_KEY_FINGERPRINT=44d2569cb61f7ffb # Self-test:
sudo headscale-selftest
# Guide: https://secureanycloud.com/stacks/headscale-0-29-6/

Your values differ from these. To print the API key when you need it for the REST API, run:

sudo grep '^HEADSCALE_API_KEY=' /root/headscale-credentials.txt | cut -d= -f2-

Check that both services are active, that Headscale listens on loopback only, and that nginx listens on ports 80 and 443:

systemctl is-active headscale.service nginx.service headscale version | head -1 sudo ss -Htlnp | awk '{print $4, $6}' | grep -E ':(22|80|443|8080|9090) ' | sed -E 's/,pid=[0-9]+,fd=[0-9]+//g' | sort -u

active active headscale version v0.29.6+dirty 0.0.0.0:22 users:(("sshd"),("systemd")) 0.0.0.0:443 users:(("nginx"),("nginx"),("nginx")) 0.0.0.0:80 users:(("nginx"),("nginx"),("nginx")) 127.0.0.1:8080 users:(("headscale")) 127.0.0.1:9090 users:(("headscale")) [::]:22 users:(("sshd"),("systemd")) [::]:443 users:(("nginx"),("nginx"),("nginx")) [::]:80 users:(("nginx"),("nginx"),("nginx"))

The +dirty suffix is part of upstream's own version string for the 0.29.6 release build. The binary is the unmodified official release.

The shipped self-test checks the services, the loopback listener and the server URL. It also proves the REST API over HTTPS: the API answers 401 without a key and for a key with the right ID but the wrong secret, and 200 with the key in the credentials file. The self-test prints no secret:

sudo headscale-selftest

SELFTEST_OK headscale+nginx active; loopback 127.0.0.1:8080; health 200; REST API 401 anonymous/wrong, 200 per-instance key; server_url https://3.82.98.168

Tailscale clients talk to a control server only over HTTPS that they trust. The certificate is unique to your instance. Check its fingerprint against TLS_CERT_SHA256 from Step 2:

sudo openssl x509 -in /etc/headscale/tls/headscale.crt -noout -subject -enddate -ext subjectAltName
sudo openssl x509 -in /etc/headscale/tls/headscale.crt -noout -fingerprint -sha256

subject=O = sac, CN = 3.82.98.168 notAfter=Oct 24 11:12:25 2036 GMT X509v3 Subject Alternative Name: IP Address:127.0.0.1, IP Address:3.82.98.168, DNS:ec2-3-82-98-168.compute-1.amazonaws.com sha256 Fingerprint=84:FB:65:69:64:6A:35:35:97:64:9E:4A:84:A0:40:AD:29:49:13:19:00:EF:0A:24:F5:3A:3E:C6:3C:C2:75:AE

Copy the certificate to your workstation and add it to each device's trusted roots:

ssh -i ~/.ssh/my-key-pair.pem ubuntu@<public-ip> 'sudo cat /etc/headscale/tls/headscale.crt' > headscale.crt
# Linux (Debian/Ubuntu):
sudo cp headscale.crt /usr/local/share/ca-certificates/headscale.crt && sudo update-ca-certificates
# macOS:
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain headscale.crt
# Windows (elevated PowerShell): Import-Certificate -FilePath headscale.crt -CertStoreLocation Cert:\LocalMachine\Root

For phones and for large numbers of devices, a certificate from a public CA for your own DNS name is easier (Step 9).

Every device belongs to a Headscale user. Create a user, then create a pre-auth key for it. The example key is reusable for 24 hours. Leave out --reusable for a single-use key.

Headscale prints the key once, so treat it like a password.

sudo headscale users create alice
sudo headscale users list
sudo headscale preauthkeys create --user 1 --reusable --expiration 24h

User created ID | Name | Username | Email | Created 1 | | alice | | 2026-10-27 11:02:02 hskey-auth-<prefix>-<secret>

Use the numeric ID from users list with --user. The command sudo headscale preauthkeys list shows every key with its ID, but never the secret part again. To revoke a key, run sudo headscale preauthkeys expire --id <id>.

Install the official Tailscale client on the device (tailscale.com/download) and make sure it trusts the certificate (Step 5). Then log in to your server with the pre-auth key:

sudo tailscale up --login-server https://<HEADSCALE_HOST> --auth-key hskey-auth-<prefix>-<secret>

On a shared machine, put the key in a file that only you can read and use --auth-key file:/path/to/key, so the key is not on the command line.

Without --auth-key, the client prints a registration link. Open the link to see the command, then approve the device on the server with sudo headscale nodes register --user alice --key <registration-id>.

The Tailscale apps for Windows, macOS, iOS and Android have a setting for a custom coordination server (a "custom login server" / "alternate coordination server URL"). Enter https://<HEADSCALE_HOST> there.

On the server, the device appears with its 100.64.x.y address:

sudo headscale nodes list

ID | Hostname | Name | MachineKey | NodeKey | User | Tags | IP addresses | Ephemeral | Last seen | Expiration | Connected | Expired

On a new instance the list is empty.

SecureAnyCloud tested registration on the image with the official Tailscale 1.104.2 client. A wrong pre-auth key is refused, and a valid one registers the device with a 100.64.0.0/10 address and brings it online.

The REST API is at https://<HEADSCALE_HOST>/api/v1/ and needs the API key as a bearer token.

This example reads the key from the credentials file and passes it to curl on standard input, so the key never appears on a command line. Without the key, the API answers 401:

H=$(sudo sed -n 's/^HEADSCALE_HOST=//p' /root/headscale-credentials.txt)
sudo cat /etc/headscale/tls/headscale.crt > /tmp/headscale.crt
sudo sed -n 's/^HEADSCALE_API_KEY=//p' /root/headscale-credentials.txt \
  | sed 's/^/header = "Authorization: Bearer /; s/$/"/' \
  | curl -sS -K - --cacert /tmp/headscale.crt --resolve "$H:443:127.0.0.1" "https://$H/api/v1/node" echo curl -sS -o /dev/null -w 'without the key: %{http_code}\n' --cacert /tmp/headscale.crt --resolve "$H:443:127.0.0.1" "https://$H/api/v1/node" rm -f /tmp/headscale.crt

{"nodes":[]} without the key: 401

From your workstation, call https://<HEADSCALE_HOST>/api/v1/... with the header Authorization: Bearer <api-key>.

Manage keys with sudo headscale apikeys list, sudo headscale apikeys create --expiration 90d and sudo headscale apikeys expire --prefix <prefix>. The key in the credentials file expires on the date shown in Step 2.

First boot fixes the server URL to the instance's public IPv4. To use a DNS name instead, point an A record at the instance (an Elastic IP keeps the address stable), then run:

sudo headscale-set-server-url headscale.example.com

SET_SERVER_URL_OK server_url=https://headscale.example.com

The command rewrites server_url, issues a new self-signed certificate for the name, restarts Headscale and reloads nginx.

With no argument, the command returns the server to the instance's current address. Use that after a stop and start changes the public IP; the login banner warns you when it has. Devices registered under the old URL log in again with tailscale up --login-server https://<new-name> --force-reauth.

To replace the self-signed certificate with one from a public CA for that name, put the certificate chain and key in place and reload nginx:

sudo install -m 0644 fullchain.pem /etc/headscale/tls/headscale.crt
sudo install -m 0600 privkey.pem /etc/headscale/tls/headscale.key
sudo systemctl reload nginx

Devices then need no extra trust step. Running headscale-set-server-url again issues a new self-signed certificate over the CA certificate.

With no policy set, every registered device can reach every other registered device. To restrict that, write a policy in Tailscale's HuJSON format and load it. Headscale validates the policy and applies it to every device at once.

This example lets each user reach only their own devices:

cat > policy.hujson <<'EOF' { "acls": [ { "action": "accept", "src": ["autogroup:member"], "dst": ["autogroup:self:*"] } ] } EOF
sudo headscale policy set -f policy.hujson
sudo headscale policy get

Until you set a policy, sudo headscale policy get reports that no policy is found. Headscale's policy reference is at headscale.net.

The configuration file is /etc/headscale/config.yaml, which root and the headscale group can read. This command shows the settings that SecureAnyCloud chose:

sudo grep -nE '^(server_url|listen_addr|metrics_listen_addr|grpc_allow_insecure|trusted_proxies)|^ (magic_dns|base_domain|override_local_dns)|^ enabled' /etc/headscale/config.yaml

6:server_url: https://3.82.98.168 9:listen_addr: 127.0.0.1:8080 10:metrics_listen_addr: 127.0.0.1:9090 14:grpc_allow_insecure: false 18:trusted_proxies: 35: enabled: false 71: magic_dns: true 72: base_domain: headscale.internal 74: override_local_dns: false

To push name servers to your devices, list them under dns.nameservers.global. Set override_local_dns: true to make devices use them for every lookup. Then restart Headscale with sudo systemctl restart headscale.

Keep listen_addr on loopback. The start check refuses anything else, because nginx is the only listener meant to face the network. Change server_url with headscale-set-server-url (Step 9), not by hand.

For relayed traffic, devices use Tailscale's public DERP servers. To run your own relay, run Tailscale's derper on a separate instance and list it in a DERP map file under derp.paths. The embedded relay stays off on this image.

headscale.service runs only when first boot's ready marker exists. Every start runs the guard as root first, and both services are denied access to the metadata service:

systemctl cat headscale.service | grep -E '^(ConditionPathExists|ExecStartPre|ExecStart|User|ProtectSystem|CapabilityBoundingSet)='
systemctl show -p IPAddressDeny headscale.service nginx.service
sudo stat -c '%a %U:%G %n' /root/headscale-credentials.txt /etc/headscale/config.yaml /etc/headscale/tls/headscale.key /var/lib/headscale

ConditionPathExists=/var/lib/sac/data/headscale-bootstrap-ready User=headscale ExecStartPre=+/usr/local/sbin/headscale-guard ExecStart=/usr/bin/headscale serve ProtectSystem=strict CapabilityBoundingSet= IPAddressDeny=168.63.129.16/32 fd00:ec2::254/128 169.254.169.254/32 IPAddressDeny=168.63.129.16/32 fd00:ec2::254/128 169.254.169.254/32 600 root:root /root/headscale-credentials.txt 640 root:headscale /etc/headscale/config.yaml 600 root:root /etc/headscale/tls/headscale.key 750 headscale:headscale /var/lib/headscale

Port 80 only redirects to the configured server URL and answers a health probe at /healthz:

curl -sS -o /dev/null -w '%{http_code} %{redirect_url}\n' http://127.0.0.1/
curl -sS http://127.0.0.1/healthz

301 https://3.82.98.168/ ok

journalctl -u headscale shows the server log, which covers requests, registrations and errors. The lines below are the self-test's refused probes and its accepted request. Headscale logs a refused key by reason only, never by value.

/var/log/nginx/ holds the HTTPS access log. Registration links are not logged:

sudo journalctl -u headscale --no-pager -n 5 -o cat | cut -c1-140

2026-10-27T11:12:57Z ERR ../../../home/runner/work/headscale/headscale/hscontrol/app.go:486 > missing "Bearer " prefix in "Authorization" he 2026-10-27T11:12:57Z INF http request bytes=12 elapsed=0.168616 method=GET path=/api/v1/apikey proto=HTTP/1.1 remote=127.0.0.1 status=401 2026-10-27T11:12:57Z INF ../../../home/runner/work/headscale/headscale/hscontrol/app.go:497 > failed to validate token error="invalid API ke 2026-10-27T11:12:57Z INF http request bytes=12 elapsed=70.147782 method=GET path=/api/v1/apikey proto=HTTP/1.1 remote=127.0.0.1 status=401 2026-10-27T11:12:57Z INF http request bytes=12 elapsed=72.186011 method=GET path=/api/v1/node proto=HTTP/1.1 remote=127.0.0.1 status=200

Backup: Everything Headscale knows is in /var/lib/headscale, which holds the SQLite database and the Noise private key. Stop the service, copy the directory, and start the service again. Keep the copy as private as the server itself. EBS snapshots of the instance also work.

Upgrades: Ubuntu security updates install automatically. Headscale is held at 0.29.6. To upgrade, follow these steps:

• Read the upgrade notes.
• Back up /var/lib/headscale.
• Download the new headscale_<version>_linux_amd64.deb from the releases page.
• Check its SHA-256 against the release's checksums.txt.
• Run sudo apt-mark unhold headscale.
• Run sudo apt install ./headscale_<version>_linux_amd64.deb.
• Run sudo apt-mark hold headscale.
• Run sudo systemctl restart headscale.

SecureAnyCloud also ships updated versions as new versions of this listing.

• Keep SSH open only to your management addresses.
• Use an Elastic IP or a DNS name, so the server URL that your devices know never changes under them.
• Prefer single-use or short-lived pre-auth keys, and expire keys that you no longer need (sudo headscale preauthkeys expire --id <id>).
• Set an access policy (Step 10) once you have more than a handful of devices or more than one user.
• Rotate the REST API key before it expires, and expire any key that may have been exposed (sudo headscale apikeys expire --prefix <prefix>).
• Back up /var/lib/headscale regularly and keep the backup private. Whoever has the Noise key and database can impersonate your control server.