NativeCopy Anchor Link

Northplane can run straight on the host, which suits setups where Headscale already runs there, usually under systemd. It's built from source once, then runs on Node.js.

PrerequisitesCopy Anchor Link

• Linux
• Headscale and a Northplane config file, as described in Before installing
• To build: Go matching the go directive in go.mod, and pnpm >=10.4 <11
• To run: Node.js >=24.2 <25

Go and pnpm are only needed to build. The result runs on Node.js alone.

BuildingCopy Anchor Link

# Optionally check out a release tag first
git clone https://github.com/tale/headplane.git
cd headplane
./build.sh

build.sh installs locked dependencies and builds the web UI, the Browser SSH module, the agent and the healthcheck binary. The agent lands in build/hp_agent. Copy it to /usr/libexec/headplane/agent to use it, or see the agent page for another location.

RunningCopy Anchor Link

Create the data directory from server.data_path (/var/lib/headplane by default) and make it writable by the user that runs Northplane:

sudo mkdir -p /var/lib/headplane
sudo chown -R headplane:headplane /var/lib/headplane

Then start Northplane from the repository directory, so it can find build/:

node build/server/index.js

It reads /etc/headplane/config.yaml unless HEADPLANE_CONFIG_PATH points elsewhere. Open http://localhost:3000/admin once it's up.

systemdCopy Anchor Link

Save this as /etc/systemd/system/headplane.service, adjusting the user and paths, then run sudo systemctl daemon-reload and sudo systemctl enable --now headplane:

[Unit]
Description=Northplane
# Use headscale.service here instead if Headscale runs under systemd
After=network.target

[Service]
Type=simple
User=headplane
WorkingDirectory=/opt/headplane
ExecStart=/usr/bin/node /opt/headplane/build/server/index.js
Restart=on-failure
RestartSec=5s
# Environment=HEADPLANE_CONFIG_PATH=/path/to/config.yaml

[Install]
WantedBy=multi-user.target

Signing inCopy Anchor Link

Until SSO or proxy authentication is set up, sign in with a Headscale API key:

headscale apikeys create --expiration 90d

See API keys for how keys and sessions work.

Custom path prefixCopy Anchor Link

To serve Northplane somewhere other than /admin, set server.base_path. See A different path.

Next stepsCopy Anchor Link

• To edit DNS and sign-in restrictions from the UI, set up the proc integration.
• Put Northplane behind a reverse proxy.
• See After installing for the rest.