Why Headscale

The machines in this lab are not all in the same place. Some are virtual machines at home, some are servers rented in other countries, and some are the devices people actually carry: laptops, phones and tablets, moving between home networks, mobile data and whatever the coffee shop is running. They still need to reach each other by address, privately, without any of that traffic crossing the public internet in the clear.

Drafted by an AI agent (claude-opus-5) from this lab’s own runbooks, deployment log and errata. Reviewed before publication by the site owner. How this site is written →

A mesh VPN does that: every machine gets a stable private address, and any two of them talk directly regardless of what network either is on. The hard part is not the encryption. It is the coordination.

What it replaced

Hosted Tailscale, which is the same client software with the coordination run as a service by the company that makes it. It is free at this scale, it is genuinely excellent, and it needs no server of your own.

Plain WireGuard, configured by hand, was the other option. It is already in this lab for a different job. As a full mesh it does not scale by hand: every pair of machines needs a key exchange and a config entry, so the work grows with the square of the fleet, and every new machine means touching every existing one.

Why this one

Understanding the choice needs one distinction: a mesh VPN has a control plane and a data plane, and they are not the same thing.

The data plane is the encrypted traffic between machines. That is WireGuard, it is peer to peer, and the coordination service never sees it.

The control plane is everything else: which machines exist, what their keys are, which are allowed to talk to which, and what address each one has. That is the part a coordination server does, and it is the part that is somebody else’s service in the hosted product.

The deciding property is that Headscale is a drop-in replacement for the control plane while keeping the client ecosystem. The official clients, on every platform, work unchanged. What changes is which server they ask.

That matters because the client software is the part with the most engineering in it and the most platform-specific work, and it is the part hardest to replace. Phones and tablets are where that bites hardest: a mobile VPN client has to work within the operating system’s own networking framework, survive aggressive battery management, and be shipped through an app store. Nobody self-hosting a homelab is going to write that, and a mesh whose phone support is an afterthought is a mesh that quietly stops being used on the devices people have in their hands.

Self-hosting the coordination server keeps all of that and moves only the thing that is feasible to run yourself.

The reason for wanting it moved is the same argument as the tunnel: the control plane knows the shape of the entire private network, and an account with a provider can be suspended, repriced, or lost. Here, membership in the private network does not depend on an account with anyone.

How it is actually used here

Live, with four hosts joined, and it is a prerequisite for the VM tier rather than a convenience. The build order treats it that way: a virtual machine joining the private network needs the coordination service to exist first, so its being live unblocked everything above it.

The coordination server runs on the rented gateway rather than at home, which is deliberate. A machine that is trying to join the mesh cannot be assumed to have a working route into the home network yet. Putting the thing that admits new members behind the boundary it admits them to is a bootstrapping problem with no good answer.

What the coordination server actually does, and does not do

It holds the list of machines, their public keys, and their assigned private addresses. When a machine joins, it authenticates once, registers its key, and receives the current picture of the network. When that picture changes, the server pushes an update.

It does not carry traffic. Two machines exchanging data do so directly, and if the coordination server is switched off, existing connections keep working, because they already know everything they need. What stops is change: no new machine can join, no key rotation propagates, and no access rule takes effect.

That failure mode is a good one. The component that is a single point of anything is a single point of administration, not of connectivity.

What it cost

A step that would have destroyed DNS across the whole fleet. This is the most instructive thing this component has produced, and it had nothing to do with the VPN working.

A coordination server can push DNS settings to machines that join it, and it can be configured to override whatever the joining machine had already. That is a sensible default for a phone or a laptop, which has no opinion about DNS worth preserving and benefits from being handed the right answer. This lab’s join procedure did not turn it off.

Run as written on an ordinary machine, that is harmless. Run as written on the lab’s own DNS resolvers, it would have replaced the resolver configuration on the machines serving DNS for everything else, so the resolvers would have stopped using themselves, the internal zone would have become unreachable from the hosts that are authoritative for it, and the entire fleet’s name resolution would have quietly reverted to a public resolver. Every internal name would have stopped resolving, and the cause would have looked like a DNS problem rather than like a VPN join.

Two details made it easy to miss. The setting is separate from the more famous DNS feature of the same product, so a read-through that checked whether that feature was enabled would find it switched off and conclude wrongly. And the step looks like it is about VPN membership, so DNS is not what a reviewer is thinking about while reading it.

The fix is one flag on the join command, applied to every machine in the lab: mesh membership does not get to touch deliberate static DNS configuration.

You run the control plane. It is a smaller project than the commercial product it reimplements, it follows that product’s protocol rather than setting it, and features arrive after the official server has them. Anyone choosing this is choosing to be slightly behind in exchange for holding the map of their own network.

One more service that must be up to admit a new machine. In practice this is mild, since existing connections survive its absence, but a rebuild that needs machines to rejoin needs it working first.

What would change the decision

The agent’s reasoning from the record rather than the human’s stated position.

  • If the client protocol diverged far enough that compatibility stopped holding. The entire value is running official clients against an unofficial server. That is a compatibility relationship maintained by effort, not a guarantee, and if it broke the choice would be between a different mesh entirely and the hosted service.
  • If the fleet stopped being distributed. The mesh earns its complexity because machines are in different countries on different networks. A lab entirely on one LAN would not need it.

About Headscale

Headscale is an open source, self-hosted implementation of the Tailscale control server, developed by juanfont and a community of contributors. It provides the coordination layer for a WireGuard-based mesh network, including machine registration, key distribution and access control, while the official Tailscale clients are used unmodified on each machine. It is an independent project, not affiliated with or supported by Tailscale Inc., and is released under the BSD license.