mirror of https://github.com/juanfont/headscale.git synced 2026-08-08 00:18:46 +09:00

Files

T

Kristoffer Dalby f6aea642d3 all: scrub stale gRPC references from comments and docs

Reword comments and docs that still named the removed gRPC stack, rename
the GRPCSortable test interface, and drop the dead gRPC port note from the
dev README.

2026-06-19 05:58:10 +00:00

main.go

all: remove dead gRPC config, tests, and helpers

2026-06-19 05:58:10 +00:00

README.md

all: scrub stale gRPC references from comments and docs

2026-06-19 05:58:10 +00:00

README.md

cmd/dev -- Local Development Environment

Starts a headscale server on localhost with a pre-created user and pre-auth key. Pair with mts to add real tailscale nodes.

Quick start

# Terminal 1: start headscale
go run ./cmd/dev

# Terminal 2: start mts server
go tool mts server run

# Terminal 3: add and connect nodes
go tool mts server add node1
go tool mts server add node2

# Disable logtail (avoids startup delays, see "Known issues" below)
for n in node1 node2; do
  cat > ~/.config/multi-tailscale-dev/$n/env.txt << 'EOF'
TS_NO_LOGS_NO_SUPPORT=true
EOF
done

# Restart nodes so env.txt takes effect
go tool mts server stop node1 && go tool mts server start node1
go tool mts server stop node2 && go tool mts server start node2

# Connect to headscale (use the auth key printed by cmd/dev)
go tool mts node1 up --login-server=http://127.0.0.1:8080 --authkey=<KEY> --reset
go tool mts node2 up --login-server=http://127.0.0.1:8080 --authkey=<KEY> --reset

# Verify
go tool mts node1 status

Flags

Flag	Default	Description
`--port`	8080	Headscale listen port
`--keep`	false	Keep state directory on exit

The metrics/debug port is port + 1010 (default 9090).

What it does

Builds the headscale binary into a temp directory
Writes a minimal dev config (SQLite, public DERP, debug logging)
Starts headscale serve as a subprocess
Creates a "dev" user and a reusable 24h pre-auth key via the CLI
Prints a banner with server URL, auth key, and usage instructions
Blocks until Ctrl+C, then kills headscale

State lives in /tmp/headscale-dev-*/. Pass --keep to preserve it across restarts (useful for inspecting the database or reusing keys).

Useful endpoints

http://127.0.0.1:8080/health -- health check
http://127.0.0.1:9090/debug/ping -- interactive ping UI
http://127.0.0.1:9090/debug/ping?node=1 -- quick-ping a node
POST http://127.0.0.1:9090/debug/ping with node=<id> -- trigger ping

Managing headscale

The banner prints the full path to the built binary and config. Use it for any headscale CLI command:

/tmp/headscale-dev-*/headscale -c /tmp/headscale-dev-*/config.yaml nodes list
/tmp/headscale-dev-*/headscale -c /tmp/headscale-dev-*/config.yaml users list

Known issues

Logtail delays on mts nodes

Freshly created mts instances may take 30+ seconds to start if ~/.local/share/tailscale/ contains stale logtail cache from previous tailscaled runs. The daemon blocks trying to upload old logs before creating its socket.

Fix: write TS_NO_LOGS_NO_SUPPORT=true to each instance's env.txt before starting (or restart after writing). See the quick start above.

mts node cleanup

mts stores state in ~/.config/multi-tailscale-dev/. Old instances accumulate over time. Clean them with:

go tool mts server rm <name>