SEC.01

The playbook

The run starts read-only: the recon probes decide what happens next. The steps that follow are adapted to the distribution and state found — a real machine is rarely clean.

1. 01reconHeadscale already present? version
2. 02reconservice active? existing config (server_url, listen_addr)?
3. 03reconports 8080/9090/50443 free? 80/443 held by a reverse proxy?
4. 04reconreverse proxy present (Caddy or Nginx) for TLS
5. 05reconDebian >= 12 or Ubuntu >= 22.04, architecture
6. 06actThe domain points to this serververify
7. 07actDownload the official packageverify
8. 08actInstall Headscaleverify
9. 09actConfigure server_urlverify
10. 10actEnableverify
11. 11actTLS reverse proxyverify
12. 12actCreate the first userverify

SEC.02

What it verifies

Each step ships its own check. The run only moves on when the check passes, so what the recipe reports as done is what is actually on the server.

1. 01verifyThe domain points to this serverVerified bygetent ahostsv4 ${domain} | head -1; curl -4fsS https://api.ipify.org
2. 02verifyDownload the official packageVerified bydpkg-deb -f /tmp/headscale.deb Version
3. 03verifyInstall HeadscaleVerified byheadscale version
4. 04verifyConfigure server_urlVerified byheadscale configtest && grep -c "^server_url: https://${domain}" /etc/headscale/config.yaml
5. 05verifyEnableVerified bysystemctl is-active headscale && curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8080/health
6. 06verifyTLS reverse proxyVerified bycurl -s -o /dev/null -w '%{http_code}' https://${domain}/health
7. 07verifyCreate the first userVerified byheadscale users list | grep -cw ${hs_user}

SEC.03

Guardrails

Non-negotiable instructions the run must respect, whatever it finds on the server.

SEC.04

Variables

What you choose before launching — the recipe fills in the rest.

SEC.05

How a recipe runs in Servor

Servor is zero-knowledge: the platform cannot execute anything on its own. When you launch this recipe, a run reads the reconnaissance, plans the steps and asks for your approval. Each approved command is signed by your browser — with a key the server never sees — then relayed verbatim to the agent, which verifies the signature locally before executing.

SEC.06

Deploy on Servor button

Maintain Headscale or a project that needs it? Put this button in your README or on your site: one click and your users install it on their own server.

SEC.07

More networking recipes

1. 01TailscaleTailscale mesh VPN: auth key or login link, without touching the server DNS.
2. 02WireGuardWireGuard VPN server + a first client, without touching routing. Destructive: network interface.
3. 03Pi-holePi-hole v6 (DNS + ad blocking) in a container, on the chosen IP. Destructive when listening on 0.0.0.0 (port 53).
4. 04AdGuard HomeAdGuard Home filtering DNS, local UI. Destructive: may free port 53.
5. 05OpenVPNOpenVPN server via the road-warrior script (angristan), first client created. Destructive: network.