Packages / headscale
APT repository · deb.freshdeb.com/headscaleprinted 28 Oct 2026, 08:16 UTC
headscale
headscale, an open source implementation of the Tailscale control server. Your Tailscale clients log in to your own server instead of Tailscale's. The APT repository upstream doesn't publish, laid out like upstream's own .deb. One release line for Debian 12 and 13, Ubuntu 22.04, 24.04 and 26.04 on amd64 and arm64.
latest 0.29.6github.com/juanfont/headscaleupstream sourcepackaging
Componentlatest
mirrors v0.29, currently 0.29.6, and moves when a newer line takes over.
Not published yet. The first headscale release is being built. These commands will work once it lands at deb.freshdeb.com/headscale; the versions shown are the ones package.yaml will publish.
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
sudo tee /etc/apt/sources.list.d/freshdeb-headscale.sources >/dev/null <<EOF
Types: deb
URIs: https://deb.freshdeb.com/headscale
Suites: $(. /etc/os-release && echo $VERSION_CODENAME)
Components: latest
Signed-By: /etc/apt/keyrings/freshdeb-archive-keyring.gpg
EOFWith auto, the shell reads the codename from /etc/os-release on the machine you paste this into.
3Install
sudo apt update && sudo apt install headscale
apt policy headscale # expect 0.29.6-1+freshdeb~…Before you install headscale
Neither Debian nor Ubuntu ship headscale. 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.
How it's packaged
No distribution packages headscale, so the packaging is ours, written the way Debian would. The build, the defaults and the layout follow upstream's wherever upstream has them.
- Distributions
- None ship headscale. Upstream publishes a .deb with each release but no APT repository. This package is laid out like upstream's and also called
headscale, so it upgrades an installation of upstream's .deb in place. - Build
- Upstream's release build:
CGO_ENABLED=0,-s -w, the pinned Go toolchain and vendored modules verified against go.sum. Upstream's unit tests gate the build. - Version
- A patch of ours lets the build set the version, commit and build time, which upstream reads from git. Built from the release's source without it, headscale says
devand skips its database version check. - Layout
- Upstream's:
/usr/bin/headscale,/etc/headscale/config.yaml(upstream's example, a conffile), data in/var/lib/headscale, theheadscaleuser and upstream's sandboxedheadscale.service, enabled and started on install, listening on 127.0.0.1:8080. - Release lines
- One per minor, because headscale upgrades one minor at a time and refuses a database from further back. Older minors stay published as stepping stones.
- Purge
- Like upstream's .deb, purging removes the
headscaleuser and/var/lib/headscale, the database included.
Packing list
Every release line of headscale and the distributions it's built for. Each line is its own APT component and only gets the releases it follows (v0.29: 0.29.x, patch releases only). After upstream end of life it stops building but stays installable. Hatched cells have no build: usually that distribution already ships the same or a newer version itself.
| Line | Component | Current | bookwormDebian 12 | trixieDebian 13 | jammyUbuntu 22.04 | nobleUbuntu 24.04 | resoluteUbuntu 26.04 | Support |
|---|---|---|---|---|---|---|---|---|
| 0.29 | v0.29latest | 0.29.6 | built: 0.29.6-1 | built: 0.29.6-1 | built: 0.29.6-1 | built: 0.29.6-1 | built: 0.29.6-1 | – |
Versions follow <upstream>-<revision>+freshdeb~<distro>, distro being deb12, deb13, ubuntu22.04, ubuntu24.04 or ubuntu26.04, for amd64 and arm64. Published versions are never rebuilt or replaced.
Contents
- headscale
- The control server and its CLI, with shell completions.
Origin
- Upstream
- github.com/juanfont/headscalerelease tags pinned to commit hashes
- Packaging
- our own, in Debian's styleno distribution packages headscale
- Our changes
- Per-line quilt patches under
patches/. - Built for
- bookworm, trixie, jammy, noble, resoluteamd64, arm64, built natively
- Files
- package.yaml · debian/ · report an issuepackage.yaml explains every change
