Headscale

Headscale

The gateway joins a self-hosted Headscale control server (0.26 or newer) the same way as hosted Tailscale; only the login server differs.

1. On the Headscale server create a user and a pre-auth key — preferably expiring, reusable only if needed, ideally tagged.
2. Web UI → Tailscale: set Login server, e.g. https://headscale.example.com (host, host:port and http://… also work).
3. Paste the pre-auth key in Auth key, choose a hostname, enable, save.
4. Approve advertised routes or the exit node on the server (headscale routes … or your admin UI); the device cannot see approval.
5. Status → Tailscale connected. A control connection alone is not proof that peers or services work.

Notes

• HTTPS certificates are validated against public CAs only; a private or self-signed CA is not accepted.
• The DERP map comes from your server; if it serves none, only direct paths work.
• Reported client version is an optional compatibility override and adds no capability.
• Tailnet lock is not supported: the device cannot sign its own node key.

Full guide: HEADSCALE.md.