tale/headplane: A Feature-Complete Web UI for Headscale Networks

tale/headplane: A Feature-Complete Web UI for Headscale Networks

Running a self-hosted VPN infrastructure with Headscale gives you control, but it comes with a friction point: no built-in web interface. Every node registration, ACL update, or DNS change requires command-line interaction or manual configuration file edits. For teams managing dozens of machines across multiple users, this overhead compounds quickly. tale/headplane addresses this gap directly — it's a feature-complete web UI for Headscale that replicates the management experience developers expect from commercial VPN solutions, without sacrificing the self-hosted model.

What is tale/headplane?

tale/headplane is an open-source web interface for Headscale, the de-facto self-hosted implementation of Tailscale's WireGuard-based VPN protocol. The project is maintained by Aarnav Tale and distributed under the MIT License. As of July 2025, the repository has accumulated 2,729 stars and 213 forks, with TypeScript as its primary language — signaling active community interest and a modern, type-safe codebase.

The tool sits in a specific but growing category: infrastructure management UIs for self-hosted networking tools. Headscale itself provides the control plane and coordination server for WireGuard mesh networks, but deliberately omits a graphical administration layer. Headplane fills this architectural gap, aiming to replicate the functionality of Tailscale's official dashboard while remaining fully compatible with Headscale's open-source backend.

What makes tale/headplane relevant now is the broader shift toward self-hosted infrastructure and zero-trust networking. Organizations evaluating Tailscale's commercial offering often hit cost or data-sovereignty constraints. Headscale provides the protocol compatibility, but without a management UI, operational friction remains high. Headplane reduces that friction without introducing proprietary dependencies.

Key Features

Machine Management Headplane provides comprehensive control over registered nodes: viewing machine status, managing expiry settings, configuring network routing (subnet routers and exit nodes), renaming devices, and transferring ownership between users. This covers the full lifecycle of a node in a production mesh network.

Access Control List (ACL) Configuration Rather than hand-editing HuJSON files, administrators can configure ACLs and tags through the web interface. This includes setting up user groups, defining port-based access rules, and enforcing tag-based policies — critical for segmenting production and development environments within the same network.

OpenID Connect (OIDC) Integration Headplane supports OIDC as an authentication provider, enabling integration with existing identity infrastructure (Keycloak, Authentik, Okta, etc.). This avoids maintaining a separate user credential store and aligns with SSO requirements common in organizational deployments.

DNS and Provisioning Automation The UI exposes Headscale's DNS settings for editing and includes automated provisioning capabilities. This reduces manual configuration drift when spinning up new coordination servers or migrating between infrastructure.

Headscale Settings Configuration Beyond runtime management, Headplane allows direct modification of Headscale's core settings through the interface — bridging the gap between one-off CLI commands and persistent configuration management.

Use Cases

Small Team Self-Hosted VPN A 10-20 person engineering team wants Tailscale-compatible mesh networking without per-seat pricing. They deploy Headscale on existing infrastructure, then use tale/headplane as the daily management interface for onboarding new developers, revoking departed employees' access, and debugging connectivity issues without SSHing to the coordination server.

Multi-Environment Network Segmentation A DevOps^{↗ Bright Coding Blog} team runs separate production, staging, and internal tooling networks under one Headscale instance. Using Headplane's ACL and tagging features, they enforce that staging nodes cannot reach production databases, while CI/CD runners have limited, tag-scoped access to deployment targets — all configured through the web UI rather than error-prone manual file edits.

Infrastructure-as-Code Adjacent Workflows Teams using Terraform or Pulumi for infrastructure provisioning still need a visualization and debugging layer. Headplane serves as the operational console: verifying that automated registrations succeeded, inspecting routing table propagation, and performing ad-hoc access grants that don't warrant a full CI pipeline run.

Identity-Integrated Corporate Deployments Organizations with existing OIDC providers (corporate Azure AD, Google Workspace, or self-hosted alternatives) can deploy Headplane without introducing parallel authentication systems. This satisfies security audit requirements while keeping the networking stack fully open-source.

Installation & Setup

The README directs users to https://headplane.net for detailed installation instructions. Based on the project's structure and typical TypeScript/Node.js deployment patterns, installation likely follows standard containerized or Node.js application procedures.

For containerized deployments, you would typically:

# Pull the latest stable image
docker↗ Bright Coding Blog pull ghcr.io/tale/headplane:latest

# Or use the pre-release channel for testing
docker pull ghcr.io/tale/headplane:next

The next tag corresponds to pre-release builds that update when new release PRs are opened and actively in testing — useful for evaluating upcoming features or contributing bug reports before general availability.

For configuration, Headplane requires connectivity to your Headscale instance. This typically involves setting environment variables or mounting a configuration file with:

• Headscale API endpoint and authentication key
• OIDC provider endpoints and client credentials (if using SSO)
• Listen address and port for the Headplane web server

Since v0.6.0, the project uses semantic versioning, making dependency and upgrade planning predictable.

Real Code Examples

The README does not contain extensive inline code snippets — this reflects the current documentation structure, which defers to the project's website for detailed instructions. Below are the configuration and deployment patterns explicitly documented or strongly implied by the project's design:

Container Deployment with Docker Compose

# docker-compose.yml — typical structure based on project patterns
services:
  headplane:
    image: ghcr.io/tale/headplane:latest
    # Pre-release builds available under :next tag for testing
    ports:
      - "3000:3000"  # Default Headplane listen port
    environment:
      # Headscale API connection
      HEADSCALE_URL: "http://headscale:8080"
      HEADSCALE_API_KEY: "${HEADSCALE_API_KEY}"
      # OIDC configuration (optional but recommended)
      OIDC_ISSUER: "https://auth.example.com"
      OIDC_CLIENT_ID: "headplane"
      OIDC_CLIENT_SECRET: "${OIDC_CLIENT_SECRET}"
    volumes:
      # Persist any local configuration or state
      - ./data:/app/data

This structure aligns with Headplane's documented features: OIDC integration, Headscale settings configuration, and the need for persistent API credentials.

Semantic Version Reference

# Check current version — since v0.6.0 uses semver
# Stable releases follow MAJOR.MINOR.PATCH
curl -s https://api.github.com/repos/tale/headplane/releases/latest | \
  grep '"tag_name"' | \
  sed -E 's/.*"([^"]+)".*/\1/'

# For pre-release testing, monitor the next tag
docker pull ghcr.io/tale/headplane:next

The explicit semver adoption since v0.6.0 is documented in the README and matters for teams pinning dependencies in production environments.

Note: The README's deployment documentation is intentionally concise, directing users to https://headplane.net. The examples above represent standard patterns consistent with the project's TypeScript/Node.js stack and documented configuration surface, not copied verbatim from the README.

Advanced Usage & Best Practices

Separate Pre-Release and Production Instances Given the next tag's nature — updated when release PRs are in active testing — run a staging Headplane instance tracking next against a non-production Headscale server. This validates UI behavior with your ACL and OIDC configurations before promoting to your production latest deployment.

ACL Version Control Integration While Headplane enables web-based ACL editing, consider exporting and committing ACL configurations to git. The web UI excels for rapid iteration and debugging; version control provides audit trails and disaster recovery. Treat Headplane as the operational interface, not the system of record.

OIDC Scope Minimization When configuring OIDC, request only necessary scopes (openid, profile, email typically). Headplane's integration enables SSO convenience, but following least-privilege principles in your identity provider configuration prevents over-provisioning.

Monitor Headscale API Compatibility Headplane's feature completeness depends on Headscale API stability. Before upgrading either component, verify compatibility in your staging environment. The projects move independently — a Headscale release may precede Headplane support or vice versa.

Comparison with Alternatives

Headscale CLI Only: Zero additional dependencies, but operational friction scales with team size and network complexity. Suitable for solo operators or automation-heavy workflows.

Tailscale Official: Polished experience with proprietary features (MagicDNS optimizations, funnel, etc.), but requires SaaS trust model and ongoing subscription costs. The control plane is not self-hostable.

tale/headplane occupies a specific niche: teams committed to self-hosting the control plane who need graphical management without building an internal tool.

FAQ

Is tale/headplane officially affiliated with Headscale or Tailscale? No — it's an independent community project by Aarnav Tale, compatible with Headscale's API but not officially endorsed by either organization.

What license is tale/headplane released under? MIT License, permitting commercial use, modification, and distribution with minimal restrictions.

Does Headplane replace the Headscale server? No — it's a management layer. You still need a running Headscale instance; Headplane connects via its API.

Can I use Headplane without OIDC? The README documents OIDC as a supported login provider; alternative authentication methods may exist but aren't prominently featured in current documentation.

How current is the project? Last commit dated July 13, 2026 per repository metadata, indicating active maintenance.

Are pre-release builds stable for production? The next tag is explicitly for testing during active release PRs. Use latest or version-pinned tags for production.

Where do I report bugs or request features? Open an issue on the GitHub repository; contributor guidelines are available at ./docs/CONTRIBUTING.md.

Conclusion

tale/headplane solves a concrete operational problem: Headscale's powerful networking capabilities are undermined by its lack of administrative interface. For teams already committed to self-hosted infrastructure, the choice isn't between Headplane and Tailscale's SaaS — it's between Headplane and maintaining internal tooling or accepting CLI-only operations.

With 2,729 stars, active TypeScript development, and a feature set covering machine lifecycle, ACL management, OIDC integration, and DNS provisioning, it's a credible production option. The MIT license removes commercial friction. Semantic versioning since v0.6.0 provides upgrade predictability.

It's best suited for: small-to-medium engineering teams running Headscale, organizations with OIDC infrastructure seeking SSO-integrated network management, and operators who need visual debugging tools without surrendering control plane ownership.

Ready to evaluate it? Clone the repository, check the website for deployment specifics, and open an issue if you hit gaps — contributions are explicitly welcomed. [INTERNAL_LINK: Headscale deployment guide]

Explore the source and latest releases at https://github.com/tale/headplane