MirrorNest
← All guides

Headscale

Headscale is an open-source, self-hosted implementation of the Tailscale coordination server, letting you run your own private WireGuard-based mesh network without Tailscale's SaaS control plane.

Target: Debian 12+ / Ubuntu 22.04+NetworkingVPNOfficial homepage ↗Official docs ↗
This guide is synthesized from Headscale's own official documentation, linked above — always cross-check exact package/version names there before running these commands on a production server, since distro and project versions move over time.

  1. 1Download the official .deb package

    HEADSCALE_VERSION="0.23.0" # set to the version you want
    HEADSCALE_ARCH="amd64"
    wget --output-document=headscale.deb "https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_${HEADSCALE_ARCH}.deb"

    Check the releases page for the current version number before running this.

    Headscale releases ↗

  2. 2Install the package

    The .deb package creates a dedicated headscale user, default config, and a systemd unit for you.

    sudo apt install ./headscale.deb

  3. 3Configure and start headscale

    sudo nano /etc/headscale/config.yaml
    sudo systemctl restart headscale
    sudo systemctl status headscale