replacing tailscale with headscale

Stub i haven't finished writing this yet. i publish drafts early as part of WFD 17.

i used Tailscale to access my homelab. Proxmox box, k3s cluster on top, a few services (WFD 15 covers the stack). install the client, authenticate, everything gets a stable IP, MagicDNS gives names. painless.

i didn't have a strong reason to replace it. the free tier covers 100 devices and 3 users which is more than i'll ever need. the control plane still knows every device on my network though, their IPs, their keys, and which subnets they can reach. i already had a box that could run this myself, so i did.

Headscale is a self-hosted, open source implementation of the Tailscale control plane. 35.9k stars, BSD-3 license, v0.28.0 as of Feb 2026. one of the maintainers works at Tailscale and is allowed to work on Headscale during business hours, which is about as close to an endorsement as you'll get from an upstream vendor for an alternative implementation.

what headscale is

Tailscale has two parts: the client (open source, runs on your devices) and the control plane (proprietary, hosted by Tailscale). the control plane handles key exchange, peer discovery, NAT traversal, DNS, and ACL enforcement. the clients do the WireGuard tunneling peer-to-peer.

Headscale replaces the control plane. the clients stay the same. you point tailscale up --login-server https://headscale.example.com at your instance and everything else works.

graph TD
    TC["Tailscale control plane (hosted by Tailscale Inc)"] --- T1[macbook]
    TC --- T2[phone]
    TC --- T3[pixie]
    T1 ---|WireGuard peer-to-peer| T2
    T1 ---|WireGuard peer-to-peer| T3
    T2 ---|WireGuard peer-to-peer| T3

graph TD
    HC["Headscale (self-hosted on pixie)"] --- H1[macbook]
    HC --- H2[phone]
    HC --- H3[aurora]
    H1 ---|WireGuard peer-to-peer| H2
    H1 ---|WireGuard peer-to-peer| H3
    H2 ---|WireGuard peer-to-peer| H3

traffic goes peer-to-peer between clients. the control plane only handles discovery. if NAT traversal fails, traffic routes through DERP relays (Headscale can embed its own).

DERP (Designated Encrypted Relay for Packets) is Tailscale's fallback relay. when two devices can't punch through NAT directly, traffic gets encrypted end-to-end and bounced through a DERP server. the relay can't read anything, it just forwards bytes. Headscale can run its own DERP server or use Tailscale's public ones.

feature parity

what i used from Tailscale and whether Headscale covers it:

none of the missing stuff matters for a homelab.

where it runs

it needs to be reachable for devices to find each other. if it lives inside the homelab and Proxmox goes down, nothing can reconnect. a $5 VPS would fix that, and i only have one site, so if Proxmox is down i can't reach anything regardless. LXC container on Proxmox it is.

LXC setup

Headscale is a single Go binary with no kernel dependencies, so a Debian LXC with 128MB RAM runs it fine.

wget https://github.com/juanfont/headscale/releases/download/v0.28.0/headscale_0.28.0_linux_amd64.deb
dpkg -i headscale_0.28.0_linux_amd64.deb
systemctl enable --now headscale

config at /etc/headscale/config.yaml:

server_url: https://headscale.pixie.local
listen_addr: 0.0.0.0:8080
noise:
  private_key_path: /var/lib/headscale/noise_private.key
prefixes:
  v4: 100.64.0.0/10
  allocation: sequential
dns:
  base_domain: tail.home
  magic_dns: true
  nameservers:
    global:
      - 1.1.1.1
  extra_records:
    - name: "grafana.tail.home"
      type: "A"
      value: "100.64.0.3"
    - name: "pixie.tail.home"
      type: "A"
      value: "100.64.0.1"
database:
  type: sqlite
  sqlite:
    path: /var/lib/headscale/db.sqlite

100.64.0.0/10 is the CGNAT range that Tailscale reserves for device IPs. it won't collide with your LAN. every device on the mesh gets a stable 100.x.x.x address.

Headscale recommends SQLite over PostgreSQL. from the config comments: "All new development, testing and optimisations are done with SQLite in mind."

i already had a Caddy LXC handling TLS for other services so that sits in front.

routing into k8s

pod CIDR is 10.42.0.0/16, service CIDR is 10.43.0.0/16. the same cluster running the stuff from WFD 13 and WFD 21. to reach pods and services from my laptop over the mesh, one of the k3s nodes advertises those subnets as routes.

subnet routing lets a node on the mesh act as a gateway to a local network. aurora advertises the k3s pod and service CIDRs, so any device on the tailnet can reach cluster IPs without being inside the cluster itself. the traffic goes laptop → aurora (via WireGuard) → k3s network.

# may@aurora
sudo tailscale up --login-server https://headscale.pixie.local \
  --advertise-routes=10.42.0.0/16,10.43.0.0/16

approve the routes:

headscale routes list
headscale routes enable -r <route-id>

or set up auto-approval in the ACL policy:

{
  "tagOwners": {
    "tag:k8s": ["may@"]
  },
  "autoApprovers": {
    "routes": {
      "10.42.0.0/16": ["tag:k8s"],
      "10.43.0.0/16": ["tag:k8s"]
    }
  },
  "acls": [
    { "action": "accept", "src": ["*"], "dst": ["*:*"] }
  ]
}

after this, kubectl works from my laptop without port forwarding or a VPN gateway and any device on the mesh can hit k8s services by cluster IP.

terraform

there's a Terraform provider: awlsring/headscale. v0.5.0 supports Headscale v0.28.x.

terraform {
  required_providers {
    headscale = {
      source  = "awlsring/headscale"
      version = "0.5.0"
    }
  }
}

provider "headscale" {
  api_key  = var.headscale_api_key
  endpoint = "https://headscale.pixie.local"
}

resource "headscale_user" "may" {
  name = "may"
}

resource "headscale_pre_auth_key" "k8s_nodes" {
  user            = headscale_user.may.name
  reusable        = true
  ephemeral       = false
  time_to_expire  = "8760h"
  acl_tags        = ["tag:k8s"]
}

the pre-auth key automates node registration. i pass it to cloud-init when provisioning k3s VMs so they join the mesh on boot.

a pre-auth key lets a device register with the control plane without interactive login. cloud-init runs on first boot, calls tailscale up --authkey <key>, and the VM joins the mesh automatically. combined with the tag:k8s ACL tag, the auto-approver kicks in and the subnet routes are approved without manual intervention.

i manage my homelab with OpenTofu and the Proxmox provider already. adding the Headscale provider means users, keys, and ACL policies live alongside the VM definitions. one tofu apply and a node exists, is registered, and has its routes approved. that felt good the first time i ran it.

was it worth it

arguments against:

• Tailscale worked and i added maintenance for no functional gain
• Headscale has no web UI (third-party options exist, they're separate projects)
• debugging connection issues is harder without Tailscale's admin console

arguments for:

• i own the coordination data
• one less external dependency
• the Terraform provider lets me manage it as code alongside everything else
• i learned more about how Tailscale actually works under the hood

this XDA article has it right: "most people probably shouldn't" switch. Tailscale's free tier is generous and the managed experience is better. i just wanted to.

references

• Headscale GitHub
• Headscale docs
• Headscale config reference
• awlsring/headscale Terraform provider
• FOSDEM 2026: Headscale & Tailscale