Headscale is a free reimplementation of Tailscale’s control plane, active since 2020. With version 0.25 it has reached a maturity level where it can be recommended without large caveats for workloads that do not need the full commercial ecosystem. This post is a practical guide from the point of view of someone managing a mesh of five to a hundred nodes who is weighing whether to leave the commercial platform.

Key takeaways

  • Headscale reimplements only Tailscale’s control plane; official clients connect without modification.

  • Version 0.25.1 stabilises full ACLs in Tailscale’s HuJSON format, advertised routes and DNS resolution in large meshes.

  • Deployment needs a Go binary, a database (SQLite or PostgreSQL) and a TLS-terminating reverse proxy.

  • SSO integration, Funnel and the analytics ecosystem are where the commercial platform remains superior.

  • For teams with full control-plane ownership requirements (public sector, healthcare, defence), Headscale is the most solid option.

What Headscale is and is not

Tailscale has two cleanly separable parts:

  • Clients (tailscale, tailscaled): free, installed on each node.

  • Control plane: the commercial server managing identities, keys, ACLs, discovery and node coordination.

The data plane (actual WireGuard tunnels) is direct between nodes and does not traverse the Tailscale cloud.

Headscale, started by Juan Font, reimplements the control plane. Official Tailscale clients connect to a Headscale server instead of the commercial server with no changes on the client side. What Headscale does not deliver is the commercial ecosystem: no bundled SaaS dashboard, no turnkey enterprise SSO with Okta or Entra, no extras like Funnel or MagicDNS at full parity.

2025 maturity: what changed

Version 0.24 brought more complete ACL support with Tailscale’s policy format, letting you migrate existing rules without rewriting them. Version 0.25 stabilises the implementation and fixes issues with advertised routes and DNS resolution in large meshes. The 0.25.1 point release is the recommended production version.

Third-party admin UIs also cover the SaaS gap. Headscale-ui and Headscale Admin offer user, preauthkey and ACL management from the browser, not as polished as the commercial dashboard, but covering 80 % of what an admin needs.

Practical architecture

The main component is a Go binary that needs:

  • A database (SQLite or PostgreSQL).

  • A reverse proxy with TLS in front (Traefik or Caddy).

  • A YAML configuration file with public URL, DERP map, DNS directives and ACL policies.

The internal architecture has three conceptual pieces. First, the device and user map: each device belongs to a user and has WireGuard public keys the server signs. Second, the ACLs describing which devices can talk to which on what ports. Third, the coordinator keeping clients informed of topology changes.

Clients connect over HTTPS and maintain a long-lived open connection. Actual node traffic is direct WireGuard whenever possible, with DERP relay only when strict NAT forbids it. Headscale setup pairs naturally with the Traefik self-hosted pattern we’ve covered elsewhere.

Tailscale ACLs in Headscale

Tailscale’s policy language, based on HuJSON, describes users, groups, device tags and allow rules. Headscale 0.24 and above supports the latest syntax almost entirely, with minor documented exceptions.

A typical ACL defines groups (admin, dev, operations), tags devices (tag:server, tag:laptop) and sets rules like "members of admin can reach tag:server on ports 22 and 443". It is an identity-over-network model that beats the usual IP rules.

The part that needs most care is preauthkeys, server-issued tokens that let a device register automatically. Issuing short-lived, scope-restricted keys is good hygiene.

Where it is still less convenient than Tailscale

Not a total equal. Four areas where the commercial platform remains better:

  • SSO integration. Tailscale wires up Okta, Google Workspace, Entra or GitHub with a wizard; Headscale requires manual OpenID Connect setup.

  • Funnel. No equivalent to the service exposing internal services to the internet with automatic TLS.

  • Analytics and audit. Headscale exposes Prometheus metrics and structured logs, but you must build the equivalent dashboard yourself.

  • Support. No SLA; active repo issues and a reasonable community, but no commercial ticket.

My read

For a technical team that already self-hosts and is comfortable with PostgreSQL, a reverse proxy and automated TLS, Headscale in 2025 is a serious alternative without a big asterisk. It is especially useful when compliance requires full control-plane ownership, or when subscription cost is hard to justify.

Where I would stay on commercial Tailscale is in companies where team time costs more than the subscription, where SSO and Funnel are daily business, and where there is budget to outsource the operation. The choice is not ideological, it is operational.

The combination of containerd 2.0 in production with Headscale’s network segmentation forms a coherent isolation stack for small multi-tenant environments.

Frequently asked questions

Do I need special clients to use Headscale?

No. Headscale reimplements only Tailscale's control plane, so the official clients (tailscale, tailscaled) connect to a Headscale server instead of the commercial server with no changes on the client side. The data plane is still direct WireGuard between nodes whenever possible, with DERP relay only when strict NAT forbids it. Clients connect over HTTPS and keep a long-lived open connection.

What do I need to deploy to run a Headscale server?

A Go binary, a database (SQLite or PostgreSQL) and a TLS-terminating reverse proxy in front such as Traefik or Caddy. Plus a YAML configuration file with the public URL, DERP map, DNS directives and ACL policies. The recommended production version is 0.25.1. Third-party UIs like Headscale-ui and Headscale Admin let you manage users, preauthkeys and ACLs from the browser.

Can I reuse my Tailscale ACLs in Headscale?

Yes. Since version 0.24 Headscale supports Tailscale's HuJSON policy format almost entirely, with minor documented exceptions. You can migrate existing rules without rewriting them: groups such as admin or dev, tags such as tag:server, and per-port rules. What remains less convenient than the commercial platform is SSO integration, which requires manual OpenID Connect setup, the lack of Funnel, and analytics.