explaingit

juanfont/headscale

Analysis updated 2026-06-20

38,107GoAudience · ops devopsComplexity · 4/5Setup · moderate

TLDR

Headscale is a self-hosted, open-source replacement for Tailscale's coordination server, letting you run a private WireGuard mesh network across all your devices without depending on any third-party cloud service.

Mindmap

mindmap
  root((headscale))
    What it does
      Self-hosted VPN control
      WireGuard mesh
      No cloud dependency
    How it works
      Tailscale client compatible
      Key management
      IP assignment
    Use cases
      Home lab networking
      Small team VPN
      De-Googled setup
    Tech stack
      Go
      WireGuard
      Protobuf
      NixOS
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

What do people build with it?

USE CASE 1

Connect all your home lab devices into a private mesh network you fully control, without sending device metadata to Tailscale's servers.

USE CASE 2

Set up a secure private network for a small team so remote employees can reach internal servers through WireGuard without a traditional VPN appliance.

USE CASE 3

Run on a de-Googled or self-hosted server to keep all network configuration and device registration entirely off third-party infrastructure.

USE CASE 4

Deploy on NixOS as a first-class target and manage the full WireGuard key lifecycle with your own tooling and policies.

What is it built with?

GoWireGuardProtobufNixOS

How does it compare?

juanfont/headscaleistio/istioxtls/xray-core
Stars38,10738,16738,207
LanguageGoGoGo
Setup difficultymoderatehardhard
Complexity4/54/53/5
Audienceops devopsops devopsops devops

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · moderate Time to first run · 1h+

Requires a publicly reachable server and Tailscale clients on each device reconfigured to point to your Headscale instance instead of tailscale.com.

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
Help me install Headscale on my Linux VPS so that my laptop and home server connect through WireGuard without using Tailscale's cloud coordination server.
Prompt 2
Show me how to register a new device with my self-hosted Headscale instance by configuring the Tailscale client to point to my server's URL instead of tailscale.com.
Prompt 3
I want to deploy Headscale on NixOS. Walk me through the NixOS module configuration and getting my first device registered and reachable.
Prompt 4
How do I create user accounts, generate pre-auth keys, and set ACL policies in Headscale using its CLI?
Prompt 5
My Headscale server is running but two devices cannot reach each other directly. Help me debug the DERP relay configuration and NAT traversal settings.

Frequently asked questions

What is headscale?

Headscale is a self-hosted, open-source replacement for Tailscale's coordination server, letting you run a private WireGuard mesh network across all your devices without depending on any third-party cloud service.

What language is headscale written in?

Mainly Go. The stack also includes Go, WireGuard, Protobuf.

How hard is headscale to set up?

Setup difficulty is rated moderate, with roughly 1h+ to a first successful run.

Who is headscale for?

Mainly ops devops.

Open on GitHub → Explain another repo

This repo across BitVibe Labs

Scan in gitsafehub Deploy in gitdeployhub juanfont on gitmyhub

Verify against the repo before relying on details.