Incus Headscale Deployment

Table of Contents

• Overview
• Prerequisites
• Quick Start
  • Deploy Headscale Server
  • Deploy Headscale Gateway
• Configuration
  • Headscale Server
  • Headscale Gateway
• Usage
  • Management Commands
  • Headscale Server Management
  • Gateway Management
• Network Architecture
• Files
• Integration
• License

Overview

Simple Makefile-based deployment system for Headscale server and gateway using Incus containers.

This project provides cloud-init configurations for deploying:

• Headscale Server: Self-hosted Tailscale control plane for internal network

• Headscale Gateway: Tailscale-to-Headscale bridge for external access

Prerequisites

• Incus installed and configured

• Lima VM (or Linux host) with Incus

• Tailscale account (for gateway)

Quick Start

Deploy Headscale Server

make NAME=headscale-server start

Deploy Headscale Gateway

# First, create Tailscale auth key at https://login.tailscale.com/admin/settings/keys
# Then configure auth key (see Configuration section)

make NAME=headscale-gateway start

Configuration

Headscale Server

Environment variables:

• HEADSCALE_SERVER_URL - Server URL (default: http://192.168.5.10:8080)

• HEADSCALE_BASE_DOMAIN - MagicDNS domain (default: home.local)

Headscale Gateway

Environment variables:

• GATEWAY_HOSTNAME - Gateway hostname (default: ${CLUSTER_NAME}-hs-gateway)

• GATEWAY_ROUTES - Routes to advertise (default: 100.64.0.0/10,192.168.5.0/24)

Tailscale auth key (required):

# Create secrets file in the gateway container
incus exec headscale-gateway -- bash
mkdir -p /run/secrets
echo "tskey-auth-XXXXXXXXXX" > /run/secrets/tailscale-authkey
chmod 600 /run/secrets/tailscale-authkey
systemctl restart tailscale-gateway

Usage

Management Commands

# Start instance
make NAME=<instance> start

# Stop instance
make NAME=<instance> stop

# Delete instance
make NAME=<instance> delete

# Shell into instance
make NAME=<instance> shell

# Show status
make NAME=<instance> status

# Show logs
make NAME=<instance> logs

Headscale Server Management

# Create user
incus exec headscale-server -- headscale users create admin

# Create auth key
incus exec headscale-server -- headscale preauthkeys create --user admin --reusable --expiration 720h

# List nodes
incus exec headscale-server -- headscale nodes list

# List routes
incus exec headscale-server -- headscale routes list

Gateway Management

# Check Tailscale status
incus exec headscale-gateway -- tailscale status

# Check advertised routes
incus exec headscale-gateway -- tailscale status --json | jq -r '.Self.AllowedIPs[]'

Network Architecture

Darwin Hosts (bioskop, alcide)
    ↓ Headscale Client (100.64.x.x)
Headscale Server (headscale-server container)
    ↓ Manages SSH keys, ACLs

When mobile (alcide):
    ↓ Tailscale (100.x.x.x)
Headscale Gateway (headscale-gateway container)
    ↓ Bridges networks
Internal resources (100.64.x.x)

Files

• Makefile - Deployment automation

• cloud-config.headscale-server.yaml.tmpl - Headscale server cloud-init

• cloud-config.headscale-gateway.yaml.tmpl - Headscale gateway cloud-init

Integration

This project is designed to be used as a git subtree in nix-darwin-home:

# In nix-darwin-home repository
git subtree add --prefix=modules/nixos/incus-headscale \
  https://github.com/nxmatic/incus-headscale.git main --squash

License

MIT