🚀 v1.0.45 — Mobile responsive

The Headscale Admin
you actually want

Production-ready, role-based dashboard for Headscale. Docker install in under 5 minutes. No Node.js. No cloning. Just pull and run.

⚡ Quick Install 🎭 Live Demo ⭐ Star on GitHub
hs.yourdomain.com/admin
Home Users Nodes ACL Editor DNS Settings
☀️
🌙
13
Users
12
Nodes Online
7
Nodes Offline
👤
Users
🖥️
Nodes
🛣️
Routes
📋
ACL Editor
🌐
DNS
⚙️
Settings
admin@yourdomain.com super_admin
☕ Buy me a coffee Logout
3
Role levels
6
ACL Editor tabs
<5min
Install time
v0.28+
Headscale support
// Features

Everything you need to manage
your Tailnet

Built for real Headscale deployments — from single-user homelab to multi-tenant company networks.

🔐
Role-Based Access
Three roles — super_admin, group_admin, user. Group admins only see their own domain's users and nodes. Per-domain filtering throughout.
🚀
Deploy Wizard
Visual tailscale up command builder with live preview. Generate pre-auth keys, set flags, copy to clipboard or show as QR code.
📋
ACL Editor
6-tab visual editor — Users, Groups, Hosts, Policies, SSH, Config. Edit policies in-place with protocol selectors and JSON validator.
🌐
DNS Management
Manage tailnet name, Magic DNS, nameservers, split DNS and extra records. Sticky toolbar for fast edits without scrolling.
🖥️
Node Management
View, search, rename, move owner, expire and delete nodes. Online/offline status, IP addresses. Route approval per node.
🔑
Pre-Auth Keys
Create, expire and clear expired keys per user. Auto-refresh on navigate. Integrated with the deploy wizard for seamless node onboarding.
📜
Audit Log
All admin actions logged — who did what, when. Login history, user changes, node actions and DNS edits all captured.
🆕
Update Notifications
Footer shows an amber button when a newer version is available on GitHub. No manual version checking needed.
📱
Mobile Responsive
Hamburger nav, scrollable tables, full-width modals and stacking layouts. Works on phone and tablet without compromises.
// Access Control

Multi-tenant role system

Perfect for MSPs, families or companies sharing a Headscale instance — each group only sees their own world.

super_admin
Full Access
  • All users and nodes across all domains
  • DNS, Routes, ACL Editor full control
  • Settings, audit log, pre-auth keys
  • Create users and manage login mapping
  • Register and unregister instance
group_admin
Domain Admin
  • Own @domain.com users and nodes only
  • ACL editor for their domain policies
  • Deploy wizard for their users
  • Create and manage pre-auth keys
  • Cannot see other domains
user
Standard User
  • Read-only view of own profile
  • View own labelled API keys
  • No access to admin features
  • No node or user management
  • Login with Headscale API key
// Installation

Up and running in minutes

No Node.js. No cloning. No building. Three files and you're done.

1 Download files
# Download docker-compose and env template curl -O https://raw.githubusercontent.com/HybridRCG/headscale-admin-react/main/resources/docker-compose.yml curl -O https://raw.githubusercontent.com/HybridRCG/headscale-admin-react/main/resources/vps.env.example cp vps.env.example .env
2 Configure .env
# Edit .env with your values JWT_SECRET=$(openssl rand -base64 32) HEADSCALE_DOMAIN=hs.yourdomain.com HEADSCALE_URL=http://headscale:8080 HS_LICENSE_SECRET=$(openssl rand -base64 32)
3 Start
docker compose up -d # users-mapping.json auto-created on first start # Edit it to match your Headscale username docker compose restart hs-react
4 First login
# Create a Headscale API key docker exec headscale /ko-app/headscale \ apikey create --expiration 90d # Open https://your-domain.com/admin # Login: username + API key
💡
Auto-created configuration
On first start, users-mapping.json is automatically created at /etc/headscale/users-mapping.json with a default admin user. Edit to set your actual username, email and role.
// Get Started

Ready to take control
of your Tailnet?

Install in under 5 minutes. Free and open source.

⚡ Install Now View on GitHub →
☕ Buy me a coffee
☕

Support HS React

HS React is free and open source. If it saves you time, consider buying me a coffee.
In return you'll receive a license key that:

✓ Removes the Buy Me a Coffee button from your footer
✓ Entitles you to request updates & new features
✓ Supports continued development
☕ Buy Me a Coffee

Enter the license key in Settings → Registration after purchase