Skip to content

Headscale

Headscale is an open source, self-hosted implementation of the Tailscale control server.

It allows you to create your own private mesh VPN using the WireGuard protocol, providing secure connectivity between your devices without relying on a third-party service.

Website
Headscale
License
BSD-3-Clause
Author
Florian Merz
Last changed
2026-11-11

Tested with Headscale 0.29.7 on Uberspace 8.0.100. We can't guarantee it to work with newer versions.

Report a guide issue

Note

For this guide you should be familiar with the basic concepts of:

License

Headscale is released under the BSD-3-Clause License.

All relevant legal information can be found in the LICENSE file in the repository of the project.

Prerequisites

If you want to use Headscale with your own domain you need to add it first.

Installation

Download the latest Headscale binary from the official GitHub releases page. Replace 0.29.7 with the latest version:

[isabell@stardust ~]$ wget -O ~/bin/headscale \
  https://github.com/juanfont/headscale/releases/download/v0.29.7/headscale_0.29.7_linux_amd64
[isabell@stardust ~]$ chmod +x ~/bin/headscale

By default, Headscale loads the configuration from $HOME/.headscale/config.yaml, so we continue with creating the directory:

[isabell@stardust ~]$ mkdir -p ~/.headscale

Then download the example configuration file:

[isabell@stardust ~]$ wget -O ~/.headscale/config.yaml \
  https://github.com/juanfont/headscale/raw/v0.29.7/config-example.yaml

Configuration

Configure Headscale for the Uberspace web backend

Edit ~/.headscale/config.yaml and adjust the following values. Replace isabell with your username and isabell.uber.space with your domain.

Warning

Review the rest of the configuration and adjust it to suit your environment. At minimum, set server_url, listen_addr, private_key_path, unix_socket, and database.sqlite.

Note

Uberspace's web backend handles HTTPS. Leave tls_cert_path and tls_key_path empty in the Headscale configuration. See Headscale's TLS documentation for more information.

For a minimal setup, set these values:

server_url: "https://isabell.uber.space:443"
listen_addr: "0.0.0.0:8080"

tls_cert_path: ""
tls_key_path: ""

unix_socket: "/home/isabell/.headscale/headscale.sock"

noise:
  private_key_path: "private.key"

database:
  type: sqlite

  sqlite:
    path: "db.sqlite"

Generate a private key for WireGuard:

[isabell@moondust ~]$ headscale generate private-key > ~/.headscale/private.key

Note

For further configuration options, see Headscale's configuration documentation.

Validate the configuration:

[isabell@moondust ~]$ headscale configtest

If the command reports no errors, test the daemon by running headscale serve in a terminal. Stop it with Ctrl+C after confirming that it starts without errors.

Set up the service

Create and start a systemd service for Headscale:

[isabell@moondust ~]$ uberspace service add headscale "$HOME/bin/headscale serve" --workdir "$HOME/.headscale"

Check the service status and logs if it does not start:

[isabell@moondust ~]$ systemctl --user status headscale
[isabell@moondust ~]$ journalctl --user -u headscale

Configure the Uberspace web backend

Connect the web backend to the running Headscale service on port 8080:

[isabell@moondust ~]$ uberspace web backend add isabell.uber.space port 8080

The Uberspace web backend handles HTTPS and proxies requests, including WebSockets, to Headscale.

Usage

Once Headscale is running, create a user:

[isabell@moondust ~]$ headscale users create <USER>

Create a preauth key for device registration. Get the <USER-ID> with headscale users list:

[isabell@moondust ~]$ headscale preauthkeys create --user <USER-ID>

Install the Tailscale client on your device, then use the preauth key there:

[localuser@localhost ~]$ tailscale up --login-server https://isabell.uber.space --authkey <PREAUTHKEY>

For more commands, run headscale help or see the official documentation.

Updates

Note

Check the release page regularly.

Follow Headscale's upgrade instructions, including release-specific configuration changes, and do not skip minor versions. Stop the service and back up its configuration, keys and database before replacing the running binary:

[isabell@moondust ~]$ systemctl --user stop headscale
[isabell@moondust ~]$ cp -a ~/.headscale ~/.headscale.backup-$(date +%Y%m%d%H%M%S)

Download the new binary using the installation command above, validate the configuration, then start the service:

[isabell@moondust ~]$ headscale configtest
[isabell@moondust ~]$ systemctl --user start headscale