Development builds¶

Each push to main produces container images and cross-compiled binaries. Container images are multi-arch (amd64, arm64) and use the same distroless base image as official releases.

Container images¶

Images are available from both Docker Hub and GitHub Container Registry, tagged with the short commit hash of the build (e.g. main-abc1234):

• Docker Hub: docker.io/headscale/headscale:main-<sha>
• GitHub Container Registry: ghcr.io/juanfont/headscale:main-<sha>

To find the latest available tag, check the GitHub Actions workflow or the GitHub Container Registry package page.

For example, to run a specific development build:

docker run \
  --name headscale \
  --detach \
  --read-only \
  --tmpfs /var/run/headscale \
  --volume "$(pwd)/config:/etc/headscale:ro" \
  --volume "$(pwd)/lib:/var/lib/headscale" \
  --publish 127.0.0.1:8080:8080 \
  --publish 127.0.0.1:9090:9090 \
  --health-cmd "CMD headscale health" \
  docker.io/headscale/headscale:main-<sha> \
  serve

See Running headscale in a container for full container setup instructions.

Binaries¶

Pre-built binaries from the latest successful build on main are available via nightly.link:

After downloading and extracting the archive, make the binary executable and follow the standalone binary installation instructions for setting up the service.