AltFreeStack
ESEN
Auth & Identitydocker-readypermissive-license100% FOSS🟢 Lightweight · ~256MB

Headscale: Open Source alternative to Tailscale in 2026

Headscale is an open source implementation of Tailscale's coordination server: build your own encrypted WireGuard mesh network using the official clients, without relying on the commercial control plane.

Alternative to Tailscale
License BSD-3-Clause44.6k starsWebsite GitHub Repository

Audit Snapshot

View notes →

  • License — Matches GitHub

  • GitHub — Active

  • Latest release — v0.29.5 · today

  • Docker Compose — Partial

  • Production — Not production-tested by AltFreeStack

Headscale vs. Tailscale

Pros

  • Works with the official Tailscale app on every device
  • Zero dependency on Tailscale Inc.'s commercial control plane

Things to consider

  • Requires editing a YAML config file, not everything is environment-variable driven
  • Some new official client features take time to land in Headscale

Quick Docker installation guide

Copy this docker-compose.yml, adjust the example passwords and run docker compose up -d on your server. See the full step-by-step guide →

💡 Official SaaS or self-hosted with AltFreeStack?

  • On the official cloud: a recurring monthly fee and usage limits on Tailscale.
  • On your own VPS: 100% free software on your own server, with no artificial row, project or user limits.
docker-compose.yml
# Headscale necesita un archivo config.yaml montado además de las
# variables de entorno — copia el config-example.yaml oficial antes de
# arrancar:
services:
  headscale:
    image: headscale/headscale:0.29.4
    restart: unless-stopped
    command: serve
    ports:
      - "8080:8080"
    volumes:
      - ./config:/etc/headscale
      - headscale_data:/var/lib/headscale
volumes:
  headscale_data:

🚀 Deploy in 1 command

Recommended for beginners

Copy this single command and paste it into your freshly created VPS's console (Vultr, DigitalOcean...). It downloads the script, prints it to your screen so you can see exactly what it's about to do (never a blind direct pipe), and only then installs Docker if needed, writes the files with secrets already generated, and starts everything — no nano, no pasting code blocks.

curl -sSL ".../api/deploy?stack=headscale" -o deploy.sh && cat deploy.sh && bash deploy.sh
See what this script does →

This docker-compose corresponds to an actively maintained project — last commit today.

This docker-compose not working for you? Report it on GitHub →

Technical profile

License
BSD-3-Clause
Category
Auth & Identity
Replaces
Tailscale
Tech stack
GoSQLite

Under the hood

Database

SQLite / PostgreSQL

Language

Go

Platforms

Web · Desktop (Mac/Win/Linux) · Mobile (iOS/Android)

Key features

  • Compatible with official Tailscale clients on every device
  • Encrypted WireGuard mesh network under the hood
  • Supports ACLs, exit nodes and subnets just like the commercial service

Frequently asked questions

What is Headscale?

An open source implementation (BSD-3-Clause) of Tailscale's coordination server: it builds your own encrypted mesh network with WireGuard using the same official clients, with no dependency on Tailscale Inc.'s commercial control plane.

Do I need Headscale's own client, or Tailscale's?

You use the official Tailscale clients on all your devices — Headscale only replaces the coordination server (control plane) they connect to, not the client.

Does Headscale support ACLs and exit nodes like the commercial service?

Yes, it supports ACLs, exit nodes, and subnets just like Tailscale Inc. In exchange, it requires editing a YAML config file — not everything is controlled through environment variables alone.

💾 Backups in 3 steps (Day 2)

As long as the ./data folder (the "volume" mapped into the container) exists on your server, your data survives any restart or container update — that's the only thing you need to back up.

1. Create a compressed backup on the server

tar -czvf backup-$(date +%F).tar.gz ./data

2. Download it to your computer

From your computer's terminal (not your server's):

scp root@YOUR_IP:~/app/backup-*.tar.gz ./

3. Restore in case of emergency

tar -xzvf backup-file.tar.gz
🌐 Connect your domain with free SSL

Step 1 — Set up the DNS

In your domain registrar's dashboard (Cloudflare, Namecheap, GoDaddy...), create a record:

Type
A
Name/Host
@ (root domain) or a subdomain, e.g. app
Content/Value
Your server's public IP

Wait 5 to 15 minutes for the record to propagate across the internet.

Step 2 — Automatic reverse proxy with Caddy

One single file, no Nginx config or manual certificates — Caddy issues and renews Let's Encrypt HTTPS on its own.

Create a file called Caddyfile:

yourdomain.com {
    reverse_proxy localhost:8080
}

Start Caddy with this command (pulls the image and runs it in the background):

docker run -d -p 80:80 -p 443:443 --name caddy --restart always -v $PWD/Caddyfile:/etc/caddy/Caddyfile -v caddy_data:/data caddy