Skip to content

Running headscale on Linux

Note: Outdated and "advanced"

This documentation is considered the "legacy"/advanced/manual version of the documentation, you most likely do not want to use this documentation and rather look at the distro specific documentation (TODO LINK)[].


This documentation has the goal of showing a user how-to set up and run headscale on Linux. In additional to the "get up and running section", there is an optional SystemD section describing how to make headscale run properly in a server environment.

Configure and run headscale

  1. Download the latest headscale binary from GitHub's release page:

    wget --output-document=/usr/local/bin/headscale \<HEADSCALE VERSION>/headscale_<HEADSCALE VERSION>_linux_<ARCH>
  2. Make headscale executable:

    chmod +x /usr/local/bin/headscale
  3. Prepare a directory to hold headscale configuration and the SQLite database:

    # Directory for configuration
    mkdir -p /etc/headscale
    # Directory for Database, and other variable data (like certificates)
    mkdir -p /var/lib/headscale
    # or if you create a headscale user:
    useradd \
      --create-home \
      --home-dir /var/lib/headscale/ \
      --system \
      --user-group \
      --shell /usr/sbin/nologin \
  4. Create an empty SQLite database:

    touch /var/lib/headscale/db.sqlite
  5. Create a headscale configuration:

    touch /etc/headscale/config.yaml

    (Strongly Recommended) Download a copy of the example configuration from the headscale repository.

  6. Start the headscale server:

    headscale serve

    This command will start headscale in the current terminal session.

    To continue the tutorial, open a new terminal and let it run in the background. Alternatively use terminal emulators like tmux or screen.

    To run headscale in the background, please follow the steps in the SystemD section before continuing.

  7. Verify headscale is running: Verify headscale is available:

  8. Create a user (tailnet):

    headscale users create myfirstuser

Register a machine (normal login)

On a client machine, execute the tailscale login command:

tailscale up --login-server YOUR_HEADSCALE_URL

Register the machine:

headscale --user myfirstuser nodes register --key <YOUR_MACHINE_KEY>

Register machine using a pre authenticated key

Generate a key using the command line:

headscale --user myfirstuser preauthkeys create --reusable --expiration 24h

This will return a pre-authenticated key that can be used to connect a node to headscale during the tailscale command:

tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>

Running headscale in the background with SystemD

⚠ Deprecated: This part is very outdated and you should use the pre-packaged Headscale for this

This section demonstrates how to run headscale as a service in the background with SystemD. This should work on most modern Linux distributions.

  1. Create a SystemD service configuration at /etc/systemd/system/headscale.service containing:

    Description=headscale controller
    ExecStart=/usr/local/bin/headscale serve
    # Optional security enhancements
    ReadWritePaths=/var/lib/headscale /var/run/headscale

    Note that when running as the headscale user ensure that, either you add your current user to the headscale group:

    usermod -a -G headscale current_user

    or run all headscale commands as the headscale user:

    su - headscale
  2. In /etc/headscale/config.yaml, override the default headscale unix socket with path that is writable by the headscale user or group:

    unix_socket: /var/run/headscale/headscale.sock
  3. Reload SystemD to load the new configuration file:

    systemctl daemon-reload
  4. Enable and start the new headscale service:

    systemctl enable --now headscale
  5. Verify the headscale service:

    systemctl status headscale

    Verify headscale is available:


headscale will now run in the background and start at boot.