Headscale is an open-source, self-hosted implementation of the Tailscale control server, written in Go and maintained by Juan Font and Kristoffer Dalby. In a Tailscale-style mesh the clients talk to each other directly over WireGuard, but they need a control server to exchange public keys, hand out the virtual IP addresses and decide who is allowed to reach whom. Tailscale’s clients are open source; that coordination service is not. Headscale replaces it with a server you run yourself.

Point any official Tailscale client at your own server with --login-server and your machines join a tailnet whose keys, user accounts and ACL policy never leave your infrastructure. The project deliberately keeps a narrow scope — a single tailnet, aimed at self-hosters, homelabs and small open-source organisations rather than multi-tenant enterprise deployments. It ships as a single static binary, keeps state in SQLite or PostgreSQL, and is developed in the open with a release roughly every few weeks (v0.29.5, October 2026).

Key Features

• Base Tailscale compatibility — the overlay network, NAT traversal and WireGuard key exchange work exactly as they do against the hosted control server, so existing clients keep working unchanged.
• Node registration — interactive web authentication or pre-authentication keys (single-use or reusable, with an expiry), so headless servers can join without a browser.
• Single sign-on over OIDC — register nodes through your own identity provider and optionally refresh user profiles from it.
• DNS and MagicDNS — automatic node names, global and restricted (split) nameservers, search domains, plus extra DNS records that Headscale adds beyond what Tailscale offers.
• ACL policies and grants — a HuJSON policy covering ACLs, grants, autogroups, node attributes and auto-approvers for subnet routers and exit nodes, with policy tests and sshTests to verify the rules you wrote.
• Tailscale SSH — SSH access governed by the same policy file instead of per-host keys.
• Subnet routers and exit nodes — advertise routes from a home or office LAN, or route all traffic through a chosen node, with route filtering via grants.
• Tags and ephemeral nodes — tag-based identities for servers and CI jobs, and nodes that register automatically only while they exist.
• Embedded DERP server — run your own relay between machines that cannot connect directly, so no connection metadata leaves your network. External DERP maps can be used too, and peer relays are supported.
• Dual stack — IPv4 and IPv6 addressing for every node.
• File sharing — Taildrop and Taildrive for sending and sharing files between your own machines.
• CLI, gRPC API and API keys — administer users, nodes, routes, pre-auth keys and the policy from the command line or programmatically over gRPC. The screenshot above is a real Headscale 0.29.5 server with users, a reusable pre-auth key and an API key created through the CLI.
• Observability — Prometheus metrics endpoint, structured logging and a headscale health check for your monitoring stack.
• SQLite or PostgreSQL — start with a single SQLite file, move to PostgreSQL for busier deployments.

Why Use It

Headscale exists for people who want the convenience of a WireGuard mesh without handing the control plane to a third party. Because the coordination server is the component that knows every node, its keys and its addresses, self-hosting it keeps that map inside your own network — the traffic itself was always end-to-end encrypted, but the metadata is worth owning too.

It is genuinely open: BSD 3-Clause, no open-core edition and no feature gating behind a subscription, with a single-binary deployment that fits a small VPS or a spare machine. Development is active and the docs are thorough, covering registration, DNS, routes, DERP and policy. The honest limits: it is not a complete reimplementation of every Tailscale feature — Funnel, Serve and network flow logs are still in progress — the policy file will not accept OIDC groups in ACLs, and the project targets one tailnet, so it is not a drop-in replacement for the hosted service in a large organisation. The maintainers also advise against running it behind a reverse proxy or in a container in production.

Use Cases

• Homelab mesh — join a NAS, a couple of servers and your workstations into one private network with stable names, without opening ports.
• Personal and family devices — phone, laptop and desktop that reach each other from anywhere, with access rules you control.
• Cloud and VPS fleets — connect machines across providers to each other and back to the LAN through a subnet router.
• Remote access to a home network — a subnet router advertises the local LAN; an exit node gives you a trusted egress from public Wi-Fi.
• Ephemeral CI runners — tag-based, auto-expiring nodes that join the tailnet for a build and vanish afterwards.
• Replacing the hosted control plane — keep the official clients while owning the account, key and policy data behind them.

Platforms

Server: Linux (x86_64, arm64), FreeBSD, macOS and Windows builds, plus a Docker image — although the project advises against reverse proxies and container deployments for anything serious. Clients: the last 10 releases of the official Tailscale client on Linux, Windows, macOS, iOS, tvOS, Android, OpenBSD and FreeBSD (Windows, Android and Apple platforms need a little extra configuration described in the docs).

Licence

BSD 3-Clause — fully open source, with no commercial edition or paid tier. The licence is in the repository: LICENSE.

Website

headscale.net — documentation for the stable and development versions, plus github.com/juanfont/headscale for the source and releases.

Related

• WireGuard — the VPN protocol that carries every packet in the mesh
• Networking & Virtualization — more self-hosted network tools in the directory