Analytics cookies only (Google Analytics, PostHog). No ad networks, no cross-site tracking. See our privacy policy.
Self-host Headscale
updated Jul 2026deployed by usprices checked · Jul 2026Install verified on Ubuntu 26.04 · Nov 2026 · how we test
We earn commissions when you shop through the links below. Full disclosure →
An open-source, self-hosted implementation of the Tailscale control server — run your own coordination plane for a private WireGuard mesh and keep using the official Tailscale clients, without depending on Tailscale's hosted service.
Pick Headscale when you already like the Tailscale clients and the only thing you refuse to rent is the coordination server: it is a BSD-3-Clause Go binary with SQLite by default that implements a single tailnet — MagicDNS, ACLs and grants, subnet routers and exit nodes, an embedded DERP relay and OIDC registration are all on the features list — and the README scopes it at "personal use, or a small open-source organisation". There is no built-in web interface; the admin surface is the `headscale` CLI, with community UIs listed in the docs. If you want a mesh product with its own dashboard and users, that is NetBird.
Paid link — we earn a commission if you shop through it.
Install
Run these commands on your server:
# Headscale — control server only (no web UI); needs a config.yaml + TLS on 443mkdir -p ./headscale/config ./headscale/data && cd ./headscale# the example config must match the image version — main's copy has moved on and the container refuses to start on itcurl -fsSL -o config/config.yaml https://raw.githubusercontent.com/juanfont/headscale/v0.29.7/config-example.yaml# publish the port: listen_addr defaults to 127.0.0.1:8080, unreachable from outside the containersed -i 's|^listen_addr: 127.0.0.1:8080|listen_addr: 0.0.0.0:8080|' config/config.yaml# still edit server_url to your https:// URL before real use (it defaults to http://127.0.0.1:8080)docker run --name headscale -d -p 443:8080 \ -v $(pwd)/config:/etc/headscale -v $(pwd)/data:/var/lib/headscale \ headscale/headscale:v0.29.7 serve
Headscale is small and well documented, but its maintainers are unusually explicit about what they do and do not support:
non-negotiable"Please note that we do not support nor encourage the use of reverse proxies and container to run Headscale" (README). The FAQ adds that container images are built "for convenience" but Docker deployment is not officially supported, and the container page is marked community documentation "not verified by headscale developers". Our snippet runs it in Docker — expect community-level help, in the Discord docker-issues channel.
non-negotiableUpgrade one minor at a time. The FAQ's rule is "0.26.0 → 0.27.1 → 0.28.0" without skipping, always on the latest patch, and to read the changelog first: v0.29.3 (July 2026, the current release as of September 2026) needs Tailscale clients >= v1.80.0, and the unreleased 0.30 changelog already removes the gRPC API and changes CLI output shapes.
non-negotiableTLS on 443 is effectively mandatory: the requirements page says the Tailscale client "assumes HTTPS on port 443 in certain situations" and strongly recommends it for production. Our snippet publishes 443 to the container's plain-HTTP 8080, so either set tls_letsencrypt_hostname (needs port 80 free for HTTP-01, or TLS-ALPN-01 on 443) or tls_cert_path / tls_key_path — and the certificate must contain the full chain or the Android client rejects it.
non-negotiableIt is not built for churn. The FAQ says performance "is not part of the consideration": every network change recomputes a map for every node, so it "can likely handle 100s of devices (maybe more), if there is little to no change", while "many nodes with frequent changes will cause the resource usage to remain constantly high." Running Headscale on a machine that is itself in the tailnet is "not supported", and PostgreSQL is in "maintenance mode" — stay on SQLite.
non-negotiableThe 256 MB floor is our estimate; the requirements page publishes no RAM figure.
Headscale used 12 MB of RAM at idle on GCP e2-standard-2 · Ubuntu 26.04 LTS · Docker 29.9.3 (first boot, measured Nov 2026). We list a minimum of 256 MB.
Is the Headscale install snippet verified?
The Headscale install snippet is marked verified on Ubuntu 26.04 (Nov 2026).