Web GUI (Headplane) - Headscale + Tailscale Docker Stack

Headplane is a modern web-based GUI for managing your Headscale server, providing an intuitive alternative to command-line management.

Accessing Headplane

Headplane is included in the Docker stack and runs automatically: URL: http://localhost:3001/admin/

Make sure to include the trailing slash (/admin/). Without it, you’ll get a 404 error.

Initial Setup

Generate an API key

docker exec headscale headscale apikeys create --expiration 999d

Copy the generated key (it’s shown only once).

Open Headplane in browser

Navigate to: http://localhost:3001/admin/

Paste the API key into the login form and click Login.

Dashboard

The dashboard provides an overview of your entire network:

Network Overview

Total nodes connected
Online/offline status
Active users
Recent activity

Quick Stats

Number of nodes per user
Active routes
Pre-auth keys created
System health

Recent Events

New nodes connected
Routes advertised
Keys created
Configuration changes

Health Status

Headscale service status
Database connectivity
API availability
Version information

Managing Nodes

View All Nodes

Click Nodes in the sidebar
See all connected devices with:
- Hostname
- User/owner
- IP addresses (IPv4 and IPv6)
- Online/offline status
- Last seen timestamp
- Operating system
- Tags

Node Details

Click any node to view detailed information:

General Info
Network Info
Routes
Tags

Full hostname
Node ID
User/namespace
Created date
Last updated
Tailscale version
OS and architecture

Node Actions

Rename

Click node name
Edit hostname field
Save changes

Delete

Select node
Click Delete button
Confirm deletion

This removes the node from the network. It must reconnect with a new key.

Expire

Select node
Click Expire
Node is marked as expired

Useful for temporarily disabling access.

Managing Users

View Users

Click Users in sidebar
See all users with:
- Username
- Number of nodes
- Created date
- Node list preview

Create User

Click 'Create User'

In the Users page, click the Create User button.

Enter username

Type the username (lowercase, no spaces recommended).

Save

Click Save to create the user.

Generate keys

Create pre-auth keys for the new user to connect devices.

View nodes: Click username to see all their devices
Delete user: Remove user and all associated nodes
Generate keys: Create pre-auth keys for the user

Pre-Auth Key Management

Create Pre-Auth Key

Navigate to Pre-Auth Keys

Click Pre-Auth Keys in the sidebar.

Click 'Create New Key'

Button is at the top of the page.

Configure key settings

Basic Settings
Advanced Options

User: Select which user owns this key
Expiration: Set how long the key is valid
- 1 hour (production)
- 24 hours (testing)
- 168 hours (7 days)
- Custom duration

Reusable: Allow key to connect multiple devices
Ephemeral: Auto-remove node on disconnect
Tags: Apply ACL tags to nodes using this key
- tag:personal
- tag:servers
- tag:guests

Create and copy key

Click Create
Copy the generated key immediately
Store it securely

The key is shown only once. You cannot retrieve it later.

View Active Keys

See all pre-auth keys:

Key prefix (last few characters)
User/owner
Created date
Expiration date
Reusable status
Used/unused status

Expire Key

Find the key in the list
Click Expire button
Key is immediately invalidated
Cannot be used to connect new devices

Route Management

View Routes

Click Routes in sidebar
See all advertised routes:
- Node advertising the route
- Subnet/prefix (e.g., 192.168.1.0/24)
- Exit node routes (0.0.0.0/0)
- Enabled/disabled status

Approve Routes

Find the route

Routes are listed with their advertising node and prefix.

Click 'Approve' or 'Enable'

Button appears next to disabled routes.

Verify activation

The route status changes to Enabled and clients can now use it.

Approve Exit Nodes

Exit node routes are shown as 0.0.0.0/0 (IPv4) or ::/0 (IPv6):

Find exit node route
Click Approve
Node can now route internet traffic

Disable Route

Find enabled route
Click Disable
Clients can no longer use this route

ACL Policy Editor

Edit Policies

Navigate to Policies/Settings

Click Policies or Settings in sidebar.

Edit policy JSON

Use the built-in editor to modify policy.json:

{
  "tagOwners": {
    "tag:personal": ["group:admins"],
    "tag:servers": ["group:admins"]
  },
  "acls": [
    {
      "action": "accept",
      "src": ["tag:personal"],
      "dst": ["tag:servers:22,80,443"]
    }
  ]
}

Validate syntax

The editor highlights JSON syntax errors.

Save changes

Click Save to apply the new policy.

Policy Examples

Personal Network
Guest Isolation
Multi-Tier

{
  "tagOwners": {
    "tag:personal": ["group:admins"],
    "tag:servers": ["group:admins"]
  },
  "acls": [
    {
      "action": "accept",
      "src": ["tag:personal"],
      "dst": ["tag:servers:*"]
    }
  ]
}

{
  "tagOwners": {
    "tag:guests": ["group:admins"]
  },
  "acls": [
    {
      "action": "accept",
      "src": ["tag:guests"],
      "dst": ["tag:services:80,443"],
      "comment": "Guests only access web services"
    }
  ]
}

{
  "tagOwners": {
    "tag:personal": ["group:admins"],
    "tag:servers": ["group:admins"],
    "tag:private": ["group:admins"]
  },
  "acls": [
    {
      "action": "accept",
      "src": ["tag:personal"],
      "dst": ["tag:servers:22,80,443", "tag:private:*"]
    },
    {
      "action": "accept",
      "src": ["tag:servers"],
      "dst": ["tag:servers:*"]
    }
  ]
}

API Keys Management

Create Additional API Keys

Go to Settings or API Keys
Click Create API Key
Set expiration (recommended: 365 days)
Copy and store the key securely

Revoke API Key

Revoking an API key will log out any sessions using that key.

Find the key in the list
Click Revoke or Delete
Confirm revocation

Headplane Configuration

Headplane settings are in headplane/config.yaml:

headplane/config.yaml

headscale_url: http://headscale:8080
api_key: YOUR_API_KEY_HERE
cookie_secret: exactly_32_character_string_
log_level: info

Configuration Options

Option	Description	Example
`headscale_url`	Internal Headscale URL	`http://headscale:8080`
`api_key`	Headscale API key	Generated from `headscale apikeys create`
`cookie_secret`	Session encryption key	32-character string
`log_level`	Logging verbosity	`info`, `debug`, `warn`

Troubleshooting

404 Error When Accessing Headplane

Check URL has trailing slash

✅ Correct: http://localhost:3001/admin/❌ Wrong: http://localhost:3001

Verify Headplane is running

docker compose ps | grep headplane
# Should show "Up"

Check logs

docker compose logs headplane --tail 50

Generate new API key

docker exec headscale headscale apikeys create --expiration 999d

Update Headplane config

Edit headplane/config.yaml and add the new key:

api_key: NEW_KEY_HERE

Restart Headplane

docker compose restart headplane

Headplane Not Loading / Blank Page

# Check Headscale is running
curl http://localhost:8000/health
# Should return: {"status":"pass"}

# Verify API key works
docker exec headscale headscale nodes list

# Check cookie_secret is exactly 32 characters
grep cookie_secret headplane/config.yaml

# Restart both services
docker compose restart headscale headplane

Changes Not Appearing

Hard refresh browser: Ctrl+Shift+R (or Cmd+Shift+R on Mac)
Clear browser cache: Settings → Clear browsing data
Check service logs: docker compose logs headplane

GUI vs Command Line

Headplane GUI
Command Line

Best for:

Visual overview of network
Quick device management
Non-technical users
One-off tasks
Monitoring status

Advantages:

No terminal needed
Visual feedback
Easy navigation
Real-time updates

Security Best Practices

Secure API Keys

Use long expiration only for dev: --expiration 999d
Production keys: --expiration 90d
Rotate keys regularly
Never commit keys to git

Network Access

Don’t expose Headplane publicly
Use VPN or Tailscale to access it
Add authentication proxy if needed
Monitor access logs

Cookie Security

Use strong 32-character cookie_secret
Change default secret
Use random string generator:

openssl rand -base64 32

Regular Audits

Review connected nodes weekly
Check active API keys
Audit user access
Remove unused keys and nodes

Tips and Tricks

Keyboard Shortcuts

Search nodes: Type in search box (usually / key)
Refresh data: F5 or refresh button
Navigate: Use browser back/forward

Bulk Operations

For bulk operations, use command line:

# Delete multiple nodes
for id in 1 2 3 4 5; do
  docker exec headscale headscale nodes delete --identifier $id
done

# Create multiple users
for user in alice bob charlie; do
  docker exec headscale headscale users create $user
done

Export Data

# Export node list
docker exec headscale headscale nodes list > nodes.txt

# Export users
docker exec headscale headscale users list > users.txt

# Export routes
docker exec headscale headscale routes list > routes.txt

Get Started

Deployment

Configuration

Guides

Operations

​Accessing Headplane

​Initial Setup

​Dashboard

Network Overview

Quick Stats

Recent Events

Health Status

​Managing Nodes

​View All Nodes

​Node Details

​Node Actions

Rename

Delete

Expire

Tag

​Managing Users

​View Users

​Create User

​User Actions

​Pre-Auth Key Management

​Create Pre-Auth Key

​View Active Keys

​Expire Key

​Route Management

​View Routes

​Approve Routes

​Approve Exit Nodes

​Disable Route

​ACL Policy Editor

​Edit Policies

​Policy Examples

​API Keys Management

​Create Additional API Keys

​Revoke API Key

​Headplane Configuration

​Configuration Options

​Troubleshooting

​404 Error When Accessing Headplane

​Cannot Login / Invalid API Key

​Headplane Not Loading / Blank Page

​Changes Not Appearing

​GUI vs Command Line

​Security Best Practices

Secure API Keys

Network Access

Cookie Security

Regular Audits

​Tips and Tricks

​Keyboard Shortcuts

​Bulk Operations

​Export Data

​Next Steps

Build docs developers (and LLMs) love

Accessing Headplane

Initial Setup

Dashboard

Managing Nodes

View All Nodes

Node Details

Node Actions

Managing Users

View Users

Create User

User Actions

Pre-Auth Key Management

Create Pre-Auth Key

View Active Keys

Expire Key

Route Management

View Routes

Approve Routes

Approve Exit Nodes

Disable Route

ACL Policy Editor

Edit Policies

Policy Examples

API Keys Management

Create Additional API Keys

Revoke API Key

Headplane Configuration

Configuration Options

Troubleshooting

404 Error When Accessing Headplane

Cannot Login / Invalid API Key

Headplane Not Loading / Blank Page

Changes Not Appearing

GUI vs Command Line

Security Best Practices

Tips and Tricks

Keyboard Shortcuts

Bulk Operations

Export Data

Next Steps