Fix CLI timeout issues in integration tests

- Increase default CLI timeout from 5s to 30s in config.go - Fix error messages to match test expectations ("user/node not found") - Smart lookup gRPC calls need more time in containerized CI environment The CLI smart lookup feature makes additional gRPC calls that require longer timeouts than the original 5-second default, especially in containerized test environments with network latency. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
Fix integration test timeouts by increasing CLI timeout for containerized environment
2026-07-20 23:10:44 +09:00 · 2025-07-16 11:31:51 +00:00 · 2025-07-15 18:10:42 +00:00 · 2025-07-15 16:24:54 +00:00 · 2025-07-15 16:17:31 +00:00 · 2025-07-15 14:51:23 +00:00
1712 changed files with 41572 additions and 12153236 deletions
@@ -21,3 +21,4 @@ LICENSE
 node_modules/
 package-lock.json
 package.json
+
@@ -1,16 +0,0 @@
-root = true
-
-[*]
-charset = utf-8
-end_of_line = lf
-indent_size = 2
-indent_style = space
-insert_final_newline = true
-trim_trailing_whitespace = true
-max_line_length = 120
-
-[*.go]
-indent_style = tab
-
-[Makefile]
-indent_style = tab
@@ -6,7 +6,8 @@ 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
@@ -14,7 +15,8 @@ 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
@@ -50,15 +52,12 @@ body:
        If you are using a container, always provide the headscale version and not only the Docker image version.
        Please do not put "latest".

-        Describe your "headscale network". Is there a lot of nodes, are the nodes all interconnected, are some subnet routers?
-
        If you are experiencing a problem during an upgrade, please provide the versions of the old and new versions of Headscale and Tailscale.

        examples:
          - **OS**: Ubuntu 24.04
          - **Headscale version**: 0.24.3
          - **Tailscale version**: 1.80.0
-          - **Number of nodes**: 20
      value: |
        - OS:
        - Headscale version:
@@ -78,10 +77,6 @@ body:
    attributes:
      label: Debug information
      description: |
-        Please have a look at our [Debugging and troubleshooting
-        guide](https://headscale.net/development/ref/debug/) to learn about
-        common debugging techniques.
-
        Links? References? Anything that will give us more context about the issue you are encountering.
        If **any** of these are omitted we will likely close your issue, do **not** ignore them.

@@ -97,7 +92,7 @@ body:
        `tailscale status --json > DESCRIPTIVE_NAME.json`

        Get the logs of a Tailscale client that is not working as expected.
-        `tailscale debug daemon-logs`
+        `tailscale daemon-logs`

        Tip: You can attach images or log files by clicking this area to highlight it and then dragging files in.
        **Ensure** you use formatting for files you attach.
@@ -3,9 +3,9 @@ blank_issues_enabled: false

 # Contact links
 contact_links:
-  - name: "headscale Discord community"
-    url: "https://discord.gg/c84AZQhmpx"
-    about: "Please ask and answer questions about usage of headscale here."
  - name: "headscale usage documentation"
-    url: "https://headscale.net/"
+    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"
+    about: "Please ask and answer questions about usage of headscale here."
@@ -16,13 +16,15 @@ body:
  - type: textarea
    attributes:
      label: Description
-      description: A clear and precise description of what new or changed feature you want.
+      description:
+        A clear and precise description of what new or changed feature you want.
    validations:
      required: true
  - type: checkboxes
    attributes:
      label: Contribution
-      description: Are you willing to contribute to the implementation of this feature?
+      description:
+        Are you willing to contribute to the implementation of this feature?
      options:
        - label: I can write the design doc for this feature
          required: false
@@ -31,6 +33,7 @@ body:
  - type: textarea
    attributes:
      label: How can it be implemented?
-      description: Free text for your ideas on how this feature could be implemented.
+      description:
+        Free text for your ideas on how this feature could be implemented.
    validations:
      required: false
@@ -1,80 +0,0 @@
-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).
@@ -1,15 +0,0 @@
-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.
@@ -5,21 +5,19 @@ on:
    branches:
      - main
  pull_request:
+    branches:
+      - main

 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
    permissions: write-all
    steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          fetch-depth: 2
      - name: Get changed files
@@ -33,24 +31,34 @@ jobs:
              - '**/*.go'
              - 'integration_test/'
              - 'config-example.yaml'
-      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
+      - uses: nixbuild/nix-quick-install-action@889f3180bb5f064ee9e3201428d04ae9e41d54ad # v31
        if: steps.changed-files.outputs.files == 'true'
-      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
+      - 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: Check vendor hash
-        id: vendorhash
+      - name: Run nix build
+        id: build
        if: steps.changed-files.outputs.files == 'true'
        run: |
-          go run ./cmd/vendorhash check | tee check-result
-          {
-            grep '^expected_sri=' check-result || true
-            grep '^actual_sri='   check-result || true
-          } >> "$GITHUB_OUTPUT"
+          nix build |& tee build-result
+          BUILD_STATUS="${PIPESTATUS[0]}"

-      - name: Vendor hash diverging
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
-        if: failure() && steps.vendorhash.outcome == 'failure'
+          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
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        if: failure() && steps.build.outcome == 'failure'
        with:
          github-token: ${{secrets.GITHUB_TOKEN}}
          script: |
@@ -58,14 +66,10 @@ jobs:
              pull_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
-              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.'
+              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 }}'
            })

-      - name: Run nix build
-        if: steps.changed-files.outputs.files == 'true'
-        run: nix build --fallback
-
-      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        if: steps.changed-files.outputs.files == 'true'
        with:
          name: headscale-linux
@@ -75,21 +79,29 @@ jobs:
    strategy:
      matrix:
        env:
+          - "GOARCH=arm   GOOS=linux GOARM=5"
+          - "GOARCH=arm   GOOS=linux GOARM=6"
+          - "GOARCH=arm   GOOS=linux GOARM=7"
          - "GOARCH=arm64 GOOS=linux"
+          - "GOARCH=386   GOOS=linux"
          - "GOARCH=amd64 GOOS=linux"
          - "GOARCH=arm64 GOOS=darwin"
          - "GOARCH=amd64 GOOS=darwin"
    steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
-      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
-      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: nixbuild/nix-quick-install-action@889f3180bb5f064ee9e3201428d04ae9e41d54ad # v31
+      - 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: Run go cross compile
-        env:
-          CGO_ENABLED: 0
-        run: env ${{ matrix.env }} go build -o "headscale"
+        run:
+          env ${{ matrix.env }} nix develop --command -- go build -o "headscale"
          ./cmd/headscale
-      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: "headscale-${{ matrix.env }}"
          path: "headscale"
@@ -1,54 +0,0 @@
-name: Check Generated Files
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
-
-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
-    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'
-              - 'tools/**'
-      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
-        if: steps.changed-files.outputs.files == 'true'
-      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
-        if: steps.changed-files.outputs.files == 'true'
-
-      - name: Run make generate
-        if: steps.changed-files.outputs.files == 'true'
-        run: make generate
-
-      - name: Check for uncommitted changes
-        if: steps.changed-files.outputs.files == 'true'
-        run: |
-          if ! git diff --exit-code; then
-            echo "❌ Generated files are not up to date!"
-            echo "Please run 'make generate' and commit the changes."
-            exit 1
-          else
-            echo "✅ All generated files are up to date."
-          fi
@@ -6,15 +6,11 @@ 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
    steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          fetch-depth: 2
      - name: Get changed files
@@ -28,15 +24,20 @@ jobs:
              - '**/*.go'
              - 'integration_test/'
              - 'config-example.yaml'
-      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
+      - uses: nixbuild/nix-quick-install-action@889f3180bb5f064ee9e3201428d04ae9e41d54ad # v31
        if: steps.changed-files.outputs.files == 'true'
-      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
+      - 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: Generate and check integration tests
        if: steps.changed-files.outputs.files == 'true'
        run: |
-          (cd .github/workflows && go generate)
+          nix develop --command bash -c "cd .github/workflows && go generate"
          git diff --exit-code .github/workflows/test-integration.yaml

      - name: Show missing tests
@@ -1,108 +0,0 @@
---
-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
@@ -21,15 +21,15 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          fetch-depth: 0
      - name: Install python
-        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
        with:
          python-version: 3.x
      - name: Setup cache
-        uses: actions/cache@a7833574556fa59680c1b7cb190c1735db73ebf0 # v5.0.0
+        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
        with:
          key: ${{ github.ref }}
          path: .cache
@@ -11,13 +11,13 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
      - name: Install python
-        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
        with:
          python-version: 3.x
      - name: Setup cache
-        uses: actions/cache@a7833574556fa59680c1b7cb190c1735db73ebf0 # v5.0.0
+        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
        with:
          key: ${{ github.ref }}
          path: .cache
@@ -1,39 +0,0 @@
-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 }}
@@ -10,55 +10,6 @@ import (
 	"strings"
 )

-// testsToSplit defines tests that should be split into multiple CI jobs.
-// 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:
-//   - TestAutoApproveMultiNetwork/authkey-tag-advertiseduringup-false-pol-database
-//   - TestAutoApproveMultiNetwork/webauth-user-advertiseduringup-true-pol-file
-//
-// Splitting by approver type (tag, user, group) creates 6 CI jobs with 4 tests each:
-//   - TestAutoApproveMultiNetwork/authkey-tag.* (4 tests)
-//   - TestAutoApproveMultiNetwork/authkey-user.* (4 tests)
-//   - TestAutoApproveMultiNetwork/authkey-group.* (4 tests)
-//   - TestAutoApproveMultiNetwork/webauth-tag.* (4 tests)
-//   - TestAutoApproveMultiNetwork/webauth-user.* (4 tests)
-//   - TestAutoApproveMultiNetwork/webauth-group.* (4 tests)
-//
-// This reduces load per CI job (4 tests instead of 12) to avoid infrastructure
-// flakiness when running many sequential Docker-based integration tests.
-var testsToSplit = map[string][]string{
-	"TestAutoApproveMultiNetwork": {
-		"authkey-tag",
-		"authkey-user",
-		"authkey-group",
-		"webauth-tag",
-		"webauth-user",
-		"webauth-group",
-	},
-}
-
-// expandTests takes a list of test names and expands any that need splitting
-// into multiple subtest patterns.
-func expandTests(tests []string) []string {
-	var expanded []string
-	for _, test := range tests {
-		if prefixes, ok := testsToSplit[test]; ok {
-			// This test should be split into multiple jobs.
-			// We append ".*" to each prefix because the CI runner wraps patterns
-			// with ^...$ anchors. Without ".*", a pattern like "authkey$" wouldn't
-			// match "authkey-tag-advertiseduringup-false-pol-database".
-			for _, prefix := range prefixes {
-				expanded = append(expanded, fmt.Sprintf("%s/%s.*", test, prefix))
-			}
-		} else {
-			expanded = append(expanded, test)
-		}
-	}
-	return expanded
-}
-
 func findTests() []string {
 	rgBin, err := exec.LookPath("rg")
 	if err != nil {
@@ -66,9 +17,7 @@ func findTests() []string {
 	}

 	args := []string{
-		"--type", "go",
 		"--regexp", "func (Test.+)\\(.*",
-		"--max-depth", "1",
 		"../../integration/",
 		"--replace", "$1",
 		"--sort", "path",
@@ -117,11 +66,8 @@ func updateYAML(tests []string, jobName string, testPath string) {
 func main() {
 	tests := findTests()

-	// Expand tests that should be split into multiple jobs
-	expandedTests := expandTests(tests)
-
-	quotedTests := make([]string, len(expandedTests))
-	for i, test := range expandedTests {
+	quotedTests := make([]string, len(tests))
+	for i, test := range tests {
 		quotedTests[i] = fmt.Sprintf("\"%s\"", test)
 	}

@@ -11,13 +11,13 @@ jobs:
    runs-on: ubuntu-latest

    steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          # [Required] Access token with `workflow` scope.
          token: ${{ secrets.WORKFLOW_SECRET }}

      - name: Run GitHub Actions Version Updater
-        uses: saadmk11/github-actions-version-updater@d8781caf11d11168579c8e5e94f62b068038f442 # v0.9.0
+        uses: saadmk11/github-actions-version-updater@64be81ba69383f81f2be476703ea6570c4c8686e # v0.8.1
        with:
          # [Required] Access token with `workflow` scope.
          token: ${{ secrets.WORKFLOW_SECRET }}
@@ -16,7 +16,7 @@ on:

 jobs:
  test:
-    runs-on: ubuntu-24.04-arm
+    runs-on: ubuntu-latest
    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.
@@ -28,12 +28,23 @@ jobs:
      # that triggered the build.
      HAS_TAILSCALE_SECRET: ${{ secrets.TS_OAUTH_CLIENT_ID }}
    steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        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'
      - name: Tailscale
        if: ${{ env.HAS_TAILSCALE_SECRET }}
-        uses: tailscale/github-action@a392da0a182bba0e9613b6243ebd69529b1878aa # v4.1.0
+        uses: tailscale/github-action@6986d2c82a91fbac2949fe01f5bab95cf21b5102 # v3.2.2
        with:
          oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}
          oauth-secret: ${{ secrets.TS_OAUTH_SECRET }}
@@ -41,106 +52,44 @@ jobs:
      - name: Setup SSH server for Actor
        if: ${{ env.HAS_TAILSCALE_SECRET }}
        uses: alexellis/setup-sshd-actor@master
-      - name: Download headscale image
-        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+      - uses: nixbuild/nix-quick-install-action@889f3180bb5f064ee9e3201428d04ae9e41d54ad # v31
+        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:
-          name: headscale-image
-          path: /tmp/artifacts
-      - name: Download tailscale HEAD image
-        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
-        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:
-          name: hi-binary
-          path: /tmp/artifacts
-      - name: Download Go cache
-        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
-        with:
-          name: go-cache
-          path: /tmp/artifacts
-      - name: Download postgres image
-        if: ${{ inputs.postgres_flag == '--postgres=1' }}
-        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
-        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: Load br_netfilter for in-cluster service routing
-        if: inputs.test == 'TestK8sOperator'
-        # TestK8sOperator runs k3s in a container; without br_netfilter on the
-        # host, bridged pod-to-pod traffic skips kube-proxy's ClusterIP DNAT and
-        # in-cluster DNS (kube-dns) is unreachable. The module cannot be loaded
-        # from inside the unprivileged-module rancher/k3s image, so load it here.
-        run: sudo modprobe br_netfilter
-      - 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
-          chmod +x /tmp/artifacts/hi
-          docker images
-          # Extract Go cache to host directories for bind mounting
-          mkdir -p /tmp/go-cache
-          tar -xzf /tmp/artifacts/go-cache.tar.gz -C /tmp/go-cache
-          ls -la /tmp/go-cache/ /tmp/go-cache/.cache/
+          primary-key:
+            nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix',
+            '**/flake.lock') }}
+          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
      - name: Run Integration Test
-        env:
-          HEADSCALE_INTEGRATION_HEADSCALE_IMAGE: headscale:${{ github.sha }}
-          HEADSCALE_INTEGRATION_TAILSCALE_IMAGE: tailscale-head:${{ github.sha }}
-          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 }}
-      # Sanitize test name for artifact upload (replace invalid characters: " : < > | * ? \ / with -)
-      - name: Sanitize test name for artifacts
-        if: always()
-        id: sanitize
-        run: echo "name=${TEST_NAME//[\":<>|*?\\\/]/-}" >> $GITHUB_OUTPUT
-        env:
-          TEST_NAME: ${{ inputs.test }}
-      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
-        if: always()
+        uses: Wandalen/wretry.action@e68c23e6309f2871ca8ae4763e7629b9c258e1ea # v3.8.0
+        if: steps.changed-files.outputs.files == 'true'
        with:
-          name: ${{ inputs.database_name }}-${{ steps.sanitize.outputs.name }}-logs
+          # Our integration tests are started like a thundering herd, often
+          # hitting limits of the various external repositories we depend on
+          # like docker hub. This will retry jobs every 5 min, 10 times,
+          # hopefully letting us avoid manual intervention and restarting jobs.
+          # One could of course argue that we should invest in trying to avoid
+          # this, but currently it seems like a larger investment to be cleverer
+          # about this.
+          # Some of the jobs might still require manual restart as they are really
+          # slow and this will cause them to eventually be killed by Github actions.
+          attempt_delay: 300000 # 5 min
+          attempt_limit: 2
+          command: |
+            nix develop --command -- hi run "^${{ inputs.test }}$" \
+              --timeout=120m \
+              ${{ inputs.postgres_flag }}
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: always() && steps.changed-files.outputs.files == 'true'
+        with:
+          name: ${{ inputs.database_name }}-${{ inputs.test }}-logs
          path: "control_logs/*/*.log"
-      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
-        if: always()
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: always() && steps.changed-files.outputs.files == 'true'
        with:
-          name: ${{ inputs.database_name }}-${{ steps.sanitize.outputs.name }}-artifacts
-          path: control_logs/
+          name: ${{ inputs.database_name }}-${{ inputs.test }}-archives
+          path: "control_logs/*/*.tar"
      - name: Setup a blocking tmux session
        if: ${{ env.HAS_TAILSCALE_SECRET }}
        uses: alexellis/block-with-tmux-action@master
@@ -0,0 +1,93 @@
+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@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        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@889f3180bb5f064ee9e3201428d04ae9e41d54ad # v31
+        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}}
+          --format=colored-line-number
+
+  prettier-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        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@889f3180bb5f064ee9e3201428d04ae9e41d54ad # v31
+        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@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: nixbuild/nix-quick-install-action@889f3180bb5f064ee9e3201428d04ae9e41d54ad # v31
+      - 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
@@ -1,28 +0,0 @@
-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 }}
@@ -1,99 +0,0 @@
-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
-          }
@@ -1,56 +0,0 @@
-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
@@ -1,51 +0,0 @@
-name: NixOS Module Tests
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
-
-concurrency:
-  group: ${{ github.workflow }}-$${{ github.head_ref || github.run_id }}
-  cancel-in-progress: true
-
-jobs:
-  nix-module-check:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-
-    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: |
-            nix:
-              - 'nix/**'
-              - 'flake.nix'
-              - 'flake.lock'
-            go:
-              - 'go.*'
-              - '**/*.go'
-              - 'cmd/**'
-              - 'hscontrol/**'
-
-      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
-        if: steps.changed-files.outputs.nix == 'true' || steps.changed-files.outputs.go == 'true'
-
-      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
-        if: steps.changed-files.outputs.nix == 'true' || steps.changed-files.outputs.go == 'true'
-
-      - 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 --fallback
@@ -7,37 +7,38 @@ 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'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          fetch-depth: 0

      - name: Login to DockerHub
-        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 # v3.4.0
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Login to GHCR
-        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 # v3.4.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
+      - uses: nixbuild/nix-quick-install-action@889f3180bb5f064ee9e3201428d04ae9e41d54ad # v31
+      - 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: Run goreleaser
-        run: goreleaser release --clean
+        run: nix develop --command -- goreleaser release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -1,36 +0,0 @@
-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/...
@@ -12,16 +12,18 @@ jobs:
      issues: write
      pull-requests: write
    steps:
-      - uses: actions/stale@997185467fa4f803885201cee163a9f38240193d # v10.1.1
+      - uses: actions/stale@5bef64f19d7facfb25b37b414482c7164d639639 # v9.1.0
        with:
          days-before-issue-stale: 90
          days-before-issue-close: 7
          stale-issue-label: "stale"
-          stale-issue-message: "This issue is stale because it has been open for 90 days with no
+          stale-issue-message:
+            "This issue is stale because it has been open for 90 days with no
            activity."
-          close-issue-message: "This issue was closed because it has been inactive for 14 days
+          close-issue-message:
+            "This issue was closed because it has been inactive for 14 days
            since being marked as stale."
          days-before-pr-stale: -1
          days-before-pr-close: -1
-          exempt-issue-labels: "no-stale-bot,needs-more-info"
+          exempt-issue-labels: "no-stale-bot"
          repo-token: ${{ secrets.GITHUB_TOKEN }}
@@ -1,30 +0,0 @@
-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 }}
@@ -6,215 +6,8 @@ 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-24.04-arm
-    outputs:
-      files-changed: ${{ steps.changed-files.outputs.files }}
-    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/**'
-              - 'config-example.yaml'
-              - '.github/workflows/test-integration.yaml'
-              - '.github/workflows/integration-test-template.yml'
-              - 'Dockerfile.*'
-      - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main
-        if: steps.changed-files.outputs.files == 'true'
-      - uses: Mic92/hestia/action@ff07bb902a9968ac0c3d0e51d90a606662a375d8 # main
-        if: steps.changed-files.outputs.files == 'true'
-      - 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
-          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
-        with:
-          name: hi-binary
-          path: hi
-          retention-days: 10
-      - name: Package Go cache
-        if: steps.changed-files.outputs.files == 'true'
-        run: |
-          # Package Go module cache and build cache
-          tar -czf go-cache.tar.gz -C ~ go .cache/go-build
-      - name: Upload Go cache
-        if: steps.changed-files.outputs.files == 'true'
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
-        with:
-          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: |
-          docker build \
-            --file Dockerfile.integration-ci \
-            --tag headscale:${{ github.sha }} \
-            .
-          docker save headscale:${{ github.sha }} | gzip > headscale-image.tar.gz
-      - name: Build tailscale HEAD image
-        if: steps.changed-files.outputs.files == 'true'
-        run: |
-          docker build \
-            --file Dockerfile.tailscale-HEAD \
-            --tag tailscale-head:${{ github.sha }} \
-            .
-          docker save tailscale-head:${{ github.sha }} | gzip > tailscale-head-image.tar.gz
-      - name: Upload headscale image
-        if: steps.changed-files.outputs.files == 'true'
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
-        with:
-          name: headscale-image
-          path: headscale-image.tar.gz
-          retention-days: 10
-      - name: Upload tailscale HEAD image
-        if: steps.changed-files.outputs.files == 'true'
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
-        with:
-          name: tailscale-head-image
-          path: tailscale-head-image.tar.gz
-          retention-days: 10
-  build-postgres:
-    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 }}
-          docker save postgres:${{ github.sha }} | gzip > postgres-image.tar.gz
-      - name: Upload postgres image
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
-        with:
-          name: postgres-image
-          path: postgres-image.tar.gz
-          retention-days: 10
-  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:
@@ -230,66 +23,30 @@ jobs:
          - TestPolicyUpdateWhileRunningWithCLIInDatabase
          - TestACLAutogroupMember
          - TestACLAutogroupTagged
-          - TestACLAutogroupSelf
-          - TestACLPolicyPropagationOverTime
-          - TestACLTagPropagation
-          - TestACLTagPropagationPortSpecific
-          - TestACLGroupWithUnknownUser
-          - TestACLGroupAfterUserDeletion
-          - TestACLGroupDeletionExactReproduction
-          - TestACLDynamicUnknownUserAddition
-          - TestACLDynamicUnknownUserRemoval
-          - TestAPIAuthenticationBypass
-          - TestAPIAuthenticationBypassCurl
-          - TestRemoteCLIAuthenticationBypass
-          - TestCLIWithConfigAuthenticationBypass
          - TestAuthKeyLogoutAndReloginSameUser
          - TestAuthKeyLogoutAndReloginNewUser
          - TestAuthKeyLogoutAndReloginSameUserExpiredKey
-          - TestAuthKeyDeleteKey
-          - TestAuthKeyLogoutAndReloginRoutesPreserved
          - TestOIDCAuthenticationPingAll
          - TestOIDCExpireNodesBasedOnTokenExpiry
          - TestOIDC024UserCreation
          - TestOIDCAuthenticationWithPKCE
          - TestOIDCReloginSameNodeNewUser
-          - TestOIDCFollowUpUrl
-          - TestOIDCMultipleOpenedLoginUrls
-          - TestOIDCReloginSameNodeSameUser
-          - TestOIDCExpiryAfterRestart
-          - TestOIDCACLPolicyOnJoin
-          - TestOIDCReloginSameUserRoutesPreserved
          - TestAuthWebFlowAuthenticationPingAll
-          - TestAuthWebFlowLogoutAndReloginSameUser
-          - TestAuthWebFlowLogoutAndReloginNewUser
-          - TestApiKeyCommand
-          - TestApiKeyCommandValidation
-          - TestAuthCommandValidation
-          - TestNodeCommand
-          - TestNodeExpireCommand
-          - TestNodeRenameCommand
-          - TestPreAuthKeyCorrectUserLoggedInCommand
-          - TestTaggedNodesCLIOutput
-          - TestNodeExpireFlagsCommand
-          - TestNodeCommandValidation
-          - TestNodeTagCommand
-          - TestNodeRouteCommands
-          - TestNodeBackfillIPsCommand
-          - TestOAuthClientCommand
-          - TestOAuthClientCommandValidation
-          - TestPolicyCheckCommand
-          - TestSSHTestsRejectFailingPolicy
-          - TestPolicyCommand
-          - TestPolicyBrokenConfigCommand
+          - TestAuthWebFlowLogoutAndRelogin
+          - TestUserCommand
          - TestPreAuthKeyCommand
          - TestPreAuthKeyCommandWithoutExpiry
          - TestPreAuthKeyCommandReusableEphemeral
-          - TestPreAuthKeyDeleteCommand
-          - TestPreAuthKeyCommandValidation
-          - TestServerInfoCommands
-          - TestUserCommand
-          - TestUserCreateCommand
-          - TestUserCommandValidation
+          - TestPreAuthKeyCorrectUserLoggedInCommand
+          - TestApiKeyCommand
+          - TestNodeTagCommand
+          - TestNodeAdvertiseTagCommand
+          - TestNodeCommand
+          - TestNodeExpireCommand
+          - TestNodeRenameCommand
+          - TestNodeMoveCommand
+          - TestPolicyCommand
+          - TestPolicyBrokenConfigCommand
          - TestDERPVerifyEndpoint
          - TestResolveMagicDNS
          - TestResolveMagicDNSExtraRecordsPath
@@ -304,33 +61,17 @@ jobs:
          - TestTaildrop
          - TestUpdateHostnameFromClient
          - TestExpireNode
-          - TestSetNodeExpiryInFuture
-          - TestDisableNodeExpiry
          - TestNodeOnlineStatus
          - TestPingAllByIPManyUpDown
          - Test2118DeletingOnlineNodePanics
-          - TestGrantCapRelay
-          - TestGrantCapDrive
-          - TestK8sOperator
          - TestEnablingRoutes
          - TestHASubnetRouterFailover
          - TestSubnetRouteACL
          - TestEnablingExitRoutes
-          - TestExitRoutesWithAutogroupInternetACL
          - TestSubnetRouterMultiNetwork
          - TestSubnetRouterMultiNetworkExitNode
-          - TestAutoApproveMultiNetwork/authkey-tag.*
-          - TestAutoApproveMultiNetwork/authkey-user.*
-          - TestAutoApproveMultiNetwork/authkey-group.*
-          - TestAutoApproveMultiNetwork/webauth-tag.*
-          - TestAutoApproveMultiNetwork/webauth-user.*
-          - TestAutoApproveMultiNetwork/webauth-group.*
+          - TestAutoApproveMultiNetwork
          - TestSubnetRouteACLFiltering
-          - TestGrantViaSubnetSteering
-          - TestHASubnetRouterPingFailover
-          - TestHASubnetRouterFailoverBothOffline
-          - TestHASubnetRouterFailoverBothOfflineCablePull
-          - TestHASubnetRouterFailoverDockerDisconnect
          - TestHeadscale
          - TestTailscaleNodesJoiningHeadcale
          - TestSSHOneUserToAll
@@ -338,59 +79,12 @@ jobs:
          - TestSSHNoSSHConfigured
          - TestSSHIsBlockedInACL
          - TestSSHUserOnlyIsolation
-          - TestSSHAutogroupSelf
-          - TestSSHOneUserToOneCheckModeCLI
-          - TestSSHOneUserToOneCheckModeOIDC
-          - TestSSHCheckModeUnapprovedTimeout
-          - TestSSHCheckModeCheckPeriodCLI
-          - TestSSHCheckModeAutoApprove
-          - TestSSHCheckModeSessionLossReDelegates
-          - TestSSHCheckModeNegativeCLI
-          - TestSSHLocalpart
-          - TestTagsAuthKeyWithTagRequestDifferentTag
-          - TestTagsAuthKeyWithTagNoAdvertiseFlag
-          - TestTagsAuthKeyWithTagCannotAddViaCLI
-          - TestTagsAuthKeyWithTagCannotChangeViaCLI
-          - TestTagsAuthKeyWithTagAdminOverrideReauthPreserves
-          - TestTagsAuthKeyWithTagCLICannotModifyAdminTags
-          - TestTagsAuthKeyWithoutTagCannotRequestTags
-          - TestTagsAuthKeyWithoutTagRegisterNoTags
-          - TestTagsAuthKeyWithoutTagCannotAddViaCLI
-          - TestTagsAuthKeyWithoutTagCLINoOpAfterAdminWithReset
-          - TestTagsAuthKeyWithoutTagCLINoOpAfterAdminWithEmptyAdvertise
-          - TestTagsAuthKeyWithoutTagCLICannotReduceAdminMultiTag
-          - TestTagsUserLoginOwnedTagAtRegistration
-          - TestTagsUserLoginNonExistentTagAtRegistration
-          - TestTagsUserLoginUnownedTagAtRegistration
-          - TestTagsUserLoginAddTagViaCLIReauth
-          - TestTagsUserLoginRemoveTagViaCLIReauth
-          - TestTagsUserLoginCLINoOpAfterAdminAssignment
-          - TestTagsUserLoginCLICannotRemoveAdminTags
-          - TestTagsAuthKeyWithTagRequestNonExistentTag
-          - TestTagsAuthKeyWithTagRequestUnownedTag
-          - TestTagsAuthKeyWithoutTagRequestNonExistentTag
-          - TestTagsAuthKeyWithoutTagRequestUnownedTag
-          - TestTagsAdminAPICannotSetNonExistentTag
-          - TestTagsAdminAPICanSetUnownedTag
-          - TestTagsAdminAPICannotRemoveAllTags
-          - TestTagsIssue2978ReproTagReplacement
-          - TestTagsAdminAPICannotSetInvalidFormat
-          - TestTagsUserLoginReauthWithEmptyTagsRemovesAllTags
-          - TestTagsAuthKeyWithoutUserInheritsTags
-          - TestTagsAuthKeyWithoutUserRejectsAdvertisedTags
-          - TestTagsAuthKeyConvertToUserViaCLIRegister
-          - TestTS2021WebSocketGET
-          - TestTS2021WASMClientUnderNode
-          - TestTailscaleRustAxum
    uses: ./.github/workflows/integration-test-template.yml
-    secrets: inherit
    with:
      test: ${{ matrix.test }}
      postgres_flag: "--postgres=0"
      database_name: "sqlite"
  postgres:
-    needs: [build, build-postgres, build-tailscale-released]
-    if: needs.build.outputs.files-changed == 'true'
    strategy:
      fail-fast: false
      matrix:
@@ -401,7 +95,6 @@ jobs:
          - TestPingAllByIPManyUpDown
          - TestSubnetRouterMultiNetwork
    uses: ./.github/workflows/integration-test-template.yml
-    secrets: inherit
    with:
      test: ${{ matrix.test }}
      postgres_flag: "--postgres=1"
@@ -0,0 +1,48 @@
+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@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        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@889f3180bb5f064ee9e3201428d04ae9e41d54ad # v31
+        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
@@ -0,0 +1,19 @@
+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"
@@ -1,10 +1,6 @@
 ignored/
 tailscale/
 .vscode/
-.claude/
-logs/
-
-*.prof

 # Binaries for programs and plugins
 *.exe
@@ -29,7 +25,6 @@ config*.yaml
 !config-example.yaml
 derp.yaml
 *.hujson
-!hscontrol/policy/v2/testdata/*/*.hujson
 *.key
 /db.sqlite
 *.sqlite3
@@ -46,15 +41,14 @@ 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

 __debug_bin

+
 node_modules/
 package-lock.json
 package.json
+
@@ -7,19 +7,16 @@ linters:
    - depguard
    - dupl
    - exhaustruct
-    - funcorder
    - funlen
    - gochecknoglobals
    - gochecknoinits
    - gocognit
    - godox
-    - gomodguard
    - interfacebloat
    - ireturn
    - lll
    - maintidx
    - makezero
-    - mnd
    - musttag
    - nestif
    - nolintlint
@@ -31,43 +28,6 @@ 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
-        - pattern: 'time\.Sleep'
-          msg: >-
-            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:
        - appendAssign
@@ -2,16 +2,12 @@
 version: 2
 before:
  hooks:
-    - go mod tidy -compat=1.26
+    - go mod tidy -compat=1.24
    - go mod vendor

 release:
  prerelease: auto
  draft: true
-  header: |
-    ## Upgrade
-
-    Please follow the steps outlined in the [upgrade guide](https://headscale.net/stable/setup/upgrade/) to update your existing Headscale installation.

 builds:
  - id: headscale
@@ -23,10 +19,20 @@ builds:
      - darwin_amd64
      - darwin_arm64
      - freebsd_amd64
+      - linux_386
      - linux_amd64
      - linux_arm64
+      - linux_arm_5
+      - linux_arm_6
+      - linux_arm_7
    flags:
      - -mod=readonly
+    ldflags:
+      - -s -w
+      - -X github.com/juanfont/headscale/hscontrol/types.Version={{ .Version }}
+      - -X github.com/juanfont/headscale/hscontrol/types.GitCommitHash={{ .Commit }}
+    tags:
+      - ts2019

 archives:
  - id: golang-cross
@@ -42,9 +48,10 @@ source:
    - "vendor/"

 nfpms:
-  # Configure nFPM for .deb releases
+  # Configure nFPM for .deb and .rpm releases
  #
-  # See https://goreleaser.com/customization/package/nfpm/
+  # See https://nfpm.goreleaser.com/configuration/
+  # and https://goreleaser.com/customization/nfpm/
  #
  # Useful tools for debugging .debs:
  # List file contents: dpkg -c dist/headscale...deb
@@ -78,8 +85,6 @@ 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:
@@ -101,14 +106,16 @@ kos:
    # bare tells KO to only use the repository
    # for tagging and naming the container.
    bare: true
-    base_image: gcr.io/distroless/base-debian13
+    base_image: gcr.io/distroless/base-debian12
    build: headscale
    main: ./cmd/headscale
    env:
      - CGO_ENABLED=0
    platforms:
      - linux/amd64
+      - linux/386
      - linux/arm64
+      - linux/arm/v7
    tags:
      - "{{ if not .Prerelease }}latest{{ end }}"
      - "{{ if not .Prerelease }}{{ .Major }}.{{ .Minor }}.{{ .Patch }}{{ end }}"
@@ -121,8 +128,6 @@ kos:
      - "{{ .Tag }}"
      - '{{ trimprefix .Tag "v" }}'
      - "sha-{{ .ShortCommit }}"
-    creation_time: "{{.CommitTimestamp}}"
-    ko_data_creation_time: "{{.CommitTimestamp}}"

  - id: ghcr-debug
    repositories:
@@ -130,14 +135,16 @@ kos:
      - headscale/headscale

    bare: true
-    base_image: gcr.io/distroless/base-debian13:debug
+    base_image: gcr.io/distroless/base-debian12:debug
    build: headscale
    main: ./cmd/headscale
    env:
      - CGO_ENABLED=0
    platforms:
      - linux/amd64
+      - linux/386
      - linux/arm64
+      - linux/arm/v7
    tags:
      - "{{ if not .Prerelease }}latest-debug{{ end }}"
      - "{{ if not .Prerelease }}{{ .Major }}.{{ .Minor }}.{{ .Patch }}-debug{{ end }}"
@@ -1,34 +0,0 @@
-{
-  "mcpServers": {
-    "claude-code-mcp": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@steipete/claude-code-mcp@latest"],
-      "env": {}
-    },
-    "sequential-thinking": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
-      "env": {}
-    },
-    "nixos": {
-      "type": "stdio",
-      "command": "uvx",
-      "args": ["mcp-nixos"],
-      "env": {}
-    },
-    "context7": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp"],
-      "env": {}
-    },
-    "git": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@cyanheads/git-mcp-server"],
-      "env": {}
-    }
-  }
-}
@@ -1,2 +0,0 @@
-[plugin.mkdocs]
-align_semantic_breaks_in_lists = true
@@ -1,72 +0,0 @@
-# prek/pre-commit configuration for headscale
-# See: https://prek.j178.dev/quickstart/
-# See: https://prek.j178.dev/builtin/
-
-# 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
-  # prek will use fast-path optimized versions automatically
-  # See: https://prek.j178.dev/builtin/
-  - repo: https://github.com/pre-commit/pre-commit-hooks
-    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
-      - id: check-merge-conflict
-      - id: check-symlinks
-      - id: check-toml
-      - id: check-xml
-      - id: check-yaml
-      - id: detect-private-key
-      - id: end-of-file-fixer
-      - id: fix-byte-order-marker
-      - id: mixed-line-ending
-      - id: trailing-whitespace
-
-  # Local hooks for project-specific tooling
-  - repo: local
-    hooks:
-      # nixpkgs-fmt for Nix files
-      - id: nixpkgs-fmt
-        name: nixpkgs-fmt
-        entry: nixpkgs-fmt
-        language: system
-        files: \.nix$
-
-      # Prettier for formatting
-      - id: prettier
-        name: prettier
-        entry: prettier --write --list-different
-        language: system
-        exclude: ^docs/
-        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
-        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
@@ -1,2 +1,5 @@
 .github/workflows/test-integration-v2*
-docs/
+docs/about/features.md
+docs/ref/configuration.md
+docs/ref/oidc.md
+docs/ref/remote-cli.md
@@ -1,296 +0,0 @@
-# AGENTS.md
-
-Behavioural guidance for AI agents working in this repository. Reference
-material for complex procedures lives next to the code — integration
-testing is documented in [`cmd/hi/README.md`](cmd/hi/README.md) and
-[`integration/README.md`](integration/README.md). Read those files
-before running tests or writing new ones.
-
-Headscale is an open-source implementation of the Tailscale control server
-written in Go. It manages node registration, IP allocation, policy
-enforcement, and DERP routing for self-hosted tailnets.
-
-## Interaction Rules
-
-These rules govern how you work in this repo. They are listed first
-because they shape every other decision.
-
-### Ask with comprehensive multiple-choice options
-
-When you need to clarify intent, scope, or approach, use the
-`AskUserQuestion` tool (or a numbered list fallback) and present the user
-with a comprehensive set of options. Cover the likely branches explicitly
-and include an "other — please describe" escape.
-
- Bad: _"How should I handle expired nodes?"_
- Good: _"How should expired nodes be handled? (a) Remain visible to peers
-  but marked expired (current behaviour); (b) Hidden from peers entirely;
-  (c) Hidden from peers but visible in admin API; (d) Other."_
-
-This matters more than you think — open-ended questions waste a round
-trip and often produce a misaligned answer.
-
-### Read the documented procedure before running complex commands
-
-Before invoking any `hi` command, integration test, generator, or
-migration tool, read the referenced README in full —
-`cmd/hi/README.md` for running tests, `integration/README.md` for
-writing them. Never guess flags. If the procedure is not documented
-anywhere, ask the user rather than inventing one.
-
-### Map once, then act
-
-Use `Glob` / `Grep` to understand file structure, then execute. Do not
-re-explore the same area to "double-check" once you have a plan. Do not
-re-read files you edited in this session — the harness tracks state for
-you.
-
-### Fail fast, report up
-
-If a command fails twice with the same error, stop and report the exact
-error to the user with context. Do not loop through variants or
-"try one more thing". A repeated failure means your model of the problem
-is wrong.
-
-### Confirm scope for multi-file changes
-
-Before touching more than three files, show the user which files will
-change and why. Use plan mode (`ExitPlanMode`) for non-trivial work.
-
-### Prefer editing existing files
-
-Do not create new files unless strictly necessary. Do not generate helper
-abstractions, wrapper utilities, or "just in case" configuration. Three
-similar lines of code is better than a premature abstraction.
-
-## Quick Start
-
-```bash
-# Enter the nix dev shell (Go 1.26.1, buf, golangci-lint, prek)
-nix develop
-
-# Full development workflow: fmt + lint + test + build
-make dev
-
-# Individual targets
-make build           # build the headscale binary
-make test            # go test ./...
-make fmt             # format Go, docs, proto
-make lint            # lint Go, proto
-make generate        # regenerate protobuf code (after changes to proto/)
-make clean           # remove build artefacts
-
-# Direct go test invocations
-go test ./...
-go test -race ./...
-
-# Integration tests — read cmd/hi/README.md first
-go run ./cmd/hi doctor
-go run ./cmd/hi run "TestName"
-```
-
-Go 1.26.1 minimum (per `go.mod:3`). `nix develop` pins the exact toolchain
-used in CI.
-
-## Pre-Commit with prek
-
-`prek` installs git hooks that run the same checks as CI.
-
-```bash
-nix develop
-prek install            # one-time setup
-prek run                # run hooks on staged files
-prek run --all-files    # run hooks on the full tree
-```
-
-Hooks cover: file hygiene (trailing whitespace, line endings, BOM),
-syntax validation (JSON/YAML/TOML/XML), merge-conflict markers, private
-key detection, nixpkgs-fmt, prettier, and `golangci-lint` via
-`--new-from-rev=HEAD~1` (see `.pre-commit-config.yaml:59`). A manual
-invocation with an `upstream/main` remote is equivalent:
-
-```bash
-golangci-lint run --new-from-rev=upstream/main --timeout=5m --fix
-```
-
-`git commit --no-verify` is acceptable only for WIP commits on feature
-branches — never on `main`.
-
-## Project Layout
-
-```
-headscale/
-├── cmd/
-│   ├── headscale/    # Main headscale server binary
-│   └── hi/           # Integration test runner (see cmd/hi/README.md)
-├── hscontrol/        # Core control plane
-├── integration/      # End-to-end Docker-based tests (see integration/README.md)
-├── proto/            # Protocol buffer definitions
-├── gen/              # Generated code (buf output — do not edit)
-├── docs/             # User and ACL reference documentation
-└── packaging/        # Distribution packaging
-```
-
-### `hscontrol/` packages
-
- `app.go`, `handlers.go`, `grpcv1.go`, `noise.go`, `auth.go`, `oidc.go`,
-  `poll.go`, `metrics.go`, `debug.go`, `tailsql.go`, `platform_config.go`
-  — top-level server files
- `state/` — central coordinator (`state.go`) and the copy-on-write
-  `NodeStore` (`node_store.go`). All cross-subsystem operations go
-  through `State`.
- `db/` — GORM layer, migrations, schema. `node.go`, `users.go`,
-  `api_key.go`, `preauth_keys.go`, `ip.go`, `policy.go`.
- `mapper/` — streaming batcher that distributes MapResponses to
-  clients: `batcher.go`, `node_conn.go`, `builder.go`, `mapper.go`.
-  Performance-critical.
- `policy/` — `policy/v2/` is **the** policy implementation. The
-  top-level `policy.go` is thin wrappers. There is no v1 directory.
- `routes/`, `dns/`, `derp/`, `types/`, `util/`, `templates/`, `capver/`
-  — routing, MagicDNS, relay, core types, helpers, client templates,
-  capability versioning.
- `servertest/` — in-memory test harness for server-level tests that
-  don't need Docker. Prefer this over `integration/` when possible.
- `assets/` — embedded UI assets.
-
-### `cmd/hi/` files
-
-`main.go`, `run.go`, `doctor.go`, `docker.go`, `cleanup.go`, `stats.go`,
-`README.md`. **Read `cmd/hi/README.md` before running any `hi` command.**
-
-## Architecture Essentials
-
- **`hscontrol/state/state.go`** is the central coordinator. Cross-cutting
-  operations (node updates, policy evaluation, IP allocation) go through
-  the `State` type, not directly to the database.
- **`NodeStore`** in `hscontrol/state/node_store.go` is a copy-on-write
-  in-memory cache backed by `atomic.Pointer[Snapshot]`. Every read is a
-  pointer load; writes rebuild a new snapshot and atomically swap. It is
-  the hot path for `MapRequest` processing and peer visibility.
- **The map-request sync point** is
-  `State.UpdateNodeFromMapRequest()` in
-  `hscontrol/state/state.go:2351`. This is where Hostinfo changes,
-  endpoint updates, and route advertisements land in the NodeStore.
- **Mapper subsystem** streams MapResponses via `batcher.go` and
-  `node_conn.go`. Changes here affect all connected clients.
- **Node registration flow**: noise handshake (`noise.go`) → auth
-  (`auth.go`) → state/DB persistence (`state/`, `db/`) → initial map
-  (`mapper/`).
-
-## Database Migration Rules
-
-These rules are load-bearing — violating them corrupts production
-databases. The `migrationsRequiringFKDisabled` map in
-`hscontrol/db/db.go:962` is frozen as of 2025-07-02 (see the comment at
-`db.go:989`). All new migrations must:
-
-1. **Never reorder existing migrations.** Migration order is immutable
-   once committed.
-2. **Only add new migrations to the end** of the migrations array.
-3. **Never disable foreign keys.** No new entries in
-   `migrationsRequiringFKDisabled`.
-4. **Use the migration ID format** `YYYYMMDDHHMM-short-description`
-   (timestamp + descriptive suffix). Example: `202602201200-clear-tagged-node-user-id`.
-5. **Never rename columns** that later migrations reference. Let
-   `AutoMigrate` create a new column if needed.
-
-## Tags-as-Identity
-
-Headscale enforces **tags XOR user ownership**: every node is either
-tagged (owned by tags) or user-owned (owned by a user namespace), never
-both. This is a load-bearing architectural rule.
-
- **Use `node.IsTagged()`** (`hscontrol/types/node.go:221`) to determine
-  ownership, not `node.UserID().Valid()`. A tagged node may still have
-  `UserID` set for "created by" tracking — `IsTagged()` is authoritative.
- `IsUserOwned()` (`node.go:227`) returns `!IsTagged()`.
- Tagged nodes are presented to Tailscale as the special
-  `TaggedDevices` user (`hscontrol/types/users.go`, ID `2147455555`).
- `SetTags` validation is enforced by `validateNodeOwnership()` in
-  `hscontrol/state/tags.go`.
- Examples and edge cases live in `hscontrol/types/node_tags_test.go`
-  and `hscontrol/grpcv1_test.go` (`TestSetTags_*`).
-
-**Don't do this**:
-
-```go
-if node.UserID().Valid() { /* assume user-owned */ }       // WRONG
-if node.UserID().Valid() && !node.IsTagged() { /* ok */ }  // correct
-```
-
-## Policy Engine
-
-`hscontrol/policy/v2/policy.go` is the policy implementation. The
-top-level `hscontrol/policy/policy.go` contains only wrapper functions
-around v2. There is no v1 directory.
-
-Key concepts an agent will encounter:
-
- **Autogroups**: `autogroup:self`, `autogroup:member`, `autogroup:internet`
- **Tag owners**: IP-based authorization for who can claim a tag
- **Route approvals**: auto-approval of subnet routes by policy
- **SSH policies**: SSH access control via grants
- **HuJSON** parsing for policy files
-
-For usage examples, read `hscontrol/policy/v2/policy_test.go`. For ACL
-reference documentation, see `docs/`.
-
-## Integration Testing
-
-**Before running any `hi` command, read `cmd/hi/README.md` in full.**
-Guessing at `hi` flags leads to broken runs and stale containers.
-
-Test-authoring patterns (`EventuallyWithT`, `IntegrationSkip`, helper
-variants, scenario setup) are documented in `integration/README.md`.
-
-Key reminders:
-
- Integration test functions **must** start with `IntegrationSkip(t)`.
- External calls (`client.Status`, `headscale.ListNodes`, etc.) belong
-  inside `EventuallyWithT`; state-mutating commands (`tailscale set`)
-  must not.
- Tests generate ~100 MB of logs per run under `control_logs/{runID}/`.
-  Prune old runs if disk is tight.
- Flakes are almost always code, not infrastructure. Read `hs-*.stderr.log`
-  before blaming Docker.
-
-## Code Conventions
-
- **Commit messages** follow Go-style `package: imperative description`.
-  Recent examples from `git log`:
-  - `db: scope DestroyUser to only delete the target user's pre-auth keys`
-  - `state: fix policy change race in UpdateNodeFromMapRequest`
-  - `integration: fix ACL tests for address-family-specific resolve`
-
-  Not Conventional Commits. No `feat:`/`chore:`/`docs:` prefixes.
-
- **Protobuf regeneration**: changes under `proto/` require
-  `make generate` (which runs `buf generate`) and should land in a
-  **separate commit** from the callers that use the regenerated types.
- **Formatting** is enforced by `golangci-lint` with `golines` (width 88)
-  and `gofumpt`. Run `make fmt` or rely on the pre-commit hook.
- **Logging** uses `zerolog`. Prefer single-line chains
-  (`log.Info().Str(...).Msg(...)`). For 4+ fields or conditional fields,
-  build incrementally and **reassign** the event variable:
-  `e = e.Str("k", v)`. Forgetting to reassign silently drops the field.
- **Tests**: prefer `hscontrol/servertest/` for server-level tests that
-  don't need Docker — faster than full integration tests.
- **View types in read paths**: response serializers must read through
-  `NodeView`/`UserView`/`PreAuthKeyView` accessors. `AsStruct()` clones the
-  whole record on every read — it is only for DB-write/merge clones and mutable
-  working copies, never to build an API response. `grep AsStruct hscontrol/api`
-  must come back empty.
-
-## Gotchas
-
- **Database**: SQLite for local dev, PostgreSQL for integration-heavy
-  tests (`go run ./cmd/hi run "..." --postgres`). Some race conditions
-  only surface on one backend.
- **NodeStore writes** rebuild a full snapshot. Measure before changing
-  hot-path code.
- **`.claude/agents/` is deprecated.** Do not create new agent files
-  there. Put behavioural guidance in this file and procedural guidance
-  in the nearest README.
- **Do not edit `gen/`** — it is regenerated from `proto/` by
-  `make generate`.
- **Proto changes + code changes should be two commits**, not one.
@@ -1 +1,395 @@
-@AGENTS.md
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+Headscale is an open-source implementation of the Tailscale control server written in Go. It provides self-hosted coordination for Tailscale networks (tailnets), managing node registration, IP allocation, policy enforcement, and DERP routing.
+
+## Development Commands
+
+### Quick Setup
+```bash
+# Recommended: Use Nix for dependency management
+nix develop
+
+# Full development workflow
+make dev  # runs fmt + lint + test + build
+```
+
+### Essential Commands
+```bash
+# Build headscale binary
+make build
+
+# Run tests
+make test
+go test ./...                    # All unit tests
+go test -race ./...              # With race detection
+
+# Run specific integration test
+go run ./cmd/hi run "TestName" --postgres
+
+# Code formatting and linting
+make fmt         # Format all code (Go, docs, proto)
+make lint        # Lint all code (Go, proto)
+make fmt-go      # Format Go code only
+make lint-go     # Lint Go code only
+
+# Protocol buffer generation (after modifying proto/)
+make generate
+
+# Clean build artifacts  
+make clean
+```
+
+### Integration Testing
+```bash
+# Use the hi (Headscale Integration) test runner
+go run ./cmd/hi doctor                    # Check system requirements
+go run ./cmd/hi run "TestPattern"         # Run specific test
+go run ./cmd/hi run "TestPattern" --postgres  # With PostgreSQL backend
+
+# Test artifacts are saved to control_logs/ with logs and debug data
+```
+
+## Project Structure & Architecture
+
+### Top-Level Organization
+
+```
+headscale/
+├── cmd/                    # Command-line applications
+│   ├── headscale/         # Main headscale server binary
+│   └── hi/               # Headscale Integration test runner
+├── hscontrol/            # Core control plane logic
+├── integration/          # End-to-end Docker-based tests
+├── proto/               # Protocol buffer definitions
+├── gen/                 # Generated code (protobuf)
+├── docs/                # Documentation
+└── packaging/           # Distribution packaging
+```
+
+### Core Packages (`hscontrol/`)
+
+**Main Server (`hscontrol/`)**
+- `app.go`: Application setup, dependency injection, server lifecycle
+- `handlers.go`: HTTP/gRPC API endpoints for management operations
+- `grpcv1.go`: gRPC service implementation for headscale API
+- `poll.go`: **Critical** - Handles Tailscale MapRequest/MapResponse protocol
+- `noise.go`: Noise protocol implementation for secure client communication
+- `auth.go`: Authentication flows (web, OIDC, command-line)
+- `oidc.go`: OpenID Connect integration for user authentication
+
+**State Management (`hscontrol/state/`)**
+- `state.go`: Central coordinator for all subsystems (database, policy, IP allocation, DERP)
+- `node_store.go`: **Performance-critical** - In-memory cache with copy-on-write semantics
+- Thread-safe operations with deadlock detection
+- Coordinates between database persistence and real-time operations
+
+**Database Layer (`hscontrol/db/`)**
+- `db.go`: Database abstraction, GORM setup, migration management
+- `node.go`: Node lifecycle, registration, expiration, IP assignment
+- `users.go`: User management, namespace isolation
+- `api_key.go`: API authentication tokens
+- `preauth_keys.go`: Pre-authentication keys for automated node registration
+- `ip.go`: IP address allocation and management
+- `policy.go`: Policy storage and retrieval
+- Schema migrations in `schema.sql` with extensive test data coverage
+
+**Policy Engine (`hscontrol/policy/`)**
+- `policy.go`: Core ACL evaluation logic, HuJSON parsing
+- `v2/`: Next-generation policy system with improved filtering
+- `matcher/`: ACL rule matching and evaluation engine
+- Determines peer visibility, route approval, and network access rules
+- Supports both file-based and database-stored policies
+
+**Network Management (`hscontrol/`)**
+- `derp/`: DERP (Designated Encrypted Relay for Packets) server implementation
+  - NAT traversal when direct connections fail
+  - Fallback relay for firewall-restricted environments
+- `mapper/`: Converts internal Headscale state to Tailscale's wire protocol format
+  - `tail.go`: Tailscale-specific data structure generation
+- `routes/`: Subnet route management and primary route selection
+- `dns/`: DNS record management and MagicDNS implementation
+
+**Utilities & Support (`hscontrol/`)**
+- `types/`: Core data structures, configuration, validation
+- `util/`: Helper functions for networking, DNS, key management
+- `templates/`: Client configuration templates (Apple, Windows, etc.)
+- `notifier/`: Event notification system for real-time updates
+- `metrics.go`: Prometheus metrics collection
+- `capver/`: Tailscale capability version management
+
+### Key Subsystem Interactions
+
+**Node Registration Flow**
+1. **Client Connection**: `noise.go` handles secure protocol handshake
+2. **Authentication**: `auth.go` validates credentials (web/OIDC/preauth)
+3. **State Creation**: `state.go` coordinates IP allocation via `db/ip.go`
+4. **Storage**: `db/node.go` persists node, `NodeStore` caches in memory
+5. **Network Setup**: `mapper/` generates initial Tailscale network map
+
+**Ongoing Operations**
+1. **Poll Requests**: `poll.go` receives periodic client updates
+2. **State Updates**: `NodeStore` maintains real-time node information
+3. **Policy Application**: `policy/` evaluates ACL rules for peer relationships
+4. **Map Distribution**: `mapper/` sends network topology to all affected clients
+
+**Route Management**
+1. **Advertisement**: Clients announce routes via `poll.go` Hostinfo updates
+2. **Storage**: `db/` persists routes, `NodeStore` caches for performance
+3. **Approval**: `policy/` auto-approves routes based on ACL rules
+4. **Distribution**: `routes/` selects primary routes, `mapper/` distributes to peers
+
+### Command-Line Tools (`cmd/`)
+
+**Main Server (`cmd/headscale/`)**
+- `headscale.go`: CLI parsing, configuration loading, server startup
+- Supports daemon mode, CLI operations (user/node management), database operations
+
+**Integration Test Runner (`cmd/hi/`)**
+- `main.go`: Test execution framework with Docker orchestration
+- `run.go`: Individual test execution with artifact collection
+- `doctor.go`: System requirements validation
+- `docker.go`: Container lifecycle management
+- Essential for validating changes against real Tailscale clients
+
+### Generated & External Code
+
+**Protocol Buffers (`proto/` → `gen/`)**
+- Defines gRPC API for headscale management operations
+- Client libraries can generate from these definitions
+- Run `make generate` after modifying `.proto` files
+
+**Integration Testing (`integration/`)**
+- `scenario.go`: Docker test environment setup
+- `tailscale.go`: Tailscale client container management
+- Individual test files for specific functionality areas
+- Real end-to-end validation with network isolation
+
+### Critical Performance Paths
+
+**High-Frequency Operations**
+1. **MapRequest Processing** (`poll.go`): Every 15-60 seconds per client
+2. **NodeStore Reads** (`node_store.go`): Every operation requiring node data
+3. **Policy Evaluation** (`policy/`): On every peer relationship calculation
+4. **Route Lookups** (`routes/`): During network map generation
+
+**Database Write Patterns**
+- **Frequent**: Node heartbeats, endpoint updates, route changes
+- **Moderate**: User operations, policy updates, API key management
+- **Rare**: Schema migrations, bulk operations
+
+### Configuration & Deployment
+
+**Configuration** (`hscontrol/types/config.go`)**
+- Database connection settings (SQLite/PostgreSQL)
+- Network configuration (IP ranges, DNS settings)
+- Policy mode (file vs database)
+- DERP relay configuration
+- OIDC provider settings
+
+**Key Dependencies**
+- **GORM**: Database ORM with migration support
+- **Tailscale Libraries**: Core networking and protocol code
+- **Zerolog**: Structured logging throughout the application
+- **Buf**: Protocol buffer toolchain for code generation
+
+### Development Workflow Integration
+
+The architecture supports incremental development:
+- **Unit Tests**: Focus on individual packages (`*_test.go` files)
+- **Integration Tests**: Validate cross-component interactions
+- **Database Tests**: Extensive migration and data integrity validation
+- **Policy Tests**: ACL rule evaluation and edge cases
+- **Performance Tests**: NodeStore and high-frequency operation validation
+
+## Integration Test System
+
+### Overview
+Integration tests use Docker containers running real Tailscale clients against a Headscale server. Tests validate end-to-end functionality including routing, ACLs, node lifecycle, and network coordination.
+
+### Running Integration Tests
+
+**System Requirements**
+```bash
+# Check if your system is ready
+go run ./cmd/hi doctor
+```
+This verifies Docker, Go, required images, and disk space.
+
+**Test Execution Patterns**
+```bash
+# Run a single test (recommended for development)
+go run ./cmd/hi run "TestSubnetRouterMultiNetwork"
+
+# Run with PostgreSQL backend (for database-heavy tests)
+go run ./cmd/hi run "TestExpireNode" --postgres
+
+# Run multiple tests with pattern matching
+go run ./cmd/hi run "TestSubnet*"
+
+# Run all integration tests (CI/full validation)
+go test ./integration -timeout 30m
+```
+
+**Test Categories & Timing**
+- **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` (12 min duration)
+
+### Test Infrastructure
+
+**Docker Setup**
+- Headscale server container with configurable database backend
+- Multiple Tailscale client containers with different versions
+- Isolated networks per test scenario
+- Automatic cleanup after test completion
+
+**Test Artifacts**
+All test runs save artifacts to `control_logs/TIMESTAMP-ID/`:
+```
+control_logs/20250713-213106-iajsux/
+├── hs-testname-abc123.stderr.log     # Headscale server logs
+├── hs-testname-abc123.stdout.log
+├── hs-testname-abc123.db             # Database snapshot
+├── hs-testname-abc123_metrics.txt    # Prometheus metrics
+├── hs-testname-abc123-mapresponses/  # Protocol debug data
+├── ts-client-xyz789.stderr.log       # Tailscale client logs
+├── ts-client-xyz789.stdout.log
+└── ts-client-xyz789_status.json      # Client status dump
+```
+
+### Test Development Guidelines
+
+**Timing Considerations**
+Integration tests involve real network operations and Docker container lifecycle:
+
+```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) // May fail due to timing
+
+// ✅ Correct: Wait for async operations to complete
+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")
+```
+
+**Common Test Patterns**
+- **Route Advertisement**: Use `EventuallyWithT` for route propagation
+- **Node State Changes**: Wait for NodeStore synchronization  
+- **ACL Policy Changes**: Allow time for policy recalculation
+- **Network Connectivity**: Use ping tests with retries
+
+**Test Data Management**
+```go
+// Node identification: Don't assume array ordering
+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 node that should have the route
+    }
+}
+```
+
+### Troubleshooting Integration Tests
+
+**Common Failure Patterns**
+1. **Timing Issues**: Test assertions run before async operations complete
+   - **Solution**: Use `EventuallyWithT` with appropriate timeouts
+   - **Timeout Guidelines**: 3-5s for route operations, 10s for complex scenarios
+
+2. **Infrastructure Problems**: Disk space, Docker issues, network conflicts
+   - **Check**: `go run ./cmd/hi doctor` for system health
+   - **Clean**: Remove old test containers and networks
+
+3. **NodeStore Synchronization**: Tests expecting immediate data availability
+   - **Key Points**: Route advertisements must propagate through poll requests
+   - **Fix**: Wait for NodeStore updates after Hostinfo changes
+
+4. **Database Backend Differences**: SQLite vs PostgreSQL behavior differences
+   - **Use**: `--postgres` flag for database-intensive tests
+   - **Note**: Some timing characteristics differ between backends
+
+**Debugging Failed Tests**
+1. **Check test artifacts** in `control_logs/` for detailed logs
+2. **Examine MapResponse JSON** files for protocol-level debugging
+3. **Review Headscale stderr logs** for server-side error messages
+4. **Check Tailscale client status** for network-level issues
+
+**Resource Management**
+- Tests require significant disk space (each run ~100MB of logs)
+- Docker containers are cleaned up automatically on success
+- Failed tests may leave containers running - clean manually if needed
+- Use `docker system prune` periodically to reclaim space
+
+### Best Practices for Test Modifications
+
+1. **Always test locally** before committing integration test changes
+2. **Use appropriate timeouts** - too short causes flaky tests, too long slows CI
+3. **Clean up properly** - ensure tests don't leave persistent state
+4. **Handle both success and failure paths** in test scenarios
+5. **Document timing requirements** for complex test scenarios
+
+## NodeStore Implementation Details
+
+**Key Insight from Recent Work**: The NodeStore is a critical performance optimization that caches node data in memory while ensuring consistency with the database. When working with route advertisements or node state changes:
+
+1. **Timing Considerations**: Route advertisements need time to propagate from clients to server. Use `require.EventuallyWithT()` patterns in tests instead of immediate assertions.
+
+2. **Synchronization Points**: NodeStore updates happen at specific points like `poll.go:420` after Hostinfo changes. Ensure these are maintained when modifying the polling logic.
+
+3. **Peer Visibility**: The NodeStore's `peersFunc` determines which nodes are visible to each other. Policy-based filtering is separate from monitoring visibility - expired nodes should remain visible for debugging but marked as expired.
+
+## Testing Guidelines
+
+### Integration Test Patterns
+```go
+// Use EventuallyWithT for async operations
+require.EventuallyWithT(t, func(c *assert.CollectT) {
+    nodes, err := headscale.ListNodes()
+    assert.NoError(c, err)
+    // Check expected state
+}, 10*time.Second, 100*time.Millisecond, "description")
+
+// Node route checking by actual node properties, not array position
+var routeNode *v1.Node
+for _, node := range nodes {
+    if nodeIDStr := fmt.Sprintf("%d", node.GetId()); expectedRoutes[nodeIDStr] != "" {
+        routeNode = node
+        break
+    }
+}
+```
+
+### Running Problematic Tests
+- Some tests require significant time (e.g., `TestNodeOnlineStatus` runs for 12 minutes)
+- Infrastructure issues like disk space can cause test failures unrelated to code changes  
+- Use `--postgres` flag when testing database-heavy scenarios
+
+## Important Notes
+
+- **Dependencies**: Use `nix develop` for consistent toolchain (Go, buf, protobuf tools, linting)
+- **Protocol Buffers**: Changes to `proto/` require `make generate` and should be committed separately
+- **Code Style**: Enforced via golangci-lint with golines (width 88) and gofumpt formatting
+- **Database**: Supports both SQLite (development) and PostgreSQL (production/testing)
+- **Integration Tests**: Require Docker and can consume significant disk space
+- **Performance**: NodeStore optimizations are critical for scale - be careful with changes to state management
+
+## Debugging Integration Tests
+
+Test artifacts are preserved in `control_logs/TIMESTAMP-ID/` including:
+- Headscale server logs (stderr/stdout)
+- Tailscale client logs and status
+- Database dumps and network captures
+- MapResponse JSON files for protocol debugging
+
+When tests fail, check these artifacts first before assuming code issues.
@@ -0,0 +1,201 @@
+# CLI Standardization Summary
+
+## Changes Made
+
+### 1. Command Naming Standardization
+- **Fixed**: `backfillips` → `backfill-ips` (with backward compat alias)
+- **Fixed**: `dumpConfig` → `dump-config` (with backward compat alias) 
+- **Result**: All commands now use kebab-case consistently
+
+### 2. Flag Standardization
+
+#### Node Commands
+- **Added**: `--node` flag as primary way to specify nodes
+- **Deprecated**: `--identifier` flag (hidden, marked deprecated)
+- **Backward Compatible**: Both flags work, `--identifier` shows deprecation warning
+- **Smart Lookup Ready**: `--node` accepts strings for future name/hostname/IP lookup
+
+#### User Commands  
+- **Updated**: User identification flow prepared for `--user` flag
+- **Maintained**: Existing `--name` and `--identifier` flags for backward compatibility
+
+### 3. Description Consistency
+- **Fixed**: "Api" → "API" throughout
+- **Fixed**: Capitalization consistency in short descriptions
+- **Fixed**: Removed unnecessary periods from short descriptions
+- **Standardized**: "Handle/Manage the X of Headscale" pattern
+
+### 4. Type Consistency
+- **Standardized**: Node IDs use `uint64` consistently
+- **Maintained**: Backward compatibility with existing flag types
+
+## Current Status
+
+### ✅ Completed
+- Command naming (kebab-case)
+- Flag deprecation and aliasing
+- Description standardization  
+- Backward compatibility preservation
+- Helper functions for flag processing
+- **SMART LOOKUP IMPLEMENTATION**:
+  - Enhanced `ListNodesRequest` proto with ID, name, hostname, IP filters
+  - Implemented smart filtering in `ListNodes` gRPC method
+  - Added CLI smart lookup functions for nodes and users
+  - Single match validation with helpful error messages
+  - Automatic detection: ID (numeric) vs IP vs name/hostname/email
+
+### ✅ Smart Lookup Features
+- **Node Lookup**: By ID, hostname, or IP address
+- **User Lookup**: By ID, username, or email address  
+- **Single Match Enforcement**: Errors if 0 or >1 matches found
+- **Helpful Error Messages**: Shows all matches when ambiguous
+- **Full Backward Compatibility**: All existing flags still work
+- **Enhanced List Commands**: Both `nodes list` and `users list` support all filter types
+
+## Breaking Changes
+
+**None.** All changes maintain full backward compatibility through flag aliases and deprecation warnings.
+
+## Implementation Details
+
+### Smart Lookup Algorithm
+
+1. **Input Detection**:
+   ```go
+   if numeric && > 0 -> treat as ID
+   else if contains "@" -> treat as email (users only)  
+   else if valid IP address -> treat as IP (nodes only)
+   else -> treat as name/hostname
+   ```
+
+2. **gRPC Filtering**:
+   - Uses enhanced `ListNodes`/`ListUsers` with specific filters
+   - Server-side filtering for optimal performance
+   - Single transaction per lookup
+
+3. **Match Validation**:
+   - Exactly 1 match: Return ID
+   - 0 matches: Error with "not found" message
+   - >1 matches: Error listing all matches for disambiguation
+
+### Enhanced Proto Definitions
+
+```protobuf
+message ListNodesRequest { 
+  string user = 1;           // existing
+  uint64 id = 2;            // new: filter by ID
+  string name = 3;          // new: filter by hostname  
+  string hostname = 4;      // new: alias for name
+  repeated string ip_addresses = 5; // new: filter by IPs
+}
+```
+
+### Future Enhancements
+
+- **Fuzzy Matching**: Partial name matching with confirmation
+- **Recently Used**: Cache recently accessed nodes/users
+- **Tab Completion**: Shell completion for names/hostnames
+- **Bulk Operations**: Multi-select with pattern matching
+
+## Migration Path for Users
+
+### Now Available (Current Release)
+```bash
+# Old way (still works, shows deprecation warning)
+headscale nodes expire --identifier 123
+
+# New way with smart lookup:
+headscale nodes expire --node 123                    # by ID
+headscale nodes expire --node "my-laptop"           # by hostname  
+headscale nodes expire --node "100.64.0.1"          # by Tailscale IP
+headscale nodes expire --node "192.168.1.100"       # by real IP
+
+# User operations:
+headscale users destroy --user 123                   # by ID
+headscale users destroy --user "alice"               # by username
+headscale users destroy --user "alice@company.com"   # by email
+
+# Enhanced list commands with filtering:
+headscale nodes list --node "laptop"                 # filter nodes by name
+headscale nodes list --ip "100.64.0.1"              # filter nodes by IP
+headscale nodes list --user "alice"                  # filter nodes by user
+headscale users list --user "alice"                  # smart lookup user
+headscale users list --email "@company.com"          # filter by email domain
+headscale users list --name "alice"                  # filter by exact name
+
+# Error handling examples:
+headscale nodes expire --node "laptop"
+# Error: multiple nodes found matching 'laptop': ID=1 name=laptop-alice, ID=2 name=laptop-bob
+
+headscale nodes expire --node "nonexistent" 
+# Error: no node found matching 'nonexistent'
+```
+
+## Command Structure Overview
+
+```
+headscale [global-flags] <command> [command-flags] <subcommand> [subcommand-flags] [args]
+
+Global Flags:
+  --config, -c     config file path
+  --output, -o     output format (json, yaml, json-line)  
+  --force          disable prompts
+
+Commands:
+├── serve
+├── version  
+├── config-test
+├── dump-config (alias: dumpConfig)
+├── mockoidc
+├── generate/
+│   └── private-key
+├── nodes/
+│   ├── list (--user, --tags, --columns)
+│   ├── register (--user, --key) 
+│   ├── list-routes (--node)
+│   ├── expire (--node)
+│   ├── rename (--node) <new-name>
+│   ├── delete (--node)
+│   ├── move (--node, --user)
+│   ├── tag (--node, --tags)
+│   ├── approve-routes (--node, --routes)
+│   └── backfill-ips (alias: backfillips)
+├── users/
+│   ├── create <name> (--display-name, --email, --picture-url)
+│   ├── list (--user, --name, --email, --columns)
+│   ├── destroy (--user|--name|--identifier)
+│   └── rename (--user|--name|--identifier, --new-name)
+├── apikeys/
+│   ├── list
+│   ├── create (--expiration)
+│   ├── expire (--prefix)
+│   └── delete (--prefix)
+├── preauthkeys/
+│   ├── list (--user)
+│   ├── create (--user, --reusable, --ephemeral, --expiration, --tags)
+│   └── expire (--user) <key>
+├── policy/
+│   ├── get
+│   ├── set (--file)
+│   └── check (--file)
+└── debug/
+    └── create-node (--name, --user, --key, --route)
+```
+
+## Deprecated Flags
+
+All deprecated flags continue to work but show warnings:
+
+- `--identifier` → use `--node` (for node commands) or `--user` (for user commands)
+- `--namespace` → use `--user` (already implemented)
+- `dumpConfig` → use `dump-config`
+- `backfillips` → use `backfill-ips`
+
+## Error Handling
+
+Improved error messages provide clear guidance:
+```
+Error: node specifier must be a numeric ID (smart lookup by name/hostname/IP not yet implemented)
+Error: --node flag is required  
+Error: --user flag is required
+```
@@ -1,6 +1,6 @@
 # For testing purposes only

-FROM golang:1.26.5-alpine AS build-env
+FROM golang: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.23
+FROM alpine:3.18
 RUN apk add --no-cache ca-certificates iptables iproute2 ip6tables curl

 COPY --from=build-env /go/bin/* /usr/local/bin/
@@ -2,43 +2,25 @@
 # and are in no way endorsed by Headscale's maintainers as an
 # official nor supported release or distribution.

-FROM docker.io/golang:1.26.5-trixie AS builder
+FROM docker.io/golang:1.24-bookworm
 ARG VERSION=dev
 ENV GOPATH /go
 WORKDIR /go/src/headscale

-# Install delve debugger first - rarely changes, good cache candidate
-RUN go install github.com/go-delve/delve/cmd/dlv@latest
+RUN apt-get update \
+  && apt-get install --no-install-recommends --yes less jq sqlite3 dnsutils \
+  && rm -rf /var/lib/apt/lists/* \
+  && apt-get clean
+RUN mkdir -p /var/run/headscale

-# Download dependencies - only invalidated when go.mod/go.sum change
 COPY go.mod go.sum /go/src/headscale/
 RUN go mod download

-# Copy source and build - invalidated on any source change
 COPY . .

-# Build debug binary with debug symbols for delve
-RUN CGO_ENABLED=0 GOOS=linux go build -gcflags="all=-N -l" -o /go/bin/headscale ./cmd/headscale
-
-# Runtime stage
-FROM debian:trixie-slim
-
-RUN apt-get --update install --no-install-recommends --yes \
-    bash ca-certificates curl dnsutils findutils iproute2 jq less procps python3 sqlite3 \
-  && apt-get dist-clean
-
-RUN mkdir -p /var/run/headscale
-
-# Copy binaries from builder
-COPY --from=builder /go/bin/headscale /usr/local/bin/headscale
-COPY --from=builder /go/bin/dlv /usr/local/bin/dlv
-
-# Copy source code for delve source-level debugging
-COPY --from=builder /go/src/headscale /go/src/headscale
-
-WORKDIR /go/src/headscale
+RUN CGO_ENABLED=0 GOOS=linux go install -a ./cmd/headscale && test -e /go/bin/headscale

 # Need to reset the entrypoint or everything will run as a busybox script
 ENTRYPOINT []
-EXPOSE 8080/tcp 40000/tcp
-CMD ["dlv", "--listen=0.0.0.0:40000", "--headless=true", "--api-version=2", "--accept-multiclient", "exec", "/usr/local/bin/headscale", "--"]
+EXPOSE 8080/tcp
+CMD ["headscale"]
@@ -1,17 +0,0 @@
-# Minimal CI image - expects pre-built headscale binary in build context
-# For local development with delve debugging, use Dockerfile.integration instead
-
-FROM debian:trixie-slim
-
-RUN apt-get --update install --no-install-recommends --yes \
-    bash ca-certificates curl dnsutils findutils iproute2 jq less procps python3 sqlite3 \
-  && apt-get dist-clean
-
-RUN mkdir -p /var/run/headscale
-
-# Copy pre-built headscale binary from build context
-COPY headscale /usr/local/bin/headscale
-
-ENTRYPOINT []
-EXPOSE 8080/tcp
-CMD ["/usr/local/bin/headscale"]
@@ -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.26.5-alpine AS build-env
+FROM golang:1.24-alpine AS build-env

 WORKDIR /go/src

@@ -36,10 +36,8 @@ 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.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
+FROM alpine:3.18
+RUN apk add --no-cache ca-certificates iptables iproute2 ip6tables curl

 COPY --from=build-env /go/bin/* /usr/local/bin/
 # For compat with the previous run.sh, although ideally you should be
@@ -1,26 +0,0 @@
-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
@@ -1,30 +0,0 @@
-# For integration testing only.
-#
-# Builds the Tailscale control client (integration/wasmic/wasmclient) for
-# GOOS=js/GOARCH=wasm and packages it with Go's wasm_exec Node runner. The
-# container idles; the integration test execs
-#   node /app/wasm_exec_node.js /app/client.wasm <control-url>
-# to drive a real browser-style WebSocket GET against headscale's /ts2021,
-# guarding the regression in issue #3357.
-
-FROM golang:1.26.5-alpine AS build
-
-WORKDIR /src
-
-# Only the module metadata and the wasm client package are needed to build the
-# js/wasm binary; its imports (tailscale.com/control/controlhttp, ...) resolve
-# from the module proxy.
-COPY go.mod go.sum ./
-COPY integration/wasmic/wasmclient ./integration/wasmic/wasmclient
-
-RUN GOOS=js GOARCH=wasm go build -o /out/client.wasm ./integration/wasmic/wasmclient \
-    && cp "$(go env GOROOT)/lib/wasm/wasm_exec.js" /out/wasm_exec.js \
-    && cp "$(go env GOROOT)/lib/wasm/wasm_exec_node.js" /out/wasm_exec_node.js
-
-FROM node:24-alpine
-
-WORKDIR /app
-COPY --from=build /out/ /app/
-
-# Idle; the test execs the client on demand with the headscale control URL.
-ENTRYPOINT ["tail", "-f", "/dev/null"]
@@ -20,7 +20,8 @@ endef

 # Source file collections using shell find for better performance
 GO_SOURCES := $(shell find . -name '*.go' -not -path './gen/*' -not -path './vendor/*')
-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/*')
+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/*')

 # Default target
 .PHONY: all
@@ -32,8 +33,9 @@ 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
@@ -50,7 +52,7 @@ test: check-deps $(GO_SOURCES) go.mod go.sum

 # Formatting targets
 .PHONY: fmt
-fmt: fmt-go fmt-mdformat fmt-prettier
+fmt: fmt-go fmt-prettier fmt-proto

 .PHONY: fmt-go
 fmt-go: check-deps $(GO_SOURCES)
@@ -58,69 +60,47 @@ fmt-go: check-deps $(GO_SOURCES)
 	gofumpt -l -w .
 	golangci-lint run --fix

-.PHONY: fmt-mdformat
-fmt-mdformat: check-deps
-	@echo "Formatting documentation..."
-	mdformat docs/
-
 .PHONY: fmt-prettier
-fmt-prettier: check-deps $(PRETTIER_SOURCES)
-	@echo "Formatting markup and config files..."
+fmt-prettier: check-deps $(DOC_SOURCES)
+	@echo "Formatting documentation and config files..."
 	prettier --write '**/*.{ts,js,md,yaml,yml,sass,css,scss,html}'
+	prettier --write --print-width 80 --prose-wrap always CHANGELOG.md
+
+.PHONY: fmt-proto
+fmt-proto: check-deps $(PROTO_SOURCES)
+	@echo "Formatting Protocol Buffer files..."
+	clang-format -i $(PROTO_SOURCES)

 # Linting targets
 .PHONY: lint
-lint: lint-go
+lint: lint-go lint-proto

 .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
+generate: check-deps $(PROTO_SOURCES)
+	@echo "Generating code from Protocol Buffers..."
+	rm -rf gen
+	buf generate proto

 # Clean targets
 .PHONY: clean
 clean:
-	rm -rf headscale gen/client
+	rm -rf headscale gen

 # 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:
@@ -130,20 +110,21 @@ 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, markup)"
-	@echo "  lint         - Lint all code (Go)"
-	@echo "  generate     - Generate code (go generate + client)"
+	@echo "  fmt          - Format all code (Go, docs, proto)"
+	@echo "  lint         - Lint all code (Go, proto)"
+	@echo "  generate     - Generate code from Protocol Buffers"
 	@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-mdformat - Format documentation only"
-	@echo "  fmt-prettier - Format markup and config files only"
+	@echo "  fmt-prettier - Format documentation only" 
+	@echo "  fmt-proto    - Format Protocol Buffer 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"
 	@echo ""
 	@echo "Note: If not running in a nix shell, ensure dependencies are available:"
-	@echo "  nix develop"
+	@echo "  nix develop"
@@ -1,4 +1,4 @@
-![headscale logo](./docs/assets/logo/headscale3_header_stacked_left.png)
+![headscale logo](./docs/logo/headscale3_header_stacked_left.png)

 ![ci](https://github.com/juanfont/headscale/actions/workflows/test.yml/badge.svg)

@@ -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/docs/concepts/tailnet) is
-private network which Tailscale assigns to a user in terms of private users or an
+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
 organisation.

 ## Design goal
@@ -63,18 +63,8 @@ and container to run Headscale.**

 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

@@ -113,8 +103,6 @@ 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.
@@ -159,7 +147,6 @@ make build
 We recommend using Nix for dependency management to ensure you have all required tools. If you prefer to manage dependencies yourself, you can use Make directly:

 **With Nix (recommended):**
-
 ```shell
 nix develop
 make test
@@ -167,7 +154,6 @@ make build
 ```

 **With your own dependencies:**
-
 ```shell
 make test
 make build
@@ -0,0 +1,21 @@
+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
@@ -1,95 +0,0 @@
-# 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>
-```
@@ -1,312 +0,0 @@
-// 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
-}
@@ -1,75 +0,0 @@
-// 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)
-}
@@ -3,17 +3,16 @@ package cli
 import (
 	"context"
 	"fmt"
-	"net/http"
 	"strconv"
+	"time"

-	clientv1 "github.com/juanfont/headscale/gen/client/v1"
+	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
 	"github.com/juanfont/headscale/hscontrol/util"
+	"github.com/prometheus/common/model"
+	"github.com/pterm/pterm"
+	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
-)
-
-const (
-	// DefaultAPIKeyExpiry is 90 days.
-	DefaultAPIKeyExpiry = "90d"
+	"google.golang.org/protobuf/types/known/timestamppb"
 )

 func init() {
@@ -26,198 +25,201 @@ func init() {
 	apiKeysCmd.AddCommand(createAPIKeyCmd)

 	expireAPIKeyCmd.Flags().StringP("prefix", "p", "", "ApiKey prefix")
-	expireAPIKeyCmd.Flags().Uint64P("id", "i", 0, "ApiKey ID")
+	if err := expireAPIKeyCmd.MarkFlagRequired("prefix"); err != nil {
+		log.Fatal().Err(err).Msg("")
+	}
 	apiKeysCmd.AddCommand(expireAPIKeyCmd)

 	deleteAPIKeyCmd.Flags().StringP("prefix", "p", "", "ApiKey prefix")
-	deleteAPIKeyCmd.Flags().Uint64P("id", "i", 0, "ApiKey ID")
+	if err := deleteAPIKeyCmd.MarkFlagRequired("prefix"); err != nil {
+		log.Fatal().Err(err).Msg("")
+	}
 	apiKeysCmd.AddCommand(deleteAPIKeyCmd)
 }

 var apiKeysCmd = &cobra.Command{
 	Use:     "apikeys",
-	Short:   "Handle the Api keys in Headscale",
+	Short:   "Handle the API keys in Headscale",
 	Aliases: []string{"apikey", "api"},
 }

 var listAPIKeys = &cobra.Command{
-	Use:     cmdList,
-	Short:   "List the Api keys for headscale",
-	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 {
-			return fmt.Errorf("listing api keys: %w", err)
-		}
+	Use:     "list",
+	Short:   "List the API keys for Headscale",
+	Aliases: []string{"ls", "show"},
+	Run: func(cmd *cobra.Command, args []string) {
+		output := GetOutputFlag(cmd)

-		if resp.StatusCode() != http.StatusOK {
-			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
-		}
+		err := WithClient(func(ctx context.Context, client v1.HeadscaleServiceClient) error {
+			request := &v1.ListApiKeysRequest{}

-		apiKeys := resp.JSON200.ApiKeys
-
-		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,
-				})
+			response, err := client.ListApiKeys(ctx, request)
+			if err != nil {
+				ErrorOutput(
+					err,
+					fmt.Sprintf("Error getting the list of keys: %s", err),
+					output,
+				)
+				return err
 			}

-			return renderTable([]string{"ID", "Prefix", colExpiration, colCreated}, rows)
+			if output != "" {
+				SuccessOutput(response.GetApiKeys(), "", output)
+				return nil
+			}
+
+			tableData := pterm.TableData{
+				{"ID", "Prefix", "Expiration", "Created"},
+			}
+			for _, key := range response.GetApiKeys() {
+				expiration := "-"
+
+				if key.GetExpiration() != nil {
+					expiration = ColourTime(key.GetExpiration().AsTime())
+				}
+
+				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 err
+			}
+			return nil
 		})
-	}),
+		if err != nil {
+			return
+		}
+	},
 }

 var createAPIKeyCmd = &cobra.Command{
 	Use:   "create",
-	Short: "Creates a new Api key",
+	Short: "Create a new API key",
 	Long: `
 Creates a new Api key, the Api key is only visible on creation
 and cannot be retrieved again.
-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 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 := GetOutputFlag(cmd)
+
+		request := &v1.CreateApiKeyRequest{}
+
+		durationStr, _ := cmd.Flags().GetString("expiration")
+
+		duration, err := model.ParseDuration(durationStr)
 		if err != nil {
-			return err
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Could not parse duration: %s\n", err),
+				output,
+			)
+			return
 		}

-		resp, err := client.CreateApiKeyWithResponse(ctx, clientv1.CreateApiKeyJSONRequestBody{
-			Expiration: &expiryTime,
+		expiration := time.Now().UTC().Add(time.Duration(duration))
+
+		request.Expiration = timestamppb.New(expiration)
+
+		err = WithClient(func(ctx context.Context, client v1.HeadscaleServiceClient) error {
+			response, err := client.CreateApiKey(ctx, request)
+			if err != nil {
+				ErrorOutput(
+					err,
+					fmt.Sprintf("Cannot create Api Key: %s\n", err),
+					output,
+				)
+				return err
+			}
+
+			SuccessOutput(response.GetApiKey(), response.GetApiKey(), output)
+			return nil
 		})
 		if err != nil {
-			return fmt.Errorf("creating api key: %w", err)
+			return
 		}
-
-		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:     cmdExpire,
-	Short:   "Expire an ApiKey",
-	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)
+	Use:     "expire",
+	Short:   "Expire an API key",
+	Aliases: []string{"revoke", "exp", "e"},
+	Run: func(cmd *cobra.Command, args []string) {
+		output := GetOutputFlag(cmd)
+		prefix, err := cmd.Flags().GetString("prefix")
 		if err != nil {
-			return err
+			ErrorOutput(err, fmt.Sprintf("Error getting prefix from CLI flag: %s", err), output)
+			return
 		}

-		body := clientv1.ExpireApiKeyJSONRequestBody{}
+		err = WithClient(func(ctx context.Context, client v1.HeadscaleServiceClient) error {
+			request := &v1.ExpireApiKeyRequest{
+				Prefix: prefix,
+			}

-		if id != 0 {
-			idStr := strconv.FormatUint(id, util.Base10)
-			body.Id = &idStr
-		}
+			response, err := client.ExpireApiKey(ctx, request)
+			if err != nil {
+				ErrorOutput(
+					err,
+					fmt.Sprintf("Cannot expire Api Key: %s\n", err),
+					output,
+				)
+				return err
+			}

-		if prefix != "" {
-			body.Prefix = &prefix
-		}
-
-		resp, err := client.ExpireApiKeyWithResponse(ctx, body)
+			SuccessOutput(response, "Key expired", output)
+			return nil
+		})
 		if err != nil {
-			return fmt.Errorf("expiring api key: %w", err)
+			return
 		}
-
-		if resp.StatusCode() != http.StatusOK {
-			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
-		}
-
-		return printOutput(cmd, resp.JSON200, "Key expired")
-	}),
+	},
 }

 var deleteAPIKeyCmd = &cobra.Command{
-	Use:     cmdDelete,
-	Short:   "Delete an ApiKey",
-	Aliases: []string{"remove", aliasDel},
-	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
-		id, prefix, err := apiKeyIDOrPrefix(cmd)
+	Use:     "delete",
+	Short:   "Delete an API key",
+	Aliases: []string{"remove", "del"},
+	Run: func(cmd *cobra.Command, args []string) {
+		output := GetOutputFlag(cmd)
+		prefix, err := cmd.Flags().GetString("prefix")
 		if err != nil {
-			return err
+			ErrorOutput(err, fmt.Sprintf("Error getting prefix from CLI flag: %s", err), output)
+			return
 		}

-		// 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)
+		err = WithClient(func(ctx context.Context, client v1.HeadscaleServiceClient) error {
+			request := &v1.DeleteApiKeyRequest{
+				Prefix: prefix,
+			}
+
+			response, err := client.DeleteApiKey(ctx, request)
 			if err != nil {
+				ErrorOutput(
+					err,
+					fmt.Sprintf("Cannot delete Api Key: %s\n", err),
+					output,
+				)
 				return err
 			}
-		}

-		resp, err := client.DeleteApiKeyWithResponse(ctx, prefix, &clientv1.DeleteApiKeyParams{})
+			SuccessOutput(response, "Key deleted", output)
+			return nil
+		})
 		if err != nil {
-			return fmt.Errorf("deleting api key: %w", err)
+			return
 		}
-
-		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)
+	},
 }
@@ -1,99 +0,0 @@
-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")
-	}),
-}
@@ -0,0 +1,16 @@
+package cli
+
+import (
+	"context"
+
+	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+)
+
+// WithClient handles gRPC client setup and cleanup, calls fn with client and context
+func WithClient(fn func(context.Context, v1.HeadscaleServiceClient) error) error {
+	ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
+	defer cancel()
+	defer conn.Close()
+
+	return fn(ctx, client)
+}
@@ -1,8 +1,7 @@
 package cli

 import (
-	"fmt"
-
+	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
 )

@@ -12,14 +11,12 @@ func init() {

 var configTestCmd = &cobra.Command{
 	Use:   "configtest",
-	Short: "Test the configuration.",
-	Long:  "Run a test of the configuration and exit.",
-	RunE: func(cmd *cobra.Command, args []string) error {
+	Short: "Test the configuration",
+	Long:  "Run a test of the configuration and exit",
+	Run: func(cmd *cobra.Command, args []string) {
 		_, err := newHeadscaleServerWithConfig()
 		if err != nil {
-			return fmt.Errorf("configuration error: %w", err)
+			log.Fatal().Caller().Err(err).Msg("Error initializing")
 		}
-
-		return nil
 	},
 }
@@ -0,0 +1,46 @@
+package cli
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestConfigTestCommand(t *testing.T) {
+	// Test that the configtest command exists and is properly configured
+	assert.NotNil(t, configTestCmd)
+	assert.Equal(t, "configtest", configTestCmd.Use)
+	assert.Equal(t, "Test the configuration.", configTestCmd.Short)
+	assert.Equal(t, "Run a test of the configuration and exit.", configTestCmd.Long)
+	assert.NotNil(t, configTestCmd.Run)
+}
+
+func TestConfigTestCommandInRootCommand(t *testing.T) {
+	// Test that configtest is available as a subcommand of root
+	cmd, _, err := rootCmd.Find([]string{"configtest"})
+	require.NoError(t, err)
+	assert.Equal(t, "configtest", cmd.Name())
+	assert.Equal(t, configTestCmd, cmd)
+}
+
+func TestConfigTestCommandHelp(t *testing.T) {
+	// Test that the command has proper help text
+	assert.NotEmpty(t, configTestCmd.Short)
+	assert.NotEmpty(t, configTestCmd.Long)
+	assert.Contains(t, configTestCmd.Short, "configuration")
+	assert.Contains(t, configTestCmd.Long, "test")
+	assert.Contains(t, configTestCmd.Long, "configuration")
+}
+
+// Note: We can't easily test the actual execution of configtest because:
+// 1. It depends on configuration files being present
+// 2. It calls log.Fatal() which would exit the test process
+// 3. It tries to initialize a full Headscale server
+//
+// In a real refactor, we would:
+// 1. Extract the configuration validation logic to a testable function
+// 2. Return errors instead of calling log.Fatal()
+// 3. Accept configuration as a parameter instead of loading from global state
+//
+// For now, we test the command structure and that it's properly wired up.
@@ -3,21 +3,37 @@ package cli
 import (
 	"context"
 	"fmt"
-	"net/http"

-	clientv1 "github.com/juanfont/headscale/gen/client/v1"
+	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
 	"github.com/juanfont/headscale/hscontrol/types"
+	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
+	"google.golang.org/grpc/status"
+)
+
+const (
+	errPreAuthKeyMalformed = Error("key is malformed. expected 64 hex characters with `nodekey` prefix")
 )

 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("key", "k", "", "Key")
-	mustMarkRequired(createNodeCmd, "name", "user", "key")

+	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("")
+	}
 	createNodeCmd.Flags().
 		StringSliceP("route", "r", []string{}, "List (or repeated flags) of routes to advertise")

@@ -32,33 +48,79 @@ var debugCmd = &cobra.Command{

 var createNodeCmd = &cobra.Command{
 	Use:   "create-node",
-	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")
+	Short: "Create a node that can be registered with `nodes register <>` command",
+	Run: func(cmd *cobra.Command, args []string) {
+		output := GetOutputFlag(cmd)

-		_, err := types.AuthIDFromString(registrationID)
+		user, err := cmd.Flags().GetString("user")
 		if err != nil {
-			return fmt.Errorf("parsing machine key: %w", err)
+			ErrorOutput(err, fmt.Sprintf("Error getting user: %s", err), output)
+			return
 		}

-		routes, _ := cmd.Flags().GetStringSlice("route")
+		name, err := cmd.Flags().GetString("name")
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error getting node from flag: %s", err),
+				output,
+			)
+			return
+		}

-		resp, err := client.DebugCreateNodeWithResponse(ctx, clientv1.DebugCreateNodeJSONRequestBody{
-			Key:    &registrationID,
-			Name:   &name,
-			User:   &user,
-			Routes: &routes,
+		registrationID, err := cmd.Flags().GetString("key")
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error getting key from flag: %s", err),
+				output,
+			)
+			return
+		}
+
+		_, err = types.RegistrationIDFromString(registrationID)
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Failed to parse machine key from flag: %s", err),
+				output,
+			)
+			return
+		}
+
+		routes, err := cmd.Flags().GetStringSlice("route")
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error getting routes from flag: %s", err),
+				output,
+			)
+			return
+		}
+
+		err = WithClient(func(ctx context.Context, client v1.HeadscaleServiceClient) error {
+			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,
+				)
+				return err
+			}
+
+			SuccessOutput(response.GetNode(), "Node created", output)
+			return nil
 		})
 		if err != nil {
-			return fmt.Errorf("creating node: %w", err)
+			return
 		}
-
-		if resp.StatusCode() != http.StatusOK {
-			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
-		}
-
-		return printOutput(cmd, resp.JSON200.Node, "Node created")
-	}),
+	},
 }
@@ -0,0 +1,144 @@
+package cli
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestDebugCommand(t *testing.T) {
+	// Test that the debug command exists and is properly configured
+	assert.NotNil(t, debugCmd)
+	assert.Equal(t, "debug", debugCmd.Use)
+	assert.Equal(t, "debug and testing commands", debugCmd.Short)
+	assert.Equal(t, "debug contains extra commands used for debugging and testing headscale", debugCmd.Long)
+}
+
+func TestDebugCommandInRootCommand(t *testing.T) {
+	// Test that debug is available as a subcommand of root
+	cmd, _, err := rootCmd.Find([]string{"debug"})
+	require.NoError(t, err)
+	assert.Equal(t, "debug", cmd.Name())
+	assert.Equal(t, debugCmd, cmd)
+}
+
+func TestCreateNodeCommand(t *testing.T) {
+	// Test that the create-node command exists and is properly configured
+	assert.NotNil(t, createNodeCmd)
+	assert.Equal(t, "create-node", createNodeCmd.Use)
+	assert.Equal(t, "Create a node that can be registered with `nodes register <>` command", createNodeCmd.Short)
+	assert.NotNil(t, createNodeCmd.Run)
+}
+
+func TestCreateNodeCommandInDebugCommand(t *testing.T) {
+	// Test that create-node is available as a subcommand of debug
+	cmd, _, err := rootCmd.Find([]string{"debug", "create-node"})
+	require.NoError(t, err)
+	assert.Equal(t, "create-node", cmd.Name())
+	assert.Equal(t, createNodeCmd, cmd)
+}
+
+func TestCreateNodeCommandFlags(t *testing.T) {
+	// Test that create-node has the required flags
+
+	// Test name flag
+	nameFlag := createNodeCmd.Flags().Lookup("name")
+	assert.NotNil(t, nameFlag)
+	assert.Equal(t, "", nameFlag.Shorthand) // No shorthand for name
+	assert.Equal(t, "", nameFlag.DefValue)
+
+	// Test user flag
+	userFlag := createNodeCmd.Flags().Lookup("user")
+	assert.NotNil(t, userFlag)
+	assert.Equal(t, "u", userFlag.Shorthand)
+
+	// Test key flag
+	keyFlag := createNodeCmd.Flags().Lookup("key")
+	assert.NotNil(t, keyFlag)
+	assert.Equal(t, "k", keyFlag.Shorthand)
+
+	// Test route flag
+	routeFlag := createNodeCmd.Flags().Lookup("route")
+	assert.NotNil(t, routeFlag)
+	assert.Equal(t, "r", routeFlag.Shorthand)
+
+}
+
+func TestCreateNodeCommandRequiredFlags(t *testing.T) {
+	// Test that required flags are marked as required
+	// We can't easily test the actual requirement enforcement without executing the command
+	// But we can test that the flags exist and have the expected properties
+
+	// These flags should be required based on the init() function
+	requiredFlags := []string{"name", "user", "key"}
+
+	for _, flagName := range requiredFlags {
+		flag := createNodeCmd.Flags().Lookup(flagName)
+		assert.NotNil(t, flag, "Required flag %s should exist", flagName)
+	}
+}
+
+func TestErrorType(t *testing.T) {
+	// Test the Error type implementation
+	err := errPreAuthKeyMalformed
+	assert.Equal(t, "key is malformed. expected 64 hex characters with `nodekey` prefix", err.Error())
+	assert.Equal(t, "key is malformed. expected 64 hex characters with `nodekey` prefix", string(err))
+
+	// Test that it implements the error interface
+	var genericErr error = err
+	assert.Equal(t, "key is malformed. expected 64 hex characters with `nodekey` prefix", genericErr.Error())
+}
+
+func TestErrorConstants(t *testing.T) {
+	// Test that error constants are defined properly
+	assert.Equal(t, Error("key is malformed. expected 64 hex characters with `nodekey` prefix"), errPreAuthKeyMalformed)
+}
+
+func TestDebugCommandStructure(t *testing.T) {
+	// Test that debug has create-node as a subcommand
+	found := false
+	for _, subcmd := range debugCmd.Commands() {
+		if subcmd.Name() == "create-node" {
+			found = true
+			break
+		}
+	}
+	assert.True(t, found, "create-node should be a subcommand of debug")
+}
+
+func TestCreateNodeCommandHelp(t *testing.T) {
+	// Test that the command has proper help text
+	assert.NotEmpty(t, createNodeCmd.Short)
+	assert.Contains(t, createNodeCmd.Short, "Create a node")
+	assert.Contains(t, createNodeCmd.Short, "nodes register")
+}
+
+func TestCreateNodeCommandFlagDescriptions(t *testing.T) {
+	// Test that flags have appropriate usage descriptions
+	nameFlag := createNodeCmd.Flags().Lookup("name")
+	assert.Equal(t, "Name", nameFlag.Usage)
+
+	userFlag := createNodeCmd.Flags().Lookup("user")
+	assert.Equal(t, "User", userFlag.Usage)
+
+	keyFlag := createNodeCmd.Flags().Lookup("key")
+	assert.Equal(t, "Key", keyFlag.Usage)
+
+	routeFlag := createNodeCmd.Flags().Lookup("route")
+	assert.Contains(t, routeFlag.Usage, "routes to advertise")
+
+}
+
+// Note: We can't easily test the actual execution of create-node because:
+// 1. It depends on gRPC client configuration
+// 2. It calls SuccessOutput/ErrorOutput which exit the process
+// 3. It requires valid registration keys and user setup
+//
+// In a real refactor, we would:
+// 1. Extract the business logic to testable functions
+// 2. Use dependency injection for the gRPC client
+// 3. Return errors instead of calling ErrorOutput/SuccessOutput
+// 4. Add validation functions that can be tested independently
+//
+// For now, we test the command structure and flag configuration.
@@ -12,15 +12,18 @@ func init() {
 }

 var dumpConfigCmd = &cobra.Command{
-	Use:    "dumpConfig",
-	Short:  "dump current config to /etc/headscale/config.dump.yaml, integration test only",
-	Hidden: true,
-	RunE: func(cmd *cobra.Command, args []string) error {
-		err := viper.WriteConfigAs("/etc/headscale/config.dump.yaml")
-		if err != nil {
-			return fmt.Errorf("dumping config: %w", err)
-		}
-
+	Use:     "dump-config",
+	Short:   "Dump current config to /etc/headscale/config.dump.yaml, integration test only",
+	Aliases: []string{"dumpConfig"},
+	Hidden:  true,
+	Args: func(cmd *cobra.Command, args []string) error {
 		return nil
 	},
+	Run: func(cmd *cobra.Command, args []string) {
+		err := viper.WriteConfigAs("/etc/headscale/config.dump.yaml")
+		if err != nil {
+			//nolint
+			fmt.Println("Failed to dump config")
+		}
+	},
 }
@@ -21,17 +21,22 @@ var generateCmd = &cobra.Command{
 var generatePrivateKeyCmd = &cobra.Command{
 	Use:   "private-key",
 	Short: "Generate a private key for the headscale server",
-	RunE: func(cmd *cobra.Command, args []string) error {
+	Run: func(cmd *cobra.Command, args []string) {
+		output := GetOutputFlag(cmd)
 		machineKey := key.NewMachine()

 		machineKeyStr, err := machineKey.MarshalText()
 		if err != nil {
-			return fmt.Errorf("marshalling machine key: %w", err)
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error getting machine key from flag: %s", err),
+				output,
+			)
 		}

-		return printOutput(cmd, map[string]string{
+		SuccessOutput(map[string]string{
 			"private_key": string(machineKeyStr),
 		},
-			string(machineKeyStr))
+			string(machineKeyStr), output)
 	},
 }
@@ -0,0 +1,230 @@
+package cli
+
+import (
+	"bytes"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gopkg.in/yaml.v3"
+)
+
+func TestGenerateCommand(t *testing.T) {
+	// Test that the generate command exists and shows help
+	cmd := &cobra.Command{
+		Use:   "headscale",
+		Short: "headscale - a Tailscale control server",
+	}
+
+	cmd.AddCommand(generateCmd)
+
+	out := new(bytes.Buffer)
+	cmd.SetOut(out)
+	cmd.SetErr(out)
+	cmd.SetArgs([]string{"generate", "--help"})
+
+	err := cmd.Execute()
+	require.NoError(t, err)
+
+	outStr := out.String()
+	assert.Contains(t, outStr, "Generate commands")
+	assert.Contains(t, outStr, "private-key")
+	assert.Contains(t, outStr, "Aliases:")
+	assert.Contains(t, outStr, "gen")
+}
+
+func TestGenerateCommandAlias(t *testing.T) {
+	// Test that the "gen" alias works
+	cmd := &cobra.Command{
+		Use:   "headscale",
+		Short: "headscale - a Tailscale control server",
+	}
+
+	cmd.AddCommand(generateCmd)
+
+	out := new(bytes.Buffer)
+	cmd.SetOut(out)
+	cmd.SetErr(out)
+	cmd.SetArgs([]string{"gen", "--help"})
+
+	err := cmd.Execute()
+	require.NoError(t, err)
+
+	outStr := out.String()
+	assert.Contains(t, outStr, "Generate commands")
+}
+
+func TestGeneratePrivateKeyCommand(t *testing.T) {
+	tests := []struct {
+		name       string
+		args       []string
+		expectJSON bool
+		expectYAML bool
+	}{
+		{
+			name:       "default output",
+			args:       []string{"generate", "private-key"},
+			expectJSON: false,
+			expectYAML: false,
+		},
+		{
+			name:       "json output",
+			args:       []string{"generate", "private-key", "--output", "json"},
+			expectJSON: true,
+			expectYAML: false,
+		},
+		{
+			name:       "yaml output",
+			args:       []string{"generate", "private-key", "--output", "yaml"},
+			expectJSON: false,
+			expectYAML: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Note: This command calls SuccessOutput which exits the process
+			// We can't test the actual execution easily without mocking
+			// Instead, we test the command structure and that it exists
+
+			cmd := &cobra.Command{
+				Use:   "headscale",
+				Short: "headscale - a Tailscale control server",
+			}
+
+			cmd.AddCommand(generateCmd)
+			cmd.PersistentFlags().StringP("output", "o", "", "Output format")
+
+			// Test that the command exists and can be found
+			privateKeyCmd, _, err := cmd.Find([]string{"generate", "private-key"})
+			require.NoError(t, err)
+			assert.Equal(t, "private-key", privateKeyCmd.Name())
+			assert.Equal(t, "Generate a private key for the headscale server", privateKeyCmd.Short)
+		})
+	}
+}
+
+func TestGeneratePrivateKeyHelp(t *testing.T) {
+	cmd := &cobra.Command{
+		Use:   "headscale",
+		Short: "headscale - a Tailscale control server",
+	}
+
+	cmd.AddCommand(generateCmd)
+
+	out := new(bytes.Buffer)
+	cmd.SetOut(out)
+	cmd.SetErr(out)
+	cmd.SetArgs([]string{"generate", "private-key", "--help"})
+
+	err := cmd.Execute()
+	require.NoError(t, err)
+
+	outStr := out.String()
+	assert.Contains(t, outStr, "Generate a private key for the headscale server")
+	assert.Contains(t, outStr, "Usage:")
+}
+
+// Test the key generation logic in isolation (without SuccessOutput/ErrorOutput)
+func TestPrivateKeyGeneration(t *testing.T) {
+	// We can't easily test the full command because it calls SuccessOutput which exits
+	// But we can test that the key generation produces valid output format
+
+	// This is testing the core logic that would be in the command
+	// In a real refactor, we'd extract this to a testable function
+
+	// For now, we can test that the command structure is correct
+	assert.NotNil(t, generatePrivateKeyCmd)
+	assert.Equal(t, "private-key", generatePrivateKeyCmd.Use)
+	assert.Equal(t, "Generate a private key for the headscale server", generatePrivateKeyCmd.Short)
+	assert.NotNil(t, generatePrivateKeyCmd.Run)
+}
+
+func TestGenerateCommandStructure(t *testing.T) {
+	// Test the command hierarchy
+	assert.Equal(t, "generate", generateCmd.Use)
+	assert.Equal(t, "Generate commands", generateCmd.Short)
+	assert.Contains(t, generateCmd.Aliases, "gen")
+
+	// Test that private-key is a subcommand
+	found := false
+	for _, subcmd := range generateCmd.Commands() {
+		if subcmd.Name() == "private-key" {
+			found = true
+			break
+		}
+	}
+	assert.True(t, found, "private-key should be a subcommand of generate")
+}
+
+// Helper function to test output formats (would be used if we refactored the command)
+func validatePrivateKeyOutput(t *testing.T, output string, format string) {
+	switch format {
+	case "json":
+		var result map[string]interface{}
+		err := json.Unmarshal([]byte(output), &result)
+		require.NoError(t, err, "Output should be valid JSON")
+
+		privateKey, exists := result["private_key"]
+		require.True(t, exists, "JSON should contain private_key field")
+
+		keyStr, ok := privateKey.(string)
+		require.True(t, ok, "private_key should be a string")
+		require.NotEmpty(t, keyStr, "private_key should not be empty")
+
+		// Basic validation that it looks like a machine key
+		assert.True(t, strings.HasPrefix(keyStr, "mkey:"), "Machine key should start with mkey:")
+
+	case "yaml":
+		var result map[string]interface{}
+		err := yaml.Unmarshal([]byte(output), &result)
+		require.NoError(t, err, "Output should be valid YAML")
+
+		privateKey, exists := result["private_key"]
+		require.True(t, exists, "YAML should contain private_key field")
+
+		keyStr, ok := privateKey.(string)
+		require.True(t, ok, "private_key should be a string")
+		require.NotEmpty(t, keyStr, "private_key should not be empty")
+
+		assert.True(t, strings.HasPrefix(keyStr, "mkey:"), "Machine key should start with mkey:")
+
+	default:
+		// Default format should just be the key itself
+		assert.True(t, strings.HasPrefix(output, "mkey:"), "Default output should be the machine key")
+		assert.NotContains(t, output, "{", "Default output should not contain JSON")
+		assert.NotContains(t, output, "private_key:", "Default output should not contain YAML structure")
+	}
+}
+
+func TestPrivateKeyOutputFormats(t *testing.T) {
+	// Test cases for different output formats
+	// These test the validation logic we would use after refactoring
+
+	tests := []struct {
+		format string
+		sample string
+	}{
+		{
+			format: "json",
+			sample: `{"private_key": "mkey:abcd1234567890abcd1234567890abcd1234567890abcd1234567890abcd1234"}`,
+		},
+		{
+			format: "yaml",
+			sample: "private_key: mkey:abcd1234567890abcd1234567890abcd1234567890abcd1234567890abcd1234\n",
+		},
+		{
+			format: "",
+			sample: "mkey:abcd1234567890abcd1234567890abcd1234567890abcd1234567890abcd1234",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run("format_"+tt.format, func(t *testing.T) {
+			validatePrivateKeyOutput(t, tt.sample, tt.format)
+		})
+	}
+}
@@ -1,32 +0,0 @@
-package cli
-
-import (
-	"context"
-	"fmt"
-	"net/http"
-
-	clientv1 "github.com/juanfont/headscale/gen/client/v1"
-	"github.com/spf13/cobra"
-)
-
-func init() {
-	rootCmd.AddCommand(healthCmd)
-}
-
-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.",
-	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
-		resp, err := client.HealthWithResponse(ctx)
-		if err != nil {
-			return fmt.Errorf("checking health: %w", err)
-		}
-
-		if resp.StatusCode() != http.StatusOK {
-			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
-		}
-
-		return printOutput(cmd, resp.JSON200, "")
-	}),
-}
@@ -1,7 +1,6 @@
 package cli

 import (
-	"context"
 	"encoding/json"
 	"errors"
 	"fmt"
@@ -11,20 +10,22 @@ 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"
 )

-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")
-)
+// Error is used to compare errors as per https://dave.cheney.net/2016/04/07/constant-errors
+type Error string

-const refreshTTL = 60 * time.Minute
+func (e Error) Error() string { return string(e) }
+
+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 accessTTL = 2 * time.Minute

@@ -36,13 +37,12 @@ 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",
-	RunE: func(cmd *cobra.Command, args []string) error {
+	Run: func(cmd *cobra.Command, args []string) {
 		err := mockOIDC()
 		if err != nil {
-			return fmt.Errorf("running mock OIDC server: %w", err)
+			log.Error().Err(err).Msgf("Error running mock OIDC server")
+			os.Exit(1)
 		}
-
-		return nil
 	},
 }

@@ -51,47 +51,41 @@ 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 errMockOidcUsersNotDefined
+		return errors.New("MOCKOIDC_USERS not defined")
 	}

 	var users []mockoidc.MockUser
-
 	err := json.Unmarshal([]byte(userStr), &users)
 	if err != nil {
 		return fmt.Errorf("unmarshalling users: %w", err)
 	}

-	log.Info().Interface(zf.Users, users).Msg("loading users from JSON")
+	log.Info().Interface("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 {
@@ -103,7 +97,7 @@ func mockOIDC() error {
 		return err
 	}

-	listener, err := new(net.ListenConfig).Listen(context.Background(), "tcp", fmt.Sprintf("%s:%d", addrStr, port))
+	listener, err := net.Listen("tcp", fmt.Sprintf("%s:%d", addrStr, port))
 	if err != nil {
 		return err
 	}
@@ -112,10 +106,8 @@ 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

@@ -146,13 +138,12 @@ 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)
 			}
 		})
 	})
@@ -1,271 +0,0 @@
-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
-}
@@ -2,65 +2,32 @@ package cli

 import (
 	"context"
-	"errors"
 	"fmt"
-	"net/http"
+	"io"
 	"os"

-	clientv1 "github.com/juanfont/headscale/gen/client/v1"
-	"github.com/juanfont/headscale/hscontrol/db"
+	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
 	"github.com/juanfont/headscale/hscontrol/policy"
 	"github.com/juanfont/headscale/hscontrol/types"
+	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
 	"tailscale.com/types/views"
 )

-const (
-	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 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")
-	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")
+	if err := setPolicy.MarkFlagRequired("file"); err != nil {
+		log.Fatal().Err(err).Msg("")
+	}
 	policyCmd.AddCommand(setPolicy)

 	checkPolicy.Flags().StringP("file", "f", "", "Path to a policy file in HuJSON format")
-	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")
+	if err := checkPolicy.MarkFlagRequired("file"); err != nil {
+		log.Fatal().Err(err).Msg("")
+	}
 	policyCmd.AddCommand(checkPolicy)
 }

@@ -72,48 +39,28 @@ var policyCmd = &cobra.Command{
 var getPolicy = &cobra.Command{
 	Use:     "get",
 	Short:   "Print the current ACL Policy",
-	Aliases: []string{cmdShow, "view", "fetch"},
-	RunE: func(cmd *cobra.Command, args []string) error {
-		var policyData string
+	Aliases: []string{"show", "view", "fetch"},
+	Run: func(cmd *cobra.Command, args []string) {
+		output := GetOutputFlag(cmd)

-		if bypass, _ := cmd.Flags().GetBool(bypassFlag); bypass {
-			d, err := openBypassDB(cmd)
+		err := WithClient(func(ctx context.Context, client v1.HeadscaleServiceClient) error {
+			request := &v1.GetPolicyRequest{}
+
+			response, err := client.GetPolicy(ctx, request)
 			if err != nil {
+				ErrorOutput(err, fmt.Sprintf("Failed loading ACL Policy: %s", err), output)
 				return err
 			}
-			defer d.Close()

-			pol, err := d.GetPolicy()
-			if err != nil {
-				return fmt.Errorf("loading policy from database: %w", err)
-			}
-
-			policyData = pol.Data
-		} else {
-			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)
-				}
-
-				if resp.StatusCode() != http.StatusOK {
-					return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
-				}
-
-				policyData = resp.JSON200.Policy
-
-				return nil
-			})
-			if err != nil {
-				return err
-			}
+			// 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("", response.GetPolicy(), "")
+			return nil
+		})
+		if err != nil {
+			return
 		}
-
-		// 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
 	},
 }

@@ -124,137 +71,66 @@ 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"},
-	RunE: func(cmd *cobra.Command, args []string) error {
+	Run: func(cmd *cobra.Command, args []string) {
+		output := GetOutputFlag(cmd)
 		policyPath, _ := cmd.Flags().GetString("file")

-		policyBytes, err := os.ReadFile(policyPath)
+		f, err := os.Open(policyPath)
 		if err != nil {
-			return fmt.Errorf("reading policy file: %w", err)
+			ErrorOutput(err, fmt.Sprintf("Error opening the policy file: %s", err), output)
+			return
+		}
+		defer f.Close()
+
+		policyBytes, err := io.ReadAll(f)
+		if err != nil {
+			ErrorOutput(err, fmt.Sprintf("Error reading the policy file: %s", err), output)
+			return
 		}

-		if bypass, _ := cmd.Flags().GetBool(bypassFlag); bypass {
-			d, err := openBypassDB(cmd)
-			if err != nil {
+		request := &v1.SetPolicyRequest{Policy: string(policyBytes)}
+
+		err = WithClient(func(ctx context.Context, client v1.HeadscaleServiceClient) error {
+			if _, err := client.SetPolicy(ctx, request); err != nil {
+				ErrorOutput(err, fmt.Sprintf("Failed to set ACL Policy: %s", err), output)
 				return err
 			}
-			defer d.Close()

-			users, err := d.ListUsers(nil)
-			if err != nil {
-				return fmt.Errorf("loading users for policy validation: %w", err)
-			}
-
-			_, err = policy.NewPolicyManager(policyBytes, users, views.Slice[types.NodeView]{})
-			if err != nil {
-				return fmt.Errorf("parsing policy file: %w", err)
-			}
-
-			_, err = d.SetPolicy(string(policyBytes))
-			if err != nil {
-				return fmt.Errorf("setting ACL policy: %w", err)
-			}
-		} else {
-			policyStr := string(policyBytes)
-
-			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 resp.StatusCode() != http.StatusOK {
-					return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
-				}
-
-				return nil
-			})
-			if err != nil {
-				return err
-			}
+			SuccessOutput(nil, "Policy updated.", "")
+			return nil
+		})
+		if err != nil {
+			return
 		}
-
-		fmt.Println("Policy updated.")
-
-		return nil
 	},
 }

 var checkPolicy = &cobra.Command{
 	Use:   "check",
 	Short: "Check the Policy file for errors",
-	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 {
+	Run: func(cmd *cobra.Command, args []string) {
+		output := GetOutputFlag(cmd)
 		policyPath, _ := cmd.Flags().GetString("file")

-		policyBytes, err := os.ReadFile(policyPath)
+		f, err := os.Open(policyPath)
 		if err != nil {
-			return fmt.Errorf("reading policy file: %w", err)
+			ErrorOutput(err, fmt.Sprintf("Error opening the policy file: %s", err), output)
+			return
 		}
+		defer f.Close()

-		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
-		}
-
-		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
-		})
+		policyBytes, err := io.ReadAll(f)
 		if err != nil {
-			return err
+			ErrorOutput(err, fmt.Sprintf("Error reading the policy file: %s", err), output)
+			return
 		}

-		fmt.Println("Policy is valid")
+		_, err = policy.NewPolicyManager(policyBytes, nil, views.Slice[types.NodeView]{})
+		if err != nil {
+			ErrorOutput(err, fmt.Sprintf("Error parsing the policy file: %s", err), output)
+			return
+		}

-		return nil
+		SuccessOutput(nil, "Policy is valid", "")
 	},
 }
@@ -3,25 +3,29 @@ package cli
 import (
 	"context"
 	"fmt"
-	"net/http"
 	"strconv"
 	"strings"
+	"time"

-	clientv1 "github.com/juanfont/headscale/gen/client/v1"
-	"github.com/juanfont/headscale/hscontrol/util"
+	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	"github.com/prometheus/common/model"
+	"github.com/pterm/pterm"
+	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
-)
-
-const (
-	DefaultPreAuthKeyExpiry = "1h"
+	"google.golang.org/protobuf/types/known/timestamppb"
 )

 func init() {
 	rootCmd.AddCommand(preauthkeysCmd)
+	preauthkeysCmd.PersistentFlags().Uint64P("user", "u", 0, "User identifier (ID)")
+
+	err := preauthkeysCmd.MarkPersistentFlagRequired("user")
+	if err != nil {
+		log.Fatal().Err(err).Msg("")
+	}
 	preauthkeysCmd.AddCommand(listPreAuthKeys)
 	preauthkeysCmd.AddCommand(createPreAuthKeyCmd)
 	preauthkeysCmd.AddCommand(expirePreAuthKeyCmd)
-	preauthkeysCmd.AddCommand(deletePreAuthKeyCmd)
 	createPreAuthKeyCmd.PersistentFlags().
 		Bool("reusable", false, "Make the preauthkey reusable")
 	createPreAuthKeyCmd.PersistentFlags().
@@ -30,9 +34,6 @@ func init() {
 		StringP("expiration", "e", DefaultPreAuthKeyExpiry, "Human-readable expiration of the key (e.g. 30m, 24h)")
 	createPreAuthKeyCmd.Flags().
 		StringSlice("tags", []string{}, "Tags to automatically assign to node")
-	createPreAuthKeyCmd.PersistentFlags().Uint64P("user", "u", 0, "User identifier (ID)")
-	expirePreAuthKeyCmd.PersistentFlags().Uint64P("id", "i", 0, "Authkey ID")
-	deletePreAuthKeyCmd.PersistentFlags().Uint64P("id", "i", 0, "Authkey ID")
 }

 var preauthkeysCmd = &cobra.Command{
@@ -42,161 +43,197 @@ var preauthkeysCmd = &cobra.Command{
 }

 var listPreAuthKeys = &cobra.Command{
-	Use:     cmdList,
-	Short:   "List all preauthkeys",
-	Aliases: []string{"ls", cmdShow},
-	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
-		resp, err := client.ListPreAuthKeysWithResponse(ctx)
+	Use:     "list",
+	Short:   "List the preauthkeys for this user",
+	Aliases: []string{"ls", "show"},
+	Run: func(cmd *cobra.Command, args []string) {
+		output := GetOutputFlag(cmd)
+
+		user, err := cmd.Flags().GetUint64("user")
 		if err != nil {
-			return fmt.Errorf("listing preauthkeys: %w", err)
+			ErrorOutput(err, fmt.Sprintf("Error getting user: %s", err), output)
+			return
 		}

-		if resp.StatusCode() != http.StatusOK {
-			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
-		}
-
-		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,
-				})
+		err = WithClient(func(ctx context.Context, client v1.HeadscaleServiceClient) error {
+			request := &v1.ListPreAuthKeysRequest{
+				User: user,
 			}

-			return renderTable([]string{
-				"ID",
-				"Key/Prefix",
-				"Reusable",
-				"Ephemeral",
-				"Used",
-				colExpiration,
-				colCreated,
-				"Owner",
-			}, rows)
+			response, err := client.ListPreAuthKeys(ctx, request)
+			if err != nil {
+				ErrorOutput(
+					err,
+					fmt.Sprintf("Error getting the list of keys: %s", err),
+					output,
+				)
+				return err
+			}
+
+			if output != "" {
+				SuccessOutput(response.GetPreAuthKeys(), "", output)
+				return nil
+			}
+
+			tableData := pterm.TableData{
+				{
+					"ID",
+					"Key",
+					"Reusable",
+					"Ephemeral",
+					"Used",
+					"Expiration",
+					"Created",
+					"Tags",
+				},
+			}
+			for _, key := range response.GetPreAuthKeys() {
+				expiration := "-"
+				if key.GetExpiration() != nil {
+					expiration = ColourTime(key.GetExpiration().AsTime())
+				}
+
+				aclTags := ""
+
+				for _, tag := range key.GetAclTags() {
+					aclTags += "," + tag
+				}
+
+				aclTags = strings.TrimLeft(aclTags, ",")
+
+				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(HeadscaleDateTimeFormat),
+					aclTags,
+				})
+
+			}
+			err = pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
+			if err != nil {
+				ErrorOutput(
+					err,
+					fmt.Sprintf("Failed to render pterm table: %s", err),
+					output,
+				)
+				return err
+			}
+			return nil
 		})
-	}),
+		if err != nil {
+			return
+		}
+	},
 }

 var createPreAuthKeyCmd = &cobra.Command{
 	Use:     "create",
-	Short:   "Creates a new preauthkey",
-	Aliases: []string{"c", cmdNew},
-	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
-		user, _ := cmd.Flags().GetUint64("user")
+	Short:   "Creates a new preauthkey in the specified user",
+	Aliases: []string{"c", "new"},
+	Run: func(cmd *cobra.Command, args []string) {
+		output := GetOutputFlag(cmd)
+
+		user, err := cmd.Flags().GetUint64("user")
+		if err != nil {
+			ErrorOutput(err, fmt.Sprintf("Error getting user: %s", err), output)
+			return
+		}
+
 		reusable, _ := cmd.Flags().GetBool("reusable")
 		ephemeral, _ := cmd.Flags().GetBool("ephemeral")
 		tags, _ := cmd.Flags().GetStringSlice("tags")

-		expiryTime, err := expirationFromFlag(cmd)
+		request := &v1.CreatePreAuthKeyRequest{
+			User:      user,
+			Reusable:  reusable,
+			Ephemeral: ephemeral,
+			AclTags:   tags,
+		}
+
+		durationStr, _ := cmd.Flags().GetString("expiration")
+
+		duration, err := model.ParseDuration(durationStr)
 		if err != nil {
-			return err
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Could not parse duration: %s\n", err),
+				output,
+			)
+			return
 		}

-		userStr := strconv.FormatUint(user, util.Base10)
+		expiration := time.Now().UTC().Add(time.Duration(duration))

-		request := clientv1.CreatePreAuthKeyJSONRequestBody{
-			User:       &userStr,
-			Reusable:   &reusable,
-			Ephemeral:  &ephemeral,
-			AclTags:    &tags,
-			Expiration: &expiryTime,
-		}
+		log.Trace().
+			Dur("expiration", time.Duration(duration)).
+			Msg("expiration has been set")

-		resp, err := client.CreatePreAuthKeyWithResponse(ctx, request)
+		request.Expiration = timestamppb.New(expiration)
+
+		err = WithClient(func(ctx context.Context, client v1.HeadscaleServiceClient) error {
+			response, err := client.CreatePreAuthKey(ctx, request)
+			if err != nil {
+				ErrorOutput(
+					err,
+					fmt.Sprintf("Cannot create Pre Auth Key: %s\n", err),
+					output,
+				)
+				return err
+			}
+
+			SuccessOutput(response.GetPreAuthKey(), response.GetPreAuthKey().GetKey(), output)
+			return nil
+		})
 		if err != nil {
-			return fmt.Errorf("creating preauthkey: %w", err)
+			return
 		}
-
-		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:     cmdExpire,
+	Use:     "expire KEY",
 	Short:   "Expire a preauthkey",
-	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 {
-			return err
+	Aliases: []string{"revoke", "exp", "e"},
+	Args: func(cmd *cobra.Command, args []string) error {
+		if len(args) < 1 {
+			return errMissingParameter
 		}

-		idStr := strconv.FormatUint(id, util.Base10)
+		return nil
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		output := GetOutputFlag(cmd)
+		user, err := cmd.Flags().GetUint64("user")
+		if err != nil {
+			ErrorOutput(err, fmt.Sprintf("Error getting user: %s", err), output)
+			return
+		}

-		resp, err := client.ExpirePreAuthKeyWithResponse(ctx, clientv1.ExpirePreAuthKeyJSONRequestBody{
-			Id: &idStr,
+		err = WithClient(func(ctx context.Context, client v1.HeadscaleServiceClient) error {
+			request := &v1.ExpirePreAuthKeyRequest{
+				User: user,
+				Key:  args[0],
+			}
+
+			response, err := client.ExpirePreAuthKey(ctx, request)
+			if err != nil {
+				ErrorOutput(
+					err,
+					fmt.Sprintf("Cannot expire Pre Auth Key: %s\n", err),
+					output,
+				)
+				return err
+			}
+
+			SuccessOutput(response, "Key expired", output)
+			return nil
 		})
 		if err != nil {
-			return fmt.Errorf("expiring preauthkey: %w", err)
+			return
 		}
-
-		if resp.StatusCode() != http.StatusOK {
-			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
-		}
-
-		return printOutput(cmd, resp.JSON200, "Key expired")
-	}),
-}
-
-var deletePreAuthKeyCmd = &cobra.Command{
-	Use:     cmdDelete,
-	Short:   "Delete a preauthkey",
-	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 {
-			return err
-		}
-
-		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")
-	}),
+	},
 }
@@ -1,10 +1,10 @@
 package cli

 import (
+	"fmt"
 	"os"
 	"runtime"
 	"slices"
-	"strings"

 	"github.com/juanfont/headscale/hscontrol/types"
 	"github.com/rs/zerolog"
@@ -22,6 +22,11 @@ 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)")
@@ -29,34 +34,25 @@ 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.
@@ -71,56 +67,25 @@ func initConfig() {

 	disableUpdateCheck := viper.GetBool("disable_check_updates")
 	if !disableUpdateCheck && !machineOutput {
-		versionInfo := types.GetVersionInfo()
 		if (runtime.GOOS == "linux" || runtime.GOOS == "darwin") &&
-			!versionInfo.Dirty {
+			types.Version != "dev" {
 			githubTag := &latest.GithubTag{
-				Owner:         "juanfont",
-				Repository:    "headscale",
-				TagFilterFunc: filterPreReleasesIfStable(func() string { return versionInfo.Version }),
+				Owner:      "juanfont",
+				Repository: "headscale",
 			}
-
-			res, err := latest.Check(githubTag, versionInfo.Version)
+			res, err := latest.Check(githubTag, types.Version)
 			if err == nil && res.Outdated {
 				//nolint
 				log.Warn().Msgf(
 					"An updated version of Headscale has been found (%s vs. your current %s). Check it out https://github.com/juanfont/headscale/releases\n",
 					res.Current,
-					versionInfo.Version,
+					types.Version,
 				)
 			}
 		}
 	}
 }

-var prereleases = []string{"alpha", "beta", "rc", "dev"}
-
-func isPreReleaseVersion(version string) bool {
-	return slices.ContainsFunc(prereleases, func(unstable string) bool {
-		return strings.Contains(version, unstable)
-	})
-}
-
-// filterPreReleasesIfStable returns a function that filters out
-// pre-release tags if the current version is stable.
-// If the current version is a pre-release, it does not filter anything.
-// versionFunc is a function that returns the current version string, it is
-// a func for testability.
-func filterPreReleasesIfStable(versionFunc func() string) func(string) bool {
-	return func(tag string) bool {
-		version := versionFunc()
-
-		// If we are on a pre-release version, then we do not filter anything
-		// as we want to recommend the user the latest pre-release.
-		if isPreReleaseVersion(version) {
-			return false
-		}
-
-		// If we are on a stable release, filter out pre-releases.
-		return isPreReleaseVersion(tag)
-	}
-}
-
 var rootCmd = &cobra.Command{
 	Use:   "headscale",
 	Short: "headscale - a Tailscale control server",
@@ -128,15 +93,11 @@ 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() {
-	cmd, err := rootCmd.ExecuteC()
-	if err != nil {
-		outputFormat, _ := cmd.Flags().GetString("output")
-		printError(err, outputFormat)
+	if err := rootCmd.Execute(); err != nil {
+		fmt.Fprintln(os.Stderr, err)
 		os.Exit(1)
 	}
 }
@@ -1,308 +0,0 @@
-package cli
-
-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
-		currentVersion string
-		tag            string
-		expectedFilter bool
-		description    string
-	}{
-		{
-			name:           "stable version filters alpha tag",
-			currentVersion: v23,
-			tag:            v24Alpha1Tag,
-			expectedFilter: true,
-			description:    "When on stable release, alpha tags should be filtered",
-		},
-		{
-			name:           "stable version filters beta tag",
-			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: v23,
-			tag:            v24RCTag,
-			expectedFilter: true,
-			description:    "When on stable release, rc tags should be filtered",
-		},
-		{
-			name:           "stable version allows stable tag",
-			currentVersion: v23,
-			tag:            v24Tag,
-			expectedFilter: false,
-			description:    "When on stable release, stable tags should not be filtered",
-		},
-		{
-			name:           "alpha version allows alpha tag",
-			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: 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: v23Alpha1,
-			tag:            v24RCTag,
-			expectedFilter: false,
-			description:    "When on alpha release, rc tags should not be filtered",
-		},
-		{
-			name:           "alpha version allows stable tag",
-			currentVersion: v23Alpha1,
-			tag:            v24Tag,
-			expectedFilter: false,
-			description:    "When on alpha release, stable tags should not be filtered",
-		},
-		{
-			name:           "beta version allows alpha tag",
-			currentVersion: v23Beta1,
-			tag:            v24Alpha1Tag,
-			expectedFilter: false,
-			description:    "When on beta release, alpha tags should not be filtered",
-		},
-		{
-			name:           "beta version allows beta tag",
-			currentVersion: "0.23.0-beta.2",
-			tag:            "v0.24.0-beta.3",
-			expectedFilter: false,
-			description:    "When on beta release, beta tags should not be filtered",
-		},
-		{
-			name:           "beta version allows rc tag",
-			currentVersion: v23Beta1,
-			tag:            v24RCTag,
-			expectedFilter: false,
-			description:    "When on beta release, rc tags should not be filtered",
-		},
-		{
-			name:           "beta version allows stable tag",
-			currentVersion: v23Beta1,
-			tag:            v24Tag,
-			expectedFilter: false,
-			description:    "When on beta release, stable tags should not be filtered",
-		},
-		{
-			name:           "rc version allows alpha tag",
-			currentVersion: v23RC1,
-			tag:            v24Alpha1Tag,
-			expectedFilter: false,
-			description:    "When on rc release, alpha tags should not be filtered",
-		},
-		{
-			name:           "rc version allows beta tag",
-			currentVersion: v23RC1,
-			tag:            "v0.24.0-beta.1",
-			expectedFilter: false,
-			description:    "When on rc release, beta tags should not be filtered",
-		},
-		{
-			name:           "rc version allows rc tag",
-			currentVersion: "0.23.0-rc.2",
-			tag:            "v0.24.0-rc.3",
-			expectedFilter: false,
-			description:    "When on rc release, rc tags should not be filtered",
-		},
-		{
-			name:           "rc version allows stable tag",
-			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: v231,
-			tag:            v24Alpha1Tag,
-			expectedFilter: true,
-			description:    "Stable version with patch number should filter alpha tags",
-		},
-		{
-			name:           "stable version with patch allows stable",
-			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: 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: 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: 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: v23,
-			tag:            "",
-			expectedFilter: false,
-			description:    "Empty tags should not be filtered",
-		},
-		{
-			name:           "dev version allows all tags",
-			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: 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: 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: v23Dev,
-			tag:            v24Tag,
-			expectedFilter: false,
-			description:    "When on dev release, stable tags should not be filtered",
-		},
-	}
-
-	for _, tt := range tests {
-		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",
-					tt.name,
-					result,
-					tt.expectedFilter,
-					tt.description,
-					tt.currentVersion,
-					tt.tag,
-				)
-			}
-		})
-	}
-}
-
-func TestIsPreReleaseVersion(t *testing.T) {
-	tests := []struct {
-		name        string
-		version     string
-		expected    bool
-		description string
-	}{
-		{
-			name:        "stable version",
-			version:     v23,
-			expected:    false,
-			description: "Stable version should not be pre-release",
-		},
-		{
-			name:        "alpha version",
-			version:     v23Alpha1,
-			expected:    true,
-			description: "Alpha version should be pre-release",
-		},
-		{
-			name:        "beta version",
-			version:     v23Beta1,
-			expected:    true,
-			description: "Beta version should be pre-release",
-		},
-		{
-			name:        "rc version",
-			version:     v23RC1,
-			expected:    true,
-			description: "RC version should be pre-release",
-		},
-		{
-			name:        "version with alpha substring",
-			version:     "0.23.0-alphabetical",
-			expected:    true,
-			description: "Version containing 'alpha' should be pre-release",
-		},
-		{
-			name:        "version with beta substring",
-			version:     "0.23.0-betamax",
-			expected:    true,
-			description: "Version containing 'beta' should be pre-release",
-		},
-		{
-			name:        "dev version",
-			version:     v23Dev,
-			expected:    true,
-			description: "Dev version should be pre-release",
-		},
-		{
-			name:        "empty version",
-			version:     "",
-			expected:    false,
-			description: "Empty version should not be pre-release",
-		},
-		{
-			name:        "version with patch number",
-			version:     v231,
-			expected:    false,
-			description: "Stable version with patch should not be pre-release",
-		},
-	}
-
-	for _, tt := range tests {
-		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",
-					tt.name,
-					result,
-					tt.expected,
-					tt.description,
-					tt.version,
-				)
-			}
-		})
-	}
-}
@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"net/http"

+	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
 	"github.com/tailscale/squibble"
 )
@@ -16,22 +17,24 @@ func init() {
 var serveCmd = &cobra.Command{
 	Use:   "serve",
 	Short: "Launches the headscale server",
-	RunE: func(cmd *cobra.Command, args []string) error {
+	Args: func(cmd *cobra.Command, args []string) error {
+		return nil
+	},
+	Run: func(cmd *cobra.Command, args []string) {
 		app, err := newHeadscaleServerWithConfig()
 		if err != nil {
-			if squibbleErr, ok := errors.AsType[squibble.ValidationError](err); ok {
+			var squibbleErr squibble.ValidationError
+			if errors.As(err, &squibbleErr) {
 				fmt.Printf("SQLite schema failed to validate:\n")
 				fmt.Println(squibbleErr.Diff)
 			}

-			return fmt.Errorf("initializing: %w", err)
+			log.Fatal().Caller().Err(err).Msg("Error initializing")
 		}

 		err = app.Serve()
 		if err != nil && !errors.Is(err, http.ErrServerClosed) {
-			return fmt.Errorf("headscale ran into an error and had to shut down: %w", err)
+			log.Fatal().Caller().Err(err).Msg("Headscale ran into an error and had to shut down.")
 		}
-
-		return nil
 	},
 }
@@ -0,0 +1,70 @@
+package cli
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestServeCommand(t *testing.T) {
+	// Test that the serve command exists and is properly configured
+	assert.NotNil(t, serveCmd)
+	assert.Equal(t, "serve", serveCmd.Use)
+	assert.Equal(t, "Launches the headscale server", serveCmd.Short)
+	assert.NotNil(t, serveCmd.Run)
+	assert.NotNil(t, serveCmd.Args)
+}
+
+func TestServeCommandInRootCommand(t *testing.T) {
+	// Test that serve is available as a subcommand of root
+	cmd, _, err := rootCmd.Find([]string{"serve"})
+	require.NoError(t, err)
+	assert.Equal(t, "serve", cmd.Name())
+	assert.Equal(t, serveCmd, cmd)
+}
+
+func TestServeCommandArgs(t *testing.T) {
+	// Test that the Args function is defined and accepts any arguments
+	// The current implementation always returns nil (accepts any args)
+	assert.NotNil(t, serveCmd.Args)
+
+	// Test the args function directly
+	err := serveCmd.Args(serveCmd, []string{})
+	assert.NoError(t, err, "Args function should accept empty arguments")
+
+	err = serveCmd.Args(serveCmd, []string{"extra", "args"})
+	assert.NoError(t, err, "Args function should accept extra arguments")
+}
+
+func TestServeCommandHelp(t *testing.T) {
+	// Test that the command has proper help text
+	assert.NotEmpty(t, serveCmd.Short)
+	assert.Contains(t, serveCmd.Short, "server")
+	assert.Contains(t, serveCmd.Short, "headscale")
+}
+
+func TestServeCommandStructure(t *testing.T) {
+	// Test basic command structure
+	assert.Equal(t, "serve", serveCmd.Name())
+	assert.Equal(t, "Launches the headscale server", serveCmd.Short)
+
+	// Test that it has no subcommands (it's a leaf command)
+	subcommands := serveCmd.Commands()
+	assert.Empty(t, subcommands, "Serve command should not have subcommands")
+}
+
+// Note: We can't easily test the actual execution of serve because:
+// 1. It depends on configuration files being present and valid
+// 2. It calls log.Fatal() which would exit the test process
+// 3. It tries to start an actual HTTP server which would block forever
+// 4. It requires database connections and other infrastructure
+//
+// In a real refactor, we would:
+// 1. Extract server initialization logic to a testable function
+// 2. Use dependency injection for configuration and dependencies
+// 3. Return errors instead of calling log.Fatal()
+// 4. Add graceful shutdown capabilities for testing
+// 5. Allow server startup to be cancelled via context
+//
+// For now, we test the command structure and basic properties.
@@ -1,23 +0,0 @@
-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"
-)
@@ -0,0 +1,55 @@
+package cli
+
+import (
+	"strings"
+
+	"github.com/pterm/pterm"
+	"github.com/spf13/cobra"
+)
+
+const (
+	HeadscaleDateTimeFormat = "2006-01-02 15:04:05"
+	DefaultAPIKeyExpiry     = "90d"
+	DefaultPreAuthKeyExpiry = "1h"
+)
+
+// FilterTableColumns filters table columns based on --columns flag
+func FilterTableColumns(cmd *cobra.Command, tableData pterm.TableData) pterm.TableData {
+	columns, _ := cmd.Flags().GetString("columns")
+	if columns == "" || len(tableData) == 0 {
+		return tableData
+	}
+
+	headers := tableData[0]
+	wantedColumns := strings.Split(columns, ",")
+
+	// Find column indices
+	var indices []int
+	for _, wanted := range wantedColumns {
+		wanted = strings.TrimSpace(wanted)
+		for i, header := range headers {
+			if strings.EqualFold(header, wanted) {
+				indices = append(indices, i)
+				break
+			}
+		}
+	}
+
+	if len(indices) == 0 {
+		return tableData
+	}
+
+	// Filter all rows
+	filtered := make(pterm.TableData, len(tableData))
+	for i, row := range tableData {
+		newRow := make([]string, len(indices))
+		for j, idx := range indices {
+			if idx < len(row) {
+				newRow[j] = row[idx]
+			}
+		}
+		filtered[i] = newRow
+	}
+
+	return filtered
+}
@@ -4,81 +4,36 @@ import (
 	"context"
 	"errors"
 	"fmt"
-	"net/http"
 	"net/url"
 	"strconv"
+	"strings"

-	clientv1 "github.com/juanfont/headscale/gen/client/v1"
-	"github.com/juanfont/headscale/hscontrol/util"
-	"github.com/juanfont/headscale/hscontrol/util/zlog/zf"
+	survey "github.com/AlecAivazis/survey/v2"
+	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	"github.com/pterm/pterm"
 	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
-)
-
-// CLI user errors.
-var (
-	errFlagRequired       = errors.New("--name or --identifier flag is required")
-	errMultipleUsersMatch = errors.New("multiple users match query, specify an ID")
+	"google.golang.org/grpc/status"
 )

 func usernameAndIDFlag(cmd *cobra.Command) {
-	cmd.Flags().Int64P("identifier", "i", -1, "User identifier (ID)")
+	cmd.Flags().StringP("user", "u", "", "User identifier (ID, name, or email)")
 	cmd.Flags().StringP("name", "n", "", "Username")
 }

-// usernameAndIDFromFlag returns the username and ID from the flags of the command.
-func usernameAndIDFromFlag(cmd *cobra.Command) (uint64, string, error) {
-	username, _ := cmd.Flags().GetString("name")
-
-	identifier, _ := cmd.Flags().GetInt64("identifier")
-	if username == "" && identifier < 0 {
-		return 0, "", errFlagRequired
-	}
-
-	// 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)
+// userIDFromFlag returns the user ID using smart lookup.
+// If no user is specified, it will exit the program with an error.
+func userIDFromFlag(cmd *cobra.Command) uint64 {
+	userID, err := GetUserIdentifier(cmd)
 	if err != nil {
-		return 0, nil, err
+		ErrorOutput(
+			err,
+			"Cannot identify user: "+err.Error(),
+			GetOutputFlag(cmd),
+		)
 	}

-	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
+	return userID
 }

 func init() {
@@ -88,26 +43,32 @@ func init() {
 	createUserCmd.Flags().StringP("email", "e", "", "Email")
 	createUserCmd.Flags().StringP("picture-url", "p", "", "Profile picture URL")
 	userCmd.AddCommand(listUsersCmd)
-	usernameAndIDFlag(listUsersCmd)
-	listUsersCmd.Flags().StringP("email", "e", "", "Email")
+	// Smart lookup filters - can be used individually or combined
+	listUsersCmd.Flags().StringP("user", "u", "", "Filter by user (ID, name, or email)")
+	listUsersCmd.Flags().Uint64P("id", "", 0, "Filter by user ID")
+	listUsersCmd.Flags().StringP("name", "n", "", "Filter by username")
+	listUsersCmd.Flags().StringP("email", "e", "", "Filter by email address")
+	listUsersCmd.Flags().String("columns", "", "Comma-separated list of columns to display (ID,Name,Username,Email,Created)")
 	userCmd.AddCommand(destroyUserCmd)
 	usernameAndIDFlag(destroyUserCmd)
 	userCmd.AddCommand(renameUserCmd)
 	usernameAndIDFlag(renameUserCmd)
 	renameUserCmd.Flags().StringP("new-name", "r", "", "New username")
-	mustMarkRequired(renameUserCmd, "new-name")
+	renameUserCmd.MarkFlagRequired("new-name")
 }

+var errMissingParameter = errors.New("missing parameters")
+
 var userCmd = &cobra.Command{
 	Use:     "users",
 	Short:   "Manage the users of Headscale",
-	Aliases: []string{"user"},
+	Aliases: []string{"user", "namespace", "namespaces", "ns"},
 }

 var createUserCmd = &cobra.Command{
 	Use:     "create NAME",
 	Short:   "Creates a new user",
-	Aliases: []string{"c", cmdNew},
+	Aliases: []string{"c", "new"},
 	Args: func(cmd *cobra.Command, args []string) error {
 		if len(args) < 1 {
 			return errMissingParameter
@@ -115,148 +76,273 @@ var createUserCmd = &cobra.Command{

 		return nil
 	},
-	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
+	Run: func(cmd *cobra.Command, args []string) {
+		output := GetOutputFlag(cmd)
 		userName := args[0]

-		log.Trace().Interface(zf.Client, client).Msg("obtained API client")
-
-		request := clientv1.CreateUserJSONRequestBody{Name: &userName}
+		request := &v1.CreateUserRequest{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 { //nolint:noinlineerr
-				return fmt.Errorf("invalid picture URL: %w", err)
+			if _, err := url.Parse(pictureURL); err != nil {
+				ErrorOutput(
+					err,
+					fmt.Sprintf(
+						"Invalid Picture URL: %s",
+						err,
+					),
+					output,
+				)
+				return
+			}
+			request.PictureUrl = pictureURL
+		}
+
+		err := WithClient(func(ctx context.Context, client v1.HeadscaleServiceClient) error {
+			log.Trace().Interface("client", client).Msg("Obtained gRPC client")
+			log.Trace().Interface("request", request).Msg("Sending CreateUser request")
+
+			response, err := client.CreateUser(ctx, request)
+			if err != nil {
+				ErrorOutput(
+					err,
+					"Cannot create user: "+status.Convert(err).Message(),
+					output,
+				)
+				return err
 			}

-			request.PictureUrl = &pictureURL
-		}
-
-		log.Trace().Interface(zf.Request, request).Msg("sending CreateUser request")
-
-		resp, err := client.CreateUserWithResponse(ctx, request)
+			SuccessOutput(response.GetUser(), "User created", output)
+			return nil
+		})
 		if err != nil {
-			return fmt.Errorf("creating user: %w", err)
+			return
 		}
-
-		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",
+	Use:     "destroy --user USER",
 	Short:   "Destroys a user",
-	Aliases: []string{cmdDelete},
-	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
-		_, user, err := resolveSingleUser(ctx, client, cmd)
+	Aliases: []string{"delete"},
+	Run: func(cmd *cobra.Command, args []string) {
+		output := GetOutputFlag(cmd)
+
+		id := userIDFromFlag(cmd)
+		request := &v1.ListUsersRequest{
+			Id: id,
+		}
+
+		var user *v1.User
+		err := WithClient(func(ctx context.Context, client v1.HeadscaleServiceClient) error {
+			users, err := client.ListUsers(ctx, request)
+			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,
+				)
+				return err
+			}
+
+			user = users.GetUsers()[0]
+			return nil
+		})
 		if err != nil {
-			return err
+			return
 		}

-		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")
+		confirm := false
+		force, _ := cmd.Flags().GetBool("force")
+		if !force {
+			prompt := &survey.Confirm{
+				Message: fmt.Sprintf(
+					"Do you want to remove the user %q (%d) and any associated preauthkeys?",
+					user.GetName(), user.GetId(),
+				),
+			}
+			err := survey.AskOne(prompt, &confirm)
+			if err != nil {
+				return
+			}
 		}

-		resp, err := client.DeleteUserWithResponse(ctx, user.Id)
-		if err != nil {
-			return fmt.Errorf("destroying user: %w", err)
-		}
+		if confirm || force {
+			err = WithClient(func(ctx context.Context, client v1.HeadscaleServiceClient) error {
+				request := &v1.DeleteUserRequest{Id: user.GetId()}

-		if resp.StatusCode() != http.StatusOK {
-			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
+				response, err := client.DeleteUser(ctx, request)
+				if err != nil {
+					ErrorOutput(
+						err,
+						"Cannot destroy user: "+status.Convert(err).Message(),
+						output,
+					)
+					return err
+				}
+				SuccessOutput(response, "User destroyed", output)
+				return nil
+			})
+			if err != nil {
+				return
+			}
+		} else {
+			SuccessOutput(map[string]string{"Result": "User not destroyed"}, "User not destroyed", output)
 		}
-
-		return printOutput(cmd, resp.JSON200, "User destroyed")
-	}),
+	},
 }

 var listUsersCmd = &cobra.Command{
-	Use:     cmdList,
+	Use:     "list",
 	Short:   "List all the users",
-	Aliases: []string{"ls", cmdShow},
-	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
-		params := &clientv1.ListUsersParams{}
+	Aliases: []string{"ls", "show"},
+	Run: func(cmd *cobra.Command, args []string) {
+		output := GetOutputFlag(cmd)

-		id, _ := cmd.Flags().GetInt64("identifier")
-		username, _ := cmd.Flags().GetString("name")
-		email, _ := cmd.Flags().GetString("email")
+		err := WithClient(func(ctx context.Context, client v1.HeadscaleServiceClient) error {
+			request := &v1.ListUsersRequest{}

-		// filter by one param at most
-		switch {
-		case id > 0:
-			idStr := strconv.FormatInt(id, util.Base10)
-			params.Id = &idStr
-		case username != "":
-			params.Name = &username
-		case email != "":
-			params.Email = &email
-		}
+			// Check for smart lookup flag first
+			userFlag, _ := cmd.Flags().GetString("user")
+			if userFlag != "" {
+				// Use smart lookup to determine filter type
+				if id, err := strconv.ParseUint(userFlag, 10, 64); err == nil && id > 0 {
+					request.Id = id
+				} else if strings.Contains(userFlag, "@") {
+					request.Email = userFlag
+				} else {
+					request.Name = userFlag
+				}
+			} else {
+				// Check specific filter flags
+				if id, _ := cmd.Flags().GetUint64("id"); id > 0 {
+					request.Id = id
+				} else if name, _ := cmd.Flags().GetString("name"); name != "" {
+					request.Name = name
+				} else if email, _ := cmd.Flags().GetString("email"); email != "" {
+					request.Email = email
+				}
+			}

-		resp, err := client.ListUsersWithResponse(ctx, params)
-		if err != nil {
-			return fmt.Errorf("listing users: %w", err)
-		}
+			response, err := client.ListUsers(ctx, request)
+			if err != nil {
+				ErrorOutput(
+					err,
+					"Cannot get users: "+status.Convert(err).Message(),
+					output,
+				)
+				return err
+			}

-		if resp.StatusCode() != http.StatusOK {
-			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
-		}
+			if output != "" {
+				SuccessOutput(response.GetUsers(), "", output)
+				return nil
+			}

-		users := resp.JSON200.Users
-
-		return printListOutput(cmd, users, func() error {
-			rows := make([][]string, 0, len(users))
-			for _, user := range users {
-				rows = append(
-					rows,
+			tableData := pterm.TableData{{"ID", "Name", "Username", "Email", "Created"}}
+			for _, user := range response.GetUsers() {
+				tableData = append(
+					tableData,
 					[]string{
-						user.Id,
-						user.DisplayName,
-						user.Name,
-						user.Email,
-						user.CreatedAt.Format(HeadscaleDateTimeFormat),
+						strconv.FormatUint(user.GetId(), 10),
+						user.GetDisplayName(),
+						user.GetName(),
+						user.GetEmail(),
+						user.GetCreatedAt().AsTime().Format(HeadscaleDateTimeFormat),
 					},
 				)
 			}
-
-			return renderTable([]string{"ID", "Name", "Username", "Email", colCreated}, rows)
+			tableData = FilterTableColumns(cmd, tableData)
+			err = pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
+			if err != nil {
+				ErrorOutput(
+					err,
+					fmt.Sprintf("Failed to render pterm table: %s", err),
+					output,
+				)
+				return err
+			}
+			return nil
 		})
-	}),
+		if err != nil {
+			// Error already handled in closure
+			return
+		}
+	},
 }

 var renameUserCmd = &cobra.Command{
 	Use:     "rename",
 	Short:   "Renames a user",
 	Aliases: []string{"mv"},
-	RunE: clientRunE(func(ctx context.Context, client *clientv1.ClientWithResponses, cmd *cobra.Command, args []string) error {
-		id, _, err := resolveSingleUser(ctx, client, cmd)
-		if err != nil {
-			return err
-		}
+	Run: func(cmd *cobra.Command, args []string) {
+		output := GetOutputFlag(cmd)

+		id := userIDFromFlag(cmd)
 		newName, _ := cmd.Flags().GetString("new-name")

-		resp, err := client.RenameUserWithResponse(ctx, strconv.FormatUint(id, util.Base10), newName)
+		err := WithClient(func(ctx context.Context, client v1.HeadscaleServiceClient) error {
+			listReq := &v1.ListUsersRequest{
+				Id: id,
+			}
+
+			users, err := client.ListUsers(ctx, listReq)
+			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,
+				)
+				return err
+			}
+
+			renameReq := &v1.RenameUserRequest{
+				OldId:   id,
+				NewName: newName,
+			}
+
+			response, err := client.RenameUser(ctx, renameReq)
+			if err != nil {
+				ErrorOutput(
+					err,
+					"Cannot rename user: "+status.Convert(err).Message(),
+					output,
+				)
+				return err
+			}
+
+			SuccessOutput(response.GetUser(), "User renamed", output)
+			return nil
+		})
 		if err != nil {
-			return fmt.Errorf("renaming user: %w", err)
+			return
 		}
-
-		if resp.StatusCode() != http.StatusOK {
-			return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
-		}
-
-		return printOutput(cmd, resp.JSON200.User, "User renamed")
-	}),
+	},
 }
@@ -4,88 +4,24 @@ import (
 	"context"
 	"crypto/tls"
 	"encoding/json"
-	"errors"
 	"fmt"
 	"net"
-	"net/http"
 	"os"
-	"slices"
+	"strconv"
 	"strings"
-	"time"

-	"github.com/cenkalti/backoff/v5"
-	clientv1 "github.com/juanfont/headscale/gen/client/v1"
+	v1 "github.com/juanfont/headscale/gen/go/headscale/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"
 	"github.com/spf13/cobra"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/credentials"
+	"google.golang.org/grpc/credentials/insecure"
 	"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 {
@@ -103,47 +39,14 @@ func newHeadscaleServerWithConfig() (*hscontrol.Headscale, error) {
 	return app, nil
 }

-// 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) {
+func newHeadscaleCLIWithConfig() (context.Context, v1.HeadscaleServiceClient, *grpc.ClientConn, context.CancelFunc) {
 	cfg, err := types.LoadCLIConfig()
 	if err != nil {
-		return nil, nil, nil, fmt.Errorf("loading configuration: %w", err)
+		log.Fatal().
+			Err(err).
+			Caller().
+			Msgf("Failed to load configuration")
+		os.Exit(-1) // we get here if logging is suppressed (i.e., json output)
 	}

 	log.Debug().
@@ -152,249 +55,296 @@ func newHeadscaleCLIWithConfig() (context.Context, *clientv1.ClientWithResponses

 	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.")

-		client, err := newSocketClient(cfg.UnixSocket)
+		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, 0o666) // nolint
 		if err != nil {
-			cancel()
-
-			return nil, nil, nil, err
+			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()

-		log.Trace().Caller().Str(zf.Address, cfg.UnixSocket).Msg("connecting via unix socket")
+		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.")
+		}
+		grpcOptions = append(grpcOptions,
+			grpc.WithPerRPCCredentials(tokenAuth{
+				token: apiKey,
+			}),
+		)

-		return ctx, client, cancel, nil
-	}
+		if cfg.CLI.Insecure {
+			tlsConfig := &tls.Config{
+				// turn of gosec as we are intentionally setting
+				// insecure.
+				//nolint:gosec
+				InsecureSkipVerify: true,
+			}

-	// 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 {
-		cancel()
-
-		return nil, nil, nil, err
-	}
-
-	log.Trace().Caller().Str(zf.Address, address).Msg("connecting via HTTPS")
-
-	return ctx, client, cancel, nil
-}
-
-// 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,
+			grpcOptions = append(grpcOptions,
+				grpc.WithTransportCredentials(credentials.NewTLS(tlsConfig)),
+			)
+		} else {
+			grpcOptions = append(grpcOptions,
+				grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(nil, "")),
 			)
 		}
-	} else {
-		socket.Close()
 	}

-	httpClient := &http.Client{
-		Transport: &http.Transport{
-			DialContext: func(ctx context.Context, _, _ string) (net.Conn, error) {
-				return dialHeadscaleSocket(ctx, socketPath)
-			},
-		},
+	log.Trace().Caller().Str("address", address).Msg("Connecting via gRPC")
+	conn, err := grpc.DialContext(ctx, address, grpcOptions...)
+	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)
 	}

-	return clientv1.NewClientWithResponses(
-		"http://local",
-		clientv1.WithHTTPClient(httpClient),
-	)
+	client := v1.NewHeadscaleServiceClient(conn)
+
+	return ctx, client, conn, cancel
 }

-// 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) {
+func output(result interface{}, override string, outputFormat string) string {
+	var jsonBytes []byte
+	var err error
 	switch outputFormat {
-	case outputFormatJSON:
-		b, err := json.MarshalIndent(result, "", "\t")
+	case "json":
+		jsonBytes, err = json.MarshalIndent(result, "", "\t")
 		if err != nil {
-			return "", fmt.Errorf("marshalling JSON output: %w", err)
+			log.Fatal().Err(err).Msg("failed to unmarshal output")
 		}
-
-		return string(b), nil
-	case outputFormatJSONLine:
-		b, err := json.Marshal(result)
+	case "json-line":
+		jsonBytes, err = json.Marshal(result)
 		if err != nil {
-			return "", fmt.Errorf("marshalling JSON-line output: %w", err)
+			log.Fatal().Err(err).Msg("failed to unmarshal output")
 		}
-
-		return string(b), nil
-	case outputFormatYAML:
-		b, err := yaml.Marshal(result)
+	case "yaml":
+		jsonBytes, err = yaml.Marshal(result)
 		if err != nil {
-			return "", fmt.Errorf("marshalling YAML output: %w", err)
+			log.Fatal().Err(err).Msg("failed to unmarshal output")
 		}
-
-		return string(b), nil
 	default:
-		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
+		// nolint
+		return override
 	}

-	fmt.Println(out)
-
-	return nil
+	return string(jsonBytes)
 }

-// 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
+// SuccessOutput prints the result to stdout and exits with status code 0.
+func SuccessOutput(result interface{}, override string, outputFormat string) {
+	fmt.Println(output(result, override, outputFormat))
+	os.Exit(0)
 }

-// 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) {
+// ErrorOutput prints an error message to stderr and exits with status code 1.
+func ErrorOutput(errResult error, override string, outputFormat string) {
 	type errOutput struct {
 		Error string `json:"error"`
 	}

-	if outputFormat == "" {
-		fmt.Fprintf(os.Stderr, "Error: %s\n", err)
+	fmt.Fprintf(os.Stderr, "%s\n", output(errOutput{errResult.Error()}, override, outputFormat))
+	os.Exit(1)
+}

-		return
+func HasMachineOutputFlag() bool {
+	for _, arg := range os.Args {
+		if arg == "json" || arg == "json-line" || arg == "yaml" {
+			return true
+		}
 	}

-	// formatOutput cannot fail here: errOutput is a single string field.
-	out, _ := formatOutput(errOutput{Error: err.Error()}, "", outputFormat)
-	fmt.Fprintf(os.Stderr, "%s\n", out)
+	return false
 }

-func hasMachineOutputFlag() bool {
-	return slices.ContainsFunc(os.Args, func(arg string) bool {
-		return arg == outputFormatJSON || arg == outputFormatJSONLine || arg == outputFormatYAML
-	})
+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
+}
+
+// GetOutputFlag returns the output flag value (never fails)
+func GetOutputFlag(cmd *cobra.Command) string {
+	output, _ := cmd.Flags().GetString("output")
+	return output
+}
+
+
+// GetNodeIdentifier returns the node ID using smart lookup via gRPC ListNodes call
+func GetNodeIdentifier(cmd *cobra.Command) (uint64, error) {
+	nodeFlag, _ := cmd.Flags().GetString("node")
+
+	// Use --node flag
+	if nodeFlag == "" {
+		return 0, fmt.Errorf("--node flag is required")
+	}
+
+	// Use smart lookup via gRPC
+	return lookupNodeBySpecifier(nodeFlag)
+}
+
+// lookupNodeBySpecifier performs smart lookup of a node by ID, name, hostname, or IP
+func lookupNodeBySpecifier(specifier string) (uint64, error) {
+	var nodeID uint64
+
+	err := WithClient(func(ctx context.Context, client v1.HeadscaleServiceClient) error {
+		request := &v1.ListNodesRequest{}
+
+		// Detect what type of specifier this is and set appropriate filter
+		if id, err := strconv.ParseUint(specifier, 10, 64); err == nil && id > 0 {
+			// Looks like a numeric ID
+			request.Id = id
+		} else if isIPAddress(specifier) {
+			// Looks like an IP address
+			request.IpAddresses = []string{specifier}
+		} else {
+			// Treat as hostname/name
+			request.Name = specifier
+		}
+
+		response, err := client.ListNodes(ctx, request)
+		if err != nil {
+			return fmt.Errorf("failed to lookup node: %w", err)
+		}
+
+		nodes := response.GetNodes()
+		if len(nodes) == 0 {
+			return fmt.Errorf("node not found")
+		}
+
+		if len(nodes) > 1 {
+			var nodeInfo []string
+			for _, node := range nodes {
+				nodeInfo = append(nodeInfo, fmt.Sprintf("ID=%d name=%s", node.GetId(), node.GetName()))
+			}
+			return fmt.Errorf("multiple nodes found matching '%s': %s", specifier, strings.Join(nodeInfo, ", "))
+		}
+
+		// Exactly one match - this is what we want
+		nodeID = nodes[0].GetId()
+		return nil
+	})
+	if err != nil {
+		return 0, err
+	}
+
+	return nodeID, nil
+}
+
+// isIPAddress checks if a string looks like an IP address
+func isIPAddress(s string) bool {
+	// Try parsing as IP address (both IPv4 and IPv6)
+	if net.ParseIP(s) != nil {
+		return true
+	}
+	// Try parsing as CIDR
+	if _, _, err := net.ParseCIDR(s); err == nil {
+		return true
+	}
+	return false
+}
+
+// GetUserIdentifier returns the user ID using smart lookup via gRPC ListUsers call
+func GetUserIdentifier(cmd *cobra.Command) (uint64, error) {
+	userFlag, _ := cmd.Flags().GetString("user")
+	nameFlag, _ := cmd.Flags().GetString("name")
+
+	var specifier string
+
+	// Determine which flag was used (prefer --user, fall back to legacy flags)
+	if userFlag != "" {
+		specifier = userFlag
+	} else if nameFlag != "" {
+		specifier = nameFlag
+	} else {
+		return 0, fmt.Errorf("--user flag is required")
+	}
+
+	// Use smart lookup via gRPC
+	return lookupUserBySpecifier(specifier)
+}
+
+// lookupUserBySpecifier performs smart lookup of a user by ID, name, or email
+func lookupUserBySpecifier(specifier string) (uint64, error) {
+	var userID uint64
+
+	err := WithClient(func(ctx context.Context, client v1.HeadscaleServiceClient) error {
+		request := &v1.ListUsersRequest{}
+
+		// Detect what type of specifier this is and set appropriate filter
+		if id, err := strconv.ParseUint(specifier, 10, 64); err == nil && id > 0 {
+			// Looks like a numeric ID
+			request.Id = id
+		} else if strings.Contains(specifier, "@") {
+			// Looks like an email address
+			request.Email = specifier
+		} else {
+			// Treat as username
+			request.Name = specifier
+		}
+
+		response, err := client.ListUsers(ctx, request)
+		if err != nil {
+			return fmt.Errorf("failed to lookup user: %w", err)
+		}
+
+		users := response.GetUsers()
+		if len(users) == 0 {
+			return fmt.Errorf("user not found")
+		}
+
+		if len(users) > 1 {
+			var userInfo []string
+			for _, user := range users {
+				userInfo = append(userInfo, fmt.Sprintf("ID=%d name=%s email=%s", user.GetId(), user.GetName(), user.GetEmail()))
+			}
+			return fmt.Errorf("multiple users found matching '%s': %s", specifier, strings.Join(userInfo, ", "))
+		}
+
+		// Exactly one match - this is what we want
+		userID = users[0].GetId()
+		return nil
+	})
+	if err != nil {
+		return 0, err
+	}
+
+	return userID, nil
 }
@@ -1,72 +0,0 @@
-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")
-}
@@ -1,35 +1,175 @@
 package cli

-import "testing"
+import (
+	"os"
+	"testing"

-func TestClientBaseURL(t *testing.T) {
+	"github.com/stretchr/testify/assert"
+)
+
+func TestHasMachineOutputFlag(t *testing.T) {
 	tests := []struct {
-		name    string
-		address string
-		want    string
+		name     string
+		args     []string
+		expected bool
 	}{
 		{
-			name:    "bare host defaults to https",
-			address: "headscale.example.com:50443",
-			want:    "https://headscale.example.com:50443",
+			name:     "no machine output flags",
+			args:     []string{"headscale", "users", "list"},
+			expected: false,
 		},
 		{
-			name:    "explicit https scheme is kept",
-			address: "https://headscale.example.com",
-			want:    "https://headscale.example.com",
+			name:     "json flag present",
+			args:     []string{"headscale", "users", "list", "json"},
+			expected: true,
 		},
 		{
-			name:    "explicit http scheme is kept",
-			address: "http://localhost:8080",
-			want:    "http://localhost:8080",
+			name:     "json-line flag present",
+			args:     []string{"headscale", "nodes", "list", "json-line"},
+			expected: true,
+		},
+		{
+			name:     "yaml flag present",
+			args:     []string{"headscale", "apikeys", "list", "yaml"},
+			expected: true,
+		},
+		{
+			name:     "mixed flags with json",
+			args:     []string{"headscale", "--config", "/tmp/config.yaml", "users", "list", "json"},
+			expected: true,
+		},
+		{
+			name:     "flag as part of longer argument",
+			args:     []string{"headscale", "users", "create", "json-user@example.com"},
+			expected: false,
 		},
 	}

 	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)
-			}
+			// Save original os.Args
+			originalArgs := os.Args
+			defer func() { os.Args = originalArgs }()
+
+			// Set os.Args to test case
+			os.Args = tt.args
+
+			result := HasMachineOutputFlag()
+			assert.Equal(t, tt.expected, result)
 		})
 	}
 }
+
+func TestOutput(t *testing.T) {
+	tests := []struct {
+		name         string
+		result       interface{}
+		override     string
+		outputFormat string
+		expected     string
+	}{
+		{
+			name:         "default format returns override",
+			result:       map[string]string{"test": "value"},
+			override:     "Human readable output",
+			outputFormat: "",
+			expected:     "Human readable output",
+		},
+		{
+			name:         "default format with empty override",
+			result:       map[string]string{"test": "value"},
+			override:     "",
+			outputFormat: "",
+			expected:     "",
+		},
+		{
+			name:         "json format",
+			result:       map[string]string{"name": "test", "id": "123"},
+			override:     "Human readable",
+			outputFormat: "json",
+			expected:     "{\n\t\"id\": \"123\",\n\t\"name\": \"test\"\n}",
+		},
+		{
+			name:         "json-line format",
+			result:       map[string]string{"name": "test", "id": "123"},
+			override:     "Human readable",
+			outputFormat: "json-line",
+			expected:     "{\"id\":\"123\",\"name\":\"test\"}",
+		},
+		{
+			name:         "yaml format",
+			result:       map[string]string{"name": "test", "id": "123"},
+			override:     "Human readable",
+			outputFormat: "yaml",
+			expected:     "id: \"123\"\nname: test\n",
+		},
+		{
+			name:         "invalid format returns override",
+			result:       map[string]string{"test": "value"},
+			override:     "Human readable output",
+			outputFormat: "invalid",
+			expected:     "Human readable output",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := output(tt.result, tt.override, tt.outputFormat)
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}
+
+func TestOutputWithComplexData(t *testing.T) {
+	// Test with more complex data structures
+	complexData := struct {
+		Users []struct {
+			Name string `json:"name" yaml:"name"`
+			ID   int    `json:"id" yaml:"id"`
+		} `json:"users" yaml:"users"`
+	}{
+		Users: []struct {
+			Name string `json:"name" yaml:"name"`
+			ID   int    `json:"id" yaml:"id"`
+		}{
+			{Name: "user1", ID: 1},
+			{Name: "user2", ID: 2},
+		},
+	}
+
+	// Test JSON output
+	jsonResult := output(complexData, "override", "json")
+	assert.Contains(t, jsonResult, "\"users\":")
+	assert.Contains(t, jsonResult, "\"name\": \"user1\"")
+	assert.Contains(t, jsonResult, "\"id\": 1")
+
+	// Test YAML output
+	yamlResult := output(complexData, "override", "yaml")
+	assert.Contains(t, yamlResult, "users:")
+	assert.Contains(t, yamlResult, "name: user1")
+	assert.Contains(t, yamlResult, "id: 1")
+}
+
+func TestOutputWithNilData(t *testing.T) {
+	// Test with nil data
+	result := output(nil, "fallback", "json")
+	assert.Equal(t, "null", result)
+
+	result = output(nil, "fallback", "yaml")
+	assert.Equal(t, "null\n", result)
+
+	result = output(nil, "fallback", "")
+	assert.Equal(t, "fallback", result)
+}
+
+func TestOutputWithEmptyData(t *testing.T) {
+	// Test with empty slice
+	emptySlice := []string{}
+	result := output(emptySlice, "fallback", "json")
+	assert.Equal(t, "[]", result)
+
+	// Test with empty map
+	emptyMap := map[string]string{}
+	result = output(emptyMap, "fallback", "json")
+	assert.Equal(t, "{}", result)
+}
@@ -7,16 +7,17 @@ import (

 func init() {
 	rootCmd.AddCommand(versionCmd)
-	versionCmd.Flags().StringP("output", "o", "", "Output format. Empty for human-readable, 'json', 'json-line' or 'yaml'")
 }

 var versionCmd = &cobra.Command{
 	Use:   "version",
-	Short: "Print the version.",
-	Long:  "The version of headscale.",
-	RunE: func(cmd *cobra.Command, args []string) error {
-		info := types.GetVersionInfo()
-
-		return printOutput(cmd, info, info.String())
+	Short: "Print the version",
+	Long:  "The version of headscale",
+	Run: func(cmd *cobra.Command, args []string) {
+		output := GetOutputFlag(cmd)
+		SuccessOutput(map[string]string{
+			"version": types.Version,
+			"commit":  types.GitCommitHash,
+		}, types.Version, output)
 	},
 }
@@ -0,0 +1,45 @@
+package cli
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestVersionCommand(t *testing.T) {
+	// Test that version command exists
+	assert.NotNil(t, versionCmd)
+	assert.Equal(t, "version", versionCmd.Use)
+	assert.Equal(t, "Print the version.", versionCmd.Short)
+	assert.Equal(t, "The version of headscale.", versionCmd.Long)
+}
+
+func TestVersionCommandStructure(t *testing.T) {
+	// Test command is properly added to root
+	found := false
+	for _, cmd := range rootCmd.Commands() {
+		if cmd.Use == "version" {
+			found = true
+			break
+		}
+	}
+	assert.True(t, found, "version command should be added to root command")
+}
+
+func TestVersionCommandFlags(t *testing.T) {
+	// Version command should inherit output flag from root as persistent flag
+	outputFlag := versionCmd.Flag("output")
+	if outputFlag == nil {
+		// Try persistent flags from root
+		outputFlag = rootCmd.PersistentFlags().Lookup("output")
+	}
+	assert.NotNil(t, outputFlag, "version command should have access to output flag")
+}
+
+func TestVersionCommandRun(t *testing.T) {
+	// Test that Run function is set
+	assert.NotNil(t, versionCmd.Run)
+
+	// We can't easily test the actual execution without mocking SuccessOutput
+	// but we can verify the function exists and has the right signature
+}
@@ -11,7 +11,20 @@ import (
 )

 func main() {
-	colors := termcolor.SupportLevel(os.Stderr) != termcolor.LevelNone
+	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
+	}

 	// Adhere to no-color.org manifesto of allowing users to
 	// turn off color in cli/services
@@ -9,15 +9,34 @@ import (
 	"github.com/juanfont/headscale/hscontrol/types"
 	"github.com/juanfont/headscale/hscontrol/util"
 	"github.com/spf13/viper"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
+	"gopkg.in/check.v1"
 )

-func TestConfigFileLoading(t *testing.T) {
-	tmpDir := t.TempDir()
+func Test(t *testing.T) {
+	check.TestingT(t)
+}
+
+var _ = check.Suite(&Suite{})
+
+type Suite struct{}
+
+func (s *Suite) SetUpSuite(c *check.C) {
+}
+
+func (s *Suite) TearDownSuite(c *check.C) {
+}
+
+func (*Suite) TestConfigFileLoading(c *check.C) {
+	tmpDir, err := os.MkdirTemp("", "headscale")
+	if err != nil {
+		c.Fatal(err)
+	}
+	defer os.RemoveAll(tmpDir)

 	path, err := os.Getwd()
-	require.NoError(t, err)
+	if err != nil {
+		c.Fatal(err)
+	}

 	cfgFile := filepath.Join(tmpDir, "config.yaml")

@@ -26,51 +45,70 @@ func TestConfigFileLoading(t *testing.T) {
 		filepath.Clean(path+"/../../config-example.yaml"),
 		cfgFile,
 	)
-	require.NoError(t, err)
+	if err != nil {
+		c.Fatal(err)
+	}

 	// Load example config, it should load without validation errors
 	err = types.LoadConfig(cfgFile, true)
-	require.NoError(t, err)
+	c.Assert(err, check.IsNil)

 	// Test that config file was interpreted correctly
-	assert.Equal(t, "http://127.0.0.1:8080", viper.GetString("server_url"))
-	assert.Equal(t, "127.0.0.1:8080", viper.GetString("listen_addr"))
-	assert.Equal(t, "127.0.0.1:9090", viper.GetString("metrics_listen_addr"))
-	assert.Equal(t, "sqlite", viper.GetString("database.type"))
-	assert.Equal(t, "/var/lib/headscale/db.sqlite", viper.GetString("database.sqlite.path"))
-	assert.Empty(t, viper.GetString("tls_letsencrypt_hostname"))
-	assert.Equal(t, ":http", viper.GetString("tls_letsencrypt_listen"))
-	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"))
+	c.Assert(viper.GetString("server_url"), check.Equals, "http://127.0.0.1:8080")
+	c.Assert(viper.GetString("listen_addr"), check.Equals, "127.0.0.1:8080")
+	c.Assert(viper.GetString("metrics_listen_addr"), check.Equals, "127.0.0.1:9090")
+	c.Assert(viper.GetString("database.type"), check.Equals, "sqlite")
+	c.Assert(viper.GetString("database.sqlite.path"), check.Equals, "/var/lib/headscale/db.sqlite")
+	c.Assert(viper.GetString("tls_letsencrypt_hostname"), check.Equals, "")
+	c.Assert(viper.GetString("tls_letsencrypt_listen"), check.Equals, ":http")
+	c.Assert(viper.GetString("tls_letsencrypt_challenge_type"), check.Equals, "HTTP-01")
+	c.Assert(
+		util.GetFileMode("unix_socket_permission"),
+		check.Equals,
+		fs.FileMode(0o770),
+	)
+	c.Assert(viper.GetBool("logtail.enabled"), check.Equals, false)
 }

-func TestConfigLoading(t *testing.T) {
-	tmpDir := t.TempDir()
+func (*Suite) TestConfigLoading(c *check.C) {
+	tmpDir, err := os.MkdirTemp("", "headscale")
+	if err != nil {
+		c.Fatal(err)
+	}
+	defer os.RemoveAll(tmpDir)

 	path, err := os.Getwd()
-	require.NoError(t, err)
+	if err != nil {
+		c.Fatal(err)
+	}

 	// Symlink the example config file
 	err = os.Symlink(
 		filepath.Clean(path+"/../../config-example.yaml"),
 		filepath.Join(tmpDir, "config.yaml"),
 	)
-	require.NoError(t, err)
+	if err != nil {
+		c.Fatal(err)
+	}

 	// Load example config, it should load without validation errors
 	err = types.LoadConfig(tmpDir, false)
-	require.NoError(t, err)
+	c.Assert(err, check.IsNil)

 	// Test that config file was interpreted correctly
-	assert.Equal(t, "http://127.0.0.1:8080", viper.GetString("server_url"))
-	assert.Equal(t, "127.0.0.1:8080", viper.GetString("listen_addr"))
-	assert.Equal(t, "127.0.0.1:9090", viper.GetString("metrics_listen_addr"))
-	assert.Equal(t, "sqlite", viper.GetString("database.type"))
-	assert.Equal(t, "/var/lib/headscale/db.sqlite", viper.GetString("database.sqlite.path"))
-	assert.Empty(t, viper.GetString("tls_letsencrypt_hostname"))
-	assert.Equal(t, ":http", viper.GetString("tls_letsencrypt_listen"))
-	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"))
+	c.Assert(viper.GetString("server_url"), check.Equals, "http://127.0.0.1:8080")
+	c.Assert(viper.GetString("listen_addr"), check.Equals, "127.0.0.1:8080")
+	c.Assert(viper.GetString("metrics_listen_addr"), check.Equals, "127.0.0.1:9090")
+	c.Assert(viper.GetString("database.type"), check.Equals, "sqlite")
+	c.Assert(viper.GetString("database.sqlite.path"), check.Equals, "/var/lib/headscale/db.sqlite")
+	c.Assert(viper.GetString("tls_letsencrypt_hostname"), check.Equals, "")
+	c.Assert(viper.GetString("tls_letsencrypt_listen"), check.Equals, ":http")
+	c.Assert(viper.GetString("tls_letsencrypt_challenge_type"), check.Equals, "HTTP-01")
+	c.Assert(
+		util.GetFileMode("unix_socket_permission"),
+		check.Equals,
+		fs.FileMode(0o770),
+	)
+	c.Assert(viper.GetBool("logtail.enabled"), check.Equals, false)
+	c.Assert(viper.GetBool("randomize_client_port"), check.Equals, false)
 }
@@ -1,262 +0,0 @@
-# hi — Headscale Integration test runner
-
-`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
-```
@@ -3,13 +3,9 @@ package main
 import (
 	"context"
 	"fmt"
-	"log"
-	"os"
-	"path/filepath"
 	"strings"
 	"time"

-	"github.com/cenkalti/backoff/v5"
 	"github.com/docker/docker/api/types/container"
 	"github.com/docker/docker/api/types/filters"
 	"github.com/docker/docker/api/types/image"
@@ -18,46 +14,30 @@ import (
 )

 // cleanupBeforeTest performs cleanup operations before running tests.
-// Only removes stale (stopped/exited) test containers to avoid interfering with concurrent test runs.
 func cleanupBeforeTest(ctx context.Context) error {
-	err := cleanupStaleTestContainers(ctx)
-	if err != nil {
-		return fmt.Errorf("cleaning stale test containers: %w", err)
+	if err := killTestContainers(ctx); err != nil {
+		return fmt.Errorf("failed to kill test containers: %w", err)
 	}

-	if err := pruneDockerNetworks(ctx); err != nil { //nolint:noinlineerr
-		return fmt.Errorf("pruning networks: %w", err)
+	if err := pruneDockerNetworks(ctx); err != nil {
+		return fmt.Errorf("failed to prune networks: %w", err)
 	}

 	return nil
 }

-// cleanupAfterTest removes the test container and all associated integration test containers for the run.
-func cleanupAfterTest(ctx context.Context, cli *client.Client, containerID, runID string) error {
-	// Remove the main test container
-	err := cli.ContainerRemove(ctx, containerID, container.RemoveOptions{
+// cleanupAfterTest removes the test container after completion.
+func cleanupAfterTest(ctx context.Context, cli *client.Client, containerID string) error {
+	return cli.ContainerRemove(ctx, containerID, container.RemoveOptions{
 		Force: true,
 	})
-	if err != nil {
-		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("cleaning up containers for run %s: %w", runID, err)
-		}
-	}
-
-	return nil
 }

 // killTestContainers terminates and removes all test containers.
 func killTestContainers(ctx context.Context) error {
-	cli, err := createDockerClient(ctx)
+	cli, err := createDockerClient()
 	if err != nil {
-		return fmt.Errorf("creating Docker client: %w", err)
+		return fmt.Errorf("failed to create Docker client: %w", err)
 	}
 	defer cli.Close()

@@ -65,14 +45,30 @@ func killTestContainers(ctx context.Context) error {
 		All: true,
 	})
 	if err != nil {
-		return fmt.Errorf("listing containers: %w", err)
+		return fmt.Errorf("failed to list containers: %w", err)
 	}

 	removed := 0
-
 	for _, cont := range containers {
-		if isTestContainerName(cont.Names) {
-			if killAndRemove(ctx, cli, cont) {
+		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) {
 				removed++
 			}
 		}
@@ -87,157 +83,43 @@ func killTestContainers(ctx context.Context) error {
 	return nil
 }

-// killTestContainersByRunID terminates and removes all test containers for a specific run ID.
-// 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(ctx)
-	if err != nil {
-		return fmt.Errorf("creating Docker client: %w", err)
-	}
-	defer cli.Close()
-
-	// Filter containers by hi.run-id label
-	containers, err := cli.ContainerList(ctx, container.ListOptions{
-		All: true,
-		Filters: filters.NewArgs(
-			filters.Arg("label", "hi.run-id="+runID),
-		),
-	})
-	if err != nil {
-		return fmt.Errorf("listing containers for run %s: %w", runID, err)
-	}
-
-	removed := 0
-
-	for _, cont := range containers {
-		if killAndRemove(ctx, cli, cont) {
-			removed++
-		}
-	}
-
-	if removed > 0 {
-		fmt.Printf("Removed %d containers for run ID %s\n", removed, runID)
-	}
-
-	return nil
-}
-
-// cleanupStaleTestContainers removes stopped/exited test containers without affecting running tests.
-// 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(ctx)
-	if err != nil {
-		return fmt.Errorf("creating Docker client: %w", err)
-	}
-	defer cli.Close()
-
-	// Only get stopped/exited containers
-	containers, err := cli.ContainerList(ctx, container.ListOptions{
-		All: true,
-		Filters: filters.NewArgs(
-			filters.Arg("status", "exited"),
-			filters.Arg("status", "dead"),
-		),
-	})
-	if err != nil {
-		return fmt.Errorf("listing stopped containers: %w", err)
-	}
-
-	removed := 0
-
-	for _, cont := range containers {
-		// Only remove containers that look like test containers
-		if isTestContainerName(cont.Names) {
-			if killAndRemove(ctx, cli, cont) {
-				removed++
-			}
-		}
-	}
-
-	if removed > 0 {
-		fmt.Printf("Removed %d stale test containers\n", removed)
-	}
-
-	return nil
-}
-
-const (
-	containerRemoveInitialInterval = 100 * time.Millisecond
-	containerRemoveMaxElapsedTime  = 2 * time.Second
-)
-
 // removeContainerWithRetry attempts to remove a container with exponential backoff retry logic.
 func removeContainerWithRetry(ctx context.Context, cli *client.Client, containerID string) bool {
-	expBackoff := backoff.NewExponentialBackOff()
-	expBackoff.InitialInterval = containerRemoveInitialInterval
+	maxRetries := 3
+	baseDelay := 100 * time.Millisecond

-	_, err := backoff.Retry(ctx, func() (struct{}, error) {
+	for attempt := range maxRetries {
 		err := cli.ContainerRemove(ctx, containerID, container.RemoveOptions{
 			Force: true,
 		})
-		if err != nil {
-			return struct{}{}, err
-		}
-
-		return struct{}{}, nil
-	}, backoff.WithBackOff(expBackoff), backoff.WithMaxElapsedTime(containerRemoveMaxElapsedTime))
-
-	return err == nil
-}
-
-// testContainerNamePrefixes are the name prefixes used by containers that the
-// integration test harness creates (headscale, tailscale, DERP, and k3s).
-var testContainerNamePrefixes = []string{"hs-", "ts-", "derp-", "k3s-"}
-
-// matchesTestContainerPrefix reports whether name belongs to an integration
-// test container, ignoring any leading "/" that Docker prefixes names with.
-func matchesTestContainerPrefix(name string) bool {
-	name = strings.TrimPrefix(name, "/")
-	for _, prefix := range testContainerNamePrefixes {
-		if strings.HasPrefix(name, prefix) {
+		if err == nil {
 			return true
 		}
+
+		// If this is the last attempt, don't wait
+		if attempt == maxRetries-1 {
+			break
+		}
+
+		// Wait with exponential backoff
+		delay := baseDelay * time.Duration(1<<attempt)
+		time.Sleep(delay)
 	}

 	return false
 }

-// 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") ||
-			matchesTestContainerPrefix(name) {
-			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(ctx)
+	cli, err := createDockerClient()
 	if err != nil {
-		return fmt.Errorf("creating Docker client: %w", err)
+		return fmt.Errorf("failed to create Docker client: %w", err)
 	}
 	defer cli.Close()

 	report, err := cli.NetworksPrune(ctx, filters.Args{})
 	if err != nil {
-		return fmt.Errorf("pruning networks: %w", err)
+		return fmt.Errorf("failed to prune networks: %w", err)
 	}

 	if len(report.NetworksDeleted) > 0 {
@@ -251,9 +133,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(ctx)
+	cli, err := createDockerClient()
 	if err != nil {
-		return fmt.Errorf("creating Docker client: %w", err)
+		return fmt.Errorf("failed to create Docker client: %w", err)
 	}
 	defer cli.Close()

@@ -261,14 +143,12 @@ func cleanOldImages(ctx context.Context) error {
 		All: true,
 	})
 	if err != nil {
-		return fmt.Errorf("listing images: %w", err)
+		return fmt.Errorf("failed to list 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") ||
@@ -303,19 +183,18 @@ 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(ctx)
+	cli, err := createDockerClient()
 	if err != nil {
-		return fmt.Errorf("creating Docker client: %w", err)
+		return fmt.Errorf("failed to create 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) { //nolint:staticcheck // SA1019: deprecated but functional
+		if errdefs.IsNotFound(err) {
 			fmt.Printf("Go module cache volume not found: %s\n", volumeName)
-		} else if errdefs.IsConflict(err) { //nolint:staticcheck // SA1019: deprecated but functional
+		} else if errdefs.IsConflict(err) {
 			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)
@@ -326,110 +205,3 @@ func cleanCacheVolume(ctx context.Context) error {

 	return nil
 }
-
-// cleanupSuccessfulTestArtifacts removes artifacts from successful test runs to save disk space.
-// This function removes large artifacts that are mainly useful for debugging failures:
-// - Database dumps (.db files)
-// - Profile data (pprof directories)
-// - MapResponse data (mapresponses directories)
-// - Prometheus metrics files
-//
-// It preserves:
-// - Log files (.log) which are small and useful for verification.
-func cleanupSuccessfulTestArtifacts(logsDir string, verbose bool) error {
-	entries, err := os.ReadDir(logsDir)
-	if err != nil {
-		return fmt.Errorf("reading logs directory: %w", err)
-	}
-
-	var (
-		removedFiles, removedDirs int
-		totalSize                 int64
-	)
-
-	for _, entry := range entries {
-		name := entry.Name()
-		fullPath := filepath.Join(logsDir, name)
-
-		if entry.IsDir() {
-			// Remove pprof and mapresponses directories (typically large)
-			// These directories contain artifacts from all containers in the test run
-			if name == "pprof" || name == "mapresponses" {
-				size, sizeErr := getDirSize(fullPath)
-				if sizeErr == nil {
-					totalSize += size
-				}
-
-				err := os.RemoveAll(fullPath)
-				if err != nil {
-					if verbose {
-						log.Printf("Warning: failed to remove directory %s: %v", name, err)
-					}
-				} else {
-					removedDirs++
-
-					if verbose {
-						log.Printf("Removed directory: %s/", name)
-					}
-				}
-			}
-		} else {
-			// Only process test-related files (headscale and tailscale)
-			if !strings.HasPrefix(name, "hs-") && !strings.HasPrefix(name, "ts-") {
-				continue
-			}
-
-			// Remove database, metrics, and status files, but keep logs
-			shouldRemove := strings.HasSuffix(name, ".db") ||
-				strings.HasSuffix(name, "_metrics.txt") ||
-				strings.HasSuffix(name, "_status.json")
-
-			if shouldRemove {
-				info, infoErr := entry.Info()
-				if infoErr == nil {
-					totalSize += info.Size()
-				}
-
-				err := os.Remove(fullPath)
-				if err != nil {
-					if verbose {
-						log.Printf("Warning: failed to remove file %s: %v", name, err)
-					}
-				} else {
-					removedFiles++
-
-					if verbose {
-						log.Printf("Removed file: %s", name)
-					}
-				}
-			}
-		}
-	}
-
-	if removedFiles > 0 || removedDirs > 0 {
-		const bytesPerMB = 1024 * 1024
-		log.Printf("Cleaned up %d files and %d directories (freed ~%.2f MB)",
-			removedFiles, removedDirs, float64(totalSize)/bytesPerMB)
-	}
-
-	return nil
-}
-
-// getDirSize calculates the total size of a directory.
-func getDirSize(path string) (int64, error) {
-	var size int64
-
-	err := filepath.Walk(path, func(_ string, info os.FileInfo, err error) error {
-		if err != nil {
-			return err
-		}
-
-		if !info.IsDir() {
-			size += info.Size()
-		}
-
-		return nil
-	})
-
-	return size, err
-}
@@ -14,7 +14,6 @@ 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"
@@ -23,22 +22,17 @@ 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(ctx)
+	cli, err := createDockerClient()
 	if err != nil {
-		return fmt.Errorf("creating Docker client: %w", err)
+		return fmt.Errorf("failed to create Docker client: %w", err)
 	}
 	defer cli.Close()

@@ -54,21 +48,19 @@ func runTestContainer(ctx context.Context, config *RunConfig) error {

 	absLogsDir, err := filepath.Abs(logsDir)
 	if err != nil {
-		return fmt.Errorf("getting absolute path for logs directory: %w", err)
+		return fmt.Errorf("failed to get absolute path for logs directory: %w", err)
 	}

 	const dirPerm = 0o755
-	if err := os.MkdirAll(absLogsDir, dirPerm); err != nil { //nolint:noinlineerr
-		return fmt.Errorf("creating logs directory: %w", err)
+	if err := os.MkdirAll(absLogsDir, dirPerm); err != nil {
+		return fmt.Errorf("failed to create logs directory: %w", err)
 	}

 	if config.CleanBefore {
 		if config.Verbose {
 			log.Printf("Running pre-test cleanup...")
 		}
-
-		err := cleanupBeforeTest(ctx)
-		if err != nil && config.Verbose {
+		if err := cleanupBeforeTest(ctx); err != nil && config.Verbose {
 			log.Printf("Warning: pre-test cleanup failed: %v", err)
 		}
 	}
@@ -79,118 +71,52 @@ func runTestContainer(ctx context.Context, config *RunConfig) error {
 	}

 	imageName := "golang:" + config.GoVersion
-	if err := ensureImageAvailable(ctx, cli, imageName, config.Verbose); err != nil { //nolint:noinlineerr
-		return fmt.Errorf("ensuring image availability: %w", err)
+	if err := ensureImageAvailable(ctx, cli, imageName, config.Verbose); err != nil {
+		return fmt.Errorf("failed to ensure image availability: %w", err)
 	}

 	resp, err := createGoTestContainer(ctx, cli, config, containerName, absLogsDir, goTestCmd)
 	if err != nil {
-		return fmt.Errorf("creating container: %w", err)
+		return fmt.Errorf("failed to create container: %w", err)
 	}

 	if config.Verbose {
 		log.Printf("Created container: %s", resp.ID)
 	}

-	if err := cli.ContainerStart(ctx, resp.ID, container.StartOptions{}); err != nil { //nolint:noinlineerr
-		return fmt.Errorf("starting container: %w", err)
+	if err := cli.ContainerStart(ctx, resp.ID, container.StartOptions{}); err != nil {
+		return fmt.Errorf("failed to start container: %w", err)
 	}

 	log.Printf("Starting test: %s", config.TestPattern)
-	log.Printf("Run ID: %s", runID)
-	log.Printf("Monitor with: docker logs -f %s", containerName)
-	log.Printf("Logs directory: %s", logsDir)
-
-	// Start stats collection for container resource monitoring (if enabled)
-	var statsCollector *StatsCollector
-
-	if config.Stats {
-		var err error
-
-		statsCollector, err = NewStatsCollector(ctx)
-		if err != nil {
-			if config.Verbose {
-				log.Printf("Warning: failed to create stats collector: %v", err)
-			}
-
-			statsCollector = nil
-		}
-
-		if statsCollector != nil {
-			defer statsCollector.Close()
-
-			// Start stats collection immediately - no need for complex retry logic
-			// The new implementation monitors Docker events and will catch containers as they start
-			err := statsCollector.StartCollection(ctx, runID, config.Verbose)
-			if err != nil {
-				if config.Verbose {
-					log.Printf("Warning: failed to start stats collection: %v", err)
-				}
-			}
-			defer statsCollector.StopCollection()
-		}
-	}

 	exitCode, err := streamAndWait(ctx, cli, resp.ID)

 	// Ensure all containers have finished and logs are flushed before extracting artifacts
-	waitErr := waitForContainerFinalization(ctx, cli, resp.ID, config.Verbose)
-	if waitErr != nil && config.Verbose {
+	if waitErr := waitForContainerFinalization(ctx, cli, resp.ID, config.Verbose); 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 { //nolint:noinlineerr
+	if err := extractArtifactsFromContainers(ctx, resp.ID, logsDir, config.Verbose); err != nil && config.Verbose {
 		log.Printf("Warning: failed to extract artifacts from containers: %v", err)
 	}

 	// Always list control files regardless of test outcome
 	listControlFiles(logsDir)

-	// Print stats summary and check memory limits if enabled
-	if config.Stats && statsCollector != nil {
-		violations := statsCollector.PrintSummaryAndCheckLimits(config.HSMemoryLimit, config.TSMemoryLimit)
-		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 %w", len(violations), ErrMemoryLimitViolations)
-		}
-	}
-
 	shouldCleanup := config.CleanAfter && (!config.KeepOnFailure || exitCode == 0)
 	if shouldCleanup {
 		if config.Verbose {
-			log.Printf("Running post-test cleanup for run %s...", runID)
+			log.Printf("Running post-test cleanup...")
 		}
-
-		cleanErr := cleanupAfterTest(ctx, cli, resp.ID, runID)
-
-		if cleanErr != nil && config.Verbose {
+		if cleanErr := cleanupAfterTest(ctx, cli, resp.ID); cleanErr != nil && config.Verbose {
 			log.Printf("Warning: post-test cleanup failed: %v", cleanErr)
 		}
-
-		// Clean up artifacts from successful tests to save disk space in CI
-		if exitCode == 0 {
-			if config.Verbose {
-				log.Printf("Test succeeded, cleaning up artifacts to save disk space...")
-			}
-
-			cleanErr := cleanupSuccessfulTestArtifacts(logsDir, config.Verbose)
-
-			if cleanErr != nil && config.Verbose {
-				log.Printf("Warning: artifact cleanup failed: %v", cleanErr)
-			}
-		}
 	}

 	if err != nil {
-		return fmt.Errorf("executing test: %w", err)
+		return fmt.Errorf("test execution failed: %w", err)
 	}

 	if exitCode != 0 {
@@ -224,7 +150,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("getting working directory: %w", err)
+		return container.CreateResponse{}, fmt.Errorf("failed to get working directory: %w", err)
 	}

 	projectRoot := findProjectRoot(pwd)
@@ -235,28 +161,6 @@ func createGoTestContainer(ctx context.Context, cli *client.Client, config *RunC
 		fmt.Sprintf("HEADSCALE_INTEGRATION_POSTGRES=%d", boolToInt(config.UsePostgres)),
 		"HEADSCALE_INTEGRATION_RUN_ID=" + runID,
 	}
-
-	// Pass through CI environment variable for CI detection
-	if ci := os.Getenv("CI"); ci != "" {
-		env = append(env, "CI="+ci)
-	}
-
-	// Pass through all HEADSCALE_INTEGRATION_* environment variables
-	for _, e := range os.Environ() {
-		if strings.HasPrefix(e, "HEADSCALE_INTEGRATION_") {
-			// Skip the ones we already set explicitly
-			if strings.HasPrefix(e, "HEADSCALE_INTEGRATION_POSTGRES=") ||
-				strings.HasPrefix(e, "HEADSCALE_INTEGRATION_RUN_ID=") {
-				continue
-			}
-
-			env = append(env, e)
-		}
-	}
-
-	// Set GOCACHE to a known location (used by both bind mount and volume cases)
-	env = append(env, "GOCACHE=/cache/go-build")
-
 	containerConfig := &container.Config{
 		Image:      "golang:" + config.GoVersion,
 		Cmd:        goTestCmd,
@@ -276,43 +180,20 @@ func createGoTestContainer(ctx context.Context, cli *client.Client, config *RunC
 		log.Printf("Using Docker socket: %s", dockerSocketPath)
 	}

-	binds := []string{
-		fmt.Sprintf("%s:%s", projectRoot, projectRoot),
-		dockerSocketPath + ":/var/run/docker.sock",
-		logsDir + ":/tmp/control",
-	}
-
-	// Use bind mounts for Go cache if provided via environment variables,
-	// otherwise fall back to Docker volumes for local development
-	var mounts []mount.Mount
-
-	goCache := os.Getenv("HEADSCALE_INTEGRATION_GO_CACHE")
-	goBuildCache := os.Getenv("HEADSCALE_INTEGRATION_GO_BUILD_CACHE")
-
-	if goCache != "" {
-		binds = append(binds, goCache+":/go")
-	} else {
-		mounts = append(mounts, mount.Mount{
-			Type:   mount.TypeVolume,
-			Source: "hs-integration-go-cache",
-			Target: "/go",
-		})
-	}
-
-	if goBuildCache != "" {
-		binds = append(binds, goBuildCache+":/cache/go-build")
-	} else {
-		mounts = append(mounts, mount.Mount{
-			Type:   mount.TypeVolume,
-			Source: "hs-integration-go-build-cache",
-			Target: "/cache/go-build",
-		})
-	}
-
 	hostConfig := &container.HostConfig{
 		AutoRemove: false, // We'll remove manually for better control
-		Binds:      binds,
-		Mounts:     mounts,
+		Binds: []string{
+			fmt.Sprintf("%s:%s", projectRoot, projectRoot),
+			dockerSocketPath + ":/var/run/docker.sock",
+			logsDir + ":/tmp/control",
+		},
+		Mounts: []mount.Mount{
+			{
+				Type:   mount.TypeVolume,
+				Source: "hs-integration-go-cache",
+				Target: "/go",
+			},
+		},
 	}

 	return cli.ContainerCreate(ctx, containerConfig, hostConfig, nil, nil, containerName)
@@ -326,7 +207,7 @@ func streamAndWait(ctx context.Context, cli *client.Client, containerID string)
 		Follow:     true,
 	})
 	if err != nil {
-		return -1, fmt.Errorf("getting container logs: %w", err)
+		return -1, fmt.Errorf("failed to get container logs: %w", err)
 	}
 	defer out.Close()

@@ -338,7 +219,7 @@ func streamAndWait(ctx context.Context, cli *client.Client, containerID string)
 	select {
 	case err := <-errCh:
 		if err != nil {
-			return -1, fmt.Errorf("waiting for container: %w", err)
+			return -1, fmt.Errorf("error waiting for container: %w", err)
 		}
 	case status := <-statusCh:
 		return int(status.StatusCode), nil
@@ -352,7 +233,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("listing containers: %w", err)
+		return fmt.Errorf("failed to list containers: %w", err)
 	}

 	testContainers := getCurrentTestContainers(containers, testContainerID, verbose)
@@ -361,7 +242,6 @@ 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()

@@ -371,7 +251,6 @@ 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
@@ -382,14 +261,12 @@ 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)
 					}
@@ -402,7 +279,6 @@ func waitForContainerFinalization(ctx context.Context, cli *client.Client, testC
 				if verbose {
 					log.Printf("All test containers finalized, ready for artifact extraction")
 				}
-
 				return nil
 			}
 		}
@@ -419,15 +295,13 @@ 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 { //nolint:noinlineerr
+		if _, err := os.Stat(filepath.Join(current, "go.mod")); err == nil {
 			return current
 		}
-
 		parent := filepath.Dir(current)
 		if parent == current {
 			return startPath
 		}
-
 		current = parent
 	}
 }
@@ -437,37 +311,34 @@ func boolToInt(b bool) int {
 	if b {
 		return 1
 	}
-
 	return 0
 }

 // DockerContext represents Docker context information.
 type DockerContext struct {
-	Name      string         `json:"Name"`
-	Metadata  map[string]any `json:"Metadata"`
-	Endpoints map[string]any `json:"Endpoints"`
-	Current   bool           `json:"Current"`
+	Name      string                 `json:"Name"`
+	Metadata  map[string]interface{} `json:"Metadata"`
+	Endpoints map[string]interface{} `json:"Endpoints"`
+	Current   bool                   `json:"Current"`
 }

 // createDockerClient creates a Docker client with context detection.
-func createDockerClient(ctx context.Context) (*client.Client, error) {
-	contextInfo, err := getCurrentDockerContext(ctx)
+func createDockerClient() (*client.Client, error) {
+	contextInfo, err := getCurrentDockerContext()
 	if err != nil {
 		return client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
 	}

 	var clientOpts []client.Opt
-
 	clientOpts = append(clientOpts, client.WithAPIVersionNegotiation())

 	if contextInfo != nil {
 		if endpoints, ok := contextInfo.Endpoints["docker"]; ok {
-			if endpointMap, ok := endpoints.(map[string]any); ok {
+			if endpointMap, ok := endpoints.(map[string]interface{}); ok {
 				if host, ok := endpointMap["Host"].(string); ok {
 					if runConfig.Verbose {
 						log.Printf("Using Docker host from context '%s': %s", contextInfo.Name, host)
 					}
-
 					clientOpts = append(clientOpts, client.WithHost(host))
 				}
 			}
@@ -482,17 +353,16 @@ func createDockerClient(ctx context.Context) (*client.Client, error) {
 }

 // getCurrentDockerContext retrieves the current Docker context information.
-func getCurrentDockerContext(ctx context.Context) (*DockerContext, error) {
-	cmd := exec.CommandContext(ctx, "docker", "context", "inspect")
-
+func getCurrentDockerContext() (*DockerContext, error) {
+	cmd := exec.Command("docker", "context", "inspect")
 	output, err := cmd.Output()
 	if err != nil {
-		return nil, fmt.Errorf("getting docker context: %w", err)
+		return nil, fmt.Errorf("failed to get docker context: %w", err)
 	}

 	var contexts []DockerContext
-	if err := json.Unmarshal(output, &contexts); err != nil { //nolint:noinlineerr
-		return nil, fmt.Errorf("parsing docker context: %w", err)
+	if err := json.Unmarshal(output, &contexts); err != nil {
+		return nil, fmt.Errorf("failed to parse docker context: %w", err)
 	}

 	if len(contexts) > 0 {
@@ -509,94 +379,34 @@ func getDockerSocketPath() string {
 	return "/var/run/docker.sock"
 }

-// 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) //nolint:staticcheck // SA1019: deprecated but functional
-	if err != nil {
-		if client.IsErrNotFound(err) { //nolint:staticcheck // SA1019: deprecated but functional
-			return false, nil
-		}
-
-		return false, fmt.Errorf("inspecting image %s: %w", imageName, err)
-	}
-
-	return true, nil
-}
-
-// ensureImageAvailable pulls imageName if missing, using Docker Hub
-// credentials and retrying transient errors.
+// ensureImageAvailable pulls the specified Docker image to ensure it's available.
 func ensureImageAvailable(ctx context.Context, cli *client.Client, imageName string, verbose bool) error {
-	available, err := checkImageAvailableLocally(ctx, cli, imageName)
+	if verbose {
+		log.Printf("Pulling image %s...", imageName)
+	}
+
+	reader, err := cli.ImagePull(ctx, imageName, image.PullOptions{})
 	if err != nil {
-		return fmt.Errorf("checking local image availability: %w", err)
-	}
-
-	if available {
-		if verbose {
-			log.Printf("Image %s is available locally", imageName)
-		}
-
-		return nil
+		return fmt.Errorf("failed to pull image %s: %w", imageName, err)
 	}
+	defer reader.Close()

 	if verbose {
-		log.Printf("Image %s not found locally, pulling...", imageName)
-	}
-
-	registryAuth, err := dockertestutil.RegistryAuth()
-	if err != nil {
-		return fmt.Errorf("resolving registry auth: %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 {
+		_, 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)
+		}
 		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)
@@ -605,11 +415,9 @@ func listControlFiles(logsDir string) {
 		return
 	}

-	var (
-		logFiles  []string
-		dataFiles []string
-		dataDirs  []string
-	)
+	var logFiles []string
+	var dataFiles []string
+	var dataDirs []string

 	for _, entry := range entries {
 		name := entry.Name()
@@ -638,7 +446,6 @@ func listControlFiles(logsDir string) {

 	if len(logFiles) > 0 {
 		log.Printf("Headscale logs:")
-
 		for _, file := range logFiles {
 			log.Printf("  %s", file)
 		}
@@ -646,11 +453,9 @@ 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)
 		}
@@ -659,27 +464,25 @@ 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(ctx)
+	cli, err := createDockerClient()
 	if err != nil {
-		return fmt.Errorf("creating Docker client: %w", err)
+		return fmt.Errorf("failed to create 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("listing containers: %w", err)
+		return fmt.Errorf("failed to list 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
-		err := extractContainerArtifacts(ctx, cli, cont.ID, cont.name, logsDir, verbose)
-		if err != nil {
+		if err := extractContainerArtifacts(ctx, cli, cont.ID, cont.name, logsDir, verbose); err != nil {
 			if verbose {
 				log.Printf("Warning: failed to extract artifacts from container %s (%s): %v", cont.name, cont.ID[:12], err)
 			}
@@ -687,7 +490,6 @@ func extractArtifactsFromContainers(ctx context.Context, testContainerID, logsDi
 			if verbose {
 				log.Printf("Extracted artifacts from container %s (%s)", cont.name, cont.ID[:12])
 			}
-
 			extractedCount++
 		}
 	}
@@ -711,13 +513,11 @@ 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
 		}
 	}
@@ -735,7 +535,7 @@ func getCurrentTestContainers(containers []container.Summary, testContainerID st
 	for _, cont := range containers {
 		for _, name := range cont.Names {
 			containerName := strings.TrimPrefix(name, "/")
-			if matchesTestContainerPrefix(containerName) {
+			if strings.HasPrefix(containerName, "hs-") || strings.HasPrefix(containerName, "ts-") {
 				// Check if container has matching run ID label
 				if cont.Labels != nil && cont.Labels["hi.run-id"] == runID {
 					testRunContainers = append(testRunContainers, testContainer{
@@ -758,15 +558,23 @@ 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
-	err := os.MkdirAll(logsDir, defaultDirPerm)
-	if err != nil {
-		return fmt.Errorf("creating logs directory: %w", err)
+	if err := os.MkdirAll(logsDir, 0o755); err != nil {
+		return fmt.Errorf("failed to create logs directory: %w", err)
 	}

 	// Extract container logs
-	err = extractContainerLogs(ctx, cli, containerID, containerName, logsDir, verbose)
-	if err != nil {
-		return fmt.Errorf("extracting logs: %w", err)
+	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
+		}
 	}

 	return nil
@@ -783,7 +591,7 @@ func extractContainerLogs(ctx context.Context, cli *client.Client, containerID,
 		Tail:       "all",
 	})
 	if err != nil {
-		return fmt.Errorf("getting container logs: %w", err)
+		return fmt.Errorf("failed to get container logs: %w", err)
 	}
 	defer logReader.Close()

@@ -797,17 +605,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("demultiplexing container logs: %w", err)
+		return fmt.Errorf("failed to demultiplex container logs: %w", err)
 	}

 	// Write stdout logs
-	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)
+	if err := os.WriteFile(stdoutPath, stdoutBuf.Bytes(), 0o644); err != nil {
+		return fmt.Errorf("failed to write stdout log: %w", err)
 	}

 	// Write stderr logs
-	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 err := os.WriteFile(stderrPath, stderrBuf.Bytes(), 0o644); err != nil {
+		return fmt.Errorf("failed to write stderr log: %w", err)
 	}

 	if verbose {
@@ -816,3 +624,72 @@ 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
+}
+
+// logExtractionError logs extraction errors with appropriate level based on error type.
+func logExtractionError(artifactType, containerName string, err error, verbose bool) {
+	if errors.Is(err, ErrFileNotFoundInTar) {
+		// File not found is expected and only logged in verbose mode
+		if verbose {
+			log.Printf("No %s found in container %s", artifactType, containerName)
+		}
+	} else {
+		// Other errors are actual failures and should be logged as warnings
+		log.Printf("Warning: failed to extract %s from %s: %v", artifactType, containerName, err)
+	}
+}
+
+// extractSingleFile copies a single file from a container.
+func extractSingleFile(ctx context.Context, cli *client.Client, containerID, sourcePath, fileName, logsDir string, verbose bool) error {
+	tarReader, _, err := cli.CopyFromContainer(ctx, containerID, sourcePath)
+	if err != nil {
+		return fmt.Errorf("failed to copy %s from container: %w", sourcePath, err)
+	}
+	defer tarReader.Close()
+
+	// Extract the single file from the tar
+	filePath := filepath.Join(logsDir, fileName)
+	if err := extractFileFromTar(tarReader, filepath.Base(sourcePath), filePath); err != nil {
+		return fmt.Errorf("failed to extract file from tar: %w", err)
+	}
+
+	if verbose {
+		log.Printf("Extracted %s from %s", fileName, containerID[:12])
+	}
+
+	return nil
+}
+
+// extractDirectory copies a directory from a container and extracts its contents.
+func extractDirectory(ctx context.Context, cli *client.Client, containerID, sourcePath, dirName, logsDir string, verbose bool) error {
+	tarReader, _, err := cli.CopyFromContainer(ctx, containerID, sourcePath)
+	if err != nil {
+		return fmt.Errorf("failed to copy %s from container: %w", sourcePath, err)
+	}
+	defer tarReader.Close()
+
+	// Create target directory
+	targetDir := filepath.Join(logsDir, dirName)
+	if err := os.MkdirAll(targetDir, 0o755); err != nil {
+		return fmt.Errorf("failed to create directory %s: %w", targetDir, err)
+	}
+
+	// Extract the directory from the tar
+	if err := extractDirectoryFromTar(tarReader, targetDir); err != nil {
+		return fmt.Errorf("failed to extract directory from tar: %w", err)
+	}
+
+	if verbose {
+		log.Printf("Extracted %s/ from %s", dirName, containerID[:12])
+	}
+
+	return nil
+}
@@ -5,25 +5,8 @@ import (
 	"errors"
 	"fmt"
 	"log"
-	"os"
 	"os/exec"
 	"strings"
-
-	"github.com/juanfont/headscale/integration/dockertestutil"
-	"github.com/juanfont/headscale/integration/k3sic"
-)
-
-const (
-	statusPass = "PASS"
-	statusFail = "FAIL"
-	statusWarn = "WARN"
-
-	nameDockerDaemon  = "Docker Daemon"
-	nameDockerContext = "Docker Context"
-	nameDockerSocket  = "Docker Socket"
-	nameGolangImage   = "Golang Image"
-	nameK3sImage      = "K3s Image"
-	nameGoInstall     = "Go Installation"
 )

 var ErrSystemChecksFailed = errors.New("system checks failed")
@@ -36,21 +19,6 @@ 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{}
@@ -63,29 +31,27 @@ func runDoctorCheck(ctx context.Context) error {
 	results = append(results, dockerResult)

 	// If Docker is available, run additional checks
-	if dockerResult.Status == statusPass {
+	if dockerResult.Status == "PASS" {
 		results = append(results, checkDockerContext(ctx))
 		results = append(results, checkDockerSocket(ctx))
-		results = append(results, checkDockerHubCredentials())
 		results = append(results, checkGolangImage(ctx))
-		results = append(results, checkK3sImage(ctx))
 	}

 	// Check 3: Go installation
-	results = append(results, checkGoInstallation(ctx))
+	results = append(results, checkGoInstallation())

 	// Check 4: Git repository
-	results = append(results, checkGitRepository(ctx))
+	results = append(results, checkGitRepository())

 	// Check 5: Required files
-	results = append(results, checkRequiredFiles(ctx))
+	results = append(results, checkRequiredFiles())

 	// Display results
 	displayDoctorResults(results)

 	// Return error if any critical checks failed
 	for _, result := range results {
-		if result.Status == statusFail {
+		if result.Status == "FAIL" {
 			return fmt.Errorf("%w - see details above", ErrSystemChecksFailed)
 		}
 	}
@@ -99,233 +65,227 @@ func runDoctorCheck(ctx context.Context) error {
 func checkDockerBinary() DoctorResult {
 	_, err := exec.LookPath("docker")
 	if err != nil {
-		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:  "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 pass("Docker Binary", "Docker binary found")
+	return DoctorResult{
+		Name:    "Docker Binary",
+		Status:  "PASS",
+		Message: "Docker binary found",
+	}
 }

 // checkDockerDaemon verifies Docker daemon is running and accessible.
 func checkDockerDaemon(ctx context.Context) DoctorResult {
-	cli, err := createDockerClient(ctx)
+	cli, err := createDockerClient()
 	if err != nil {
-		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",
-		)
+		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",
+			},
+		}
 	}
 	defer cli.Close()

 	_, err = cli.Ping(ctx)
 	if err != nil {
-		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:  "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 pass(nameDockerDaemon, "Docker daemon is running and accessible")
+	return DoctorResult{
+		Name:    "Docker Daemon",
+		Status:  "PASS",
+		Message: "Docker daemon is running and accessible",
+	}
 }

 // checkDockerContext verifies Docker context configuration.
-func checkDockerContext(ctx context.Context) DoctorResult {
-	contextInfo, err := getCurrentDockerContext(ctx)
+func checkDockerContext(_ context.Context) DoctorResult {
+	contextInfo, err := getCurrentDockerContext()
 	if err != nil {
-		return warn(
-			nameDockerContext,
-			"Could not detect Docker context, using default settings",
-			"Check: docker context ls",
-			"Consider setting up a specific context if needed",
-		)
+		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",
+			},
+		}
 	}

 	if contextInfo == nil {
-		return pass(nameDockerContext, "Using default Docker context")
+		return DoctorResult{
+			Name:    "Docker Context",
+			Status:  "PASS",
+			Message: "Using default Docker context",
+		}
 	}

-	return pass(nameDockerContext, "Using Docker context: "+contextInfo.Name)
+	return DoctorResult{
+		Name:    "Docker Context",
+		Status:  "PASS",
+		Message: "Using Docker context: " + contextInfo.Name,
+	}
 }

 // checkDockerSocket verifies Docker socket accessibility.
 func checkDockerSocket(ctx context.Context) DoctorResult {
-	cli, err := createDockerClient(ctx)
+	cli, err := createDockerClient()
 	if err != nil {
-		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",
-		)
+		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",
+			},
+		}
 	}
 	defer cli.Close()

 	info, err := cli.Info(ctx)
 	if err != nil {
-		return fail(
-			nameDockerSocket,
-			fmt.Sprintf("Cannot get Docker info: %v", err),
-			"Check Docker daemon status",
-			"Verify socket permissions",
-		)
+		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 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 DoctorResult{
+		Name:    "Docker Socket",
+		Status:  "PASS",
+		Message: fmt.Sprintf("Docker socket accessible (Server: %s)", info.ServerVersion),
 	}
-
-	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.
+// checkGolangImage verifies we can access the golang Docker image.
 func checkGolangImage(ctx context.Context) DoctorResult {
-	cli, err := createDockerClient(ctx)
+	cli, err := createDockerClient()
 	if err != nil {
-		return fail(nameGolangImage, "Cannot create Docker client for image check")
+		return DoctorResult{
+			Name:    "Golang Image",
+			Status:  "FAIL",
+			Message: "Cannot create Docker client for image check",
+		}
 	}
 	defer cli.Close()

 	goVersion := detectGoVersion()
 	imageName := "golang:" + goVersion

-	// First check if image is available locally
-	available, err := checkImageAvailableLocally(ctx, cli, imageName)
-	if err != nil {
-		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 pass(nameGolangImage, fmt.Sprintf("Golang image %s is available locally", imageName))
-	}
-
-	// Image not available locally, try to pull it
+	// Check if we can pull the image
 	err = ensureImageAvailable(ctx, cli, imageName, false)
 	if err != nil {
-		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:  "FAIL",
+			Message: fmt.Sprintf("Cannot pull golang image %s: %v", imageName, err),
+			Suggestions: []string{
+				"Check internet connectivity",
+				"Verify Docker Hub access",
+				"Try: docker pull " + imageName,
+			},
+		}
 	}

-	return pass(nameGolangImage, fmt.Sprintf("Golang image %s is now available", imageName))
-}
-
-// checkK3sImage verifies the ghcr k3s image used by TestK8sOperator is available
-// locally or can be pulled. The image is pinned (see [k3sic.K3sImage]).
-func checkK3sImage(ctx context.Context) DoctorResult {
-	cli, err := createDockerClient(ctx)
-	if err != nil {
-		return fail(nameK3sImage, "Cannot create Docker client for image check")
+	return DoctorResult{
+		Name:    "Golang Image",
+		Status:  "PASS",
+		Message: fmt.Sprintf("Golang image %s is available", imageName),
 	}
-	defer cli.Close()
-
-	imageName := k3sic.K3sImage
-
-	available, err := checkImageAvailableLocally(ctx, cli, imageName)
-	if err != nil {
-		return fail(
-			nameK3sImage,
-			fmt.Sprintf("Cannot check k3s image %s: %v", imageName, err),
-			"Check Docker daemon status",
-			"Try: docker images | grep k3s",
-		)
-	}
-
-	if available {
-		return pass(nameK3sImage, fmt.Sprintf("K3s image %s is available locally", imageName))
-	}
-
-	err = ensureImageAvailable(ctx, cli, imageName, false)
-	if err != nil {
-		return warn(
-			nameK3sImage,
-			fmt.Sprintf("K3s image %s not available locally and could not pull: %v", imageName, err),
-			"Only TestK8sOperator needs this image; other tests are unaffected",
-			"Try: docker pull "+imageName,
-		)
-	}
-
-	return pass(nameK3sImage, fmt.Sprintf("K3s image %s is now available", imageName))
 }

 // checkGoInstallation verifies Go is installed and working.
-func checkGoInstallation(ctx context.Context) DoctorResult {
+func checkGoInstallation() DoctorResult {
 	_, err := exec.LookPath("go")
 	if err != nil {
-		return fail(
-			nameGoInstall,
-			"Go binary not found in PATH",
-			"Install Go: https://golang.org/dl/",
-			"Ensure go is in your PATH",
-		)
+		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",
+			},
+		}
 	}

-	cmd := exec.CommandContext(ctx, "go", "version")
-
+	cmd := exec.Command("go", "version")
 	output, err := cmd.Output()
 	if err != nil {
-		return fail(nameGoInstall, fmt.Sprintf("Cannot get Go version: %v", err))
+		return DoctorResult{
+			Name:    "Go Installation",
+			Status:  "FAIL",
+			Message: fmt.Sprintf("Cannot get Go version: %v", err),
+		}
 	}

 	version := strings.TrimSpace(string(output))

-	return pass(nameGoInstall, version)
+	return DoctorResult{
+		Name:    "Go Installation",
+		Status:  "PASS",
+		Message: version,
+	}
 }

 // checkGitRepository verifies we're in a git repository.
-func checkGitRepository(ctx context.Context) DoctorResult {
-	cmd := exec.CommandContext(ctx, "git", "rev-parse", "--git-dir")
-
+func checkGitRepository() DoctorResult {
+	cmd := exec.Command("git", "rev-parse", "--git-dir")
 	err := cmd.Run()
 	if err != nil {
-		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:  "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 pass("Git Repository", "Running in Git repository")
+	return DoctorResult{
+		Name:    "Git Repository",
+		Status:  "PASS",
+		Message: "Running in Git repository",
+	}
 }

 // checkRequiredFiles verifies required files exist.
-func checkRequiredFiles(_ context.Context) DoctorResult {
+func checkRequiredFiles() DoctorResult {
 	requiredFiles := []string{
 		"go.mod",
 		"integration/",
@@ -333,25 +293,31 @@ func checkRequiredFiles(_ context.Context) DoctorResult {
 	}

 	var missingFiles []string
-
 	for _, file := range requiredFiles {
-		_, err := os.Stat(file)
-		if err != nil {
+		cmd := exec.Command("test", "-e", file)
+		if err := cmd.Run(); err != nil {
 			missingFiles = append(missingFiles, file)
 		}
 	}

 	if len(missingFiles) > 0 {
-		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:  "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 pass("Required Files", "All required files found")
+	return DoctorResult{
+		Name:    "Required Files",
+		Status:  "PASS",
+		Message: "All required files found",
+	}
 }

 // displayDoctorResults shows the results in a formatted way.
@@ -361,13 +327,12 @@ func displayDoctorResults(results []DoctorResult) {

 	for _, result := range results {
 		var icon string
-
 		switch result.Status {
-		case statusPass:
+		case "PASS":
 			icon = "✅"
-		case statusWarn:
+		case "WARN":
 			icon = "⚠️"
-		case statusFail:
+		case "FAIL":
 			icon = "❌"
 		default:
 			icon = "❓"
@@ -1,89 +0,0 @@
-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
-}
@@ -29,13 +29,6 @@ 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",
@@ -86,17 +79,15 @@ func main() {
 }

 func cleanAll(ctx context.Context) error {
-	for _, step := range []func(context.Context) error{
-		killTestContainers,
-		pruneDockerNetworks,
-		cleanOldImages,
-		cleanCacheVolume,
-	} {
-		err := step(ctx)
-		if err != nil {
-			return err
-		}
+	if err := killTestContainers(ctx); err != nil {
+		return err
+	}
+	if err := pruneDockerNetworks(ctx); err != nil {
+		return err
+	}
+	if err := cleanOldImages(ctx); err != nil {
+		return err
 	}

-	return nil
+	return cleanCacheVolume(ctx)
 }
@@ -6,7 +6,6 @@ import (
 	"log"
 	"os"
 	"path/filepath"
-	"strings"
 	"time"

 	"github.com/creachadair/command"
@@ -20,14 +19,11 @@ type RunConfig struct {
 	FailFast      bool          `flag:"failfast,default=true,Stop on first test failure"`
 	UsePostgres   bool          `flag:"postgres,default=false,Use PostgreSQL instead of SQLite"`
 	GoVersion     string        `flag:"go-version,Go version to use (auto-detected from go.mod)"`
-	CleanBefore   bool          `flag:"clean-before,default=true,Clean stale resources before test"`
+	CleanBefore   bool          `flag:"clean-before,default=true,Clean resources before test"`
 	CleanAfter    bool          `flag:"clean-after,default=true,Clean resources after test"`
 	KeepOnFailure bool          `flag:"keep-on-failure,default=false,Keep containers on test failure"`
 	LogsDir       string        `flag:"logs-dir,default=control_logs,Control logs directory"`
 	Verbose       bool          `flag:"verbose,default=false,Verbose output"`
-	Stats         bool          `flag:"stats,default=false,Collect and display container resource usage statistics"`
-	HSMemoryLimit float64       `flag:"hs-memory-limit,default=0,Fail test if any Headscale container exceeds this memory limit in MB (0 = disabled)"`
-	TSMemoryLimit float64       `flag:"ts-memory-limit,default=0,Fail test if any Tailscale container exceeds this memory limit in MB (0 = disabled)"`
 }

 // runIntegrationTest executes the integration test workflow.
@@ -49,9 +45,7 @@ func runIntegrationTest(env *command.Env) error {
 	if runConfig.Verbose {
 		log.Printf("Running pre-flight system checks...")
 	}
-
-	err := runDoctorCheck(env.Context())
-	if err != nil {
+	if err := runDoctorCheck(env.Context()); err != nil {
 		return fmt.Errorf("pre-flight checks failed: %w", err)
 	}

@@ -67,21 +61,62 @@ func runIntegrationTest(env *command.Env) error {

 // detectGoVersion reads the Go version from go.mod file.
 func detectGoVersion() string {
-	content, err := os.ReadFile("go.mod")
+	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)
 	if err != nil {
-		content, err = os.ReadFile(filepath.Join("..", "..", "go.mod"))
-		if err != nil {
-			return "1.26.1"
-		}
+		return "1.24"
 	}

-	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]
+	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]
 			}
+
+			return version
 		}
 	}

-	return "1.26.1"
+	return "1.24"
+}
+
+// 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
 }
@@ -1,488 +0,0 @@
-package main
-
-import (
-	"cmp"
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"log"
-	"slices"
-	"strings"
-	"sync"
-	"time"
-
-	"github.com/docker/docker/api/types"
-	"github.com/docker/docker/api/types/container"
-	"github.com/docker/docker/api/types/events"
-	"github.com/docker/docker/api/types/filters"
-	"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
-	ContainerName string
-	Stats         []StatsSample
-	mutex         sync.RWMutex
-}
-
-// StatsSample represents a single stats measurement.
-type StatsSample struct {
-	Timestamp time.Time
-	CPUUsage  float64 // CPU usage percentage
-	MemoryMB  float64 // Memory usage in MB
-}
-
-// StatsCollector manages collection of container statistics.
-type StatsCollector struct {
-	client            *client.Client
-	containers        map[string]*ContainerStats
-	stopChan          chan struct{}
-	wg                sync.WaitGroup
-	mutex             sync.RWMutex
-	collectionStarted bool
-}
-
-// NewStatsCollector creates a new stats collector instance.
-func NewStatsCollector(ctx context.Context) (*StatsCollector, error) {
-	cli, err := createDockerClient(ctx)
-	if err != nil {
-		return nil, fmt.Errorf("creating Docker client: %w", err)
-	}
-
-	return &StatsCollector{
-		client:     cli,
-		containers: make(map[string]*ContainerStats),
-		stopChan:   make(chan struct{}),
-	}, nil
-}
-
-// StartCollection begins monitoring all containers and collecting stats for hs- and ts- containers with matching run ID.
-func (sc *StatsCollector) StartCollection(ctx context.Context, runID string, verbose bool) error {
-	sc.mutex.Lock()
-	defer sc.mutex.Unlock()
-
-	if sc.collectionStarted {
-		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 {
-		log.Printf("Started container monitoring for run ID %s", runID)
-	}
-
-	return nil
-}
-
-// StopCollection stops all stats collection.
-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
-	close(sc.stopChan)
-
-	// Wait for all goroutines to finish
-	sc.wg.Wait()
-
-	// Mark as stopped
-	sc.mutex.Lock()
-	sc.collectionStarted = false
-	sc.mutex.Unlock()
-}
-
-// monitorExistingContainers checks for existing containers that match our criteria.
-func (sc *StatsCollector) monitorExistingContainers(ctx context.Context, runID string, verbose bool) {
-	defer sc.wg.Done()
-
-	containers, err := sc.client.ContainerList(ctx, container.ListOptions{})
-	if err != nil {
-		if verbose {
-			log.Printf("Failed to list existing containers: %v", err)
-		}
-
-		return
-	}
-
-	for _, cont := range containers {
-		if sc.shouldMonitorContainer(cont, runID) {
-			sc.startStatsForContainer(ctx, cont.ID, cont.Names[0], verbose)
-		}
-	}
-}
-
-// monitorDockerEvents listens for container start events and begins monitoring relevant containers.
-func (sc *StatsCollector) monitorDockerEvents(ctx context.Context, runID string, verbose bool) {
-	defer sc.wg.Done()
-
-	filter := filters.NewArgs()
-	filter.Add("type", "container")
-	filter.Add("event", "start")
-
-	eventOptions := events.ListOptions{
-		Filters: filter,
-	}
-
-	events, errs := sc.client.Events(ctx, eventOptions)
-
-	for {
-		select {
-		case <-sc.stopChan:
-			return
-		case <-ctx.Done():
-			return
-		case event := <-events:
-			if event.Type == "container" && event.Action == "start" {
-				// Get container details
-				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{ //nolint:staticcheck // SA1019: use container.Summary
-					ID:     containerInfo.ID,
-					Names:  []string{containerInfo.Name},
-					Labels: containerInfo.Config.Labels,
-				}
-
-				if sc.shouldMonitorContainer(cont, runID) {
-					sc.startStatsForContainer(ctx, cont.ID, cont.Names[0], verbose)
-				}
-			}
-		case err := <-errs:
-			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 { //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
-	}
-
-	// Check if it's an hs- or ts- container
-	for _, name := range cont.Names {
-		containerName := strings.TrimPrefix(name, "/")
-		if strings.HasPrefix(containerName, "hs-") || strings.HasPrefix(containerName, "ts-") {
-			return true
-		}
-	}
-
-	return false
-}
-
-// startStatsForContainer begins stats collection for a specific container.
-func (sc *StatsCollector) startStatsForContainer(ctx context.Context, containerID, containerName string, verbose bool) {
-	containerName = strings.TrimPrefix(containerName, "/")
-
-	sc.mutex.Lock()
-	// Check if we're already monitoring this container
-	if _, exists := sc.containers[containerID]; exists {
-		sc.mutex.Unlock()
-		return
-	}
-
-	sc.containers[containerID] = &ContainerStats{
-		ContainerID:   containerID,
-		ContainerName: containerName,
-		Stats:         make([]StatsSample, 0),
-	}
-	sc.mutex.Unlock()
-
-	if verbose {
-		log.Printf("Starting stats collection for container %s (%s)", containerName, containerID[:12])
-	}
-
-	sc.wg.Add(1)
-
-	go sc.collectStatsForContainer(ctx, containerID, verbose)
-}
-
-// collectStatsForContainer collects stats for a specific container using Docker API streaming.
-func (sc *StatsCollector) collectStatsForContainer(ctx context.Context, containerID string, verbose bool) {
-	defer sc.wg.Done()
-
-	// Use Docker API streaming stats - much more efficient than CLI
-	statsResponse, err := sc.client.ContainerStats(ctx, containerID, true)
-	if err != nil {
-		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 //nolint:staticcheck // SA1019: use StatsResponse
-
-	for {
-		select {
-		case <-sc.stopChan:
-			return
-		case <-ctx.Done():
-			return
-		default:
-			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
-			}
-
-			// Calculate CPU percentage (only if we have previous stats)
-			var cpuPercent float64
-			if prevStats != nil {
-				cpuPercent = calculateCPUPercent(prevStats, &stats)
-			}
-
-			// Calculate memory usage in MB
-			memoryMB := float64(stats.MemoryStats.Usage) / (1024 * 1024)
-
-			// 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
-					exists         bool
-				)
-
-				sc.mutex.RLock()
-				containerStats, exists = sc.containers[containerID]
-				sc.mutex.RUnlock()
-
-				if exists && containerStats != nil {
-					containerStats.mutex.Lock()
-					containerStats.Stats = append(containerStats.Stats, StatsSample{
-						Timestamp: time.Now(),
-						CPUUsage:  cpuPercent,
-						MemoryMB:  memoryMB,
-					})
-					containerStats.mutex.Unlock()
-				}
-			}
-
-			// Save current stats for next iteration
-			prevStats = &stats
-		}
-	}
-}
-
-// calculateCPUPercent calculates CPU usage percentage from Docker stats.
-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)
-
-	if systemDelta > 0 && cpuDelta >= 0 {
-		// 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
-			numCPUs = 1.0
-		}
-
-		return (cpuDelta / systemDelta) * numCPUs * 100.0
-	}
-
-	return 0.0
-}
-
-// ContainerStatsSummary represents summary statistics for a container.
-type ContainerStatsSummary struct {
-	ContainerName string
-	SampleCount   int
-	CPU           StatsSummary
-	Memory        StatsSummary
-}
-
-// MemoryViolation represents a container that exceeded the memory limit.
-type MemoryViolation struct {
-	ContainerName string
-	MaxMemoryMB   float64
-	LimitMB       float64
-}
-
-// StatsSummary represents min, max, and average for a metric.
-type StatsSummary struct {
-	Min     float64
-	Max     float64
-	Average float64
-}
-
-// GetSummary returns a summary of collected statistics.
-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))
-
-	for _, containerStats := range containerRefs {
-		containerStats.mutex.RLock()
-		stats := make([]StatsSample, len(containerStats.Stats))
-		copy(stats, containerStats.Stats)
-		containerName := containerStats.ContainerName
-		containerStats.mutex.RUnlock()
-
-		if len(stats) == 0 {
-			continue
-		}
-
-		summary := ContainerStatsSummary{
-			ContainerName: containerName,
-			SampleCount:   len(stats),
-		}
-
-		extract := func(get func(StatsSample) float64) []float64 {
-			values := make([]float64, len(stats))
-			for i, sample := range stats {
-				values[i] = get(sample)
-			}
-
-			return values
-		}
-
-		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
-	slices.SortFunc(summaries, func(a, b ContainerStatsSummary) int {
-		return cmp.Compare(a.ContainerName, b.ContainerName)
-	})
-
-	return summaries
-}
-
-// calculateStatsSummary calculates min, max, and average for a slice of values.
-func calculateStatsSummary(values []float64) StatsSummary {
-	if len(values) == 0 {
-		return StatsSummary{}
-	}
-
-	minVal := values[0]
-	maxVal := values[0]
-	sum := 0.0
-
-	for _, value := range values {
-		minVal = min(minVal, value)
-		maxVal = max(maxVal, value)
-		sum += value
-	}
-
-	return StatsSummary{
-		Min:     minVal,
-		Max:     maxVal,
-		Average: sum / float64(len(values)),
-	}
-}
-
-// PrintSummary prints the statistics summary to the console.
-func (sc *StatsCollector) PrintSummary() {
-	summaries := sc.GetSummary()
-
-	if len(summaries) == 0 {
-		log.Printf("No container statistics collected")
-		return
-	}
-
-	log.Printf("Container Resource Usage Summary:")
-	log.Printf("================================")
-
-	for _, summary := range summaries {
-		log.Printf("Container: %s (%d samples)", summary.ContainerName, summary.SampleCount)
-		log.Printf("  CPU Usage:    Min: %6.2f%%  Max: %6.2f%%  Avg: %6.2f%%",
-			summary.CPU.Min, summary.CPU.Max, summary.CPU.Average)
-		log.Printf("  Memory Usage: Min: %6.1f MB Max: %6.1f MB Avg: %6.1f MB",
-			summary.Memory.Min, summary.Memory.Max, summary.Memory.Average)
-		log.Printf("")
-	}
-}
-
-// CheckMemoryLimits checks if any containers exceeded their memory limits.
-func (sc *StatsCollector) CheckMemoryLimits(hsLimitMB, tsLimitMB float64) []MemoryViolation {
-	if hsLimitMB <= 0 && tsLimitMB <= 0 {
-		return nil
-	}
-
-	summaries := sc.GetSummary()
-
-	var violations []MemoryViolation
-
-	for _, summary := range summaries {
-		var limitMB float64
-		if strings.HasPrefix(summary.ContainerName, "hs-") {
-			limitMB = hsLimitMB
-		} else if strings.HasPrefix(summary.ContainerName, "ts-") {
-			limitMB = tsLimitMB
-		} else {
-			continue // Skip containers that don't match our patterns
-		}
-
-		if limitMB > 0 && summary.Memory.Max > limitMB {
-			violations = append(violations, MemoryViolation{
-				ContainerName: summary.ContainerName,
-				MaxMemoryMB:   summary.Memory.Max,
-				LimitMB:       limitMB,
-			})
-		}
-	}
-
-	return violations
-}
-
-// PrintSummaryAndCheckLimits prints the statistics summary and returns memory violations if any.
-func (sc *StatsCollector) PrintSummaryAndCheckLimits(hsLimitMB, tsLimitMB float64) []MemoryViolation {
-	sc.PrintSummary()
-	return sc.CheckMemoryLimits(hsLimitMB, tsLimitMB)
-}
-
-// Close closes the stats collector and cleans up resources.
-func (sc *StatsCollector) Close() error {
-	sc.StopCollection()
-	return sc.client.Close()
-}
@@ -0,0 +1,100 @@
+package main
+
+import (
+	"archive/tar"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// ErrFileNotFoundInTar indicates a file was not found in the tar archive.
+var ErrFileNotFoundInTar = errors.New("file not found in tar")
+
+// extractFileFromTar extracts a single file from a tar reader.
+func extractFileFromTar(tarReader io.Reader, fileName, outputPath string) error {
+	tr := tar.NewReader(tarReader)
+
+	for {
+		header, err := tr.Next()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			return fmt.Errorf("failed to read tar header: %w", err)
+		}
+
+		// Check if this is the file we're looking for
+		if filepath.Base(header.Name) == fileName {
+			if header.Typeflag == tar.TypeReg {
+				// Create the output file
+				outFile, err := os.Create(outputPath)
+				if err != nil {
+					return fmt.Errorf("failed to create output file: %w", err)
+				}
+				defer outFile.Close()
+
+				// Copy file contents
+				if _, err := io.Copy(outFile, tr); err != nil {
+					return fmt.Errorf("failed to copy file contents: %w", err)
+				}
+
+				return nil
+			}
+		}
+	}
+
+	return fmt.Errorf("%w: %s", ErrFileNotFoundInTar, fileName)
+}
+
+// extractDirectoryFromTar extracts all files from a tar reader to a target directory.
+func extractDirectoryFromTar(tarReader io.Reader, targetDir string) error {
+	tr := tar.NewReader(tarReader)
+
+	for {
+		header, err := tr.Next()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			return fmt.Errorf("failed to read tar header: %w", err)
+		}
+
+		// Clean the path to prevent directory traversal
+		cleanName := filepath.Clean(header.Name)
+		if strings.Contains(cleanName, "..") {
+			continue // Skip potentially dangerous paths
+		}
+
+		targetPath := filepath.Join(targetDir, filepath.Base(cleanName))
+
+		switch header.Typeflag {
+		case tar.TypeDir:
+			// Create directory
+			if err := os.MkdirAll(targetPath, os.FileMode(header.Mode)); err != nil {
+				return fmt.Errorf("failed to create directory %s: %w", targetPath, err)
+			}
+		case tar.TypeReg:
+			// Create file
+			outFile, err := os.Create(targetPath)
+			if err != nil {
+				return fmt.Errorf("failed to create file %s: %w", targetPath, err)
+			}
+
+			if _, err := io.Copy(outFile, tr); err != nil {
+				outFile.Close()
+				return fmt.Errorf("failed to copy file contents: %w", err)
+			}
+			outFile.Close()
+
+			// Set file permissions
+			if err := os.Chmod(targetPath, os.FileMode(header.Mode)); err != nil {
+				return fmt.Errorf("failed to set file permissions: %w", err)
+			}
+		}
+	}
+
+	return nil
+}
@@ -1,66 +0,0 @@
-package main
-
-import (
-	"encoding/json"
-	"errors"
-	"fmt"
-	"os"
-
-	"github.com/creachadair/command"
-	"github.com/creachadair/flax"
-	"github.com/juanfont/headscale/hscontrol/mapper"
-	"github.com/juanfont/headscale/integration/integrationutil"
-)
-
-type MapConfig struct {
-	Directory string `flag:"directory,Directory to read map responses from"`
-}
-
-var (
-	mapConfig            MapConfig
-	errDirectoryRequired = errors.New("directory is required")
-)
-
-func main() {
-	root := command.C{
-		Name: "mapresponses",
-		Help: "MapResponses is a tool to map and compare map responses from a directory",
-		Commands: []*command.C{
-			{
-				Name:     "online",
-				Help:     "",
-				Usage:    "run [test-pattern] [flags]",
-				SetFlags: command.Flags(flax.MustBind, &mapConfig),
-				Run:      runOnline,
-			},
-			command.HelpCommand(nil),
-		},
-	}
-
-	env := root.NewEnv(nil).MergeFlags(true)
-	command.RunOrFail(env, os.Args[1:])
-}
-
-// runIntegrationTest executes the integration test workflow.
-func runOnline(env *command.Env) error {
-	if mapConfig.Directory == "" {
-		return errDirectoryRequired
-	}
-
-	resps, err := mapper.ReadMapResponsesFromDirectory(mapConfig.Directory)
-	if err != nil {
-		return fmt.Errorf("reading map responses from directory: %w", err)
-	}
-
-	expected := integrationutil.BuildExpectedOnlineMap(resps)
-
-	out, err := json.MarshalIndent(expected, "", "  ")
-	if err != nil {
-		return fmt.Errorf("marshaling expected online map: %w", err)
-	}
-
-	os.Stderr.Write(out)
-	os.Stderr.Write([]byte("\n"))
-
-	return nil
-}
@@ -1,221 +0,0 @@
-// 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
-}
@@ -20,15 +20,23 @@ 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 empty value to disable the metrics listener.
 metrics_listen_addr: 127.0.0.1:9090

-# 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: []
+# 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

 # The Noise section includes specific configuration for the
 # TS2021 Noise protocol
@@ -41,29 +49,18 @@ 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.
-#
-# 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
+# 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
+# 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.
 prefixes:
  v4: 100.64.0.0/10
  v6: fd7a:115c:a1e0::/48

  # Strategy used for allocation of IPs to nodes, available options:
-  # - sequential (default): assigns the next free IP from the previous given
-  #   IP. A best-effort approach is used and Headscale might leave holes in the
-  #   IP range or fill up existing holes in the IP range.
+  # - sequential (default): assigns the next free IP from the previous given IP.
  # - random: assigns the next free IP from a pseudo-random IP generator (crypto/rand).
  allocation: sequential

@@ -71,7 +68,8 @@ 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
@@ -107,7 +105,7 @@ derp:

    # For better connection stability (especially when using an Exit-Node and DNS is not working),
    # it is possible to optionally add the public IPv4 and IPv6 address to the Derp-Map using:
-    ipv4: 198.51.100.1
+    ipv4: 1.2.3.4
    ipv6: 2001:db8::1

  # List of externally available DERP maps encoded in JSON
@@ -116,9 +114,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/docs/reference/derp-servers/custom-derp-servers
-  # https://headscale.net/stable/ref/derp/
+  # This option is mostly interesting for people hosting
+  # their own DERP servers:
+  # https://tailscale.com/kb/1118/custom-derp-servers/
  #
  # paths:
  #   - /etc/headscale/derp-example.yaml
@@ -130,50 +128,13 @@ derp:
  auto_update_enabled: true

  # How often should we check for DERP updates?
-  update_frequency: 3h
+  update_frequency: 24h

 # Disables the automatic check for headscale updates on startup
 disable_check_updates: false

-# 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
+# Time before an inactive ephemeral node is deleted?
+ephemeral_node_inactivity_timeout: 30m

 database:
  # Database type. Available options: sqlite, postgres
@@ -230,12 +191,12 @@ database:
  #   ssl: false

 ### TLS configuration
-# See: https://headscale.net/stable/ref/tls/
-
-## Let's Encrypt / ACME
-# Headscale supports automatically requesting and setting up
+#
+## Let's encrypt / ACME
+#
+# headscale supports automatically requesting and setting up
 # TLS for a domain with Let's Encrypt.
-
+#
 # URL to ACME directory
 acme_url: https://acme-v02.api.letsencrypt.org/directory

@@ -245,13 +206,15 @@ acme_email: ""
 # Domain name to request a TLS certificate for:
 tls_letsencrypt_hostname: ""

-# Path to store certificates and metadata needed by letsencrypt
+# Path to store certificates and metadata needed by
+# letsencrypt
+# For production:
 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
 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:
 # :http = port 80
@@ -262,32 +225,30 @@ tls_cert_path: ""
 tls_key_path: ""

 log:
-  # Valid log levels: panic, fatal, error, warn, info, debug, trace
-  level: info
-
  # Output formatting for logs: text or json
  format: text
+  level: info

 ## Policy
-# 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
+# headscale supports Tailscale's ACL policies.
+# Please have a look to their KB to better
+# understand the concepts: https://tailscale.com/kb/1018/acls/
 policy:
  # The mode can be "file" or "database" that defines
-  # where the policies are stored and read from.
+  # where the ACL policies are stored and read from.
  mode: file
-
-  # If the mode is set to "file", the path to a HuJSON file containing policies.
+  # If the mode is set to "file", the path to a
+  # HuJSON file containing ACL policies.
  path: ""

 ## DNS
 #
 # headscale supports Tailscale's DNS configuration and MagicDNS.
-# Please have a look to their docs to better understand the concepts:
+# Please have a look to their KB to better understand the concepts:
 #
-# - https://tailscale.com/docs/features/magicdns
-# - https://tailscale.com/blog/2021-09-private-dns-with-magicdns
+# - https://tailscale.com/kb/1054/dns/
+# - https://tailscale.com/kb/1081/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
@@ -297,12 +258,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/docs/reference/faq/dns-resolv-conf
+# https://tailscale.com/kb/1235/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
+  # Whether to use [MagicDNS](https://tailscale.com/kb/1081/magicdns/).
  magic_dns: true

  # Defines the base domain to create the hostnames for MagicDNS.
@@ -312,9 +273,9 @@ dns:
  # `hostname.base_domain` (e.g., _myhost.example.com_).
  base_domain: example.com

-  # Whether to use the local DNS settings of a node or override the local DNS
-  # settings (default) and force the use of Headscale's DNS configuration.
-  override_local_dns: true
+  # Whether to use the local DNS settings of a node (default) or override the
+  # local DNS settings and force the use of Headscale's DNS configuration.
+  override_local_dns: false

  # List of DNS servers to expose to clients.
  nameservers:
@@ -324,13 +285,14 @@ dns:
      - 2606:4700:4700::1111
      - 2606:4700:4700::1001

-      # NextDNS (see https://tailscale.com/docs/integrations/nextdns).
+      # NextDNS (see https://tailscale.com/kb/1218/nextdns/).
      # "abc123" is example NextDNS ID, replace with yours.
      # - https://dns.nextdns.io/abc123

-    # Split DNS (see https://tailscale.com/docs/reference/dns-in-tailscale#restricted-nameservers),
+    # Split DNS (see https://tailscale.com/kb/1054/dns/),
    # a map of domains and which DNS server to use for each.
-    split: {}
+    split:
+      {}
      # foo.bar.com:
      #   - 1.1.1.1
      # darp.headscale.net:
@@ -343,7 +305,7 @@ dns:

  # Extra DNS records
  # so far only A and AAAA records are supported (on the tailscale side)
-  # See: https://headscale.net/stable/ref/dns/
+  # See: docs/ref/dns.md
  extra_records: []
  #   - name: "grafana.myvpn.example.com"
  #     type: "A"
@@ -362,7 +324,6 @@ 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
@@ -381,11 +342,15 @@ 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 `node.expiry` to be ignored for
-#   # OIDC-authenticated nodes.
+#   # Note: enabling this will cause `oidc.expiry` to be ignored.
 #   use_expiry_from_token: false
 #
 #   # The OIDC scopes to use, defaults to "openid", "profile" and "email".
@@ -393,12 +358,6 @@ unix_socket_permission: "0770"
 #   # required "openid" scope.
 #   scope: ["openid", "profile", "email"]
 #
-#   # Only verified email addresses are synchronized to the user profile by
-#   # default. Unverified emails may be allowed in case an identity provider
-#   # does not send the "email_verified: true" claim or email verification is
-#   # not required.
-#   email_verified_required: true
-#
 #   # Provide custom key/value pairs which get sent to the identity provider's
 #   # authorization endpoint.
 #   extra_params:
@@ -431,48 +390,15 @@ unix_socket_permission: "0770"
 #     method: S256

 # Logtail configuration
-# 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/docs/features/logging#opt-out-of-client-logging
+# Logtail is Tailscales logging and auditing infrastructure, it allows the control panel
+# to instruct tailscale nodes to log their activity to a remote server.
 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
+  # Enable logtail for this headscales clients.
+  # 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

-# Taildrop configuration
-# 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 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.
-#   #
-#   # node_store_batch_size: 100
-#   # node_store_batch_timeout: 500ms
+# 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
@@ -1,7 +1,5 @@
-# If you plan to somehow use headscale, please deploy your own DERP infra.
-# See: https://tailscale.com/docs/reference/derp-servers/custom-derp-servers
+# If you plan to somehow use headscale, please deploy your own DERP infra: https://tailscale.com/kb/1118/custom-derp-servers/
 regions:
-  1: null # Disable DERP region with ID 1
  900:
    regionid: 900
    regioncode: custom
@@ -9,9 +7,9 @@ regions:
    nodes:
      - name: 900a
        regionid: 900
-        hostname: myderp.example.com
-        ipv4: 198.51.100.1
-        ipv6: 2001:db8::1
+        hostname: myderp.mydomain.no
+        ipv4: 123.123.123.123
+        ipv6: "2604:a880:400:d1::828:b001"
        stunport: 0
        stunonly: false
        derpport: 0
@@ -1,3 +1,3 @@
 {%
-include-markdown "../../CONTRIBUTING.md"
+    include-markdown "../../CONTRIBUTING.md"
 %}
@@ -24,12 +24,9 @@ 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 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.
+We don't know. We might be working on it. If you're interested in contributing, please post a feature request about it.

-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:
+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,15 +44,6 @@ For convenience, we also [build container images with headscale](../setup/instal
 we don't officially support deploying headscale using Docker**. On our [Discord server](https://discord.gg/c84AZQhmpx)
 we have a "docker-issues" channel where you can ask for Docker-specific help to the community.

-## 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 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.
-
 ## Scaling / How many clients does Headscale support?

 It depends. As often stated, Headscale is not enterprise software and our focus
@@ -63,22 +51,22 @@ is homelabbers and self-hosters. Of course, we do not prevent people from using
 it in a commercial/professional setting and often get questions about scaling.

 Please note that when Headscale is developed, performance is not part of the
-consideration as the main audience is considered to be users with a modest
+consideration as the main audience is considered to be users with a moddest
 amount of devices. We focus on correctness and feature parity with Tailscale
 SaaS over time.

-To understand if you might be able to use Headscale for your use case, I will
+To understand if you might be able to use Headscale for your usecase, I will
 describe two scenarios in an effort to explain what is the central bottleneck
 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

-1. An environment with 80 laptops/phones (end user devices)
+2. 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
@@ -88,7 +76,7 @@ new "world map" is created for every node in the network.
 This means that under certain conditions, Headscale can likely handle 100s
 of devices (maybe more), if there is _little to no change_ happening in the
 network. For example, in Scenario 1, the process of computing the world map is
-extremely demanding due to the size of the network, but when the map has been
+extremly demanding due to the size of the network, but when the map has been
 created and the nodes are not changing, the Headscale instance will likely
 return to a very low resource usage until the next time there is an event
 requiring the new map.
@@ -106,14 +94,14 @@ learn about the current state of the world.
 We expect that the performance will improve over time as we improve the code
 base, but it is not a focus. In general, we will never make the tradeoff to make
 things faster on the cost of less maintainable or readable code. We are a small
-team and have to optimise for maintainability.
+team and have to optimise for maintainabillity.

 ## Which database should I use?

 We recommend the use of SQLite as database for headscale:

 - SQLite is simple to setup and easy to use
- It scales well for all of headscale's use cases
+- It scales well for all of headscale's usecases
 - Development and testing happens primarily on SQLite
 - PostgreSQL is still supported, but is considered to be in "maintenance mode"

@@ -134,7 +122,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 a policy rule allows traffic only in one direction?
+## Why do two nodes see each other in their status, even if an ACL 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
@@ -142,72 +130,7 @@ 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 policy, 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 ACL, with the exception of `tailscale
+ping` which is always allowed in either direction.

-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-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-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#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/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
-applied by a client once it successfully connected with Headscale. See the configuration option `logtail.enabled` in the
-[configuration file](../ref/configuration.md) for details.
-
-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/docs/features/logging#opt-out-of-client-logging> for
-details.
+See also <https://tailscale.com/kb/1087/device-visibility>.
@@ -5,41 +5,33 @@ to provide self-hosters and hobbyists with an open-source server they can use fo
 provides on overview of Headscale's feature and compatibility with the Tailscale control server:

 - [x] Full "base" support of Tailscale's features
- [x] [Node registration](../ref/registration.md)
-    - [x] [Web authentication](../ref/registration.md#web-authentication)
-    - [x] [Pre authenticated key](../ref/registration.md#pre-authenticated-key)
+- [x] Node registration
+    - [x] Interactive
+    - [x] Pre authenticated key
 - [x] [DNS](../ref/dns.md)
-    - [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] [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] [Extra DNS records (Headscale only)](../ref/dns.md#setting-extra-dns-records)
- [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] [Taildrop (File Sharing)](https://tailscale.com/kb/1106/taildrop)
 - [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] [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
+- [x] Embedded [DERP server](https://tailscale.com/kb/1232/derp-servers)
+- [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`
+    - [x] [Auto approvers](https://tailscale.com/kb/1337/acl-syntax#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/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] [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] Basic registration
    - [x] Update user profile from identity provider
    - [ ] OIDC groups cannot be used in ACLs
- [ ] [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))
+- [ ] [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))
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Kristoffer Dalby	cb5c5c0621	Fix CLI timeout issues in integration tests Tests / test (push) Has been cancelled - Increase default CLI timeout from 5s to 30s in config.go - Fix error messages to match test expectations ("user/node not found") - Smart lookup gRPC calls need more time in containerized CI environment The CLI smart lookup feature makes additional gRPC calls that require longer timeouts than the original 5-second default, especially in containerized test environments with network latency. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-07-16 11:31:51 +00:00
Kristoffer Dalby	fe4978764b	Fix integration test timeouts by increasing CLI timeout for containerized environment Tests / test (push) Waiting to run The integration tests were failing with timeout errors when running route-related operations like ApproveRoutes. The issue was that the CLI timeout was set to 5 seconds by default, but the containerized test environment with network latency and startup delays required more time for CLI operations to complete. This fix increases the CLI timeout to 30 seconds specifically for integration tests through the HEADSCALE_CLI_TIMEOUT environment variable. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-07-15 18:10:42 +00:00
Kristoffer Dalby	91ff5ab34f	Fix remaining CLI inconsistencies - Update users destroy command usage string to reflect --user flag - Fix documentation examples to use --node instead of --identifier - Ensure complete CLI consistency across all commands and docs 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-07-15 16:24:54 +00:00
Kristoffer Dalby	04d2e553bf	derp	2025-07-15 16:17:31 +00:00
Kristoffer Dalby	8253d588c6	derp	2025-07-15 14:51:23 +00:00
Kristoffer Dalby	024ed59ea9	more Tests / test (push) Waiting to run	2025-07-15 06:49:51 +00:00
Kristoffer Dalby	45baead257	clean Tests / test (push) Waiting to run	2025-07-14 20:56:01 +00:00
Kristoffer Dalby	67f2c20052	compli	2025-07-14 20:43:57 +00:00
Kristoffer Dalby	9d2cfb1e7e	compli Tests / test (push) Waiting to run	2025-07-14 15:50:46 +00:00
Kristoffer Dalby	7d31735bac	test	2025-07-14 15:12:32 +00:00
kradalby	60521283ab	init	2025-07-14 07:48:32 +00:00