Headplane finally gives Headscale, the self-hosted Tailscale control server, a web UI
Headplane, spotlighted by selfh.st on October 9, 2026, adds to Headscale — the open-source reimplementation of Tailscale’s control server — a web interface with OIDC single sign-on, remote SSH, and tailnet settings management. It is the missing piece for self-hosting your own mesh network without giving up usability.
October 9, 2026. The Self-Host Weekly newsletter spotlights Headplane, an administration interface for Headscale. Since 2020. Headscale has offered an open-source reimplementation of Tailscale’s control server — a way to self-host your own WireGuard “tailnet” — but only from the command line. Today. Headplane fills that gap with a web UI, OIDC single sign-on, and remote SSH. Why it matters: the promise of Tailscale without its cloud dependency is now within reach of people who do not want to administer their mesh through a headscale CLI.
Headscale was powerful, but CLI-only
To understand what Headplane adds, recall what Headscale is. Tailscale is a mesh network built on WireGuard: every machine joins an encrypted “tailnet” and can reach the others as if on a LAN, without exposing ports. Its sensitive point, for self-hosting purists, is the control server — the component that distributes keys, enforces ACLs, and orchestrates the mesh — and in Tailscale it is closed and hosted.
Headscale reimplements that control server as open source. Install it on your own machine and you recover full control of the control plane: the ACLs, the keys, the DNS, everything is yours. The price, until now, was ergonomics: no interface, a YAML configuration, and headscale commands for every operation. That friction is exactly what discouraged a slice of self-hosters accustomed to dashboards like Tailscale or Netmaker.
What Headplane actually brings
Headplane is a full-featured admin interface that plugs into an existing Headscale. Its positioning is simple: it does not replace the control plane; it adds the management layer that was missing.
The advertised features add up to a real cockpit. The tailnet overview exposes the state of the machines and the network for each node. Settings management surfaces what was buried in the Headscale configuration file: DNS servers, records, authentication controls, network parameters. Single sign-on delegates authentication to an OpenID Connect provider — Google Workspace, Azure/Entra ID, Okta, or any compatible one. Finally, remote web SSH opens a terminal to tailnet machines straight from the browser, riding on Tailscale SSH.
It deploys via Docker (recommended), native mode on a server, or limited mode for a quick test. The official image is ghcr.io/tale/headplane, and the UI is served at http://localhost:3000/admin.
The Docker deployment, step by step
The starting point is Headscale 0.26.0 or newer, already running. Headplane installs on top through a simple compose.yaml:
services:
headplane:
image: ghcr.io/tale/headplane:latest
container_name: headplane
restart: unless-stopped
ports:
- "3000:3000"
volumes:
- "./config.yaml:/etc/headplane/config.yaml"
- "./headplane-data:/var/lib/headplane"The first login requires a Headscale API key, generated on the server side:
# Adjust the expiration to your needs
headscale apikeys create --expiration 90dTo enable advanced features — notably network management from the UI — Headplane must read and write the Headscale configuration file and access the Docker socket. Both services then run in the same Docker environment, with a shared config volume and the socket mounted read-only:
services:
headplane:
image: ghcr.io/tale/headplane:latest
container_name: headplane
restart: unless-stopped
ports:
- "3000:3000"
volumes:
- "/path/to/config.yaml:/etc/headplane/config.yaml"
- "/path/to/headscale/config.yaml:/etc/headscale/config.yaml"
- "/var/run/docker.sock:/var/run/docker.sock:ro"
headscale:
image: headscale/headscale:0.26.0
container_name: headscale
restart: unless-stopped
command: serve
labels:
me.tale.headplane.target: headscale
ports:
- "8080:8080"
volumes:
- "/path/to/headscale/config.yaml:/etc/headscale/config.yaml"Two details matter more than they look. The me.tale.headplane.target label is essential for Headplane to find Headscale. And the Docker socket mount is an exposure surface: mount it read-only, or go through a proxy such as Tecnativa/docker-socket-proxy if you would rather not hand over the socket directly.
In production, Headplane sits behind a reverse proxy (Caddy, Nginx, or Traefik) and is served under an /admin path, exactly like Tailscale’s own admin console.
The real payoff: sovereignty without austerity
What makes Headplane interesting is not any single feature but that it lowers the entry cost of an architecture many self-hosters want but hesitate to attempt: owning your network control plane.
The advantages of Headscale remain intact. You no longer depend on Tailscale’s hosted service for the identity of your machines, your ACLs, or your DNS. Your keys and topology never leave your infrastructure. And you keep compatibility with existing Tailscale clients, which spares you from reconfiguring every device.
Headplane adds the missing layer: day-to-day administration. Access delegation through OIDC is the decisive point for multi-user setups — a family, an association, or a small team — where handing the CLI to everyone is simply not reasonable. Remote SSH removes the round-trip between the interface and a separate terminal when troubleshooting a machine.
Be clear-eyed about the limits. Headplane is a young project run largely by a single maintainer, and it depends on Headscale, itself a fast-moving but not institutional project. The risk of a continuity break — the lone-maintainer syndrome — is real and belongs on the scale before you make it a pillar of your infrastructure.
Verdict
If you already run Headscale in production through the CLI, adding Headplane costs you one container and buys you the interface, SSO, and web SSH without touching your control plane: a net win, provided you mount the Docker socket read-only. If you hesitated to leave Tailscale’s hosted service because of the ergonomics, now is the time to test — the experience gap has nearly closed. If you run critical infrastructure, do not make it the heart of your network yet — keep Headplane at the edge, behind a reverse proxy with TLS, and watch the project’s health before entrusting it with more.