Headscale

What Headscale is

Headscale is a free, open-source control server that you run yourself as an alternative control plane for a Tailscale network. It is designed for self-hosters and hobbyists managing one tailnet for personal use or a small open-source organisation. Its network tools include node registration, MagicDNS and split DNS, Taildrop, tags, subnet routers, exit nodes, IPv4 and IPv6, and embedded DERP. Administrators can use access control lists, API-based ACL management, some autogroups, automatic approvers, and Tailscale SSH. Node registration can use OpenID Connect, though OIDC groups are not available for ACL rules.

Clients are supported on Linux, OpenBSD, FreeBSD, Windows, Android, macOS, and iOS; tvOS is also included in the supported-platform list. Official installation routes are platform binaries and DEB packages for Debian and Ubuntu, with DEB support for Ubuntu 22.04 or later and Debian 12 or later. Headscale exposes HTTP REST and gRPC interfaces for web interfaces, remote control, and custom integrations, each requiring an API key. Its web service can use TLS with configured certificates or automatic certificate acquisition through Let's Encrypt. The project recommends SQLite; PostgreSQL is supported but in maintenance mode. Docker deployments are not officially supported. The project directs users to Discord for community support and cautions that it is not enterprise software: many nodes with frequent network changes can keep resource use high and cause it to fall behind.

Who it suits

Headscale suits self-hosters and hobbyists who want to operate a single tailnet for personal use or a small open-source organisation. It is also relevant to teams needing self-hosted control with API access, ACLs, and clients across the listed operating systems.

Limits

The free Headscale plan is an open-source self-hosted control server for a single tailnet. It is intended for personal use or a small open-source organisation, and the project warns that many nodes with frequent network changes can keep resource use high and cause it to fall behind.

Getting started

1. Visit the Headscale website and choose an official release route.
2. Install a platform binary or a supported DEB package; DEB support covers Ubuntu 22.04 or later and Debian 12 or later.
3. Configure the service and its database; SQLite is recommended, while PostgreSQL is supported in maintenance mode.
4. Set up TLS with a configured certificate or automatic acquisition through Let's Encrypt, if needed.
5. Register nodes using a supported client operating system; OpenID Connect is available for node registration.
6. Use the REST or gRPC interface with an API key for web interfaces, remote control, or custom integrations.

Verdict

Choose Headscale if you want a free, self-hosted control server for a personal or small-organisation tailnet, with network tools and API interfaces. Look elsewhere if you need enterprise-oriented scaling or an officially supported Docker deployment.