English
Headplane Hosting
Headplane is a browser admin console for an existing Headscale server, used to manage users, nodes, and extra DNS records.
- One click deploy
- 15 GB Disk Space Needed
- 1 GB RAM Memory needed
- From 2 € Price
No setup fees
Official links
Headplane’s official links and original website
- Go to Repository
Headplane GitHub
- More
Headplane Website
What you get
on AvaHost
One-click deployment, a custom domain, free HTTPS, automatic application updates, and scheduled backups come with every Cloud App. You can run multiple apps on one server, and terminal access is included.
This template does not include a database container.
Tech
- Docker image
- ghcr.io/tale/headplane:latest
- Default port
- 0
How Headplane works
Headplane is a web administration interface for Headscale, from the tale project. The Docker guide says to run it with Headscale in Docker, image ghcr.io/tale/headplane. You mount a Headplane config, a data directory, and the Headscale config file the UI is allowed to read. Some features, including network management, want the Headscale config path shared and, in the documented example, read-only access to the Docker socket on the same machine. The UI is served under /admin, often on the same hostname as Headscale, with a reverse proxy sending that path to Headplane's port 3000 and everything else to Headscale.
Headscale 0.26.0 or later is required. If that server is missing, Headplane has nothing to administer. It does not enroll Tailscale clients and it does not replace the coordination URL those clients use. SQLite or PostgreSQL for the tailnet stays inside Headscale. Headplane keeps its own small data, including session material derived from the cookie secret you set.
Key Headplane features
From the browser you can work with users, nodes, and DNS extra records when those files are mounted where the config says. The cookie secret must be random and stored, because it locks sessions. A sample config ships with the project. The interesting fields are headscale.url, the cookie secret, and the paths to the Headscale files. Point headscale.url at the in-Docker address when both containers share a network, not at a URL the browser uses.
AvaHost updates Headplane automatically and backs up its data directory on a schedule. That backup is not a backup of Headscale. A dedicated public IP is not required for Headplane itself. Put the public address on the Headscale app. Application mail is not included with Headplane. Docker socket access is powerful. Only enable the integration the upstream guide describes, and treat that socket as administrative access to the host's containers.
Self-hosting Headplane: requirements and cost
The baseline is 512 MB of RAM and half a CPU core, image ghcr.io/tale/headplane, no database of its own. On AvaHost the recommended minimum for Headplane is Plan 1 at €2. The package includes one-click deployment, a hostname or a path on the Headscale hostname, automated HTTPS, automatic updates, and scheduled backups of Headplane data. You must already have Headscale 0.26 or newer. This app does not include that server and does not include a dedicated public IP.
Who uses Headplane
People who already decided on Headscale and want a console like the one Tailscale ships, under /admin, use Headplane. It is the wrong first purchase if Headscale is not running. It is also the wrong package if you are happy with the Headscale CLI and you do not want another service mounted on the same config files.
F.A.Q
Headplane starts at €2 on Plan 1. The price is the admin UI, not Headscale and not a dedicated address for clients. If Headscale is also hosted here, it is a separate app with its own plan. The UI is light. Most of the capacity conversation belongs to the coordination server and to DERP, not to this container.
Yes. The usual layout is one hostname: Headscale on the root, Headplane under /admin, with automated HTTPS on that name. The proxy must send /admin to this app and the other paths to Headscale. You can also use a separate hostname. DNS remains yours. Clients should still be configured with the Headscale URL, not the /admin path.
AvaHost updates Headplane automatically and backs up its own data on a schedule. Headscale’s database is not in that backup. After an update, sign in to /admin and confirm the node list still loads. Keep the cookie secret and the mounted config paths written down, because a wrong mount looks like an empty server.
No. Upstream requires Headscale 0.26 or newer, and the UI only edits that server. Ordering Headplane alone does not create a tailnet. Deploy Headscale first, or deploy both and point Headplane at it. Tailscale clients ignore Headplane. They talk to Headscale.