Development builds

!!! warning

Development builds are created automatically from the latest `main` branch
and are **not versioned releases**. They may contain incomplete features,
breaking changes, or bugs. Use them for testing only.

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.