Install guide · Debian 12 (bookworm)printed 29 Oct 2026, 02:20 UTC

Install headscale 0.29 on Debian 12

Debian 12 doesn't ship headscale. The current release is 0.29.6. freshdeb builds it for bookworm from upstream's release with packaging in Debian's style, so it updates with apt upgrade like the rest of the system.

Debian 12 ships: nothing
v0.29: 0.29.6stays on 0.29.x, patch releases only. Currently 0.29.6.
Built for: amd64 and arm64, natively

1Trust the signing key (once per machine)

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.freshdeb.com/freshdeb-archive-keyring.gpg \
  | sudo tee /etc/apt/keyrings/freshdeb-archive-keyring.gpg >/dev/null

Fingerprint 3BBD F03A 9C0B F890 F8CA 9510 7595 CC55 468F 3161. How to verify.

2Add the source for bookworm

sudo tee /etc/apt/sources.list.d/freshdeb-headscale.sources >/dev/null <<EOF
Types: deb
URIs: https://deb.freshdeb.com/headscale
Suites: bookworm
Components: latest
Signed-By: /etc/apt/keyrings/freshdeb-archive-keyring.gpg
EOF

latest mirrors v0.29, currently 0.29.6, and moves when a newer line takes over. Other components: v0.29, listed with the versions.

3Install

sudo apt update && sudo apt install headscale
apt policy headscale   # expect 0.29.6-2+freshdeb~deb12

How it's packaged.

Before you install

Neither Debian nor Ubuntu ship headscale: the packaging is ours, written the way Debian would, and there's nothing to replace.

First: Upstream's .deb upgrades in place. headscale moves one minor at a time (0.28 → 0.29 → 0.30): pin a minor's component and move to the next after reading its release notes, or follow latest if you keep up with every release. Back up /etc/headscale and /var/lib/headscale first, as upstream's upgrade guide says. If you changed config.yaml, the new example lands next to it as config.yaml.dpkg-dist, and headscale refuses to start on keys a minor removed, naming them.

Why a package

Upstream publishes a .deb with each release but no APT repository, so every update is a manual download. This repository serves the same layout, upgrades an installed upstream .deb in place, and keeps each minor as its own line, because headscale upgrades one minor at a time.

headscale elsewhere

headscale: every release line, its contents and origin