hwdsl2/headscale-server repository overview

⁠Headscale Server on Docker

GitHub: https://github.com/hwdsl2/docker-headscale⁠

Docker image to run a Headscale⁠ server — a self-hosted, open-source implementation of the Tailscale coordination server. Connect all your devices using the official Tailscale client apps, with your own server in control.

Features:

• Automatically generates server configuration and a pre-auth key on first start
• Manage users, nodes and pre-auth keys via a helper script (hs_manage)
• MagicDNS support for seamless hostname resolution across your network
• Persistent data via a Docker volume
• Multi-arch: linux/amd64, linux/arm64

Also available:

• Without Docker: Headscale install script⁠
• VPN: WireGuard⁠, OpenVPN⁠, IPsec VPN⁠
• AI/Audio: Whisper (STT)⁠, Kokoro (TTS)⁠, Embeddings⁠, LiteLLM⁠

⁠Quick start

⁠Prerequisites

A publicly reachable server with a domain name and TLS certificate is strongly recommended. See TLS and reverse proxy⁠ for setup options.

⁠Using Docker

Create a vpn.env file. HS_SERVER_URL is the HTTPS URL that Tailscale clients use to connect to your server. See Environment variables⁠ for all options.

HS_SERVER_URL=https://hs.example.com

Run the container:

docker run \
  --name headscale \
  --restart=always \
  -p 127.0.0.1:8080:8080/tcp \
  -v headscale-data:/var/lib/headscale \
  -v ./vpn.env:/vpn.env:ro \
  -d hwdsl2/headscale-server

Note: With the above command, port 8080 is bound to localhost only. A reverse proxy on the host that handles TLS and forwards to 127.0.0.1:8080 is required for Tailscale clients to connect. See TLS and reverse proxy⁠. To expose the port directly instead, replace 127.0.0.1:8080:8080 with 8080:8080.

Alternatively, you may set up Headscale without Docker⁠. To learn more about how to use this image, read the sections below.

On first start, the container will:

1. Generate the server configuration from your environment variables
2. Create the initial user (default: admin)
3. Print a reusable pre-auth key to the container logs

Retrieve the initial pre-auth key from the logs:

docker logs headscale

Connect a device using the official Tailscale client⁠:

tailscale up --login-server https://hs.example.com --authkey <key-from-logs>

⁠Using Docker Compose

cp vpn.env.example vpn.env
nano vpn.env        # Set HS_SERVER_URL at minimum
docker compose up -d
docker compose logs headscale

Example docker-compose.yml (already included):

services:
  headscale:
    image: hwdsl2/headscale-server
    container_name: headscale
    restart: always
    ports:
      - "127.0.0.1:8080:8080/tcp"
    volumes:
      - headscale-data:/var/lib/headscale
      - ./vpn.env:/vpn.env:ro

volumes:
  headscale-data:

⁠Download

Get the trusted build from the Docker Hub registry⁠:

docker pull hwdsl2/headscale-server

Alternatively, you may download from Quay.io⁠:

docker pull quay.io/hwdsl2/headscale-server
docker image tag quay.io/hwdsl2/headscale-server hwdsl2/headscale-server

Supported platforms: linux/amd64 and linux/arm64.

⁠Client configuration

Refer to the Headscale documentation for instructions on connecting clients:

• Android⁠
• Apple (iOS / macOS)⁠
• Windows⁠

⁠Environment variables

All variables are optional. HS_SERVER_URL is strongly recommended for production use.

Note: In your env file, you may enclose values in single quotes, e.g. VAR='value'. Do not add spaces around =.

The configuration file is regenerated on each container start. To change a setting, update vpn.env and restart the container. The env file is bind-mounted into the container, so changes are picked up on every restart without recreating the container.

⁠TLS and reverse proxy

Tailscale clients work best with HTTPS. The recommended setup is to run a reverse proxy in front of Headscale that handles TLS termination, then set HS_SERVER_URL to your HTTPS URL.

Use one of the following addresses to reach the Headscale container from your reverse proxy:

• headscale:8080 — if your reverse proxy runs as a container in the same Docker network as Headscale (e.g. defined in the same docker-compose.yml). Docker resolves the container name automatically.
• 127.0.0.1:8080 — if your reverse proxy runs on the host and port 8080 is published (the default docker-compose.yml publishes it).

Note: Do not use the container's internal IP address obtained from docker inspect. That IP address changes every time the container is recreated.

Example with Caddy⁠ (Docker image⁠) (automatic TLS via Let's Encrypt, reverse proxy in the same Docker network):

Caddyfile:

hs.example.com {
  reverse_proxy headscale:8080
}

Example with nginx (reverse proxy on the host):

server {
  listen 443 ssl;
  server_name hs.example.com;

  ssl_certificate     /path/to/cert.pem;
  ssl_certificate_key /path/to/key.pem;

  location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 3600s;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
  }
}

Set HS_SERVER_URL=https://hs.example.com in your vpn.env and restart the container.

Ports to open in your firewall:

⁠Managing the server

Use the hs_manage helper to manage users and nodes from the host without entering the container.

Register a node by its node key:

docker exec headscale hs_manage --registernode <key> --user admin

Add a user:

docker exec headscale hs_manage --adduser alice

Delete a user:

docker exec -it headscale hs_manage --deleteuser alice
# Or skip the confirmation prompt:
docker exec headscale hs_manage --deleteuser alice --yes

Create a pre-auth key for a user:

docker exec headscale hs_manage --createkey --user alice

List users:

docker exec headscale hs_manage --listusers

List all registered nodes:

docker exec headscale hs_manage --listnodes

List nodes for a specific user:

docker exec headscale hs_manage --listnodes --user alice

Delete a node by ID:

docker exec -it headscale hs_manage --deletenode 3
# Or skip the confirmation prompt:
docker exec headscale hs_manage --deletenode 3 --yes

List all pre-auth keys:

docker exec headscale hs_manage --listkeys

Show help:

docker exec headscale hs_manage --help

You can also run Headscale commands directly using docker exec headscale headscale <command>. Run docker exec headscale headscale -h or refer to the Headscale documentation⁠ for available commands.

⁠Update Docker image

To update the Docker image and container, first download⁠ the latest version:

docker pull hwdsl2/headscale-server

If the Docker image is already up to date, you should see:

Status: Image is up to date for hwdsl2/headscale-server:latest

Otherwise, it will download the latest version. Remove and re-create the container using instructions from Quick start⁠. Your data is preserved in the headscale-data volume.

⁠Technical details

• Base image: alpine:3.23
• Headscale: 0.28.0
• Data directory: /var/lib/headscale (Docker volume)
• Configuration: generated from vpn.env on every container start; update vpn.env and restart to apply changes (no container re-creation needed)
• Ports: 8080/tcp (coordination server), 9090/tcp (Prometheus metrics, optional)
• Platforms: linux/amd64, linux/arm64

⁠License

Note: The software components inside the pre-built image (such as Headscale) are under the respective licenses chosen by their respective copyright holders. As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

Copyright (C) 2026 Lin Song
This work is licensed under the MIT License⁠.

Headscale is Copyright (c) 2020, Juan Font, and is distributed under the BSD 3-Clause License⁠.

Tailscale® is a registered trademark of Tailscale Inc. This project is not affiliated with or endorsed by Tailscale Inc.