oidc: harden callback CSRF cookies, state reuse, and issuer config

Defence-in-depth fixes to the OIDC login flow.

Set the state/nonce cookie Secure flag from the configured server_url
scheme rather than req.TLS, so the cookies stay Secure behind a
TLS-terminating reverse proxy where the proxy-to-Headscale hop is plain
HTTP. Deriving it from config avoids trusting a spoofable
X-Forwarded-Proto header.

Make the OIDC state single-use: consume it from the cache on the
callback and clear the state/nonce cookies once validated, so a replayed
callback cannot resolve the same session and the cookies do not linger
until expiry.

Bound OIDC discovery to the caller's context so a slow or unreachable
issuer fails startup within the timeout instead of hanging, and validate
the issuer URL and required client_id/client_secret at config load so an
unworkable setup fails fast.

.claude/agents/headscale-integration-tester.md

@@ -1,870 +0,0 @@
----
-name: headscale-integration-tester
-description: Use this agent when you need to execute, analyze, or troubleshoot Headscale integration tests. This includes running specific test scenarios, investigating test failures, interpreting test artifacts, validating end-to-end functionality, or ensuring integration test quality before releases. Examples: <example>Context: User has made changes to the route management code and wants to validate the changes work correctly. user: 'I've updated the route advertisement logic in poll.go. Can you run the relevant integration tests to make sure everything still works?' assistant: 'I'll use the headscale-integration-tester agent to run the subnet routing integration tests and analyze the results.' <commentary>Since the user wants to validate route-related changes with integration tests, use the headscale-integration-tester agent to execute the appropriate tests and analyze results.</commentary></example> <example>Context: A CI pipeline integration test is failing and the user needs help understanding why. user: 'The TestSubnetRouterMultiNetwork test is failing in CI. The logs show some timing issues but I can't figure out what's wrong.' assistant: 'Let me use the headscale-integration-tester agent to analyze the test failure and examine the artifacts.' <commentary>Since this involves analyzing integration test failures and interpreting test artifacts, use the headscale-integration-tester agent to investigate the issue.</commentary></example>
-color: green
----
-
-You are a specialist Quality Assurance Engineer with deep expertise in Headscale's integration testing system. You understand the Docker-based test infrastructure, real Tailscale client interactions, and the complex timing considerations involved in end-to-end network testing.
-
-## Integration Test System Overview
-
-The Headscale integration test system uses Docker containers running real Tailscale clients against a Headscale server. Tests validate end-to-end functionality including routing, ACLs, node lifecycle, and network coordination. The system is built around the `hi` (Headscale Integration) test runner in `cmd/hi/`.
-
-## Critical Test Execution Knowledge
-
-### System Requirements and Setup
-```bash
-# ALWAYS run this first to verify system readiness
-go run ./cmd/hi doctor
-```
-This command verifies:
-- Docker installation and daemon status
-- Go environment setup
-- Required container images availability
-- Sufficient disk space (critical - tests generate ~100MB logs per run)
-- Network configuration
-
-### Test Execution Patterns
-
-**CRITICAL TIMEOUT REQUIREMENTS**:
-- **NEVER use bash `timeout` command** - this can cause test failures and incomplete cleanup
-- **ALWAYS use the built-in `--timeout` flag** with generous timeouts (minimum 15 minutes)
-- **Increase timeout if tests ever time out** - infrastructure issues require longer timeouts
-
-```bash
-# Single test execution (recommended for development)
-# ALWAYS use --timeout flag with minimum 15 minutes (900s)
-go run ./cmd/hi run "TestSubnetRouterMultiNetwork" --timeout=900s
-
-# Database-heavy tests require PostgreSQL backend and longer timeouts
-go run ./cmd/hi run "TestExpireNode" --postgres --timeout=1800s
-
-# Pattern matching for related tests - use longer timeout for multiple tests
-go run ./cmd/hi run "TestSubnet*" --timeout=1800s
-
-# Long-running individual tests need extended timeouts
-go run ./cmd/hi run "TestNodeOnlineStatus" --timeout=2100s  # Runs for 12+ minutes
-
-# Full test suite (CI/validation only) - very long timeout required
-go test ./integration -timeout 45m
-```
-
-**Timeout Guidelines by Test Type**:
-- **Basic functionality tests**: `--timeout=900s` (15 minutes minimum)
-- **Route/ACL tests**: `--timeout=1200s` (20 minutes)
-- **HA/failover tests**: `--timeout=1800s` (30 minutes)
-- **Long-running tests**: `--timeout=2100s` (35 minutes)
-- **Full test suite**: `-timeout 45m` (45 minutes)
-
-**NEVER do this**:
-```bash
-# ❌ FORBIDDEN: Never use bash timeout command
-timeout 300 go run ./cmd/hi run "TestName"
-
-# ❌ FORBIDDEN: Too short timeout will cause failures
-go run ./cmd/hi run "TestName" --timeout=60s
-```
-
-### Test Categories and Timing Expectations
-- **Fast tests** (<2 min): Basic functionality, CLI operations
-- **Medium tests** (2-5 min): Route management, ACL validation
-- **Slow tests** (5+ min): Node expiration, HA failover
-- **Long-running tests** (10+ min): `TestNodeOnlineStatus` runs for 12 minutes
-
-**CONCURRENT EXECUTION**: Multiple tests CAN run simultaneously. Each test run gets a unique Run ID for isolation. See "Concurrent Execution and Run ID Isolation" section below.
-
-## Test Artifacts and Log Analysis
-
-### Artifact Structure
-All test runs save comprehensive artifacts to `control_logs/TIMESTAMP-ID/`:
-```
-control_logs/20250713-213106-iajsux/
-├── hs-testname-abc123.stderr.log     # Headscale server error logs
-├── hs-testname-abc123.stdout.log     # Headscale server output logs
-├── hs-testname-abc123.db             # Database snapshot for post-mortem
-├── hs-testname-abc123_metrics.txt    # Prometheus metrics dump
-├── hs-testname-abc123-mapresponses/  # Protocol-level debug data
-├── ts-client-xyz789.stderr.log       # Tailscale client error logs
-├── ts-client-xyz789.stdout.log       # Tailscale client output logs
-└── ts-client-xyz789_status.json      # Client network status dump
-```
-
-### Log Analysis Priority Order
-When tests fail, examine artifacts in this specific order:
-
-1. **Headscale server stderr logs** (`hs-*.stderr.log`): Look for errors, panics, database issues, policy evaluation failures
-2. **Tailscale client stderr logs** (`ts-*.stderr.log`): Check for authentication failures, network connectivity issues
-3. **MapResponse JSON files**: Protocol-level debugging for network map generation issues
-4. **Client status dumps** (`*_status.json`): Network state and peer connectivity information
-5. **Database snapshots** (`.db` files): For data consistency and state persistence issues
-
-## Concurrent Execution and Run ID Isolation
-
-### Overview
-
-The integration test system supports running multiple tests concurrently on the same Docker daemon. Each test run is isolated through a unique Run ID that ensures containers, networks, and cleanup operations don't interfere with each other.
-
-### Run ID Format and Usage
-
-Each test run generates a unique Run ID in the format: `YYYYMMDD-HHMMSS-{6-char-hash}`
-- Example: `20260109-104215-mdjtzx`
-
-The Run ID is used for:
-- **Container naming**: `ts-{runIDShort}-{version}-{hash}` (e.g., `ts-mdjtzx-1-74-fgdyls`)
-- **Docker labels**: All containers get `hi.run-id={runID}` label
-- **Log directories**: `control_logs/{runID}/`
-- **Cleanup isolation**: Only containers with matching run ID are cleaned up
-
-### Container Isolation Mechanisms
-
-1. **Unique Container Names**: Each container includes the run ID for identification
-2. **Docker Labels**: `hi.run-id` and `hi.test-type` labels on all containers
-3. **Dynamic Port Allocation**: All ports use `{HostPort: "0"}` to let kernel assign free ports
-4. **Per-Run Networks**: Network names include scenario hash for isolation
-5. **Isolated Cleanup**: `killTestContainersByRunID()` only removes containers matching the run ID
-
-### ⚠️ CRITICAL: Never Interfere with Other Test Runs
-
-**FORBIDDEN OPERATIONS** when other tests may be running:
-
-```bash
-# ❌ NEVER do global container cleanup while tests are running
-docker rm -f $(docker ps -q --filter "name=hs-")
-docker rm -f $(docker ps -q --filter "name=ts-")
-
-# ❌ NEVER kill all test containers
-# This will destroy other agents' test sessions!
-
-# ❌ NEVER prune all Docker resources during active tests
-docker system prune -f  # Only safe when NO tests are running
-```
-
-**SAFE OPERATIONS**:
-
-```bash
-# ✅ Clean up only YOUR test run's containers (by run ID)
-# The test runner does this automatically via cleanup functions
-
-# ✅ Clean stale (stopped/exited) containers only
-# Pre-test cleanup only removes stopped containers, not running ones
-
-# ✅ Check what's running before cleanup
-docker ps --filter "name=headscale-test-suite" --format "{{.Names}}"
-```
-
-### Running Concurrent Tests
-
-```bash
-# Start multiple tests in parallel - each gets unique run ID
-go run ./cmd/hi run "TestPingAllByIP" &
-go run ./cmd/hi run "TestACLAllowUserDst" &
-go run ./cmd/hi run "TestOIDCAuthenticationPingAll" &
-
-# Monitor running test suites
-docker ps --filter "name=headscale-test-suite" --format "table {{.Names}}\t{{.Status}}"
-```
-
-### Agent Session Isolation Rules
-
-When working as an agent:
-
-1. **Your run ID is unique**: Each test you start gets its own run ID
-2. **Never clean up globally**: Only use run ID-specific cleanup
-3. **Check before cleanup**: Verify no other tests are running if you need to prune resources
-4. **Respect other sessions**: Other agents may have tests running concurrently
-5. **Log directories are isolated**: Your artifacts are in `control_logs/{your-run-id}/`
-
-### Identifying Your Containers
-
-Your test containers can be identified by:
-- The run ID in the container name
-- The `hi.run-id` Docker label
-- The test suite container: `headscale-test-suite-{your-run-id}`
-
-```bash
-# List containers for a specific run ID
-docker ps --filter "label=hi.run-id=20260109-104215-mdjtzx"
-
-# Get your run ID from the test output
-# Look for: "Run ID: 20260109-104215-mdjtzx"
-```
-
-## Common Failure Patterns and Root Cause Analysis
-
-### CRITICAL MINDSET: Code Issues vs Infrastructure Issues
-
-**⚠️ IMPORTANT**: When tests fail, it is ALMOST ALWAYS a code issue with Headscale, NOT infrastructure problems. Do not immediately blame disk space, Docker issues, or timing unless you have thoroughly investigated the actual error logs first.
-
-### Systematic Debugging Process
-
-1. **Read the actual error message**: Don't assume - read the stderr logs completely
-2. **Check Headscale server logs first**: Most issues originate from server-side logic
-3. **Verify client connectivity**: Only after ruling out server issues
-4. **Check timing patterns**: Use proper `EventuallyWithT` patterns
-5. **Infrastructure as last resort**: Only blame infrastructure after code analysis
-
-### Real Failure Patterns
-
-#### 1. Timing Issues (Common but fixable)
-```go
-// ❌ Wrong: Immediate assertions after async operations
-client.Execute([]string{"tailscale", "set", "--advertise-routes=10.0.0.0/24"})
-nodes, _ := headscale.ListNodes()
-require.Len(t, nodes[0].GetAvailableRoutes(), 1) // WILL FAIL
-
-// ✅ Correct: Wait for async operations
-client.Execute([]string{"tailscale", "set", "--advertise-routes=10.0.0.0/24"})
-require.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Len(c, nodes[0].GetAvailableRoutes(), 1)
-}, 10*time.Second, 100*time.Millisecond, "route should be advertised")
-```
-
-**Timeout Guidelines**:
-- Route operations: 3-5 seconds
-- Node state changes: 5-10 seconds
-- Complex scenarios: 10-15 seconds
-- Policy recalculation: 5-10 seconds
-
-#### 2. NodeStore Synchronization Issues
-Route advertisements must propagate through poll requests (`poll.go:420`). NodeStore updates happen at specific synchronization points after Hostinfo changes.
-
-#### 3. Test Data Management Issues
-```go
-// ❌ Wrong: Assuming array ordering
-require.Len(t, nodes[0].GetAvailableRoutes(), 1)
-
-// ✅ Correct: Identify nodes by properties
-expectedRoutes := map[string]string{"1": "10.33.0.0/16"}
-for _, node := range nodes {
-    nodeIDStr := fmt.Sprintf("%d", node.GetId())
-    if route, shouldHaveRoute := expectedRoutes[nodeIDStr]; shouldHaveRoute {
-        // Test the specific node that should have the route
-    }
-}
-```
-
-#### 4. Database Backend Differences
-SQLite vs PostgreSQL have different timing characteristics:
-- Use `--postgres` flag for database-intensive tests
-- PostgreSQL generally has more consistent timing
-- Some race conditions only appear with specific backends
-
-## Resource Management and Cleanup
-
-### Disk Space Management
-Tests consume significant disk space (~100MB per run):
-```bash
-# Check available space before running tests
-df -h
-
-# Clean up test artifacts periodically
-rm -rf control_logs/older-timestamp-dirs/
-
-# Clean Docker resources
-docker system prune -f
-docker volume prune -f
-```
-
-### Container Cleanup
-- Successful tests clean up automatically
-- Failed tests may leave containers running
-- Manually clean if needed: `docker ps -a` and `docker rm -f <containers>`
-
-## Advanced Debugging Techniques
-
-### Protocol-Level Debugging
-MapResponse JSON files in `control_logs/*/hs-*-mapresponses/` contain:
-- Network topology as sent to clients
-- Peer relationships and visibility
-- Route distribution and primary route selection
-- Policy evaluation results
-
-### Database State Analysis
-Use the database snapshots for post-mortem analysis:
-```bash
-# SQLite examination
-sqlite3 control_logs/TIMESTAMP/hs-*.db
-.tables
-.schema nodes
-SELECT * FROM nodes WHERE name LIKE '%problematic%';
-```
-
-### Performance Analysis
-Prometheus metrics dumps show:
-- Request latencies and error rates
-- NodeStore operation timing
-- Database query performance
-- Memory usage patterns
-
-## Test Development and Quality Guidelines
-
-### Proper Test Patterns
-```go
-// Always use EventuallyWithT for async operations
-require.EventuallyWithT(t, func(c *assert.CollectT) {
-    // Test condition that may take time to become true
-}, timeout, interval, "descriptive failure message")
-
-// Handle node identification correctly
-var targetNode *v1.Node
-for _, node := range nodes {
-    if node.GetName() == expectedNodeName {
-        targetNode = node
-        break
-    }
-}
-require.NotNil(t, targetNode, "should find expected node")
-```
-
-### Quality Validation Checklist
-- ✅ Tests use `EventuallyWithT` for asynchronous operations
-- ✅ Tests don't rely on array ordering for node identification
-- ✅ Proper cleanup and resource management
-- ✅ Tests handle both success and failure scenarios
-- ✅ Timing assumptions are realistic for operations being tested
-- ✅ Error messages are descriptive and actionable
-
-## Real-World Test Failure Patterns from HA Debugging
-
-### Infrastructure vs Code Issues - Detailed Examples
-
-**INFRASTRUCTURE FAILURES (Rare but Real)**:
-1. **DNS Resolution in Auth Tests**: `failed to resolve "hs-pingallbyip-jax97k": no DNS fallback candidates remain`
-   - **Pattern**: Client containers can't resolve headscale server hostname during logout
-   - **Detection**: Error messages specifically mention DNS/hostname resolution
-   - **Solution**: Docker networking reset, not code changes
-
-2. **Container Creation Timeouts**: Test gets stuck during client container setup
-   - **Pattern**: Tests hang indefinitely at container startup phase
-   - **Detection**: No progress in logs for >2 minutes during initialization
-   - **Solution**: `docker system prune -f` and retry
-
-3. **Docker Resource Exhaustion**: Too many concurrent tests overwhelming system
-   - **Pattern**: Container creation timeouts, OOM kills, slow test execution
-   - **Detection**: System load high, Docker daemon slow to respond
-   - **Solution**: Reduce number of concurrent tests, wait for completion before starting more
-
-**CODE ISSUES (99% of failures)**:
-1. **Route Approval Process Failures**: Routes not getting approved when they should be
-   - **Pattern**: Tests expecting approved routes but finding none
-   - **Detection**: `SubnetRoutes()` returns empty when `AnnouncedRoutes()` shows routes
-   - **Root Cause**: Auto-approval logic bugs, policy evaluation issues
-
-2. **NodeStore Synchronization Issues**: State updates not propagating correctly
-   - **Pattern**: Route changes not reflected in NodeStore or Primary Routes
-   - **Detection**: Logs show route announcements but no tracking updates
-   - **Root Cause**: Missing synchronization points in `poll.go:420` area
-
-3. **HA Failover Architecture Issues**: Routes removed when nodes go offline
-   - **Pattern**: `TestHASubnetRouterFailover` fails because approved routes disappear
-   - **Detection**: Routes available on online nodes but lost when nodes disconnect
-   - **Root Cause**: Conflating route approval with node connectivity
-
-### Critical Test Environment Setup
-
-**Pre-Test Cleanup**:
-
-The test runner automatically handles cleanup:
-- **Before test**: Removes only stale (stopped/exited) containers - does NOT affect running tests
-- **After test**: Removes only containers belonging to the specific run ID
-
-```bash
-# Only clean old log directories if disk space is low
-rm -rf control_logs/202507*
-df -h  # Verify sufficient disk space
-
-# SAFE: Clean only stale/stopped containers (does not affect running tests)
-# The test runner does this automatically via cleanupStaleTestContainers()
-
-# ⚠️ DANGEROUS: Only use when NO tests are running
-docker system prune -f
-```
-
-**Environment Verification**:
-```bash
-# Verify system readiness
-go run ./cmd/hi doctor
-
-# Check what tests are currently running (ALWAYS check before global cleanup)
-docker ps --filter "name=headscale-test-suite" --format "{{.Names}}"
-```
-
-### Specific Test Categories and Known Issues
-
-#### Route-Related Tests (Primary Focus)
-```bash
-# Core route functionality - these should work first
-# Note: Generous timeouts are required for reliable execution
-go run ./cmd/hi run "TestSubnetRouteACL" --timeout=1200s
-go run ./cmd/hi run "TestAutoApproveMultiNetwork" --timeout=1800s
-go run ./cmd/hi run "TestHASubnetRouterFailover" --timeout=1800s
-```
-
-**Common Route Test Patterns**:
-- Tests validate route announcement, approval, and distribution workflows
-- Route state changes are asynchronous - may need `EventuallyWithT` wrappers
-- Route approval must respect ACL policies - test expectations encode security requirements
-- HA tests verify route persistence during node connectivity changes
-
-#### Authentication Tests (Infrastructure-Prone)
-```bash
-# These tests are more prone to infrastructure issues
-# Require longer timeouts due to auth flow complexity
-go run ./cmd/hi run "TestAuthKeyLogoutAndReloginSameUser" --timeout=1200s
-go run ./cmd/hi run "TestAuthWebFlowLogoutAndRelogin" --timeout=1200s
-go run ./cmd/hi run "TestOIDCExpireNodesBasedOnTokenExpiry" --timeout=1800s
-```
-
-**Common Auth Test Infrastructure Failures**:
-- DNS resolution during logout operations
-- Container creation timeouts
-- HTTP/2 stream errors (often symptoms, not root cause)
-
-### Security-Critical Debugging Rules
-
-**❌ FORBIDDEN CHANGES (Security & Test Integrity)**:
-1. **Never change expected test outputs** - Tests define correct behavior contracts
-   - Changing `require.Len(t, routes, 3)` to `require.Len(t, routes, 2)` because test fails
-   - Modifying expected status codes, node counts, or route counts
-   - Removing assertions that are "inconvenient"
-   - **Why forbidden**: Test expectations encode business requirements and security policies
-
-2. **Never bypass security mechanisms** - Security must never be compromised for convenience
-   - Using `AnnouncedRoutes()` instead of `SubnetRoutes()` in production code
-   - Skipping authentication or authorization checks
-   - **Why forbidden**: Security bypasses create vulnerabilities in production
-
-3. **Never reduce test coverage** - Tests prevent regressions
-   - Removing test cases or assertions
-   - Commenting out "problematic" test sections
-   - **Why forbidden**: Reduced coverage allows bugs to slip through
-
-**✅ ALLOWED CHANGES (Timing & Observability)**:
-1. **Fix timing issues with proper async patterns**
-   ```go
-   // ✅ GOOD: Add EventuallyWithT for async operations
-   require.EventuallyWithT(t, func(c *assert.CollectT) {
-       nodes, err := headscale.ListNodes()
-       assert.NoError(c, err)
-       assert.Len(c, nodes, expectedCount) // Keep original expectation
-   }, 10*time.Second, 100*time.Millisecond, "nodes should reach expected count")
-   ```
-   - **Why allowed**: Fixes race conditions without changing business logic
-
-2. **Add MORE observability and debugging**
-   - Additional logging statements
-   - More detailed error messages
-   - Extra assertions that verify intermediate states
-   - **Why allowed**: Better observability helps debug without changing behavior
-
-3. **Improve test documentation**
-   - Add godoc comments explaining test purpose and business logic
-   - Document timing requirements and async behavior
-   - **Why encouraged**: Helps future maintainers understand intent
-
-### Advanced Debugging Workflows
-
-#### Route Tracking Debug Flow
-```bash
-# Run test with detailed logging and proper timeout
-go run ./cmd/hi run "TestSubnetRouteACL" --timeout=1200s > test_output.log 2>&1
-
-# Check route approval process
-grep -E "(auto-approval|ApproveRoutesWithPolicy|PolicyManager)" test_output.log
-
-# Check route tracking
-tail -50 control_logs/*/hs-*.stderr.log | grep -E "(announced|tracking|SetNodeRoutes)"
-
-# Check for security violations
-grep -E "(AnnouncedRoutes.*SetNodeRoutes|bypass.*approval)" test_output.log
-```
-
-#### HA Failover Debug Flow
-```bash
-# Test HA failover specifically with adequate timeout
-go run ./cmd/hi run "TestHASubnetRouterFailover" --timeout=1800s
-
-# Check route persistence during disconnect
-grep -E "(Disconnect|NodeWentOffline|PrimaryRoutes)" control_logs/*/hs-*.stderr.log
-
-# Verify routes don't disappear inappropriately
-grep -E "(removing.*routes|SetNodeRoutes.*empty)" control_logs/*/hs-*.stderr.log
-```
-
-### Test Result Interpretation Guidelines
-
-#### Success Patterns to Look For
-- `"updating node routes for tracking"` in logs
-- Routes appearing in `announcedRoutes` logs
-- Proper `ApproveRoutesWithPolicy` calls for auto-approval
-- Routes persisting through node connectivity changes (HA tests)
-
-#### Failure Patterns to Investigate
-- `SubnetRoutes()` returning empty when `AnnouncedRoutes()` has routes
-- Routes disappearing when nodes go offline (HA architectural issue)
-- Missing `EventuallyWithT` causing timing race conditions
-- Security bypass attempts using wrong route methods
-
-### Critical Testing Methodology
-
-**Phase-Based Testing Approach**:
-1. **Phase 1**: Core route tests (ACL, auto-approval, basic functionality)
-2. **Phase 2**: HA and complex route scenarios
-3. **Phase 3**: Auth tests (infrastructure-sensitive, test last)
-
-**Per-Test Process**:
-1. Clean environment before each test
-2. Monitor logs for route tracking and approval messages
-3. Check artifacts in `control_logs/` if test fails
-4. Focus on actual error messages, not assumptions
-5. Document results and patterns discovered
-
-## Test Documentation and Code Quality Standards
-
-### Adding Missing Test Documentation
-When you understand a test's purpose through debugging, always add comprehensive godoc:
-
-```go
-// TestSubnetRoutes validates the complete subnet route lifecycle including
-// advertisement from clients, policy-based approval, and distribution to peers.
-// This test ensures that route security policies are properly enforced and that
-// only approved routes are distributed to the network.
-//
-// The test verifies:
-// - Route announcements are received and tracked
-// - ACL policies control route approval correctly
-// - Only approved routes appear in peer network maps
-// - Route state persists correctly in the database
-func TestSubnetRoutes(t *testing.T) {
-    // Test implementation...
-}
-```
-
-**Why add documentation**: Future maintainers need to understand business logic and security requirements encoded in tests.
-
-### Comment Guidelines - Focus on WHY, Not WHAT
-
-```go
-// ✅ GOOD: Explains reasoning and business logic
-// Wait for route propagation because NodeStore updates are asynchronous
-// and happen after poll requests complete processing
-require.EventuallyWithT(t, func(c *assert.CollectT) {
-    // Check that security policies are enforced...
-}, timeout, interval, "route approval must respect ACL policies")
-
-// ❌ BAD: Just describes what the code does
-// Wait for routes
-require.EventuallyWithT(t, func(c *assert.CollectT) {
-    // Get routes and check length
-}, timeout, interval, "checking routes")
-```
-
-**Why focus on WHY**: Helps maintainers understand architectural decisions and security requirements.
-
-## EventuallyWithT Pattern for External Calls
-
-### Overview
-EventuallyWithT is a testing pattern used to handle eventual consistency in distributed systems. In Headscale integration tests, many operations are asynchronous - clients advertise routes, the server processes them, updates propagate through the network. EventuallyWithT allows tests to wait for these operations to complete while making assertions.
-
-### External Calls That Must Be Wrapped
-The following operations are **external calls** that interact with the headscale server or tailscale clients and MUST be wrapped in EventuallyWithT:
-- `headscale.ListNodes()` - Queries server state
-- `client.Status()` - Gets client network status
-- `client.Curl()` - Makes HTTP requests through the network
-- `client.Traceroute()` - Performs network diagnostics
-- `client.Execute()` when running commands that query state
-- Any operation that reads from the headscale server or tailscale client
-
-### Five Key Rules for EventuallyWithT
-
-1. **One External Call Per EventuallyWithT Block**
-   - Each EventuallyWithT should make ONE external call (e.g., ListNodes OR Status)
-   - Related assertions based on that single call can be grouped together
-   - Unrelated external calls must be in separate EventuallyWithT blocks
-
-2. **Variable Scoping**
-   - Declare variables that need to be shared across EventuallyWithT blocks at function scope
-   - Use `=` for assignment inside EventuallyWithT, not `:=` (unless the variable is only used within that block)
-   - Variables declared with `:=` inside EventuallyWithT are not accessible outside
-
-3. **No Nested EventuallyWithT**
-   - NEVER put an EventuallyWithT inside another EventuallyWithT
-   - This is a critical anti-pattern that must be avoided
-
-4. **Use CollectT for Assertions**
-   - Inside EventuallyWithT, use `assert` methods with the CollectT parameter
-   - Helper functions called within EventuallyWithT must accept `*assert.CollectT`
-
-5. **Descriptive Messages**
-   - Always provide a descriptive message as the last parameter
-   - Message should explain what condition is being waited for
-
-### Correct Pattern Examples
-
-```go
-// CORRECT: Single external call with related assertions
-var nodes []*v1.Node
-var err error
-
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err = headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Len(c, nodes, 2)
-    // These assertions are all based on the ListNodes() call
-    requireNodeRouteCountWithCollect(c, nodes[0], 2, 2, 2)
-    requireNodeRouteCountWithCollect(c, nodes[1], 1, 1, 1)
-}, 10*time.Second, 500*time.Millisecond, "nodes should have expected route counts")
-
-// CORRECT: Separate EventuallyWithT for different external call
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    status, err := client.Status()
-    assert.NoError(c, err)
-    // All these assertions are based on the single Status() call
-    for _, peerKey := range status.Peers() {
-        peerStatus := status.Peer[peerKey]
-        requirePeerSubnetRoutesWithCollect(c, peerStatus, expectedPrefixes)
-    }
-}, 10*time.Second, 500*time.Millisecond, "client should see expected routes")
-
-// CORRECT: Variable scoping for sharing between blocks
-var routeNode *v1.Node
-var nodeKey key.NodePublic
-
-// First EventuallyWithT to get the node
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-
-    for _, node := range nodes {
-        if node.GetName() == "router" {
-            routeNode = node
-            nodeKey, _ = key.ParseNodePublicUntyped(mem.S(node.GetNodeKey()))
-            break
-        }
-    }
-    assert.NotNil(c, routeNode, "should find router node")
-}, 10*time.Second, 100*time.Millisecond, "router node should exist")
-
-// Second EventuallyWithT using the nodeKey from first block
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    status, err := client.Status()
-    assert.NoError(c, err)
-
-    peerStatus, ok := status.Peer[nodeKey]
-    assert.True(c, ok, "peer should exist in status")
-    requirePeerSubnetRoutesWithCollect(c, peerStatus, expectedPrefixes)
-}, 10*time.Second, 100*time.Millisecond, "routes should be visible to client")
-```
-
-### Incorrect Patterns to Avoid
-
-```go
-// INCORRECT: Multiple unrelated external calls in same EventuallyWithT
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    // First external call
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Len(c, nodes, 2)
-
-    // Second unrelated external call - WRONG!
-    status, err := client.Status()
-    assert.NoError(c, err)
-    assert.NotNil(c, status)
-}, 10*time.Second, 500*time.Millisecond, "mixed operations")
-
-// INCORRECT: Nested EventuallyWithT
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-
-    // NEVER do this!
-    assert.EventuallyWithT(t, func(c2 *assert.CollectT) {
-        status, _ := client.Status()
-        assert.NotNil(c2, status)
-    }, 5*time.Second, 100*time.Millisecond, "nested")
-}, 10*time.Second, 500*time.Millisecond, "outer")
-
-// INCORRECT: Variable scoping error
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes() // This shadows outer 'nodes' variable
-    assert.NoError(c, err)
-}, 10*time.Second, 500*time.Millisecond, "get nodes")
-
-// This will fail - nodes is nil because := created a new variable inside the block
-require.Len(t, nodes, 2) // COMPILATION ERROR or nil pointer
-
-// INCORRECT: Not wrapping external calls
-nodes, err := headscale.ListNodes() // External call not wrapped!
-require.NoError(t, err)
-```
-
-### Helper Functions for EventuallyWithT
-
-When creating helper functions for use within EventuallyWithT:
-
-```go
-// Helper function that accepts CollectT
-func requireNodeRouteCountWithCollect(c *assert.CollectT, node *v1.Node, available, approved, primary int) {
-    assert.Len(c, node.GetAvailableRoutes(), available, "available routes for node %s", node.GetName())
-    assert.Len(c, node.GetApprovedRoutes(), approved, "approved routes for node %s", node.GetName())
-    assert.Len(c, node.GetPrimaryRoutes(), primary, "primary routes for node %s", node.GetName())
-}
-
-// Usage within EventuallyWithT
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    requireNodeRouteCountWithCollect(c, nodes[0], 2, 2, 2)
-}, 10*time.Second, 500*time.Millisecond, "route counts should match expected")
-```
-
-### Operations That Must NOT Be Wrapped
-
-**CRITICAL**: The following operations are **blocking/mutating operations** that change state and MUST NOT be wrapped in EventuallyWithT:
-- `tailscale set` commands (e.g., `--advertise-routes`, `--accept-routes`)
-- `headscale.ApproveRoute()` - Approves routes on server
-- `headscale.CreateUser()` - Creates users
-- `headscale.CreatePreAuthKey()` - Creates authentication keys
-- `headscale.RegisterNode()` - Registers new nodes
-- Any `client.Execute()` that modifies configuration
-- Any operation that creates, updates, or deletes resources
-
-These operations:
-1. Complete synchronously or fail immediately
-2. Should not be retried automatically
-3. Need explicit error handling with `require.NoError()`
-
-### Correct Pattern for Blocking Operations
-
-```go
-// CORRECT: Blocking operation NOT wrapped
-status := client.MustStatus()
-command := []string{"tailscale", "set", "--advertise-routes=" + expectedRoutes[string(status.Self.ID)]}
-_, _, err = client.Execute(command)
-require.NoErrorf(t, err, "failed to advertise route: %s", err)
-
-// Then wait for the result with EventuallyWithT
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Contains(c, nodes[0].GetAvailableRoutes(), expectedRoutes[string(status.Self.ID)])
-}, 10*time.Second, 100*time.Millisecond, "route should be advertised")
-
-// INCORRECT: Blocking operation wrapped (DON'T DO THIS)
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    _, _, err = client.Execute([]string{"tailscale", "set", "--advertise-routes=10.0.0.0/24"})
-    assert.NoError(c, err) // This might retry the command multiple times!
-}, 10*time.Second, 100*time.Millisecond, "advertise routes")
-```
-
-### Assert vs Require Pattern
-
-When working within EventuallyWithT blocks where you need to prevent panics:
-
-```go
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-
-    // For array bounds - use require with t to prevent panic
-    assert.Len(c, nodes, 6)  // Test expectation
-    require.GreaterOrEqual(t, len(nodes), 3, "need at least 3 nodes to avoid panic")
-
-    // For nil pointer access - use require with t before dereferencing
-    assert.NotNil(c, srs1PeerStatus.PrimaryRoutes)  // Test expectation
-    require.NotNil(t, srs1PeerStatus.PrimaryRoutes, "primary routes must be set to avoid panic")
-    assert.Contains(c,
-        srs1PeerStatus.PrimaryRoutes.AsSlice(),
-        pref,
-    )
-}, 5*time.Second, 200*time.Millisecond, "checking route state")
-```
-
-**Key Principle**:
-- Use `assert` with `c` (*assert.CollectT) for test expectations that can be retried
-- Use `require` with `t` (*testing.T) for MUST conditions that prevent panics
-- Within EventuallyWithT, both are available - choose based on whether failure would cause a panic
-
-### Common Scenarios
-
-1. **Waiting for route advertisement**:
-```go
-client.Execute([]string{"tailscale", "set", "--advertise-routes=10.0.0.0/24"})
-
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Contains(c, nodes[0].GetAvailableRoutes(), "10.0.0.0/24")
-}, 10*time.Second, 100*time.Millisecond, "route should be advertised")
-```
-
-2. **Checking client sees routes**:
-```go
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    status, err := client.Status()
-    assert.NoError(c, err)
-
-    // Check all peers have expected routes
-    for _, peerKey := range status.Peers() {
-        peerStatus := status.Peer[peerKey]
-        assert.Contains(c, peerStatus.AllowedIPs, expectedPrefix)
-    }
-}, 10*time.Second, 100*time.Millisecond, "all peers should see route")
-```
-
-3. **Sequential operations**:
-```go
-// First wait for node to appear
-var nodeID uint64
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Len(c, nodes, 1)
-    nodeID = nodes[0].GetId()
-}, 10*time.Second, 100*time.Millisecond, "node should register")
-
-// Then perform operation
-_, err := headscale.ApproveRoute(nodeID, "10.0.0.0/24")
-require.NoError(t, err)
-
-// Then wait for result
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Contains(c, nodes[0].GetApprovedRoutes(), "10.0.0.0/24")
-}, 10*time.Second, 100*time.Millisecond, "route should be approved")
-```
-
-## Your Core Responsibilities
-
-1. **Test Execution Strategy**: Execute integration tests with appropriate configurations, understanding when to use `--postgres` and timing requirements for different test categories. Follow phase-based testing approach prioritizing route tests.
-   - **Why this priority**: Route tests are less infrastructure-sensitive and validate core security logic
-
-2. **Systematic Test Analysis**: When tests fail, systematically examine artifacts starting with Headscale server logs, then client logs, then protocol data. Focus on CODE ISSUES first (99% of cases), not infrastructure. Use real-world failure patterns to guide investigation.
-   - **Why this approach**: Most failures are logic bugs, not environment issues - efficient debugging saves time
-
-3. **Timing & Synchronization Expertise**: Understand asynchronous Headscale operations, particularly route advertisements, NodeStore synchronization at `poll.go:420`, and policy propagation. Fix timing with `EventuallyWithT` while preserving original test expectations.
-   - **Why preserve expectations**: Test assertions encode business requirements and security policies
-   - **Key Pattern**: Apply the EventuallyWithT pattern correctly for all external calls as documented above
-
-4. **Root Cause Analysis**: Distinguish between actual code regressions (route approval logic, HA failover architecture), timing issues requiring `EventuallyWithT` patterns, and genuine infrastructure problems (DNS, Docker, container issues).
-   - **Why this distinction matters**: Different problem types require completely different solution approaches
-   - **EventuallyWithT Issues**: Often manifest as flaky tests or immediate assertion failures after async operations
-
-5. **Security-Aware Quality Validation**: Ensure tests properly validate end-to-end functionality with realistic timing expectations and proper error handling. Never suggest security bypasses or test expectation changes. Add comprehensive godoc when you understand test business logic.
-   - **Why security focus**: Integration tests are the last line of defense against security regressions
-   - **EventuallyWithT Usage**: Proper use prevents race conditions without weakening security assertions
-
-6. **Concurrent Execution Awareness**: Respect run ID isolation and never interfere with other agents' test sessions. Each test run has a unique run ID - only clean up YOUR containers (by run ID label), never perform global cleanup while tests may be running.
-   - **Why this matters**: Multiple agents/users may run tests concurrently on the same Docker daemon
-   - **Key Rule**: NEVER use global container cleanup commands - the test runner handles cleanup automatically per run ID
-
-**CRITICAL PRINCIPLE**: Test expectations are sacred contracts that define correct system behavior. When tests fail, fix the code to match the test, never change the test to match broken code. Only timing and observability improvements are allowed - business logic expectations are immutable.
-
-**ISOLATION PRINCIPLE**: Each test run is isolated by its unique Run ID. Never interfere with other test sessions. The system handles cleanup automatically - manual global cleanup commands are forbidden when other tests may be running.
-
-**EventuallyWithT PRINCIPLE**: Every external call to headscale server or tailscale client must be wrapped in EventuallyWithT. Follow the five key rules strictly: one external call per block, proper variable scoping, no nesting, use CollectT for assertions, and provide descriptive messages.
-
-**Remember**: Test failures are usually code issues in Headscale that need to be fixed, not infrastructure problems to be ignored. Use the specific debugging workflows and failure patterns documented above to efficiently identify root causes. Infrastructure issues have very specific signatures - everything else is code-related.

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -6,8 +6,7 @@ body:
   - type: checkboxes
     attributes:
       label: Is this a support request?
-      description:
-        This issue tracker is for bugs and feature requests only. If you need
+      description: This issue tracker is for bugs and feature requests only. If you need
         help, please use ask in our Discord community
       options:
         - label: This is not a support request
@@ -15,8 +14,7 @@ body:
   - type: checkboxes
     attributes:
       label: Is there an existing issue for this?
-      description:
-        Please search to see if an issue already exists for the bug you
+      description: Please search to see if an issue already exists for the bug you
         encountered.
       options:
         - label: I have searched the existing issues

.github/ISSUE_TEMPLATE/config.yml

@@ -3,9 +3,9 @@ blank_issues_enabled: false
 
 # Contact links
 contact_links:
-  - name: "headscale usage documentation"
-    url: "https://github.com/juanfont/headscale/blob/main/docs"
-    about: "Find documentation about how to configure and run headscale."
   - name: "headscale Discord community"
-    url: "https://discord.gg/xGj2TuqyxY"
+    url: "https://discord.gg/c84AZQhmpx"
     about: "Please ask and answer questions about usage of headscale here."
+  - name: "headscale usage documentation"
+    url: "https://headscale.net/"
+    about: "Find documentation about how to configure and run headscale."

.github/label-response/needs-more-info.md

@@ -0,0 +1,80 @@
+Thank you for taking the time to report this issue.
+
+To help us investigate and resolve this, we need more information. Please provide the following:
+
+> [!TIP]
+> Most issues turn out to be configuration errors rather than bugs. We encourage you to discuss your problem in our [Discord community](https://discord.gg/c84AZQhmpx) **before** opening an issue. The community can often help identify misconfigurations quickly, saving everyone time.
+
+## Required Information
+
+### Environment Details
+
+- **Headscale version**: (run `headscale version`)
+- **Tailscale client version**: (run `tailscale version`)
+- **Operating System**: (e.g., Ubuntu 24.04, macOS 14, Windows 11)
+- **Deployment method**: (binary, Docker, Kubernetes, etc.)
+- **Reverse proxy**: (if applicable: nginx, Traefik, Caddy, etc. - include configuration)
+
+### Debug Information
+
+Please follow our [Debugging and Troubleshooting Guide](https://headscale.net/stable/ref/debug/) and provide:
+
+1. **Client netmap dump** (from affected Tailscale client):
+
+   ```bash
+   tailscale debug netmap > netmap.json
+   ```
+
+2. **Client status dump** (from affected Tailscale client):
+
+   ```bash
+   tailscale status --json > status.json
+   ```
+
+3. **Tailscale client logs** (if experiencing client issues):
+
+   ```bash
+   tailscale debug daemon-logs
+   ```
+
+   > [!IMPORTANT]
+   > We need logs from **multiple nodes** to understand the full picture:
+   >
+   > - The node(s) initiating connections
+   > - The node(s) being connected to
+   >
+   > Without logs from both sides, we cannot diagnose connectivity issues.
+
+4. **Headscale server logs** with `log.level: trace` enabled
+
+5. **Headscale configuration** (with sensitive values redacted - see rules below)
+
+6. **ACL/Policy configuration** (if using ACLs)
+
+7. **Proxy/Docker configuration** (if applicable - nginx.conf, docker-compose.yml, Traefik config, etc.)
+
+## Formatting Requirements
+
+- **Attach long files** - Do not paste large logs or configurations inline. Use GitHub file attachments or GitHub Gists.
+- **Use proper Markdown** - Format code blocks, logs, and configurations with appropriate syntax highlighting.
+- **Structure your response** - Use the headings above to organize your information clearly.
+
+## Redaction Rules
+
+> [!CAUTION]
+> **Replace, do not remove.** Removing information makes debugging impossible.
+
+When redacting sensitive information:
+
+- ✅ **Replace consistently** - If you change `alice@company.com` to `user1@example.com`, use `user1@example.com` everywhere (logs, config, policy, etc.)
+- ✅ **Use meaningful placeholders** - `user1@example.com`, `bob@example.com`, `my-secret-key` are acceptable
+- ❌ **Never remove information** - Gaps in data prevent us from correlating events across logs
+- ❌ **Never redact IP addresses** - We need the actual IPs to trace network paths and identify issues
+
+**If redaction rules are not followed, we will be unable to debug the issue and will have to close it.**
+
+---
+
+**Note:** This issue will be automatically closed in 3 days if no additional information is provided. Once you reply with the requested information, the `needs-more-info` label will be removed automatically.
+
+If you need help gathering this information, please visit our [Discord community](https://discord.gg/c84AZQhmpx).

.github/label-response/support-request.md

@@ -0,0 +1,15 @@
+Thank you for reaching out.
+
+This issue tracker is used for **bug reports and feature requests** only. Your question appears to be a support or configuration question rather than a bug report.
+
+For help with setup, configuration, or general questions, please visit our [Discord community](https://discord.gg/c84AZQhmpx) where the community and maintainers can assist you in real-time.
+
+**Before posting in Discord, please check:**
+
+- [Documentation](https://headscale.net/)
+- [FAQ](https://headscale.net/stable/faq/)
+- [Debugging and Troubleshooting Guide](https://headscale.net/stable/ref/debug/)
+
+If after troubleshooting you determine this is actually a bug, please open a new issue with the required debug information from the troubleshooting guide.
+
+This issue has been automatically closed.

.github/workflows/build.yml

@@ -10,6 +10,10 @@ concurrency:
   group: ${{ github.workflow }}-$${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
+defaults:
+  run:
+    shell: nix develop --fallback --command bash -e {0}
+
 jobs:
   build-nix:
     runs-on: ubuntu-latest
@@ -29,33 +33,24 @@ jobs:
               - '**/*.go'
               - 'integration_test/'
               - 'config-example.yaml'
-      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
+      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
         if: steps.changed-files.outputs.files == 'true'
-      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
+      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
         if: steps.changed-files.outputs.files == 'true'
-        with:
-          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix',
-            '**/flake.lock') }}
-          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
 
-      - name: Run nix build
-        id: build
+      - name: Check vendor hash
+        id: vendorhash
         if: steps.changed-files.outputs.files == 'true'
         run: |
-          nix build |& tee build-result
-          BUILD_STATUS="${PIPESTATUS[0]}"
+          go run ./cmd/vendorhash check | tee check-result
+          {
+            grep '^expected_sri=' check-result || true
+            grep '^actual_sri='   check-result || true
+          } >> "$GITHUB_OUTPUT"
 
-          OLD_HASH=$(cat build-result | grep specified: | awk -F ':' '{print $2}' | sed 's/ //g')
-          NEW_HASH=$(cat build-result | grep got: | awk -F ':' '{print $2}' | sed 's/ //g')
-
-          echo "OLD_HASH=$OLD_HASH" >> $GITHUB_OUTPUT
-          echo "NEW_HASH=$NEW_HASH" >> $GITHUB_OUTPUT
-
-          exit $BUILD_STATUS
-
-      - name: Nix gosum diverging
+      - name: Vendor hash diverging
         uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
-        if: failure() && steps.build.outcome == 'failure'
+        if: failure() && steps.vendorhash.outcome == 'failure'
         with:
           github-token: ${{secrets.GITHUB_TOKEN}}
           script: |
@@ -63,9 +58,13 @@ jobs:
               pull_number: context.issue.number,
               owner: context.repo.owner,
               repo: context.repo.repo,
-              body: 'Nix build failed with wrong gosum, please update "vendorSha256" (${{ steps.build.outputs.OLD_HASH }}) for the "headscale" package in flake.nix with the new SHA: ${{ steps.build.outputs.NEW_HASH }}'
+              body: 'Vendor hash in `flakehashes.json` is stale (was `${{ steps.vendorhash.outputs.expected_sri }}`, should be `${{ steps.vendorhash.outputs.actual_sri }}`). Run `go run ./cmd/vendorhash update` and commit the result.'
             })
 
+      - name: Run nix build
+        if: steps.changed-files.outputs.files == 'true'
+        run: nix build --fallback
+
       - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         if: steps.changed-files.outputs.files == 'true'
         with:
@@ -82,17 +81,13 @@ jobs:
           - "GOARCH=amd64 GOOS=darwin"
     steps:
       - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
-      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
-      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
-        with:
-          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix',
-            '**/flake.lock') }}
-          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
+      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
+      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
 
       - name: Run go cross compile
         env:
           CGO_ENABLED: 0
-        run: env ${{ matrix.env }} nix develop --command -- go build -o "headscale"
+        run: env ${{ matrix.env }} go build -o "headscale"
           ./cmd/headscale
       - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:

.github/workflows/check-generated.yml

@@ -12,6 +12,10 @@ concurrency:
   group: ${{ github.workflow }}-$${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
+defaults:
+  run:
+    shell: nix develop --fallback --command bash -e {0}
+
 jobs:
   check-generated:
     runs-on: ubuntu-latest
@@ -28,20 +32,15 @@ jobs:
               - '*.nix'
               - 'go.*'
               - '**/*.go'
-              - '**/*.proto'
-              - 'buf.gen.yaml'
               - 'tools/**'
-      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
+      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
         if: steps.changed-files.outputs.files == 'true'
-      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
+      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
         if: steps.changed-files.outputs.files == 'true'
-        with:
-          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix', '**/flake.lock') }}
-          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
 
       - name: Run make generate
         if: steps.changed-files.outputs.files == 'true'
-        run: nix develop --command -- make generate
+        run: make generate
 
       - name: Check for uncommitted changes
         if: steps.changed-files.outputs.files == 'true'

.github/workflows/check-tests.yaml

@@ -6,6 +6,10 @@ concurrency:
   group: ${{ github.workflow }}-$${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
+defaults:
+  run:
+    shell: nix develop --fallback --command bash -e {0}
+
 jobs:
   check-tests:
     runs-on: ubuntu-latest
@@ -24,19 +28,15 @@ jobs:
               - '**/*.go'
               - 'integration_test/'
               - 'config-example.yaml'
-      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
+      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
         if: steps.changed-files.outputs.files == 'true'
-      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
+      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
         if: steps.changed-files.outputs.files == 'true'
-        with:
-          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix',
-            '**/flake.lock') }}
-          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
 
       - name: Generate and check integration tests
         if: steps.changed-files.outputs.files == 'true'
         run: |
-          nix develop --command bash -c "cd .github/workflows && go generate"
+          (cd .github/workflows && go generate)
           git diff --exit-code .github/workflows/test-integration.yaml
 
       - name: Show missing tests

.github/workflows/container-main.yml

@@ -0,0 +1,108 @@
+---
+name: Build (main)
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "*.nix"
+      - "go.*"
+      - "**/*.go"
+      - ".github/workflows/container-main.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.sha }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: nix develop --fallback --command bash -e {0}
+
+jobs:
+  container:
+    if: github.repository == 'juanfont/headscale'
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Login to DockerHub
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Login to GHCR
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
+      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
+
+      - name: Set commit timestamp
+        run: echo "SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)" >> $GITHUB_ENV
+
+      - name: Build and push to GHCR
+        env:
+          KO_DOCKER_REPO: ghcr.io/juanfont/headscale
+          KO_DEFAULTBASEIMAGE: gcr.io/distroless/base-debian13
+          CGO_ENABLED: "0"
+        run: |
+          ko build \
+            --bare \
+            --platform=linux/amd64,linux/arm64 \
+            --tags=main-${GITHUB_SHA::7},development \
+            ./cmd/headscale
+
+      - name: Push to Docker Hub
+        env:
+          KO_DOCKER_REPO: headscale/headscale
+          KO_DEFAULTBASEIMAGE: gcr.io/distroless/base-debian13
+          CGO_ENABLED: "0"
+        run: |
+          ko build \
+            --bare \
+            --platform=linux/amd64,linux/arm64 \
+            --tags=main-${GITHUB_SHA::7},development \
+            ./cmd/headscale
+
+  binaries:
+    if: github.repository == 'juanfont/headscale'
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - goos: linux
+            goarch: amd64
+          - goos: linux
+            goarch: arm64
+          - goos: darwin
+            goarch: amd64
+          - goos: darwin
+            goarch: arm64
+    steps:
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
+      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
+
+      - name: Build binary
+        env:
+          CGO_ENABLED: "0"
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+        run: go build -o headscale ./cmd/headscale
+
+      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: headscale-${{ matrix.goos }}-${{ matrix.goarch }}
+          path: headscale

.github/workflows/gc.yml

@@ -0,0 +1,39 @@
+name: Cache GC
+
+# Garbage collection for the hestia binary cache. Must run on the default
+# branch: a PR job's cache scope is read-only towards the default branch and
+# dies with the PR, but the default-branch scope grows forever without GC.
+
+concurrency:
+  group: hestia-gc
+  cancel-in-progress: false
+
+on:
+  schedule:
+    # Daily, off-peak (UTC).
+    - cron: "23 3 * * *"
+  workflow_dispatch:
+    inputs:
+      dry-run:
+        description: Plan only; do not repack, touch, or delete anything.
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+jobs:
+  gc:
+    runs-on: ubuntu-latest
+    permissions:
+      # REST cache deletes need actions:write.
+      actions: write
+      contents: read
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
+      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
+      - name: Run garbage collection
+        run: '"${HESTIA_BIN}" gc ${{ inputs.dry-run && ''--dry-run'' || '''' }}'
+        env:
+          GITHUB_TOKEN: ${{ github.token }}

.github/workflows/gh-action-integration-generator.go

@@ -14,7 +14,7 @@ import (
 // Key is the test function name, value is a list of subtest prefixes.
 // Each prefix becomes a separate CI job as "TestName/prefix".
 //
-// Example: TestAutoApproveMultiNetwork has subtests like:
+// Example: [TestAutoApproveMultiNetwork] has subtests like:
 //   - TestAutoApproveMultiNetwork/authkey-tag-advertiseduringup-false-pol-database
 //   - TestAutoApproveMultiNetwork/webauth-user-advertiseduringup-true-pol-file
 //
@@ -66,7 +66,9 @@ func findTests() []string {
 	}
 
 	args := []string{
+		"--type", "go",
 		"--regexp", "func (Test.+)\\(.*",
+		"--max-depth", "1",
 		"../../integration/",
 		"--replace", "$1",
 		"--sort", "path",

.github/workflows/integration-test-template.yml

@@ -16,7 +16,7 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04-arm
     env:
       # Github does not allow us to access secrets in pull requests,
       # so this env var is used to check if we have the secret or not.
@@ -51,6 +51,11 @@ jobs:
         with:
           name: tailscale-head-image
           path: /tmp/artifacts
+      - name: Download tailscale released images
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+        with:
+          name: tailscale-released-images
+          path: /tmp/artifacts
       - name: Download hi binary
         uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         with:
@@ -67,10 +72,26 @@ jobs:
         with:
           name: postgres-image
           path: /tmp/artifacts
+      - name: Force overlay2 storage driver
+        run: |
+          sudo mkdir -p /etc/docker
+          echo '{"storage-driver":"overlay2"}' | sudo tee /etc/docker/daemon.json
+          sudo systemctl restart docker
+          docker version
+      - name: Login to Docker Hub
+        env:
+          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_CI_USERNAME }}
+          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_CI_TOKEN }}
+        if: env.DOCKERHUB_USERNAME != ''
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        with:
+          username: ${{ env.DOCKERHUB_USERNAME }}
+          password: ${{ env.DOCKERHUB_TOKEN }}
       - name: Load Docker images, Go cache, and prepare binary
         run: |
           gunzip -c /tmp/artifacts/headscale-image.tar.gz | docker load
           gunzip -c /tmp/artifacts/tailscale-head-image.tar.gz | docker load
+          gunzip -c /tmp/artifacts/tailscale-released-images.tar.gz | docker load
           if [ -f /tmp/artifacts/postgres-image.tar.gz ]; then
             gunzip -c /tmp/artifacts/postgres-image.tar.gz | docker load
           fi
@@ -87,6 +108,12 @@ jobs:
           HEADSCALE_INTEGRATION_POSTGRES_IMAGE: ${{ inputs.postgres_flag == '--postgres=1' && format('postgres:{0}', github.sha) || '' }}
           HEADSCALE_INTEGRATION_GO_CACHE: /tmp/go-cache/go
           HEADSCALE_INTEGRATION_GO_BUILD_CACHE: /tmp/go-cache/.cache/go-build
+          # Mirror the docker/login-action secrets into env so the
+          # dockertestutil.Credentials resolver picks them up directly
+          # (otherwise it falls back to parsing ~/.docker/config.json,
+          # which works but is one step further from the source).
+          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_CI_USERNAME }}
+          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_CI_TOKEN }}
         run: /tmp/artifacts/hi run --stats --ts-memory-limit=300 --hs-memory-limit=1500 "^${{ inputs.test }}$" \
           --timeout=120m \
           ${{ inputs.postgres_flag }}

.github/workflows/lint.yml

@@ -1,93 +0,0 @@
-name: Lint
-
-on: [pull_request]
-
-concurrency:
-  group: ${{ github.workflow }}-$${{ github.head_ref || github.run_id }}
-  cancel-in-progress: true
-
-jobs:
-  golangci-lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
-        with:
-          fetch-depth: 2
-      - name: Get changed files
-        id: changed-files
-        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
-        with:
-          filters: |
-            files:
-              - '*.nix'
-              - 'go.*'
-              - '**/*.go'
-              - 'integration_test/'
-              - 'config-example.yaml'
-      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
-        if: steps.changed-files.outputs.files == 'true'
-      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
-        if: steps.changed-files.outputs.files == 'true'
-        with:
-          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix',
-            '**/flake.lock') }}
-          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
-
-      - name: golangci-lint
-        if: steps.changed-files.outputs.files == 'true'
-        run: nix develop --command -- golangci-lint run
-          --new-from-rev=${{github.event.pull_request.base.sha}}
-          --output.text.path=stdout
-          --output.text.print-linter-name
-          --output.text.print-issued-lines
-          --output.text.colors
-
-  prettier-lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
-        with:
-          fetch-depth: 2
-      - name: Get changed files
-        id: changed-files
-        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
-        with:
-          filters: |
-            files:
-              - '*.nix'
-              - '**/*.md'
-              - '**/*.yml'
-              - '**/*.yaml'
-              - '**/*.ts'
-              - '**/*.js'
-              - '**/*.sass'
-              - '**/*.css'
-              - '**/*.scss'
-              - '**/*.html'
-      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
-        if: steps.changed-files.outputs.files == 'true'
-      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
-        if: steps.changed-files.outputs.files == 'true'
-        with:
-          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix',
-            '**/flake.lock') }}
-          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
-
-      - name: Prettify code
-        if: steps.changed-files.outputs.files == 'true'
-        run: nix develop --command -- prettier --no-error-on-unmatched-pattern
-          --ignore-unknown --check **/*.{ts,js,md,yaml,yml,sass,css,scss,html}
-
-  proto-lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
-      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
-      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
-        with:
-          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix',
-            '**/flake.lock') }}
-          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
-
-      - name: Buf lint
-        run: nix develop --command -- buf lint proto

.github/workflows/needs-more-info-comment.yml

@@ -0,0 +1,28 @@
+name: Needs More Info - Post Comment
+
+on:
+  issues:
+    types: [labeled]
+
+jobs:
+  post-comment:
+    if: >-
+      github.event.label.name == 'needs-more-info' &&
+      github.repository == 'juanfont/headscale'
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          sparse-checkout: .github/label-response/needs-more-info.md
+          sparse-checkout-cone-mode: false
+
+      - name: Post instruction comment
+        run: gh issue comment "$NUMBER" --body-file .github/label-response/needs-more-info.md
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+          NUMBER: ${{ github.event.issue.number }}

.github/workflows/needs-more-info-timer.yml

@@ -0,0 +1,99 @@
+name: Needs More Info - Timer
+
+on:
+  schedule:
+    - cron: "0 0 * * *" # Daily at midnight UTC
+  issue_comment:
+    types: [created]
+  workflow_dispatch:
+
+jobs:
+  # When a non-bot user comments on a needs-more-info issue, remove the label.
+  remove-label-on-response:
+    if: >-
+      github.repository == 'juanfont/headscale' &&
+      github.event_name == 'issue_comment' &&
+      github.event.comment.user.type != 'Bot' &&
+      contains(github.event.issue.labels.*.name, 'needs-more-info')
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - name: Remove needs-more-info label
+        run: gh issue edit "$NUMBER" --remove-label needs-more-info
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+          NUMBER: ${{ github.event.issue.number }}
+
+  # On schedule, close issues that have had no human response for 3 days.
+  close-stale:
+    if: >-
+      github.repository == 'juanfont/headscale' &&
+      github.event_name != 'issue_comment'
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - uses: hustcer/setup-nu@920172d92eb04671776f3ba69d605d3b09351c30 # v3.22
+        with:
+          version: "*"
+
+      - name: Close stale needs-more-info issues
+        shell: nu {0}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          let issues = (gh issue list
+            --repo $env.GH_REPO
+            --label "needs-more-info"
+            --state open
+            --json number
+            | from json)
+
+          for issue in $issues {
+            let number = $issue.number
+            print $"Checking issue #($number)"
+
+            # Find when needs-more-info was last added
+            let events = (gh api $"repos/($env.GH_REPO)/issues/($number)/events"
+              --paginate | from json)
+            let label_event = ($events
+              | where event == "labeled"
+              | where label.name == "needs-more-info"
+              | last)
+            let label_added_at = ($label_event.created_at | into datetime)
+
+            # Check for non-bot comments after the label was added
+            let comments = (gh api $"repos/($env.GH_REPO)/issues/($number)/comments"
+              --paginate | from json)
+            let human_responses = ($comments
+              | where user.type != "Bot"
+              | where { ($in.created_at | into datetime) > $label_added_at })
+
+            if ($human_responses | length) > 0 {
+              print $"  Human responded, removing label"
+              gh issue edit $number --repo $env.GH_REPO --remove-label needs-more-info
+              continue
+            }
+
+            # Check if 3 days have passed
+            let elapsed = (date now) - $label_added_at
+            if $elapsed < 3day {
+              print $"  Only ($elapsed | format duration day) elapsed, skipping"
+              continue
+            }
+
+            print $"  No response for ($elapsed | format duration day), closing"
+            let message = [
+              "This issue has been automatically closed because no additional information was provided within 3 days."
+              ""
+              "If you have the requested information, please open a new issue and include the debug information requested above."
+              ""
+              "Thank you for your understanding."
+            ] | str join "\n"
+            gh issue comment $number --repo $env.GH_REPO --body $message
+            gh issue close $number --repo $env.GH_REPO --reason "not planned"
+            gh issue edit $number --repo $env.GH_REPO --remove-label needs-more-info
+          }

.github/workflows/nix-checks.yml

@@ -0,0 +1,56 @@
+name: Nix Flake Checks
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-$${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+# Each job only runs `nix build .#checks.<system>.<name>`; the check logic lives
+# in flake.nix via the flake-checks library. The fileset-filtered checks hit the
+# hestia cache when their inputs are unchanged, so no changed-files gating.
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
+      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
+      - name: build
+        run: nix build -L .#checks.x86_64-linux.build
+
+  gotest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
+      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
+      - name: gotest
+        run: nix build -L .#checks.x86_64-linux.gotest
+
+  golangci-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
+      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
+      - name: golangci-lint
+        run: nix build -L .#checks.x86_64-linux.golangci-lint
+
+  formatting:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
+      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
+      - name: formatting
+        run: nix build -L .#checks.x86_64-linux.formatting

.github/workflows/nix-module-test.yml

@@ -38,18 +38,14 @@ jobs:
               - 'cmd/**'
               - 'hscontrol/**'
 
-      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
+      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
         if: steps.changed-files.outputs.nix == 'true' || steps.changed-files.outputs.go == 'true'
 
-      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
+      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
         if: steps.changed-files.outputs.nix == 'true' || steps.changed-files.outputs.go == 'true'
-        with:
-          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix',
-            '**/flake.lock') }}
-          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
 
       - name: Run NixOS module tests
         if: steps.changed-files.outputs.nix == 'true' || steps.changed-files.outputs.go == 'true'
         run: |
           echo "Running NixOS module integration test..."
-          nix build .#checks.x86_64-linux.headscale -L
+          nix build .#checks.x86_64-linux.headscale -L --fallback

.github/workflows/release.yml

@@ -7,6 +7,10 @@ on:
       - "*" # triggers only if push new tag version
   workflow_dispatch:
 
+defaults:
+  run:
+    shell: nix develop --fallback --command bash -e {0}
+
 jobs:
   goreleaser:
     if: github.repository == 'juanfont/headscale'
@@ -30,14 +34,10 @@ jobs:
           username: ${{ github.repository_owner }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
-      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
-        with:
-          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix',
-            '**/flake.lock') }}
-          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
+      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
+      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
 
       - name: Run goreleaser
-        run: nix develop --command -- goreleaser release --clean
+        run: goreleaser release --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/servertest.yml

@@ -0,0 +1,36 @@
+name: Server Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-$${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+# hscontrol/servertest is excluded from the sandboxed gotest flake check: it is
+# slow (10s+ convergence cases) and timing-sensitive (race/stress/HA property
+# tests), so it runs here in the devShell with a generous timeout instead.
+defaults:
+  run:
+    shell: nix develop --fallback --command bash -e {0}
+
+permissions:
+  contents: read
+
+jobs:
+  servertest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
+      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
+
+      - name: go test ./hscontrol/servertest
+        env:
+          CGO_ENABLED: "0"
+        run: go test -timeout=20m ./hscontrol/servertest/...

.github/workflows/stale.yml

@@ -23,5 +23,5 @@ jobs:
             since being marked as stale."
           days-before-pr-stale: -1
           days-before-pr-close: -1
-          exempt-issue-labels: "no-stale-bot"
+          exempt-issue-labels: "no-stale-bot,needs-more-info"
           repo-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/support-request.yml

@@ -0,0 +1,30 @@
+name: Support Request - Close Issue
+
+on:
+  issues:
+    types: [labeled]
+
+jobs:
+  close-support-request:
+    if: >-
+      github.event.label.name == 'support-request' &&
+      github.repository == 'juanfont/headscale'
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          sparse-checkout: .github/label-response/support-request.md
+          sparse-checkout-cone-mode: false
+
+      - name: Post comment and close issue
+        run: |
+          gh issue comment "$NUMBER" --body-file .github/label-response/support-request.md
+          gh issue close "$NUMBER" --reason "not planned"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+          NUMBER: ${{ github.event.issue.number }}

.github/workflows/test-integration.yaml

@@ -6,13 +6,19 @@ on: [pull_request]
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
+defaults:
+  run:
+    shell: nix develop --fallback --command bash -e {0}
 jobs:
   # build: Builds binaries and Docker images once, uploads as artifacts for reuse.
   # build-postgres: Pulls postgres image separately to avoid Docker Hub rate limits.
+  # build-tailscale-released: Pre-pulls released Tailscale images from ghcr.io
+  # so fork PRs (no DOCKERHUB_USERNAME secret) don't hit Docker Hub rate
+  # limits at test time.
   # sqlite: Runs all integration tests with SQLite backend.
   # postgres: Runs a subset of tests with PostgreSQL to verify database compatibility.
   build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04-arm
     outputs:
       files-changed: ${{ steps.changed-files.outputs.files }}
     steps:
@@ -33,23 +39,18 @@ jobs:
               - '.github/workflows/test-integration.yaml'
               - '.github/workflows/integration-test-template.yml'
               - 'Dockerfile.*'
-      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
+      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
         if: steps.changed-files.outputs.files == 'true'
-      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
+      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
         if: steps.changed-files.outputs.files == 'true'
-        with:
-          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix', '**/flake.lock') }}
-          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
       - name: Build binaries and warm Go cache
         if: steps.changed-files.outputs.files == 'true'
         run: |
           # Build all Go binaries in one nix shell to maximize cache reuse
-          nix develop --command -- bash -c '
-            go build -o hi ./cmd/hi
-            CGO_ENABLED=0 GOOS=linux go build -o headscale ./cmd/headscale
-            # Build integration test binary to warm the cache with all dependencies
-            go test -c ./integration -o /dev/null 2>/dev/null || true
-          '
+          go build -o hi ./cmd/hi
+          CGO_ENABLED=0 GOOS=linux go build -o headscale ./cmd/headscale
+          # Build integration test binary to warm the cache with all dependencies
+          go test -c ./integration -o /dev/null 2>/dev/null || true
       - name: Upload hi binary
         if: steps.changed-files.outputs.files == 'true'
         uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
@@ -69,6 +70,26 @@ jobs:
           name: go-cache
           path: go-cache.tar.gz
           retention-days: 10
+      - name: Force overlay2 storage driver
+        if: steps.changed-files.outputs.files == 'true'
+        run: |
+          # Docker 29 runner images default to overlayfs, which breaks
+          # docker build via Go SDK libraries and docker save/load
+          # tarball formats. overlay2 is the long-standing default.
+          # https://github.com/actions/runner-images/issues/13474
+          sudo mkdir -p /etc/docker
+          echo '{"storage-driver":"overlay2"}' | sudo tee /etc/docker/daemon.json
+          sudo systemctl restart docker
+          docker version
+      - name: Login to Docker Hub
+        env:
+          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_CI_USERNAME }}
+          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_CI_TOKEN }}
+        if: env.DOCKERHUB_USERNAME != ''
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        with:
+          username: ${{ env.DOCKERHUB_USERNAME }}
+          password: ${{ env.DOCKERHUB_TOKEN }}
       - name: Build headscale image
         if: steps.changed-files.outputs.files == 'true'
         run: |
@@ -100,11 +121,28 @@ jobs:
           path: tailscale-head-image.tar.gz
           retention-days: 10
   build-postgres:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04-arm
     needs: build
     if: needs.build.outputs.files-changed == 'true'
     steps:
+      - name: Force overlay2 storage driver
+        shell: bash
+        run: |
+          sudo mkdir -p /etc/docker
+          echo '{"storage-driver":"overlay2"}' | sudo tee /etc/docker/daemon.json
+          sudo systemctl restart docker
+          docker version
+      - name: Login to Docker Hub
+        env:
+          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_CI_USERNAME }}
+          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_CI_TOKEN }}
+        if: env.DOCKERHUB_USERNAME != ''
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        with:
+          username: ${{ env.DOCKERHUB_USERNAME }}
+          password: ${{ env.DOCKERHUB_TOKEN }}
       - name: Pull and save postgres image
+        shell: bash
         run: |
           docker pull postgres:latest
           docker tag postgres:latest postgres:${{ github.sha }}
@@ -115,9 +153,68 @@ jobs:
           name: postgres-image
           path: postgres-image.tar.gz
           retention-days: 10
-  sqlite:
+  build-tailscale-released:
+    runs-on: ubuntu-24.04-arm
     needs: build
     if: needs.build.outputs.files-changed == 'true'
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
+      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
+      - name: Force overlay2 storage driver
+        run: |
+          sudo mkdir -p /etc/docker
+          echo '{"storage-driver":"overlay2"}' | sudo tee /etc/docker/daemon.json
+          sudo systemctl restart docker
+          docker version
+      - name: Login to Docker Hub
+        env:
+          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_CI_USERNAME }}
+          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_CI_TOKEN }}
+        if: env.DOCKERHUB_USERNAME != ''
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        with:
+          username: ${{ env.DOCKERHUB_USERNAME }}
+          password: ${{ env.DOCKERHUB_TOKEN }}
+      - name: List Tailscale versions to pre-pull
+        id: versions
+        run: |
+          versions=$(go run ./cmd/hi list-versions --set=must --exclude=head)
+          echo "versions=${versions}" >> "$GITHUB_OUTPUT"
+          echo "Pre-pulling: ${versions}"
+      - name: Pull Tailscale images
+        run: |
+          # Releases come from ghcr.io (anonymous, unmetered). The
+          # "unstable" floating tag on ghcr.io has been stale since 2022,
+          # so it still needs to come from Docker Hub. xargs -P 0 fans
+          # out one process per tag and returns non-zero if any pull
+          # fails.
+          refs=""
+          for v in ${{ steps.versions.outputs.versions }}; do
+            if [ "${v}" = "unstable" ]; then
+              refs="${refs} tailscale/tailscale:${v}"
+            else
+              refs="${refs} ghcr.io/tailscale/tailscale:${v}"
+            fi
+          done
+          echo "${refs}" | tr ' ' '\n' | grep -v '^$' \
+            | xargs -P 0 -I{} docker pull "{}"
+          echo "REFS=${refs}" >> "$GITHUB_ENV"
+      - name: Save Tailscale images to tarball
+        run: |
+          # Single docker save with all refs: one consistent snapshot, no
+          # parallel-daemon race.
+          docker save ${REFS} | gzip > tailscale-released-images.tar.gz
+          ls -lh tailscale-released-images.tar.gz
+      - name: Upload Tailscale released images
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: tailscale-released-images
+          path: tailscale-released-images.tar.gz
+          retention-days: 10
+  sqlite:
+    needs: [build, build-tailscale-released]
+    if: needs.build.outputs.files-changed == 'true'
     strategy:
       fail-fast: false
       matrix:
@@ -144,7 +241,7 @@ jobs:
           - TestACLDynamicUnknownUserRemoval
           - TestAPIAuthenticationBypass
           - TestAPIAuthenticationBypassCurl
-          - TestGRPCAuthenticationBypass
+          - TestRemoteCLIAuthenticationBypass
           - TestCLIWithConfigAuthenticationBypass
           - TestAuthKeyLogoutAndReloginSameUser
           - TestAuthKeyLogoutAndReloginNewUser
@@ -165,18 +262,34 @@ jobs:
           - TestAuthWebFlowAuthenticationPingAll
           - TestAuthWebFlowLogoutAndReloginSameUser
           - TestAuthWebFlowLogoutAndReloginNewUser
-          - TestUserCommand
-          - TestPreAuthKeyCommand
-          - TestPreAuthKeyCommandWithoutExpiry
-          - TestPreAuthKeyCommandReusableEphemeral
-          - TestPreAuthKeyCorrectUserLoggedInCommand
-          - TestTaggedNodesCLIOutput
           - TestApiKeyCommand
+          - TestApiKeyCommandValidation
+          - TestAuthCommandValidation
           - TestNodeCommand
           - TestNodeExpireCommand
           - TestNodeRenameCommand
+          - TestPreAuthKeyCorrectUserLoggedInCommand
+          - TestTaggedNodesCLIOutput
+          - TestNodeExpireFlagsCommand
+          - TestNodeCommandValidation
+          - TestNodeTagCommand
+          - TestNodeRouteCommands
+          - TestNodeBackfillIPsCommand
+          - TestOAuthClientCommand
+          - TestOAuthClientCommandValidation
+          - TestPolicyCheckCommand
+          - TestSSHTestsRejectFailingPolicy
           - TestPolicyCommand
           - TestPolicyBrokenConfigCommand
+          - TestPreAuthKeyCommand
+          - TestPreAuthKeyCommandWithoutExpiry
+          - TestPreAuthKeyCommandReusableEphemeral
+          - TestPreAuthKeyDeleteCommand
+          - TestPreAuthKeyCommandValidation
+          - TestServerInfoCommands
+          - TestUserCommand
+          - TestUserCreateCommand
+          - TestUserCommandValidation
           - TestDERPVerifyEndpoint
           - TestResolveMagicDNS
           - TestResolveMagicDNSExtraRecordsPath
@@ -192,13 +305,17 @@ jobs:
           - TestUpdateHostnameFromClient
           - TestExpireNode
           - TestSetNodeExpiryInFuture
+          - TestDisableNodeExpiry
           - TestNodeOnlineStatus
           - TestPingAllByIPManyUpDown
           - Test2118DeletingOnlineNodePanics
+          - TestGrantCapRelay
+          - TestGrantCapDrive
           - TestEnablingRoutes
           - TestHASubnetRouterFailover
           - TestSubnetRouteACL
           - TestEnablingExitRoutes
+          - TestExitRoutesWithAutogroupInternetACL
           - TestSubnetRouterMultiNetwork
           - TestSubnetRouterMultiNetworkExitNode
           - TestAutoApproveMultiNetwork/authkey-tag.*
@@ -208,6 +325,11 @@ jobs:
           - TestAutoApproveMultiNetwork/webauth-user.*
           - TestAutoApproveMultiNetwork/webauth-group.*
           - TestSubnetRouteACLFiltering
+          - TestGrantViaSubnetSteering
+          - TestHASubnetRouterPingFailover
+          - TestHASubnetRouterFailoverBothOffline
+          - TestHASubnetRouterFailoverBothOfflineCablePull
+          - TestHASubnetRouterFailoverDockerDisconnect
           - TestHeadscale
           - TestTailscaleNodesJoiningHeadcale
           - TestSSHOneUserToAll
@@ -216,6 +338,14 @@ jobs:
           - TestSSHIsBlockedInACL
           - TestSSHUserOnlyIsolation
           - TestSSHAutogroupSelf
+          - TestSSHOneUserToOneCheckModeCLI
+          - TestSSHOneUserToOneCheckModeOIDC
+          - TestSSHCheckModeUnapprovedTimeout
+          - TestSSHCheckModeCheckPeriodCLI
+          - TestSSHCheckModeAutoApprove
+          - TestSSHCheckModeSessionLossReDelegates
+          - TestSSHCheckModeNegativeCLI
+          - TestSSHLocalpart
           - TestTagsAuthKeyWithTagRequestDifferentTag
           - TestTagsAuthKeyWithTagNoAdvertiseFlag
           - TestTagsAuthKeyWithTagCannotAddViaCLI
@@ -248,6 +378,7 @@ jobs:
           - TestTagsAuthKeyWithoutUserInheritsTags
           - TestTagsAuthKeyWithoutUserRejectsAdvertisedTags
           - TestTagsAuthKeyConvertToUserViaCLIRegister
+          - TestTailscaleRustAxum
     uses: ./.github/workflows/integration-test-template.yml
     secrets: inherit
     with:
@@ -255,7 +386,7 @@ jobs:
       postgres_flag: "--postgres=0"
       database_name: "sqlite"
   postgres:
-    needs: [build, build-postgres]
+    needs: [build, build-postgres, build-tailscale-released]
     if: needs.build.outputs.files-changed == 'true'
     strategy:
       fail-fast: false

.github/workflows/test.yml

@@ -1,47 +0,0 @@
-name: Tests
-
-on: [push, pull_request]
-
-concurrency:
-  group: ${{ github.workflow }}-$${{ github.head_ref || github.run_id }}
-  cancel-in-progress: true
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
-        with:
-          fetch-depth: 2
-
-      - name: Get changed files
-        id: changed-files
-        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
-        with:
-          filters: |
-            files:
-              - '*.nix'
-              - 'go.*'
-              - '**/*.go'
-              - 'integration_test/'
-              - 'config-example.yaml'
-
-      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
-        if: steps.changed-files.outputs.files == 'true'
-      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
-        if: steps.changed-files.outputs.files == 'true'
-        with:
-          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix',
-            '**/flake.lock') }}
-          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
-
-      - name: Run tests
-        if: steps.changed-files.outputs.files == 'true'
-        env:
-          # As of 2025-01-06, these env vars was not automatically
-          # set anymore which breaks the initdb for postgres on
-          # some of the database migration tests.
-          LC_ALL: "en_US.UTF-8"
-          LC_CTYPE: "en_US.UTF-8"
-        run: nix develop --command -- gotestsum

.github/workflows/update-flake.yml

@@ -1,19 +0,0 @@
-name: update-flake-lock
-on:
-  workflow_dispatch: # allows manual triggering
-  schedule:
-    - cron: "0 0 * * 0" # runs weekly on Sunday at 00:00
-
-jobs:
-  lockfile:
-    if: github.repository == 'juanfont/headscale'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-      - name: Install Nix
-        uses: DeterminateSystems/nix-installer-action@21a544727d0c62386e78b4befe52d19ad12692e3 # v17
-      - name: Update flake.lock
-        uses: DeterminateSystems/update-flake-lock@428c2b58a4b7414dabd372acb6a03dba1084d3ab # v25
-        with:
-          pr-title: "Update flake.lock"

.gitignore

@@ -29,6 +29,7 @@ config*.yaml
 !config-example.yaml
 derp.yaml
 *.hujson
+!hscontrol/policy/v2/testdata/*/*.hujson
 *.key
 /db.sqlite
 *.sqlite3
@@ -45,6 +46,9 @@ result
 
 integration_test/etc/config.dump.yaml
 
+# OpenAPI spec is served live from the code and emitted on demand, not committed
+/openapi/v1/headscale.yaml
+
 # MkDocs
 .cache
 /site

.golangci.yaml

@@ -13,11 +13,13 @@ linters:
     - gochecknoinits
     - gocognit
     - godox
+    - gomodguard
     - interfacebloat
     - ireturn
     - lll
     - maintidx
     - makezero
+    - mnd
     - musttag
     - nestif
     - nolintlint
@@ -29,6 +31,17 @@ linters:
     - wrapcheck
     - wsl
   settings:
+    goconst:
+      # Test fixtures repeat strings (IPs, tags, hostnames) by their
+      # nature; extracting them obscures the test rather than helping.
+      # Production code stays strict.
+      ignore-tests: true
+      # Default is 3. Bump so "happens thrice" cases that are not part
+      # of a shared vocabulary do not get extracted.
+      min-occurrences: 5
+      # Default is 3. Short literals ("set", "get", "new") read better
+      # at call sites than behind a named constant.
+      min-len: 6
     forbidigo:
       forbid:
         # Forbid time.Sleep everywhere with context-appropriate alternatives
@@ -37,6 +50,23 @@ linters:
             time.Sleep is forbidden.
             In tests: use assert.EventuallyWithT for polling/waiting patterns.
             In production code: use a backoff strategy (e.g., cenkalti/backoff) or proper synchronization primitives.
+        # Forbid inline string literals in zerolog field methods - use zf.* constants
+        - pattern: '\.(Str|Int|Int8|Int16|Int32|Int64|Uint|Uint8|Uint16|Uint32|Uint64|Float32|Float64|Bool|Dur|Time|TimeDiff|Strs|Ints|Uints|Floats|Bools|Any|Interface)\("[^"]+"'
+          msg: >-
+            Use zf.* constants for zerolog field names instead of string literals.
+            Import "github.com/juanfont/headscale/hscontrol/util/zlog/zf" and use
+            constants like zf.NodeID, zf.UserName, etc. Add new constants to
+            hscontrol/util/zlog/zf/fields.go if needed.
+        # Forbid ptr.To - use Go 1.26 new(expr) instead
+        - pattern: 'ptr\.To\('
+          msg: >-
+            ptr.To is forbidden. Use Go 1.26's new(expr) syntax instead.
+            Example: ptr.To(value) → new(value)
+        # Forbid tsaddr.SortPrefixes - use slices.SortFunc with netip.Prefix.Compare
+        - pattern: 'tsaddr\.SortPrefixes'
+          msg: >-
+            tsaddr.SortPrefixes is forbidden. Use Go 1.26's netip.Prefix.Compare instead.
+            Example: slices.SortFunc(prefixes, netip.Prefix.Compare)
       analyze-types: true
     gocritic:
       disabled-checks:

.goreleaser.yml

@@ -2,7 +2,7 @@
 version: 2
 before:
   hooks:
-    - go mod tidy -compat=1.25
+    - go mod tidy -compat=1.26
     - go mod vendor
 
 release:
@@ -13,29 +13,6 @@ release:
 
     Please follow the steps outlined in the [upgrade guide](https://headscale.net/stable/setup/upgrade/) to update your existing Headscale installation.
 
-    **It's best to update from one stable version to the next** (e.g., 0.24.0 → 0.25.1 → 0.26.1) in case you are multiple releases behind. You should always pick the latest available patch release.
-
-    Be sure to check the changelog above for version-specific upgrade instructions and breaking changes.
-
-    ### Backup Your Database
-
-    **Always backup your database before upgrading.** Here's how to backup a SQLite database:
-
-    ```bash
-    # Stop headscale
-    systemctl stop headscale
-
-    # Backup sqlite database
-    cp /var/lib/headscale/db.sqlite /var/lib/headscale/db.sqlite.backup
-
-    # Backup sqlite WAL/SHM files (if they exist)
-    cp /var/lib/headscale/db.sqlite-wal /var/lib/headscale/db.sqlite-wal.backup
-    cp /var/lib/headscale/db.sqlite-shm /var/lib/headscale/db.sqlite-shm.backup
-
-    # Start headscale (migration will run automatically)
-    systemctl start headscale
-    ```
-
 builds:
   - id: headscale
     main: ./cmd/headscale
@@ -50,8 +27,6 @@ builds:
       - linux_arm64
     flags:
       - -mod=readonly
-    tags:
-      - ts2019
 
 archives:
   - id: golang-cross
@@ -67,10 +42,9 @@ source:
     - "vendor/"
 
 nfpms:
-  # Configure nFPM for .deb and .rpm releases
+  # Configure nFPM for .deb releases
   #
-  # See https://nfpm.goreleaser.com/configuration/
-  # and https://goreleaser.com/customization/nfpm/
+  # See https://goreleaser.com/customization/package/nfpm/
   #
   # Useful tools for debugging .debs:
   # List file contents: dpkg -c dist/headscale...deb
@@ -104,6 +78,8 @@ nfpms:
         dst: /usr/lib/systemd/system/headscale.service
       - dst: /var/lib/headscale
         type: dir
+      - src: ./config-example.yaml
+        dst: /usr/share/doc/headscale/examples/config-example.yaml
       - src: LICENSE
         dst: /usr/share/doc/headscale/copyright
     scripts:

.mdformat.toml

@@ -0,0 +1,2 @@
+[plugin.mkdocs]
+align_semantic_breaks_in_lists = true

.pre-commit-config.yaml

@@ -2,8 +2,9 @@
 # See: https://prek.j178.dev/quickstart/
 # See: https://prek.j178.dev/builtin/
 
-# Global exclusions - ignore generated code
-exclude: ^gen/
+# Global exclusions - ignore generated code (proto output and emitted OpenAPI)
+# and recorded golden fixtures.
+exclude: ^(gen|openapi)/|^hscontrol/testdata/apiv1_golden/
 
 repos:
   # Built-in hooks from pre-commit/pre-commit-hooks
@@ -13,6 +14,7 @@ repos:
     rev: v6.0.0
     hooks:
       - id: check-added-large-files
+        args: [--maxkb=1024]
       - id: check-case-conflict
       - id: check-executables-have-shebangs
       - id: check-json
@@ -43,26 +45,28 @@ repos:
         entry: prettier --write --list-different
         language: system
         exclude: ^docs/
-        types_or:
-          [
-            javascript,
-            jsx,
-            ts,
-            tsx,
-            yaml,
-            json,
-            toml,
-            html,
-            css,
-            scss,
-            sass,
-            markdown,
-          ]
+        types_or: [javascript, jsx, ts, tsx, yaml, json, toml, html, css, scss, sass, markdown]
+
+      # mdformat for docs
+      - id: mdformat
+        name: mdformat
+        entry: mdformat
+        language: system
+        types_or: [markdown]
+        files: ^docs/
 
       # golangci-lint for Go code quality
       - id: golangci-lint
         name: golangci-lint
-        entry: nix develop --command golangci-lint run --new-from-rev=HEAD~1 --timeout=5m --fix
+        entry: nix develop --command -- golangci-lint run --new-from-rev=HEAD~1 --timeout=5m --fix
         language: system
         types: [go]
         pass_filenames: false
+
+      # vendor-hash keeps flakehashes.json in sync with go.mod/go.sum.
+      - id: vendor-hash
+        name: vendor-hash
+        entry: nix develop --command -- go run ./cmd/vendorhash check
+        language: system
+        files: ^(go\.mod|go\.sum|flakehashes\.json)$
+        pass_filenames: false

.prettierignore

@@ -1,5 +1,2 @@
 .github/workflows/test-integration-v2*
-docs/about/features.md
-docs/ref/api.md
-docs/ref/configuration.md
-docs/ref/oidc.md
+docs/

CHANGELOG.md

@@ -1,6 +1,366 @@
 # CHANGELOG
 
-## 0.29.0 (202x-xx-xx)
+## 0.30.0 (202x-xx-xx)
+
+**Minimum supported Tailscale client version: v1.xx.0**
+
+### v1 REST API replaced; gRPC and Protobuf removed
+
+The v1 REST API now provides an OpenAPI 3.1 specification at
+`/api/v1/openapi.yaml`, with interactive documentation at `/api/v1/docs`. This
+replaces the Swagger 2.0 document and the `/swagger` UI. The Protobuf, gRPC and
+grpc-gateway stack behind it is gone, and the `headscale` CLI now talks to the
+HTTP API directly.
+
+[#3324](https://github.com/juanfont/headscale/pull/3324)
+
+### OAuth clients and scopes for the v2 API
+
+The v2 API now authenticates with OAuth 2.0 client-credentials, the way the
+Tailscale ecosystem does. An OAuth client mints short-lived access tokens whose
+scopes limit which operations they may perform and whose tags limit the devices
+they may create, so a credential can be issued with only the access it needs.
+The `headscale oauth-clients` command manages them. This lets the Tailscale
+Terraform provider and Kubernetes operator drive Headscale unchanged; admin API
+keys remain all-access.
+
+[#3334](https://github.com/juanfont/headscale/pull/3334)
+
+### BREAKING
+
+#### API
+
+- The gRPC API is removed; all programmatic access now goes through the HTTP API at `/api/v1` [#3324](https://github.com/juanfont/headscale/pull/3324)
+- API errors are now RFC 7807 `application/problem+json`, including authentication failures, instead of the previous gRPC-status JSON shape [#3324](https://github.com/juanfont/headscale/pull/3324)
+- Errors that previously returned HTTP 500 — unknown users or nodes, malformed input, duplicate names — now return the correct 404, 400 or 409 [#3324](https://github.com/juanfont/headscale/pull/3324)
+- The OpenAPI document is OpenAPI 3.1 at `/api/v1/openapi.yaml` (docs at `/api/v1/docs`), replacing Swagger 2.0 at `/swagger` [#3324](https://github.com/juanfont/headscale/pull/3324)
+
+#### CLI
+
+- `--output json` / `--output yaml` now emit the API's shape — camelCase fields, string-encoded IDs, RFC3339 timestamps — instead of the old Protobuf encoding [#3324](https://github.com/juanfont/headscale/pull/3324)
+- `headscale policy` renames the database-bypass flag from `--bypass-grpc-and-access-database-directly` to `--bypass-server-and-access-database-directly` [#3324](https://github.com/juanfont/headscale/pull/3324)
+
+### Changes
+
+- Expiring or deleting a non-existent pre-auth key now returns an error instead of silently succeeding [#3324](https://github.com/juanfont/headscale/pull/3324)
+
+## 0.29.1 (2026-06-18)
+
+**Minimum supported Tailscale client version: v1.80.0**
+
+### Changes
+
+- Fix nodes with `tags='null'` losing their assigned user on upgrade [#3325](https://github.com/juanfont/headscale/pull/3325)
+
+## 0.29.0 (2026-06-17)
+
+**Minimum supported Tailscale client version: v1.80.0**
+
+### Tailscale ACL compatibility improvements
+
+Extensive test cases were systematically generated using Tailscale clients and the official SaaS
+to understand how the packet filter should be generated. We discovered a few differences, but
+overall our implementation was very close.
+[#3036](https://github.com/juanfont/headscale/pull/3036)
+
+### SSH check action
+
+SSH rules with `"action": "check"` are now supported. When a client initiates a SSH connection to a node
+with a `check` action policy, the user is prompted to authenticate via OIDC or CLI approval before access
+is granted. OIDC approval requires the authenticated user to own the source node; tagged source nodes
+cannot use SSH check-mode.
+
+A new `headscale auth` CLI command group supports the approval flow:
+
+- `headscale auth approve --auth-id <id>` approves a pending authentication request (SSH check or web auth)
+- `headscale auth reject --auth-id <id>` rejects a pending authentication request
+- `headscale auth register --auth-id <id> --user <user>` registers a node (replaces deprecated `headscale nodes register`)
+
+[#1850](https://github.com/juanfont/headscale/pull/1850)
+[#3180](https://github.com/juanfont/headscale/pull/3180)
+
+### Policy tests (beta)
+
+Headscale now evaluates the `tests` block in a policy file. Tests assert reachability between
+named sources and destinations and cover the whole policy — both `acls` and `grants` rules
+contribute. They run on user-initiated writes via `headscale policy set`, on SIGHUP reload
+(`systemctl reload headscale` / `kill -HUP $(pidof headscale)`), and on `headscale policy check`.
+A failing test rejects the write before it is applied, with the same error message Tailscale SaaS
+would return for the same policy.
+
+At boot a stored policy whose tests no longer pass — for example because a referenced user was
+deleted while the server was offline — logs a warning and the server keeps running. Fix the
+policy and reload.
+
+This feature is **beta** while behavioural coverage against Tailscale SaaS broadens.
+
+[#3229](https://github.com/juanfont/headscale/pull/3229)
+
+### SSH policy tests (beta)
+
+Headscale now evaluates the `sshTests` block in a policy file. Each entry names a source, one or
+more destination hosts, and three optional user lists: `accept` asserts the listed login users
+reach every destination via an accept- or check-action SSH rule, `deny` asserts none of them
+reach any destination, and `check` requires reachability specifically through a check-action
+rule. Tests run on `headscale policy set`, on SIGHUP reload (`systemctl reload headscale` /
+`kill -HUP $(pidof headscale)`), and on `headscale policy check`. A failing test rejects the
+write before it is applied, with the same error message Tailscale SaaS would return for the same
+policy.
+
+At boot a stored policy whose sshTests no longer pass — for example because a referenced user was
+deleted while the server was offline — logs a warning and the server keeps running. Fix the
+policy and reload.
+
+This feature is **beta** while behavioural coverage against Tailscale SaaS broadens.
+
+[#3263](https://github.com/juanfont/headscale/pull/3263)
+
+### SSH rule validation
+
+SSH rule parsing now trims surrounding whitespace on `action`, `users`, `src`, and `dst`,
+rejects empty or wildcard entries in `users`, rejects empty `acceptEnv`, and rejects negative
+`checkPeriod`. `hosts:` aliases are rejected as SSH destinations, non-ASCII tag names are
+rejected at parse time, and the wording for group-nesting cycles matches Tailscale SaaS.
+[#3263](https://github.com/juanfont/headscale/pull/3263)
+
+### Grants
+
+We now support [Tailscale grants](https://tailscale.com/docs/features/access-control/grants)
+alongside ACLs. Grants extend what you can express in a policy beyond packet filtering: the `app`
+field controls application-level features like Taildrive file sharing and peer relay, and the `via`
+field steers traffic through specific tagged subnet routers or exit nodes. The `ip` field works like
+an ACL rule. Grants can be mixed with ACLs in the same policy file.
+[#2180](https://github.com/juanfont/headscale/pull/2180)
+
+As part of this, we added `autogroup:danger-all`. It resolves to `0.0.0.0/0` and `::/0`, all IP
+addresses, including those outside the tailnet. This replaces the old behaviour where `*` matched
+all IPs (see BREAKING below). The name is intentional: accepting traffic from the entire
+internet is a security-sensitive choice. `autogroup:danger-all` can only be used as a source.
+
+### Node attributes (`nodeAttrs`)
+
+ACL policies now accept a `nodeAttrs` block. Each entry hands a list of
+Tailscale node capabilities to every node matching `target`. The accepted
+target forms are the same as `acls.src` and `grants.src`: users, groups,
+tags, hosts, prefixes, `autogroup:member`, `autogroup:tagged`, and `*`.
+
+```jsonc
+{
+  "randomizeClientPort": true,
+  "nodeAttrs": [
+    { "target": ["autogroup:tagged"], "attr": ["disable-captive-portal-detection"] },
+    { "target": ["alice@example.com"], "attr": ["nextdns:abc123"] },
+  ],
+}
+```
+
+Frequently requested capabilities this unlocks include `magicdns-aaaa`,
+`disable-relay-server`, `disable-captive-portal-detection`,
+`nextdns:<profile>` / `nextdns:no-device-info`, `randomize-client-port`,
+and the Taildrive `drive:share` / `drive:access` pair. The set is not
+limited to these, any string-only cap an operator places in policy
+reaches clients unchanged.
+
+`randomizeClientPort` also lands as a top-level policy field that toggles
+the default for every node, replacing the old server-config knob.
+
+A new `auto_update.enabled` config option controls the tailnet-wide
+default for client auto-update. When true, every node's CapMap carries
+`default-auto-update: [true]` so fresh clients pick up the default
+unless they make a local opt-in / opt-out choice.
+
+Policies that use the `funnel` cap, `ipPool` blocks, or
+`autogroup:admin` / `autogroup:owner` targets are rejected at load —
+those features depend on machinery headscale does not yet ship.
+
+[#3251](https://github.com/juanfont/headscale/pull/3251)
+
+### Taildrive
+
+Taildrive ([file-sync between
+nodes](https://tailscale.com/docs/features/taildrive)) is now
+configurable through policy. Grant `drive:share` to the node that
+hosts files and `drive:access` to nodes that read or write them; pair
+with a `tailscale.com/cap/drive` grant to set the per-share access
+mode:
+
+```jsonc
+{
+  "nodeAttrs": [
+    { "target": ["tag:fileserver"], "attr": ["drive:share"] },
+    { "target": ["autogroup:member"], "attr": ["drive:access"] },
+  ],
+  "grants": [
+    {
+      "src": ["autogroup:member"],
+      "dst": ["tag:fileserver"],
+      "app": {
+        "tailscale.com/cap/drive": [{ "shares": ["*"], "access": "rw" }],
+      },
+    },
+  ],
+}
+```
+
+A wildcard `nodeAttrs` (`"target": ["*"]`) hands the caps to every
+node when fine-grained control is not needed.
+
+### Hostname sanitisation
+
+Hostnames are now santised using Tailscales `magicdns` sanitisation rules, matching Tailscale SaaS behavior. This means that hostnames with non-ASCII characters, special characters, or reserved DNS label characters are now transformed into valid DNS labels for MagicDNS. This improves our previously too strict sanitisation that rejected hostnames based on our guesswork and not based on the Tailscale upstream behaviour.
+
+Examples that previously regressed and now work:
+
+| Input                | Raw (Hostname)       | DNS label (GivenName) |
+| -------------------- | -------------------- | --------------------- |
+| `Joe's Mac mini`     | `Joe's Mac mini`     | `joes-mac-mini`       |
+| `Yuri's MacBook Pro` | `Yuri's MacBook Pro` | `yuris-macbook-pro`   |
+| `Test@Host`          | `Test@Host`          | `test-host`           |
+| `mail.server`        | `mail.server`        | `mail-server`         |
+| `My-PC!`             | `My-PC!`             | `my-pc`               |
+| `我的电脑`           | `我的电脑`           | `node`                |
+
+[#3202](https://github.com/juanfont/headscale/pull/3202)
+
+### HA subnet router health probing
+
+Headscale now actively probes HA subnet routers to detect nodes that are connected but not
+forwarding traffic. The control plane periodically pings HA subnet routers via the Noise
+control channel and fails over to a healthy standby if the primary stops responding. This is
+enabled by default (`node.routes.ha.probe_interval: 10s`, `probe_timeout: 5s`) and only
+active when HA routes exist (2+ nodes advertising the same prefix). Set `probe_interval` to
+`0` to disable. This complements the existing disconnect-based failover, catching "zombie
+connected" routers that maintain their control session but cannot route packets.
+[#3194](https://github.com/juanfont/headscale/pull/3194)
+
+### BREAKING
+
+#### Hostname handling
+
+- The `GivenName` collision policy changed from an 8-char random hash suffix (`laptop-abc12xyz`) to a monotonic numeric suffix (`laptop`, `laptop-1`, `laptop-2`, …), matching Tailscale SaaS. Empty / all-non-ASCII hostnames now fall back to the literal `node` instead of `invalid-<rand>`. MagicDNS names change on upgrade for any node whose previous label was a random-suffix form; the raw `Hostname` column is unchanged. [#3202](https://github.com/juanfont/headscale/pull/3202)
+
+#### ACL Policy
+
+- Wildcard (`*`) in ACL sources and destinations now resolves to Tailscale's CGNAT range (`100.64.0.0/10`) and ULA range (`fd7a:115c:a1e0::/48`) instead of all IPs (`0.0.0.0/0` and `::/0`) [#3036](https://github.com/juanfont/headscale/pull/3036)
+  - This better matches Tailscale's security model where `*` means "any node in the tailnet" rather than "any IP address"
+  - Policies that need to match all IP addresses including non-Tailscale IPs should use `autogroup:danger-all` as a source, or explicit CIDR ranges as destinations [#2180](https://github.com/juanfont/headscale/pull/2180)
+  - `autogroup:danger-all` can only be used as a source; it cannot be used as a destination
+  - **Note**: Users with non-standard IP ranges configured in `prefixes.ipv4` or `prefixes.ipv6` (which is unsupported and produces a warning) will need to explicitly specify their CIDR ranges in ACL rules instead of using `*`
+- Validate `autogroup:self` source restrictions matching Tailscale behavior - tags, hosts, and IPs are rejected as sources for `autogroup:self` destinations [#3036](https://github.com/juanfont/headscale/pull/3036)
+  - Policies using tags, hosts, or IP addresses as sources for `autogroup:self` destinations will now fail validation
+- The `proto:icmp` protocol name now only includes ICMPv4 (protocol 1), matching Tailscale behavior [#3036](https://github.com/juanfont/headscale/pull/3036)
+  - Previously, `proto:icmp` included both ICMPv4 and ICMPv6
+  - Use `proto:ipv6-icmp` or protocol number `58` explicitly for ICMPv6
+
+#### Upgrade Path
+
+- Headscale now enforces a strict version upgrade path [#3083](https://github.com/juanfont/headscale/pull/3083)
+  - Skipping minor versions (e.g. 0.27 → 0.29) is blocked; upgrade one minor version at a time
+  - Downgrading to a previous minor version is blocked
+  - Patch version changes within the same minor are always allowed
+
+#### Configuration
+
+- The `randomize_client_port` server-config key was removed; the
+  toggle now lives in the policy file as a top-level
+  `randomizeClientPort` field, matching the Tailscale-hosted schema. [#3251](https://github.com/juanfont/headscale/pull/3251)
+  Headscale refuses to start when the old key is set. Move it to the
+  policy file referenced by `policy.path`:
+
+  ```jsonc
+  {
+    "randomizeClientPort": true,
+  }
+  ```
+
+  If you do not have a policy file yet, create one with that minimal
+  content and point `policy.path` at it. The default carries over —
+  empty / absent policy means `randomizeClientPort: false`, matching
+  the previous behaviour for operators who never set the key. Per-node
+  opt-in via `nodeAttrs` is also supported and stacks on top of the
+  global default.
+
+#### CLI
+
+- `headscale nodes register` is deprecated in favour of `headscale auth register --auth-id <id> --user <user>` [#1850](https://github.com/juanfont/headscale/pull/1850)
+  - The old command continues to work but will be removed in a future release
+
+### Changes
+
+#### ACL Policy
+
+- Fix subnet-to-subnet peer visibility — subnet routers now correctly become peers when ACL rules reference only subnet CIDRs as sources, without requiring node IP rules [#3175](https://github.com/juanfont/headscale/pull/3175)
+- Fix filter rule reduction to use only approved subnet routes instead of all advertised routes, matching Tailscale SaaS behavior [#3175](https://github.com/juanfont/headscale/pull/3175)
+- Add ICMP and IPv6-ICMP protocols to default filter rules when no protocol is specified [#3036](https://github.com/juanfont/headscale/pull/3036)
+- Fix autogroup:self handling for tagged nodes - tagged nodes no longer incorrectly receive autogroup:self filter rules [#3036](https://github.com/juanfont/headscale/pull/3036)
+- Use CIDR format for autogroup:self destination IPs matching Tailscale behavior [#3036](https://github.com/juanfont/headscale/pull/3036)
+- Merge filter rules with identical SrcIPs and IPProto matching Tailscale behavior - multiple ACL rules with the same source now produce a single FilterRule with combined DstPorts [#3036](https://github.com/juanfont/headscale/pull/3036)
+- Fix exit nodes incorrectly receiving filter rules for destinations that only overlap via exit routes [#3169](https://github.com/juanfont/headscale/issues/3169) [#3175](https://github.com/juanfont/headscale/pull/3175)
+- Fix address-based aliases (hosts, raw IPs) incorrectly expanding to include the matching node's other address family [#2180](https://github.com/juanfont/headscale/pull/2180)
+- Fix identity-based aliases (tags, users, groups) resolving to IPv4 only; they now include both IPv4 and IPv6 matching Tailscale behavior [#2180](https://github.com/juanfont/headscale/pull/2180)
+- Fix wildcard (`*`) source in ACLs now using actually-approved subnet routes instead of autoApprover policy prefixes [#2180](https://github.com/juanfont/headscale/pull/2180)
+- Fix non-wildcard source IPs being dropped when combined with wildcard `*` in the same ACL rule [#2180](https://github.com/juanfont/headscale/pull/2180)
+- Fix exit node approval not triggering filter rule recalculation for peers [#2180](https://github.com/juanfont/headscale/pull/2180)
+- Policy validation error messages now include field context (e.g., `src=`, `dst=`) and are more descriptive [#2180](https://github.com/juanfont/headscale/pull/2180)
+- Reject policies whose `user@` tokens match multiple DB users; rename the duplicate via `headscale users rename` to load [#3160](https://github.com/juanfont/headscale/issues/3160)
+- Evaluate the policy `tests` block on user-initiated writes across both `acls` and `grants`; reject policies whose tests fail (beta) [#1803](https://github.com/juanfont/headscale/issues/1803)
+
+#### Grants
+
+- Add support for policy grants with `ip`, `app`, and `via` fields [#2180](https://github.com/juanfont/headscale/pull/2180)
+- Add `autogroup:danger-all` as a source-only autogroup resolving to all IP addresses [#2180](https://github.com/juanfont/headscale/pull/2180)
+- Add capability grants for Taildrive (`cap/drive`) and peer relay (`cap/relay`) with automatic companion capabilities [#2180](https://github.com/juanfont/headscale/pull/2180)
+- Add per-viewer via route steering — grants with `via` tags control which subnet router or exit node handles traffic for each group of viewers [#2180](https://github.com/juanfont/headscale/pull/2180)
+- Enable Taildrive node attributes on all nodes; actual access is controlled by `cap/drive` grants [#2180](https://github.com/juanfont/headscale/pull/2180)
+
+#### SSH Policy
+
+- Add support for `localpart:*@<domain>` in SSH rule `users` field, mapping each matching user's email local-part as their OS username [#3091](https://github.com/juanfont/headscale/pull/3091)
+- Add SSH `check` action support with OIDC and CLI-based approval flows [#1850](https://github.com/juanfont/headscale/pull/1850)
+
+#### CLI
+
+- Add `headscale auth register`, `headscale auth approve`, and `headscale auth reject` CLI commands [#1850](https://github.com/juanfont/headscale/pull/1850)
+- Deprecate `headscale nodes register --key` in favour of `headscale auth register --auth-id` [#1850](https://github.com/juanfont/headscale/pull/1850)
+- `headscale policy check --bypass-grpc-and-access-database-directly` validates `user@` tokens against the live user database [#3160](https://github.com/juanfont/headscale/issues/3160)
+- Remove deprecated `--namespace` flag from `nodes list`, `nodes register`, and `debug create-node` commands (use `--user` instead) [#3093](https://github.com/juanfont/headscale/pull/3093)
+- Remove deprecated `namespace`/`ns` command aliases for `users` and `machine`/`machines` aliases for `nodes` [#3093](https://github.com/juanfont/headscale/pull/3093)
+- Fix `DestroyUser` deleting all pre-auth keys in the database instead of only the target user's keys [#3155](https://github.com/juanfont/headscale/pull/3155)
+- `headscale policy check` evaluates the `tests` block when invoked with `--bypass-grpc-and-access-database-directly`; without the flag it warns instead of running the tests against empty data [#1803](https://github.com/juanfont/headscale/issues/1803)
+
+#### API
+
+- Add `auth` related routes. The `auth/register` endpoint now expects data as JSON [#1850](https://github.com/juanfont/headscale/pull/1850)
+- Remove gRPC reflection from the remote (TCP) server [#3180](https://github.com/juanfont/headscale/pull/3180)
+
+#### OIDC
+
+- Add a confirmation page before completing node registration, showing the device hostname and machine key fingerprint [#3180](https://github.com/juanfont/headscale/pull/3180)
+- Generalise auth templates into reusable `AuthSuccess` and `AuthWeb` components [#1850](https://github.com/juanfont/headscale/pull/1850)
+- Unify auth pipeline with `AuthVerdict` type, supporting registration, reauthentication, and SSH checks [#1850](https://github.com/juanfont/headscale/pull/1850)
+
+#### Configuration
+
+- Add `node.expiry` configuration option to set a default node key expiry for nodes registered via auth key [#3122](https://github.com/juanfont/headscale/pull/3122)
+  - Tagged nodes (registered with tagged pre-auth keys) are exempt from default expiry
+  - `oidc.expiry` has been removed; use `node.expiry` instead (applies to all registration methods including OIDC)
+  - `ephemeral_node_inactivity_timeout` is deprecated in favour of `node.ephemeral.inactivity_timeout`
+- Add `trusted_proxies` to gate `True-Client-IP` / `X-Real-IP` / `X-Forwarded-For` (previously honoured from any client) [#3268](https://github.com/juanfont/headscale/pull/3268)
+
+#### Debug
+
+- Add node connectivity ping page for verifying control-plane reachability [#3183](https://github.com/juanfont/headscale/pull/3183)
+- Omit secret fields (`Pass`, `ClientSecret`, `APIKey`) from `/debug/config` JSON output [#3180](https://github.com/juanfont/headscale/pull/3180)
+- Route `statsviz` through `tsweb.Protected` [#3180](https://github.com/juanfont/headscale/pull/3180)
+
+#### Other
+
+- Remove old migrations for the debian package [#3185](https://github.com/juanfont/headscale/pull/3185)
+- Install `config-example.yaml` as example for the debian package [#3186](https://github.com/juanfont/headscale/pull/3186)
+- Fix user-owned re-registration with zero client expiry and no default storing `0001-01-01 00:00:00` in the database instead of `NULL` [#3199](https://github.com/juanfont/headscale/pull/3199)
+- Fix `tailscaled` restart on a node with no expiry resetting `NULL` to `0001-01-01 00:00:00` in the database, affecting both tagged and untagged nodes [#3197](https://github.com/juanfont/headscale/pull/3197)
+- Backfill `nodes.expiry` rows persisted by older versions as `0001-01-01 00:00:00` to `NULL`, so nodes upgraded from <0.28 stop reporting as expired [#3284](https://github.com/juanfont/headscale/issues/3284)
+- Update reverse proxy documentation for `trusted_proxies` configuration option [#3292](https://github.com/juanfont/headscale/pull/3292)
 
 ## 0.28.0 (2026-02-04)
 
@@ -11,7 +371,7 @@
 Tags are now implemented following the Tailscale model where tags and user ownership are mutually exclusive. Devices can be either
 user-owned (authenticated via web/OIDC) or tagged (authenticated via tagged PreAuthKeys). Tagged devices receive their identity from
 tags rather than users, making them suitable for servers and infrastructure. Applying a tag to a device removes user-based
-ownership. See the [Tailscale tags documentation](https://tailscale.com/kb/1068/tags) for details on how tags work.
+ownership. See the [Tailscale tags documentation](https://tailscale.com/docs/features/tags) for details on how tags work.
 
 User-owned nodes can now request tags during registration using `--advertise-tags`. Tags are validated against the `tagOwners` policy
 and applied at registration time. Tags can be managed via the CLI or API after registration. Tagged nodes can return to user-owned
@@ -110,7 +470,7 @@ sequentially through each stable release, selecting the latest patch version ava
 
 - **SSH Policy**: SSH source/destination validation now enforces Tailscale's security model [#3010](https://github.com/juanfont/headscale/issues/3010)
 
-  Per [Tailscale SSH documentation](https://tailscale.com/kb/1193/tailscale-ssh), the following rules are now enforced:
+  Per [Tailscale SSH documentation](https://tailscale.com/docs/features/tailscale-ssh), the following rules are now enforced:
   1. **Tags cannot SSH to user-owned devices**: SSH rules with `tag:*` or `autogroup:tagged` as source cannot have username destinations (e.g., `alice@`) or `autogroup:member`/`autogroup:self` as destination
   2. **Username destinations require same-user source**: If destination is a specific username (e.g., `alice@`), the source must be that exact same user only. Use `autogroup:self` for same-user SSH access instead
 
@@ -239,8 +599,8 @@ DERPMap updates when upstream is changed.
 
 This release adds support for the three missing autogroups: `self`
 (experimental), `member`, and `tagged`. Please refer to the
-[documentation](https://tailscale.com/kb/1018/autogroups/) for a detailed
-explanation.
+[documentation](https://tailscale.com/docs/reference/targets-and-selectors#autogroups)
+for a detailed explanation.
 
 `autogroup:self` is marked as experimental and should be used with caution, but
 we need help testing it. Experimental here means two things; first, generating
@@ -403,7 +763,7 @@ The SSH policy has been reworked to be more consistent with the rest of the
 policy. In addition, several inconsistencies between our implementation and
 Tailscale's upstream has been closed and this might be a breaking change for
 some users. Please refer to the
-[upstream documentation](https://tailscale.com/kb/1337/acl-syntax#tailscale-ssh)
+[upstream documentation](https://tailscale.com/docs/reference/syntax/policy-file#tailscale-ssh)
 for more information on which types are allowed in `src`, `dst` and `users`.
 
 There is one large inconsistency left, we allow `*` as a destination as we
@@ -917,7 +1277,7 @@ part of adopting [#1460](https://github.com/juanfont/headscale/pull/1460).
 
 - Added support for Tailscale TS2021 protocol [#738](https://github.com/juanfont/headscale/pull/738)
 - Add experimental support for
-  [SSH ACL](https://tailscale.com/kb/1018/acls/#tailscale-ssh) (see docs for
+  [SSH ACL](https://tailscale.com/docs/reference/syntax/policy-file#tailscale-ssh) (see docs for
   limitations) [#847](https://github.com/juanfont/headscale/pull/847)
   - Please note that this support should be considered _partially_ implemented
   - SSH ACLs status:
@@ -994,7 +1354,7 @@ part of adopting [#1460](https://github.com/juanfont/headscale/pull/1460).
 ### BREAKING
 
 - Old ACL syntax is no longer supported ("users" & "ports" -> "src" & "dst").
-  Please check [the new syntax](https://tailscale.com/kb/1018/acls/).
+  Please check [the new syntax](https://tailscale.com/docs/features/access-control/acls).
 
 ### Changes
 
@@ -1024,7 +1384,7 @@ part of adopting [#1460](https://github.com/juanfont/headscale/pull/1460).
 - Add -c option to specify config file from command line [#285](https://github.com/juanfont/headscale/issues/285)
   [#612](https://github.com/juanfont/headscale/pull/601)
 - Add configuration option to allow Tailscale clients to use a random WireGuard
-  port. [kb/1181/firewalls](https://tailscale.com/kb/1181/firewalls)
+  port. [Tailscale docs](https://tailscale.com/docs/reference/syntax/policy-file#randomizeclientport)
   [#624](https://github.com/juanfont/headscale/pull/624)
 - Improve obtuse UX regarding missing configuration
   (`ephemeral_node_inactivity_timeout` not set)

Dockerfile.derper

@@ -1,6 +1,6 @@
 # For testing purposes only
 
-FROM golang:alpine AS build-env
+FROM golang:1.26.4-alpine AS build-env
 
 WORKDIR /go/src
 
@@ -12,7 +12,7 @@ WORKDIR /go/src/tailscale
 ARG TARGETARCH
 RUN GOARCH=$TARGETARCH go install -v ./cmd/derper
 
-FROM alpine:3.22
+FROM alpine:3.23
 RUN apk add --no-cache ca-certificates iptables iproute2 ip6tables curl
 
 COPY --from=build-env /go/bin/* /usr/local/bin/

Dockerfile.integration

@@ -2,7 +2,7 @@
 # and are in no way endorsed by Headscale's maintainers as an
 # official nor supported release or distribution.
 
-FROM docker.io/golang:1.25-trixie AS builder
+FROM docker.io/golang:1.26.4-trixie AS builder
 ARG VERSION=dev
 ENV GOPATH /go
 WORKDIR /go/src/headscale

Dockerfile.tailscale-HEAD

@@ -4,7 +4,7 @@
 # This Dockerfile is more or less lifted from tailscale/tailscale
 # to ensure a similar build process when testing the HEAD of tailscale.
 
-FROM golang:1.25-alpine AS build-env
+FROM golang:1.26.4-alpine AS build-env
 
 WORKDIR /go/src
 
@@ -36,7 +36,7 @@ RUN GOARCH=$TARGETARCH go install -tags="${BUILD_TAGS}" -ldflags="\
       -X tailscale.com/version.gitCommitStamp=$VERSION_GIT_HASH" \
       -v ./cmd/tailscale ./cmd/tailscaled ./cmd/containerboot
 
-FROM alpine:3.22
+FROM alpine:3.23
 # Upstream: ca-certificates ip6tables iptables iproute2
 # Tests: curl python3 (traceroute via BusyBox)
 RUN apk add --no-cache ca-certificates curl ip6tables iptables iproute2 python3

Dockerfile.tailscale-rs

@@ -0,0 +1,26 @@
+FROM rust:1.95-trixie AS builder
+
+ARG TAILSCALE_RS_REPO=https://github.com/tailscale/tailscale-rs.git
+ARG TAILSCALE_RS_REF=main
+
+WORKDIR /app
+RUN git clone --depth 1 --branch "$TAILSCALE_RS_REF" "$TAILSCALE_RS_REPO" .
+
+# Re-export ts_control's insecure-keyfetch feature through the tailscale
+# crate so the axum example can fetch the headscale control key over
+# plain HTTP. The integration harness serves the control plane without
+# TLS, and upstream only allows plain-HTTP key fetches when this Cargo
+# feature is compiled in.
+RUN sed -i '/^axum = \["dep:axum"\]/a insecure-keyfetch = ["ts_control/insecure-keyfetch"]' Cargo.toml
+
+RUN cargo build --release --features axum,insecure-keyfetch --example axum
+
+FROM debian:trixie-slim
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    ca-certificates \
+    iproute2 \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /app/target/release/examples/axum /usr/local/bin/axum

Makefile

@@ -20,8 +20,7 @@ endef
 
 # Source file collections using shell find for better performance
 GO_SOURCES := $(shell find . -name '*.go' -not -path './gen/*' -not -path './vendor/*')
-PROTO_SOURCES := $(shell find . -name '*.proto' -not -path './gen/*' -not -path './vendor/*')
-DOC_SOURCES := $(shell find . \( -name '*.md' -o -name '*.yaml' -o -name '*.yml' -o -name '*.ts' -o -name '*.js' -o -name '*.html' -o -name '*.css' -o -name '*.scss' -o -name '*.sass' \) -not -path './gen/*' -not -path './vendor/*' -not -path './node_modules/*')
+PRETTIER_SOURCES := $(shell find . \( -name '*.md' -o -name '*.yaml' -o -name '*.yml' -o -name '*.ts' -o -name '*.js' -o -name '*.html' -o -name '*.css' -o -name '*.scss' -o -name '*.sass' \) -not -path './gen/*' -not -path './vendor/*' -not -path './node_modules/*')
 
 # Default target
 .PHONY: all
@@ -33,9 +32,8 @@ check-deps:
 	$(call check_tool,go)
 	$(call check_tool,golangci-lint)
 	$(call check_tool,gofumpt)
+	$(call check_tool,mdformat)
 	$(call check_tool,prettier)
-	$(call check_tool,clang-format)
-	$(call check_tool,buf)
 
 # Build targets
 .PHONY: build
@@ -52,7 +50,7 @@ test: check-deps $(GO_SOURCES) go.mod go.sum
 
 # Formatting targets
 .PHONY: fmt
-fmt: fmt-go fmt-prettier fmt-proto
+fmt: fmt-go fmt-mdformat fmt-prettier
 
 .PHONY: fmt-go
 fmt-go: check-deps $(GO_SOURCES)
@@ -60,45 +58,69 @@ fmt-go: check-deps $(GO_SOURCES)
 	gofumpt -l -w .
 	golangci-lint run --fix
 
-.PHONY: fmt-prettier
-fmt-prettier: check-deps $(DOC_SOURCES)
-	@echo "Formatting documentation and config files..."
-	prettier --write '**/*.{ts,js,md,yaml,yml,sass,css,scss,html}'
+.PHONY: fmt-mdformat
+fmt-mdformat: check-deps
+	@echo "Formatting documentation..."
+	mdformat docs/
 
-.PHONY: fmt-proto
-fmt-proto: check-deps $(PROTO_SOURCES)
-	@echo "Formatting Protocol Buffer files..."
-	clang-format -i $(PROTO_SOURCES)
+.PHONY: fmt-prettier
+fmt-prettier: check-deps $(PRETTIER_SOURCES)
+	@echo "Formatting markup and config files..."
+	prettier --write '**/*.{ts,js,md,yaml,yml,sass,css,scss,html}'
 
 # Linting targets
 .PHONY: lint
-lint: lint-go lint-proto
+lint: lint-go
 
 .PHONY: lint-go
 lint-go: check-deps $(GO_SOURCES) go.mod go.sum
 	@echo "Linting Go code..."
 	golangci-lint run --timeout 10m
 
-.PHONY: lint-proto
-lint-proto: check-deps $(PROTO_SOURCES)
-	@echo "Linting Protocol Buffer files..."
-	cd proto/ && buf lint
-
 # Code generation
 .PHONY: generate
 generate: check-deps
 	@echo "Generating code..."
 	go generate ./...
+	$(MAKE) client
+
+# Emit the OpenAPI spec on demand. The server serves it live at /openapi.yaml;
+# this is for external consumers or inspection and is not committed.
+.PHONY: openapi
+openapi:
+	@echo "Emitting OpenAPI spec from code..."
+	go run ./cmd/gen-openapi
+
+# Generate the strongly-typed Go HTTP clients (v1 and v2). The served specs are
+# OpenAPI 3.1, but oapi-codegen v2 does not yet read 3.1, so each client is
+# generated from a transient 3.0.3 downgrade of its document. Pinned so the
+# committed clients are reproducible.
+.PHONY: client
+client:
+	@echo "Generating API clients..."
+	@tmp=$$(mktemp -t headscale-openapi-3.0.XXXXXX.yaml); \
+	go run ./cmd/gen-openapi -downgrade "$$tmp" && \
+	go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@v2.7.1 \
+		-generate types,client -package clientv1 -o gen/client/v1/client.gen.go "$$tmp" && \
+	go run ./cmd/gen-openapi -api v2 -downgrade "$$tmp" && \
+	go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@v2.7.1 \
+		-generate types,client -package clientv2 -o gen/client/v2/client.gen.go "$$tmp"; \
+	status=$$?; rm -f "$$tmp"; exit $$status
 
 # Clean targets
 .PHONY: clean
 clean:
-	rm -rf headscale gen
+	rm -rf headscale gen/client
 
 # Development workflow
 .PHONY: dev
 dev: fmt lint test build
 
+# Start a local headscale dev server (use mts to add nodes)
+.PHONY: dev-server
+dev-server:
+	go run ./cmd/dev
+
 # Help target
 .PHONY: help
 help:
@@ -108,18 +130,17 @@ help:
 	@echo "  all          - Run lint, test, and build (default)"
 	@echo "  build        - Build headscale binary"
 	@echo "  test         - Run Go tests"
-	@echo "  fmt          - Format all code (Go, docs, proto)"
-	@echo "  lint         - Lint all code (Go, proto)"
-	@echo "  generate     - Generate code from Protocol Buffers"
+	@echo "  fmt          - Format all code (Go, docs, markup)"
+	@echo "  lint         - Lint all code (Go)"
+	@echo "  generate     - Generate code (go generate + client)"
 	@echo "  dev          - Full development workflow (fmt + lint + test + build)"
 	@echo "  clean        - Clean build artifacts"
 	@echo ""
 	@echo "Specific targets:"
 	@echo "  fmt-go       - Format Go code only"
-	@echo "  fmt-prettier - Format documentation only"
-	@echo "  fmt-proto    - Format Protocol Buffer files only"
+	@echo "  fmt-mdformat - Format documentation only"
+	@echo "  fmt-prettier - Format markup and config files only"
 	@echo "  lint-go      - Lint Go code only"
-	@echo "  lint-proto   - Lint Protocol Buffer files only"
 	@echo ""
 	@echo "Dependencies:"
 	@echo "  check-deps   - Verify required tools are available"

README.md

@@ -30,8 +30,8 @@ nodes in the Tailscale network. It assigns the IP addresses of the clients,
 creates the boundaries between each user, enables sharing machines between users,
 and exposes the advertised routes of your nodes.
 
-A [Tailscale network (tailnet)](https://tailscale.com/kb/1136/tailnet/) is private
-network which Tailscale assigns to a user in terms of private users or an
+A [Tailscale network (tailnet)](https://tailscale.com/docs/concepts/tailnet) is
+private network which Tailscale assigns to a user in terms of private users or an
 organisation.
 
 ## Design goal
@@ -65,8 +65,16 @@ Please have a look at the [`documentation`](https://headscale.net/stable/).
 
 For NixOS users, a module is available in [`nix/`](./nix/).
 
+## Builds from `main`
+
+Development builds from the `main` branch are available as container images and
+binaries. See the [development builds](https://headscale.net/stable/setup/install/main/)
+documentation for details.
+
 ## Talks
 
+- Fosdem 2026 (video): [Headscale & Tailscale: The complementary open source clone](https://fosdem.org/2026/schedule/event/KYQ3LL-headscale-the-complementary-open-source-clone/)
+  - presented by Kristoffer Dalby
 - Fosdem 2023 (video): [Headscale: How we are using integration testing to reimplement Tailscale](https://fosdem.org/2023/schedule/event/goheadscale/)
   - presented by Juan Font Alonso and Kristoffer Dalby
 
@@ -105,6 +113,8 @@ run `make lint` and `make fmt` before committing any code.
 The **Proto** code is linted with [`buf`](https://docs.buf.build/lint/overview) and
 formatted with [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html).
 
+The **docs** are formatted with [`mdformat`](https://mdformat.readthedocs.io).
+
 The **rest** (Markdown, YAML, etc) is formatted with [`prettier`](https://prettier.io).
 
 Check out the `.golangci.yaml` and `Makefile` to see the specific configuration.

buf.gen.yaml

@@ -1,21 +0,0 @@
-version: v1
-plugins:
-  - name: go
-    out: gen/go
-    opt:
-      - paths=source_relative
-  - name: go-grpc
-    out: gen/go
-    opt:
-      - paths=source_relative
-  - name: grpc-gateway
-    out: gen/go
-    opt:
-      - paths=source_relative
-      - generate_unbound_methods=true
-  # - name: gorm
-  #   out: gen/go
-  #   opt:
-  #     - paths=source_relative,enums=string,gateway=true
-  - name: openapiv2
-    out: gen/openapiv2

cmd/dev/README.md

@@ -0,0 +1,95 @@
+# 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
+
+```bash
+# 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
+
+1. Builds the headscale binary into a temp directory
+2. Writes a minimal dev config (SQLite, public DERP, debug logging)
+3. Starts `headscale serve` as a subprocess
+4. Creates a "dev" user and a reusable 24h pre-auth key via the CLI
+5. Prints a banner with server URL, auth key, and usage instructions
+6. 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:
+
+```bash
+/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:
+
+```bash
+go tool mts server rm <name>
+```

cmd/dev/main.go

@@ -0,0 +1,312 @@
+// cmd/dev starts a local headscale development server with a pre-created
+// user and pre-auth key, ready for connecting tailscale nodes via mts.
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"flag"
+	"fmt"
+	"log"
+	"net/http"
+	"os"
+	"os/exec"
+	"os/signal"
+	"path/filepath"
+	"strconv"
+	"syscall"
+	"time"
+)
+
+var (
+	port = flag.Int("port", 8080, "headscale listen port")
+	keep = flag.Bool("keep", false, "keep state directory on exit")
+)
+
+var errHealthTimeout = errors.New("health check timed out")
+
+var errEmptyAuthKey = errors.New("empty auth key in response")
+
+// maxDevPort is the highest --port value that keeps the derived metrics
+// port (port+1010) inside the valid 1..65535 TCP range.
+const maxDevPort = 64525
+
+const devConfig = `---
+server_url: http://127.0.0.1:%d
+listen_addr: 127.0.0.1:%d
+metrics_listen_addr: 127.0.0.1:%d
+
+noise:
+  private_key_path: %s/noise_private.key
+
+prefixes:
+  v4: 100.64.0.0/10
+  v6: fd7a:115c:a1e0::/48
+  allocation: sequential
+
+database:
+  type: sqlite
+  sqlite:
+    path: %s/db.sqlite
+    write_ahead_log: true
+
+derp:
+  server:
+    enabled: false
+  urls:
+    - https://controlplane.tailscale.com/derpmap/default
+  auto_update_enabled: false
+
+dns:
+  magic_dns: true
+  base_domain: headscale.dev
+  override_local_dns: false
+
+log:
+  level: debug
+  format: text
+
+policy:
+  mode: database
+
+unix_socket: %s/headscale.sock
+unix_socket_permission: "0770"
+`
+
+func main() {
+	flag.Parse()
+	log.SetFlags(0)
+
+	if *port < 1 || *port > maxDevPort {
+		log.Fatalf(
+			"--port must be in 1..%d (higher values overflow the derived metrics port); got %d",
+			maxDevPort, *port,
+		)
+	}
+
+	http.DefaultClient.Timeout = 2 * time.Second
+	http.DefaultClient.CheckRedirect = func(*http.Request, []*http.Request) error {
+		return http.ErrUseLastResponse
+	}
+
+	err := run()
+	if err != nil {
+		log.Fatal(err)
+	}
+}
+
+func run() error {
+	metricsPort := *port + 1010 // default 9090
+
+	tmpDir, err := os.MkdirTemp("", "headscale-dev-")
+	if err != nil {
+		return fmt.Errorf("creating temp dir: %w", err)
+	}
+
+	if !*keep {
+		defer os.RemoveAll(tmpDir)
+	}
+
+	// Write config.
+	configPath := filepath.Join(tmpDir, "config.yaml")
+	configContent := fmt.Sprintf(
+		devConfig,
+		*port, *port, metricsPort,
+		tmpDir, tmpDir, tmpDir,
+	)
+
+	err = os.WriteFile(configPath, []byte(configContent), 0o600)
+	if err != nil {
+		return fmt.Errorf("writing config: %w", err)
+	}
+
+	// Build headscale.
+	fmt.Println("Building headscale...")
+
+	hsBin := filepath.Join(tmpDir, "headscale")
+
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
+
+	build := exec.CommandContext(ctx, "go", "build", "-o", hsBin, "./cmd/headscale")
+	build.Stdout = os.Stdout
+	build.Stderr = os.Stderr
+
+	err = build.Run()
+	if err != nil {
+		return fmt.Errorf("building headscale: %w", err)
+	}
+
+	// Start headscale serve.
+	fmt.Println("Starting headscale server...")
+
+	serve := exec.CommandContext(ctx, hsBin, "serve", "-c", configPath)
+	serve.Stdout = os.Stdout
+	serve.Stderr = os.Stderr
+
+	err = serve.Start()
+	if err != nil {
+		return fmt.Errorf("starting headscale: %w", err)
+	}
+
+	// Wait for server to be ready.
+	healthURL := fmt.Sprintf("http://127.0.0.1:%d/health", *port)
+
+	err = waitForHealth(ctx, healthURL, 30*time.Second)
+	if err != nil {
+		return fmt.Errorf("waiting for headscale: %w", err)
+	}
+
+	// Create user.
+	fmt.Println("Creating user and pre-auth key...")
+
+	userJSON, err := runHS(ctx, hsBin, configPath, "users", "create", "dev", "-o", "json")
+	if err != nil {
+		return fmt.Errorf("creating user: %w", err)
+	}
+
+	userID, err := extractUserID(userJSON)
+	if err != nil {
+		return fmt.Errorf("parsing user: %w", err)
+	}
+
+	// Create pre-auth key.
+	keyJSON, err := runHS(
+		ctx, hsBin, configPath,
+		"preauthkeys", "create",
+		"-u", strconv.FormatUint(userID, 10),
+		"--reusable",
+		"-e", "24h",
+		"-o", "json",
+	)
+	if err != nil {
+		return fmt.Errorf("creating pre-auth key: %w", err)
+	}
+
+	authKey, err := extractAuthKey(keyJSON)
+	if err != nil {
+		return fmt.Errorf("parsing pre-auth key: %w", err)
+	}
+
+	// Print banner.
+	fmt.Printf(
+		`
+=== Headscale Dev Environment ===
+  Server:  http://127.0.0.1:%d
+  Metrics: http://127.0.0.1:%d
+  Debug:   http://127.0.0.1:%d/debug/ping
+  Config:  %s
+  State:   %s
+
+Pre-auth key: %s
+
+Connect nodes with mts:
+  go tool mts server run                  # start mts (once, another terminal)
+  go tool mts server add node1            # create a node
+  go tool mts node1 up --login-server=http://127.0.0.1:%d --authkey=%s
+  go tool mts node1 status                # check connection
+
+Manage headscale:
+  %s -c %s nodes list
+  %s -c %s users list
+
+Press Ctrl+C to stop.
+`,
+		*port, metricsPort, metricsPort,
+		configPath, tmpDir,
+		authKey,
+		*port, authKey,
+		hsBin, configPath,
+		hsBin, configPath,
+	)
+
+	// Wait for headscale to exit.
+	err = serve.Wait()
+	if err != nil {
+		// Context cancellation is expected on Ctrl+C.
+		if ctx.Err() != nil {
+			fmt.Println("\nShutting down...")
+
+			return nil
+		}
+
+		return fmt.Errorf("headscale exited: %w", err)
+	}
+
+	return nil
+}
+
+// waitForHealth polls the health endpoint until it returns 200 or the
+// timeout expires.
+func waitForHealth(ctx context.Context, url string, timeout time.Duration) error {
+	deadline := time.Now().Add(timeout)
+
+	for time.Now().Before(deadline) {
+		if ctx.Err() != nil {
+			return ctx.Err()
+		}
+
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+		if err != nil {
+			return fmt.Errorf("creating request: %w", err)
+		}
+
+		resp, err := http.DefaultClient.Do(req)
+		if err == nil {
+			resp.Body.Close()
+
+			if resp.StatusCode == http.StatusOK {
+				return nil
+			}
+		}
+
+		// Busy-wait is acceptable for a dev tool polling a local server.
+		time.Sleep(200 * time.Millisecond) //nolint:forbidigo
+	}
+
+	return errHealthTimeout
+}
+
+// runHS executes a headscale CLI command and returns its stdout.
+func runHS(ctx context.Context, bin, config string, args ...string) ([]byte, error) {
+	fullArgs := append([]string{"-c", config}, args...)
+	cmd := exec.CommandContext(ctx, bin, fullArgs...)
+	cmd.Stderr = os.Stderr
+
+	return cmd.Output()
+}
+
+// extractUserID parses the JSON output of "users create" and returns the
+// user ID.
+func extractUserID(data []byte) (uint64, error) {
+	var user struct {
+		ID uint64 `json:"id"`
+	}
+
+	err := json.Unmarshal(data, &user)
+	if err != nil {
+		return 0, fmt.Errorf("unmarshalling user JSON: %w (raw: %s)", err, data)
+	}
+
+	return user.ID, nil
+}
+
+// extractAuthKey parses the JSON output of "preauthkeys create" and
+// returns the key string.
+func extractAuthKey(data []byte) (string, error) {
+	var key struct {
+		Key string `json:"key"`
+	}
+
+	err := json.Unmarshal(data, &key)
+	if err != nil {
+		return "", fmt.Errorf("unmarshalling key JSON: %w (raw: %s)", err, data)
+	}
+
+	if key.Key == "" {
+		return "", errEmptyAuthKey
+	}
+
+	return key.Key, nil
+}

cmd/gen-openapi/main.go

@@ -0,0 +1,75 @@
+// Command gen-openapi emits a Headscale OpenAPI document from the authoritative
+// Huma definitions in hscontrol/api/v1 and hscontrol/api/v2. The server also
+// serves each spec live (at /openapi.yaml and /api/v2/openapi); this tool emits
+// them on demand, and with -downgrade the 3.0.3 form used to generate the typed
+// client. The output is not committed.
+//
+// Usage:
+//
+//	go run ./cmd/gen-openapi                       # write the v1 3.1 spec to its default path
+//	go run ./cmd/gen-openapi -api v2               # write the v2 3.1 spec to its default path
+//	go run ./cmd/gen-openapi -downgrade <path>     # write the v1 3.0.3 downgrade (for client gen)
+//	go run ./cmd/gen-openapi -api v2 -downgrade <path>  # the v2 3.0.3 downgrade
+package main
+
+import (
+	"flag"
+	"log"
+	"os"
+	"path/filepath"
+
+	apiv1 "github.com/juanfont/headscale/hscontrol/api/v1"
+	apiv2 "github.com/juanfont/headscale/hscontrol/api/v2"
+)
+
+// spec bundles a version's full (3.1) and downgraded (3.0.3) generators with the
+// committed output path. outPath is relative to the repository root.
+type spec struct {
+	full    func() ([]byte, error)
+	down    func() ([]byte, error)
+	outPath string
+}
+
+// specs maps the -api value to its generators.
+var specs = map[string]spec{
+	"v1": {apiv1.Spec, apiv1.Spec30, "openapi/v1/headscale.yaml"},
+	"v2": {apiv2.Spec, apiv2.Spec30, "openapi/v2/headscale.yaml"},
+}
+
+func main() {
+	api := flag.String("api", "v1", "which API spec to emit: v1 or v2")
+	downgrade := flag.String("downgrade", "", "write the OpenAPI 3.0.3 downgrade to this path instead of the committed 3.1 spec")
+	flag.Parse()
+
+	s, ok := specs[*api]
+	if !ok {
+		log.Fatalf("unknown -api %q (want v1 or v2)", *api)
+	}
+
+	if *downgrade != "" {
+		writeSpec(*downgrade, s.down)
+
+		return
+	}
+
+	writeSpec(s.outPath, s.full)
+}
+
+func writeSpec(path string, gen func() ([]byte, error)) {
+	spec, err := gen()
+	if err != nil {
+		log.Fatalf("generating OpenAPI spec: %v", err)
+	}
+
+	err = os.MkdirAll(filepath.Dir(path), 0o755)
+	if err != nil {
+		log.Fatalf("creating output directory: %v", err)
+	}
+
+	err = os.WriteFile(path, spec, 0o600)
+	if err != nil {
+		log.Fatalf("writing %s: %v", path, err)
+	}
+
+	log.Printf("wrote %s", path)
+}

cmd/headscale/cli/api_key.go

@@ -1,20 +1,18 @@
 package cli
 
 import (
+	"context"
 	"fmt"
+	"net/http"
 	"strconv"
-	"time"
 
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	clientv1 "github.com/juanfont/headscale/gen/client/v1"
 	"github.com/juanfont/headscale/hscontrol/util"
-	"github.com/prometheus/common/model"
-	"github.com/pterm/pterm"
 	"github.com/spf13/cobra"
-	"google.golang.org/protobuf/types/known/timestamppb"
 )
 
 const (
-	// 90 days.
+	// DefaultAPIKeyExpiry is 90 days.
 	DefaultAPIKeyExpiry = "90d"
 )
 
@@ -43,58 +41,45 @@ var apiKeysCmd = &cobra.Command{
 }
 
 var listAPIKeys = &cobra.Command{
-	Use:     "list",
+	Use:     cmdList,
 	Short:   "List the Api keys for headscale",
-	Aliases: []string{"ls", "show"},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
-
-		request := &v1.ListApiKeysRequest{}
-
-		response, err := client.ListApiKeys(ctx, request)
+	Aliases: []string{"ls", cmdShow},
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		resp, err := client.ListApiKeysWithResponse(ctx)
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error getting the list of keys: %s", err),
-				output,
-			)
+			return fmt.Errorf("listing api keys: %w", err)
 		}
 
-		if output != "" {
-			SuccessOutput(response.GetApiKeys(), "", output)
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
 		}
 
-		tableData := pterm.TableData{
-			{"ID", "Prefix", "Expiration", "Created"},
-		}
-		for _, key := range response.GetApiKeys() {
-			expiration := "-"
+		apiKeys := resp.JSON200.ApiKeys
 
-			if key.GetExpiration() != nil {
-				expiration = ColourTime(key.GetExpiration().AsTime())
+		return printListOutput(cmd, apiKeys, func() error {
+			rows := make([][]string, 0, len(apiKeys))
+			for _, key := range apiKeys {
+				expiration := "-"
+				if key.Expiration != nil {
+					expiration = ColourTime(*key.Expiration)
+				}
+
+				var created string
+				if key.CreatedAt != nil {
+					created = key.CreatedAt.Format(HeadscaleDateTimeFormat)
+				}
+
+				rows = append(rows, []string{
+					key.Id,
+					key.Prefix,
+					expiration,
+					created,
+				})
 			}
 
-			tableData = append(tableData, []string{
-				strconv.FormatUint(key.GetId(), util.Base10),
-				key.GetPrefix(),
-				expiration,
-				key.GetCreatedAt().AsTime().Format(HeadscaleDateTimeFormat),
-			})
-
-		}
-		err = pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Failed to render pterm table: %s", err),
-				output,
-			)
-		}
-	},
+			return renderTable([]string{"ID", "Prefix", colExpiration, colCreated}, rows)
+		})
+	}),
 }
 
 var createAPIKeyCmd = &cobra.Command{
@@ -103,139 +88,136 @@ var createAPIKeyCmd = &cobra.Command{
 	Long: `
 Creates a new Api key, the Api key is only visible on creation
 and cannot be retrieved again.
-If you loose a key, create a new one and revoke (expire) the old one.`,
-	Aliases: []string{"c", "new"},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		request := &v1.CreateApiKeyRequest{}
-
-		durationStr, _ := cmd.Flags().GetString("expiration")
-
-		duration, err := model.ParseDuration(durationStr)
+If you lose a key, create a new one and revoke (expire) the old one.`,
+	Aliases: []string{"c", cmdNew},
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		expiryTime, err := expirationFromFlag(cmd)
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Could not parse duration: %s\n", err),
-				output,
-			)
+			return err
 		}
 
-		expiration := time.Now().UTC().Add(time.Duration(duration))
-
-		request.Expiration = timestamppb.New(expiration)
-
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
-
-		response, err := client.CreateApiKey(ctx, request)
+		resp, err := client.CreateApiKeyWithResponse(ctx, clientv1.CreateApiKeyJSONRequestBody{
+			Expiration: &expiryTime,
+		})
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Cannot create Api Key: %s\n", err),
-				output,
-			)
+			return fmt.Errorf("creating api key: %w", err)
 		}
 
-		SuccessOutput(response.GetApiKey(), response.GetApiKey(), output)
-	},
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200.ApiKey, resp.JSON200.ApiKey)
+	}),
+}
+
+// apiKeyIDOrPrefix reads --id and --prefix from cmd and validates that
+// exactly one is provided.
+func apiKeyIDOrPrefix(cmd *cobra.Command) (uint64, string, error) {
+	id, _ := cmd.Flags().GetUint64("id")
+	prefix, _ := cmd.Flags().GetString("prefix")
+
+	switch {
+	case id == 0 && prefix == "":
+		return 0, "", fmt.Errorf("either --id or --prefix must be provided: %w", errMissingParameter)
+	case id != 0 && prefix != "":
+		return 0, "", fmt.Errorf("only one of --id or --prefix can be provided: %w", errMissingParameter)
+	}
+
+	return id, prefix, nil
 }
 
 var expireAPIKeyCmd = &cobra.Command{
-	Use:     "expire",
+	Use:     cmdExpire,
 	Short:   "Expire an ApiKey",
-	Aliases: []string{"revoke", "exp", "e"},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		id, _ := cmd.Flags().GetUint64("id")
-		prefix, _ := cmd.Flags().GetString("prefix")
-
-		switch {
-		case id == 0 && prefix == "":
-			ErrorOutput(
-				errMissingParameter,
-				"Either --id or --prefix must be provided",
-				output,
-			)
-		case id != 0 && prefix != "":
-			ErrorOutput(
-				errMissingParameter,
-				"Only one of --id or --prefix can be provided",
-				output,
-			)
-		}
-
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
-
-		request := &v1.ExpireApiKeyRequest{}
-		if id != 0 {
-			request.Id = id
-		} else {
-			request.Prefix = prefix
-		}
-
-		response, err := client.ExpireApiKey(ctx, request)
+	Aliases: []string{"revoke", aliasExp, "e"},
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		id, prefix, err := apiKeyIDOrPrefix(cmd)
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Cannot expire Api Key: %s\n", err),
-				output,
-			)
+			return err
 		}
 
-		SuccessOutput(response, "Key expired", output)
-	},
+		body := clientv1.ExpireApiKeyJSONRequestBody{}
+
+		if id != 0 {
+			idStr := strconv.FormatUint(id, util.Base10)
+			body.Id = &idStr
+		}
+
+		if prefix != "" {
+			body.Prefix = &prefix
+		}
+
+		resp, err := client.ExpireApiKeyWithResponse(ctx, body)
+		if err != nil {
+			return fmt.Errorf("expiring api key: %w", err)
+		}
+
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200, "Key expired")
+	}),
 }
 
 var deleteAPIKeyCmd = &cobra.Command{
-	Use:     "delete",
+	Use:     cmdDelete,
 	Short:   "Delete an ApiKey",
-	Aliases: []string{"remove", "del"},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		id, _ := cmd.Flags().GetUint64("id")
-		prefix, _ := cmd.Flags().GetString("prefix")
-
-		switch {
-		case id == 0 && prefix == "":
-			ErrorOutput(
-				errMissingParameter,
-				"Either --id or --prefix must be provided",
-				output,
-			)
-		case id != 0 && prefix != "":
-			ErrorOutput(
-				errMissingParameter,
-				"Only one of --id or --prefix can be provided",
-				output,
-			)
-		}
-
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
-
-		request := &v1.DeleteApiKeyRequest{}
-		if id != 0 {
-			request.Id = id
-		} else {
-			request.Prefix = prefix
-		}
-
-		response, err := client.DeleteApiKey(ctx, request)
+	Aliases: []string{"remove", aliasDel},
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		id, prefix, err := apiKeyIDOrPrefix(cmd)
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Cannot delete Api Key: %s\n", err),
-				output,
-			)
+			return err
 		}
 
-		SuccessOutput(response, "Key deleted", output)
-	},
+		// The DELETE route addresses the key by its prefix in the path. When the
+		// user deletes by --id we resolve the id to its (masked) prefix first,
+		// since the path segment is required and a query-only id cannot be routed.
+		if prefix == "" {
+			prefix, err = apiKeyPrefixForID(ctx, client, id)
+			if err != nil {
+				return err
+			}
+		}
+
+		resp, err := client.DeleteApiKeyWithResponse(ctx, prefix, &clientv1.DeleteApiKeyParams{})
+		if err != nil {
+			return fmt.Errorf("deleting api key: %w", err)
+		}
+
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200, "Key deleted")
+	}),
+}
+
+// apiKeyPrefixForID resolves an API key id to its display prefix by listing the
+// keys. The DELETE endpoint addresses keys by prefix in the URL path, so a
+// delete by --id needs the prefix; the returned masked prefix is accepted by
+// the server's lookup.
+func apiKeyPrefixForID(
+	ctx context.Context,
+	client *clientv1.ClientWithResponses,
+	id uint64,
+) (string, error) {
+	resp, err := client.ListApiKeysWithResponse(ctx)
+	if err != nil {
+		return "", fmt.Errorf("listing api keys: %w", err)
+	}
+
+	if resp.StatusCode() != http.StatusOK {
+		return "", apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+	}
+
+	idStr := strconv.FormatUint(id, util.Base10)
+	for _, key := range resp.JSON200.ApiKeys {
+		if key.Id == idStr {
+			return key.Prefix, nil
+		}
+	}
+
+	return "", fmt.Errorf("%w: api key %d not found", errMissingParameter, id)
 }

cmd/headscale/cli/auth.go

@@ -0,0 +1,99 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+
+	clientv1 "github.com/juanfont/headscale/gen/client/v1"
+	"github.com/spf13/cobra"
+)
+
+func init() {
+	rootCmd.AddCommand(authCmd)
+
+	authRegisterCmd.Flags().StringP("user", "u", "", "User")
+	authRegisterCmd.Flags().String("auth-id", "", "Auth ID")
+	mustMarkRequired(authRegisterCmd, "user", "auth-id")
+	authCmd.AddCommand(authRegisterCmd)
+
+	authApproveCmd.Flags().String("auth-id", "", "Auth ID")
+	mustMarkRequired(authApproveCmd, "auth-id")
+	authCmd.AddCommand(authApproveCmd)
+
+	authRejectCmd.Flags().String("auth-id", "", "Auth ID")
+	mustMarkRequired(authRejectCmd, "auth-id")
+	authCmd.AddCommand(authRejectCmd)
+}
+
+var authCmd = &cobra.Command{
+	Use:   "auth",
+	Short: "Manage node authentication and approval",
+}
+
+var authRegisterCmd = &cobra.Command{
+	Use:   "register",
+	Short: "Register a node to your network",
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		user, _ := cmd.Flags().GetString("user")
+		authID, _ := cmd.Flags().GetString("auth-id")
+
+		resp, err := client.AuthRegisterWithResponse(ctx, clientv1.AuthRegisterJSONRequestBody{
+			AuthId: &authID,
+			User:   &user,
+		})
+		if err != nil {
+			return fmt.Errorf("registering node: %w", err)
+		}
+
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		node := resp.JSON200.Node
+
+		return printOutput(
+			cmd,
+			node,
+			fmt.Sprintf("Node %s registered", node.GivenName),
+		)
+	}),
+}
+
+var authApproveCmd = &cobra.Command{
+	Use:   "approve",
+	Short: "Approve a pending authentication request",
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		authID, _ := cmd.Flags().GetString("auth-id")
+
+		resp, err := client.AuthApproveWithResponse(ctx, clientv1.AuthApproveJSONRequestBody{AuthId: &authID})
+		if err != nil {
+			return fmt.Errorf("approving auth request: %w", err)
+		}
+
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200, "Auth request approved")
+	}),
+}
+
+var authRejectCmd = &cobra.Command{
+	Use:   "reject",
+	Short: "Reject a pending authentication request",
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		authID, _ := cmd.Flags().GetString("auth-id")
+
+		resp, err := client.AuthRejectWithResponse(ctx, clientv1.AuthRejectJSONRequestBody{AuthId: &authID})
+		if err != nil {
+			return fmt.Errorf("rejecting auth request: %w", err)
+		}
+
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200, "Auth request rejected")
+	}),
+}

cmd/headscale/cli/configtest.go

@@ -1,7 +1,8 @@
 package cli
 
 import (
-	"github.com/rs/zerolog/log"
+	"fmt"
+
 	"github.com/spf13/cobra"
 )
 
@@ -13,10 +14,12 @@ var configTestCmd = &cobra.Command{
 	Use:   "configtest",
 	Short: "Test the configuration.",
 	Long:  "Run a test of the configuration and exit.",
-	Run: func(cmd *cobra.Command, args []string) {
+	RunE: func(cmd *cobra.Command, args []string) error {
 		_, err := newHeadscaleServerWithConfig()
 		if err != nil {
-			log.Fatal().Caller().Err(err).Msg("Error initializing")
+			return fmt.Errorf("configuration error: %w", err)
 		}
+
+		return nil
 	},
 }

cmd/headscale/cli/debug.go

@@ -1,44 +1,23 @@
 package cli
 
 import (
+	"context"
 	"fmt"
+	"net/http"
 
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	clientv1 "github.com/juanfont/headscale/gen/client/v1"
 	"github.com/juanfont/headscale/hscontrol/types"
-	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
-	"google.golang.org/grpc/status"
 )
 
-// Error is used to compare errors as per https://dave.cheney.net/2016/04/07/constant-errors
-type Error string
-
-func (e Error) Error() string { return string(e) }
-
 func init() {
 	rootCmd.AddCommand(debugCmd)
 
 	createNodeCmd.Flags().StringP("name", "", "", "Name")
-	err := createNodeCmd.MarkFlagRequired("name")
-	if err != nil {
-		log.Fatal().Err(err).Msg("")
-	}
 	createNodeCmd.Flags().StringP("user", "u", "", "User")
-
-	createNodeCmd.Flags().StringP("namespace", "n", "", "User")
-	createNodeNamespaceFlag := createNodeCmd.Flags().Lookup("namespace")
-	createNodeNamespaceFlag.Deprecated = deprecateNamespaceMessage
-	createNodeNamespaceFlag.Hidden = true
-
-	err = createNodeCmd.MarkFlagRequired("user")
-	if err != nil {
-		log.Fatal().Err(err).Msg("")
-	}
 	createNodeCmd.Flags().StringP("key", "k", "", "Key")
-	err = createNodeCmd.MarkFlagRequired("key")
-	if err != nil {
-		log.Fatal().Err(err).Msg("")
-	}
+	mustMarkRequired(createNodeCmd, "name", "user", "key")
+
 	createNodeCmd.Flags().
 		StringSliceP("route", "r", []string{}, "List (or repeated flags) of routes to advertise")
 
@@ -53,71 +32,33 @@ var debugCmd = &cobra.Command{
 
 var createNodeCmd = &cobra.Command{
 	Use:   "create-node",
-	Short: "Create a node that can be registered with `nodes register <>` command",
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
+	Short: "Create a node that can be registered with `auth register <>` command",
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		user, _ := cmd.Flags().GetString("user")
+		name, _ := cmd.Flags().GetString("name")
+		registrationID, _ := cmd.Flags().GetString("key")
 
-		user, err := cmd.Flags().GetString("user")
+		_, err := types.AuthIDFromString(registrationID)
 		if err != nil {
-			ErrorOutput(err, fmt.Sprintf("Error getting user: %s", err), output)
+			return fmt.Errorf("parsing machine key: %w", err)
 		}
 
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
+		routes, _ := cmd.Flags().GetStringSlice("route")
 
-		name, err := cmd.Flags().GetString("name")
+		resp, err := client.DebugCreateNodeWithResponse(ctx, clientv1.DebugCreateNodeJSONRequestBody{
+			Key:    &registrationID,
+			Name:   &name,
+			User:   &user,
+			Routes: &routes,
+		})
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error getting node from flag: %s", err),
-				output,
-			)
+			return fmt.Errorf("creating node: %w", err)
 		}
 
-		registrationID, err := cmd.Flags().GetString("key")
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error getting key from flag: %s", err),
-				output,
-			)
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
 		}
 
-		_, err = types.RegistrationIDFromString(registrationID)
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Failed to parse machine key from flag: %s", err),
-				output,
-			)
-		}
-
-		routes, err := cmd.Flags().GetStringSlice("route")
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error getting routes from flag: %s", err),
-				output,
-			)
-		}
-
-		request := &v1.DebugCreateNodeRequest{
-			Key:    registrationID,
-			Name:   name,
-			User:   user,
-			Routes: routes,
-		}
-
-		response, err := client.DebugCreateNode(ctx, request)
-		if err != nil {
-			ErrorOutput(
-				err,
-				"Cannot create node: "+status.Convert(err).Message(),
-				output,
-			)
-		}
-
-		SuccessOutput(response.GetNode(), "Node created", output)
-	},
+		return printOutput(cmd, resp.JSON200.Node, "Node created")
+	}),
 }

cmd/headscale/cli/dump_config.go

@@ -15,14 +15,12 @@ var dumpConfigCmd = &cobra.Command{
 	Use:    "dumpConfig",
 	Short:  "dump current config to /etc/headscale/config.dump.yaml, integration test only",
 	Hidden: true,
-	Args: func(cmd *cobra.Command, args []string) error {
-		return nil
-	},
-	Run: func(cmd *cobra.Command, args []string) {
+	RunE: func(cmd *cobra.Command, args []string) error {
 		err := viper.WriteConfigAs("/etc/headscale/config.dump.yaml")
 		if err != nil {
-			//nolint
-			fmt.Println("Failed to dump config")
+			return fmt.Errorf("dumping config: %w", err)
 		}
+
+		return nil
 	},
 }

cmd/headscale/cli/generate.go

@@ -21,22 +21,17 @@ var generateCmd = &cobra.Command{
 var generatePrivateKeyCmd = &cobra.Command{
 	Use:   "private-key",
 	Short: "Generate a private key for the headscale server",
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
+	RunE: func(cmd *cobra.Command, args []string) error {
 		machineKey := key.NewMachine()
 
 		machineKeyStr, err := machineKey.MarshalText()
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error getting machine key from flag: %s", err),
-				output,
-			)
+			return fmt.Errorf("marshalling machine key: %w", err)
 		}
 
-		SuccessOutput(map[string]string{
+		return printOutput(cmd, map[string]string{
 			"private_key": string(machineKeyStr),
 		},
-			string(machineKeyStr), output)
+			string(machineKeyStr))
 	},
 }

cmd/headscale/cli/health.go

@@ -1,7 +1,11 @@
 package cli
 
 import (
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	"context"
+	"fmt"
+	"net/http"
+
+	clientv1 "github.com/juanfont/headscale/gen/client/v1"
 	"github.com/spf13/cobra"
 )
 
@@ -13,17 +17,16 @@ var healthCmd = &cobra.Command{
 	Use:   "health",
 	Short: "Check the health of the Headscale server",
 	Long:  "Check the health of the Headscale server. This command will return an exit code of 0 if the server is healthy, or 1 if it is not.",
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
-
-		response, err := client.Health(ctx, &v1.HealthRequest{})
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		resp, err := client.HealthWithResponse(ctx)
 		if err != nil {
-			ErrorOutput(err, "Error checking health", output)
+			return fmt.Errorf("checking health: %w", err)
 		}
 
-		SuccessOutput(response, "", output)
-	},
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200, "")
+	}),
 }

cmd/headscale/cli/mockoidc.go

@@ -1,6 +1,7 @@
 package cli
 
 import (
+	"context"
 	"encoding/json"
 	"errors"
 	"fmt"
@@ -10,18 +11,21 @@ import (
 	"strconv"
 	"time"
 
+	"github.com/juanfont/headscale/hscontrol/util/zlog/zf"
 	"github.com/oauth2-proxy/mockoidc"
 	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
 )
 
-const (
-	errMockOidcClientIDNotDefined     = Error("MOCKOIDC_CLIENT_ID not defined")
-	errMockOidcClientSecretNotDefined = Error("MOCKOIDC_CLIENT_SECRET not defined")
-	errMockOidcPortNotDefined         = Error("MOCKOIDC_PORT not defined")
-	refreshTTL                        = 60 * time.Minute
+var (
+	errMockOidcClientIDNotDefined     = errors.New("MOCKOIDC_CLIENT_ID not defined")
+	errMockOidcClientSecretNotDefined = errors.New("MOCKOIDC_CLIENT_SECRET not defined")
+	errMockOidcPortNotDefined         = errors.New("MOCKOIDC_PORT not defined")
+	errMockOidcUsersNotDefined        = errors.New("MOCKOIDC_USERS not defined")
 )
 
+const refreshTTL = 60 * time.Minute
+
 var accessTTL = 2 * time.Minute
 
 func init() {
@@ -32,12 +36,13 @@ var mockOidcCmd = &cobra.Command{
 	Use:   "mockoidc",
 	Short: "Runs a mock OIDC server for testing",
 	Long:  "This internal command runs a OpenID Connect for testing purposes",
-	Run: func(cmd *cobra.Command, args []string) {
+	RunE: func(cmd *cobra.Command, args []string) error {
 		err := mockOIDC()
 		if err != nil {
-			log.Error().Err(err).Msgf("Error running mock OIDC server")
-			os.Exit(1)
+			return fmt.Errorf("running mock OIDC server: %w", err)
 		}
+
+		return nil
 	},
 }
 
@@ -46,41 +51,47 @@ func mockOIDC() error {
 	if clientID == "" {
 		return errMockOidcClientIDNotDefined
 	}
+
 	clientSecret := os.Getenv("MOCKOIDC_CLIENT_SECRET")
 	if clientSecret == "" {
 		return errMockOidcClientSecretNotDefined
 	}
+
 	addrStr := os.Getenv("MOCKOIDC_ADDR")
 	if addrStr == "" {
 		return errMockOidcPortNotDefined
 	}
+
 	portStr := os.Getenv("MOCKOIDC_PORT")
 	if portStr == "" {
 		return errMockOidcPortNotDefined
 	}
+
 	accessTTLOverride := os.Getenv("MOCKOIDC_ACCESS_TTL")
 	if accessTTLOverride != "" {
 		newTTL, err := time.ParseDuration(accessTTLOverride)
 		if err != nil {
 			return err
 		}
+
 		accessTTL = newTTL
 	}
 
 	userStr := os.Getenv("MOCKOIDC_USERS")
 	if userStr == "" {
-		return errors.New("MOCKOIDC_USERS not defined")
+		return errMockOidcUsersNotDefined
 	}
 
 	var users []mockoidc.MockUser
+
 	err := json.Unmarshal([]byte(userStr), &users)
 	if err != nil {
 		return fmt.Errorf("unmarshalling users: %w", err)
 	}
 
-	log.Info().Interface("users", users).Msg("loading users from JSON")
+	log.Info().Interface(zf.Users, users).Msg("loading users from JSON")
 
-	log.Info().Msgf("Access token TTL: %s", accessTTL)
+	log.Info().Msgf("access token TTL: %s", accessTTL)
 
 	port, err := strconv.Atoi(portStr)
 	if err != nil {
@@ -92,7 +103,7 @@ func mockOIDC() error {
 		return err
 	}
 
-	listener, err := net.Listen("tcp", fmt.Sprintf("%s:%d", addrStr, port))
+	listener, err := new(net.ListenConfig).Listen(context.Background(), "tcp", fmt.Sprintf("%s:%d", addrStr, port))
 	if err != nil {
 		return err
 	}
@@ -101,8 +112,10 @@ func mockOIDC() error {
 	if err != nil {
 		return err
 	}
-	log.Info().Msgf("Mock OIDC server listening on %s", listener.Addr().String())
-	log.Info().Msgf("Issuer: %s", mock.Issuer())
+
+	log.Info().Msgf("mock OIDC server listening on %s", listener.Addr().String())
+	log.Info().Msgf("issuer: %s", mock.Issuer())
+
 	c := make(chan struct{})
 	<-c
 
@@ -133,12 +146,13 @@ func getMockOIDC(clientID string, clientSecret string, users []mockoidc.MockUser
 		ErrorQueue:                    &mockoidc.ErrorQueue{},
 	}
 
-	mock.AddMiddleware(func(h http.Handler) http.Handler {
+	_ = mock.AddMiddleware(func(h http.Handler) http.Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-			log.Info().Msgf("Request: %+v", r)
+			log.Info().Msgf("request: %+v", r)
 			h.ServeHTTP(w, r)
+
 			if r.Response != nil {
-				log.Info().Msgf("Response: %+v", r.Response)
+				log.Info().Msgf("response: %+v", r.Response)
 			}
 		})
 	})

cmd/headscale/cli/nodes.go

@@ -1,83 +1,56 @@
 package cli
 
 import (
+	"context"
 	"fmt"
-	"log"
+	"net/http"
 	"net/netip"
 	"strconv"
 	"strings"
 	"time"
 
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	clientv1 "github.com/juanfont/headscale/gen/client/v1"
 	"github.com/juanfont/headscale/hscontrol/util"
 	"github.com/pterm/pterm"
 	"github.com/samber/lo"
 	"github.com/spf13/cobra"
-	"google.golang.org/grpc/status"
-	"google.golang.org/protobuf/types/known/timestamppb"
 	"tailscale.com/types/key"
 )
 
 func init() {
 	rootCmd.AddCommand(nodeCmd)
 	listNodesCmd.Flags().StringP("user", "u", "", "Filter by user")
-
-	listNodesCmd.Flags().StringP("namespace", "n", "", "User")
-	listNodesNamespaceFlag := listNodesCmd.Flags().Lookup("namespace")
-	listNodesNamespaceFlag.Deprecated = deprecateNamespaceMessage
-	listNodesNamespaceFlag.Hidden = true
 	nodeCmd.AddCommand(listNodesCmd)
 
 	listNodeRoutesCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
 	nodeCmd.AddCommand(listNodeRoutesCmd)
 
 	registerNodeCmd.Flags().StringP("user", "u", "", "User")
-
-	registerNodeCmd.Flags().StringP("namespace", "n", "", "User")
-	registerNodeNamespaceFlag := registerNodeCmd.Flags().Lookup("namespace")
-	registerNodeNamespaceFlag.Deprecated = deprecateNamespaceMessage
-	registerNodeNamespaceFlag.Hidden = true
-
-	err := registerNodeCmd.MarkFlagRequired("user")
-	if err != nil {
-		log.Fatal(err.Error())
-	}
 	registerNodeCmd.Flags().StringP("key", "k", "", "Key")
-	err = registerNodeCmd.MarkFlagRequired("key")
-	if err != nil {
-		log.Fatal(err.Error())
-	}
+	mustMarkRequired(registerNodeCmd, "user", "key")
 	nodeCmd.AddCommand(registerNodeCmd)
 
 	expireNodeCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
 	expireNodeCmd.Flags().StringP("expiry", "e", "", "Set expire to (RFC3339 format, e.g. 2025-08-27T10:00:00Z), or leave empty to expire immediately.")
-	err = expireNodeCmd.MarkFlagRequired("identifier")
-	if err != nil {
-		log.Fatal(err.Error())
-	}
+	expireNodeCmd.Flags().BoolP("disable", "d", false, "Disable key expiry (node will never expire)")
+	mustMarkRequired(expireNodeCmd, "identifier")
 	nodeCmd.AddCommand(expireNodeCmd)
 
 	renameNodeCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
-	err = renameNodeCmd.MarkFlagRequired("identifier")
-	if err != nil {
-		log.Fatal(err.Error())
-	}
+	mustMarkRequired(renameNodeCmd, "identifier")
 	nodeCmd.AddCommand(renameNodeCmd)
 
 	deleteNodeCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
-	err = deleteNodeCmd.MarkFlagRequired("identifier")
-	if err != nil {
-		log.Fatal(err.Error())
-	}
+	mustMarkRequired(deleteNodeCmd, "identifier")
 	nodeCmd.AddCommand(deleteNodeCmd)
 
 	tagCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
-	tagCmd.MarkFlagRequired("identifier")
+	mustMarkRequired(tagCmd, "identifier")
 	tagCmd.Flags().StringSliceP("tags", "t", []string{}, "List of tags to add to the node")
 	nodeCmd.AddCommand(tagCmd)
 
 	approveRoutesCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
-	approveRoutesCmd.MarkFlagRequired("identifier")
+	mustMarkRequired(approveRoutesCmd, "identifier")
 	approveRoutesCmd.Flags().StringSliceP("routes", "r", []string{}, `List of routes that will be approved (comma-separated, e.g. "10.0.0.0/8,192.168.0.0/24" or empty string to remove all approved routes)`)
 	nodeCmd.AddCommand(approveRoutesCmd)
 
@@ -87,352 +60,243 @@ func init() {
 var nodeCmd = &cobra.Command{
 	Use:     "nodes",
 	Short:   "Manage the nodes of Headscale",
-	Aliases: []string{"node", "machine", "machines"},
+	Aliases: []string{"node"},
 }
 
 var registerNodeCmd = &cobra.Command{
-	Use:   "register",
-	Short: "Registers a node to your network",
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-		user, err := cmd.Flags().GetString("user")
+	Use:        "register",
+	Short:      "Registers a node to your network",
+	Deprecated: "use 'headscale auth register --auth-id <id> --user <user>' instead",
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		user, _ := cmd.Flags().GetString("user")
+		registrationID, _ := cmd.Flags().GetString("key")
+
+		params := &clientv1.RegisterNodeParams{
+			User: &user,
+			Key:  &registrationID,
+		}
+
+		resp, err := client.RegisterNodeWithResponse(ctx, params)
 		if err != nil {
-			ErrorOutput(err, fmt.Sprintf("Error getting user: %s", err), output)
+			return fmt.Errorf("registering node: %w", err)
 		}
 
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
-
-		registrationID, err := cmd.Flags().GetString("key")
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error getting node key from flag: %s", err),
-				output,
-			)
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
 		}
 
-		request := &v1.RegisterNodeRequest{
-			Key:  registrationID,
-			User: user,
-		}
+		node := resp.JSON200.Node
 
-		response, err := client.RegisterNode(ctx, request)
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf(
-					"Cannot register node: %s\n",
-					status.Convert(err).Message(),
-				),
-				output,
-			)
-		}
-
-		SuccessOutput(
-			response.GetNode(),
-			fmt.Sprintf("Node %s registered", response.GetNode().GetGivenName()), output)
-	},
+		return printOutput(
+			cmd,
+			node,
+			fmt.Sprintf("Node %s registered", node.GivenName),
+		)
+	}),
 }
 
 var listNodesCmd = &cobra.Command{
-	Use:     "list",
+	Use:     cmdList,
 	Short:   "List nodes",
-	Aliases: []string{"ls", "show"},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-		user, err := cmd.Flags().GetString("user")
+	Aliases: []string{"ls", cmdShow},
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		user, _ := cmd.Flags().GetString("user")
+
+		params := &clientv1.ListNodesParams{}
+		if user != "" {
+			params.User = &user
+		}
+
+		resp, err := client.ListNodesWithResponse(ctx, params)
 		if err != nil {
-			ErrorOutput(err, fmt.Sprintf("Error getting user: %s", err), output)
+			return fmt.Errorf("listing nodes: %w", err)
 		}
 
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
-
-		request := &v1.ListNodesRequest{
-			User: user,
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
 		}
 
-		response, err := client.ListNodes(ctx, request)
-		if err != nil {
-			ErrorOutput(
-				err,
-				"Cannot get nodes: "+status.Convert(err).Message(),
-				output,
-			)
-		}
+		nodes := resp.JSON200.Nodes
 
-		if output != "" {
-			SuccessOutput(response.GetNodes(), "", output)
-		}
+		return printListOutput(cmd, nodes, func() error {
+			tableData, err := nodesToPtables(nodes)
+			if err != nil {
+				return fmt.Errorf("converting to table: %w", err)
+			}
 
-		tableData, err := nodesToPtables(user, response.GetNodes())
-		if err != nil {
-			ErrorOutput(err, fmt.Sprintf("Error converting to table: %s", err), output)
-		}
-
-		err = pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Failed to render pterm table: %s", err),
-				output,
-			)
-		}
-	},
+			return pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
+		})
+	}),
 }
 
 var listNodeRoutesCmd = &cobra.Command{
 	Use:     "list-routes",
 	Short:   "List routes available on nodes",
 	Aliases: []string{"lsr", "routes"},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-		identifier, err := cmd.Flags().GetUint64("identifier")
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		identifier, _ := cmd.Flags().GetUint64("identifier")
+
+		resp, err := client.ListNodesWithResponse(ctx, &clientv1.ListNodesParams{})
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error converting ID to integer: %s", err),
-				output,
-			)
+			return fmt.Errorf("listing nodes: %w", err)
 		}
 
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
-
-		request := &v1.ListNodesRequest{}
-
-		response, err := client.ListNodes(ctx, request)
-		if err != nil {
-			ErrorOutput(
-				err,
-				"Cannot get nodes: "+status.Convert(err).Message(),
-				output,
-			)
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
 		}
 
-		nodes := response.GetNodes()
+		nodes := resp.JSON200.Nodes
+
 		if identifier != 0 {
-			for _, node := range response.GetNodes() {
-				if node.GetId() == identifier {
-					nodes = []*v1.Node{node}
+			idStr := strconv.FormatUint(identifier, util.Base10)
+			for _, node := range nodes {
+				if node.Id == idStr {
+					nodes = []clientv1.Node{node}
+
 					break
 				}
 			}
 		}
 
-		nodes = lo.Filter(nodes, func(n *v1.Node, _ int) bool {
-			return (n.GetSubnetRoutes() != nil && len(n.GetSubnetRoutes()) > 0) || (n.GetApprovedRoutes() != nil && len(n.GetApprovedRoutes()) > 0) || (n.GetAvailableRoutes() != nil && len(n.GetAvailableRoutes()) > 0)
+		nodes = lo.Filter(nodes, func(n clientv1.Node, _ int) bool {
+			return len(n.SubnetRoutes) > 0 || len(n.ApprovedRoutes) > 0 || len(n.AvailableRoutes) > 0
 		})
 
-		if output != "" {
-			SuccessOutput(nodes, "", output)
-			return
-		}
-
-		tableData, err := nodeRoutesToPtables(nodes)
-		if err != nil {
-			ErrorOutput(err, fmt.Sprintf("Error converting to table: %s", err), output)
-		}
-
-		err = pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Failed to render pterm table: %s", err),
-				output,
-			)
-		}
-	},
+		return printListOutput(cmd, nodes, func() error {
+			return pterm.DefaultTable.WithHasHeader().WithData(nodeRoutesToPtables(nodes)).Render()
+		})
+	}),
 }
 
 var expireNodeCmd = &cobra.Command{
-	Use:     "expire",
-	Short:   "Expire (log out) a node in your network",
-	Long:    "Expiring a node will keep the node in the database and force it to reauthenticate.",
-	Aliases: []string{"logout", "exp", "e"},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
+	Use:   cmdExpire,
+	Short: "Expire (log out) a node in your network",
+	Long: `Expiring a node will keep the node in the database and force it to reauthenticate.
 
-		identifier, err := cmd.Flags().GetUint64("identifier")
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error converting ID to integer: %s", err),
-				output,
-			)
+Use --disable to disable key expiry (node will never expire).`,
+	Aliases: []string{"logout", aliasExp, "e"},
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		identifier, _ := cmd.Flags().GetUint64("identifier")
+		disableExpiry, _ := cmd.Flags().GetBool("disable")
+		nodeID := strconv.FormatUint(identifier, util.Base10)
+
+		// Handle disable expiry - node will never expire.
+		if disableExpiry {
+			disable := true
+
+			resp, err := client.ExpireNodeWithResponse(ctx, nodeID, clientv1.ExpireNodeJSONRequestBody{
+				DisableExpiry: &disable,
+			})
+			if err != nil {
+				return fmt.Errorf("disabling node expiry: %w", err)
+			}
+
+			if resp.StatusCode() != http.StatusOK {
+				return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+			}
+
+			return printOutput(cmd, resp.JSON200.Node, "Node expiry disabled")
 		}
 
-		expiry, err := cmd.Flags().GetString("expiry")
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error converting expiry to string: %s", err),
-				output,
-			)
+		expiry, _ := cmd.Flags().GetString("expiry")
 
-			return
-		}
 		now := time.Now()
+
 		expiryTime := now
+
 		if expiry != "" {
+			var err error
+
 			expiryTime, err = time.Parse(time.RFC3339, expiry)
 			if err != nil {
-				ErrorOutput(
-					err,
-					fmt.Sprintf("Error converting expiry to string: %s", err),
-					output,
-				)
-
-				return
+				return fmt.Errorf("parsing expiry time: %w", err)
 			}
 		}
 
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
-
-		request := &v1.ExpireNodeRequest{
-			NodeId: identifier,
-			Expiry: timestamppb.New(expiryTime),
-		}
-
-		response, err := client.ExpireNode(ctx, request)
+		resp, err := client.ExpireNodeWithResponse(ctx, nodeID, clientv1.ExpireNodeJSONRequestBody{
+			Expiry: &expiryTime,
+		})
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf(
-					"Cannot expire node: %s\n",
-					status.Convert(err).Message(),
-				),
-				output,
-			)
+			return fmt.Errorf("expiring node: %w", err)
 		}
 
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		node := resp.JSON200.Node
+
 		if now.Equal(expiryTime) || now.After(expiryTime) {
-			SuccessOutput(response.GetNode(), "Node expired", output)
-		} else {
-			SuccessOutput(response.GetNode(), "Node expiration updated", output)
+			return printOutput(cmd, node, "Node expired")
 		}
-	},
+
+		return printOutput(cmd, node, "Node expiration updated")
+	}),
 }
 
 var renameNodeCmd = &cobra.Command{
 	Use:   "rename NEW_NAME",
 	Short: "Renames a node in your network",
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		identifier, err := cmd.Flags().GetUint64("identifier")
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error converting ID to integer: %s", err),
-				output,
-			)
-		}
-
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		identifier, _ := cmd.Flags().GetUint64("identifier")
 
 		newName := ""
 		if len(args) > 0 {
 			newName = args[0]
 		}
-		request := &v1.RenameNodeRequest{
-			NodeId:  identifier,
-			NewName: newName,
-		}
 
-		response, err := client.RenameNode(ctx, request)
+		resp, err := client.RenameNodeWithResponse(ctx, strconv.FormatUint(identifier, util.Base10), newName)
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf(
-					"Cannot rename node: %s\n",
-					status.Convert(err).Message(),
-				),
-				output,
-			)
+			return fmt.Errorf("renaming node: %w", err)
 		}
 
-		SuccessOutput(response.GetNode(), "Node renamed", output)
-	},
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200.Node, "Node renamed")
+	}),
 }
 
 var deleteNodeCmd = &cobra.Command{
-	Use:     "delete",
+	Use:     cmdDelete,
 	Short:   "Delete a node",
-	Aliases: []string{"del"},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
+	Aliases: []string{aliasDel},
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		identifier, _ := cmd.Flags().GetUint64("identifier")
+		nodeID := strconv.FormatUint(identifier, util.Base10)
 
-		identifier, err := cmd.Flags().GetUint64("identifier")
+		getResponse, err := client.GetNodeWithResponse(ctx, nodeID)
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error converting ID to integer: %s", err),
-				output,
-			)
+			return fmt.Errorf("getting node: %w", err)
 		}
 
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
-
-		getRequest := &v1.GetNodeRequest{
-			NodeId: identifier,
+		if getResponse.StatusCode() != http.StatusOK {
+			return apiError(getResponse.StatusCode(), getResponse.ApplicationproblemJSONDefault)
 		}
 
-		getResponse, err := client.GetNode(ctx, getRequest)
+		if !confirmAction(cmd, fmt.Sprintf(
+			"Do you want to remove the node %s?",
+			getResponse.JSON200.Node.Name,
+		)) {
+			return printOutput(cmd, map[string]string{colResult: "Node not deleted"}, "Node not deleted")
+		}
+
+		deleteResponse, err := client.DeleteNodeWithResponse(ctx, nodeID)
 		if err != nil {
-			ErrorOutput(
-				err,
-				"Error getting node node: "+status.Convert(err).Message(),
-				output,
-			)
+			return fmt.Errorf("deleting node: %w", err)
 		}
 
-		deleteRequest := &v1.DeleteNodeRequest{
-			NodeId: identifier,
+		if deleteResponse.StatusCode() != http.StatusOK {
+			return apiError(deleteResponse.StatusCode(), deleteResponse.ApplicationproblemJSONDefault)
 		}
 
-		confirm := false
-		force, _ := cmd.Flags().GetBool("force")
-		if !force {
-			confirm = util.YesNo(fmt.Sprintf(
-				"Do you want to remove the node %s?",
-				getResponse.GetNode().GetName(),
-			))
-		}
-
-		if confirm || force {
-			response, err := client.DeleteNode(ctx, deleteRequest)
-			if output != "" {
-				SuccessOutput(response, "", output)
-
-				return
-			}
-			if err != nil {
-				ErrorOutput(
-					err,
-					"Error deleting node: "+status.Convert(err).Message(),
-					output,
-				)
-			}
-			SuccessOutput(
-				map[string]string{"Result": "Node deleted"},
-				"Node deleted",
-				output,
-			)
-		} else {
-			SuccessOutput(map[string]string{"Result": "Node not deleted"}, "Node not deleted", output)
-		}
-	},
+		return printOutput(
+			cmd,
+			map[string]string{colResult: "Node deleted"},
+			"Node deleted",
+		)
+	}),
 }
 
 var backfillNodeIPsCmd = &cobra.Command{
@@ -450,39 +314,31 @@ all nodes that are missing.
 If you remove IPv4 or IPv6 prefixes from the config,
 it can be run to remove the IPs that should no longer
 be assigned to nodes.`,
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		confirm := false
-
-		force, _ := cmd.Flags().GetBool("force")
-		if !force {
-			confirm = util.YesNo("Are you sure that you want to assign/remove IPs to/from nodes?")
+	RunE: func(cmd *cobra.Command, args []string) error {
+		if !confirmAction(cmd, "Are you sure that you want to assign/remove IPs to/from nodes?") {
+			return nil
 		}
 
-		if confirm || force {
-			ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-			defer cancel()
-			defer conn.Close()
+		return withClient(func(ctx context.Context, client *clientv1.ClientWithResponses) error {
+			confirmed := true
 
-			changes, err := client.BackfillNodeIPs(ctx, &v1.BackfillNodeIPsRequest{Confirmed: confirm || force})
+			resp, err := client.BackfillNodeIPsWithResponse(ctx, &clientv1.BackfillNodeIPsParams{
+				Confirmed: &confirmed,
+			})
 			if err != nil {
-				ErrorOutput(
-					err,
-					"Error backfilling IPs: "+status.Convert(err).Message(),
-					output,
-				)
+				return fmt.Errorf("backfilling IPs: %w", err)
 			}
 
-			SuccessOutput(changes, "Node IPs backfilled successfully", output)
-		}
+			if resp.StatusCode() != http.StatusOK {
+				return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+			}
+
+			return printOutput(cmd, resp.JSON200, "Node IPs backfilled successfully")
+		})
 	},
 }
 
-func nodesToPtables(
-	currentUser string,
-	nodes []*v1.Node,
-) (pterm.TableData, error) {
+func nodesToPtables(nodes []clientv1.Node) (pterm.TableData, error) {
 	tableHeader := []string{
 		"ID",
 		"Hostname",
@@ -494,103 +350,78 @@ func nodesToPtables(
 		"IP addresses",
 		"Ephemeral",
 		"Last seen",
-		"Expiration",
+		colExpiration,
 		"Connected",
 		"Expired",
 	}
-	tableData := pterm.TableData{tableHeader}
+	tableData := make(pterm.TableData, 1, 1+len(nodes))
+	tableData[0] = tableHeader
 
 	for _, node := range nodes {
-		var ephemeral bool
-		if node.GetPreAuthKey() != nil && node.GetPreAuthKey().GetEphemeral() {
-			ephemeral = true
-		}
+		// An absent pre-auth key decodes into a zero NodePreAuthKey, so guard
+		// on Id before reading its flags.
+		ephemeral := node.PreAuthKey.Id != "" && node.PreAuthKey.Ephemeral
 
-		var lastSeen time.Time
 		var lastSeenTime string
-		if node.GetLastSeen() != nil {
-			lastSeen = node.GetLastSeen().AsTime()
-			lastSeenTime = lastSeen.Format("2006-01-02 15:04:05")
+		if node.LastSeen != nil {
+			lastSeenTime = node.LastSeen.Format(HeadscaleDateTimeFormat)
 		}
 
-		var expiry time.Time
-		var expiryTime string
-		if node.GetExpiry() != nil {
-			expiry = node.GetExpiry().AsTime()
-			expiryTime = expiry.Format("2006-01-02 15:04:05")
-		} else {
-			expiryTime = "N/A"
+		expiryTime := "N/A"
+		if node.Expiry != nil {
+			expiryTime = node.Expiry.Format(HeadscaleDateTimeFormat)
 		}
 
 		var machineKey key.MachinePublic
-		err := machineKey.UnmarshalText(
-			[]byte(node.GetMachineKey()),
-		)
+
+		err := machineKey.UnmarshalText([]byte(node.MachineKey))
 		if err != nil {
 			machineKey = key.MachinePublic{}
 		}
 
 		var nodeKey key.NodePublic
-		err = nodeKey.UnmarshalText(
-			[]byte(node.GetNodeKey()),
-		)
+
+		err = nodeKey.UnmarshalText([]byte(node.NodeKey))
 		if err != nil {
 			return nil, err
 		}
 
-		var online string
-		if node.GetOnline() {
+		online := pterm.LightRed("offline")
+		if node.Online {
 			online = pterm.LightGreen("online")
-		} else {
-			online = pterm.LightRed("offline")
 		}
 
-		var expired string
-		if expiry.IsZero() || expiry.After(time.Now()) {
-			expired = pterm.LightGreen("no")
-		} else {
+		expired := pterm.LightGreen("no")
+		if node.Expiry != nil && node.Expiry.Before(time.Now()) {
 			expired = pterm.LightRed("yes")
 		}
 
-		// TODO(kradalby): as part of CLI rework, we should add the posibility to show "unusable" tags as mentioned in
-		// https://github.com/juanfont/headscale/issues/2981
-		var tagsBuilder strings.Builder
+		tags := strings.Join(node.Tags, "\n")
 
-		for _, tag := range node.GetTags() {
-			tagsBuilder.WriteString("\n" + tag)
-		}
+		var ipBuilder strings.Builder
 
-		tags := tagsBuilder.String()
+		for _, addr := range node.IpAddresses {
+			ip, err := netip.ParseAddr(addr)
+			if err == nil {
+				if ipBuilder.Len() > 0 {
+					ipBuilder.WriteString("\n")
+				}
 
-		tags = strings.TrimLeft(tags, "\n")
-
-		var user string
-		if currentUser == "" || (currentUser == node.GetUser().GetName()) {
-			user = pterm.LightMagenta(node.GetUser().GetName())
-		} else {
-			// Shared into this user
-			user = pterm.LightYellow(node.GetUser().GetName())
-		}
-
-		var IPV4Address string
-		var IPV6Address string
-		for _, addr := range node.GetIpAddresses() {
-			if netip.MustParseAddr(addr).Is4() {
-				IPV4Address = addr
-			} else {
-				IPV6Address = addr
+				ipBuilder.WriteString(ip.String())
 			}
 		}
 
+		ipAddresses := ipBuilder.String()
+
 		nodeData := []string{
-			strconv.FormatUint(node.GetId(), util.Base10),
-			node.GetName(),
-			node.GetGivenName(),
+			node.Id,
+			node.Name,
+			node.GivenName,
 			machineKey.ShortString(),
 			nodeKey.ShortString(),
-			user,
+			node.User.Name,
 			tags,
-			strings.Join([]string{IPV4Address, IPV6Address}, ", "),
+			ipAddresses,
 			strconv.FormatBool(ephemeral),
 			lastSeenTime,
 			expiryTime,
@@ -607,8 +438,8 @@ func nodesToPtables(
 }
 
 func nodeRoutesToPtables(
-	nodes []*v1.Node,
-) (pterm.TableData, error) {
+	nodes []clientv1.Node,
+) pterm.TableData {
 	tableHeader := []string{
 		"ID",
 		"Hostname",
@@ -616,15 +447,16 @@ func nodeRoutesToPtables(
 		"Available",
 		"Serving (Primary)",
 	}
-	tableData := pterm.TableData{tableHeader}
+	tableData := make(pterm.TableData, 1, 1+len(nodes))
+	tableData[0] = tableHeader
 
 	for _, node := range nodes {
 		nodeData := []string{
-			strconv.FormatUint(node.GetId(), util.Base10),
-			node.GetGivenName(),
-			strings.Join(node.GetApprovedRoutes(), "\n"),
-			strings.Join(node.GetAvailableRoutes(), "\n"),
-			strings.Join(node.GetSubnetRoutes(), "\n"),
+			node.Id,
+			node.GivenName,
+			strings.Join(node.ApprovedRoutes, "\n"),
+			strings.Join(node.AvailableRoutes, "\n"),
+			strings.Join(node.SubnetRoutes, "\n"),
 		}
 		tableData = append(
 			tableData,
@@ -632,108 +464,50 @@ func nodeRoutesToPtables(
 		)
 	}
 
-	return tableData, nil
+	return tableData
 }
 
 var tagCmd = &cobra.Command{
 	Use:     "tag",
 	Short:   "Manage the tags of a node",
 	Aliases: []string{"tags", "t"},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		identifier, _ := cmd.Flags().GetUint64("identifier")
+		tagsToSet, _ := cmd.Flags().GetStringSlice("tags")
 
-		// retrieve flags from CLI
-		identifier, err := cmd.Flags().GetUint64("identifier")
+		resp, err := client.SetTagsWithResponse(ctx, strconv.FormatUint(identifier, util.Base10), clientv1.SetTagsJSONRequestBody{
+			Tags: &tagsToSet,
+		})
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error converting ID to integer: %s", err),
-				output,
-			)
-		}
-		tagsToSet, err := cmd.Flags().GetStringSlice("tags")
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error retrieving list of tags to add to node, %v", err),
-				output,
-			)
+			return fmt.Errorf("setting tags: %w", err)
 		}
 
-		// Sending tags to node
-		request := &v1.SetTagsRequest{
-			NodeId: identifier,
-			Tags:   tagsToSet,
-		}
-		resp, err := client.SetTags(ctx, request)
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error while sending tags to headscale: %s", err),
-				output,
-			)
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
 		}
 
-		if resp != nil {
-			SuccessOutput(
-				resp.GetNode(),
-				"Node updated",
-				output,
-			)
-		}
-	},
+		return printOutput(cmd, resp.JSON200.Node, "Node updated")
+	}),
 }
 
 var approveRoutesCmd = &cobra.Command{
 	Use:   "approve-routes",
 	Short: "Manage the approved routes of a node",
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		identifier, _ := cmd.Flags().GetUint64("identifier")
+		routes, _ := cmd.Flags().GetStringSlice("routes")
 
-		// retrieve flags from CLI
-		identifier, err := cmd.Flags().GetUint64("identifier")
+		resp, err := client.SetApprovedRoutesWithResponse(ctx, strconv.FormatUint(identifier, util.Base10), clientv1.SetApprovedRoutesJSONRequestBody{
+			Routes: &routes,
+		})
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error converting ID to integer: %s", err),
-				output,
-			)
-		}
-		routes, err := cmd.Flags().GetStringSlice("routes")
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error retrieving list of routes to add to node, %v", err),
-				output,
-			)
+			return fmt.Errorf("setting approved routes: %w", err)
 		}
 
-		// Sending routes to node
-		request := &v1.SetApprovedRoutesRequest{
-			NodeId: identifier,
-			Routes: routes,
-		}
-		resp, err := client.SetApprovedRoutes(ctx, request)
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error while sending routes to headscale: %s", err),
-				output,
-			)
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
 		}
 
-		if resp != nil {
-			SuccessOutput(
-				resp.GetNode(),
-				"Node updated",
-				output,
-			)
-		}
-	},
+		return printOutput(cmd, resp.JSON200.Node, "Node updated")
+	}),
 }

cmd/headscale/cli/oauth_client.go

@@ -0,0 +1,271 @@
+package cli
+
+import (
+	"context"
+	"crypto/tls"
+	"encoding/json"
+	"fmt"
+	"net"
+	"net/http"
+	"strings"
+
+	clientv2 "github.com/juanfont/headscale/gen/client/v2"
+	"github.com/juanfont/headscale/hscontrol/types"
+	"github.com/spf13/cobra"
+)
+
+// oauthTailnet is the single Headscale tailnet the v2 API addresses as "-".
+const oauthTailnet = "-"
+
+func init() {
+	rootCmd.AddCommand(oauthClientsCmd)
+
+	oauthClientsCmd.AddCommand(listOAuthClientsCmd)
+
+	createOAuthClientCmd.Flags().
+		StringArrayP("scope", "s", nil, "Scope the client's tokens are granted (repeatable): auth_keys, oauth_keys, devices:core, devices:routes, policy_file, feature_settings (each with a :read variant), or all/all:read")
+	createOAuthClientCmd.Flags().
+		StringArrayP("tag", "t", nil, "Tag the client's tokens may assign to devices (repeatable), e.g. tag:k8s-operator")
+	createOAuthClientCmd.Flags().StringP("description", "d", "", "Human-readable description")
+	oauthClientsCmd.AddCommand(createOAuthClientCmd)
+
+	deleteOAuthClientCmd.Flags().StringP("id", "i", "", "OAuth client id")
+	oauthClientsCmd.AddCommand(deleteOAuthClientCmd)
+}
+
+var oauthClientsCmd = &cobra.Command{
+	Use:     "oauth-clients",
+	Short:   "Manage OAuth clients",
+	Aliases: []string{"oauth-client", "oauthclients", "oauthclient", "oauth"},
+}
+
+var createOAuthClientCmd = &cobra.Command{
+	Use:   "create",
+	Short: "Create an OAuth client",
+	Long: `Create a general-purpose OAuth client. It authenticates with the OAuth 2.0
+client-credentials grant and mints short-lived, scope-limited access tokens.
+The wire format is compatible with Tailscale tooling (the Terraform provider,
+the Kubernetes operator, tscli, ...), so those can drive Headscale unchanged.
+
+The client secret is shown ONCE on creation and cannot be retrieved again; if
+you lose it, delete the client and create a new one.
+
+Scopes gate what the client's tokens may do; tags are the device tags those
+tokens may assign and are required when the scopes include devices:core or
+auth_keys.`,
+	Aliases: []string{"c", cmdNew},
+	RunE: func(cmd *cobra.Command, _ []string) error {
+		scopes, _ := cmd.Flags().GetStringArray("scope")
+		tags, _ := cmd.Flags().GetStringArray("tag")
+		description, _ := cmd.Flags().GetString("description")
+
+		if len(scopes) == 0 {
+			return fmt.Errorf("at least one --scope is required: %w", errMissingParameter)
+		}
+
+		ctx, client, cancel, err := newV2Client()
+		if err != nil {
+			return err
+		}
+		defer cancel()
+
+		keyType := "client"
+
+		resp, err := client.CreateKeyWithResponse(ctx, oauthTailnet, clientv2.CreateKeyRequest{
+			KeyType:     &keyType,
+			Scopes:      &scopes,
+			Tags:        &tags,
+			Description: &description,
+		})
+		if err != nil {
+			return fmt.Errorf("creating oauth client: %w", err)
+		}
+
+		err = v2Error(resp.HTTPResponse.StatusCode, resp.Body)
+		if err != nil {
+			return err
+		}
+
+		key := resp.JSON200
+
+		return printOutput(cmd, key,
+			fmt.Sprintf("OAuth client %s created.\nSecret (shown once, store it now): %s", key.Id, ptrStr(key.Key)))
+	},
+}
+
+var listOAuthClientsCmd = &cobra.Command{
+	Use:     cmdList,
+	Short:   "List OAuth clients",
+	Aliases: []string{"ls", cmdShow},
+	RunE: func(cmd *cobra.Command, _ []string) error {
+		ctx, client, cancel, err := newV2Client()
+		if err != nil {
+			return err
+		}
+		defer cancel()
+
+		resp, err := client.ListKeysWithResponse(ctx, oauthTailnet, nil)
+		if err != nil {
+			return fmt.Errorf("listing oauth clients: %w", err)
+		}
+
+		err = v2Error(resp.HTTPResponse.StatusCode, resp.Body)
+		if err != nil {
+			return err
+		}
+
+		// The keys endpoint is multiplexed; keep only OAuth clients.
+		clients := make([]clientv2.Key, 0, len(resp.JSON200.Keys))
+
+		for _, k := range resp.JSON200.Keys {
+			if k.KeyType == "client" {
+				clients = append(clients, k)
+			}
+		}
+
+		return printListOutput(cmd, clients, func() error {
+			rows := make([][]string, 0, len(clients))
+			for _, c := range clients {
+				rows = append(rows, []string{
+					c.Id,
+					strings.Join(ptrStrs(c.Scopes), ","),
+					strings.Join(ptrStrs(c.Tags), ","),
+					ptrStr(c.Description),
+					c.Created.Format(HeadscaleDateTimeFormat),
+				})
+			}
+
+			return renderTable([]string{"ID", "Scopes", "Tags", "Description", colCreated}, rows)
+		})
+	},
+}
+
+var deleteOAuthClientCmd = &cobra.Command{
+	Use:     cmdDelete,
+	Short:   "Delete an OAuth client",
+	Aliases: []string{"remove", aliasDel},
+	RunE: func(cmd *cobra.Command, _ []string) error {
+		id, _ := cmd.Flags().GetString("id")
+		if id == "" {
+			return fmt.Errorf("--id is required: %w", errMissingParameter)
+		}
+
+		ctx, client, cancel, err := newV2Client()
+		if err != nil {
+			return err
+		}
+		defer cancel()
+
+		resp, err := client.DeleteKeyWithResponse(ctx, oauthTailnet, id)
+		if err != nil {
+			return fmt.Errorf("deleting oauth client: %w", err)
+		}
+
+		err = v2Error(resp.HTTPResponse.StatusCode, resp.Body)
+		if err != nil {
+			return err
+		}
+
+		return printOutput(cmd, map[string]string{"id": id}, "OAuth client "+id+" deleted")
+	},
+}
+
+// newV2Client builds a generated v2 API client, selecting the transport the same
+// way the v1 client does: over the local unix socket it is unauthenticated
+// (local trust); a remote address injects the configured API key as a bearer
+// token.
+func newV2Client() (context.Context, *clientv2.ClientWithResponses, context.CancelFunc, error) {
+	cfg, err := types.LoadCLIConfig()
+	if err != nil {
+		return nil, nil, nil, fmt.Errorf("loading configuration: %w", err)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), cfg.CLI.Timeout)
+
+	if cfg.CLI.Address == "" {
+		socketPath := cfg.UnixSocket
+
+		httpClient := &http.Client{Transport: &http.Transport{
+			DialContext: func(ctx context.Context, _, _ string) (net.Conn, error) {
+				return dialHeadscaleSocket(ctx, socketPath)
+			},
+		}}
+
+		client, err := clientv2.NewClientWithResponses("http://local", clientv2.WithHTTPClient(httpClient))
+		if err != nil {
+			cancel()
+
+			return nil, nil, nil, err
+		}
+
+		return ctx, client, cancel, nil
+	}
+
+	if cfg.CLI.APIKey == "" {
+		cancel()
+
+		return nil, nil, nil, errAPIKeyNotSet
+	}
+
+	transport := &http.Transport{}
+	if cfg.CLI.Insecure {
+		//nolint:gosec // intentionally honouring the insecure flag
+		transport.TLSClientConfig = &tls.Config{InsecureSkipVerify: true}
+	}
+
+	apiKey := cfg.CLI.APIKey
+
+	client, err := clientv2.NewClientWithResponses(
+		clientBaseURL(cfg.CLI.Address),
+		clientv2.WithHTTPClient(&http.Client{Transport: transport}),
+		clientv2.WithRequestEditorFn(func(_ context.Context, req *http.Request) error {
+			req.Header.Set("Authorization", "Bearer "+apiKey)
+
+			return nil
+		}),
+	)
+	if err != nil {
+		cancel()
+
+		return nil, nil, nil, err
+	}
+
+	return ctx, client, cancel, nil
+}
+
+// v2Error turns a non-2xx v2 response into an error. The v2 API emits the
+// Tailscale error body ({"message":...}) rather than RFC 7807, so it reads the
+// "message" field instead of the generated problem+json types.
+func v2Error(status int, body []byte) error {
+	if status >= http.StatusOK && status < http.StatusMultipleChoices {
+		return nil
+	}
+
+	var e struct {
+		Message string `json:"message"`
+	}
+
+	if json.Unmarshal(body, &e) == nil && e.Message != "" {
+		//nolint:err113 // surfacing the server's message
+		return fmt.Errorf("api error (%d): %s", status, e.Message)
+	}
+
+	//nolint:err113 // surfacing the server's body
+	return fmt.Errorf("api error (%d): %s", status, strings.TrimSpace(string(body)))
+}
+
+func ptrStr(s *string) string {
+	if s == nil {
+		return ""
+	}
+
+	return *s
+}
+
+func ptrStrs(s *[]string) []string {
+	if s == nil {
+		return nil
+	}
+
+	return *s
+}

cmd/headscale/cli/policy.go

@@ -1,41 +1,66 @@
 package cli
 
 import (
+	"context"
+	"errors"
 	"fmt"
-	"io"
+	"net/http"
 	"os"
 
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	clientv1 "github.com/juanfont/headscale/gen/client/v1"
 	"github.com/juanfont/headscale/hscontrol/db"
 	"github.com/juanfont/headscale/hscontrol/policy"
 	"github.com/juanfont/headscale/hscontrol/types"
-	"github.com/juanfont/headscale/hscontrol/util"
-	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
 	"tailscale.com/types/views"
 )
 
 const (
-	bypassFlag = "bypass-grpc-and-access-database-directly"
+	bypassFlag = "bypass-server-and-access-database-directly" //nolint:gosec // not a credential
 )
 
+var errAborted = errors.New("command aborted by user")
+
+// bypassDatabase opens the database directly, bypassing the running server.
+// The caller must close the returned handle.
+func bypassDatabase() (*db.HSDatabase, error) {
+	cfg, err := types.LoadServerConfig()
+	if err != nil {
+		return nil, fmt.Errorf("loading config: %w", err)
+	}
+
+	d, err := db.NewHeadscaleDatabase(cfg)
+	if err != nil {
+		return nil, fmt.Errorf("opening database: %w", err)
+	}
+
+	return d, nil
+}
+
+// openBypassDB confirms the destructive bypass action and opens the database
+// directly. The caller is responsible for closing the returned handle.
+func openBypassDB(cmd *cobra.Command) (*db.HSDatabase, error) {
+	if !confirmAction(cmd, "DO NOT run this command if an instance of headscale is running, are you sure headscale is not running?") {
+		return nil, errAborted
+	}
+
+	return bypassDatabase()
+}
+
 func init() {
 	rootCmd.AddCommand(policyCmd)
 
-	getPolicy.Flags().BoolP(bypassFlag, "", false, "Uses the headscale config to directly access the database, bypassing gRPC and does not require the server to be running")
+	getPolicy.Flags().BoolP(bypassFlag, "", false, "Uses the headscale config to directly access the database, bypassing the API and does not require the server to be running")
 	policyCmd.AddCommand(getPolicy)
 
 	setPolicy.Flags().StringP("file", "f", "", "Path to a policy file in HuJSON format")
-	if err := setPolicy.MarkFlagRequired("file"); err != nil {
-		log.Fatal().Err(err).Msg("")
-	}
-	setPolicy.Flags().BoolP(bypassFlag, "", false, "Uses the headscale config to directly access the database, bypassing gRPC and does not require the server to be running")
+	setPolicy.Flags().BoolP(bypassFlag, "", false, "Uses the headscale config to directly access the database, bypassing the API and does not require the server to be running")
+	mustMarkRequired(setPolicy, "file")
 	policyCmd.AddCommand(setPolicy)
 
 	checkPolicy.Flags().StringP("file", "f", "", "Path to a policy file in HuJSON format")
-	if err := checkPolicy.MarkFlagRequired("file"); err != nil {
-		log.Fatal().Err(err).Msg("")
-	}
+	checkPolicy.Flags().BoolP(bypassFlag, "", false, "Open the database directly (no running server required) to resolve user references and to evaluate the policy's tests and sshTests blocks. Required when those checks are needed.")
+	mustMarkRequired(checkPolicy, "file")
 	policyCmd.AddCommand(checkPolicy)
 }
 
@@ -47,60 +72,48 @@ var policyCmd = &cobra.Command{
 var getPolicy = &cobra.Command{
 	Use:     "get",
 	Short:   "Print the current ACL Policy",
-	Aliases: []string{"show", "view", "fetch"},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-		var policy string
+	Aliases: []string{cmdShow, "view", "fetch"},
+	RunE: func(cmd *cobra.Command, args []string) error {
+		var policyData string
+
 		if bypass, _ := cmd.Flags().GetBool(bypassFlag); bypass {
-			confirm := false
-			force, _ := cmd.Flags().GetBool("force")
-			if !force {
-				confirm = util.YesNo("DO NOT run this command if an instance of headscale is running, are you sure headscale is not running?")
-			}
-
-			if !confirm && !force {
-				ErrorOutput(nil, "Aborting command", output)
-				return
-			}
-
-			cfg, err := types.LoadServerConfig()
+			d, err := openBypassDB(cmd)
 			if err != nil {
-				ErrorOutput(err, fmt.Sprintf("Failed loading config: %s", err), output)
-			}
-
-			d, err := db.NewHeadscaleDatabase(
-				cfg,
-				nil,
-			)
-			if err != nil {
-				ErrorOutput(err, fmt.Sprintf("Failed to open database: %s", err), output)
+				return err
 			}
+			defer d.Close()
 
 			pol, err := d.GetPolicy()
 			if err != nil {
-				ErrorOutput(err, fmt.Sprintf("Failed loading Policy from database: %s", err), output)
+				return fmt.Errorf("loading policy from database: %w", err)
 			}
 
-			policy = pol.Data
+			policyData = pol.Data
 		} else {
-			ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-			defer cancel()
-			defer conn.Close()
+			err := withClient(func(ctx context.Context, client *clientv1.ClientWithResponses) error {
+				resp, err := client.GetPolicyWithResponse(ctx)
+				if err != nil {
+					return fmt.Errorf("loading ACL policy: %w", err)
+				}
 
-			request := &v1.GetPolicyRequest{}
+				if resp.StatusCode() != http.StatusOK {
+					return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+				}
 
-			response, err := client.GetPolicy(ctx, request)
+				policyData = resp.JSON200.Policy
+
+				return nil
+			})
 			if err != nil {
-				ErrorOutput(err, fmt.Sprintf("Failed loading ACL Policy: %s", err), output)
+				return err
 			}
-
-			policy = response.GetPolicy()
 		}
 
-		// TODO(pallabpain): Maybe print this better?
-		// This does not pass output as we dont support yaml, json or json-line
-		// output for this command. It is HuJSON already.
-		SuccessOutput("", policy, "")
+		// This does not pass output format as we don't support yaml, json or
+		// json-line output for this command. It is HuJSON already.
+		fmt.Println(policyData)
+
+		return nil
 	},
 }
 
@@ -111,100 +124,137 @@ var setPolicy = &cobra.Command{
 	Updates the existing ACL Policy with the provided policy. The policy must be a valid HuJSON object.
 	This command only works when the acl.policy_mode is set to "db", and the policy will be stored in the database.`,
 	Aliases: []string{"put", "update"},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
+	RunE: func(cmd *cobra.Command, args []string) error {
 		policyPath, _ := cmd.Flags().GetString("file")
 
-		f, err := os.Open(policyPath)
+		policyBytes, err := os.ReadFile(policyPath)
 		if err != nil {
-			ErrorOutput(err, fmt.Sprintf("Error opening the policy file: %s", err), output)
-		}
-		defer f.Close()
-
-		policyBytes, err := io.ReadAll(f)
-		if err != nil {
-			ErrorOutput(err, fmt.Sprintf("Error reading the policy file: %s", err), output)
+			return fmt.Errorf("reading policy file: %w", err)
 		}
 
 		if bypass, _ := cmd.Flags().GetBool(bypassFlag); bypass {
-			confirm := false
-			force, _ := cmd.Flags().GetBool("force")
-			if !force {
-				confirm = util.YesNo("DO NOT run this command if an instance of headscale is running, are you sure headscale is not running?")
-			}
-
-			if !confirm && !force {
-				ErrorOutput(nil, "Aborting command", output)
-				return
-			}
-
-			cfg, err := types.LoadServerConfig()
+			d, err := openBypassDB(cmd)
 			if err != nil {
-				ErrorOutput(err, fmt.Sprintf("Failed loading config: %s", err), output)
+				return err
 			}
+			defer d.Close()
 
-			d, err := db.NewHeadscaleDatabase(
-				cfg,
-				nil,
-			)
+			users, err := d.ListUsers(nil)
 			if err != nil {
-				ErrorOutput(err, fmt.Sprintf("Failed to open database: %s", err), output)
-			}
-
-			users, err := d.ListUsers()
-			if err != nil {
-				ErrorOutput(err, fmt.Sprintf("Failed to load users for policy validation: %s", err), output)
+				return fmt.Errorf("loading users for policy validation: %w", err)
 			}
 
 			_, err = policy.NewPolicyManager(policyBytes, users, views.Slice[types.NodeView]{})
 			if err != nil {
-				ErrorOutput(err, fmt.Sprintf("Error parsing the policy file: %s", err), output)
-				return
+				return fmt.Errorf("parsing policy file: %w", err)
 			}
 
 			_, err = d.SetPolicy(string(policyBytes))
 			if err != nil {
-				ErrorOutput(err, fmt.Sprintf("Failed to set ACL Policy: %s", err), output)
+				return fmt.Errorf("setting ACL policy: %w", err)
 			}
 		} else {
-			request := &v1.SetPolicyRequest{Policy: string(policyBytes)}
+			policyStr := string(policyBytes)
 
-			ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-			defer cancel()
-			defer conn.Close()
+			err := withClient(func(ctx context.Context, client *clientv1.ClientWithResponses) error {
+				resp, err := client.SetPolicyWithResponse(ctx, clientv1.SetPolicyJSONRequestBody{
+					Policy: &policyStr,
+				})
+				if err != nil {
+					return fmt.Errorf("setting ACL policy: %w", err)
+				}
 
-			if _, err := client.SetPolicy(ctx, request); err != nil {
-				ErrorOutput(err, fmt.Sprintf("Failed to set ACL Policy: %s", err), output)
+				if resp.StatusCode() != http.StatusOK {
+					return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+				}
+
+				return nil
+			})
+			if err != nil {
+				return err
 			}
 		}
 
-		SuccessOutput(nil, "Policy updated.", "")
+		fmt.Println("Policy updated.")
+
+		return nil
 	},
 }
 
 var checkPolicy = &cobra.Command{
 	Use:   "check",
 	Short: "Check the Policy file for errors",
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
+	Long: `
+	Check validates the policy against the server's live users and nodes,
+	running any "tests" or "sshTests" block. By default the command calls a
+	running headscale over its API; pass --` + bypassFlag + ` to
+	open the database directly when headscale is not running.`,
+	RunE: func(cmd *cobra.Command, args []string) error {
 		policyPath, _ := cmd.Flags().GetString("file")
 
-		f, err := os.Open(policyPath)
+		policyBytes, err := os.ReadFile(policyPath)
 		if err != nil {
-			ErrorOutput(err, fmt.Sprintf("Error opening the policy file: %s", err), output)
-		}
-		defer f.Close()
-
-		policyBytes, err := io.ReadAll(f)
-		if err != nil {
-			ErrorOutput(err, fmt.Sprintf("Error reading the policy file: %s", err), output)
+			return fmt.Errorf("reading policy file: %w", err)
 		}
 
-		_, err = policy.NewPolicyManager(policyBytes, nil, views.Slice[types.NodeView]{})
-		if err != nil {
-			ErrorOutput(err, fmt.Sprintf("Error parsing the policy file: %s", err), output)
+		if bypass, _ := cmd.Flags().GetBool(bypassFlag); bypass {
+			d, err := openBypassDB(cmd)
+			if err != nil {
+				return err
+			}
+			defer d.Close()
+
+			users, err := d.ListUsers(nil)
+			if err != nil {
+				return fmt.Errorf("loading users: %w", err)
+			}
+
+			nodes, err := d.ListNodes()
+			if err != nil {
+				return fmt.Errorf("loading nodes: %w", err)
+			}
+
+			// [policy.NewPolicyManager] validates structure and user references
+			// but intentionally skips test evaluation (boot path).
+			// [policy.PolicyManager.SetPolicy] is the user-write boundary and is what runs the
+			// tests and sshTests blocks.
+			pm, err := policy.NewPolicyManager(policyBytes, users, nodes.ViewSlice())
+			if err != nil {
+				return fmt.Errorf("parsing policy file: %w", err)
+			}
+
+			_, err = pm.SetPolicy(policyBytes)
+			if err != nil {
+				return err
+			}
+
+			fmt.Println("Policy is valid")
+
+			return nil
 		}
 
-		SuccessOutput(nil, "Policy is valid", "")
+		policyStr := string(policyBytes)
+
+		err = withClient(func(ctx context.Context, client *clientv1.ClientWithResponses) error {
+			resp, err := client.CheckPolicyWithResponse(ctx, clientv1.CheckPolicyJSONRequestBody{
+				Policy: &policyStr,
+			})
+			if err != nil {
+				return err
+			}
+
+			if resp.StatusCode() != http.StatusOK {
+				return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+			}
+
+			return nil
+		})
+		if err != nil {
+			return err
+		}
+
+		fmt.Println("Policy is valid")
+
+		return nil
 	},
 }

cmd/headscale/cli/preauthkeys.go

@@ -1,16 +1,15 @@
 package cli
 
 import (
+	"context"
 	"fmt"
+	"net/http"
 	"strconv"
 	"strings"
-	"time"
 
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
-	"github.com/prometheus/common/model"
-	"github.com/pterm/pterm"
+	clientv1 "github.com/juanfont/headscale/gen/client/v1"
+	"github.com/juanfont/headscale/hscontrol/util"
 	"github.com/spf13/cobra"
-	"google.golang.org/protobuf/types/known/timestamppb"
 )
 
 const (
@@ -43,206 +42,161 @@ var preauthkeysCmd = &cobra.Command{
 }
 
 var listPreAuthKeys = &cobra.Command{
-	Use:     "list",
+	Use:     cmdList,
 	Short:   "List all preauthkeys",
-	Aliases: []string{"ls", "show"},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
-
-		response, err := client.ListPreAuthKeys(ctx, &v1.ListPreAuthKeysRequest{})
+	Aliases: []string{"ls", cmdShow},
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		resp, err := client.ListPreAuthKeysWithResponse(ctx)
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error getting the list of keys: %s", err),
-				output,
-			)
-
-			return
+			return fmt.Errorf("listing preauthkeys: %w", err)
 		}
 
-		if output != "" {
-			SuccessOutput(response.GetPreAuthKeys(), "", output)
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
 		}
 
-		tableData := pterm.TableData{
-			{
+		preAuthKeys := resp.JSON200.PreAuthKeys
+
+		return printListOutput(cmd, preAuthKeys, func() error {
+			rows := make([][]string, 0, len(preAuthKeys))
+			for _, key := range preAuthKeys {
+				expiration := ColourTime(key.Expiration)
+
+				owner := "-"
+
+				switch {
+				case len(key.AclTags) > 0:
+					owner = strings.Join(key.AclTags, "\n")
+				case key.User.Id != "":
+					owner = key.User.Name
+				}
+
+				rows = append(rows, []string{
+					key.Id,
+					key.Key,
+					strconv.FormatBool(key.Reusable),
+					strconv.FormatBool(key.Ephemeral),
+					strconv.FormatBool(key.Used),
+					expiration,
+					key.CreatedAt.Format(HeadscaleDateTimeFormat),
+					owner,
+				})
+			}
+
+			return renderTable([]string{
 				"ID",
 				"Key/Prefix",
 				"Reusable",
 				"Ephemeral",
 				"Used",
-				"Expiration",
-				"Created",
+				colExpiration,
+				colCreated,
 				"Owner",
-			},
-		}
-		for _, key := range response.GetPreAuthKeys() {
-			expiration := "-"
-			if key.GetExpiration() != nil {
-				expiration = ColourTime(key.GetExpiration().AsTime())
-			}
-
-			var owner string
-			if len(key.GetAclTags()) > 0 {
-				owner = strings.Join(key.GetAclTags(), "\n")
-			} else if key.GetUser() != nil {
-				owner = key.GetUser().GetName()
-			} else {
-				owner = "-"
-			}
-
-			tableData = append(tableData, []string{
-				strconv.FormatUint(key.GetId(), 10),
-				key.GetKey(),
-				strconv.FormatBool(key.GetReusable()),
-				strconv.FormatBool(key.GetEphemeral()),
-				strconv.FormatBool(key.GetUsed()),
-				expiration,
-				key.GetCreatedAt().AsTime().Format("2006-01-02 15:04:05"),
-				owner,
-			})
-
-		}
-		err = pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Failed to render pterm table: %s", err),
-				output,
-			)
-		}
-	},
+			}, rows)
+		})
+	}),
 }
 
 var createPreAuthKeyCmd = &cobra.Command{
 	Use:     "create",
 	Short:   "Creates a new preauthkey",
-	Aliases: []string{"c", "new"},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
+	Aliases: []string{"c", cmdNew},
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
 		user, _ := cmd.Flags().GetUint64("user")
 		reusable, _ := cmd.Flags().GetBool("reusable")
 		ephemeral, _ := cmd.Flags().GetBool("ephemeral")
 		tags, _ := cmd.Flags().GetStringSlice("tags")
 
-		request := &v1.CreatePreAuthKeyRequest{
-			User:      user,
-			Reusable:  reusable,
-			Ephemeral: ephemeral,
-			AclTags:   tags,
-		}
-
-		durationStr, _ := cmd.Flags().GetString("expiration")
-
-		duration, err := model.ParseDuration(durationStr)
+		expiryTime, err := expirationFromFlag(cmd)
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Could not parse duration: %s\n", err),
-				output,
-			)
+			return err
 		}
 
-		expiration := time.Now().UTC().Add(time.Duration(duration))
+		userStr := strconv.FormatUint(user, util.Base10)
 
-		request.Expiration = timestamppb.New(expiration)
+		request := clientv1.CreatePreAuthKeyJSONRequestBody{
+			User:       &userStr,
+			Reusable:   &reusable,
+			Ephemeral:  &ephemeral,
+			AclTags:    &tags,
+			Expiration: &expiryTime,
+		}
 
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
-
-		response, err := client.CreatePreAuthKey(ctx, request)
+		resp, err := client.CreatePreAuthKeyWithResponse(ctx, request)
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Cannot create Pre Auth Key: %s\n", err),
-				output,
-			)
+			return fmt.Errorf("creating preauthkey: %w", err)
 		}
 
-		SuccessOutput(response.GetPreAuthKey(), response.GetPreAuthKey().GetKey(), output)
-	},
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		preAuthKey := resp.JSON200.PreAuthKey
+
+		return printOutput(cmd, preAuthKey, preAuthKey.Key)
+	}),
+}
+
+// preAuthKeyID reads the required --id flag for preauthkey commands.
+func preAuthKeyID(cmd *cobra.Command) (uint64, error) {
+	id, _ := cmd.Flags().GetUint64("id")
+	if id == 0 {
+		return 0, fmt.Errorf("missing --id parameter: %w", errMissingParameter)
+	}
+
+	return id, nil
 }
 
 var expirePreAuthKeyCmd = &cobra.Command{
-	Use:     "expire",
+	Use:     cmdExpire,
 	Short:   "Expire a preauthkey",
-	Aliases: []string{"revoke", "exp", "e"},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-		id, _ := cmd.Flags().GetUint64("id")
-
-		if id == 0 {
-			ErrorOutput(
-				errMissingParameter,
-				"Error: missing --id parameter",
-				output,
-			)
-
-			return
-		}
-
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
-
-		request := &v1.ExpirePreAuthKeyRequest{
-			Id: id,
-		}
-
-		response, err := client.ExpirePreAuthKey(ctx, request)
+	Aliases: []string{"revoke", aliasExp, "e"},
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		id, err := preAuthKeyID(cmd)
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Cannot expire Pre Auth Key: %s\n", err),
-				output,
-			)
+			return err
 		}
 
-		SuccessOutput(response, "Key expired", output)
-	},
+		idStr := strconv.FormatUint(id, util.Base10)
+
+		resp, err := client.ExpirePreAuthKeyWithResponse(ctx, clientv1.ExpirePreAuthKeyJSONRequestBody{
+			Id: &idStr,
+		})
+		if err != nil {
+			return fmt.Errorf("expiring preauthkey: %w", err)
+		}
+
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200, "Key expired")
+	}),
 }
 
 var deletePreAuthKeyCmd = &cobra.Command{
-	Use:     "delete",
+	Use:     cmdDelete,
 	Short:   "Delete a preauthkey",
-	Aliases: []string{"del", "rm", "d"},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-		id, _ := cmd.Flags().GetUint64("id")
-
-		if id == 0 {
-			ErrorOutput(
-				errMissingParameter,
-				"Error: missing --id parameter",
-				output,
-			)
-
-			return
-		}
-
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
-
-		request := &v1.DeletePreAuthKeyRequest{
-			Id: id,
-		}
-
-		response, err := client.DeletePreAuthKey(ctx, request)
+	Aliases: []string{aliasDel, "rm", "d"},
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		id, err := preAuthKeyID(cmd)
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Cannot delete Pre Auth Key: %s\n", err),
-				output,
-			)
+			return err
 		}
 
-		SuccessOutput(response, "Key deleted", output)
-	},
+		idStr := strconv.FormatUint(id, util.Base10)
+
+		resp, err := client.DeletePreAuthKeyWithResponse(ctx, &clientv1.DeletePreAuthKeyParams{
+			Id: &idStr,
+		})
+		if err != nil {
+			return fmt.Errorf("deleting preauthkey: %w", err)
+		}
+
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200, "Key deleted")
+	}),
 }

cmd/headscale/cli/pterm_style.go

@@ -7,7 +7,7 @@ import (
 )
 
 func ColourTime(date time.Time) string {
-	dateStr := date.Format("2006-01-02 15:04:05")
+	dateStr := date.Format(HeadscaleDateTimeFormat)
 
 	if date.After(time.Now()) {
 		dateStr = pterm.LightGreen(dateStr)

cmd/headscale/cli/root.go

@@ -1,7 +1,6 @@
 package cli
 
 import (
-	"fmt"
 	"os"
 	"runtime"
 	"slices"
@@ -15,10 +14,6 @@ import (
 	"github.com/tcnksm/go-latest"
 )
 
-const (
-	deprecateNamespaceMessage = "use --user"
-)
-
 var cfgFile string = ""
 
 func init() {
@@ -27,11 +22,6 @@ func init() {
 		return
 	}
 
-	if slices.Contains(os.Args, "policy") && slices.Contains(os.Args, "check") {
-		zerolog.SetGlobalLevel(zerolog.Disabled)
-		return
-	}
-
 	cobra.OnInitialize(initConfig)
 	rootCmd.PersistentFlags().
 		StringVarP(&cfgFile, "config", "c", "", "config file (default is /etc/headscale/config.yaml)")
@@ -39,25 +29,34 @@ func init() {
 		StringP("output", "o", "", "Output format. Empty for human-readable, 'json', 'json-line' or 'yaml'")
 	rootCmd.PersistentFlags().
 		Bool("force", false, "Disable prompts and forces the execution")
+
+	// Re-enable usage output only for flag-parsing errors; runtime errors
+	// from [cobra.Command.RunE] should never dump usage text.
+	rootCmd.SetFlagErrorFunc(func(cmd *cobra.Command, err error) error {
+		cmd.SilenceUsage = false
+
+		return err
+	})
 }
 
 func initConfig() {
 	if cfgFile == "" {
 		cfgFile = os.Getenv("HEADSCALE_CONFIG")
 	}
+
 	if cfgFile != "" {
 		err := types.LoadConfig(cfgFile, true)
 		if err != nil {
-			log.Fatal().Caller().Err(err).Msgf("Error loading config file %s", cfgFile)
+			log.Fatal().Caller().Err(err).Msgf("error loading config file %s", cfgFile)
 		}
 	} else {
 		err := types.LoadConfig("", false)
 		if err != nil {
-			log.Fatal().Caller().Err(err).Msgf("Error loading config")
+			log.Fatal().Caller().Err(err).Msgf("error loading config")
 		}
 	}
 
-	machineOutput := HasMachineOutputFlag()
+	machineOutput := hasMachineOutputFlag()
 
 	// If the user has requested a "node" readable format,
 	// then disable login so the output remains valid.
@@ -80,6 +79,7 @@ func initConfig() {
 				Repository:    "headscale",
 				TagFilterFunc: filterPreReleasesIfStable(func() string { return versionInfo.Version }),
 			}
+
 			res, err := latest.Check(githubTag, versionInfo.Version)
 			if err == nil && res.Outdated {
 				//nolint
@@ -96,12 +96,9 @@ func initConfig() {
 var prereleases = []string{"alpha", "beta", "rc", "dev"}
 
 func isPreReleaseVersion(version string) bool {
-	for _, unstable := range prereleases {
-		if strings.Contains(version, unstable) {
-			return true
-		}
-	}
-	return false
+	return slices.ContainsFunc(prereleases, func(unstable string) bool {
+		return strings.Contains(version, unstable)
+	})
 }
 
 // filterPreReleasesIfStable returns a function that filters out
@@ -120,13 +117,7 @@ func filterPreReleasesIfStable(versionFunc func() string) func(string) bool {
 		}
 
 		// If we are on a stable release, filter out pre-releases.
-		for _, ignore := range prereleases {
-			if strings.Contains(tag, ignore) {
-				return true
-			}
-		}
-
-		return false
+		return isPreReleaseVersion(tag)
 	}
 }
 
@@ -137,11 +128,15 @@ var rootCmd = &cobra.Command{
 headscale is an open source implementation of the Tailscale control server
 
 https://github.com/juanfont/headscale`,
+	SilenceErrors: true,
+	SilenceUsage:  true,
 }
 
 func Execute() {
-	if err := rootCmd.Execute(); err != nil {
-		fmt.Fprintln(os.Stderr, err)
+	cmd, err := rootCmd.ExecuteC()
+	if err != nil {
+		outputFormat, _ := cmd.Flags().GetString("output")
+		printError(err, outputFormat)
 		os.Exit(1)
 	}
 }

cmd/headscale/cli/root_test.go

@@ -4,6 +4,19 @@ import (
 	"testing"
 )
 
+const (
+	v23       = "0.23.0"
+	v23Alpha1 = "0.23.0-alpha.1"
+	v23Beta1  = "0.23.0-beta.1"
+	v23RC1    = "0.23.0-rc.1"
+	v23Dev    = "0.23.0-dev"
+	v231      = "0.23.1"
+
+	v24Alpha1Tag = "v0.24.0-alpha.1"
+	v24RCTag     = "v0.24.0-rc.1"
+	v24Tag       = "v0.24.0"
+)
+
 func TestFilterPreReleasesIfStable(t *testing.T) {
 	tests := []struct {
 		name           string
@@ -14,64 +27,64 @@ func TestFilterPreReleasesIfStable(t *testing.T) {
 	}{
 		{
 			name:           "stable version filters alpha tag",
-			currentVersion: "0.23.0",
-			tag:            "v0.24.0-alpha.1",
+			currentVersion: v23,
+			tag:            v24Alpha1Tag,
 			expectedFilter: true,
 			description:    "When on stable release, alpha tags should be filtered",
 		},
 		{
 			name:           "stable version filters beta tag",
-			currentVersion: "0.23.0",
+			currentVersion: v23,
 			tag:            "v0.24.0-beta.2",
 			expectedFilter: true,
 			description:    "When on stable release, beta tags should be filtered",
 		},
 		{
 			name:           "stable version filters rc tag",
-			currentVersion: "0.23.0",
-			tag:            "v0.24.0-rc.1",
+			currentVersion: v23,
+			tag:            v24RCTag,
 			expectedFilter: true,
 			description:    "When on stable release, rc tags should be filtered",
 		},
 		{
 			name:           "stable version allows stable tag",
-			currentVersion: "0.23.0",
-			tag:            "v0.24.0",
+			currentVersion: v23,
+			tag:            v24Tag,
 			expectedFilter: false,
 			description:    "When on stable release, stable tags should not be filtered",
 		},
 		{
 			name:           "alpha version allows alpha tag",
-			currentVersion: "0.23.0-alpha.1",
+			currentVersion: v23Alpha1,
 			tag:            "v0.24.0-alpha.2",
 			expectedFilter: false,
 			description:    "When on alpha release, alpha tags should not be filtered",
 		},
 		{
 			name:           "alpha version allows beta tag",
-			currentVersion: "0.23.0-alpha.1",
+			currentVersion: v23Alpha1,
 			tag:            "v0.24.0-beta.1",
 			expectedFilter: false,
 			description:    "When on alpha release, beta tags should not be filtered",
 		},
 		{
 			name:           "alpha version allows rc tag",
-			currentVersion: "0.23.0-alpha.1",
-			tag:            "v0.24.0-rc.1",
+			currentVersion: v23Alpha1,
+			tag:            v24RCTag,
 			expectedFilter: false,
 			description:    "When on alpha release, rc tags should not be filtered",
 		},
 		{
 			name:           "alpha version allows stable tag",
-			currentVersion: "0.23.0-alpha.1",
-			tag:            "v0.24.0",
+			currentVersion: v23Alpha1,
+			tag:            v24Tag,
 			expectedFilter: false,
 			description:    "When on alpha release, stable tags should not be filtered",
 		},
 		{
 			name:           "beta version allows alpha tag",
-			currentVersion: "0.23.0-beta.1",
-			tag:            "v0.24.0-alpha.1",
+			currentVersion: v23Beta1,
+			tag:            v24Alpha1Tag,
 			expectedFilter: false,
 			description:    "When on beta release, alpha tags should not be filtered",
 		},
@@ -84,28 +97,28 @@ func TestFilterPreReleasesIfStable(t *testing.T) {
 		},
 		{
 			name:           "beta version allows rc tag",
-			currentVersion: "0.23.0-beta.1",
-			tag:            "v0.24.0-rc.1",
+			currentVersion: v23Beta1,
+			tag:            v24RCTag,
 			expectedFilter: false,
 			description:    "When on beta release, rc tags should not be filtered",
 		},
 		{
 			name:           "beta version allows stable tag",
-			currentVersion: "0.23.0-beta.1",
-			tag:            "v0.24.0",
+			currentVersion: v23Beta1,
+			tag:            v24Tag,
 			expectedFilter: false,
 			description:    "When on beta release, stable tags should not be filtered",
 		},
 		{
 			name:           "rc version allows alpha tag",
-			currentVersion: "0.23.0-rc.1",
-			tag:            "v0.24.0-alpha.1",
+			currentVersion: v23RC1,
+			tag:            v24Alpha1Tag,
 			expectedFilter: false,
 			description:    "When on rc release, alpha tags should not be filtered",
 		},
 		{
 			name:           "rc version allows beta tag",
-			currentVersion: "0.23.0-rc.1",
+			currentVersion: v23RC1,
 			tag:            "v0.24.0-beta.1",
 			expectedFilter: false,
 			description:    "When on rc release, beta tags should not be filtered",
@@ -119,78 +132,78 @@ func TestFilterPreReleasesIfStable(t *testing.T) {
 		},
 		{
 			name:           "rc version allows stable tag",
-			currentVersion: "0.23.0-rc.1",
-			tag:            "v0.24.0",
+			currentVersion: v23RC1,
+			tag:            v24Tag,
 			expectedFilter: false,
 			description:    "When on rc release, stable tags should not be filtered",
 		},
 		{
 			name:           "stable version with patch filters alpha",
-			currentVersion: "0.23.1",
-			tag:            "v0.24.0-alpha.1",
+			currentVersion: v231,
+			tag:            v24Alpha1Tag,
 			expectedFilter: true,
 			description:    "Stable version with patch number should filter alpha tags",
 		},
 		{
 			name:           "stable version with patch allows stable",
-			currentVersion: "0.23.1",
-			tag:            "v0.24.0",
+			currentVersion: v231,
+			tag:            v24Tag,
 			expectedFilter: false,
 			description:    "Stable version with patch number should allow stable tags",
 		},
 		{
 			name:           "tag with alpha substring in version number",
-			currentVersion: "0.23.0",
+			currentVersion: v23,
 			tag:            "v1.0.0-alpha.1",
 			expectedFilter: true,
 			description:    "Tags with alpha in version string should be filtered on stable",
 		},
 		{
 			name:           "tag with beta substring in version number",
-			currentVersion: "0.23.0",
+			currentVersion: v23,
 			tag:            "v1.0.0-beta.1",
 			expectedFilter: true,
 			description:    "Tags with beta in version string should be filtered on stable",
 		},
 		{
 			name:           "tag with rc substring in version number",
-			currentVersion: "0.23.0",
+			currentVersion: v23,
 			tag:            "v1.0.0-rc.1",
 			expectedFilter: true,
 			description:    "Tags with rc in version string should be filtered on stable",
 		},
 		{
 			name:           "empty tag on stable version",
-			currentVersion: "0.23.0",
+			currentVersion: v23,
 			tag:            "",
 			expectedFilter: false,
 			description:    "Empty tags should not be filtered",
 		},
 		{
 			name:           "dev version allows all tags",
-			currentVersion: "0.23.0-dev",
-			tag:            "v0.24.0-alpha.1",
+			currentVersion: v23Dev,
+			tag:            v24Alpha1Tag,
 			expectedFilter: false,
 			description:    "Dev versions should not filter any tags (pre-release allows all)",
 		},
 		{
 			name:           "stable version filters dev tag",
-			currentVersion: "0.23.0",
+			currentVersion: v23,
 			tag:            "v0.24.0-dev",
 			expectedFilter: true,
 			description:    "When on stable release, dev tags should be filtered",
 		},
 		{
 			name:           "dev version allows dev tag",
-			currentVersion: "0.23.0-dev",
+			currentVersion: v23Dev,
 			tag:            "v0.24.0-dev.1",
 			expectedFilter: false,
 			description:    "When on dev release, dev tags should not be filtered",
 		},
 		{
 			name:           "dev version allows stable tag",
-			currentVersion: "0.23.0-dev",
-			tag:            "v0.24.0",
+			currentVersion: v23Dev,
+			tag:            v24Tag,
 			expectedFilter: false,
 			description:    "When on dev release, stable tags should not be filtered",
 		},
@@ -200,7 +213,8 @@ func TestFilterPreReleasesIfStable(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			result := filterPreReleasesIfStable(func() string { return tt.currentVersion })(tt.tag)
 			if result != tt.expectedFilter {
-				t.Errorf("%s: got %v, want %v\nDescription: %s\nCurrent version: %s, Tag: %s",
+				t.Errorf(
+					"%s: got %v, want %v\nDescription: %s\nCurrent version: %s, Tag: %s",
 					tt.name,
 					result,
 					tt.expectedFilter,
@@ -222,25 +236,25 @@ func TestIsPreReleaseVersion(t *testing.T) {
 	}{
 		{
 			name:        "stable version",
-			version:     "0.23.0",
+			version:     v23,
 			expected:    false,
 			description: "Stable version should not be pre-release",
 		},
 		{
 			name:        "alpha version",
-			version:     "0.23.0-alpha.1",
+			version:     v23Alpha1,
 			expected:    true,
 			description: "Alpha version should be pre-release",
 		},
 		{
 			name:        "beta version",
-			version:     "0.23.0-beta.1",
+			version:     v23Beta1,
 			expected:    true,
 			description: "Beta version should be pre-release",
 		},
 		{
 			name:        "rc version",
-			version:     "0.23.0-rc.1",
+			version:     v23RC1,
 			expected:    true,
 			description: "RC version should be pre-release",
 		},
@@ -258,7 +272,7 @@ func TestIsPreReleaseVersion(t *testing.T) {
 		},
 		{
 			name:        "dev version",
-			version:     "0.23.0-dev",
+			version:     v23Dev,
 			expected:    true,
 			description: "Dev version should be pre-release",
 		},
@@ -270,7 +284,7 @@ func TestIsPreReleaseVersion(t *testing.T) {
 		},
 		{
 			name:        "version with patch number",
-			version:     "0.23.1",
+			version:     v231,
 			expected:    false,
 			description: "Stable version with patch should not be pre-release",
 		},
@@ -280,7 +294,8 @@ func TestIsPreReleaseVersion(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			result := isPreReleaseVersion(tt.version)
 			if result != tt.expected {
-				t.Errorf("%s: got %v, want %v\nDescription: %s\nVersion: %s",
+				t.Errorf(
+					"%s: got %v, want %v\nDescription: %s\nVersion: %s",
 					tt.name,
 					result,
 					tt.expected,

cmd/headscale/cli/serve.go

@@ -5,7 +5,6 @@ import (
 	"fmt"
 	"net/http"
 
-	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
 	"github.com/tailscale/squibble"
 )
@@ -17,24 +16,22 @@ func init() {
 var serveCmd = &cobra.Command{
 	Use:   "serve",
 	Short: "Launches the headscale server",
-	Args: func(cmd *cobra.Command, args []string) error {
-		return nil
-	},
-	Run: func(cmd *cobra.Command, args []string) {
+	RunE: func(cmd *cobra.Command, args []string) error {
 		app, err := newHeadscaleServerWithConfig()
 		if err != nil {
-			var squibbleErr squibble.ValidationError
-			if errors.As(err, &squibbleErr) {
+			if squibbleErr, ok := errors.AsType[squibble.ValidationError](err); ok {
 				fmt.Printf("SQLite schema failed to validate:\n")
 				fmt.Println(squibbleErr.Diff)
 			}
 
-			log.Fatal().Caller().Err(err).Msg("Error initializing")
+			return fmt.Errorf("initializing: %w", err)
 		}
 
 		err = app.Serve()
 		if err != nil && !errors.Is(err, http.ErrServerClosed) {
-			log.Fatal().Caller().Err(err).Msg("Headscale ran into an error and had to shut down.")
+			return fmt.Errorf("headscale ran into an error and had to shut down: %w", err)
 		}
+
+		return nil
 	},
 }

cmd/headscale/cli/strings.go

@@ -0,0 +1,23 @@
+package cli
+
+// Shared CLI vocabulary used across multiple command definitions in this
+// package. Centralising the strings prevents goconst drift and ensures a
+// typo in a subcommand name fails to compile rather than silently
+// breaking the binding.
+const (
+	// Subcommand verbs (cobra Use field).
+	cmdList   = "list"
+	cmdShow   = "show"
+	cmdNew    = "new"
+	cmdDelete = "delete"
+	cmdExpire = "expire"
+
+	// Subcommand aliases.
+	aliasDel = "del"
+	aliasExp = "exp"
+
+	// Output table column headers and printOutput map keys.
+	colResult     = "Result"
+	colCreated    = "Created"
+	colExpiration = "Expiration"
+)

cmd/headscale/cli/users.go

@@ -1,17 +1,24 @@
 package cli
 
 import (
+	"context"
 	"errors"
 	"fmt"
+	"net/http"
 	"net/url"
 	"strconv"
 
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	clientv1 "github.com/juanfont/headscale/gen/client/v1"
 	"github.com/juanfont/headscale/hscontrol/util"
-	"github.com/pterm/pterm"
+	"github.com/juanfont/headscale/hscontrol/util/zlog/zf"
 	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
-	"google.golang.org/grpc/status"
+)
+
+// CLI user errors.
+var (
+	errFlagRequired       = errors.New("--name or --identifier flag is required")
+	errMultipleUsersMatch = errors.New("multiple users match query, specify an ID")
 )
 
 func usernameAndIDFlag(cmd *cobra.Command) {
@@ -20,20 +27,58 @@ func usernameAndIDFlag(cmd *cobra.Command) {
 }
 
 // usernameAndIDFromFlag returns the username and ID from the flags of the command.
-// If both are empty, it will exit the program with an error.
-func usernameAndIDFromFlag(cmd *cobra.Command) (uint64, string) {
+func usernameAndIDFromFlag(cmd *cobra.Command) (uint64, string, error) {
 	username, _ := cmd.Flags().GetString("name")
+
 	identifier, _ := cmd.Flags().GetInt64("identifier")
 	if username == "" && identifier < 0 {
-		err := errors.New("--name or --identifier flag is required")
-		ErrorOutput(
-			err,
-			"Cannot rename user: "+status.Convert(err).Message(),
-			"",
-		)
+		return 0, "", errFlagRequired
 	}
 
-	return uint64(identifier), username
+	// Normalise unset/negative identifiers to 0 so the uint64
+	// conversion does not produce a bogus large value.
+	identifier = max(identifier, 0)
+
+	return uint64(identifier), username, nil //nolint:gosec // identifier is clamped to >= 0 above
+}
+
+// resolveSingleUser resolves exactly one user from the --name/--id flags,
+// returning the raw flag id and the matched user.
+func resolveSingleUser(
+	ctx context.Context,
+	client *clientv1.ClientWithResponses,
+	cmd *cobra.Command,
+) (uint64, *clientv1.User, error) {
+	id, username, err := usernameAndIDFromFlag(cmd)
+	if err != nil {
+		return 0, nil, err
+	}
+
+	params := &clientv1.ListUsersParams{}
+	if username != "" {
+		params.Name = &username
+	}
+
+	if id != 0 {
+		idStr := strconv.FormatUint(id, util.Base10)
+		params.Id = &idStr
+	}
+
+	resp, err := client.ListUsersWithResponse(ctx, params)
+	if err != nil {
+		return 0, nil, fmt.Errorf("listing users: %w", err)
+	}
+
+	if resp.StatusCode() != http.StatusOK {
+		return 0, nil, apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+	}
+
+	users := resp.JSON200.Users
+	if len(users) != 1 {
+		return 0, nil, errMultipleUsersMatch
+	}
+
+	return id, &users[0], nil
 }
 
 func init() {
@@ -50,21 +95,19 @@ func init() {
 	userCmd.AddCommand(renameUserCmd)
 	usernameAndIDFlag(renameUserCmd)
 	renameUserCmd.Flags().StringP("new-name", "r", "", "New username")
-	renameNodeCmd.MarkFlagRequired("new-name")
+	mustMarkRequired(renameUserCmd, "new-name")
 }
 
-var errMissingParameter = errors.New("missing parameters")
-
 var userCmd = &cobra.Command{
 	Use:     "users",
 	Short:   "Manage the users of Headscale",
-	Aliases: []string{"user", "namespace", "namespaces", "ns"},
+	Aliases: []string{"user"},
 }
 
 var createUserCmd = &cobra.Command{
 	Use:     "create NAME",
 	Short:   "Creates a new user",
-	Aliases: []string{"c", "new"},
+	Aliases: []string{"c", cmdNew},
 	Args: func(cmd *cobra.Command, args []string) error {
 		if len(args) < 1 {
 			return errMissingParameter
@@ -72,131 +115,80 @@ var createUserCmd = &cobra.Command{
 
 		return nil
 	},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
 		userName := args[0]
 
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
+		log.Trace().Interface(zf.Client, client).Msg("obtained API client")
 
-		log.Trace().Interface("client", client).Msg("Obtained gRPC client")
-
-		request := &v1.CreateUserRequest{Name: userName}
+		request := clientv1.CreateUserJSONRequestBody{Name: &userName}
 
 		if displayName, _ := cmd.Flags().GetString("display-name"); displayName != "" {
-			request.DisplayName = displayName
+			request.DisplayName = &displayName
 		}
 
 		if email, _ := cmd.Flags().GetString("email"); email != "" {
-			request.Email = email
+			request.Email = &email
 		}
 
 		if pictureURL, _ := cmd.Flags().GetString("picture-url"); pictureURL != "" {
-			if _, err := url.Parse(pictureURL); err != nil {
-				ErrorOutput(
-					err,
-					fmt.Sprintf(
-						"Invalid Picture URL: %s",
-						err,
-					),
-					output,
-				)
+			if _, err := url.Parse(pictureURL); err != nil { //nolint:noinlineerr
+				return fmt.Errorf("invalid picture URL: %w", err)
 			}
-			request.PictureUrl = pictureURL
+
+			request.PictureUrl = &pictureURL
 		}
 
-		log.Trace().Interface("request", request).Msg("Sending CreateUser request")
-		response, err := client.CreateUser(ctx, request)
+		log.Trace().Interface(zf.Request, request).Msg("sending CreateUser request")
+
+		resp, err := client.CreateUserWithResponse(ctx, request)
 		if err != nil {
-			ErrorOutput(
-				err,
-				"Cannot create user: "+status.Convert(err).Message(),
-				output,
-			)
+			return fmt.Errorf("creating user: %w", err)
 		}
 
-		SuccessOutput(response.GetUser(), "User created", output)
-	},
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200.User, "User created")
+	}),
 }
 
 var destroyUserCmd = &cobra.Command{
 	Use:     "destroy --identifier ID or --name NAME",
 	Short:   "Destroys a user",
-	Aliases: []string{"delete"},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		id, username := usernameAndIDFromFlag(cmd)
-		request := &v1.ListUsersRequest{
-			Name: username,
-			Id:   id,
-		}
-
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
-
-		users, err := client.ListUsers(ctx, request)
+	Aliases: []string{cmdDelete},
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		_, user, err := resolveSingleUser(ctx, client, cmd)
 		if err != nil {
-			ErrorOutput(
-				err,
-				"Error: "+status.Convert(err).Message(),
-				output,
-			)
+			return err
 		}
 
-		if len(users.GetUsers()) != 1 {
-			err := errors.New("Unable to determine user to delete, query returned multiple users, use ID")
-			ErrorOutput(
-				err,
-				"Error: "+status.Convert(err).Message(),
-				output,
-			)
+		if !confirmAction(cmd, fmt.Sprintf(
+			"Do you want to remove the user %q (%s) and any associated preauthkeys?",
+			user.Name, user.Id,
+		)) {
+			return printOutput(cmd, map[string]string{colResult: "User not destroyed"}, "User not destroyed")
 		}
 
-		user := users.GetUsers()[0]
-
-		confirm := false
-		force, _ := cmd.Flags().GetBool("force")
-		if !force {
-			confirm = util.YesNo(fmt.Sprintf(
-				"Do you want to remove the user %q (%d) and any associated preauthkeys?",
-				user.GetName(), user.GetId(),
-			))
+		resp, err := client.DeleteUserWithResponse(ctx, user.Id)
+		if err != nil {
+			return fmt.Errorf("destroying user: %w", err)
 		}
 
-		if confirm || force {
-			request := &v1.DeleteUserRequest{Id: user.GetId()}
-
-			response, err := client.DeleteUser(ctx, request)
-			if err != nil {
-				ErrorOutput(
-					err,
-					"Cannot destroy user: "+status.Convert(err).Message(),
-					output,
-				)
-			}
-			SuccessOutput(response, "User destroyed", output)
-		} else {
-			SuccessOutput(map[string]string{"Result": "User not destroyed"}, "User not destroyed", output)
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
 		}
-	},
+
+		return printOutput(cmd, resp.JSON200, "User destroyed")
+	}),
 }
 
 var listUsersCmd = &cobra.Command{
-	Use:     "list",
+	Use:     cmdList,
 	Short:   "List all the users",
-	Aliases: []string{"ls", "show"},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
-
-		request := &v1.ListUsersRequest{}
+	Aliases: []string{"ls", cmdShow},
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		params := &clientv1.ListUsersParams{}
 
 		id, _ := cmd.Flags().GetInt64("identifier")
 		username, _ := cmd.Flags().GetString("name")
@@ -205,101 +197,66 @@ var listUsersCmd = &cobra.Command{
 		// filter by one param at most
 		switch {
 		case id > 0:
-			request.Id = uint64(id)
+			idStr := strconv.FormatInt(id, util.Base10)
+			params.Id = &idStr
 		case username != "":
-			request.Name = username
+			params.Name = &username
 		case email != "":
-			request.Email = email
+			params.Email = &email
 		}
 
-		response, err := client.ListUsers(ctx, request)
+		resp, err := client.ListUsersWithResponse(ctx, params)
 		if err != nil {
-			ErrorOutput(
-				err,
-				"Cannot get users: "+status.Convert(err).Message(),
-				output,
-			)
+			return fmt.Errorf("listing users: %w", err)
 		}
 
-		if output != "" {
-			SuccessOutput(response.GetUsers(), "", output)
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
 		}
 
-		tableData := pterm.TableData{{"ID", "Name", "Username", "Email", "Created"}}
-		for _, user := range response.GetUsers() {
-			tableData = append(
-				tableData,
-				[]string{
-					strconv.FormatUint(user.GetId(), 10),
-					user.GetDisplayName(),
-					user.GetName(),
-					user.GetEmail(),
-					user.GetCreatedAt().AsTime().Format("2006-01-02 15:04:05"),
-				},
-			)
-		}
-		err = pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Failed to render pterm table: %s", err),
-				output,
-			)
-		}
-	},
+		users := resp.JSON200.Users
+
+		return printListOutput(cmd, users, func() error {
+			rows := make([][]string, 0, len(users))
+			for _, user := range users {
+				rows = append(
+					rows,
+					[]string{
+						user.Id,
+						user.DisplayName,
+						user.Name,
+						user.Email,
+						user.CreatedAt.Format(HeadscaleDateTimeFormat),
+					},
+				)
+			}
+
+			return renderTable([]string{"ID", "Name", "Username", "Email", colCreated}, rows)
+		})
+	}),
 }
 
 var renameUserCmd = &cobra.Command{
 	Use:     "rename",
 	Short:   "Renames a user",
 	Aliases: []string{"mv"},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
-		defer cancel()
-		defer conn.Close()
-
-		id, username := usernameAndIDFromFlag(cmd)
-		listReq := &v1.ListUsersRequest{
-			Name: username,
-			Id:   id,
-		}
-
-		users, err := client.ListUsers(ctx, listReq)
+	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+		id, _, err := resolveSingleUser(ctx, client, cmd)
 		if err != nil {
-			ErrorOutput(
-				err,
-				"Error: "+status.Convert(err).Message(),
-				output,
-			)
-		}
-
-		if len(users.GetUsers()) != 1 {
-			err := errors.New("Unable to determine user to delete, query returned multiple users, use ID")
-			ErrorOutput(
-				err,
-				"Error: "+status.Convert(err).Message(),
-				output,
-			)
+			return err
 		}
 
 		newName, _ := cmd.Flags().GetString("new-name")
 
-		renameReq := &v1.RenameUserRequest{
-			OldId:   id,
-			NewName: newName,
-		}
-
-		response, err := client.RenameUser(ctx, renameReq)
+		resp, err := client.RenameUserWithResponse(ctx, strconv.FormatUint(id, util.Base10), newName)
 		if err != nil {
-			ErrorOutput(
-				err,
-				"Cannot rename user: "+status.Convert(err).Message(),
-				output,
-			)
+			return fmt.Errorf("renaming user: %w", err)
 		}
 
-		SuccessOutput(response.GetUser(), "User renamed", output)
-	},
+		if resp.StatusCode() != http.StatusOK {
+			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+		}
+
+		return printOutput(cmd, resp.JSON200.User, "User renamed")
+	}),
 }

cmd/headscale/cli/utils.go

@@ -4,25 +4,88 @@ import (
 	"context"
 	"crypto/tls"
 	"encoding/json"
+	"errors"
 	"fmt"
+	"net"
+	"net/http"
 	"os"
+	"slices"
+	"strings"
+	"time"
 
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	"github.com/cenkalti/backoff/v5"
+	clientv1 "github.com/juanfont/headscale/gen/client/v1"
 	"github.com/juanfont/headscale/hscontrol"
 	"github.com/juanfont/headscale/hscontrol/types"
 	"github.com/juanfont/headscale/hscontrol/util"
+	"github.com/juanfont/headscale/hscontrol/util/zlog/zf"
+	"github.com/prometheus/common/model"
+	"github.com/pterm/pterm"
 	"github.com/rs/zerolog/log"
-	"google.golang.org/grpc"
-	"google.golang.org/grpc/credentials"
-	"google.golang.org/grpc/credentials/insecure"
+	"github.com/spf13/cobra"
 	"gopkg.in/yaml.v3"
 )
 
 const (
 	HeadscaleDateTimeFormat = "2006-01-02 15:04:05"
 	SocketWritePermissions  = 0o666
+
+	outputFormatJSON     = "json"
+	outputFormatJSONLine = "json-line"
+	outputFormatYAML     = "yaml"
 )
 
+var (
+	errAPIKeyNotSet     = errors.New("HEADSCALE_CLI_API_KEY environment variable needs to be set")
+	errMissingParameter = errors.New("missing parameters")
+	errResponseStatus   = errors.New("unexpected response status")
+)
+
+// apiError turns a non-2xx response into an error, surfacing the server's
+// RFC7807 problem detail. detail holds the operation context and errors[] the
+// wrapped cause (e.g. "name is too long"); both are joined so the server's
+// message text is not lost.
+func apiError(statusCode int, problem *clientv1.ErrorModel) error {
+	if problem == nil {
+		return fmt.Errorf("%w: %d %s", errResponseStatus, statusCode, http.StatusText(statusCode))
+	}
+
+	parts := make([]string, 0, 2)
+
+	if problem.Detail != nil && *problem.Detail != "" {
+		parts = append(parts, *problem.Detail)
+	}
+
+	if problem.Errors != nil {
+		for _, e := range *problem.Errors {
+			if e.Message != nil && *e.Message != "" {
+				parts = append(parts, *e.Message)
+			}
+		}
+	}
+
+	if len(parts) == 0 && problem.Title != nil && *problem.Title != "" {
+		parts = append(parts, *problem.Title)
+	}
+
+	if len(parts) == 0 {
+		return fmt.Errorf("%w: %d %s", errResponseStatus, statusCode, http.StatusText(statusCode))
+	}
+
+	return fmt.Errorf("%w: %s", errResponseStatus, strings.Join(parts, ": "))
+}
+
+// mustMarkRequired marks the named flags as required, panicking on an unknown
+// flag. Only called from init(), where a failure is a programming error.
+func mustMarkRequired(cmd *cobra.Command, names ...string) {
+	for _, n := range names {
+		err := cmd.MarkFlagRequired(n)
+		if err != nil {
+			panic(fmt.Sprintf("marking flag %q required on %q: %v", n, cmd.Name(), err))
+		}
+	}
+}
+
 func newHeadscaleServerWithConfig() (*hscontrol.Headscale, error) {
 	cfg, err := types.LoadServerConfig()
 	if err != nil {
@@ -40,14 +103,47 @@ func newHeadscaleServerWithConfig() (*hscontrol.Headscale, error) {
 	return app, nil
 }
 
-func newHeadscaleCLIWithConfig() (context.Context, v1.HeadscaleServiceClient, *grpc.ClientConn, context.CancelFunc) {
+// clientRunE wraps a [cobra.Command.RunE] func, injecting a ready API client
+// and a context whose timeout/cancel the wrapper owns.
+func clientRunE(
+	fn func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error,
+) func(*cobra.Command, []string) error {
+	return func(cmd *cobra.Command, args []string) error {
+		ctx, client, cancel, err := newHeadscaleCLIWithConfig()
+		if err != nil {
+			return fmt.Errorf("connecting to headscale: %w", err)
+		}
+		defer cancel()
+
+		return fn(ctx, client, cmd, args)
+	}
+}
+
+// withClient runs fn with an API client. For commands that branch on a flag
+// before talking to the server, where clientRunE's whole-RunE wrapping does
+// not fit.
+func withClient(
+	fn func(ctx context.Context, client *clientv1.ClientWithResponses) error,
+) error {
+	ctx, client, cancel, err := newHeadscaleCLIWithConfig()
+	if err != nil {
+		return fmt.Errorf("connecting to headscale: %w", err)
+	}
+	defer cancel()
+
+	return fn(ctx, client)
+}
+
+// newHeadscaleCLIWithConfig builds an HTTP client for the Headscale v1 API.
+//
+// When cfg.CLI.Address is unset the CLI is assumed to run on the server host
+// and talks to the unix socket over HTTP without authentication (local trust).
+// Otherwise it talks to the remote TCP address over HTTPS and injects the
+// configured API key as a bearer token.
+func newHeadscaleCLIWithConfig() (context.Context, *clientv1.ClientWithResponses, context.CancelFunc, error) {
 	cfg, err := types.LoadCLIConfig()
 	if err != nil {
-		log.Fatal().
-			Err(err).
-			Caller().
-			Msgf("Failed to load configuration")
-		os.Exit(-1) // we get here if logging is suppressed (i.e., json output)
+		return nil, nil, nil, fmt.Errorf("loading configuration: %w", err)
 	}
 
 	log.Debug().
@@ -56,154 +152,249 @@ func newHeadscaleCLIWithConfig() (context.Context, v1.HeadscaleServiceClient, *g
 
 	ctx, cancel := context.WithTimeout(context.Background(), cfg.CLI.Timeout)
 
-	grpcOptions := []grpc.DialOption{
-		grpc.WithBlock(),
-	}
-
 	address := cfg.CLI.Address
 
-	// If the address is not set, we assume that we are on the server hosting hscontrol.
+	// If the address is not set, we assume that we are on the server hosting [hscontrol].
 	if address == "" {
 		log.Debug().
 			Str("socket", cfg.UnixSocket).
 			Msgf("HEADSCALE_CLI_ADDRESS environment is not set, connecting to unix socket.")
 
-		address = cfg.UnixSocket
-
-		// Try to give the user better feedback if we cannot write to the headscale
-		// socket.
-		socket, err := os.OpenFile(cfg.UnixSocket, os.O_WRONLY, SocketWritePermissions) // nolint
+		client, err := newSocketClient(cfg.UnixSocket)
 		if err != nil {
-			if os.IsPermission(err) {
-				log.Fatal().
-					Err(err).
-					Str("socket", cfg.UnixSocket).
-					Msgf("Unable to read/write to headscale socket, do you have the correct permissions?")
-			}
-		}
-		socket.Close()
+			cancel()
 
-		grpcOptions = append(
-			grpcOptions,
-			grpc.WithTransportCredentials(insecure.NewCredentials()),
-			grpc.WithContextDialer(util.GrpcSocketDialer),
-		)
-	} else {
-		// If we are not connecting to a local server, require an API key for authentication
-		apiKey := cfg.CLI.APIKey
-		if apiKey == "" {
-			log.Fatal().Caller().Msgf("HEADSCALE_CLI_API_KEY environment variable needs to be set.")
+			return nil, nil, nil, err
 		}
-		grpcOptions = append(grpcOptions,
-			grpc.WithPerRPCCredentials(tokenAuth{
-				token: apiKey,
-			}),
-		)
 
-		if cfg.CLI.Insecure {
-			tlsConfig := &tls.Config{
-				// turn of gosec as we are intentionally setting
-				// insecure.
-				//nolint:gosec
-				InsecureSkipVerify: true,
-			}
+		log.Trace().Caller().Str(zf.Address, cfg.UnixSocket).Msg("connecting via unix socket")
 
-			grpcOptions = append(grpcOptions,
-				grpc.WithTransportCredentials(credentials.NewTLS(tlsConfig)),
-			)
-		} else {
-			grpcOptions = append(grpcOptions,
-				grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(nil, "")),
-			)
-		}
+		return ctx, client, cancel, nil
 	}
 
-	log.Trace().Caller().Str("address", address).Msg("Connecting via gRPC")
-	conn, err := grpc.DialContext(ctx, address, grpcOptions...)
+	// Remote connections require an API key for authentication.
+	apiKey := cfg.CLI.APIKey
+	if apiKey == "" {
+		cancel()
+
+		return nil, nil, nil, errAPIKeyNotSet
+	}
+
+	client, err := newRemoteClient(address, apiKey, cfg.CLI.Insecure)
 	if err != nil {
-		log.Fatal().Caller().Err(err).Msgf("Could not connect: %v", err)
-		os.Exit(-1) // we get here if logging is suppressed (i.e., json output)
+		cancel()
+
+		return nil, nil, nil, err
 	}
 
-	client := v1.NewHeadscaleServiceClient(conn)
+	log.Trace().Caller().Str(zf.Address, address).Msg("connecting via HTTPS")
 
-	return ctx, client, conn, cancel
+	return ctx, client, cancel, nil
 }
 
-func output(result any, override string, outputFormat string) string {
-	var jsonBytes []byte
-	var err error
+// newSocketClient builds an API client that dials the local unix socket. The
+// base-URL host is irrelevant; the custom dialer routes every request to the
+// socket.
+func newSocketClient(socketPath string) (*clientv1.ClientWithResponses, error) {
+	// Probe for a clearer permission error up front. [os.OpenFile] on a unix
+	// socket returns ENXIO on Linux (expected); only permission errors are
+	// actionable. The real connection goes through [net.Dial].
+	socket, err := os.OpenFile(socketPath, os.O_WRONLY, SocketWritePermissions) //nolint
+	if err != nil {
+		if os.IsPermission(err) {
+			return nil, fmt.Errorf(
+				"unable to read/write to headscale socket %q, do you have the correct permissions? %w",
+				socketPath,
+				err,
+			)
+		}
+	} else {
+		socket.Close()
+	}
+
+	httpClient := &http.Client{
+		Transport: &http.Transport{
+			DialContext: func(ctx context.Context, _, _ string) (net.Conn, error) {
+				return dialHeadscaleSocket(ctx, socketPath)
+			},
+		},
+	}
+
+	return clientv1.NewClientWithResponses(
+		"http://local",
+		clientv1.WithHTTPClient(httpClient),
+	)
+}
+
+// dialHeadscaleSocket connects to the unix socket, retrying until it appears or
+// ctx (the CLI timeout) expires. The socket is created late in startup (after
+// noise key, database, migrations), so a command run right after the server
+// starts can race its creation; retrying preserves the old gRPC client's
+// blocking-dial tolerance rather than failing on a not-yet-present socket.
+func dialHeadscaleSocket(ctx context.Context, socketPath string) (net.Conn, error) {
+	b := backoff.NewExponentialBackOff()
+	b.InitialInterval = 50 * time.Millisecond
+	b.MaxInterval = 1 * time.Second
+
+	return backoff.Retry(ctx, func() (net.Conn, error) {
+		return util.SocketDialer(ctx, socketPath)
+	}, backoff.WithBackOff(b))
+}
+
+// clientBaseURL turns a configured CLI address into a client base URL. A bare
+// host[:port] (the historical form) defaults to https; an address that already
+// carries a scheme is used as-is, so an explicit http:// or https:// is honoured
+// rather than doubled into https://https://...
+func clientBaseURL(address string) string {
+	if strings.Contains(address, "://") {
+		return address
+	}
+
+	return "https://" + address
+}
+
+// newRemoteClient builds an API client for a remote Headscale over HTTPS,
+// honouring insecure (skip TLS verification) and injecting the API key as a
+// bearer token on every request.
+func newRemoteClient(address, apiKey string, insecure bool) (*clientv1.ClientWithResponses, error) {
+	transport := &http.Transport{}
+	if insecure {
+		transport.TLSClientConfig = &tls.Config{
+			// turn off gosec as we are intentionally setting insecure.
+			//nolint:gosec
+			InsecureSkipVerify: true,
+		}
+	}
+
+	httpClient := &http.Client{Transport: transport}
+
+	return clientv1.NewClientWithResponses(
+		clientBaseURL(address),
+		clientv1.WithHTTPClient(httpClient),
+		clientv1.WithRequestEditorFn(func(_ context.Context, req *http.Request) error {
+			req.Header.Set("Authorization", "Bearer "+apiKey)
+
+			return nil
+		}),
+	)
+}
+
+// formatOutput serialises result into the requested format. For the
+// default (empty) format the human-readable override string is returned.
+func formatOutput(result any, override string, outputFormat string) (string, error) {
 	switch outputFormat {
-	case "json":
-		jsonBytes, err = json.MarshalIndent(result, "", "\t")
+	case outputFormatJSON:
+		b, err := json.MarshalIndent(result, "", "\t")
 		if err != nil {
-			log.Fatal().Err(err).Msg("failed to unmarshal output")
+			return "", fmt.Errorf("marshalling JSON output: %w", err)
 		}
-	case "json-line":
-		jsonBytes, err = json.Marshal(result)
+
+		return string(b), nil
+	case outputFormatJSONLine:
+		b, err := json.Marshal(result)
 		if err != nil {
-			log.Fatal().Err(err).Msg("failed to unmarshal output")
+			return "", fmt.Errorf("marshalling JSON-line output: %w", err)
 		}
-	case "yaml":
-		jsonBytes, err = yaml.Marshal(result)
+
+		return string(b), nil
+	case outputFormatYAML:
+		b, err := yaml.Marshal(result)
 		if err != nil {
-			log.Fatal().Err(err).Msg("failed to unmarshal output")
+			return "", fmt.Errorf("marshalling YAML output: %w", err)
 		}
+
+		return string(b), nil
 	default:
-		// nolint
-		return override
+		return override, nil
+	}
+}
+
+// printOutput formats result and writes it to stdout. It reads the --output
+// flag from cmd to decide the serialisation format.
+func printOutput(cmd *cobra.Command, result any, override string) error {
+	format, _ := cmd.Flags().GetString("output")
+
+	out, err := formatOutput(result, override, format)
+	if err != nil {
+		return err
 	}
 
-	return string(jsonBytes)
+	fmt.Println(out)
+
+	return nil
 }
 
-// SuccessOutput prints the result to stdout and exits with status code 0.
-func SuccessOutput(result any, override string, outputFormat string) {
-	fmt.Println(output(result, override, outputFormat))
-	os.Exit(0)
+// expirationFromFlag parses the --expiration flag as a Prometheus-style
+// duration (e.g. "90d", "1h") and returns an absolute time.
+func expirationFromFlag(cmd *cobra.Command) (time.Time, error) {
+	durationStr, _ := cmd.Flags().GetString("expiration")
+
+	duration, err := model.ParseDuration(durationStr)
+	if err != nil {
+		return time.Time{}, fmt.Errorf("parsing duration: %w", err)
+	}
+
+	return time.Now().UTC().Add(time.Duration(duration)), nil
 }
 
-// ErrorOutput prints an error message to stderr and exits with status code 1.
-func ErrorOutput(errResult error, override string, outputFormat string) {
+// confirmAction returns true when the user confirms a prompt, or when
+// --force is set.  Callers decide what to do when it returns false.
+func confirmAction(cmd *cobra.Command, prompt string) bool {
+	force, _ := cmd.Flags().GetBool("force")
+	if force {
+		return true
+	}
+
+	return util.YesNo(prompt)
+}
+
+// renderTable prints a human-readable pterm table with the given header row
+// and data rows, using the shared header styling.
+func renderTable(header []string, rows [][]string) error {
+	tableData := make(pterm.TableData, 0, 1+len(rows))
+	tableData = append(tableData, header)
+	tableData = append(tableData, rows...)
+
+	return pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
+}
+
+// printListOutput checks the --output flag: when a machine-readable format is
+// requested it serialises data as JSON/YAML; otherwise it calls the render
+// callback to produce the human-readable pterm table.
+func printListOutput(
+	cmd *cobra.Command,
+	data any,
+	renderTable func() error,
+) error {
+	format, _ := cmd.Flags().GetString("output")
+	if format != "" {
+		return printOutput(cmd, data, "")
+	}
+
+	return renderTable()
+}
+
+// printError writes err to stderr, formatting it as JSON/YAML when the
+// --output flag requests machine-readable output.  Used exclusively by
+// [Execute] so that every error surfaces in the format the caller asked for.
+func printError(err error, outputFormat string) {
 	type errOutput struct {
 		Error string `json:"error"`
 	}
 
-	var errorMessage string
-	if errResult != nil {
-		errorMessage = errResult.Error()
-	} else {
-		errorMessage = override
+	if outputFormat == "" {
+		fmt.Fprintf(os.Stderr, "Error: %s\n", err)
+
+		return
 	}
 
-	fmt.Fprintf(os.Stderr, "%s\n", output(errOutput{errorMessage}, override, outputFormat))
-	os.Exit(1)
+	// formatOutput cannot fail here: errOutput is a single string field.
+	out, _ := formatOutput(errOutput{Error: err.Error()}, "", outputFormat)
+	fmt.Fprintf(os.Stderr, "%s\n", out)
 }
 
-func HasMachineOutputFlag() bool {
-	for _, arg := range os.Args {
-		if arg == "json" || arg == "json-line" || arg == "yaml" {
-			return true
-		}
-	}
-
-	return false
-}
-
-type tokenAuth struct {
-	token string
-}
-
-// Return value is mapped to request headers.
-func (t tokenAuth) GetRequestMetadata(
-	ctx context.Context,
-	in ...string,
-) (map[string]string, error) {
-	return map[string]string{
-		"authorization": "Bearer " + t.token,
-	}, nil
-}
-
-func (tokenAuth) RequireTransportSecurity() bool {
-	return true
+func hasMachineOutputFlag() bool {
+	return slices.ContainsFunc(os.Args, func(arg string) bool {
+		return arg == outputFormatJSON || arg == outputFormatJSONLine || arg == outputFormatYAML
+	})
 }

cmd/headscale/cli/utils_socket_test.go

@@ -0,0 +1,72 @@
+package cli
+
+import (
+	"context"
+	"net"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestDialHeadscaleSocketRetriesUntilPresent proves the CLI socket dialer
+// tolerates a not-yet-created socket (the server-still-starting race) by
+// retrying until it appears, rather than failing immediately like a bare dial.
+func TestDialHeadscaleSocketRetriesUntilPresent(t *testing.T) {
+	sock := filepath.Join(t.TempDir(), "headscale.sock")
+
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+
+	type result struct {
+		conn net.Conn
+		err  error
+	}
+
+	done := make(chan result, 1)
+
+	go func() {
+		conn, err := dialHeadscaleSocket(ctx, sock)
+		done <- result{conn, err}
+	}()
+
+	// Listen only after the dialer has begun, so its backoff must retry the
+	// absent socket and connect once it exists.
+	var lc net.ListenConfig
+
+	ln, err := lc.Listen(ctx, "unix", sock)
+	require.NoError(t, err)
+
+	defer ln.Close()
+
+	go func() {
+		if conn, _ := ln.Accept(); conn != nil {
+			conn.Close()
+		}
+	}()
+
+	res := <-done
+	require.NoError(t, res.err)
+	require.NotNil(t, res.conn)
+
+	res.conn.Close()
+}
+
+// TestDialHeadscaleSocketRespectsDeadline proves the retry is bounded by the
+// context: when the socket never appears, the dialer returns an error around the
+// deadline instead of hanging.
+func TestDialHeadscaleSocketRespectsDeadline(t *testing.T) {
+	sock := filepath.Join(t.TempDir(), "absent.sock")
+
+	ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
+	defer cancel()
+
+	start := time.Now()
+
+	conn, err := dialHeadscaleSocket(ctx, sock)
+	require.Error(t, err)
+	assert.Nil(t, conn)
+	assert.Less(t, time.Since(start), 5*time.Second, "should stop near the deadline, not hang")
+}

cmd/headscale/cli/utils_test.go

@@ -0,0 +1,35 @@
+package cli
+
+import "testing"
+
+func TestClientBaseURL(t *testing.T) {
+	tests := []struct {
+		name    string
+		address string
+		want    string
+	}{
+		{
+			name:    "bare host defaults to https",
+			address: "headscale.example.com:50443",
+			want:    "https://headscale.example.com:50443",
+		},
+		{
+			name:    "explicit https scheme is kept",
+			address: "https://headscale.example.com",
+			want:    "https://headscale.example.com",
+		},
+		{
+			name:    "explicit http scheme is kept",
+			address: "http://localhost:8080",
+			want:    "http://localhost:8080",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := clientBaseURL(tt.address); got != tt.want {
+				t.Errorf("clientBaseURL(%q) = %q, want %q", tt.address, got, tt.want)
+			}
+		})
+	}
+}

cmd/headscale/cli/version.go

@@ -14,11 +14,9 @@ var versionCmd = &cobra.Command{
 	Use:   "version",
 	Short: "Print the version.",
 	Long:  "The version of headscale.",
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
+	RunE: func(cmd *cobra.Command, args []string) error {
 		info := types.GetVersionInfo()
 
-		SuccessOutput(info, info.String(), output)
+		return printOutput(cmd, info, info.String())
 	},
 }

cmd/headscale/headscale.go

@@ -11,20 +11,7 @@ import (
 )
 
 func main() {
-	var colors bool
-	switch l := termcolor.SupportLevel(os.Stderr); l {
-	case termcolor.Level16M:
-		colors = true
-	case termcolor.Level256:
-		colors = true
-	case termcolor.LevelBasic:
-		colors = true
-	case termcolor.LevelNone:
-		colors = false
-	default:
-		// no color, return text as is.
-		colors = false
-	}
+	colors := termcolor.SupportLevel(os.Stderr) != termcolor.LevelNone
 
 	// Adhere to no-color.org manifesto of allowing users to
 	// turn off color in cli/services

cmd/headscale/headscale_test.go

@@ -14,9 +14,7 @@ import (
 )
 
 func TestConfigFileLoading(t *testing.T) {
-	tmpDir, err := os.MkdirTemp("", "headscale")
-	require.NoError(t, err)
-	defer os.RemoveAll(tmpDir)
+	tmpDir := t.TempDir()
 
 	path, err := os.Getwd()
 	require.NoError(t, err)
@@ -48,9 +46,7 @@ func TestConfigFileLoading(t *testing.T) {
 }
 
 func TestConfigLoading(t *testing.T) {
-	tmpDir, err := os.MkdirTemp("", "headscale")
-	require.NoError(t, err)
-	defer os.RemoveAll(tmpDir)
+	tmpDir := t.TempDir()
 
 	path, err := os.Getwd()
 	require.NoError(t, err)
@@ -77,5 +73,4 @@ func TestConfigLoading(t *testing.T) {
 	assert.Equal(t, "HTTP-01", viper.GetString("tls_letsencrypt_challenge_type"))
 	assert.Equal(t, fs.FileMode(0o770), util.GetFileMode("unix_socket_permission"))
 	assert.False(t, viper.GetBool("logtail.enabled"))
-	assert.False(t, viper.GetBool("randomize_client_port"))
 }

cmd/hi/README.md

@@ -1,6 +1,262 @@
-# hi
+# hi — Headscale Integration test runner
 
-hi (headscale integration runner) is an entirely "vibe coded" wrapper around our
-[integration test suite](../integration). It essentially runs the docker
-commands for you with some added benefits of extracting resources like logs and
-databases.
+`hi` wraps Docker container orchestration around the tests in
+[`../../integration`](../../integration) and extracts debugging artefacts
+(logs, database snapshots, MapResponse protocol captures) for post-mortem
+analysis.
+
+**Read this file in full before running any `hi` command.** The test
+runner has sharp edges — wrong flags produce stale containers, lost
+artefacts, or hung CI.
+
+For test-authoring patterns (scenario setup, `EventuallyWithT`,
+`IntegrationSkip`, helper variants), read
+[`../../integration/README.md`](../../integration/README.md).
+
+## Quick Start
+
+```bash
+# Verify system requirements (Docker, Go, disk space, images)
+go run ./cmd/hi doctor
+
+# Run a single test (the default flags are tuned for development)
+go run ./cmd/hi run "TestPingAllByIP"
+
+# Run a database-heavy test against PostgreSQL
+go run ./cmd/hi run "TestExpireNode" --postgres
+
+# Pattern matching
+go run ./cmd/hi run "TestSubnet*"
+```
+
+Run `doctor` before the first `run` in any new environment. Tests
+generate ~100 MB of logs per run in `control_logs/`; `doctor` verifies
+there is enough space and that the required Docker images are available.
+
+## Commands
+
+| Command            | Purpose                                              |
+| ------------------ | ---------------------------------------------------- |
+| `run [pattern]`    | Execute the test(s) matching `pattern`               |
+| `doctor`           | Verify system requirements                           |
+| `clean networks`   | Prune unused Docker networks                         |
+| `clean images`     | Clean old test images                                |
+| `clean containers` | Kill **all** test containers (dangerous — see below) |
+| `clean cache`      | Clean Go module cache volume                         |
+| `clean all`        | Run all cleanup operations                           |
+
+## Flags
+
+Defaults are tuned for single-test development runs. Review before
+changing.
+
+| Flag                | Default        | Purpose                                                                     |
+| ------------------- | -------------- | --------------------------------------------------------------------------- |
+| `--timeout`         | `120m`         | Total test timeout. Use the built-in flag — never wrap with bash `timeout`. |
+| `--postgres`        | `false`        | Use PostgreSQL instead of SQLite                                            |
+| `--failfast`        | `true`         | Stop on first test failure                                                  |
+| `--go-version`      | auto           | Detected from `go.mod` (currently 1.26.1)                                   |
+| `--clean-before`    | `true`         | Clean stale (stopped/exited) containers before starting                     |
+| `--clean-after`     | `true`         | Clean this run's containers after completion                                |
+| `--keep-on-failure` | `false`        | Preserve containers for manual inspection on failure                        |
+| `--logs-dir`        | `control_logs` | Where to save run artefacts                                                 |
+| `--verbose`         | `false`        | Verbose output                                                              |
+| `--stats`           | `false`        | Collect container resource-usage stats                                      |
+| `--hs-memory-limit` | `0`            | Fail if any headscale container exceeds N MB (0 = disabled)                 |
+| `--ts-memory-limit` | `0`            | Fail if any tailscale container exceeds N MB                                |
+
+### Timeout guidance
+
+The default `120m` is generous for a single test. If you must tune it,
+these are realistic floors by category:
+
+| Test type                 | Minimum     | Examples                              |
+| ------------------------- | ----------- | ------------------------------------- |
+| Basic functionality / CLI | 900s (15m)  | `TestPingAllByIP`, `TestCLI*`         |
+| Route / ACL               | 1200s (20m) | `TestSubnet*`, `TestACL*`             |
+| HA / failover             | 1800s (30m) | `TestHASubnetRouter*`                 |
+| Long-running              | 2100s (35m) | `TestNodeOnlineStatus` (~12 min body) |
+| Full suite                | 45m         | `go test ./integration -timeout 45m`  |
+
+**Never** use the shell `timeout` command around `hi`. It kills the
+process mid-cleanup and leaves stale containers:
+
+```bash
+timeout 300 go run ./cmd/hi run "TestName"   # WRONG — orphaned containers
+go run ./cmd/hi run "TestName" --timeout=900s  # correct
+```
+
+## Concurrent Execution
+
+Multiple `hi run` invocations can run simultaneously on the same Docker
+daemon. Each invocation gets a unique **Run ID** (format
+`YYYYMMDD-HHMMSS-6charhash`, e.g. `20260409-104215-mdjtzx`).
+
+- **Container names** include the short run ID: `ts-mdjtzx-1-74-fgdyls`
+- **Docker labels**: `hi.run-id={runID}` on every container
+- **Port allocation**: dynamic — kernel assigns free ports, no conflicts
+- **Cleanup isolation**: each run cleans only its own containers
+- **Log directories**: `control_logs/{runID}/`
+
+```bash
+# Start three tests in parallel — each gets its own run ID
+go run ./cmd/hi run "TestPingAllByIP" &
+go run ./cmd/hi run "TestACLAllowUserDst" &
+go run ./cmd/hi run "TestOIDCAuthenticationPingAll" &
+```
+
+### Safety rules for concurrent runs
+
+- ✅ Your run cleans only containers labelled with its own `hi.run-id`
+- ✅ `--clean-before` removes only stopped/exited containers
+- ❌ **Never** run `docker rm -f $(docker ps -q --filter name=hs-)` —
+  this destroys other agents' live test sessions
+- ❌ **Never** run `docker system prune -f` while any tests are running
+- ❌ **Never** run `hi clean containers` / `hi clean all` while other
+  tests are running — both kill all test containers on the daemon
+
+To identify your own containers:
+
+```bash
+docker ps --filter "label=hi.run-id=20260409-104215-mdjtzx"
+```
+
+The run ID appears at the top of the `hi run` output — copy it from
+there rather than trying to reconstruct it.
+
+## Artefacts
+
+Every run saves debugging artefacts under `control_logs/{runID}/`:
+
+```
+control_logs/20260409-104215-mdjtzx/
+├── hs-<test>-<hash>.stderr.log        # headscale server errors
+├── hs-<test>-<hash>.stdout.log        # headscale server output
+├── hs-<test>-<hash>.db                # database snapshot (SQLite)
+├── hs-<test>-<hash>_metrics.txt       # Prometheus metrics dump
+├── hs-<test>-<hash>-mapresponses/     # MapResponse protocol captures
+├── ts-<client>-<hash>.stderr.log      # tailscale client errors
+├── ts-<client>-<hash>.stdout.log      # tailscale client output
+└── ts-<client>-<hash>_status.json     # client network-status dump
+```
+
+Artefacts persist after cleanup. Old runs accumulate fast — delete
+unwanted directories to reclaim disk.
+
+## Debugging workflow
+
+When a test fails, read the artefacts **in this order**:
+
+1. **`hs-*.stderr.log`** — headscale server errors, panics, policy
+   evaluation failures. Most issues originate server-side.
+
+   ```bash
+   grep -E "ERROR|panic|FATAL" control_logs/*/hs-*.stderr.log
+   ```
+
+2. **`ts-*.stderr.log`** — authentication failures, connectivity issues,
+   DNS resolution problems on the client side.
+
+3. **MapResponse JSON** in `hs-*-mapresponses/` — protocol-level
+   debugging for network map generation, peer visibility, route
+   distribution, policy evaluation results.
+
+   ```bash
+   ls control_logs/*/hs-*-mapresponses/
+   jq '.Peers[] | {Name, Tags, PrimaryRoutes}' \
+       control_logs/*/hs-*-mapresponses/001.json
+   ```
+
+4. **`*_status.json`** — client peer-connectivity state.
+
+5. **`hs-*.db`** — SQLite snapshot for post-mortem consistency checks.
+
+   ```bash
+   sqlite3 control_logs/<runID>/hs-*.db
+   sqlite> .tables
+   sqlite> .schema nodes
+   sqlite> SELECT id, hostname, user_id, tags FROM nodes WHERE hostname LIKE '%problematic%';
+   ```
+
+6. **`*_metrics.txt`** — Prometheus dumps for latency, NodeStore
+   operation timing, database query performance, memory usage.
+
+## Heuristic: infrastructure vs code
+
+**Before blaming Docker, disk, or network: read `hs-*.stderr.log` in
+full.** In practice, well over 99% of failures are code bugs (policy
+evaluation, NodeStore sync, route approval) rather than infrastructure.
+
+Actual infrastructure failures have signature error messages:
+
+| Signature                                                       | Cause                     | Fix                                                           |
+| --------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------- |
+| `failed to resolve "hs-...": no DNS fallback candidates remain` | Docker DNS                | Reset Docker networking                                       |
+| `container creation timeout`, no progress >2 min                | Resource exhaustion       | `docker system prune -f` (when no other tests running), retry |
+| OOM kills, slow Docker daemon                                   | Too many concurrent tests | Reduce concurrency, wait for completion                       |
+| `no space left on device`                                       | Disk full                 | Delete old `control_logs/`                                    |
+
+If you don't see a signature error, **assume it's a code regression** —
+do not retry hoping the flake goes away.
+
+## Common failure patterns (code bugs)
+
+### Route advertisement timing
+
+Test asserts route state before the client has finished propagating its
+Hostinfo update. Symptom: `nodes[0].GetAvailableRoutes()` empty when
+the test expects a route.
+
+- **Wrong fix**: `time.Sleep(5 * time.Second)` — fragile and slow.
+- **Right fix**: wrap the assertion in `EventuallyWithT`. See
+  [`../../integration/README.md`](../../integration/README.md).
+
+### NodeStore sync issues
+
+Route changes not reflected in the NodeStore snapshot. Symptom: route
+advertisements in logs but no tracking updates in subsequent reads.
+
+The sync point is `State.UpdateNodeFromMapRequest()` in
+`hscontrol/state/state.go`. If you added a new kind of client state
+update, make sure it lands here.
+
+### HA failover: routes disappearing on disconnect
+
+`TestHASubnetRouterFailover` fails because approved routes vanish when
+a subnet router goes offline. **This is a bug, not expected behaviour.**
+Route approval must not be coupled to client connectivity — routes
+stay approved; only the primary-route selection is affected by
+connectivity.
+
+### Policy evaluation race
+
+Symptom: tests that change policy and immediately assert peer visibility
+fail intermittently. Policy changes trigger async recomputation.
+
+- See recent fixes in `git log -- hscontrol/state/` for examples (e.g.
+  the `PolicyChange` trigger on every Connect/Disconnect).
+
+### SQLite vs PostgreSQL timing differences
+
+Some race conditions only surface on one backend. If a test is flaky,
+try the other backend with `--postgres`:
+
+```bash
+go run ./cmd/hi run "TestName" --postgres --verbose
+```
+
+PostgreSQL generally has more consistent timing; SQLite can expose
+races during rapid writes.
+
+## Keeping containers for inspection
+
+If you need to inspect a failed test's state manually:
+
+```bash
+go run ./cmd/hi run "TestName" --keep-on-failure
+# containers survive — inspect them
+docker exec -it ts-<runID>-<...> /bin/sh
+docker logs hs-<runID>-<...>
+# clean up manually when done
+go run ./cmd/hi clean all   # only when no other tests are running
+```

cmd/hi/cleanup.go

@@ -22,11 +22,11 @@ import (
 func cleanupBeforeTest(ctx context.Context) error {
 	err := cleanupStaleTestContainers(ctx)
 	if err != nil {
-		return fmt.Errorf("failed to clean stale test containers: %w", err)
+		return fmt.Errorf("cleaning stale test containers: %w", err)
 	}
 
-	if err := pruneDockerNetworks(ctx); err != nil {
-		return fmt.Errorf("failed to prune networks: %w", err)
+	if err := pruneDockerNetworks(ctx); err != nil { //nolint:noinlineerr
+		return fmt.Errorf("pruning networks: %w", err)
 	}
 
 	return nil
@@ -39,14 +39,14 @@ func cleanupAfterTest(ctx context.Context, cli *client.Client, containerID, runI
 		Force: true,
 	})
 	if err != nil {
-		return fmt.Errorf("failed to remove test container: %w", err)
+		return fmt.Errorf("removing test container: %w", err)
 	}
 
 	// Clean up integration test containers for this run only
 	if runID != "" {
 		err := killTestContainersByRunID(ctx, runID)
 		if err != nil {
-			return fmt.Errorf("failed to clean up containers for run %s: %w", runID, err)
+			return fmt.Errorf("cleaning up containers for run %s: %w", runID, err)
 		}
 	}
 
@@ -55,9 +55,9 @@ func cleanupAfterTest(ctx context.Context, cli *client.Client, containerID, runI
 
 // killTestContainers terminates and removes all test containers.
 func killTestContainers(ctx context.Context) error {
-	cli, err := createDockerClient()
+	cli, err := createDockerClient(ctx)
 	if err != nil {
-		return fmt.Errorf("failed to create Docker client: %w", err)
+		return fmt.Errorf("creating Docker client: %w", err)
 	}
 	defer cli.Close()
 
@@ -65,30 +65,14 @@ func killTestContainers(ctx context.Context) error {
 		All: true,
 	})
 	if err != nil {
-		return fmt.Errorf("failed to list containers: %w", err)
+		return fmt.Errorf("listing containers: %w", err)
 	}
 
 	removed := 0
+
 	for _, cont := range containers {
-		shouldRemove := false
-		for _, name := range cont.Names {
-			if strings.Contains(name, "headscale-test-suite") ||
-				strings.Contains(name, "hs-") ||
-				strings.Contains(name, "ts-") ||
-				strings.Contains(name, "derp-") {
-				shouldRemove = true
-				break
-			}
-		}
-
-		if shouldRemove {
-			// First kill the container if it's running
-			if cont.State == "running" {
-				_ = cli.ContainerKill(ctx, cont.ID, "KILL")
-			}
-
-			// Then remove the container with retry logic
-			if removeContainerWithRetry(ctx, cli, cont.ID) {
+		if isTestContainerName(cont.Names) {
+			if killAndRemove(ctx, cli, cont) {
 				removed++
 			}
 		}
@@ -107,9 +91,9 @@ func killTestContainers(ctx context.Context) error {
 // This function filters containers by the hi.run-id label to only affect containers
 // belonging to the specified test run, leaving other concurrent test runs untouched.
 func killTestContainersByRunID(ctx context.Context, runID string) error {
-	cli, err := createDockerClient()
+	cli, err := createDockerClient(ctx)
 	if err != nil {
-		return fmt.Errorf("failed to create Docker client: %w", err)
+		return fmt.Errorf("creating Docker client: %w", err)
 	}
 	defer cli.Close()
 
@@ -121,19 +105,13 @@ func killTestContainersByRunID(ctx context.Context, runID string) error {
 		),
 	})
 	if err != nil {
-		return fmt.Errorf("failed to list containers for run %s: %w", runID, err)
+		return fmt.Errorf("listing containers for run %s: %w", runID, err)
 	}
 
 	removed := 0
 
 	for _, cont := range containers {
-		// Kill the container if it's running
-		if cont.State == "running" {
-			_ = cli.ContainerKill(ctx, cont.ID, "KILL")
-		}
-
-		// Remove the container with retry logic
-		if removeContainerWithRetry(ctx, cli, cont.ID) {
+		if killAndRemove(ctx, cli, cont) {
 			removed++
 		}
 	}
@@ -149,9 +127,9 @@ func killTestContainersByRunID(ctx context.Context, runID string) error {
 // This is useful for cleaning up leftover containers from previous crashed or interrupted test runs
 // without interfering with currently running concurrent tests.
 func cleanupStaleTestContainers(ctx context.Context) error {
-	cli, err := createDockerClient()
+	cli, err := createDockerClient(ctx)
 	if err != nil {
-		return fmt.Errorf("failed to create Docker client: %w", err)
+		return fmt.Errorf("creating Docker client: %w", err)
 	}
 	defer cli.Close()
 
@@ -164,27 +142,15 @@ func cleanupStaleTestContainers(ctx context.Context) error {
 		),
 	})
 	if err != nil {
-		return fmt.Errorf("failed to list stopped containers: %w", err)
+		return fmt.Errorf("listing stopped containers: %w", err)
 	}
 
 	removed := 0
 
 	for _, cont := range containers {
 		// Only remove containers that look like test containers
-		shouldRemove := false
-
-		for _, name := range cont.Names {
-			if strings.Contains(name, "headscale-test-suite") ||
-				strings.Contains(name, "hs-") ||
-				strings.Contains(name, "ts-") ||
-				strings.Contains(name, "derp-") {
-				shouldRemove = true
-				break
-			}
-		}
-
-		if shouldRemove {
-			if removeContainerWithRetry(ctx, cli, cont.ID) {
+		if isTestContainerName(cont.Names) {
+			if killAndRemove(ctx, cli, cont) {
 				removed++
 			}
 		}
@@ -221,17 +187,42 @@ func removeContainerWithRetry(ctx context.Context, cli *client.Client, container
 	return err == nil
 }
 
+// isTestContainerName reports whether any of the container names belong to an
+// integration test container.
+func isTestContainerName(names []string) bool {
+	for _, name := range names {
+		if strings.Contains(name, "headscale-test-suite") ||
+			strings.Contains(name, "hs-") ||
+			strings.Contains(name, "ts-") ||
+			strings.Contains(name, "derp-") {
+			return true
+		}
+	}
+
+	return false
+}
+
+// killAndRemove kills a running container then removes it with retry logic,
+// reporting whether the removal succeeded.
+func killAndRemove(ctx context.Context, cli *client.Client, cont container.Summary) bool {
+	if cont.State == "running" {
+		_ = cli.ContainerKill(ctx, cont.ID, "KILL")
+	}
+
+	return removeContainerWithRetry(ctx, cli, cont.ID)
+}
+
 // pruneDockerNetworks removes unused Docker networks.
 func pruneDockerNetworks(ctx context.Context) error {
-	cli, err := createDockerClient()
+	cli, err := createDockerClient(ctx)
 	if err != nil {
-		return fmt.Errorf("failed to create Docker client: %w", err)
+		return fmt.Errorf("creating Docker client: %w", err)
 	}
 	defer cli.Close()
 
 	report, err := cli.NetworksPrune(ctx, filters.Args{})
 	if err != nil {
-		return fmt.Errorf("failed to prune networks: %w", err)
+		return fmt.Errorf("pruning networks: %w", err)
 	}
 
 	if len(report.NetworksDeleted) > 0 {
@@ -245,9 +236,9 @@ func pruneDockerNetworks(ctx context.Context) error {
 
 // cleanOldImages removes test-related and old dangling Docker images.
 func cleanOldImages(ctx context.Context) error {
-	cli, err := createDockerClient()
+	cli, err := createDockerClient(ctx)
 	if err != nil {
-		return fmt.Errorf("failed to create Docker client: %w", err)
+		return fmt.Errorf("creating Docker client: %w", err)
 	}
 	defer cli.Close()
 
@@ -255,12 +246,14 @@ func cleanOldImages(ctx context.Context) error {
 		All: true,
 	})
 	if err != nil {
-		return fmt.Errorf("failed to list images: %w", err)
+		return fmt.Errorf("listing images: %w", err)
 	}
 
 	removed := 0
+
 	for _, img := range images {
 		shouldRemove := false
+
 		for _, tag := range img.RepoTags {
 			if strings.Contains(tag, "hs-") ||
 				strings.Contains(tag, "headscale-integration") ||
@@ -295,18 +288,19 @@ func cleanOldImages(ctx context.Context) error {
 
 // cleanCacheVolume removes the Docker volume used for Go module cache.
 func cleanCacheVolume(ctx context.Context) error {
-	cli, err := createDockerClient()
+	cli, err := createDockerClient(ctx)
 	if err != nil {
-		return fmt.Errorf("failed to create Docker client: %w", err)
+		return fmt.Errorf("creating Docker client: %w", err)
 	}
 	defer cli.Close()
 
 	volumeName := "hs-integration-go-cache"
+
 	err = cli.VolumeRemove(ctx, volumeName, true)
 	if err != nil {
-		if errdefs.IsNotFound(err) {
+		if errdefs.IsNotFound(err) { //nolint:staticcheck // SA1019: deprecated but functional
 			fmt.Printf("Go module cache volume not found: %s\n", volumeName)
-		} else if errdefs.IsConflict(err) {
+		} else if errdefs.IsConflict(err) { //nolint:staticcheck // SA1019: deprecated but functional
 			fmt.Printf("Go module cache volume is in use and cannot be removed: %s\n", volumeName)
 		} else {
 			fmt.Printf("Failed to remove Go module cache volume %s: %v\n", volumeName, err)
@@ -330,7 +324,7 @@ func cleanCacheVolume(ctx context.Context) error {
 func cleanupSuccessfulTestArtifacts(logsDir string, verbose bool) error {
 	entries, err := os.ReadDir(logsDir)
 	if err != nil {
-		return fmt.Errorf("failed to read logs directory: %w", err)
+		return fmt.Errorf("reading logs directory: %w", err)
 	}
 
 	var (

cmd/hi/docker.go

@@ -14,6 +14,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/cenkalti/backoff/v5"
 	"github.com/docker/docker/api/types/container"
 	"github.com/docker/docker/api/types/image"
 	"github.com/docker/docker/api/types/mount"
@@ -22,17 +23,22 @@ import (
 	"github.com/juanfont/headscale/integration/dockertestutil"
 )
 
+const defaultDirPerm = 0o755
+
 var (
 	ErrTestFailed              = errors.New("test failed")
 	ErrUnexpectedContainerWait = errors.New("unexpected end of container wait")
 	ErrNoDockerContext         = errors.New("no docker context found")
+	ErrMemoryLimitViolations   = errors.New("container(s) exceeded memory limits")
 )
 
 // runTestContainer executes integration tests in a Docker container.
+//
+//nolint:gocyclo // complex test orchestration function
 func runTestContainer(ctx context.Context, config *RunConfig) error {
-	cli, err := createDockerClient()
+	cli, err := createDockerClient(ctx)
 	if err != nil {
-		return fmt.Errorf("failed to create Docker client: %w", err)
+		return fmt.Errorf("creating Docker client: %w", err)
 	}
 	defer cli.Close()
 
@@ -48,19 +54,21 @@ func runTestContainer(ctx context.Context, config *RunConfig) error {
 
 	absLogsDir, err := filepath.Abs(logsDir)
 	if err != nil {
-		return fmt.Errorf("failed to get absolute path for logs directory: %w", err)
+		return fmt.Errorf("getting absolute path for logs directory: %w", err)
 	}
 
 	const dirPerm = 0o755
-	if err := os.MkdirAll(absLogsDir, dirPerm); err != nil {
-		return fmt.Errorf("failed to create logs directory: %w", err)
+	if err := os.MkdirAll(absLogsDir, dirPerm); err != nil { //nolint:noinlineerr
+		return fmt.Errorf("creating logs directory: %w", err)
 	}
 
 	if config.CleanBefore {
 		if config.Verbose {
 			log.Printf("Running pre-test cleanup...")
 		}
-		if err := cleanupBeforeTest(ctx); err != nil && config.Verbose {
+
+		err := cleanupBeforeTest(ctx)
+		if err != nil && config.Verbose {
 			log.Printf("Warning: pre-test cleanup failed: %v", err)
 		}
 	}
@@ -71,21 +79,21 @@ func runTestContainer(ctx context.Context, config *RunConfig) error {
 	}
 
 	imageName := "golang:" + config.GoVersion
-	if err := ensureImageAvailable(ctx, cli, imageName, config.Verbose); err != nil {
-		return fmt.Errorf("failed to ensure image availability: %w", err)
+	if err := ensureImageAvailable(ctx, cli, imageName, config.Verbose); err != nil { //nolint:noinlineerr
+		return fmt.Errorf("ensuring image availability: %w", err)
 	}
 
 	resp, err := createGoTestContainer(ctx, cli, config, containerName, absLogsDir, goTestCmd)
 	if err != nil {
-		return fmt.Errorf("failed to create container: %w", err)
+		return fmt.Errorf("creating container: %w", err)
 	}
 
 	if config.Verbose {
 		log.Printf("Created container: %s", resp.ID)
 	}
 
-	if err := cli.ContainerStart(ctx, resp.ID, container.StartOptions{}); err != nil {
-		return fmt.Errorf("failed to start container: %w", err)
+	if err := cli.ContainerStart(ctx, resp.ID, container.StartOptions{}); err != nil { //nolint:noinlineerr
+		return fmt.Errorf("starting container: %w", err)
 	}
 
 	log.Printf("Starting test: %s", config.TestPattern)
@@ -95,13 +103,16 @@ func runTestContainer(ctx context.Context, config *RunConfig) error {
 
 	// Start stats collection for container resource monitoring (if enabled)
 	var statsCollector *StatsCollector
+
 	if config.Stats {
 		var err error
-		statsCollector, err = NewStatsCollector()
+
+		statsCollector, err = NewStatsCollector(ctx)
 		if err != nil {
 			if config.Verbose {
 				log.Printf("Warning: failed to create stats collector: %v", err)
 			}
+
 			statsCollector = nil
 		}
 
@@ -110,7 +121,8 @@ func runTestContainer(ctx context.Context, config *RunConfig) error {
 
 			// Start stats collection immediately - no need for complex retry logic
 			// The new implementation monitors Docker events and will catch containers as they start
-			if err := statsCollector.StartCollection(ctx, runID, config.Verbose); err != nil {
+			err := statsCollector.StartCollection(ctx, runID, config.Verbose)
+			if err != nil {
 				if config.Verbose {
 					log.Printf("Warning: failed to start stats collection: %v", err)
 				}
@@ -122,12 +134,13 @@ func runTestContainer(ctx context.Context, config *RunConfig) error {
 	exitCode, err := streamAndWait(ctx, cli, resp.ID)
 
 	// Ensure all containers have finished and logs are flushed before extracting artifacts
-	if waitErr := waitForContainerFinalization(ctx, cli, resp.ID, config.Verbose); waitErr != nil && config.Verbose {
+	waitErr := waitForContainerFinalization(ctx, cli, resp.ID, config.Verbose)
+	if waitErr != nil && config.Verbose {
 		log.Printf("Warning: failed to wait for container finalization: %v", waitErr)
 	}
 
 	// Extract artifacts from test containers before cleanup
-	if err := extractArtifactsFromContainers(ctx, resp.ID, logsDir, config.Verbose); err != nil && config.Verbose {
+	if err := extractArtifactsFromContainers(ctx, resp.ID, logsDir, config.Verbose); err != nil && config.Verbose { //nolint:noinlineerr
 		log.Printf("Warning: failed to extract artifacts from containers: %v", err)
 	}
 
@@ -140,12 +153,13 @@ func runTestContainer(ctx context.Context, config *RunConfig) error {
 		if len(violations) > 0 {
 			log.Printf("MEMORY LIMIT VIOLATIONS DETECTED:")
 			log.Printf("=================================")
+
 			for _, violation := range violations {
 				log.Printf("Container %s exceeded memory limit: %.1f MB > %.1f MB",
 					violation.ContainerName, violation.MaxMemoryMB, violation.LimitMB)
 			}
 
-			return fmt.Errorf("test failed: %d container(s) exceeded memory limits", len(violations))
+			return fmt.Errorf("test failed: %d %w", len(violations), ErrMemoryLimitViolations)
 		}
 	}
 
@@ -176,7 +190,7 @@ func runTestContainer(ctx context.Context, config *RunConfig) error {
 	}
 
 	if err != nil {
-		return fmt.Errorf("test execution failed: %w", err)
+		return fmt.Errorf("executing test: %w", err)
 	}
 
 	if exitCode != 0 {
@@ -210,7 +224,7 @@ func buildGoTestCommand(config *RunConfig) []string {
 func createGoTestContainer(ctx context.Context, cli *client.Client, config *RunConfig, containerName, logsDir string, goTestCmd []string) (container.CreateResponse, error) {
 	pwd, err := os.Getwd()
 	if err != nil {
-		return container.CreateResponse{}, fmt.Errorf("failed to get working directory: %w", err)
+		return container.CreateResponse{}, fmt.Errorf("getting working directory: %w", err)
 	}
 
 	projectRoot := findProjectRoot(pwd)
@@ -312,7 +326,7 @@ func streamAndWait(ctx context.Context, cli *client.Client, containerID string)
 		Follow:     true,
 	})
 	if err != nil {
-		return -1, fmt.Errorf("failed to get container logs: %w", err)
+		return -1, fmt.Errorf("getting container logs: %w", err)
 	}
 	defer out.Close()
 
@@ -324,7 +338,7 @@ func streamAndWait(ctx context.Context, cli *client.Client, containerID string)
 	select {
 	case err := <-errCh:
 		if err != nil {
-			return -1, fmt.Errorf("error waiting for container: %w", err)
+			return -1, fmt.Errorf("waiting for container: %w", err)
 		}
 	case status := <-statusCh:
 		return int(status.StatusCode), nil
@@ -338,7 +352,7 @@ func waitForContainerFinalization(ctx context.Context, cli *client.Client, testC
 	// First, get all related test containers
 	containers, err := cli.ContainerList(ctx, container.ListOptions{All: true})
 	if err != nil {
-		return fmt.Errorf("failed to list containers: %w", err)
+		return fmt.Errorf("listing containers: %w", err)
 	}
 
 	testContainers := getCurrentTestContainers(containers, testContainerID, verbose)
@@ -347,6 +361,7 @@ func waitForContainerFinalization(ctx context.Context, cli *client.Client, testC
 	maxWaitTime := 10 * time.Second
 	checkInterval := 500 * time.Millisecond
 	timeout := time.After(maxWaitTime)
+
 	ticker := time.NewTicker(checkInterval)
 	defer ticker.Stop()
 
@@ -356,6 +371,7 @@ func waitForContainerFinalization(ctx context.Context, cli *client.Client, testC
 			if verbose {
 				log.Printf("Timeout waiting for container finalization, proceeding with artifact extraction")
 			}
+
 			return nil
 		case <-ticker.C:
 			allFinalized := true
@@ -366,12 +382,14 @@ func waitForContainerFinalization(ctx context.Context, cli *client.Client, testC
 					if verbose {
 						log.Printf("Warning: failed to inspect container %s: %v", testCont.name, err)
 					}
+
 					continue
 				}
 
 				// Check if container is in a final state
 				if !isContainerFinalized(inspect.State) {
 					allFinalized = false
+
 					if verbose {
 						log.Printf("Container %s still finalizing (state: %s)", testCont.name, inspect.State.Status)
 					}
@@ -384,6 +402,7 @@ func waitForContainerFinalization(ctx context.Context, cli *client.Client, testC
 				if verbose {
 					log.Printf("All test containers finalized, ready for artifact extraction")
 				}
+
 				return nil
 			}
 		}
@@ -400,13 +419,15 @@ func isContainerFinalized(state *container.State) bool {
 func findProjectRoot(startPath string) string {
 	current := startPath
 	for {
-		if _, err := os.Stat(filepath.Join(current, "go.mod")); err == nil {
+		if _, err := os.Stat(filepath.Join(current, "go.mod")); err == nil { //nolint:noinlineerr
 			return current
 		}
+
 		parent := filepath.Dir(current)
 		if parent == current {
 			return startPath
 		}
+
 		current = parent
 	}
 }
@@ -416,6 +437,7 @@ func boolToInt(b bool) int {
 	if b {
 		return 1
 	}
+
 	return 0
 }
 
@@ -428,13 +450,14 @@ type DockerContext struct {
 }
 
 // createDockerClient creates a Docker client with context detection.
-func createDockerClient() (*client.Client, error) {
-	contextInfo, err := getCurrentDockerContext()
+func createDockerClient(ctx context.Context) (*client.Client, error) {
+	contextInfo, err := getCurrentDockerContext(ctx)
 	if err != nil {
 		return client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
 	}
 
 	var clientOpts []client.Opt
+
 	clientOpts = append(clientOpts, client.WithAPIVersionNegotiation())
 
 	if contextInfo != nil {
@@ -444,6 +467,7 @@ func createDockerClient() (*client.Client, error) {
 					if runConfig.Verbose {
 						log.Printf("Using Docker host from context '%s': %s", contextInfo.Name, host)
 					}
+
 					clientOpts = append(clientOpts, client.WithHost(host))
 				}
 			}
@@ -458,16 +482,17 @@ func createDockerClient() (*client.Client, error) {
 }
 
 // getCurrentDockerContext retrieves the current Docker context information.
-func getCurrentDockerContext() (*DockerContext, error) {
-	cmd := exec.Command("docker", "context", "inspect")
+func getCurrentDockerContext(ctx context.Context) (*DockerContext, error) {
+	cmd := exec.CommandContext(ctx, "docker", "context", "inspect")
+
 	output, err := cmd.Output()
 	if err != nil {
-		return nil, fmt.Errorf("failed to get docker context: %w", err)
+		return nil, fmt.Errorf("getting docker context: %w", err)
 	}
 
 	var contexts []DockerContext
-	if err := json.Unmarshal(output, &contexts); err != nil {
-		return nil, fmt.Errorf("failed to parse docker context: %w", err)
+	if err := json.Unmarshal(output, &contexts); err != nil { //nolint:noinlineerr
+		return nil, fmt.Errorf("parsing docker context: %w", err)
 	}
 
 	if len(contexts) > 0 {
@@ -486,59 +511,92 @@ func getDockerSocketPath() string {
 
 // checkImageAvailableLocally checks if the specified Docker image is available locally.
 func checkImageAvailableLocally(ctx context.Context, cli *client.Client, imageName string) (bool, error) {
-	_, _, err := cli.ImageInspectWithRaw(ctx, imageName)
+	_, _, err := cli.ImageInspectWithRaw(ctx, imageName) //nolint:staticcheck // SA1019: deprecated but functional
 	if err != nil {
-		if client.IsErrNotFound(err) {
+		if client.IsErrNotFound(err) { //nolint:staticcheck // SA1019: deprecated but functional
 			return false, nil
 		}
-		return false, fmt.Errorf("failed to inspect image %s: %w", imageName, err)
+
+		return false, fmt.Errorf("inspecting image %s: %w", imageName, err)
 	}
 
 	return true, nil
 }
 
-// ensureImageAvailable checks if the image is available locally first, then pulls if needed.
+// ensureImageAvailable pulls imageName if missing, using Docker Hub
+// credentials and retrying transient errors.
 func ensureImageAvailable(ctx context.Context, cli *client.Client, imageName string, verbose bool) error {
-	// First check if image is available locally
 	available, err := checkImageAvailableLocally(ctx, cli, imageName)
 	if err != nil {
-		return fmt.Errorf("failed to check local image availability: %w", err)
+		return fmt.Errorf("checking local image availability: %w", err)
 	}
 
 	if available {
 		if verbose {
 			log.Printf("Image %s is available locally", imageName)
 		}
+
 		return nil
 	}
 
-	// Image not available locally, try to pull it
 	if verbose {
 		log.Printf("Image %s not found locally, pulling...", imageName)
 	}
 
-	reader, err := cli.ImagePull(ctx, imageName, image.PullOptions{})
+	registryAuth, err := dockertestutil.RegistryAuth()
 	if err != nil {
-		return fmt.Errorf("failed to pull image %s: %w", imageName, err)
+		return fmt.Errorf("resolving registry auth: %w", err)
 	}
-	defer reader.Close()
 
-	if verbose {
-		_, err = io.Copy(os.Stdout, reader)
-		if err != nil {
-			return fmt.Errorf("failed to read pull output: %w", err)
-		}
-	} else {
-		_, err = io.Copy(io.Discard, reader)
-		if err != nil {
-			return fmt.Errorf("failed to read pull output: %w", err)
-		}
+	_, err = backoff.Retry(
+		ctx,
+		func() (struct{}, error) {
+			reader, pullErr := cli.ImagePull(ctx, imageName, image.PullOptions{RegistryAuth: registryAuth})
+			if pullErr != nil {
+				if isPermanentDockerPullError(pullErr) {
+					return struct{}{}, backoff.Permanent(pullErr)
+				}
+
+				return struct{}{}, fmt.Errorf("pulling image %s: %w", imageName, pullErr)
+			}
+			defer reader.Close()
+
+			sink := io.Discard
+			if verbose {
+				sink = os.Stdout
+			}
+
+			_, copyErr := io.Copy(sink, reader)
+			if copyErr != nil {
+				return struct{}{}, fmt.Errorf("reading pull output: %w", copyErr)
+			}
+
+			return struct{}{}, nil
+		},
+		backoff.WithBackOff(backoff.NewExponentialBackOff()),
+		backoff.WithMaxElapsedTime(60*time.Second),
+	)
+	if err != nil {
+		return err
+	}
+
+	if !verbose {
 		log.Printf("Image %s pulled successfully", imageName)
 	}
 
 	return nil
 }
 
+func isPermanentDockerPullError(err error) bool {
+	msg := strings.ToLower(err.Error())
+
+	return strings.Contains(msg, "manifest unknown") ||
+		strings.Contains(msg, "manifest not found") ||
+		strings.Contains(msg, "repository does not exist") ||
+		strings.Contains(msg, "name unknown") ||
+		strings.Contains(msg, "no such image")
+}
+
 // listControlFiles displays the headscale test artifacts created in the control logs directory.
 func listControlFiles(logsDir string) {
 	entries, err := os.ReadDir(logsDir)
@@ -547,9 +605,11 @@ func listControlFiles(logsDir string) {
 		return
 	}
 
-	var logFiles []string
-	var dataFiles []string
-	var dataDirs []string
+	var (
+		logFiles  []string
+		dataFiles []string
+		dataDirs  []string
+	)
 
 	for _, entry := range entries {
 		name := entry.Name()
@@ -578,6 +638,7 @@ func listControlFiles(logsDir string) {
 
 	if len(logFiles) > 0 {
 		log.Printf("Headscale logs:")
+
 		for _, file := range logFiles {
 			log.Printf("  %s", file)
 		}
@@ -585,9 +646,11 @@ func listControlFiles(logsDir string) {
 
 	if len(dataFiles) > 0 || len(dataDirs) > 0 {
 		log.Printf("Headscale data:")
+
 		for _, file := range dataFiles {
 			log.Printf("  %s", file)
 		}
+
 		for _, dir := range dataDirs {
 			log.Printf("  %s/", dir)
 		}
@@ -596,25 +659,27 @@ func listControlFiles(logsDir string) {
 
 // extractArtifactsFromContainers collects container logs and files from the specific test run.
 func extractArtifactsFromContainers(ctx context.Context, testContainerID, logsDir string, verbose bool) error {
-	cli, err := createDockerClient()
+	cli, err := createDockerClient(ctx)
 	if err != nil {
-		return fmt.Errorf("failed to create Docker client: %w", err)
+		return fmt.Errorf("creating Docker client: %w", err)
 	}
 	defer cli.Close()
 
 	// List all containers
 	containers, err := cli.ContainerList(ctx, container.ListOptions{All: true})
 	if err != nil {
-		return fmt.Errorf("failed to list containers: %w", err)
+		return fmt.Errorf("listing containers: %w", err)
 	}
 
 	// Get containers from the specific test run
 	currentTestContainers := getCurrentTestContainers(containers, testContainerID, verbose)
 
 	extractedCount := 0
+
 	for _, cont := range currentTestContainers {
 		// Extract container logs and tar files
-		if err := extractContainerArtifacts(ctx, cli, cont.ID, cont.name, logsDir, verbose); err != nil {
+		err := extractContainerArtifacts(ctx, cli, cont.ID, cont.name, logsDir, verbose)
+		if err != nil {
 			if verbose {
 				log.Printf("Warning: failed to extract artifacts from container %s (%s): %v", cont.name, cont.ID[:12], err)
 			}
@@ -622,6 +687,7 @@ func extractArtifactsFromContainers(ctx context.Context, testContainerID, logsDi
 			if verbose {
 				log.Printf("Extracted artifacts from container %s (%s)", cont.name, cont.ID[:12])
 			}
+
 			extractedCount++
 		}
 	}
@@ -645,11 +711,13 @@ func getCurrentTestContainers(containers []container.Summary, testContainerID st
 
 	// Find the test container to get its run ID label
 	var runID string
+
 	for _, cont := range containers {
 		if cont.ID == testContainerID {
 			if cont.Labels != nil {
 				runID = cont.Labels["hi.run-id"]
 			}
+
 			break
 		}
 	}
@@ -690,23 +758,15 @@ func getCurrentTestContainers(containers []container.Summary, testContainerID st
 // extractContainerArtifacts saves logs and tar files from a container.
 func extractContainerArtifacts(ctx context.Context, cli *client.Client, containerID, containerName, logsDir string, verbose bool) error {
 	// Ensure the logs directory exists
-	if err := os.MkdirAll(logsDir, 0o755); err != nil {
-		return fmt.Errorf("failed to create logs directory: %w", err)
+	err := os.MkdirAll(logsDir, defaultDirPerm)
+	if err != nil {
+		return fmt.Errorf("creating logs directory: %w", err)
 	}
 
 	// Extract container logs
-	if err := extractContainerLogs(ctx, cli, containerID, containerName, logsDir, verbose); err != nil {
-		return fmt.Errorf("failed to extract logs: %w", err)
-	}
-
-	// Extract tar files for headscale containers only
-	if strings.HasPrefix(containerName, "hs-") {
-		if err := extractContainerFiles(ctx, cli, containerID, containerName, logsDir, verbose); err != nil {
-			if verbose {
-				log.Printf("Warning: failed to extract files from %s: %v", containerName, err)
-			}
-			// Don't fail the whole extraction if files are missing
-		}
+	err = extractContainerLogs(ctx, cli, containerID, containerName, logsDir, verbose)
+	if err != nil {
+		return fmt.Errorf("extracting logs: %w", err)
 	}
 
 	return nil
@@ -723,7 +783,7 @@ func extractContainerLogs(ctx context.Context, cli *client.Client, containerID,
 		Tail:       "all",
 	})
 	if err != nil {
-		return fmt.Errorf("failed to get container logs: %w", err)
+		return fmt.Errorf("getting container logs: %w", err)
 	}
 	defer logReader.Close()
 
@@ -737,17 +797,17 @@ func extractContainerLogs(ctx context.Context, cli *client.Client, containerID,
 	// Demultiplex the Docker logs stream to separate stdout and stderr
 	_, err = stdcopy.StdCopy(&stdoutBuf, &stderrBuf, logReader)
 	if err != nil {
-		return fmt.Errorf("failed to demultiplex container logs: %w", err)
+		return fmt.Errorf("demultiplexing container logs: %w", err)
 	}
 
 	// Write stdout logs
-	if err := os.WriteFile(stdoutPath, stdoutBuf.Bytes(), 0o644); err != nil {
-		return fmt.Errorf("failed to write stdout log: %w", err)
+	if err := os.WriteFile(stdoutPath, stdoutBuf.Bytes(), 0o644); err != nil { //nolint:gosec,noinlineerr // log files should be readable
+		return fmt.Errorf("writing stdout log: %w", err)
 	}
 
 	// Write stderr logs
-	if err := os.WriteFile(stderrPath, stderrBuf.Bytes(), 0o644); err != nil {
-		return fmt.Errorf("failed to write stderr log: %w", err)
+	if err := os.WriteFile(stderrPath, stderrBuf.Bytes(), 0o644); err != nil { //nolint:gosec,noinlineerr // log files should be readable
+		return fmt.Errorf("writing stderr log: %w", err)
 	}
 
 	if verbose {
@@ -756,12 +816,3 @@ func extractContainerLogs(ctx context.Context, cli *client.Client, containerID,
 
 	return nil
 }
-
-// extractContainerFiles extracts database file and directories from headscale containers.
-// Note: The actual file extraction is now handled by the integration tests themselves
-// via SaveProfile, SaveMapResponses, and SaveDatabase functions in hsic.go.
-func extractContainerFiles(ctx context.Context, cli *client.Client, containerID, containerName, logsDir string, verbose bool) error {
-	// Files are now extracted directly by the integration tests
-	// This function is kept for potential future use or other file types
-	return nil
-}

cmd/hi/doctor.go

@@ -5,8 +5,23 @@ import (
 	"errors"
 	"fmt"
 	"log"
+	"os"
 	"os/exec"
 	"strings"
+
+	"github.com/juanfont/headscale/integration/dockertestutil"
+)
+
+const (
+	statusPass = "PASS"
+	statusFail = "FAIL"
+	statusWarn = "WARN"
+
+	nameDockerDaemon  = "Docker Daemon"
+	nameDockerContext = "Docker Context"
+	nameDockerSocket  = "Docker Socket"
+	nameGolangImage   = "Golang Image"
+	nameGoInstall     = "Go Installation"
 )
 
 var ErrSystemChecksFailed = errors.New("system checks failed")
@@ -19,6 +34,21 @@ type DoctorResult struct {
 	Suggestions []string
 }
 
+// pass builds a passing DoctorResult.
+func pass(name, message string) DoctorResult {
+	return DoctorResult{Name: name, Status: statusPass, Message: message}
+}
+
+// warn builds a warning DoctorResult with optional suggestions.
+func warn(name, message string, suggestions ...string) DoctorResult {
+	return DoctorResult{Name: name, Status: statusWarn, Message: message, Suggestions: suggestions}
+}
+
+// fail builds a failing DoctorResult with optional suggestions.
+func fail(name, message string, suggestions ...string) DoctorResult {
+	return DoctorResult{Name: name, Status: statusFail, Message: message, Suggestions: suggestions}
+}
+
 // runDoctorCheck performs comprehensive pre-flight checks for integration testing.
 func runDoctorCheck(ctx context.Context) error {
 	results := []DoctorResult{}
@@ -31,27 +61,28 @@ func runDoctorCheck(ctx context.Context) error {
 	results = append(results, dockerResult)
 
 	// If Docker is available, run additional checks
-	if dockerResult.Status == "PASS" {
+	if dockerResult.Status == statusPass {
 		results = append(results, checkDockerContext(ctx))
 		results = append(results, checkDockerSocket(ctx))
+		results = append(results, checkDockerHubCredentials())
 		results = append(results, checkGolangImage(ctx))
 	}
 
 	// Check 3: Go installation
-	results = append(results, checkGoInstallation())
+	results = append(results, checkGoInstallation(ctx))
 
 	// Check 4: Git repository
-	results = append(results, checkGitRepository())
+	results = append(results, checkGitRepository(ctx))
 
 	// Check 5: Required files
-	results = append(results, checkRequiredFiles())
+	results = append(results, checkRequiredFiles(ctx))
 
 	// Display results
 	displayDoctorResults(results)
 
 	// Return error if any critical checks failed
 	for _, result := range results {
-		if result.Status == "FAIL" {
+		if result.Status == statusFail {
 			return fmt.Errorf("%w - see details above", ErrSystemChecksFailed)
 		}
 	}
@@ -65,140 +96,115 @@ func runDoctorCheck(ctx context.Context) error {
 func checkDockerBinary() DoctorResult {
 	_, err := exec.LookPath("docker")
 	if err != nil {
-		return DoctorResult{
-			Name:    "Docker Binary",
-			Status:  "FAIL",
-			Message: "Docker binary not found in PATH",
-			Suggestions: []string{
-				"Install Docker: https://docs.docker.com/get-docker/",
-				"For macOS: consider using colima or Docker Desktop",
-				"Ensure docker is in your PATH",
-			},
-		}
+		return fail(
+			"Docker Binary",
+			"Docker binary not found in PATH",
+			"Install Docker: https://docs.docker.com/get-docker/",
+			"For macOS: consider using colima or Docker Desktop",
+			"Ensure docker is in your PATH",
+		)
 	}
 
-	return DoctorResult{
-		Name:    "Docker Binary",
-		Status:  "PASS",
-		Message: "Docker binary found",
-	}
+	return pass("Docker Binary", "Docker binary found")
 }
 
 // checkDockerDaemon verifies Docker daemon is running and accessible.
 func checkDockerDaemon(ctx context.Context) DoctorResult {
-	cli, err := createDockerClient()
+	cli, err := createDockerClient(ctx)
 	if err != nil {
-		return DoctorResult{
-			Name:    "Docker Daemon",
-			Status:  "FAIL",
-			Message: fmt.Sprintf("Cannot create Docker client: %v", err),
-			Suggestions: []string{
-				"Start Docker daemon/service",
-				"Check Docker Desktop is running (if using Docker Desktop)",
-				"For colima: run 'colima start'",
-				"Verify DOCKER_HOST environment variable if set",
-			},
-		}
+		return fail(
+			nameDockerDaemon,
+			fmt.Sprintf("Cannot create Docker client: %v", err),
+			"Start Docker daemon/service",
+			"Check Docker Desktop is running (if using Docker Desktop)",
+			"For colima: run 'colima start'",
+			"Verify DOCKER_HOST environment variable if set",
+		)
 	}
 	defer cli.Close()
 
 	_, err = cli.Ping(ctx)
 	if err != nil {
-		return DoctorResult{
-			Name:    "Docker Daemon",
-			Status:  "FAIL",
-			Message: fmt.Sprintf("Cannot ping Docker daemon: %v", err),
-			Suggestions: []string{
-				"Ensure Docker daemon is running",
-				"Check Docker socket permissions",
-				"Try: docker info",
-			},
-		}
+		return fail(
+			nameDockerDaemon,
+			fmt.Sprintf("Cannot ping Docker daemon: %v", err),
+			"Ensure Docker daemon is running",
+			"Check Docker socket permissions",
+			"Try: docker info",
+		)
 	}
 
-	return DoctorResult{
-		Name:    "Docker Daemon",
-		Status:  "PASS",
-		Message: "Docker daemon is running and accessible",
-	}
+	return pass(nameDockerDaemon, "Docker daemon is running and accessible")
 }
 
 // checkDockerContext verifies Docker context configuration.
-func checkDockerContext(_ context.Context) DoctorResult {
-	contextInfo, err := getCurrentDockerContext()
+func checkDockerContext(ctx context.Context) DoctorResult {
+	contextInfo, err := getCurrentDockerContext(ctx)
 	if err != nil {
-		return DoctorResult{
-			Name:    "Docker Context",
-			Status:  "WARN",
-			Message: "Could not detect Docker context, using default settings",
-			Suggestions: []string{
-				"Check: docker context ls",
-				"Consider setting up a specific context if needed",
-			},
-		}
+		return warn(
+			nameDockerContext,
+			"Could not detect Docker context, using default settings",
+			"Check: docker context ls",
+			"Consider setting up a specific context if needed",
+		)
 	}
 
 	if contextInfo == nil {
-		return DoctorResult{
-			Name:    "Docker Context",
-			Status:  "PASS",
-			Message: "Using default Docker context",
-		}
+		return pass(nameDockerContext, "Using default Docker context")
 	}
 
-	return DoctorResult{
-		Name:    "Docker Context",
-		Status:  "PASS",
-		Message: "Using Docker context: " + contextInfo.Name,
-	}
+	return pass(nameDockerContext, "Using Docker context: "+contextInfo.Name)
 }
 
 // checkDockerSocket verifies Docker socket accessibility.
 func checkDockerSocket(ctx context.Context) DoctorResult {
-	cli, err := createDockerClient()
+	cli, err := createDockerClient(ctx)
 	if err != nil {
-		return DoctorResult{
-			Name:    "Docker Socket",
-			Status:  "FAIL",
-			Message: fmt.Sprintf("Cannot access Docker socket: %v", err),
-			Suggestions: []string{
-				"Check Docker socket permissions",
-				"Add user to docker group: sudo usermod -aG docker $USER",
-				"For colima: ensure socket is accessible",
-			},
-		}
+		return fail(
+			nameDockerSocket,
+			fmt.Sprintf("Cannot access Docker socket: %v", err),
+			"Check Docker socket permissions",
+			"Add user to docker group: sudo usermod -aG docker $USER",
+			"For colima: ensure socket is accessible",
+		)
 	}
 	defer cli.Close()
 
 	info, err := cli.Info(ctx)
 	if err != nil {
-		return DoctorResult{
-			Name:    "Docker Socket",
-			Status:  "FAIL",
-			Message: fmt.Sprintf("Cannot get Docker info: %v", err),
-			Suggestions: []string{
-				"Check Docker daemon status",
-				"Verify socket permissions",
-			},
-		}
+		return fail(
+			nameDockerSocket,
+			fmt.Sprintf("Cannot get Docker info: %v", err),
+			"Check Docker daemon status",
+			"Verify socket permissions",
+		)
 	}
 
-	return DoctorResult{
-		Name:    "Docker Socket",
-		Status:  "PASS",
-		Message: fmt.Sprintf("Docker socket accessible (Server: %s)", info.ServerVersion),
+	return pass(nameDockerSocket, fmt.Sprintf("Docker socket accessible (Server: %s)", info.ServerVersion))
+}
+
+// checkDockerHubCredentials warns when pulls would be anonymous and
+// therefore rate-limited.
+func checkDockerHubCredentials() DoctorResult {
+	_, _, source := dockertestutil.Credentials()
+	if source == dockertestutil.CredentialSourceAnonymous {
+		return warn(
+			"Docker Hub Credentials",
+			"No Docker Hub credentials found — pulls will be rate-limited (100/6h per IP)",
+			"Run: docker login",
+			"Or export DOCKERHUB_USERNAME and DOCKERHUB_TOKEN",
+			"In CI: ensure the docker/login-action step is configured with secrets",
+		)
 	}
+
+	return pass("Docker Hub Credentials", fmt.Sprintf("Credentials available (source: %s)", source))
 }
 
 // checkGolangImage verifies the golang Docker image is available locally or can be pulled.
 func checkGolangImage(ctx context.Context) DoctorResult {
-	cli, err := createDockerClient()
+	cli, err := createDockerClient(ctx)
 	if err != nil {
-		return DoctorResult{
-			Name:    "Golang Image",
-			Status:  "FAIL",
-			Message: "Cannot create Docker client for image check",
-		}
+		return fail(nameGolangImage, "Cannot create Docker client for image check")
 	}
 	defer cli.Close()
 
@@ -208,107 +214,77 @@ func checkGolangImage(ctx context.Context) DoctorResult {
 	// First check if image is available locally
 	available, err := checkImageAvailableLocally(ctx, cli, imageName)
 	if err != nil {
-		return DoctorResult{
-			Name:    "Golang Image",
-			Status:  "FAIL",
-			Message: fmt.Sprintf("Cannot check golang image %s: %v", imageName, err),
-			Suggestions: []string{
-				"Check Docker daemon status",
-				"Try: docker images | grep golang",
-			},
-		}
+		return fail(
+			nameGolangImage,
+			fmt.Sprintf("Cannot check golang image %s: %v", imageName, err),
+			"Check Docker daemon status",
+			"Try: docker images | grep golang",
+		)
 	}
 
 	if available {
-		return DoctorResult{
-			Name:    "Golang Image",
-			Status:  "PASS",
-			Message: fmt.Sprintf("Golang image %s is available locally", imageName),
-		}
+		return pass(nameGolangImage, fmt.Sprintf("Golang image %s is available locally", imageName))
 	}
 
 	// Image not available locally, try to pull it
 	err = ensureImageAvailable(ctx, cli, imageName, false)
 	if err != nil {
-		return DoctorResult{
-			Name:    "Golang Image",
-			Status:  "FAIL",
-			Message: fmt.Sprintf("Golang image %s not available locally and cannot pull: %v", imageName, err),
-			Suggestions: []string{
-				"Check internet connectivity",
-				"Verify Docker Hub access",
-				"Try: docker pull " + imageName,
-				"Or run tests offline if image was pulled previously",
-			},
-		}
+		return fail(
+			nameGolangImage,
+			fmt.Sprintf("Golang image %s not available locally and cannot pull: %v", imageName, err),
+			"Check internet connectivity",
+			"Verify Docker Hub access",
+			"Try: docker pull "+imageName,
+			"Or run tests offline if image was pulled previously",
+		)
 	}
 
-	return DoctorResult{
-		Name:    "Golang Image",
-		Status:  "PASS",
-		Message: fmt.Sprintf("Golang image %s is now available", imageName),
-	}
+	return pass(nameGolangImage, fmt.Sprintf("Golang image %s is now available", imageName))
 }
 
 // checkGoInstallation verifies Go is installed and working.
-func checkGoInstallation() DoctorResult {
+func checkGoInstallation(ctx context.Context) DoctorResult {
 	_, err := exec.LookPath("go")
 	if err != nil {
-		return DoctorResult{
-			Name:    "Go Installation",
-			Status:  "FAIL",
-			Message: "Go binary not found in PATH",
-			Suggestions: []string{
-				"Install Go: https://golang.org/dl/",
-				"Ensure go is in your PATH",
-			},
-		}
+		return fail(
+			nameGoInstall,
+			"Go binary not found in PATH",
+			"Install Go: https://golang.org/dl/",
+			"Ensure go is in your PATH",
+		)
 	}
 
-	cmd := exec.Command("go", "version")
+	cmd := exec.CommandContext(ctx, "go", "version")
+
 	output, err := cmd.Output()
 	if err != nil {
-		return DoctorResult{
-			Name:    "Go Installation",
-			Status:  "FAIL",
-			Message: fmt.Sprintf("Cannot get Go version: %v", err),
-		}
+		return fail(nameGoInstall, fmt.Sprintf("Cannot get Go version: %v", err))
 	}
 
 	version := strings.TrimSpace(string(output))
 
-	return DoctorResult{
-		Name:    "Go Installation",
-		Status:  "PASS",
-		Message: version,
-	}
+	return pass(nameGoInstall, version)
 }
 
 // checkGitRepository verifies we're in a git repository.
-func checkGitRepository() DoctorResult {
-	cmd := exec.Command("git", "rev-parse", "--git-dir")
+func checkGitRepository(ctx context.Context) DoctorResult {
+	cmd := exec.CommandContext(ctx, "git", "rev-parse", "--git-dir")
+
 	err := cmd.Run()
 	if err != nil {
-		return DoctorResult{
-			Name:    "Git Repository",
-			Status:  "FAIL",
-			Message: "Not in a Git repository",
-			Suggestions: []string{
-				"Run from within the headscale git repository",
-				"Clone the repository: git clone https://github.com/juanfont/headscale.git",
-			},
-		}
+		return fail(
+			"Git Repository",
+			"Not in a Git repository",
+			"Run from within the headscale git repository",
+			"Clone the repository: git clone https://github.com/juanfont/headscale.git",
+		)
 	}
 
-	return DoctorResult{
-		Name:    "Git Repository",
-		Status:  "PASS",
-		Message: "Running in Git repository",
-	}
+	return pass("Git Repository", "Running in Git repository")
 }
 
 // checkRequiredFiles verifies required files exist.
-func checkRequiredFiles() DoctorResult {
+func checkRequiredFiles(_ context.Context) DoctorResult {
 	requiredFiles := []string{
 		"go.mod",
 		"integration/",
@@ -316,31 +292,25 @@ func checkRequiredFiles() DoctorResult {
 	}
 
 	var missingFiles []string
+
 	for _, file := range requiredFiles {
-		cmd := exec.Command("test", "-e", file)
-		if err := cmd.Run(); err != nil {
+		_, err := os.Stat(file)
+		if err != nil {
 			missingFiles = append(missingFiles, file)
 		}
 	}
 
 	if len(missingFiles) > 0 {
-		return DoctorResult{
-			Name:    "Required Files",
-			Status:  "FAIL",
-			Message: "Missing required files: " + strings.Join(missingFiles, ", "),
-			Suggestions: []string{
-				"Ensure you're in the headscale project root directory",
-				"Check that integration/ directory exists",
-				"Verify this is a complete headscale repository",
-			},
-		}
+		return fail(
+			"Required Files",
+			"Missing required files: "+strings.Join(missingFiles, ", "),
+			"Ensure you're in the headscale project root directory",
+			"Check that integration/ directory exists",
+			"Verify this is a complete headscale repository",
+		)
 	}
 
-	return DoctorResult{
-		Name:    "Required Files",
-		Status:  "PASS",
-		Message: "All required files found",
-	}
+	return pass("Required Files", "All required files found")
 }
 
 // displayDoctorResults shows the results in a formatted way.
@@ -350,12 +320,13 @@ func displayDoctorResults(results []DoctorResult) {
 
 	for _, result := range results {
 		var icon string
+
 		switch result.Status {
-		case "PASS":
+		case statusPass:
 			icon = "✅"
-		case "WARN":
+		case statusWarn:
 			icon = "⚠️"
-		case "FAIL":
+		case statusFail:
 			icon = "❌"
 		default:
 			icon = "❓"

cmd/hi/listversions.go

@@ -0,0 +1,89 @@
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/creachadair/command"
+	"github.com/juanfont/headscale/hscontrol/capver"
+)
+
+var (
+	errUnknownSet    = errors.New("unknown --set value (want must|all)")
+	errUnknownFormat = errors.New("unknown --format value (want space|newline|json)")
+)
+
+// ListVersionsConfig holds flags for the list-versions subcommand.
+type ListVersionsConfig struct {
+	Set     string `flag:"set,default=must,Version set: must|all"`
+	Exclude string `flag:"exclude,Comma-separated versions to exclude (e.g. head,unstable)"`
+	Format  string `flag:"format,default=space,Output format: space|newline|json"`
+}
+
+var listVersionsConfig ListVersionsConfig
+
+// listVersions prints the Tailscale versions used by integration tests
+// in a format CI can shell out to. Mirrors integration/scenario.go
+// AllVersions and MustTestVersions: "head" and "unstable" are bare
+// tags, releases get a "v" prefix so each entry can be appended to
+// "ghcr.io/tailscale/tailscale:" directly.
+func listVersions(env *command.Env) error {
+	release := capver.TailscaleLatestMajorMinor(capver.SupportedMajorMinorVersions, true)
+	all := append([]string{"head", "unstable"}, release...)
+	must := append(append([]string{}, all[0:4]...), all[len(all)-2:]...)
+
+	var versions []string
+
+	switch listVersionsConfig.Set {
+	case "must":
+		versions = must
+	case "all":
+		versions = all
+	default:
+		return fmt.Errorf("%w: %q", errUnknownSet, listVersionsConfig.Set)
+	}
+
+	excluded := make(map[string]bool)
+
+	if listVersionsConfig.Exclude != "" {
+		for v := range strings.SplitSeq(listVersionsConfig.Exclude, ",") {
+			excluded[strings.TrimSpace(v)] = true
+		}
+	}
+
+	out := make([]string, 0, len(versions))
+
+	for _, v := range versions {
+		if excluded[v] {
+			continue
+		}
+
+		if v != "head" && v != "unstable" {
+			v = "v" + v
+		}
+
+		out = append(out, v)
+	}
+
+	switch listVersionsConfig.Format {
+	case "space":
+		fmt.Println(strings.Join(out, " "))
+	case "newline":
+		for _, v := range out {
+			fmt.Println(v)
+		}
+	case "json":
+		b, err := json.Marshal(out)
+		if err != nil {
+			return err
+		}
+
+		fmt.Println(string(b))
+	default:
+		return fmt.Errorf("%w: %q", errUnknownFormat, listVersionsConfig.Format)
+	}
+
+	return nil
+}

cmd/hi/main.go

@@ -29,6 +29,13 @@ func main() {
 					return runDoctorCheck(env.Context())
 				},
 			},
+			{
+				Name:     "list-versions",
+				Help:     "Print Tailscale versions used by integration tests",
+				Usage:    "list-versions [flags]",
+				SetFlags: command.Flags(flax.MustBind, &listVersionsConfig),
+				Run:      listVersions,
+			},
 			{
 				Name: "clean",
 				Help: "Clean Docker resources",
@@ -79,15 +86,17 @@ func main() {
 }
 
 func cleanAll(ctx context.Context) error {
-	if err := killTestContainers(ctx); err != nil {
-		return err
-	}
-	if err := pruneDockerNetworks(ctx); err != nil {
-		return err
-	}
-	if err := cleanOldImages(ctx); err != nil {
-		return err
+	for _, step := range []func(context.Context) error{
+		killTestContainers,
+		pruneDockerNetworks,
+		cleanOldImages,
+		cleanCacheVolume,
+	} {
+		err := step(ctx)
+		if err != nil {
+			return err
+		}
 	}
 
-	return cleanCacheVolume(ctx)
+	return nil
 }

cmd/hi/run.go

@@ -6,6 +6,7 @@ import (
 	"log"
 	"os"
 	"path/filepath"
+	"strings"
 	"time"
 
 	"github.com/creachadair/command"
@@ -48,7 +49,9 @@ func runIntegrationTest(env *command.Env) error {
 	if runConfig.Verbose {
 		log.Printf("Running pre-flight system checks...")
 	}
-	if err := runDoctorCheck(env.Context()); err != nil {
+
+	err := runDoctorCheck(env.Context())
+	if err != nil {
 		return fmt.Errorf("pre-flight checks failed: %w", err)
 	}
 
@@ -64,62 +67,21 @@ func runIntegrationTest(env *command.Env) error {
 
 // detectGoVersion reads the Go version from go.mod file.
 func detectGoVersion() string {
-	goModPath := filepath.Join("..", "..", "go.mod")
-
-	if _, err := os.Stat("go.mod"); err == nil {
-		goModPath = "go.mod"
-	} else if _, err := os.Stat("../../go.mod"); err == nil {
-		goModPath = "../../go.mod"
-	}
-
-	content, err := os.ReadFile(goModPath)
+	content, err := os.ReadFile("go.mod")
 	if err != nil {
-		return "1.25"
+		content, err = os.ReadFile(filepath.Join("..", "..", "go.mod"))
+		if err != nil {
+			return "1.26.1"
+		}
 	}
 
-	lines := splitLines(string(content))
-	for _, line := range lines {
-		if len(line) > 3 && line[:3] == "go " {
-			version := line[3:]
-			if idx := indexOf(version, " "); idx != -1 {
-				version = version[:idx]
+	for line := range strings.Lines(string(content)) {
+		if rest, ok := strings.CutPrefix(line, "go "); ok {
+			if f := strings.Fields(rest); len(f) > 0 {
+				return f[0]
 			}
-
-			return version
 		}
 	}
 
-	return "1.25"
-}
-
-// splitLines splits a string into lines without using strings.Split.
-func splitLines(s string) []string {
-	var lines []string
-	var current string
-
-	for _, char := range s {
-		if char == '\n' {
-			lines = append(lines, current)
-			current = ""
-		} else {
-			current += string(char)
-		}
-	}
-
-	if current != "" {
-		lines = append(lines, current)
-	}
-
-	return lines
-}
-
-// indexOf finds the first occurrence of substr in s.
-func indexOf(s, substr string) int {
-	for i := 0; i <= len(s)-len(substr); i++ {
-		if s[i:i+len(substr)] == substr {
-			return i
-		}
-	}
-
-	return -1
+	return "1.26.1"
 }

cmd/hi/stats.go

@@ -1,12 +1,13 @@
 package main
 
 import (
+	"cmp"
 	"context"
 	"encoding/json"
 	"errors"
 	"fmt"
 	"log"
-	"sort"
+	"slices"
 	"strings"
 	"sync"
 	"time"
@@ -18,6 +19,9 @@ import (
 	"github.com/docker/docker/client"
 )
 
+// ErrStatsCollectionAlreadyStarted is returned when trying to start stats collection that is already running.
+var ErrStatsCollectionAlreadyStarted = errors.New("stats collection already started")
+
 // ContainerStats represents statistics for a single container.
 type ContainerStats struct {
 	ContainerID   string
@@ -44,10 +48,10 @@ type StatsCollector struct {
 }
 
 // NewStatsCollector creates a new stats collector instance.
-func NewStatsCollector() (*StatsCollector, error) {
-	cli, err := createDockerClient()
+func NewStatsCollector(ctx context.Context) (*StatsCollector, error) {
+	cli, err := createDockerClient(ctx)
 	if err != nil {
-		return nil, fmt.Errorf("failed to create Docker client: %w", err)
+		return nil, fmt.Errorf("creating Docker client: %w", err)
 	}
 
 	return &StatsCollector{
@@ -63,17 +67,19 @@ func (sc *StatsCollector) StartCollection(ctx context.Context, runID string, ver
 	defer sc.mutex.Unlock()
 
 	if sc.collectionStarted {
-		return errors.New("stats collection already started")
+		return ErrStatsCollectionAlreadyStarted
 	}
 
 	sc.collectionStarted = true
 
 	// Start monitoring existing containers
 	sc.wg.Add(1)
+
 	go sc.monitorExistingContainers(ctx, runID, verbose)
 
 	// Start Docker events monitoring for new containers
 	sc.wg.Add(1)
+
 	go sc.monitorDockerEvents(ctx, runID, verbose)
 
 	if verbose {
@@ -87,10 +93,12 @@ func (sc *StatsCollector) StartCollection(ctx context.Context, runID string, ver
 func (sc *StatsCollector) StopCollection() {
 	// Check if already stopped without holding lock
 	sc.mutex.RLock()
+
 	if !sc.collectionStarted {
 		sc.mutex.RUnlock()
 		return
 	}
+
 	sc.mutex.RUnlock()
 
 	// Signal stop to all goroutines
@@ -114,6 +122,7 @@ func (sc *StatsCollector) monitorExistingContainers(ctx context.Context, runID s
 		if verbose {
 			log.Printf("Failed to list existing containers: %v", err)
 		}
+
 		return
 	}
 
@@ -147,13 +156,13 @@ func (sc *StatsCollector) monitorDockerEvents(ctx context.Context, runID string,
 		case event := <-events:
 			if event.Type == "container" && event.Action == "start" {
 				// Get container details
-				containerInfo, err := sc.client.ContainerInspect(ctx, event.ID)
+				containerInfo, err := sc.client.ContainerInspect(ctx, event.ID) //nolint:staticcheck // SA1019: use Actor.ID
 				if err != nil {
 					continue
 				}
 
-				// Convert to types.Container format for consistency
-				cont := types.Container{
+				// Convert to [types.Container] format for consistency
+				cont := types.Container{ //nolint:staticcheck // SA1019: use container.Summary
 					ID:     containerInfo.ID,
 					Names:  []string{containerInfo.Name},
 					Labels: containerInfo.Config.Labels,
@@ -167,13 +176,14 @@ func (sc *StatsCollector) monitorDockerEvents(ctx context.Context, runID string,
 			if verbose {
 				log.Printf("Error in Docker events stream: %v", err)
 			}
+
 			return
 		}
 	}
 }
 
 // shouldMonitorContainer determines if a container should be monitored.
-func (sc *StatsCollector) shouldMonitorContainer(cont types.Container, runID string) bool {
+func (sc *StatsCollector) shouldMonitorContainer(cont types.Container, runID string) bool { //nolint:staticcheck // SA1019: use container.Summary
 	// Check if it has the correct run ID label
 	if cont.Labels == nil || cont.Labels["hi.run-id"] != runID {
 		return false
@@ -213,6 +223,7 @@ func (sc *StatsCollector) startStatsForContainer(ctx context.Context, containerI
 	}
 
 	sc.wg.Add(1)
+
 	go sc.collectStatsForContainer(ctx, containerID, verbose)
 }
 
@@ -226,12 +237,14 @@ func (sc *StatsCollector) collectStatsForContainer(ctx context.Context, containe
 		if verbose {
 			log.Printf("Failed to get stats stream for container %s: %v", containerID[:12], err)
 		}
+
 		return
 	}
 	defer statsResponse.Body.Close()
 
 	decoder := json.NewDecoder(statsResponse.Body)
-	var prevStats *container.Stats
+
+	var prevStats *container.Stats //nolint:staticcheck // SA1019: use StatsResponse
 
 	for {
 		select {
@@ -240,12 +253,15 @@ func (sc *StatsCollector) collectStatsForContainer(ctx context.Context, containe
 		case <-ctx.Done():
 			return
 		default:
-			var stats container.Stats
-			if err := decoder.Decode(&stats); err != nil {
-				// EOF is expected when container stops or stream ends
+			var stats container.Stats //nolint:staticcheck // SA1019: use StatsResponse
+
+			err := decoder.Decode(&stats)
+			if err != nil {
+				// [io.EOF] is expected when container stops or stream ends
 				if err.Error() != "EOF" && verbose {
 					log.Printf("Failed to decode stats for container %s: %v", containerID[:12], err)
 				}
+
 				return
 			}
 
@@ -261,8 +277,10 @@ func (sc *StatsCollector) collectStatsForContainer(ctx context.Context, containe
 			// Store the sample (skip first sample since CPU calculation needs previous stats)
 			if prevStats != nil {
 				// Get container stats reference without holding the main mutex
-				var containerStats *ContainerStats
-				var exists bool
+				var (
+					containerStats *ContainerStats
+					exists         bool
+				)
 
 				sc.mutex.RLock()
 				containerStats, exists = sc.containers[containerID]
@@ -286,7 +304,7 @@ func (sc *StatsCollector) collectStatsForContainer(ctx context.Context, containe
 }
 
 // calculateCPUPercent calculates CPU usage percentage from Docker stats.
-func calculateCPUPercent(prevStats, stats *container.Stats) float64 {
+func calculateCPUPercent(prevStats, stats *container.Stats) float64 { //nolint:staticcheck // SA1019: use StatsResponse
 	// CPU calculation based on Docker's implementation
 	cpuDelta := float64(stats.CPUStats.CPUUsage.TotalUsage) - float64(prevStats.CPUStats.CPUUsage.TotalUsage)
 	systemDelta := float64(stats.CPUStats.SystemUsage) - float64(prevStats.CPUStats.SystemUsage)
@@ -295,7 +313,7 @@ func calculateCPUPercent(prevStats, stats *container.Stats) float64 {
 		// Calculate CPU percentage: (container CPU delta / system CPU delta) * number of CPUs * 100
 		numCPUs := float64(len(stats.CPUStats.CPUUsage.PercpuUsage))
 		if numCPUs == 0 {
-			// Fallback: if PercpuUsage is not available, assume 1 CPU
+			// Fallback: if [PercpuUsage] is not available, assume 1 CPU
 			numCPUs = 1.0
 		}
 
@@ -331,10 +349,12 @@ type StatsSummary struct {
 func (sc *StatsCollector) GetSummary() []ContainerStatsSummary {
 	// Take snapshot of container references without holding main lock long
 	sc.mutex.RLock()
+
 	containerRefs := make([]*ContainerStats, 0, len(sc.containers))
 	for _, containerStats := range sc.containers {
 		containerRefs = append(containerRefs, containerStats)
 	}
+
 	sc.mutex.RUnlock()
 
 	summaries := make([]ContainerStatsSummary, 0, len(containerRefs))
@@ -355,24 +375,24 @@ func (sc *StatsCollector) GetSummary() []ContainerStatsSummary {
 			SampleCount:   len(stats),
 		}
 
-		// Calculate CPU stats
-		cpuValues := make([]float64, len(stats))
-		memoryValues := make([]float64, len(stats))
+		extract := func(get func(StatsSample) float64) []float64 {
+			values := make([]float64, len(stats))
+			for i, sample := range stats {
+				values[i] = get(sample)
+			}
 
-		for i, sample := range stats {
-			cpuValues[i] = sample.CPUUsage
-			memoryValues[i] = sample.MemoryMB
+			return values
 		}
 
-		summary.CPU = calculateStatsSummary(cpuValues)
-		summary.Memory = calculateStatsSummary(memoryValues)
+		summary.CPU = calculateStatsSummary(extract(func(s StatsSample) float64 { return s.CPUUsage }))
+		summary.Memory = calculateStatsSummary(extract(func(s StatsSample) float64 { return s.MemoryMB }))
 
 		summaries = append(summaries, summary)
 	}
 
 	// Sort by container name for consistent output
-	sort.Slice(summaries, func(i, j int) bool {
-		return summaries[i].ContainerName < summaries[j].ContainerName
+	slices.SortFunc(summaries, func(a, b ContainerStatsSummary) int {
+		return cmp.Compare(a.ContainerName, b.ContainerName)
 	})
 
 	return summaries
@@ -384,23 +404,19 @@ func calculateStatsSummary(values []float64) StatsSummary {
 		return StatsSummary{}
 	}
 
-	min := values[0]
-	max := values[0]
+	minVal := values[0]
+	maxVal := values[0]
 	sum := 0.0
 
 	for _, value := range values {
-		if value < min {
-			min = value
-		}
-		if value > max {
-			max = value
-		}
+		minVal = min(minVal, value)
+		maxVal = max(maxVal, value)
 		sum += value
 	}
 
 	return StatsSummary{
-		Min:     min,
-		Max:     max,
+		Min:     minVal,
+		Max:     maxVal,
 		Average: sum / float64(len(values)),
 	}
 }
@@ -434,6 +450,7 @@ func (sc *StatsCollector) CheckMemoryLimits(hsLimitMB, tsLimitMB float64) []Memo
 	}
 
 	summaries := sc.GetSummary()
+
 	var violations []MemoryViolation
 
 	for _, summary := range summaries {

cmd/mapresponses/main.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
 	"os"
 
@@ -15,7 +16,10 @@ type MapConfig struct {
 	Directory string `flag:"directory,Directory to read map responses from"`
 }
 
-var mapConfig MapConfig
+var (
+	mapConfig            MapConfig
+	errDirectoryRequired = errors.New("directory is required")
+)
 
 func main() {
 	root := command.C{
@@ -40,7 +44,7 @@ func main() {
 // runIntegrationTest executes the integration test workflow.
 func runOnline(env *command.Env) error {
 	if mapConfig.Directory == "" {
-		return fmt.Errorf("directory is required")
+		return errDirectoryRequired
 	}
 
 	resps, err := mapper.ReadMapResponsesFromDirectory(mapConfig.Directory)
@@ -57,5 +61,6 @@ func runOnline(env *command.Env) error {
 
 	os.Stderr.Write(out)
 	os.Stderr.Write([]byte("\n"))
+
 	return nil
 }

cmd/vendorhash/main.go

@@ -0,0 +1,221 @@
+// vendorhash maintains the Nix SRI hash for the Go module vendor tree
+// and stores it in flakehashes.json alongside a content fingerprint of
+// go.mod and go.sum.
+//
+// Each block records its input fingerprint (goModSum) so that re-runs
+// with no input change are essentially free: the fast path is just a
+// sha256 over two small files. The vendor tree is only re-walked when
+// the fingerprint actually drifts.
+//
+// Subcommands:
+//
+//	vendorhash check   exit non-zero if flakehashes.json is stale
+//	vendorhash update  recompute and rewrite flakehashes.json
+//
+// The JSON schema and [goModFingerprint] algorithm mirror upstream
+// tailscale's tool/updateflakes so a future shared library extraction
+// is straightforward.
+package main
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+
+	"tailscale.com/cmd/nardump/nardump"
+)
+
+const (
+	hashesFile = "flakehashes.json"
+	goModFile  = "go.mod"
+	goSumFile  = "go.sum"
+)
+
+type FlakeHashes struct {
+	Vendor VendorBlock `json:"vendor"`
+}
+
+type VendorBlock struct {
+	GoModSum string `json:"goModSum"`
+	SRI      string `json:"sri"`
+}
+
+func main() {
+	if len(os.Args) < 2 {
+		usage()
+		os.Exit(2)
+	}
+
+	ctx := context.Background()
+
+	var err error
+
+	switch os.Args[1] {
+	case "check":
+		err = cmdCheck(ctx)
+	case "update":
+		err = cmdUpdate(ctx)
+	case "-h", "--help", "help":
+		usage()
+		return
+	default:
+		usage()
+		os.Exit(2)
+	}
+
+	if err != nil {
+		if errors.Is(err, errStale) {
+			os.Exit(1)
+		}
+
+		fmt.Fprintln(os.Stderr, "vendorhash:", err)
+		os.Exit(1)
+	}
+}
+
+func usage() {
+	fmt.Fprintln(os.Stderr, "usage: vendorhash <check|update>")
+}
+
+// errStale signals to [main] that the check found a mismatch; it has
+// already printed a remediation message, so [main] should exit 1
+// silently.
+var errStale = errors.New("vendor hash stale")
+
+// cmdCheck verifies that flakehashes.json matches the current
+// go.mod/go.sum. The fast path (fingerprint unchanged) costs only
+// a sha256 over the two files. On mismatch, it computes the actual
+// SRI so the failure message gives the developer the value to paste
+// (or to run `vendorhash update`).
+func cmdCheck(ctx context.Context) error {
+	hashes, err := loadHashes()
+	if err != nil {
+		return err
+	}
+
+	curFP, err := goModFingerprint()
+	if err != nil {
+		return err
+	}
+
+	if curFP == hashes.Vendor.GoModSum {
+		return nil
+	}
+
+	curSRI, err := hashVendor(ctx)
+	if err != nil {
+		return err
+	}
+
+	fmt.Fprintln(os.Stderr, "vendor hash is stale.")
+	fmt.Fprintf(os.Stderr, "  expected goModSum: %s\n", hashes.Vendor.GoModSum)
+	fmt.Fprintf(os.Stderr, "    actual goModSum: %s\n", curFP)
+	fmt.Fprintf(os.Stderr, "       expected sri: %s\n", hashes.Vendor.SRI)
+	fmt.Fprintf(os.Stderr, "         actual sri: %s\n", curSRI)
+	fmt.Fprintln(os.Stderr, "run: go run ./cmd/vendorhash update")
+	// Also emit machine-parseable lines so CI can pick them up.
+	fmt.Printf("expected_sri=%s\n", hashes.Vendor.SRI)
+	fmt.Printf("actual_sri=%s\n", curSRI)
+
+	return errStale
+}
+
+func cmdUpdate(ctx context.Context) error {
+	fp, err := goModFingerprint()
+	if err != nil {
+		return err
+	}
+
+	sri, err := hashVendor(ctx)
+	if err != nil {
+		return err
+	}
+
+	return writeHashes(FlakeHashes{
+		Vendor: VendorBlock{
+			GoModSum: fp,
+			SRI:      sri,
+		},
+	})
+}
+
+// goModFingerprint returns a content fingerprint of go.mod and go.sum
+// that changes whenever either file changes. The byte layout matches
+// upstream tailscale's tool/updateflakes.
+func goModFingerprint() (string, error) {
+	h := sha256.New()
+
+	for _, f := range []string{goModFile, goSumFile} {
+		b, err := os.ReadFile(f)
+		if err != nil {
+			return "", err
+		}
+
+		fmt.Fprintf(h, "%s %d\n", f, len(b))
+		h.Write(b)
+	}
+
+	return "sha256-" + base64.StdEncoding.EncodeToString(h.Sum(nil)), nil
+}
+
+// hashVendor runs `go mod vendor` into a temporary directory and
+// returns the Nix SRI hash of the resulting tree.
+func hashVendor(ctx context.Context) (string, error) {
+	out, err := os.MkdirTemp("", "nar-vendor-")
+	if err != nil {
+		return "", err
+	}
+	// `go mod vendor -o` requires the destination to not already exist.
+	err = os.Remove(out)
+	if err != nil {
+		return "", err
+	}
+
+	defer os.RemoveAll(out)
+
+	cmd := exec.CommandContext(ctx, "go", "mod", "vendor", "-o", out)
+
+	cmd.Env = append(os.Environ(), "GOWORK=off")
+	cmd.Stderr = os.Stderr
+
+	err = cmd.Run()
+	if err != nil {
+		return "", fmt.Errorf("go mod vendor: %w", err)
+	}
+
+	return nardump.SRI(os.DirFS(out))
+}
+
+func loadHashes() (FlakeHashes, error) {
+	var h FlakeHashes
+
+	b, err := os.ReadFile(hashesFile)
+	if err != nil {
+		return h, err
+	}
+
+	err = json.Unmarshal(b, &h)
+	if err != nil {
+		return h, fmt.Errorf("%s: %w", hashesFile, err)
+	}
+
+	return h, nil
+}
+
+func writeHashes(h FlakeHashes) error {
+	b, err := json.MarshalIndent(h, "", "  ")
+	if err != nil {
+		return err
+	}
+
+	b = append(b, '\n')
+
+	// flakehashes.json is committed source read by Nix during evaluation;
+	// world-readable matches every other tracked file in the repo.
+	return os.WriteFile(hashesFile, b, 0o644) //nolint:gosec
+}

config-example.yaml

@@ -20,24 +20,15 @@ listen_addr: 127.0.0.1:8080
 
 # Address to listen to /metrics and /debug, you may want
 # to keep this endpoint private to your internal network
-# Use an emty value to disable the metrics listener.
+# Use an empty value to disable the metrics listener.
 metrics_listen_addr: 127.0.0.1:9090
 
-# Address to listen for gRPC.
-# gRPC is used for controlling a headscale server
-# remotely with the CLI
-# Note: Remote access _only_ works if you have
-# valid certificates.
-#
-# For production:
-# grpc_listen_addr: 0.0.0.0:50443
-grpc_listen_addr: 127.0.0.1:50443
-
-# Allow the gRPC admin interface to run in INSECURE
-# mode. This is not recommended as the traffic will
-# be unencrypted. Only enable if you know what you
-# are doing.
-grpc_allow_insecure: false
+# CIDR(s) of reverse proxies (e.g. 127.0.0.1/32) whose
+# True-Client-IP, X-Real-IP and X-Forwarded-For headers should
+# be honoured. Empty (default) ignores those headers; setting
+# this without a proxy in front lets clients spoof their logged
+# source IP.
+trusted_proxies: []
 
 # The Noise section includes specific configuration for the
 # TS2021 Noise protocol
@@ -50,12 +41,21 @@ noise:
 # List of IP prefixes to allocate tailaddresses from.
 # Each prefix consists of either an IPv4 or IPv6 address,
 # and the associated prefix length, delimited by a slash.
-# It must be within IP ranges supported by the Tailscale
-# client - i.e., subnets of 100.64.0.0/10 and fd7a:115c:a1e0::/48.
-# See below:
-# IPv6: https://github.com/tailscale/tailscale/blob/22ebb25e833264f58d7c3f534a8b166894a89536/net/tsaddr/tsaddr.go#LL81C52-L81C71
+#
+# WARNING: These prefixes MUST be subsets of the standard Tailscale ranges:
+#   - IPv4: 100.64.0.0/10 (CGNAT range)
+#   - IPv6: fd7a:115c:a1e0::/48 (Tailscale ULA range)
+#
+# Using a SUBSET of these ranges is supported and useful if you want to
+# limit IP allocation to a smaller block (e.g., 100.64.0.0/24).
+#
+# Using ranges OUTSIDE of CGNAT/ULA is NOT supported and will cause
+# undefined behaviour. The Tailscale client has hard-coded assumptions
+# about these ranges and will break in subtle, hard-to-debug ways.
+#
+# See:
 # IPv4: https://github.com/tailscale/tailscale/blob/22ebb25e833264f58d7c3f534a8b166894a89536/net/tsaddr/tsaddr.go#L33
-# Any other range is NOT supported, and it will cause unexpected issues.
+# IPv6: https://github.com/tailscale/tailscale/blob/22ebb25e833264f58d7c3f534a8b166894a89536/net/tsaddr/tsaddr.go#LL81C52-L81C71
 prefixes:
   v4: 100.64.0.0/10
   v6: fd7a:115c:a1e0::/48
@@ -71,8 +71,7 @@ prefixes:
 # connection cannot be established.
 # https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp
 #
-# headscale needs a list of DERP servers that can be presented
-# to the clients.
+# Headscale needs a list of DERP servers that can be presented to the clients.
 derp:
   server:
     # If enabled, runs the embedded DERP server and merges it into the rest of the DERP config
@@ -117,9 +116,9 @@ derp:
 
   # Locally available DERP map files encoded in YAML
   #
-  # This option is mostly interesting for people hosting
-  # their own DERP servers:
-  # https://tailscale.com/kb/1118/custom-derp-servers/
+  # This option is mostly interesting for people hosting their own DERP servers:
+  # https://tailscale.com/docs/reference/derp-servers/custom-derp-servers
+  # https://headscale.net/stable/ref/derp/
   #
   # paths:
   #   - /etc/headscale/derp-example.yaml
@@ -136,8 +135,45 @@ derp:
 # Disables the automatic check for headscale updates on startup
 disable_check_updates: false
 
-# Time before an inactive ephemeral node is deleted?
-ephemeral_node_inactivity_timeout: 30m
+# Node lifecycle configuration.
+node:
+  # Default key expiry for non-tagged nodes, regardless of registration method
+  # (auth key, CLI, web auth). Tagged nodes are exempt and never expire.
+  #
+  # This is the base default. OIDC can override this via oidc.expiry.
+  # If a client explicitly requests a specific expiry, the client value is used.
+  #
+  # Setting the value to "0" means no default expiry (nodes never expire unless
+  # explicitly expired via `headscale nodes expire`).
+  #
+  # Tailscale SaaS uses 180d; set to a positive duration to match that behaviour.
+  #
+  # Default: 0 (no default expiry)
+  expiry: 0
+
+  ephemeral:
+    # Time before an inactive ephemeral node is deleted.
+    inactivity_timeout: 30m
+
+  # HA subnet router health probing.
+  #
+  # When HA routes exist (2+ nodes advertising the same prefix), headscale
+  # pings each HA node every probe_interval via the Noise channel. If a node
+  # fails to respond within probe_timeout it is marked unhealthy and the
+  # primary role moves to the next healthy node. A node that later responds
+  # is marked healthy again but does NOT reclaim primary (avoids flapping).
+  #
+  # Worst-case detection time is probe_interval + probe_timeout (15s default).
+  # No-op when no HA routes exist. Set probe_interval to 0 to disable.
+  routes:
+    ha:
+      # How often to ping HA subnet routers. Set to 0 to disable probing.
+      # Must be >= 2s when enabled.
+      probe_interval: 10s
+
+      # How long to wait for a ping response before marking a node unhealthy.
+      # Must be >= 1s and less than probe_interval.
+      probe_timeout: 5s
 
 database:
   # Database type. Available options: sqlite, postgres
@@ -216,7 +252,7 @@ tls_letsencrypt_cache_dir: /var/lib/headscale/cache
 
 # Type of ACME challenge to use, currently supported types:
 # HTTP-01 or TLS-ALPN-01
-# See: docs/ref/tls.md for more information
+# See: https://headscale.net/stable/ref/tls/
 tls_letsencrypt_challenge_type: HTTP-01
 # When HTTP-01 challenge is chosen, letsencrypt must set up a
 # verification endpoint, and it will be listening on:
@@ -235,25 +271,24 @@ log:
   format: text
 
 ## Policy
-# headscale supports Tailscale's ACL policies.
-# Please have a look to their KB to better
-# understand the concepts: https://tailscale.com/kb/1018/acls/
+# Headscale supports a wide range of Tailscale policy features such as ACLs and
+# Grants. Please have a look at their docs to better understand the concepts:
+# ACLs: https://tailscale.com/docs/features/access-control/acls
+# Grants: https://tailscale.com/docs/features/access-control/grants
 policy:
   # The mode can be "file" or "database" that defines
-  # where the ACL policies are stored and read from.
+  # where the policies are stored and read from.
   mode: file
-  # If the mode is set to "file", the path to a
-  # HuJSON file containing ACL policies.
+  # If the mode is set to "file", the path to a HuJSON file containing policies.
   path: ""
 
 ## DNS
 #
 # headscale supports Tailscale's DNS configuration and MagicDNS.
-# Please have a look to their KB to better understand the concepts:
+# Please have a look to their docs to better understand the concepts:
 #
-# - https://tailscale.com/kb/1054/dns/
-# - https://tailscale.com/kb/1081/magicdns/
-# - https://tailscale.com/blog/2021-09-private-dns-with-magicdns/
+# - https://tailscale.com/docs/features/magicdns
+# - https://tailscale.com/blog/2021-09-private-dns-with-magicdns
 #
 # Please note that for the DNS configuration to have any effect,
 # clients must have the `--accept-dns=true` option enabled. This is the
@@ -263,12 +298,12 @@ policy:
 # Setting _any_ of the configuration and `--accept-dns=true` on the
 # clients will integrate with the DNS manager on the client or
 # overwrite /etc/resolv.conf.
-# https://tailscale.com/kb/1235/resolv-conf
+# https://tailscale.com/docs/reference/faq/dns-resolv-conf
 #
 # If you want stop Headscale from managing the DNS configuration
 # all the fields under `dns` should be set to empty values.
 dns:
-  # Whether to use [MagicDNS](https://tailscale.com/kb/1081/magicdns/).
+  # Whether to use MagicDNS
   magic_dns: true
 
   # Defines the base domain to create the hostnames for MagicDNS.
@@ -290,11 +325,11 @@ dns:
       - 2606:4700:4700::1111
       - 2606:4700:4700::1001
 
-      # NextDNS (see https://tailscale.com/kb/1218/nextdns/).
+      # NextDNS (see https://tailscale.com/docs/integrations/nextdns).
       # "abc123" is example NextDNS ID, replace with yours.
       # - https://dns.nextdns.io/abc123
 
-    # Split DNS (see https://tailscale.com/kb/1054/dns/),
+    # Split DNS (see https://tailscale.com/docs/reference/dns-in-tailscale#restricted-nameservers),
     # a map of domains and which DNS server to use for each.
     split: {}
       # foo.bar.com:
@@ -309,7 +344,7 @@ dns:
 
   # Extra DNS records
   # so far only A and AAAA records are supported (on the tailscale side)
-  # See: docs/ref/dns.md
+  # See: https://headscale.net/stable/ref/dns/
   extra_records: []
   #   - name: "grafana.myvpn.example.com"
   #     type: "A"
@@ -328,6 +363,7 @@ unix_socket: /var/run/headscale/headscale.sock
 unix_socket_permission: "0770"
 
 # OpenID Connect
+# https://headscale.net/stable/ref/oidc/
 # oidc:
 #   # Block startup until the identity provider is available and healthy.
 #   only_start_if_oidc_is_available: true
@@ -346,15 +382,11 @@ unix_socket_permission: "0770"
 #   # `LoadCredential` straightforward:
 #   client_secret_path: "${CREDENTIALS_DIRECTORY}/oidc_client_secret"
 #
-#   # The amount of time a node is authenticated with OpenID until it expires
-#   # and needs to reauthenticate.
-#   # Setting the value to "0" will mean no expiry.
-#   expiry: 180d
-#
 #   # Use the expiry from the token received from OpenID when the user logged
 #   # in. This will typically lead to frequent need to reauthenticate and should
 #   # only be enabled if you know what you are doing.
-#   # Note: enabling this will cause `oidc.expiry` to be ignored.
+#   # Note: enabling this will cause `node.expiry` to be ignored for
+#   # OIDC-authenticated nodes.
 #   use_expiry_from_token: false
 #
 #   # The OIDC scopes to use, defaults to "openid", "profile" and "email".
@@ -403,31 +435,41 @@ unix_socket_permission: "0770"
 # Logtail is Tailscales logging and auditing infrastructure, it allows the
 # control panel to instruct tailscale nodes to log their activity to a remote
 # server. To disable logging on the client side, please refer to:
-# https://tailscale.com/kb/1011/log-mesh-traffic#opting-out-of-client-logging
+# https://tailscale.com/docs/features/logging#opt-out-of-client-logging
 logtail:
   # Enable logtail for tailscale nodes of this Headscale instance.
   # As there is currently no support for overriding the log server in Headscale, this is
   # disabled by default. Enabling this will make your clients send logs to Tailscale Inc.
   enabled: false
 
-# Enabling this option makes devices prefer a random port for WireGuard traffic over the
-# default static port 41641. This option is intended as a workaround for some buggy
-# firewall devices. See https://tailscale.com/kb/1181/firewalls/ for more information.
-randomize_client_port: false
-
 # Taildrop configuration
-# Taildrop is the file sharing feature of Tailscale, allowing nodes to send files to each other.
-# https://tailscale.com/kb/1106/taildrop/
+# Taildrop is the file sharing feature of Tailscale, allowing nodes to
+# send files to each other.
+# https://tailscale.com/docs/features/taildrop
 taildrop:
-  # Enable or disable Taildrop for all nodes.
-  # When enabled, nodes can send files to other nodes owned by the same user.
-  # Tagged devices and cross-user transfers are not permitted by Tailscale clients.
+  # Enable or disable Taildrop tailnet-wide. When disabled, headscale
+  # withholds `https://tailscale.com/cap/file-sharing` from every
+  # node's CapMap.
   enabled: true
+
+# Default node auto-update behaviour. When enabled, every node's
+# CapMap carries `default-auto-update: [true]` so clients that have
+# not made a local opt-in / opt-out choice run auto-updates by
+# default. Setting it back to false flips the default for future
+# clients; clients that already stored the value locally keep their
+# choice.
+auto_update:
+  enabled: false
 # Advanced performance tuning parameters.
 # The defaults are carefully chosen and should rarely need adjustment.
 # Only modify these if you have identified a specific performance issue.
 #
 # tuning:
+#   # Maximum number of pending registration entries in the auth cache.
+#   # Oldest entries are evicted when the cap is reached.
+#   #
+#   # register_cache_max_entries: 1024
+#
 #   # NodeStore write batching configuration.
 #   # The NodeStore batches write operations before rebuilding peer relationships,
 #   # which is computationally expensive. Batching reduces rebuild frequency.

derp-example.yaml

@@ -1,4 +1,5 @@
-# If you plan to somehow use headscale, please deploy your own DERP infra: https://tailscale.com/kb/1118/custom-derp-servers/
+# If you plan to somehow use headscale, please deploy your own DERP infra.
+# See: https://tailscale.com/docs/reference/derp-servers/custom-derp-servers
 regions:
   1: null # Disable DERP region with ID 1
   900:

docs/about/contributing.md

@@ -1,3 +1,3 @@
 {%
-    include-markdown "../../CONTRIBUTING.md"
+include-markdown "../../CONTRIBUTING.md"
 %}

docs/about/faq.md

@@ -24,9 +24,12 @@ We are more than happy to exchange emails, or to have dedicated calls before a P
 
 ## When/Why is Feature X going to be implemented?
 
-We don't know. We might be working on it. If you're interested in contributing, please post a feature request about it.
+We use [GitHub Milestones to plan for upcoming Headscale releases](https://github.com/juanfont/headscale/milestones).
+Have a look at [our current plan](https://github.com/juanfont/headscale/milestones) to get an idea when a specific
+feature is about to be implemented. The release plan is subject to change at any time.
 
-Please be aware that there are a number of reasons why we might not accept specific contributions:
+If you're interested in contributing, please post a feature request about it. Please be aware that there are a number of
+reasons why we might not accept specific contributions:
 
 - It is not possible to implement the feature in a way that makes sense in a self-hosted environment.
 - Given that we are reverse-engineering Tailscale to satisfy our own curiosity, we might be interested in implementing the feature ourselves.
@@ -47,8 +50,8 @@ we have a "docker-issues" channel where you can ask for Docker-specific help to
 ## What is the recommended update path? Can I skip multiple versions while updating?
 
 Please follow the steps outlined in the [upgrade guide](../setup/upgrade.md) to update your existing Headscale
-installation. Its best to update from one stable version to the next (e.g. 0.24.0 → 0.25.1 → 0.26.1) in case
-you are multiple releases behind. You should always pick the latest available patch release.
+installation. Its required to update from one stable version to the next (e.g. 0.26.0 → 0.27.1 → 0.28.0) without
+skipping minor versions in between. You should always pick the latest available patch release.
 
 Be sure to check the [changelog](https://github.com/juanfont/headscale/blob/main/CHANGELOG.md) for version specific
 upgrade instructions and breaking changes.
@@ -70,12 +73,12 @@ of Headscale:
 
 1. An environment with 1000 servers
 
-   - they rarely "move" (change their endpoints)
-   - new nodes are added rarely
+    - they rarely "move" (change their endpoints)
+    - new nodes are added rarely
 
-2. An environment with 80 laptops/phones (end user devices)
+1. An environment with 80 laptops/phones (end user devices)
 
-   - nodes move often, e.g. switching from home to office
+    - nodes move often, e.g. switching from home to office
 
 Headscale calculates a map of all nodes that need to talk to each other,
 creating this "world map" requires a lot of CPU time. When an event that
@@ -131,7 +134,7 @@ help to the community.
 
 Running headscale on a machine that is also in the tailnet can cause problems with subnet routers, traffic relay nodes, and MagicDNS. It might work, but it is not supported.
 
-## Why do two nodes see each other in their status, even if an ACL allows traffic only in one direction?
+## Why do two nodes see each other in their status, even if a policy rule allows traffic only in one direction?
 
 A frequent use case is to allow traffic only from one node to another, but not the other way around. For example, the
 workstation of an administrator should be able to connect to all nodes but the nodes themselves shouldn't be able to
@@ -139,31 +142,64 @@ connect back to the administrator's node. Why do all nodes see the administrator
 `tailscale status`?
 
 This is essentially how Tailscale works. If traffic is allowed to flow in one direction, then both nodes see each other
-in their output of `tailscale status`. Traffic is still filtered according to the ACL, with the exception of `tailscale
-ping` which is always allowed in either direction.
+in their output of `tailscale status`. Traffic is still filtered according to the policy, with the exception of
+`tailscale ping` which is always allowed in either direction.
 
-See also <https://tailscale.com/kb/1087/device-visibility>.
+See also <https://tailscale.com/docs/concepts/device-visibility>.
 
 ## My policy is stored in the database and Headscale refuses to start due to an invalid policy. How can I recover?
 
 Headscale checks if the policy is valid during startup and refuses to start if it detects an error. The error message
 indicates which part of the policy is invalid. Follow these steps to fix your policy:
 
-- Dump the policy to a file: `headscale policy get --bypass-grpc-and-access-database-directly > policy.json`
+- Dump the policy to a file: `headscale policy get --bypass-server-and-access-database-directly > policy.json`
 - Edit and fixup `policy.json`. Use the command `headscale policy check --file policy.json` to validate the policy.
-- Load the modified policy: `headscale policy set --bypass-grpc-and-access-database-directly --file policy.json`
+- Load the modified policy: `headscale policy set --bypass-server-and-access-database-directly --file policy.json`
 - Start Headscale as usual.
 
 !!! warning "Full server configuration required"
 
     The above commands to get/set the policy require a complete server configuration file including database settings. A
-    minimal config to [control Headscale via remote CLI](../ref/api.md#grpc) is not sufficient. You may use `headscale
-    -c /path/to/config.yaml` to specify the path to an alternative configuration file.
+    minimal config to [control Headscale via remote CLI](../ref/api.md#remote-control) is not sufficient. You may use
+    `headscale -c /path/to/config.yaml` to specify the path to an alternative configuration file.
+
+## How can I migrate back to the recommended IP prefixes?
+
+Tailscale only supports the IP prefixes `100.64.0.0/10` and `fd7a:115c:a1e0::/48` or smaller subnets thereof. The
+following steps can be used to migrate from unsupported IP prefixes back to the supported and recommended ones.
+
+!!! warning "Backup and test in a demo environment required"
+
+    The commands below update the IP addresses of all nodes in your tailnet and this might have a severe impact in your
+    specific environment. At a minimum:
+
+    - [Create a backup of your database](../setup/upgrade.md#backup)
+    - Test the commands below in a representive demo environment. This allows to catch subsequent connectivity errors
+      early and see how the tailnet behaves in your specific environment.
+
+- Stop Headscale
+- Restore the default prefixes in the [configuration file](../ref/configuration.md):
+    ```yaml
+    prefixes:
+      v4: 100.64.0.0/10
+      v6: fd7a:115c:a1e0::/48
+    ```
+- Update the `nodes.ipv4` and `nodes.ipv6` columns in the database and assign each node a unique IPv4 and IPv6 address.
+  The following SQL statement assigns IP addresses based on the node ID:
+    ```sql
+    UPDATE nodes
+    SET ipv4=concat('100.64.', id/256, '.', id%256),
+        ipv6=concat('fd7a:115c:a1e0::', format('%x', id));
+    ```
+- Update the [policy](../ref/policy.md) to reflect the IP address changes (if any)
+- Start Headscale
+
+Nodes should reconnect within a few seconds and pickup their newly assigned IP addresses.
 
 ## How can I avoid to send logs to Tailscale Inc?
 
 A Tailscale client [collects logs about its operation and connection attempts with other
-clients](https://tailscale.com/kb/1011/log-mesh-traffic#client-logs) and sends them to a central log service operated by
+clients](https://tailscale.com/docs/features/logging#client-logs) and sends them to a central log service operated by
 Tailscale Inc.
 
 Headscale, by default, instructs clients to disable log submission to the central log service. This configuration is
@@ -173,5 +209,5 @@ applied by a client once it successfully connected with Headscale. See the confi
 Alternatively, logging can also be disabled on the client side. This is independent of Headscale and opting out of
 client logging disables log submission early during client startup. The configuration is operating system specific and
 is usually achieved by setting the environment variable `TS_NO_LOGS_NO_SUPPORT=true` or by passing the flag
-`--no-logs-no-support` to `tailscaled`. See
-<https://tailscale.com/kb/1011/log-mesh-traffic#opting-out-of-client-logging> for details.
+`--no-logs-no-support` to `tailscaled`. See <https://tailscale.com/docs/features/logging#opt-out-of-client-logging> for
+details.

docs/about/features.md

@@ -9,30 +9,37 @@ provides on overview of Headscale's feature and compatibility with the Tailscale
     - [x] [Web authentication](../ref/registration.md#web-authentication)
     - [x] [Pre authenticated key](../ref/registration.md#pre-authenticated-key)
 - [x] [DNS](../ref/dns.md)
-    - [x] [MagicDNS](https://tailscale.com/kb/1081/magicdns)
-    - [x] [Global and restricted nameservers (split DNS)](https://tailscale.com/kb/1054/dns#nameservers)
-    - [x] [search domains](https://tailscale.com/kb/1054/dns#search-domains)
+    - [x] [MagicDNS](https://tailscale.com/docs/features/magicdns)
+    - [x] [Global and restricted nameservers (split DNS)](https://tailscale.com/docs/reference/dns-in-tailscale#nameservers)
+    - [x] [search domains](https://tailscale.com/docs/reference/dns-in-tailscale#search-domains)
     - [x] [Extra DNS records (Headscale only)](../ref/dns.md#setting-extra-dns-records)
-- [x] [Taildrop (File Sharing)](https://tailscale.com/kb/1106/taildrop)
+- [x] File sharing
+    - [x] [Taildrive](https://tailscale.com/docs/features/taildrive)
+    - [x] [Taildrop](https://tailscale.com/docs/features/taildrop)
 - [x] [Tags](../ref/tags.md)
 - [x] [Routes](../ref/routes.md)
     - [x] [Subnet routers](../ref/routes.md#subnet-router)
     - [x] [Exit nodes](../ref/routes.md#exit-node)
+    - [x] [Route filtering with Via](https://tailscale.com/docs/features/access-control/grants/grants-via)
 - [x] Dual stack (IPv4 and IPv6)
 - [x] Ephemeral nodes
 - [x] Embedded [DERP server](../ref/derp.md)
-- [x] Access control lists ([GitHub label "policy"](https://github.com/juanfont/headscale/labels/policy%20%F0%9F%93%9D))
-    - [x] ACL management via API
-    - [x] Some [Autogroups](https://tailscale.com/kb/1396/targets#autogroups), currently: `autogroup:internet`,
-      `autogroup:nonroot`, `autogroup:member`, `autogroup:tagged`, `autogroup:self`
-    - [x] [Auto approvers](https://tailscale.com/kb/1337/acl-syntax#auto-approvers) for [subnet
+- [x] [Peer relays](https://tailscale.com/docs/features/peer-relay)
+- [x] [Policy](../ref/policy.md) ([GitHub label "policy"](https://github.com/juanfont/headscale/labels/policy%20%F0%9F%93%9D))
+    - [x] ACLs
+    - [x] Grants
+    - [x] Some [Autogroups](../ref/policy.md#autogroups)
+    - [x] [Auto approvers](https://tailscale.com/docs/reference/syntax/policy-file#auto-approvers) for [subnet
       routers](../ref/routes.md#automatically-approve-routes-of-a-subnet-router) and [exit
       nodes](../ref/routes.md#automatically-approve-an-exit-node-with-auto-approvers)
-    - [x] [Tailscale SSH](https://tailscale.com/kb/1193/tailscale-ssh)
-* [x] [Node registration using Single-Sign-On (OpenID Connect)](../ref/oidc.md) ([GitHub label "OIDC"](https://github.com/juanfont/headscale/labels/OIDC))
+    - [x] [Tailscale SSH](https://tailscale.com/docs/features/tailscale-ssh)
+    - [x] [Node attributes](../ref/policy.md#node-attributes)
+    - [x] [Tests](https://tailscale.com/docs/reference/syntax/policy-file#tests) and
+      [sshTests](https://tailscale.com/docs/reference/syntax/policy-file#ssh-tests)
+- [x] [Node registration using Single-Sign-On (OpenID Connect)](../ref/oidc.md) ([GitHub label "OIDC"](https://github.com/juanfont/headscale/labels/OIDC))
     - [x] Basic registration
     - [x] Update user profile from identity provider
     - [ ] OIDC groups cannot be used in ACLs
-- [ ] [Funnel](https://tailscale.com/kb/1223/funnel) ([#1040](https://github.com/juanfont/headscale/issues/1040))
-- [ ] [Serve](https://tailscale.com/kb/1312/serve) ([#1234](https://github.com/juanfont/headscale/issues/1921))
-- [ ] [Network flow logs](https://tailscale.com/kb/1219/network-flow-logs) ([#1687](https://github.com/juanfont/headscale/issues/1687))
+- [ ] [Funnel](https://tailscale.com/docs/features/tailscale-funnel) ([#1040](https://github.com/juanfont/headscale/issues/1040))
+- [ ] [Serve](https://tailscale.com/docs/features/tailscale-serve) ([#1234](https://github.com/juanfont/headscale/issues/1921))
+- [ ] [Network flow logs](https://tailscale.com/docs/features/logging/network-flow-logs) ([#1687](https://github.com/juanfont/headscale/issues/1687))

docs/index.md

@@ -8,7 +8,7 @@ hide:
 
 Headscale is an open source, self-hosted implementation of the Tailscale control server.
 
-This page contains the documentation for the latest version of headscale. Please also check our [FAQ](./about/faq.md).
+This page contains the documentation for the latest version of headscale. Please also check our [FAQ](about/faq.md).
 
 Join our [Discord server](https://discord.gg/c84AZQhmpx) for a chat and community support.
 

docs/ref/acls.md

@@ -1,287 +0,0 @@
-Headscale implements the same policy ACLs as Tailscale.com, adapted to the self-hosted environment.
-
-For instance, instead of referring to users when defining groups you must
-use users (which are the equivalent to user/logins in Tailscale.com).
-
-Please check https://tailscale.com/kb/1018/acls/ for further information.
-
-When using ACL's the User borders are no longer applied. All machines
-whichever the User have the ability to communicate with other hosts as
-long as the ACL's permits this exchange.
-
-## ACL Setup
-
-To enable and configure ACLs in Headscale, you need to specify the path to your ACL policy file in the `policy.path` key in `config.yaml`.
-
-Your ACL policy file must be formatted using [huJSON](https://github.com/tailscale/hujson).
-
-Info on how these policies are written can be found
-[here](https://tailscale.com/kb/1018/acls/).
-
-Please reload or restart Headscale after updating the ACL file. Headscale may be reloaded either via its systemd service
-(`sudo systemctl reload headscale`) or by sending a SIGHUP signal (`sudo kill -HUP $(pidof headscale)`) to the main
-process. Headscale logs the result of ACL policy processing after each reload.
-
-## Simple Examples
-
-- [**Allow All**](https://tailscale.com/kb/1192/acl-samples#allow-all-default-acl): If you define an ACL file but completely omit the `"acls"` field from its content, Headscale will default to an "allow all" policy. This means all devices connected to your tailnet will be able to communicate freely with each other.
-
-    ```json
-    {}
-    ```
-
-- [**Deny All**](https://tailscale.com/kb/1192/acl-samples#deny-all): To prevent all communication within your tailnet, you can include an empty array for the `"acls"` field in your policy file.
-
-    ```json
-    {
-      "acls": []
-    }
-    ```
-
-## Complex Example
-
-Let's build a more complex example use case for a small business (It may be the place where
-ACL's are the most useful).
-
-We have a small company with a boss, an admin, two developers and an intern.
-
-The boss should have access to all servers but not to the user's hosts. Admin
-should also have access to all hosts except that their permissions should be
-limited to maintaining the hosts (for example purposes). The developers can do
-anything they want on dev hosts but only watch on productions hosts. Intern
-can only interact with the development servers.
-
-There's an additional server that acts as a router, connecting the VPN users
-to an internal network `10.20.0.0/16`. Developers must have access to those
-internal resources.
-
-Each user have at least a device connected to the network and we have some
-servers.
-
-- database.prod
-- database.dev
-- app-server1.prod
-- app-server1.dev
-- billing.internal
-- router.internal
-
-![ACL implementation example](../assets/images/headscale-acl-network.png)
-
-When [registering the servers](../usage/getting-started.md#register-a-node) we
-will need to add the flag `--advertise-tags=tag:<tag1>,tag:<tag2>`, and the user
-that is registering the server should be allowed to do it. Since anyone can add
-tags to a server they can register, the check of the tags is done on headscale
-server and only valid tags are applied. A tag is valid if the user that is
-registering it is allowed to do it.
-
-Here are the ACL's to implement the same permissions as above:
-
-```json title="acl.json"
-{
-  // groups are collections of users having a common scope. A user can be in multiple groups
-  // groups cannot be composed of groups
-  "groups": {
-    "group:boss": ["boss@"],
-    "group:dev": ["dev1@", "dev2@"],
-    "group:admin": ["admin1@"],
-    "group:intern": ["intern1@"]
-  },
-  // tagOwners in tailscale is an association between a TAG and the people allowed to set this TAG on a server.
-  // This is documented [here](https://tailscale.com/kb/1068/acl-tags#defining-a-tag)
-  // and explained [here](https://tailscale.com/blog/rbac-like-it-was-meant-to-be/)
-  "tagOwners": {
-    // the administrators can add servers in production
-    "tag:prod-databases": ["group:admin"],
-    "tag:prod-app-servers": ["group:admin"],
-
-    // the boss can tag any server as internal
-    "tag:internal": ["group:boss"],
-
-    // dev can add servers for dev purposes as well as admins
-    "tag:dev-databases": ["group:admin", "group:dev"],
-    "tag:dev-app-servers": ["group:admin", "group:dev"]
-
-    // interns cannot add servers
-  },
-  // hosts should be defined using its IP addresses and a subnet mask.
-  // to define a single host, use a /32 mask. You cannot use DNS entries here,
-  // as they're prone to be hijacked by replacing their IP addresses.
-  // see https://github.com/tailscale/tailscale/issues/3800 for more information.
-  "hosts": {
-    "postgresql.internal": "10.20.0.2/32",
-    "webservers.internal": "10.20.10.1/29"
-  },
-  "acls": [
-    // boss have access to all servers
-    {
-      "action": "accept",
-      "src": ["group:boss"],
-      "dst": [
-        "tag:prod-databases:*",
-        "tag:prod-app-servers:*",
-        "tag:internal:*",
-        "tag:dev-databases:*",
-        "tag:dev-app-servers:*"
-      ]
-    },
-
-    // admin have only access to administrative ports of the servers, in tcp/22
-    {
-      "action": "accept",
-      "src": ["group:admin"],
-      "proto": "tcp",
-      "dst": [
-        "tag:prod-databases:22",
-        "tag:prod-app-servers:22",
-        "tag:internal:22",
-        "tag:dev-databases:22",
-        "tag:dev-app-servers:22"
-      ]
-    },
-
-    // we also allow admin to ping the servers
-    {
-      "action": "accept",
-      "src": ["group:admin"],
-      "proto": "icmp",
-      "dst": [
-        "tag:prod-databases:*",
-        "tag:prod-app-servers:*",
-        "tag:internal:*",
-        "tag:dev-databases:*",
-        "tag:dev-app-servers:*"
-      ]
-    },
-
-    // developers have access to databases servers and application servers on all ports
-    // they can only view the applications servers in prod and have no access to databases servers in production
-    {
-      "action": "accept",
-      "src": ["group:dev"],
-      "dst": [
-        "tag:dev-databases:*",
-        "tag:dev-app-servers:*",
-        "tag:prod-app-servers:80,443"
-      ]
-    },
-    // developers have access to the internal network through the router.
-    // the internal network is composed of HTTPS endpoints and Postgresql
-    // database servers.
-    {
-      "action": "accept",
-      "src": ["group:dev"],
-      "dst": ["10.20.0.0/16:443,5432"]
-    },
-
-    // servers should be able to talk to database in tcp/5432. Database should not be able to initiate connections to
-    // applications servers
-    {
-      "action": "accept",
-      "src": ["tag:dev-app-servers"],
-      "proto": "tcp",
-      "dst": ["tag:dev-databases:5432"]
-    },
-    {
-      "action": "accept",
-      "src": ["tag:prod-app-servers"],
-      "dst": ["tag:prod-databases:5432"]
-    },
-
-    // interns have access to dev-app-servers only in reading mode
-    {
-      "action": "accept",
-      "src": ["group:intern"],
-      "dst": ["tag:dev-app-servers:80,443"]
-    },
-
-    // Allow users to access their own devices using autogroup:self (see below for more details about performance impact)
-    {
-      "action": "accept",
-      "src": ["autogroup:member"],
-      "dst": ["autogroup:self:*"]
-    }
-  ]
-}
-```
-
-## Autogroups
-
-Headscale supports several autogroups that automatically include users, destinations, or devices with specific properties. Autogroups provide a convenient way to write ACL rules without manually listing individual users or devices.
-
-### `autogroup:internet`
-
-Allows access to the internet through [exit nodes](routes.md#exit-node). Can only be used in ACL destinations.
-
-```json
-{
-  "action": "accept",
-  "src": ["group:users"],
-  "dst": ["autogroup:internet:*"]
-}
-```
-
-### `autogroup:member`
-
-Includes all [personal (untagged) devices](registration.md/#identity-model).
-
-```json
-{
-  "action": "accept",
-  "src": ["autogroup:member"],
-  "dst": ["tag:prod-app-servers:80,443"]
-}
-```
-
-### `autogroup:tagged`
-
-Includes all devices that [have at least one tag](registration.md/#identity-model).
-
-```json
-{
-  "action": "accept",
-  "src": ["autogroup:tagged"],
-  "dst": ["tag:monitoring:9090"]
-}
-```
-
-### `autogroup:self`
-**(EXPERIMENTAL)**
-
-!!! warning "The current implementation of `autogroup:self` is inefficient"
-
-Includes devices where the same user is authenticated on both the source and destination. Does not include tagged devices. Can only be used in ACL destinations.
-
-```json
-{
-  "action": "accept",
-  "src": ["autogroup:member"],
-  "dst": ["autogroup:self:*"]
-}
-```
-*Using `autogroup:self` may cause performance degradation on the Headscale coordinator server in large deployments, as filter rules must be compiled per-node rather than globally and the current implementation is not very efficient.*
-
-If you experience performance issues, consider using more specific ACL rules or limiting the use of `autogroup:self`.
-```json
-{
-  // The following rules allow internal users to communicate with their
-  // own nodes in case autogroup:self is causing performance issues.
-  { "action": "accept", "src": ["boss@"], "dst": ["boss@:*"] },
-  { "action": "accept", "src": ["dev1@"], "dst": ["dev1@:*"] },
-  { "action": "accept", "src": ["dev2@"], "dst": ["dev2@:*"] },
-  { "action": "accept", "src": ["admin1@"], "dst": ["admin1@:*"] },
-  { "action": "accept", "src": ["intern1@"], "dst": ["intern1@:*"] }
-}
-```
-
-### `autogroup:nonroot`
-
-Used in Tailscale SSH rules to allow access to any user except root. Can only be used in the `users` field of SSH rules.
-
-```json
-{
-  "action": "accept",
-  "src": ["autogroup:member"],
-  "dst": ["autogroup:self"],
-  "users": ["autogroup:nonroot"]
-}
-```

docs/ref/api.md

@@ -1,9 +1,10 @@
 # API
-Headscale provides a [HTTP REST API](#rest-api) and a [gRPC interface](#grpc) which may be used to integrate a [web
-interface](integration/web-ui.md), [remote control Headscale](#setup-remote-control) or provide a base for custom
+
+Headscale provides a [HTTP REST API](#rest-api) which may be used to integrate a [web
+interface](integration/web-ui.md), [remote control Headscale](#remote-control) or provide a base for custom
 integration and tooling.
 
-Both interfaces require a valid API key before use. To create an API key, log into your Headscale server and generate
+The API requires a valid API key before use. To create an API key, log into your Headscale server and generate
 one with the default expiration of 90 days:
 
 ```shell
@@ -28,13 +29,12 @@ headscale apikeys expire --prefix <PREFIX>
 ## REST API
 
 - API endpoint: `/api/v1`, e.g. `https://headscale.example.com/api/v1`
-- Documentation: `/swagger`, e.g. `https://headscale.example.com/swagger`
+- Documentation: `/api/v1/docs`, e.g. `https://headscale.example.com/api/v1/docs`
 - Headscale Version: `/version`, e.g. `https://headscale.example.com/version`
-- Authenticate using HTTP Bearer authentication by sending the [API key](#api) with the HTTP `Authorization: Bearer
-  <API_KEY>` header.
+- Authenticate using HTTP Bearer authentication by sending the [API key](#api) with the HTTP `Authorization: Bearer <API_KEY>` header.
 
 Start by [creating an API key](#api) and test it with the examples below. Read the API documentation provided by your
-Headscale server at `/swagger` for details.
+Headscale server at `/api/v1/docs` for details.
 
 === "Get details for all users"
 
@@ -54,55 +54,54 @@ Headscale server at `/swagger` for details.
 
     ```console
     curl -H "Authorization: Bearer <API_KEY>" \
-        -d user=<USER> -d key=<REGISTRATION_KEY> \
-        https://headscale.example.com/api/v1/node/register
+        --json '{"user": "<USER>", "authId": "<AUTH_ID>"}' \
+        https://headscale.example.com/api/v1/auth/register
     ```
 
-## gRPC
+## Remote control
 
-The gRPC interface can be used to control a Headscale instance from a remote machine with the `headscale` binary.
+The `headscale` binary can control a Headscale instance from a remote machine over the HTTP API.
 
 ### Prerequisite
 
 - A workstation to run `headscale` (any supported platform, e.g. Linux).
-- A Headscale server with gRPC enabled.
-- Connections to the gRPC port (default: `50443`) are allowed.
-- Remote access requires an encrypted connection via TLS.
+- The Headscale server reachable over HTTP(S).
 - An [API key](#api) to authenticate with the Headscale server.
 
 ### Setup remote control
 
-1.  Download the [`headscale` binary from GitHub's release page](https://github.com/juanfont/headscale/releases). Make
-    sure to use the same version as on the server.
+1. Download the [`headscale` binary from GitHub's release page](https://github.com/juanfont/headscale/releases). Make
+   sure to use the same version as on the server.
 
-1.  Put the binary somewhere in your `PATH`, e.g. `/usr/local/bin/headscale`
+1. Put the binary somewhere in your `PATH`, e.g. `/usr/local/bin/headscale`
 
-1.  Make `headscale` executable: `chmod +x /usr/local/bin/headscale`
+1. Make `headscale` executable: `chmod +x /usr/local/bin/headscale`
 
-1.  [Create an API key](#api) on the Headscale server.
+1. [Create an API key](#api) on the Headscale server.
 
-1.  Provide the connection parameters for the remote Headscale server either via a minimal YAML configuration file or
-    via environment variables:
+1. Provide the connection parameters for the remote Headscale server either via a minimal YAML configuration file or
+   via environment variables:
 
     === "Minimal YAML configuration file"
 
         ```yaml title="config.yaml"
         cli:
-            address: <HEADSCALE_ADDRESS>:<PORT>
+            address: <HEADSCALE_URL>
             api_key: <API_KEY>
         ```
 
     === "Environment variables"
 
         ```shell
-        export HEADSCALE_CLI_ADDRESS="<HEADSCALE_ADDRESS>:<PORT>"
+        export HEADSCALE_CLI_ADDRESS="<HEADSCALE_URL>"
         export HEADSCALE_CLI_API_KEY="<API_KEY>"
         ```
 
-    This instructs the `headscale` binary to connect to a remote instance at `<HEADSCALE_ADDRESS>:<PORT>`, instead of
-    connecting to the local instance.
+    This instructs the `headscale` binary to connect to a remote instance at `<HEADSCALE_URL>` (e.g.
+    `https://headscale.example.com`), instead of connecting to the local instance. A bare host without a scheme is
+    assumed to be `https`.
 
-1.  Test the connection by listing all nodes:
+1. Test the connection by listing all nodes:
 
     ```shell
     headscale nodes list
@@ -113,15 +112,12 @@ The gRPC interface can be used to control a Headscale instance from a remote mac
 
 ### Behind a proxy
 
-It's possible to run the gRPC remote endpoint behind a reverse proxy, like Nginx, and have it run on the _same_ port as Headscale.
-
-While this is _not a supported_ feature, an example on how this can be set up on
-[NixOS is shown here](https://github.com/kradalby/dotfiles/blob/4489cdbb19cddfbfae82cd70448a38fde5a76711/machines/headscale.oracldn/headscale.nix#L61-L91).
+The remote CLI uses the same HTTP API as everything else, so it works through the reverse proxy already in front of
+Headscale with no extra setup.
 
 ### Troubleshooting
 
 - Make sure you have the _same_ Headscale version on your server and workstation.
-- Ensure that connections to the gRPC port are allowed.
 - Verify that your TLS certificate is valid and trusted.
 - If you don't have access to a trusted certificate (e.g. from Let's Encrypt), either:
     - Add your self-signed certificate to the trust store of your OS _or_

docs/ref/configuration.md

@@ -17,8 +17,8 @@
 
     === "View on GitHub"
 
-        * Development version: <https://github.com/juanfont/headscale/blob/main/config-example.yaml>
-        * Version {{ headscale.version }}: <https://github.com/juanfont/headscale/blob/v{{ headscale.version }}/config-example.yaml>
+        - Development version: <https://github.com/juanfont/headscale/blob/main/config-example.yaml>
+        - Version {{ headscale.version }}: https://github.com/juanfont/headscale/blob/v{{ headscale.version }}/config-example.yaml
 
     === "Download with `wget`"
 

docs/ref/debug.md

@@ -3,16 +3,16 @@
 Headscale and Tailscale provide debug and introspection capabilities that can be helpful when things don't work as
 expected. This page explains some debugging techniques to help pinpoint problems.
 
-Please also have a look at [Tailscale's Troubleshooting guide](https://tailscale.com/kb/1023/troubleshooting). It offers
-a many tips and suggestions to troubleshoot common issues.
+Please also have a look at [Tailscale's Troubleshooting guide](https://tailscale.com/docs/reference/troubleshooting). It
+offers a many tips and suggestions to troubleshoot common issues.
 
 ## Tailscale
 
 The Tailscale client itself offers many commands to introspect its state as well as the state of the network:
 
-- [Check local network conditions](https://tailscale.com/kb/1080/cli#netcheck): `tailscale netcheck`
-- [Get the client status](https://tailscale.com/kb/1080/cli#status): `tailscale status --json`
-- [Get DNS status](https://tailscale.com/kb/1080/cli#dns): `tailscale dns status --all`
+- [Check local network conditions](https://tailscale.com/docs/reference/tailscale-cli#netcheck): `tailscale netcheck`
+- [Get the client status](https://tailscale.com/docs/reference/tailscale-cli#status): `tailscale status --json`
+- [Get DNS status](https://tailscale.com/docs/reference/tailscale-cli#dns): `tailscale dns status --all`
 - Client logs: `tailscale debug daemon-logs`
 - Client netmap: `tailscale debug netmap`
 - Test DERP connection: `tailscale debug derp headscale`
@@ -53,19 +53,19 @@ Headscale provides a metrics and debug endpoint. It allows to introspect differe
 
 - Information about the Go runtime, memory usage and statistics
 - Connected nodes and pending registrations
-- Active ACLs, filters and SSH policy
+- Active policy, filters and SSH policy
 - Current DERPMap
 - Prometheus metrics
 
 !!! warning "Keep the metrics and debug endpoint private"
 
     The listen address and port can be configured with the `metrics_listen_addr` variable in the [configuration
-    file](./configuration.md). By default it listens on localhost, port 9090.
+    file](configuration.md). By default it listens on localhost, port 9090.
 
     Keep the metrics and debug endpoint private to your internal network and don't expose it to the Internet.
 
     The metrics and debug interface can be disabled completely by setting `metrics_listen_addr: null` in the
-    [configuration file](./configuration.md).
+    [configuration file](configuration.md).
 
 Query metrics via <http://localhost:9090/metrics> and get an overview of available debug information via
 <http://localhost:9090/debug/>. Metrics may be queried from outside localhost but the debug interface is subject to

docs/ref/derp.md

@@ -1,13 +1,13 @@
 # DERP
 
-A [DERP (Designated Encrypted Relay for Packets) server](https://tailscale.com/kb/1232/derp-servers) is mainly used to
-relay traffic between two nodes in case a direct connection can't be established. Headscale provides an embedded DERP
-server to ensure seamless connectivity between nodes.
+A [DERP (Designated Encrypted Relay for Packets) server](https://tailscale.com/docs/reference/derp-servers) is mainly
+used to relay traffic between two nodes in case a direct connection can't be established. Headscale provides an embedded
+DERP server to ensure seamless connectivity between nodes.
 
 ## Configuration
 
-DERP related settings are configured within the `derp` section of the [configuration file](./configuration.md). The
-following sections only use a few of the available settings, check the [example configuration](./configuration.md) for
+DERP related settings are configured within the `derp` section of the [configuration file](configuration.md). The
+following sections only use a few of the available settings, check the [example configuration](configuration.md) for
 all available configuration options.
 
 ### Enable embedded DERP
@@ -31,8 +31,8 @@ traversal. [Check DERP server connectivity](#check-derp-server-connectivity) to
 ### Remove Tailscale's DERP servers
 
 Once enabled, Headscale's embedded DERP is added to the list of free-to-use [DERP
-servers](https://tailscale.com/kb/1232/derp-servers) offered by Tailscale Inc. To only use Headscale's embedded DERP
-server, disable the loading of the default DERP map:
+servers](https://tailscale.com/docs/reference/derp-servers) offered by Tailscale Inc. To only use Headscale's embedded
+DERP server, disable the loading of the default DERP map:
 
 ```yaml title="config.yaml" hl_lines="6"
 derp:
@@ -59,14 +59,14 @@ maps fetched via URL or to offer your own, custom DERP servers to nodes.
 
 === "Remove specific DERP regions"
 
-    The free-to-use [DERP servers](https://tailscale.com/kb/1232/derp-servers) are organized into regions via a region
-    ID. You can explicitly disable a specific region by setting its region ID to `null`. The following sample
+    The free-to-use [DERP servers](https://tailscale.com/docs/reference/derp-servers) are organized into regions via a
+    region ID. You can explicitly disable a specific region by setting its region ID to `null`. The following sample
     `derp.yaml` disables the New York DERP region (which has the region ID 1):
 
-     ```yaml title="derp.yaml"
-     regions:
-       1: null
-     ```
+    ```yaml title="derp.yaml"
+    regions:
+      1: null
+    ```
 
     Use the following configuration to serve the default DERP map (excluding New York) to nodes:
 
@@ -163,13 +163,12 @@ Any Tailscale client may be used to introspect the DERP map and to check for con
 - Check connectivity with the embedded DERP[^1]:`tailscale debug derp headscale`
 
 Additional DERP related metrics and information is available via the [metrics and debug
-endpoint](./debug.md#metrics-and-debug-endpoint).
-
-[^1]:
-    This assumes that the default region code of the [configuration file](./configuration.md) is used.
+endpoint](debug.md#metrics-and-debug-endpoint).
 
 ## Limitations
 
 - The embedded DERP server can't be used for Tailscale's captive portal checks as it doesn't support the `/generate_204`
   endpoint via HTTP on port tcp/80.
 - There are no speed or throughput optimisations, the main purpose is to assist in node connectivity.
+
+[^1]: This assumes that the default region code of the [configuration file](configuration.md) is used.

docs/ref/dns.md

@@ -1,19 +1,19 @@
 # DNS
 
 Headscale supports [most DNS features](../about/features.md) from Tailscale. DNS related settings can be configured
-within the `dns` section of the [configuration file](./configuration.md).
+within the `dns` section of the [configuration file](configuration.md).
 
 ## Setting extra DNS records
 
 Headscale allows to set extra DNS records which are made available via
-[MagicDNS](https://tailscale.com/kb/1081/magicdns). Extra DNS records can be configured either via static entries in the
-[configuration file](./configuration.md) or from a JSON file that Headscale continuously watches for changes:
+[MagicDNS](https://tailscale.com/docs/features/magicdns). Extra DNS records can be configured either via static entries
+in the [configuration file](configuration.md) or from a JSON file that Headscale continuously watches for changes:
 
-- Use the `dns.extra_records` option in the [configuration file](./configuration.md) for entries that are static and
+- Use the `dns.extra_records` option in the [configuration file](configuration.md) for entries that are static and
   don't change while Headscale is running. Those entries are processed when Headscale is starting up and changes to the
   configuration require a restart of Headscale.
 - For dynamic DNS records that may be added, updated or removed while Headscale is running or DNS records that are
-  generated by scripts the option `dns.extra_records_path` in the [configuration file](./configuration.md) is useful.
+  generated by scripts the option `dns.extra_records_path` in the [configuration file](configuration.md) is useful.
   Set it to the absolute path of the JSON file containing DNS records and Headscale processes this file as it detects
   changes.
 
@@ -25,7 +25,7 @@ hostname and port combination "http://hostname-in-magic-dns.myvpn.example.com:30
 
     Currently, [only A and AAAA records are processed by Tailscale](https://github.com/tailscale/tailscale/blob/v1.86.5/ipn/ipnlocal/node_backend.go#L662).
 
-1.  Configure extra DNS records using one of the available configuration options:
+1. Configure extra DNS records using one of the available configuration options:
 
     === "Static entries, via `dns.extra_records`"
 
@@ -66,12 +66,12 @@ hostname and port combination "http://hostname-in-magic-dns.myvpn.example.com:30
 
         !!! tip "Good to know"
 
-            * The `dns.extra_records_path` option in the [configuration file](./configuration.md) needs to reference the
+            - The `dns.extra_records_path` option in the [configuration file](configuration.md) needs to reference the
               JSON file containing extra DNS records.
-            * Be sure to "sort keys" and produce a stable output in case you generate the JSON file with a script.
+            - Be sure to "sort keys" and produce a stable output in case you generate the JSON file with a script.
               Headscale uses a checksum to detect changes to the file and a stable output avoids unnecessary processing.
 
-1.  Verify that DNS records are properly set using the DNS querying tool of your choice:
+1. Verify that DNS records are properly set using the DNS querying tool of your choice:
 
     === "Query with dig"
 
@@ -87,7 +87,7 @@ hostname and port combination "http://hostname-in-magic-dns.myvpn.example.com:30
         100.64.0.3
         ```
 
-1.  Optional: Setup the reverse proxy
+1. Optional: Setup the reverse proxy
 
     The motivating example here was to be able to access internal monitoring services on the same host without
     specifying a port, depicted as NGINX configuration snippet:

docs/ref/integration/reverse-proxy.md

@@ -1,90 +1,183 @@
-# Running headscale behind a reverse proxy
+# Running Headscale behind a reverse proxy
 
 !!! warning "Community documentation"
 
-    This page is not actively maintained by the headscale authors and is
-    written by community members. It is _not_ verified by headscale developers.
+    This page is not actively maintained by the Headscale authors and is
+    written by community members. It is _not_ verified by Headscale developers.
 
     **It might be outdated and it might miss necessary steps**.
 
-Running headscale behind a reverse proxy is useful when running multiple applications on the same server, and you want to reuse the same external IP and port - usually tcp/443 for HTTPS.
+Running Headscale behind a reverse proxy is useful when running multiple applications on the same server, and you want
+to reuse the same external IP and port - usually tcp/443 for HTTPS.
 
-### WebSockets
+Please see [limitations](#limitations) for known issues and limitations.
 
-The reverse proxy MUST be configured to support WebSockets to communicate with Tailscale clients.
+## Configuration
 
-WebSockets support is also required when using the Headscale [embedded DERP server](../derp.md). In this case, you will also need to expose the UDP port used for STUN (by default, udp/3478). Please check our [config-example.yaml](https://github.com/juanfont/headscale/blob/main/config-example.yaml).
+The configuration depends on the set of Headscale features you intend to use. Please have a look at the
+[requirements](../../setup/requirements.md) and especially the [ports in use](../../setup/requirements.md#ports-in-use)
+section to learn what a Tailscale clients expects.
 
-### Cloudflare
+The configuration examples in this documentation are basic and cover only HTTP and HTTPS traffic. Other features such as
+STUN for Headscale's [embedded DERP server](../derp.md) are expected to be exposed directly or to be only available on
+localhost.
 
-Running headscale behind a cloudflare proxy or cloudflare tunnel is not supported and will not work as Cloudflare does not support WebSocket POSTs as required by the Tailscale protocol. See [this issue](https://github.com/juanfont/headscale/issues/1468)
+### WebSocket
+
+Tailscale clients are using a custom protocol (Tailscale Control Protocol) to communicate with a control server such as
+Headscale. The reverse proxy **must** be configured to support WebSockets in order to communicate with Tailscale clients
+and it needs to handle two peculiarities of the Tailscale Control Protocol:
+
+- The POST method is used to upgrade the WebSocket connection.
+- The value for the `Upgrade` header is `tailscale-control-protocol`.
 
 ### TLS
 
-Headscale can be configured not to use TLS, leaving it to the reverse proxy to handle. Add the following configuration values to your headscale config file.
+Headscale can be configured not to use TLS, leaving it to the reverse proxy to handle. Add the following configuration
+values to your Headscale [configuration file](../configuration.md):
 
-```yaml title="config.yaml"
-server_url: https://<YOUR_SERVER_NAME> # This should be the FQDN at which headscale will be served
-listen_addr: 0.0.0.0:8080
-metrics_listen_addr: 0.0.0.0:9090
+```yaml title="config.yaml" hl_lines="1"
+server_url: https://<SERVER_NAME>
 tls_cert_path: ""
 tls_key_path: ""
 ```
 
-## nginx
+Headscale logs `WRN listening without TLS but ServerURL does not start with http://` during startup. This is expected
+and indicates that the reverse proxy is in charge of terminating TLS.
 
-The following example configuration can be used in your nginx setup, substituting values as necessary. `<IP:PORT>` should be the IP address and port where headscale is running. In most cases, this will be `http://localhost:8080`.
+### Trusted proxies
 
-```nginx title="nginx.conf"
-map $http_upgrade $connection_upgrade {
-    default      upgrade;
-    ''           close;
+Headscale ignores `True-Client-IP`, `X-Real-IP` and `X-Forwarded-For` headers unless the request's TCP peer matches the
+`trusted_proxies` configuration option. Set this to the CIDR(s) your reverse proxy connects from so the real client IP
+appears in access logs.
+
+```yaml title="config.yaml"
+trusted_proxies:
+  - 127.0.0.1/32
+  - ::1/128
+```
+
+The reverse proxy is responsible to replace any client-supplied `True-Client-IP`, `X-Real-IP`, `X-Forwarded-For` headers
+on inbound requests with sanitized values. Headscale picks the first valid IP address supplied by headers in this order:
+
+- `True-Client-IP`
+- `X-Real-IP`
+- `X-Forwarded-For`
+
+## Limitations
+
+- A reverse proxy adds another layer of complexity that needs to be able to handle the [Tailscale Control
+  Protocol](#websocket) properly. Be sure to test your setup without a reverse proxy before raising an issue.
+- STUN (used along with the [embedded DERP server](../derp.md)) requires udp/3478 to be served publicly.
+
+## Reverse proxy specific configuration
+
+!!! warning "Third-party software and services"
+
+    This section of the documentation is specific for third-party software and services. We recommend users read the
+    third-party documentation for a secure configuration.
+
+This following Headscale configuration may be used as base for the various reverse proxy examples below. The following
+is [assumed](../../setup/requirements.md):
+
+- Service for Tailscale clients is served via HTTPS on port 443.
+- The reverse proxy redirects HTTP to HTTPS and is terminating TLS.
+- Both Headscale and the reverse proxy are running on the same host.
+- [Metrics](../debug.md#metrics-and-debug-endpoint) are not proxied, those are available via localhost.
+
+```yaml title="config.yaml" hl_lines="1"
+server_url: https://<SERVER_NAME>
+listen_addr: 127.0.0.1:8080
+metrics_listen_addr: 127.0.0.1:9090
+trusted_proxies:
+  - 127.0.0.1/32
+  - ::1/128
+tls_cert_path: ""
+tls_key_path: ""
+```
+
+### Apache
+
+The following basic Apache configuration works with the Headscale configuration [as shown
+above](#reverse-proxy-specific-configuration). Substitute placeholders and adjust the configuration as needed:
+
+- `<SERVER_NAME>`: The server name for your instance, e.g. `headscale.example.com`
+- `<PATH_TO_TLS_CERT>`: Absolute path to your TLS certificate
+- `<PATH_TO_TLS_KEY>`: Absolute path to your TLS private key
+
+```apache title="apache.conf" hl_lines="2 7 11 14-15"
+<VirtualHost *:80>
+  ServerName <SERVER_NAME>
+
+  # Tailscale captive portal detection
+  RedirectMatch 204 ^/generate_204$
+
+  RedirectMatch permanent "^/(.*)$" "https://<SERVER_NAME>/$1"
+</VirtualHost>
+
+<VirtualHost *:443>
+  ServerName <SERVER_NAME>
+
+  SSLEngine On
+  SSLCertificateFile <PATH_TO_TLS_CERT>
+  SSLCertificateKeyFile <PATH_TO_TLS_KEY>
+
+  RequestHeader set True-Client-IP "%{REMOTE_ADDR}s"
+  RequestHeader set X-Real-IP "%{REMOTE_ADDR}s"
+
+  ProxyPreserveHost On
+  ProxyPass / http://127.0.0.1:8080/ upgrade=any
+</VirtualHost>
+```
+
+Note that `upgrade=any` is required as a parameter for `ProxyPass` so that WebSocket traffic whose `Upgrade` header
+value is not equal to `WebSocket` (i. e. Tailscale Control Protocol) is forwarded correctly. See the [Apache
+docs](https://httpd.apache.org/docs/current/mod/mod_proxy.html#upgrade) for more information on this.
+
+### Caddy
+
+The following basic Caddyfile works with the Headscale configuration [as shown
+above](#reverse-proxy-specific-configuration). Substitute placeholders and adjust the configuration as needed:
+
+- `<SERVER_NAME>`: The server name for your instance, e.g. `headscale.example.com`
+
+```none title="Caddyfile" hl_lines="1 12"
+http://<SERVER_NAME> {
+	# Tailscale captive portal detection
+	handle /generate_204 {
+		respond 204
+	}
+
+	handle * {
+		redir https://{host}{uri}
+	}
 }
 
-server {
-    listen 80;
-	listen [::]:80;
-
-	listen 443      ssl http2;
-	listen [::]:443 ssl http2;
-
-    server_name <YOUR_SERVER_NAME>;
-
-    ssl_certificate <PATH_TO_CERT>;
-    ssl_certificate_key <PATH_CERT_KEY>;
-    ssl_protocols TLSv1.2 TLSv1.3;
-
-    location / {
-        proxy_pass http://<IP:PORT>;
-        proxy_http_version 1.1;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection $connection_upgrade;
-        proxy_set_header Host $server_name;
-        proxy_redirect http:// https://;
-        proxy_buffering off;
-        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;
-        add_header Strict-Transport-Security "max-age=15552000; includeSubDomains" always;
-    }
+<SERVER_NAME> {
+	reverse_proxy 127.0.0.1:8080 {
+		header_up True-Client-IP {remote_host}
+		header_up X-Real-IP {remote_host}
+	}
 }
 ```
 
-## istio/envoy
+Caddy will [automatically](https://caddyserver.com/docs/automatic-https) provision a certificate for your
+domain/subdomain, force HTTPS, and proxy WebSocket connections.
 
-If you using [Istio](https://istio.io/) ingressgateway or [Envoy](https://www.envoyproxy.io/) as reverse proxy, there are some tips for you. If not set, you may see some debug log in proxy as below:
+### Cloudflare
 
-```log
-Sending local reply with details upgrade_failed
-```
+Running Headscale behind a Cloudflare Proxy or Cloudflare Tunnel is not supported and will not work as Cloudflare does
+not support [WebSocket POSTs as required by the Tailscale protocol](#websocket). See [issue
+1468](https://github.com/juanfont/headscale/issues/1468) for more information.
 
 ### Envoy
 
-You need to add a new upgrade_type named `tailscale-control-protocol`. [see details](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-upgradeconfig)
+You need to add a new upgrade_type named `tailscale-control-protocol`. [See
+details](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-upgradeconfig).
 
 ### Istio
 
-Same as envoy, we can use `EnvoyFilter` to add upgrade_type.
+Same as [envoy](#envoy), we can use `EnvoyFilter` to add a new upgrade_type named `tailscale-control-protocol`.
 
 ```yaml
 apiVersion: networking.istio.io/v1alpha3
@@ -109,33 +202,68 @@ spec:
               - upgrade_type: tailscale-control-protocol
 ```
 
-## Caddy
+### Nginx
 
-The following Caddyfile is all that is necessary to use Caddy as a reverse proxy for headscale, in combination with the `config.yaml` specifications above to disable headscale's built in TLS. Replace values as necessary - `<YOUR_SERVER_NAME>` should be the FQDN at which headscale will be served, and `<IP:PORT>` should be the IP address and port where headscale is running. In most cases, this will be `localhost:8080`.
+The following basic Nginx configuration works with the Headscale configuration [as shown
+above](#reverse-proxy-specific-configuration). Substitute placeholders and adjust the configuration as needed:
 
-```none title="Caddyfile"
-<YOUR_SERVER_NAME> {
-    reverse_proxy <IP:PORT>
+- `<SERVER_NAME>`: The server name for your instance, e.g. `headscale.example.com`
+- `<PATH_TO_TLS_CERT>`: Absolute path to your TLS certificate
+- `<PATH_TO_TLS_KEY>`: Absolute path to your TLS private key
+
+```nginx title="nginx.conf" hl_lines="19 37 39-40"
+# headscale
+upstream headscale {
+  zone upstreams 64K;
+  server 127.0.0.1:8080 max_fails=1 fail_timeout=5s;
+  keepalive 2;
+}
+
+# websocket
+map $http_upgrade $connection_upgrade {
+  default keep-alive;
+  ''      close;
+}
+
+# http
+server {
+  listen 80;
+  listen [::]:80;
+
+  server_name <SERVER_NAME>;
+
+  # Tailscale captive portal detection
+  location = /generate_204 {
+    return 204;
+  }
+
+  location / {
+    return 301 https://$server_name$request_uri;
+  }
+}
+
+# https
+server {
+  listen 443 ssl;
+  listen [::]:443 ssl;
+  http2 on;
+
+  server_name <SERVER_NAME>;
+
+  ssl_certificate <PATH_TO_TLS_CERT>;
+  ssl_certificate_key <PATH_TO_TLS_KEY>;
+
+  location / {
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection $connection_upgrade;
+    proxy_set_header Host $host;
+    proxy_set_header True-Client-IP $remote_addr;
+    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_buffering off;
+    proxy_pass http://headscale;
+  }
 }
 ```
-
-Caddy v2 will [automatically](https://caddyserver.com/docs/automatic-https) provision a certificate for your domain/subdomain, force HTTPS, and proxy websockets - no further configuration is necessary.
-
-For a slightly more complex configuration which utilizes Docker containers to manage Caddy, headscale, and Headscale-UI, [Guru Computing's guide](https://blog.gurucomputing.com.au/smart-vpns-with-headscale/) is an excellent reference.
-
-## Apache
-
-The following minimal Apache config will proxy traffic to the headscale instance on `<IP:PORT>`. Note that `upgrade=any` is required as a parameter for `ProxyPass` so that WebSockets traffic whose `Upgrade` header value is not equal to `WebSocket` (i. e. Tailscale Control Protocol) is forwarded correctly. See the [Apache docs](https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html) for more information on this.
-
-```apache title="apache.conf"
-<VirtualHost *:443>
-	ServerName <YOUR_SERVER_NAME>
-
-	ProxyPreserveHost On
-	ProxyPass / http://<IP:PORT>/ upgrade=any
-
-	SSLEngine On
-	SSLCertificateFile <PATH_TO_CERT>
-	SSLCertificateKeyFile <PATH_CERT_KEY>
-</VirtualHost>
-```

docs/ref/integration/web-ui.md

@@ -19,6 +19,11 @@ Headscale doesn't provide a built-in web interface but users may pick one from t
   it offers Local (`docker exec`) and API Mode
 - [headscale-console](https://github.com/rickli-cloud/headscale-console) - WebAssembly-based client supporting SSH, VNC
   and RDP with optional self-service capabilities
-- [headscale-piying](https://github.com/wszgrcy/headscale-piying) - headscale web ui,support visual ACL configuration
+- [headscale-piying](https://github.com/wszgrcy/headscale-piying) - headscale web ui, support visual ACL configuration
+- [HeadControl](https://github.com/ahmadzip/HeadControl) - Minimal Headscale admin dashboard, built with Go and HTMX
+- [Headscale Manager](https://github.com/hkdone/headscalemanager) - Headscale UI for Android
+- [Headscale UI](https://github.com/MunMunMiao/headscale-ui) - Headscale UI online and Self-hosting
+- [Headscale Panel](https://github.com/headscale-panel/panel) - A modern Headscale management panel with a clean,
+  network-operations-focused UI
 
 You can ask for support on our [Discord server](https://discord.gg/c84AZQhmpx) in the "web-interfaces" channel.

docs/ref/oidc.md

@@ -40,9 +40,9 @@ A basic configuration connects Headscale to an identity provider and typically r
 
 === "Identity provider"
 
-    * Create a new confidential client (`Client ID`, `Client secret`)
-    * Add Headscale's OIDC callback URL as valid redirect URL: `https://headscale.example.com/oidc/callback`
-    * Configure additional parameters to improve user experience such as: name, description, logo, …
+    - Create a new confidential client (`Client ID`, `Client secret`)
+    - Add Headscale's OIDC callback URL as valid redirect URL: `https://headscale.example.com/oidc/callback`
+    - Configure additional parameters to improve user experience such as: name, description, logo, …
 
 ### Enable PKCE (recommended)
 
@@ -63,8 +63,8 @@ recommended and needs to be configured for Headscale and the identity provider a
 
 === "Identity provider"
 
-    * Enable PKCE for the headscale client
-    * Set the PKCE challenge method to "S256"
+    - Enable PKCE for the headscale client
+    - Set the PKCE challenge method to "S256"
 
 ### Authorize users with filters
 
@@ -75,11 +75,11 @@ are configured, a user needs to pass all of them.
 
 === "Allowed domains"
 
-    * Check the email domain of each authenticating user against the list of allowed domains and only authorize users
+    - Check the email domain of each authenticating user against the list of allowed domains and only authorize users
       whose email domain matches `example.com`.
-    * A verified email address is required [unless email verification is disabled](#control-email-verification).
-    * Access allowed: `alice@example.com`
-    * Access denied: `bob@example.net`
+    - A verified email address is required [unless email verification is disabled](#control-email-verification).
+    - Access allowed: `alice@example.com`
+    - Access denied: `bob@example.net`
 
     ```yaml hl_lines="5-6"
     oidc:
@@ -92,11 +92,11 @@ are configured, a user needs to pass all of them.
 
 === "Allowed users/emails"
 
-    * Check the email address of each authenticating user against the list of allowed email addresses and only authorize
+    - Check the email address of each authenticating user against the list of allowed email addresses and only authorize
       users whose email is part of the `allowed_users` list.
-    * A verified email address is required [unless email verification is disabled](#control-email-verification).
-    * Access allowed: `alice@example.com`, `bob@example.net`
-    * Access denied: `mallory@example.net`
+    - A verified email address is required [unless email verification is disabled](#control-email-verification).
+    - Access allowed: `alice@example.com`, `bob@example.net`
+    - Access denied: `mallory@example.net`
 
     ```yaml hl_lines="5-7"
     oidc:
@@ -110,10 +110,10 @@ are configured, a user needs to pass all of them.
 
 === "Allowed groups"
 
-    * Use the OIDC `groups` claim of each authenticating user to get their group membership and only authorize users
+    - Use the OIDC `groups` claim of each authenticating user to get their group membership and only authorize users
       which are members in at least one of the referenced groups.
-    * Access allowed: users in the `headscale_users` group
-    * Access denied: users without groups, users with other groups
+    - Access allowed: users in the `headscale_users` group
+    - Access denied: users without groups, users with other groups
 
     ```yaml hl_lines="5-7"
     oidc:
@@ -145,16 +145,12 @@ oidc:
 ### Customize node expiration
 
 The node expiration is the amount of time a node is authenticated with OpenID Connect until it expires and needs to
-reauthenticate. The default node expiration is 180 days. This can either be customized or set to the expiration from the
-Access Token.
+reauthenticate. The default node expiration can be configured via the top-level `node.expiry` setting.
 
 === "Customize node expiration"
 
-    ```yaml hl_lines="5"
-    oidc:
-      issuer: "https://sso.example.com"
-      client_id: "headscale"
-      client_secret: "generated-secret"
+    ```yaml hl_lines="2"
+    node:
       expiry: 30d   # Use 0 to disable node expiration
     ```
 
@@ -163,7 +159,6 @@ Access Token.
     Please keep in mind that the Access Token is typically a short-lived token that expires within a few minutes. You
     will have to configure token expiration in your identity provider to avoid frequent re-authentication.
 
-
     ```yaml hl_lines="5"
     oidc:
       issuer: "https://sso.example.com"
@@ -175,6 +170,7 @@ Access Token.
 !!! tip "Expire a node and force re-authentication"
 
     A node can be expired immediately via:
+
     ```console
     headscale node expire -i <NODE_ID>
     ```
@@ -185,13 +181,16 @@ You may refer to users in the Headscale policy via:
 
 - Email address
 - Username
-- Provider identifier (only available in the database or from your identity provider)
+- Provider identifier (this value is currently only available from the [API](api.md), database or directly from your
+  identity provider)
 
 !!! note "A user identifier in the policy must contain a single `@`"
 
     The Headscale policy requires a single `@` to reference a user. If the username or provider identifier doesn't
-    already contain a single `@`, it needs to be appended at the end. For example: the username `ssmith` has to be
-    written as `ssmith@` to be correctly identified as user within the policy.
+    already contain a single `@`, it needs to be appended at the end. For example: the Headscale username `ssmith` has
+    to be written as `ssmith@` to be correctly identified as user within the policy.
+
+    Ensure that the Headscale username itself does not end with `@`.
 
 !!! warning "Email address or username might be updated by users"
 
@@ -200,6 +199,34 @@ You may refer to users in the Headscale policy via:
     consequences for Headscale where a policy might no longer work or a user might obtain more access by hijacking an
     existing username or email address.
 
+!!! tip "Howto use the provider identifier in the policy"
+
+    The provider identifier uniquely identifies an OIDC user and a well-behaving identity provider guarantees that this
+    value never changes for a particular user. It is usually an opaque and long string and its value is currently only
+    available from the [API](api.md), database or directly from your identity provider).
+
+    Use the [API](api.md) with the `/api/v1/user` endpoint to fetch the provider identifier (`providerId`). The value
+    (be sure to append an `@` in case the provider identifier doesn't already contain an `@` somewhere) can be used
+    directly to reference a user in the policy. To improve readability of the policy, one may use the `groups` section
+    as an alias:
+
+    ```json
+    {
+      "groups": {
+        "group:alice": [
+          "https://sso.example.com/oauth2/openid/59ac9125-c31b-46c5-814e-06242908cf57@"
+        ]
+      },
+      "grants": [
+        {
+          "src": ["group:alice"],
+          "dst": ["*"],
+          "ip": ["*"]
+        }
+      ]
+    }
+    ```
+
 ## Supported OIDC claims
 
 Headscale uses [the standard OIDC claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) to
@@ -219,7 +246,7 @@ endpoint.
 
 - Support for OpenID Connect aims to be generic and vendor independent. It offers only limited support for quirks of
   specific identity providers.
-- OIDC groups cannot be used in ACLs.
+- OIDC groups cannot be used in policy rules.
 - The username provided by the identity provider needs to adhere to this pattern:
     - The username must be at least two characters long.
     - It must only contain letters, digits, hyphens, dots, underscores, and up to a single `@`.
@@ -252,12 +279,13 @@ Authelia is fully supported by Headscale.
 - Authentik is fully supported by Headscale.
 - [Headscale does not support JSON Web Encryption](https://github.com/juanfont/headscale/issues/2446). Leave the field
   `Encryption Key` in the providers section unset.
+- See Authentik's [Integrate with Headscale](https://integrations.goauthentik.io/networking/headscale/)
 
 ### Google OAuth
 
-!!! warning "No username due to missing preferred_username"
+!!! warning "No username due to missing preferred_username claim"
 
-    Google OAuth does not send the `preferred_username` claim when the scope `profile` is requested. The username in
+    Google OAuth does not send the `preferred_username` claim when the `profile` scope is requested. The username in
     Headscale will be blank/not set.
 
 In order to integrate Headscale with Google, you'll need to have a [Google Cloud
@@ -273,22 +301,30 @@ Console.
 #### Steps
 
 1. Go to [Google Console](https://console.cloud.google.com) and login or create an account if you don't have one.
-2. Create a project (if you don't already have one).
-3. On the left hand menu, go to `APIs and services` -> `Credentials`
-4. Click `Create Credentials` -> `OAuth client ID`
-5. Under `Application Type`, choose `Web Application`
-6. For `Name`, enter whatever you like
-7. Under `Authorised redirect URIs`, add Headscale's OIDC callback URL: `https://headscale.example.com/oidc/callback`
-8. Click `Save` at the bottom of the form
-9. Take note of the `Client ID` and `Client secret`, you can also download it for reference if you need it.
-10. [Configure Headscale following the "Basic configuration" steps](#basic-configuration). The issuer URL for Google
-    OAuth is: `https://accounts.google.com`.
+1. Create a project (if you don't already have one).
+1. On the left hand menu, go to `APIs and services` -> `Credentials`
+1. Click `Create Credentials` -> `OAuth client ID`
+1. Under `Application Type`, choose `Web Application`
+1. For `Name`, enter whatever you like
+1. Under `Authorised redirect URIs`, add Headscale's OIDC callback URL: `https://headscale.example.com/oidc/callback`
+1. Click `Save` at the bottom of the form
+1. Take note of the `Client ID` and `Client secret`, you can also download it for reference if you need it.
+1. [Configure Headscale following the "Basic configuration" steps](#basic-configuration). The issuer URL for Google
+   OAuth is: `https://accounts.google.com`.
 
 ### Kanidm
 
 - Kanidm is fully supported by Headscale.
 - Groups for the [allowed groups filter](#authorize-users-with-filters) need to be specified with their full SPN, for
   example: `headscale_users@sso.example.com`.
+- Kanidm sends the full SPN (`alice@sso.example.com`) as `preferred_username` by default. Headscale stores this value as
+  username which might be confusing as the username and email fields now contain values that look like an email address.
+  [Kanidm can be configured to send the short username as `preferred_username` attribute
+  instead](https://kanidm.github.io/kanidm/stable/integrations/oauth2.html#short-names):
+    ```console
+    kanidm system oauth2 prefer-short-username <client name>
+    ```
+    Once configured, the short username in Headscale will be `alice` and can be referred to as `alice@` in the policy.
 
 ### Keycloak
 
@@ -332,3 +368,9 @@ oidc:
 
 Groups for the [allowed groups filter](#authorize-users-with-filters) need to be specified with their group ID(UUID) instead
 of the group name.
+
+## Switching OIDC providers
+
+Headscale only supports a single OIDC provider in its configuration, but it does store the provider identifier of each user. When switching providers, this might lead to issues with existing users: all user details (name, email, groups) might be identical with the new provider, but the identifier will differ. Headscale will be unable to create a new user as the name and email will already be in use for the existing users.
+
+At this time, you will need to manually update the `provider_identifier` column in the `users` table for each user with the appropriate value for the new provider. The identifier is built from the `iss` and `sub` claims of the OIDC ID token, for example `https://id.example.com/12340987`.

docs/ref/policy.md

@@ -0,0 +1,249 @@
+# Policy
+
+Headscale implements a large portion of Tailscale's [policy
+features](https://tailscale.com/docs/features/tailnet-policy-file), most notably access control based on
+[ACLs](https://tailscale.com/docs/features/access-control/acls) and
+[Grants](https://tailscale.com/docs/features/access-control/grants) or [Tailscale
+SSH](https://tailscale.com/docs/features/tailscale-ssh). See [limitations](#limitations) to learn about missing features
+and notable implementation differences between Headscale and Tailscale.
+
+Headscale uses the same [huJSON](https://github.com/tailscale/hujson) based file format as Tailscale. By default, no
+policy is loaded which means that Headscale allows all traffic between nodes. To start using a policy file[^1], specify
+its path in the `policy.path` key in the [configuration file](configuration.md).
+
+Headscale needs to be reloaded to pick up changes to the policy file. Either reload Headscale via its systemd service
+(`sudo systemctl reload headscale`) or by sending a SIGHUP signal (`sudo kill -HUP $(pidof headscale)`) to the main
+process. Headscale logs the result of policy processing after each reload.
+
+Please have a look at Tailscale's policy related documentation to learn more:
+
+- [Tailscale policy file](https://tailscale.com/docs/features/tailnet-policy-file): A description of supported sections
+  within the policy file along with links to syntax references for each section.
+- [ACLs](https://tailscale.com/docs/features/access-control/acls): How to configure access control using ACLs.
+- [Grants](https://tailscale.com/docs/features/access-control/grants): Introduction to Grants with links to [syntax
+  reference](https://tailscale.com/docs/reference/syntax/grants),
+  [examples](https://tailscale.com/docs/reference/examples/grants) and a [migration guide from ACLs to
+  Grants](https://tailscale.com/docs/reference/migrate-acls-grants).
+
+## Getting started
+
+Headscale supports both [ACLs](https://tailscale.com/docs/features/access-control/acls) and
+[Grants](https://tailscale.com/docs/features/access-control/grants) to write an access control policy. We recommend the
+use of Grants since ACLs are considered legacy and will not receive new features by Tailscale.
+
+### Allow All
+
+If you define a policy file but completely omit the `"acls"` or `"grants"` section, Headscale will default to an [allow
+all](https://tailscale.com/docs/reference/examples/acls#allow-all-default-acl) policy. This means all devices connected
+to your tailnet will be able to communicate freely with each other.
+
+```json title="policy.json"
+{}
+```
+
+### Deny All
+
+To [prevent all communication within your tailnet](https://tailscale.com/docs/reference/examples/acls#deny-all), you can
+include an empty array for the `"grants"` section in your policy file.
+
+```json title="policy.json"
+{
+  "grants": []
+}
+```
+
+### More examples
+
+- See our documentation on [subnet routers](routes.md#subnet-router) and [exit nodes](routes.md#exit-node) to learn how
+  to restrict their use or how to automatically approve them.
+- The Tailscale documentation provides a large collection of configuration examples:
+    - [ACL examples](https://tailscale.com/docs/reference/examples/acls)
+    - [Grants examples](https://tailscale.com/docs/reference/examples/grants)
+    - [SSH configuration](https://tailscale.com/docs/features/tailscale-ssh#configure-tailscale-ssh)
+    - [Define a tag](https://tailscale.com/docs/features/tags#define-a-tag)
+
+______________________________________________________________________
+
+## Limitations
+
+- [Device postures](https://tailscale.com/docs/features/device-posture) and the related sections such as `postures` or
+  `srcPosture` aren't supported.
+- [IP sets](https://tailscale.com/docs/features/tailnet-policy-file/ip-sets) aren't supported.
+- A subset of [Autogroups](#autogroups) are available.
+
+## Autogroups
+
+Headscale supports several [Autogroups](https://tailscale.com/docs/reference/targets-and-selectors#autogroups) that
+automatically include users, destinations, or devices with specific properties. Autogroups provide a convenient way to
+write policy rules without manually listing individual users or devices.
+
+### [`autogroup:internet`](https://tailscale.com/docs/reference/targets-and-selectors#autogroupinternet)
+
+Allows access to the internet through [exit nodes](routes.md#exit-node). Can only be used in policy destinations.
+
+```json title="policy.json"
+{
+  "grants": [
+    {
+      "src": ["alice@"],
+      "dst": ["autogroup:internet"],
+      "ip": ["*"]
+    }
+  ]
+}
+```
+
+### [`autogroup:member`](https://tailscale.com/docs/reference/targets-and-selectors#autogrouprole)
+
+Includes all [personal (untagged) devices](registration.md/#identity-model).
+
+```json title="policy.json"
+{
+  "grants": [
+    {
+      "src": ["autogroup:member"],
+      "dst": ["tag:prod-app-servers"],
+      "ip": ["80,443"]
+    }
+  ]
+}
+```
+
+### [`autogroup:tagged`](https://tailscale.com/docs/reference/targets-and-selectors#autogrouptagged)
+
+Includes all devices that [have at least one tag](registration.md/#identity-model).
+
+```json title="policy.json"
+{
+  "grants": [
+    {
+      "src": ["autogroup:tagged"],
+      "dst": ["tag:monitoring"],
+      "ip": ["9090"]
+    }
+  ]
+}
+```
+
+### [`autogroup:self`](https://tailscale.com/docs/reference/targets-and-selectors#autogroupself)
+
+Includes devices where the same user is authenticated on both the source and destination. Does not include tagged
+devices. Can only be used in policy destinations.
+
+```json title="policy.json"
+{
+  "grants": [
+    {
+      "src": ["autogroup:member"],
+      "dst": ["autogroup:self"],
+      "ip": ["*"]
+    }
+  ]
+}
+```
+
+!!! warning "The current implementation of `autogroup:self` is inefficient"
+
+    Using `autogroup:self` may cause performance degradation on the Headscale coordinator server in large deployments,
+    as filter rules must be compiled per-node rather than globally and the current implementation is not very efficient.
+
+    If you experience performance issues, consider using more specific policy rules or limiting the use of
+    `autogroup:self`.
+
+    ```json title="policy.json"
+    {
+      "grants": [
+        // The following rules allow internal users to communicate with their
+        // own nodes in case autogroup:self is causing performance issues.
+        {
+          "src": ["boss@"],
+          "dst": ["boss@"],
+          "ip": ["*"]
+        },
+        {
+          "src": ["dev1@"],
+          "dst": ["dev1@"],
+          "ip": ["*"]
+        },
+        {
+          "src": ["intern1@"],
+          "dst": ["intern1@"],
+          "ip": ["*"]
+        }
+      ]
+    }
+    ```
+
+### [`autogroup:nonroot`](https://tailscale.com/docs/reference/targets-and-selectors#other-built-in-targets)
+
+Used in Tailscale SSH rules to allow access to any user except root. Can only be used in the `users` field of SSH rules.
+
+```json title="policy.json"
+{
+  "ssh": [
+    {
+      "action": "accept",
+      "src": ["autogroup:member"],
+      "dst": ["autogroup:self"],
+      "users": ["autogroup:nonroot"]
+    }
+  ]
+}
+```
+
+### [`autogroup:danger-all`](https://tailscale.com/docs/reference/targets-and-selectors#autogroupdanger-all)
+
+This autogroup resolves to all IP addresses (`0.0.0.0/0` and `::/0`) which also includes all IP addresses outside the
+standard Tailscale IP ranges. This autogroup can only be used as source.
+
+## Node Attributes
+
+[Node attributes](https://tailscale.com/docs/reference/syntax/policy-file#node-attributes) allow for device-specific
+configuration and attributes. At least the following node attributes are currently supported by Headscale[^2]:
+
+- `drive:access`, `drive:share`: [Taildrive support](https://tailscale.com/docs/features/taildrive).
+- `nextdns:<profile>`, `nextdns:no-device-info`: [NextDNS integration](https://tailscale.com/docs/integrations/nextdns).
+  Be sure to set NextDNS as global resolver in the [configuration](configuration.md).
+- `magicdns-aaaa`: Respond to AAAA queries on the local [MagicDNS](https://tailscale.com/docs/features/magicdns)
+  resolver at 100.100.100.100.
+- `disable-ipv4`: Selectively disable IPv4 for specfic nodes. This is may be useful to workaround [CGNat
+  conflicts](https://tailscale.com/docs/reference/troubleshooting/network-configuration/cgnat-conflicts).
+- `randomize-client-port`: Allocate a [random port for WireGuard
+  traffic](https://tailscale.com/docs/reference/syntax/policy-file#randomizeclientport) instead of the static default
+  port 41641.
+- `disable-captive-portal-detection`: [Disable automatic captive portal
+  detection](https://tailscale.com/docs/integrations/captive-portals#disable-captive-portal-detection).
+
+```json title="policy.json"
+{
+  "nodeAttrs": [
+    {
+      // Enable MagicDNS AAAA records for all nodes
+      "target": ["*"]
+      "attr": ["magicdns-aaaa"]
+    }
+  ]
+}
+```
+
+## Network-wide policy options
+
+The following options are applied for the entire tailnet. Consider [node attributes](#node-attributes) for a more
+fine-grained configuration instead.
+
+- `randomizeClientPort`: Allocate a [random port for WireGuard
+  traffic](https://tailscale.com/docs/reference/syntax/policy-file#randomizeclientport) instead of the static default
+  port 41641.
+
+```json title="policy.json"
+{
+  // Use a random WireGuard port for the entire tailnet
+  "randomizeClientPort": true
+}
+```
+
+[^1]: Headscale also allows to store the policy in the database. This is typically only required in case a [web
+    interface](integration/web-ui.md) is used.
+
+[^2]: Other key-only node attributes can be used as well. Find them in the client source code with `grep -E '^\s+NodeAttr\w+' tailcfg/tailcfg.go` or by using [GitHub code search (requires
+    login)](https://github.com/search?q=repo%3Atailscale%2Ftailscale%20language%3Ago%20path%3Atailcfg%2Ftailcfg.go%20symbol%3A%2FNodeAttr%5Cw%2B%2F&type=code).

docs/ref/registration.md

@@ -11,8 +11,8 @@ Tailscale's identity model distinguishes between personal and tagged nodes:
   workstations or mobile phones. End-user devices are managed by a single user.
 - A tagged node (or service-based node or non-human node) provides services to the network. Common examples include web-
   and database servers. Those nodes are typically managed by a team of users. Some additional restrictions apply for
-  tagged nodes, e.g. a tagged node is not allowed to [Tailscale SSH](https://tailscale.com/kb/1193/tailscale-ssh) into a
-  personal node.
+  tagged nodes, e.g. a tagged node is not allowed to [Tailscale SSH](https://tailscale.com/docs/features/tailscale-ssh)
+  into a personal node.
 
 Headscale implements Tailscale's identity model and distinguishes between personal and tagged nodes where a personal
 node is owned by a Headscale user and a tagged node is owned by a tag. Tagged devices are grouped under the special user
@@ -33,7 +33,8 @@ node can be approved with:
 - [Headscale API](api.md)
 - Or delegated to an identity provider via [OpenID Connect](oidc.md)
 
-Web authentication relies on the presence of a Headscale user. Use the `headscale users` command to create a new user:
+Web authentication relies on the presence of a Headscale user. Use the `headscale users` command to create a new
+user[^1]:
 
 ```console
 headscale users create <USER>
@@ -48,10 +49,10 @@ headscale users create <USER>
     ```
 
     Usually, a browser window with further instructions is opened. This page explains how to complete the registration
-    on your Headscale server and it also prints the registration key required to approve the node:
+    on your Headscale server and it also prints the Auth ID required to approve the node:
 
     ```console
-    headscale nodes register --user <USER> --key <REGISTRATION_KEY>
+    headscale auth register --user <USER> --auth-id <AUTH_ID>
     ```
 
     Congrations, the registration of your personal node is complete and it should be listed as "online" in the output of
@@ -60,8 +61,8 @@ headscale users create <USER>
 === "Tagged devices"
 
     Your Headscale user needs to be authorized to register tagged devices. This authorization is specified in the
-    [`tagOwners`](https://tailscale.com/kb/1337/policy-syntax#tag-owners) section of the [ACL](acls.md). A simple
-    example looks like this:
+    [`tagOwners`](https://tailscale.com/docs/reference/syntax/policy-file#tag-owners) section of the
+    [policy](policy.md). A simple example looks like this:
 
     ```json title="The user alice can register nodes tagged with tag:server"
     {
@@ -79,10 +80,10 @@ headscale users create <USER>
     ```
 
     Usually, a browser window with further instructions is opened. This page explains how to complete the registration
-    on your Headscale server and it also prints the registration key required to approve the node:
+    on your Headscale server and it also prints the Auth ID required to approve the node:
 
     ```console
-    headscale nodes register --user <USER> --key <REGISTRATION_KEY>
+    headscale auth register --user <USER> --auth-id <AUTH_ID>
     ```
 
     Headscale checks that `<USER>` is allowed to register a node with the specified tag(s) and then transfers ownership
@@ -98,7 +99,7 @@ Its best suited for automation.
 
 === "Personal devices"
 
-    A personal node is always assigned to a Headscale user. Use the `headscale users` command to create a new user:
+    A personal node is always assigned to a Headscale user. Use the `headscale users` command to create a new user[^1]:
 
     ```console
     headscale users create <USER>
@@ -136,6 +137,8 @@ Its best suited for automation.
     tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
     ```
 
-    The registration of a tagged node is complete and it should be listed as "online" in the output of `headscale nodes
-    list`. The "User" column displays `tagged-devices` as the owner of the node. See the "Tags" column for the list of
+    The registration of a tagged node is complete and it should be listed as "online" in the output of
+    `headscale nodes list`. The "User" column displays `tagged-devices` as the owner of the node. See the "Tags" column for the list of
     assigned tags.
+
+[^1]: [Ensure that the Headscale username does not end with `@`.](oidc.md#reference-a-user-in-the-policy)

docs/ref/routes.md

@@ -1,7 +1,8 @@
 # Routes
 
-Headscale supports route advertising and can be used to manage [subnet routers](https://tailscale.com/kb/1019/subnets)
-and [exit nodes](https://tailscale.com/kb/1103/exit-nodes) for a tailnet.
+Headscale supports route advertising and can be used to manage [subnet
+routers](https://tailscale.com/docs/features/subnet-routers) and [exit
+nodes](https://tailscale.com/docs/features/exit-nodes) for a tailnet.
 
 - [Subnet routers](#subnet-router) may be used to connect an existing network such as a virtual
   private cloud or an on-premise network with your tailnet. Use a subnet router to access devices where Tailscale can't
@@ -72,32 +73,32 @@ $ sudo tailscale set --accept-routes
 ```
 
 Please refer to the official [Tailscale
-documentation](https://tailscale.com/kb/1019/subnets#use-your-subnet-routes-from-other-devices) for how to use a subnet
-router on different operating systems.
+documentation](https://tailscale.com/docs/features/subnet-routers#use-your-subnet-routes-from-other-devices) for how to
+use a subnet router on different operating systems.
 
-### Restrict the use of a subnet router with ACL
+### Restrict the use of a subnet router with a policy
 
-The routes announced by subnet routers are available to the nodes in a tailnet. By default, without an ACL enabled, all
-nodes can accept and use such routes. Configure an ACL to explicitly manage who can use routes.
+The routes announced by subnet routers are available to the nodes in a tailnet. By default, without a policy enabled,
+all nodes can accept and use such routes. Configure a policy to explicitly manage who can use routes.
 
-The ACL snippet below defines three hosts, a subnet router `router`, a regular node `node` and `service.example.net` as
-internal service that can be reached via a route on the subnet router `router`. It allows the node `node` to access
+The policy snippet below defines three hosts, a subnet router `router`, a regular node `node` and `service.example.net`
+as internal service that can be reached via a route on the subnet router `router`. It allows the node `node` to access
 `service.example.net` on port 80 and 443 which is reachable via the subnet router. Access to the subnet router itself is
 denied.
 
 ```json title="Access the routes of a subnet router without the subnet router itself"
 {
   "hosts": {
-    // the router is not referenced but announces 192.168.0.0/24"
+    // the router is not referenced but announces 192.168.0.0/24
     "router": "100.64.0.1/32",
     "node": "100.64.0.2/32",
     "service.example.net": "192.168.0.1/32"
   },
-  "acls": [
+  "grants": [
     {
-      "action": "accept",
       "src": ["node"],
-      "dst": ["service.example.net:80,443"]
+      "dst": ["service.example.net"],
+      "ip": ["80,443"]
     }
   ]
 }
@@ -106,10 +107,10 @@ denied.
 ### Automatically approve routes of a subnet router
 
 The initial setup of a subnet router usually requires manual approval of their announced routes on the control server
-before they can be used by a node in a tailnet. Headscale supports the `autoApprovers` section of an ACL to automate the
-approval of routes served with a subnet router.
+before they can be used by a node in a tailnet. Headscale supports the `autoApprovers` section in a policy to automate
+the approval of routes served with a subnet router.
 
-The ACL snippet below defines the tag `tag:router` owned by the user `alice`. This tag is used for `routes` in the
+The policy snippet below defines the tag `tag:router` owned by the user `alice`. This tag is used for `routes` in the
 `autoApprovers` section. The IPv4 route `192.168.0.0/24` is automatically approved once announced by a subnet router
 that advertises the tag `tag:router`.
 
@@ -123,7 +124,7 @@ that advertises the tag `tag:router`.
       "192.168.0.0/24": ["tag:router"]
     }
   },
-  "acls": [
+  "grants": [
     // more rules
   ]
 }
@@ -135,8 +136,9 @@ Advertise the route `192.168.0.0/24` from a subnet router that also advertises t
 $ sudo tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-tags tag:router --advertise-routes 192.168.0.0/24
 ```
 
-Please see the [official Tailscale documentation](https://tailscale.com/kb/1337/acl-syntax#autoapprovers) for more
-information on auto approvers.
+Please see the [official Tailscale
+documentation](https://tailscale.com/docs/reference/syntax/policy-file#auto-approvers) for more information on auto
+approvers.
 
 ## Exit node
 
@@ -199,22 +201,22 @@ The exit node can now be used on a node with:
 $ sudo tailscale set --exit-node myexit
 ```
 
-Please refer to the official [Tailscale documentation](https://tailscale.com/kb/1103/exit-nodes#use-the-exit-node) for
-how to use an exit node on different operating systems.
+Please refer to the official [Tailscale documentation](https://tailscale.com/docs/features/exit-nodes#use-the-exit-node)
+for how to use an exit node on different operating systems.
 
-### Restrict the use of an exit node with ACL
+### Restrict the use of an exit node with a policy
 
-An exit node is offered to all nodes in a tailnet. By default, without an ACL enabled, all nodes in a tailnet can select
-and use an exit node. Configure `autogroup:internet` in an ACL rule to restrict who can use _any_ of the available exit
-nodes.
+An exit node is offered to all nodes in a tailnet. By default, without a policy enabled, all nodes in a tailnet can
+select and use an exit node. Configure `autogroup:internet` in a policy rule to restrict who can use _any_ of the
+available exit nodes.
 
 ```json title="Example use of autogroup:internet"
 {
-  "acls": [
+  "grants": [
     {
-      "action": "accept",
       "src": ["..."],
-      "dst": ["autogroup:internet:*"]
+      "dst": ["autogroup:internet"],
+      "ip": ["*"]
     }
   ]
 }
@@ -222,45 +224,41 @@ nodes.
 
 ### Restrict access to exit nodes per user or group
 
-A user can use _any_ of the available exit nodes with `autogroup:internet`. Alternatively, the ACL snippet below assigns
-each user a specific exit node while hiding all other exit nodes. The user `alice` can only use exit node `exit1` while
-user `bob` can only use exit node `exit2`.
+A user can use _any_ of the available exit nodes with `autogroup:internet`. Alternatively, the policy snippet below
+assigns each user a specific exit node while hiding all other exit nodes. The user `alice` can only use an exit node
+tagged with `tag:exit1` while user `bob` can only use an exit node tagged with `tag:exit2`.
 
 ```json title="Assign each user a dedicated exit node"
 {
-  "hosts": {
-    "exit1": "100.64.0.1/32",
-    "exit2": "100.64.0.2/32"
+  "tagOwners": {
+    "tag:exit1": ["alice@"],
+    "tag:exit2": ["bob@"]
   },
-  "acls": [
+  "grants": [
     {
-      "action": "accept",
       "src": ["alice@"],
-      "dst": ["exit1:*"]
+      "dst": ["autogroup:internet"],
+      "via": ["tag:exit1"],
+      "ip": ["*"]
     },
     {
-      "action": "accept",
       "src": ["bob@"],
-      "dst": ["exit2:*"]
+      "dst": ["autogroup:internet"],
+      "via": ["tag:exit2"],
+      "ip": ["*"]
     }
   ]
 }
 ```
 
-!!! warning
-
-    - The above implementation is Headscale specific and will likely be removed once [support for
-      `via`](https://github.com/juanfont/headscale/issues/2409) is available.
-    - Beware that a user can also connect to any port of the exit node itself.
-
 ### Automatically approve an exit node with auto approvers
 
 The initial setup of an exit node usually requires manual approval on the control server before it can be used by a node
-in a tailnet. Headscale supports the `autoApprovers` section of an ACL to automate the approval of a new exit node as
+in a tailnet. Headscale supports the `autoApprovers` section in a policy to automate the approval of a new exit node as
 soon as it joins the tailnet.
 
-The ACL snippet below defines the tag `tag:exit` owned by the user `alice`. This tag is used for `exitNode` in the
-`autoApprovers` section. A new exit node that advertises the tag `tag:exit` is automatically approved:
+The policy snippet below defines the tag `tag:exit` owned by the user `alice`. This tag is used for the `exitNode` entry
+in the `autoApprovers` section. A new exit node that advertises the tag `tag:exit` is automatically approved:
 
 ```json title="Exit nodes tagged with tag:exit are automatically approved"
 {
@@ -270,7 +268,7 @@ The ACL snippet below defines the tag `tag:exit` owned by the user `alice`. This
   "autoApprovers": {
     "exitNode": ["tag:exit"]
   },
-  "acls": [
+  "grants": [
     // more rules
   ]
 }
@@ -282,26 +280,23 @@ Advertise a node as exit node and also advertise the tag `tag:exit` when joining
 $ sudo tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-tags tag:exit --advertise-exit-node
 ```
 
-Please see the [official Tailscale documentation](https://tailscale.com/kb/1337/acl-syntax#autoapprovers) for more
-information on auto approvers.
+Please see the [official Tailscale documentation](https://tailscale.com/docs/reference/syntax/policy-file#autoapprovers)
+for more information on auto approvers.
 
 ## High availability
 
-Headscale has limited support for high availability routing. Multiple subnet routers with overlapping routes or multiple
-exit nodes can be used to provide high availability for users. If one router node goes offline, another one can serve
-the same routes to clients. Please see the official [Tailscale documentation on high
-availability](https://tailscale.com/kb/1115/high-availability#subnet-router-high-availability) for details.
+Headscale supports high availability routing. Multiple subnet routers with overlapping routes or multiple exit nodes can
+be used to provide high availability for users. If one router node goes offline, another one can serve the same routes
+to clients. Please see the official [Tailscale documentation on high
+availability](https://tailscale.com/docs/how-to/set-up-high-availability#subnet-router-high-availability) for details.
 
-!!! bug
-
-    In certain situations it might take up to 16 minutes for Headscale to detect a node as offline. A failover node
-    might not be selected fast enough, if such a node is used as subnet router or exit node causing service
-    interruptions for clients. See [issue 2129](https://github.com/juanfont/headscale/issues/2129) for more information.
+This feature is enabled by default when at least two nodes advertise the same prefix. See the configuration options
+`node.routes.ha` in the [configuration file](configuration.md) for details.
 
 ## Troubleshooting
 
 ### Enable IP forwarding
 
 A subnet router or exit node is routing traffic on behalf of other nodes and thus requires IP forwarding. Check the
-official [Tailscale documentation](https://tailscale.com/kb/1019/subnets/?tab=linux#enable-ip-forwarding) for how to
+official [Tailscale documentation](https://tailscale.com/docs/features/subnet-routers#enable-ip-forwarding) for how to
 enable IP forwarding.

docs/ref/tags.md

@@ -1,7 +1,7 @@
 # Tags
 
-Headscale supports Tailscale tags. Please read [Tailscale's tag documentation](https://tailscale.com/kb/1068/tags) to
-learn how tags work and how to use them.
+Headscale supports Tailscale tags. Please read [Tailscale's tag documentation](https://tailscale.com/docs/features/tags)
+to learn how tags work and how to use them.
 
 Tags can be applied during [node registration](registration.md):
 
@@ -45,10 +45,10 @@ tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-tags= --force-reaut
 ```
 
 Usually, a browser window with further instructions is opened. This page explains how to complete the registration on
-your Headscale server and it also prints the registration key required to approve the node:
+your Headscale server and it also prints the Auth ID required to approve the node:
 
 ```console
-headscale nodes register --user <USER> --key <REGISTRATION_KEY>
+headscale auth register --user <USER> --auth-id <AUTH_ID>
 ```
 
 All previously assigned tags get removed and the node is now owned by the user specified in the above command.

docs/ref/tls.md

@@ -50,7 +50,7 @@ Headscale uses [autocert](https://pkg.go.dev/golang.org/x/crypto/acme/autocert),
 If you want to validate that certificate renewal completed successfully, this can be done either manually, or through external monitoring software. Two examples of doing this manually:
 
 1. Open the URL for your headscale server in your browser of choice, and manually inspecting the expiry date of the certificate you receive.
-2. Or, check remotely from CLI using `openssl`:
+1. Or, check remotely from CLI using `openssl`:
 
 ```console
 $ openssl s_client -servername [hostname] -connect [hostname]:443 | openssl x509 -noout -dates

docs/requirements.txt

@@ -1,6 +1,6 @@
 mike~=2.1
-mkdocs-include-markdown-plugin~=7.1
-mkdocs-macros-plugin~=1.3
-mkdocs-material[imaging]~=9.5
-mkdocs-minify-plugin~=0.7
+mkdocs-include-markdown-plugin~=7.2
+mkdocs-macros-plugin~=1.5
+mkdocs-materialx[imaging]~=10.1
+mkdocs-minify-plugin~=0.8
 mkdocs-redirects~=1.2

docs/setup/install/community.md

@@ -1,7 +1,7 @@
 # Community packages
 
 Several Linux distributions and community members provide packages for headscale. Those packages may be used instead of
-the [official releases](./official.md) provided by the headscale maintainers. Such packages offer improved integration
+the [official releases](official.md) provided by the headscale maintainers. Such packages offer improved integration
 for their targeted operating system and usually:
 
 - setup a dedicated local user account to run headscale
@@ -10,8 +10,8 @@ for their targeted operating system and usually:
 
 !!! warning "Community packages might be outdated"
 
-    The packages mentioned on this page might be outdated or unmaintained. Use the [official releases](./official.md) to
-    get the current stable version or to test pre-releases.
+    The packages mentioned on this page might be outdated or unmaintained. Use the [official releases](official.md) to
+    get the current stable version or to [test pre-releases](main.md).
 
     [![Packaging status](https://repology.org/badge/vertical-allrepos/headscale.svg)](https://repology.org/project/headscale/versions)
 
@@ -23,9 +23,6 @@ Arch Linux offers a package for headscale, install via:
 pacman -S headscale
 ```
 
-The [AUR package `headscale-git`](https://aur.archlinux.org/packages/headscale-git) can be used to build the current
-development version.
-
 ## Fedora, RHEL, CentOS
 
 A third-party repository for various RPM based distributions is available at:

docs/setup/install/container.md

@@ -7,9 +7,8 @@
 
     **It might be outdated and it might miss necessary steps**.
 
-This documentation has the goal of showing a user how-to set up and run headscale in a container. A container runtime
-such as [Docker](https://www.docker.com) or [Podman](https://podman.io) is required. The container image can be found on
-[Docker Hub](https://hub.docker.com/r/headscale/headscale) and [GitHub Container
+A container runtime such as [Docker](https://www.docker.com) or [Podman](https://podman.io) is required. The container
+image can be found on [Docker Hub](https://hub.docker.com/r/headscale/headscale) and [GitHub Container
 Registry](https://github.com/juanfont/headscale/pkgs/container/headscale). The container image URLs are:
 
 - [Docker Hub](https://hub.docker.com/r/headscale/headscale): `docker.io/headscale/headscale:<VERSION>`
@@ -18,17 +17,17 @@ Registry](https://github.com/juanfont/headscale/pkgs/container/headscale). The c
 
 ## Configure and run headscale
 
-1.  Create a directory on the container host to store headscale's [configuration](../../ref/configuration.md) and the [SQLite](https://www.sqlite.org/) database:
+1. Create a directory on the container host to store headscale's [configuration](../../ref/configuration.md) and the SQLite database:
 
     ```shell
     mkdir -p ./headscale/{config,lib}
     cd ./headscale
     ```
 
-1.  Download the example configuration for your chosen version and save it as: `$(pwd)/config/config.yaml`. Adjust the
-    configuration to suit your local environment. See [Configuration](../../ref/configuration.md) for details.
+1. Download the example configuration for your chosen version and save it as: `$(pwd)/config/config.yaml`. Adjust the
+   configuration to suit your local environment. See [Configuration](../../ref/configuration.md) for details.
 
-1.  Start headscale from within the previously created `./headscale` directory:
+1. Start headscale from within the previously created `./headscale` directory:
 
     ```shell
     docker run \
@@ -74,7 +73,7 @@ Registry](https://github.com/juanfont/headscale/pkgs/container/headscale). The c
             test: ["CMD", "headscale", "health"]
     ```
 
-1.  Verify headscale is running:
+1. Verify headscale is running:
 
     Follow the container logs:
 
@@ -98,7 +97,7 @@ Continue on the [getting started page](../../usage/getting-started.md) to regist
 
 ## Debugging headscale running in Docker
 
-The Headscale container image is based on a "distroless" image that does not contain a shell or any other debug tools. If you need to debug headscale running in the Docker container, you can use the `-debug` variant, for example `docker.io/headscale/headscale:x.x.x-debug`.
+The Headscale container image is based on a distroless image that does not contain a shell or any other debug tools. If you need to debug headscale running in the Docker container, you can use the `-debug` variant, for example `docker.io/headscale/headscale:x.x.x-debug`.
 
 ### Running the debug Docker container