github.com/juanfont/headscale

Headscale is an open-source implementation of the Tailscale control server, and the experience using it is largely positive once you understand the deployment model. The documentation has improved significantly and includes practical examples for common setups (Docker, K8s, systemd). The CLI is well-designed with clear subcommands for managing users, nodes, and routes. Error messages are generally helpful, especially around DERP configuration and ACL syntax issues.

Day-to-day operations are straightforward after initial setup. The API is stable and the config file structure is logical with good inline comments. GitHub issues get responses reasonably quickly, and the community on Discord is active and helpful for troubleshooting. Common tasks like adding nodes, managing preauth keys, and setting up subnet routing are well-documented with copy-paste examples.

The main challenge is the initial deployment complexity - understanding DERP servers, DNS integration, and TLS certificate management requires more networking knowledge than typical Go packages. Debugging client-server connection issues can be tricky without deep Tailscale protocol knowledge, though logs are verbose when enabled.

Headscale provides a self-hosted alternative to Tailscale's coordination server with surprisingly good operational characteristics. The gRPC and HTTP APIs are well-structured, and the CLI tooling makes node management straightforward. Database migrations have been stable across versions, supporting SQLite and PostgreSQL with proper connection pooling. The logging implementation using zerolog provides structured output that integrates well with observability stacks.

Resource usage is reasonable for most deployments—memory footprint stays under 100MB for networks with hundreds of nodes. The DERP relay configuration is flexible and timeout values are sensible by default (30s for coordination, configurable per-endpoint). However, the OIDC integration requires careful configuration and error messages during auth failures could be more descriptive. Breaking changes between 0.2x versions have happened, particularly around API schemas and database models, requiring careful attention during upgrades.

Under load, it handles concurrent node registrations well, though the lack of built-in rate limiting means you'll need to add that at the reverse proxy layer. Graceful shutdown works correctly, finishing in-flight requests before terminating. The metrics endpoint exposes Prometheus-compatible stats covering the important operational concerns.

Headscale serves as a self-hosted Tailscale control server and performs well in production. The gRPC and HTTP APIs are well-structured, and the built-in metrics endpoint provides useful Prometheus integration out of the box. Database connection pooling works reliably with both SQLite and PostgreSQL backends, though you'll want to tune pool settings for high node counts. The daemon handles graceful shutdowns properly, releasing connections cleanly.

Configuration is comprehensive but can be overwhelming initially - the YAML schema supports environment variable expansion which helps with secret management. Logging is structured JSON by default with configurable levels, making it straightforward to integrate with centralized logging. OIDC integration works smoothly once configured, though debugging auth flows requires bumping log levels.

Migration paths between versions require careful attention - schema changes aren't always backward compatible, and the release notes are essential reading. The retry behavior for node registration is sensible with exponential backoff, but timeout defaults are sometimes conservative for high-latency environments. Under moderate load (500+ nodes), memory usage is predictable and CPU overhead minimal, though the built-in DERP relay can become a bottleneck at scale.