Headscale Setup

Overview

Headscale is a self-hosted, open-source implementation of the Tailscale control server. It creates a mesh VPN that lets your devices communicate securely as if they were on the same local network, regardless of where they are.

Important: Headscale is a coordination server only. It manages authentication, distributes encryption keys, and helps devices find each other. It does NOT route your traffic - devices connect directly to each other (P2P).

┌─────────────────────────────────────────────────────────┐
│                    Headscale Server                     │
│                    (Control Plane)                      │
│                                                         │
│   Coordinates connections, manages authentication,      │
│   distributes keys - but doesn't route traffic          │
└─────────────────────────────────────────────────────────┘
                           │
          ┌────────────────┼────────────────┐
          │                │                │
          ▼                ▼                ▼
     ┌─────────┐     ┌─────────┐     ┌─────────┐
     │ Laptop  │◄───►│ Phone   │◄───►│  Server │
     │ 100.64.x│     │ 100.64.x│     │ 100.64.x│
     └─────────┘     └─────────┘     └─────────┘
          │                │                │
          └────────────────┴────────────────┘
                 Direct P2P connections
                 (encrypted, no central routing)

With Headscale, you control your own coordination server instead of using Tailscale’s hosted service. Each device that connects to Headscale runs the Tailscale client.

Prerequisites

• VPS setup completed (see VPS Setup)
• UFW configured (see UFW Setup)
• nginx installed and configured (see nginx Setup)
• A domain pointed to your VPS IP (required for SSL)
• Port 443 available

Installation

Follow the official Headscale setup guide: https://headscale.net/stable/setup/requirements

Remember to configure config.yaml before starting the service.

Expose with HTTPS

Headscale runs on port 8080 by default and requires HTTPS to work properly.

Set up nginx as a reverse proxy (see nginx Setup) and obtain an SSL certificate (see SSL Setup).

Important for Headscale: Enable WebSocket support by adding these headers to your nginx config:

map $http_upgrade $connection_upgrade {
    default      upgrade;
    ''           close;
}

# In your server block location:
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;

This is required because Tailscale clients use WebSockets for real-time communication.

User Management

Headscale organizes devices by user. Create a user before connecting any devices:

headscale users create <username>

List all users:

headscale users list

Connect Devices

To connect devices to your Headscale network, see Tailscale Client.

Common Commands