Headplane | Federated Computer Documentation

Overview

Headplane is the dashboard for Headscale, an open-source server that coordinates a private mesh VPN using the official Tailscale apps. Devices you add (laptops, phones, servers, office machines) can reach each other securely over encrypted WireGuard connections, wherever they are, without opening ports on your router.

Your Federated Core server runs the coordination service; your traffic goes directly between your devices whenever possible.

Main capabilities:

Machines: see every connected device, its addresses, operating system, and last seen time.
Users: group devices by person.
Access controls (ACLs): decide which devices and users can reach which others.
MagicDNS: reach devices by name, such as office-printer, instead of by IP address.
Subnet routes: let devices reach a whole office network through one machine.
Exit nodes: route all internet traffic through a chosen device, for example while on public Wi-Fi.
Pre-auth keys for adding servers and devices without an interactive sign-in.

What it replaces

Headscale with Headplane replaces the hosted Tailscale control plane, ZeroTier Central, and traditional company VPNs such as Cisco AnyConnect or NordLayer for remote access.

Signing in

Open your Headplane address and sign in. Depending on your setup, you sign in with your organization account or with an API key provided by your administrator.

Add a device

You use the official Tailscale app on each device, pointed at your own Headscale server instead of Tailscale’s.

Windows, macOS, and Linux

Install Tailscale from tailscale.com/download.
Connect it to your server. On Linux, or from a terminal on macOS and Windows:
```
tailscale up --login-server https://headscale.example.com
```
On macOS you can instead hold Option while clicking the Tailscale menu bar icon, then choose Debug, Custom Login Server. On Windows, run the command above in PowerShell.
A browser window opens with a registration step. Complete it, or copy the registration key it shows and give it to your administrator.
In Headplane, the administrator approves the device under Machines and assigns it to a user.

iPhone, iPad, and Android

Install Tailscale from the App Store or Google Play.
Open the app’s settings and choose to use an alternate server (or custom coordination server), then enter your Headscale address.
Sign in and complete registration as above.

The address to use is shown in Superpanel. It is the Headscale server, which may differ from the Headplane dashboard address.

Manage machines

In Headplane, open Machines:

Rename devices so they’re easy to recognize.
Move a machine to a different user.
Expire a machine’s key to force it to sign in again, or remove a lost or retired device.
Approve routes: if a device advertises a subnet or offers to be an exit node, approve it here before others can use it.

Control who can reach what

Open Access Control to edit the policy. By default, devices may be able to reach everything; tighten this as your network grows. The policy uses the same format as Tailscale ACLs, for example allowing the finance group to reach only the accounting server on port 443. Save, and changes apply within seconds.

DNS

Under DNS, turn on MagicDNS so devices can reach each other by name, and add nameservers or split DNS for internal domains.

Pre-auth keys for servers

For servers and unattended devices, create a pre-auth key under the user’s settings. Use it when connecting:

tailscale up --login-server https://headscale.example.com --authkey <key>

Make keys single-use and short-lived unless you need otherwise.

Superpanel settings

Access: choose which administrators can open Headplane. Regular users don’t need Headplane; they only need the Tailscale app.