explaingit

juanfont/headscale

📈 Trending38,473GoAudience · developerComplexity · 4/5ActiveLicenseSetup · hard

TLDR

Self-hosted replacement for Tailscale's control server, letting you run your own private mesh VPN network without relying on external services.

Mindmap

mindmap
  root((repo))
    What it does
      Self-hosted VPN control
      Mesh network coordinator
      Device key management
    How it works
      Replaces Tailscale server
      Works with Tailscale clients
      Manages encryption keys
    Use cases
      Home lab networking
      Small team VPN
      Privacy-focused setup
    Tech stack
      Go language
      Protobuf APIs
      WireGuard protocol
    Deployment
      Binary builds
      NixOS support
      Self-hosted only

Things people build with this

USE CASE 1

Set up a private mesh network for your home lab without sending device data to Tailscale's servers.

USE CASE 2

Connect remote team members' devices securely as if they were on the same local network.

USE CASE 3

Run a self-contained VPN for a small organization that needs full control over network configuration.

USE CASE 4

Build a private network across cloud instances, servers, and personal devices without external dependencies.

Tech stack

GoProtobufWireGuardNixOS

Getting it running

Difficulty · hard Time to first run · 1h+

Requires understanding of WireGuard, VPN networking concepts, and likely needs to be deployed on a server with proper network configuration.

Use freely for any purpose, including commercial use, as long as you keep the copyright notice and license text.

In plain English

Headscale is an open-source, self-hosted replacement for the Tailscale coordination server, written in Go. To understand what that means, some context helps: Tailscale is a modern VPN (virtual private network) that uses WireGuard, a fast, secure tunneling protocol, to connect your devices into a private mesh network. Your phones, laptops, servers, and cloud machines can all reach each other as if they were on the same local network, even behind firewalls and NAT (Network Address Translation, the mechanism that lets many devices share one public IP address). Tailscale handles this seamlessly, but one piece of it, the control server that manages encryption keys, assigns IP addresses, and keeps track of which devices belong to which network, is proprietary and hosted by Tailscale Inc. Headscale reimplements that control server so you can run it yourself on your own hardware. Your devices still use the standard, open-source Tailscale client software, but instead of phoning home to Tailscale's cloud, they register with your self-hosted Headscale instance. This gives you full control over your network configuration and avoids any dependency on a third-party service. You would use Headscale when you want a Tailscale-style private mesh network but need it to be entirely self-contained, for a home lab, a small organisation, or any situation where sending device metadata to an external server is undesirable. It is designed for personal use or small teams, not enterprise-scale deployments. The tech stack is Go, with Protobuf-defined APIs. It supports NixOS as a first-class deployment target and ships binary builds as well. Contributors need Go and the Buf Protobuf code generator.

Copy-paste prompts

Prompt 1
How do I install and configure Headscale to replace my Tailscale control server?
Prompt 2
Show me how to register Tailscale clients with my self-hosted Headscale instance.
Prompt 3
What are the steps to deploy Headscale on NixOS for a home lab?
Prompt 4
How do I manage users, devices, and network routes in Headscale?
Prompt 5
Can you explain how Headscale handles encryption keys and device authentication?
Open on GitHub → Explain another repo

Generated 2026-05-18 · Model: sonnet-4-6 · Verify against the repo before relying on details.