The Evolution of Headscale：Where Cluster Mode Meets Multi-tenancy

A few months ago, I did something “crazy”: I transformed Headscale—a project originally designed for single-node deployments—into a distributed system supporting cluster mode. The core change was elegantly simple: introducing a Cluster ID mechanism. With this ID, multiple Headscale instances now collaborate like Lego bricks, scaling horizontally without limits. Users no longer fear single-point failures, node counts can effortlessly surpass thousands, and—best of all—users can seamlessly switch nodes with a single click. The teacups from those late-night coding sessions still clutter my desk, but watching cluster traffic glide smoothly made every sip worth it.

Over the past month, I’ve dived into an even deeper challenge: multi-tenancy transformation. The mission was clear—to make Headscale operate like Tailscale’s official service, enabling isolated networks for multiple teams and clients. Imagine this: Marketing, Engineering, and an external contractor team each own their private network realm. Devices stay invisible across boundaries, policies are delegated per team, and billing splits cleanly by tenant. Technically, I implemented tenant isolation across authentication layers, data layers, and other critical components—all fused with our existing Cluster ID capability. This finally evolved the monolithic architecture into a true “cluster + multi-tenancy” dual-engine system. Today, it doesn’t just handle massive node loads; it ensures tenants coexist on the same physical node yet remain “blissfully unaware of each other’s existence.” We’ve crossed from a personal-SaaS tool into a unified platform serving both individuals and enterprises. Beyond this, months of applying Tailscale/Headscale in industrial settings have expanded our vision: our solution now scales from personal networks and enterprise IT to smart manufacturing and beyond.

Let’s be honest—this felt like rebuilding an airplane mid-flight. ACL policy collisions, tenant quota overflows, cross-cluster sync delays… bugs hunted me down relentlessly. But the moment two tenants’ devices came online simultaneously in the test environment—without a single byte leaking between them—sent a jolt through me sharper than dousing my face with ice water in winter.

Right now, the entire system is in intense development and debugging phases. Performance stress tests, audit trails, tenant self-service dashboards… these puzzle pieces are snapping into place. We’ve never stood closer to an enterprise-grade Headscale. I can’t wait to share the full blueprint with you soon. This time, the open-source world might truly sprout wings strong enough to rival commercial giants.