Headscale GUI: Best Web UIs and Docker Setup Guide

Headscale GUI web dashboard showing connected nodes and users on a self-hosted Tailscale controller network

Tailscale is great until you start caring about who owns the control plane. Self-hosting with Headscale fixes that: your node list, your keys, your ACLs, your server. No device limits, no vendor deciding what your network metadata is worth.

Then reality shows up. You’re SSH’d into a box at 11pm running headscale nodes list, copying a node ID into headscale nodes expire, then hunting for the right syntax to move a machine to another user. For a homelab, fine. For a team of ten with contractors coming and going, it gets old fast.

That’s the gap a Headscale GUI fills. Headscale deliberately ships without a web interface, and the project’s own docs point to community-built options. This guide compares the ones worth your time, shows a working Docker Compose setup, and covers the errors you’ll probably hit.

What a Headscale GUI actually gives you

Headscale is a self-hosted Tailscale controller: it coordinates keys, hands out IPs, and enforces policy. A GUI sits in front of its API and turns CLI chores into clicks. The useful parts:

  • Node visibility. See which machines are online, when they were last seen, their IPs, and who owns them.
  • User management. Create users and move machines between them without memorizing flags.
  • Pre-auth keys. Generate, set expiry on, and revoke keys for onboarding new devices or servers.
  • Route approval. Approve subnet routes and exit nodes in one place.
  • ACL editing. Some UIs let you edit and validate your policy file, which beats editing JSON blind.
  • Expiry control. Extend or expire nodes and API keys before they surprise you.

None of this is impossible with the CLI. A good Headscale web UI just makes mistakes less likely and makes it possible to hand day-to-day admin to someone who doesn’t live in a terminal.

The main Headscale GUI options compared

The Headscale docs list several community UIs and note that none are maintained by the Headscale authors. Here are the ones that matter in practice.

Headplane

Written by Aarnav Tale, Headplane aims to replicate the official Tailscale dashboard and is generally considered the most feature-complete option. It handles machine management (expiry, routes, names, owners), ACL and tag configuration, OIDC login, and DNS settings. It can also edit Headscale’s own config in its fuller “integrated” deployment, which talks to Headscale through the Docker socket.

Best for: teams that want a near-Tailscale admin experience and use OIDC.

headscale-admin

From GoodiesHQ, this is a simple, modern interface that runs as a small container and is served under /admin on the same domain as Headscale. Its README describes it as beta software that is still in active development, though usable in production when set up carefully. Image tags track Headscale versions, so a 0.24 admin tag is meant for Headscale 0.24. Your API URL and key are stored in the browser’s local storage, which matters for security (more below).

Best for: small teams that want a clean, lightweight headscale-admin setup without extra moving parts.

headscale-ui

From GuruComputing, this is a static web frontend you serve alongside Headscale, typically under /web. It talks to the API from the browser. It’s been around a long time and is straightforward, though you should check recent commit activity and Headscale compatibility before committing.

Best for: people who want a minimal static UI and are comfortable checking compatibility themselves.

headscale-webui

From iFargle, described in the Headscale docs as a simple UI for small-scale deployments. It’s simple to run, but it’s aimed at smaller setups, so check how actively it’s maintained against your Headscale version.

Best for: homelabs and very small networks.

A note on others

The Headscale docs also list a static UI that needs no backend, a self-service UI called Ouroboros for users managing their own devices, and a WebAssembly console with SSH, VNC and RDP support. Useful, but narrower in scope.

Feature comparison

Headplaneheadscale-adminheadscale-uiheadscale-webui
Setup difficultyMedium (integrated mode needs more config)EasyEasyEasy
Auth methodHeadscale API key; OIDC supportedHeadscale API key (stored in browser)Headscale API key (browser)API key configured on the server
Node status viewYesYesYesYes
ACL editingYesLimited, check current releaseCheck current releaseLimited
OIDC loginYesNoNoNo
Edits Headscale configYes (integrated mode)NoNoNo
Docker supportYesYes (official image)YesYes
MaturityActive, semantic versioningBeta, activeEstablishedSmall-scale focus

Feature support changes between releases. Treat this table as a starting point and check each project’s README before you commit.

Docker Headscale setup with a GUI (step by step)

This example runs Headscale and headscale-admin behind Caddy on one domain. It’s the simplest path because headscale-admin expects to live on the same hostname as Headscale, which also avoids CORS headaches.

1. Folder layout

headscale-stack/
├── docker-compose.yml
├── Caddyfile
└── headscale/
    ├── config/
    │   └── config.yaml
    └── data/

2. Headscale config essentials

Start from the official example config.yaml for your Headscale version, then set at least:

yaml

server_url: https://headscale.example.com
listen_addr: 0.0.0.0:8080

Keep server_url as the public HTTPS address your clients will use. A wrong value here causes confusing client errors later.

3. Docker Compose

Pin versions instead of using latest. Use the same minor version for Headscale and the admin UI image.

yaml

services:
  headscale:
    image: headscale/headscale:<version>
    container_name: headscale
    command: serve
    restart: unless-stopped
    volumes:
      - ./headscale/config:/etc/headscale
      - ./headscale/data:/var/lib/headscale
    networks:
      - hsnet

  headscale-admin:
    image: goodieshq/headscale-admin:<same-minor-version>
    container_name: headscale-admin
    restart: unless-stopped
    networks:
      - hsnet

  caddy:
    image: caddy:2
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    networks:
      - hsnet

networks:
  hsnet:

volumes:
  caddy_data:
  caddy_config:

4. Caddyfile

headscale.example.com {
    handle /admin* {
        reverse_proxy headscale-admin:80
    }

    handle {
        reverse_proxy headscale:8080
    }
}

Caddy handles HTTPS certificates automatically and passes the connection upgrades Headscale needs without extra settings.

5. Start it and create an API key

bash

docker compose up -d

docker compose exec headscale headscale apikeys create --expiration 90d

Copy the key right away. Headscale only shows it once, so if you lose it you’ll need to expire it and create a new one.

Useful key commands:

bash

docker compose exec headscale headscale apikeys list
docker compose exec headscale headscale apikeys expire --prefix "<key-prefix>"

6. Log in to the GUI

Open https://headscale.example.com/admin/, enter your Headscale URL and the API key, and you should see your users and nodes. Create your first user, then generate a pre-auth key and enroll a test machine.

If you choose Headplane instead

Headplane has two modes. The fuller integrated mode connects to Headscale through the Docker socket so it can manage config and DNS. Mounting /var/run/docker.sock into a container is a real privilege grant, so mount it read-only, restrict network access to the UI, and put it behind OIDC or at minimum a VPN. Config format changes between releases, so follow the current Headplane documentation instead of copying old blog snippets, including this one.

Common pitfalls and fixes

API key expired and the GUI stops working. Keys created with an expiry will quietly lapse. Put the expiry date in your calendar and rotate before it hits. For automation, create a separate, clearly named key per tool.

CORS errors in the browser console. This happens when the UI and Headscale live on different domains. The easiest fix is to serve both on one hostname with path routing, as above. If you must split them, add the UI’s origin to the CORS headers at your reverse proxy.

404 or blank page at /admin. The admin image expects to be served under its configured path. If you changed the path at the proxy, you may need to rebuild the image with a matching endpoint build argument.

Clients can’t connect behind Nginx. Tailscale clients use an HTTP upgrade on the control connection, and Nginx drops it unless you pass the headers through:

nginx

location / {
    proxy_pass http://headscale:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 3600s;
}

With Traefik, make sure your router points to the correct internal port and that any CORS middleware lists only the origins you actually use.

Version mismatch. If the UI shows empty lists or odd errors after a Headscale upgrade, check the UI’s compatibility notes. Upgrade Headscale and the GUI together, and read release notes first.

API key sitting in browser storage. Some UIs store the key in local storage. Anyone with access to that browser profile can use it. Don’t log in from shared machines, and keep the admin path off the public internet when you can.

Why distributed teams self-host their mesh

Remote teams tend to end up with the same problem: internal dashboards, staging servers, client data pipelines, and tooling that shouldn’t be reachable from the open internet, but still need to be reachable by people in different countries.

Take an SEO or outreach agency with members spread across time zones. A team like the one behind linksbuilderhub.com will have prospect databases, reporting dashboards, and automation scripts running on private servers. Opening ports for each of those invites scanning and brute-force attempts. Putting everything on a private mesh means those services only answer to enrolled devices.

Self-hosting the controller with Headscale adds a second benefit: no per-seat SaaS fee and no third party holding your device inventory. When a contractor leaves, you expire their node and the access disappears. A GUI makes that offboarding step something an operations lead can do without waiting for whoever has shell access.

This is a general pattern, not a claim about any one company’s internal setup, but it’s a common one for small distributed teams that want zero-trust access without a heavy enterprise stack.

Final verdict: which Headscale GUI should you pick?

  • Solo or homelab, want it running in ten minutes: headscale-admin. One small container, same-domain routing, done.
  • Small team (3 to 20 people), want near-Tailscale features, using OIDC: Headplane. It’s more work to set up, but it’s the closest thing to the official dashboard.
  • Minimal static UI, you’re comfortable checking compatibility: headscale-ui.
  • Very small network, simplest possible interface: headscale-webui.
  • Larger team with compliance needs: Headplane behind OIDC, with the admin path restricted to a VPN or allow-listed IPs, plus regular API key rotation.

Whichever you pick, pin versions, keep Headscale and the UI on matching minor releases, rotate API keys on a schedule, and keep the admin interface off the open internet if you can. A GUI makes administration easier, but it also becomes a high-value target.

1 thought on “Headscale GUI: Best Web UIs and Docker Setup Guide”

  1. Pingback: Notion Alternatives: 6 Best Picks for 2026

Leave a Comment

Your email address will not be published. Required fields are marked *