fix: write server config to telemetry (#13590 )

* fix: add external auth configs to telemetry * Refactor telemetry to send the entire config * gen * Fix linting (cherry picked from commit 3a1fa04590)
fix: display trial errors in the dashboard (#13601 )
2024-06-21 19:03:35 +00:00 · 2024-06-21 19:03:15 +00:00 · 2024-06-21 19:03:10 +00:00 · 2024-06-21 19:03:04 +00:00 · 2024-06-21 19:02:58 +00:00 · 2024-06-21 19:02:30 +00:00
2075 changed files with 120942 additions and 50336 deletions
@@ -0,0 +1,6 @@
+# Ignore all files and folders
+**
+
+# Include flake.nix and flake.lock
+!flake.nix
+!flake.lock
@@ -6,9 +6,12 @@ coderd/apidoc/swagger.json linguist-generated=true
 coderd/database/dump.sql linguist-generated=true
 peerbroker/proto/*.go linguist-generated=true
 provisionerd/proto/*.go linguist-generated=true
+provisionerd/proto/version.go linguist-generated=false
 provisionersdk/proto/*.go linguist-generated=true
 *.tfplan.json linguist-generated=true
 *.tfstate.json linguist-generated=true
 *.tfstate.dot linguist-generated=true
 *.tfplan.dot linguist-generated=true
+site/e2e/provisionerGenerated.ts linguist-generated=true
 site/src/api/typesGenerated.ts linguist-generated=true
+site/src/pages/SetupPage/countries.tsx linguist-generated=true
@@ -4,12 +4,12 @@ description: |
 inputs:
  version:
    description: "The Go version to use."
-    default: "1.21.5"
+    default: "1.21.9"
 runs:
  using: "composite"
  steps:
    - name: Setup Go
-      uses: buildjet/setup-go@v4
+      uses: buildjet/setup-go@v5
      with:
        go-version: ${{ inputs.version }}

@@ -11,13 +11,13 @@ runs:
  using: "composite"
  steps:
    - name: Install pnpm
-      uses: pnpm/action-setup@v2
+      uses: pnpm/action-setup@v3
      with:
        version: 8
    - name: Setup Node
-      uses: buildjet/setup-node@v3
+      uses: buildjet/setup-node@v4.0.1
      with:
-        node-version: 18.17.0
+        node-version: 18.19.0
        # See https://github.com/actions/setup-node#caching-global-packages-data
        cache: "pnpm"
        cache-dependency-path: ${{ inputs.directory }}/pnpm-lock.yaml
@@ -7,4 +7,4 @@ runs:
    - name: Setup sqlc
      uses: sqlc-dev/setup-sqlc@v4
      with:
-        sqlc-version: "1.24.0"
+        sqlc-version: "1.25.0"
@@ -7,5 +7,5 @@ runs:
    - name: Install Terraform
      uses: hashicorp/setup-terraform@v3
      with:
-        terraform_version: 1.5.7
+        terraform_version: 1.7.5
        terraform_wrapper: false
@@ -1,43 +0,0 @@
-codecov:
-  require_ci_to_pass: false
-  notify:
-    after_n_builds: 5
-
-comment: false
-
-github_checks:
-  annotations: false
-
-coverage:
-  range: 50..75
-  round: down
-  precision: 2
-  status:
-    patch:
-      default:
-        informational: yes
-    project:
-      default:
-        target: 65%
-        informational: true
-
-ignore:
-  # This is generated code.
-  - coderd/database/models.go
-  - coderd/database/queries.sql.go
-  - coderd/database/databasefake
-  # These are generated or don't require tests.
-  - cmd
-  - coderd/tunnel
-  - coderd/database/dump
-  - coderd/database/postgres
-  - peerbroker/proto
-  - provisionerd/proto
-  - provisionersdk/proto
-  - scripts
-  - site/.storybook
-  - rules.go
-  # Packages used for writing tests.
-  - cli/clitest
-  - coderd/coderdtest
-  - pty/ptytest
@@ -38,15 +38,12 @@ updates:
    commit-message:
      prefix: "chore"
    labels: []
+    open-pull-requests-limit: 15
    ignore:
      # Ignore patch updates for all dependencies
      - dependency-name: "*"
        update-types:
          - version-update:semver-patch
-    groups:
-      go:
-        patterns:
-          - "*"

  # Update our Dockerfile.
  - package-ecosystem: "docker"
@@ -0,0 +1,34 @@
+app = "jnb-coder"
+primary_region = "jnb"
+
+[experimental]
+  entrypoint = ["/bin/sh", "-c", "CODER_DERP_SERVER_RELAY_URL=\"http://[${FLY_PRIVATE_IP}]:3000\" /opt/coder wsproxy server"]
+  auto_rollback = true
+
+[build]
+  image = "ghcr.io/coder/coder-preview:main"
+
+[env]
+  CODER_ACCESS_URL = "https://jnb.fly.dev.coder.com"
+  CODER_HTTP_ADDRESS = "0.0.0.0:3000"
+  CODER_PRIMARY_ACCESS_URL = "https://dev.coder.com"
+  CODER_WILDCARD_ACCESS_URL = "*--apps.jnb.fly.dev.coder.com"
+  CODER_VERBOSE = "true"
+
+[http_service]
+  internal_port = 3000
+  force_https = true
+  auto_stop_machines = true
+  auto_start_machines = true
+  min_machines_running = 0
+
+# Ref: https://fly.io/docs/reference/configuration/#http_service-concurrency
+[http_service.concurrency]
+  type = "requests"
+  soft_limit = 50
+  hard_limit = 100
+
+[[vm]]
+  cpu_kind = "shared"
+  cpus = 2
+  memory_mb = 512
@@ -13,6 +13,7 @@ primary_region = "cdg"
  CODER_HTTP_ADDRESS = "0.0.0.0:3000"
  CODER_PRIMARY_ACCESS_URL = "https://dev.coder.com"
  CODER_WILDCARD_ACCESS_URL = "*--apps.paris.fly.dev.coder.com"
+  CODER_VERBOSE = "true"

 [http_service]
  internal_port = 3000
@@ -21,6 +22,12 @@ primary_region = "cdg"
  auto_start_machines = true
  min_machines_running = 0

+# Ref: https://fly.io/docs/reference/configuration/#http_service-concurrency
+[http_service.concurrency]
+  type = "requests"
+  soft_limit = 50
+  hard_limit = 100
+
 [[vm]]
  cpu_kind = "shared"
  cpus = 2
@@ -13,6 +13,7 @@ primary_region = "gru"
  CODER_HTTP_ADDRESS = "0.0.0.0:3000"
  CODER_PRIMARY_ACCESS_URL = "https://dev.coder.com"
  CODER_WILDCARD_ACCESS_URL = "*--apps.sao-paulo.fly.dev.coder.com"
+  CODER_VERBOSE = "true"

 [http_service]
  internal_port = 3000
@@ -21,6 +22,12 @@ primary_region = "gru"
  auto_start_machines = true
  min_machines_running = 0

+# Ref: https://fly.io/docs/reference/configuration/#http_service-concurrency
+[http_service.concurrency]
+  type = "requests"
+  soft_limit = 50
+  hard_limit = 100
+
 [[vm]]
  cpu_kind = "shared"
  cpus = 2
@@ -13,6 +13,7 @@ primary_region = "syd"
  CODER_HTTP_ADDRESS = "0.0.0.0:3000"
  CODER_PRIMARY_ACCESS_URL = "https://dev.coder.com"
  CODER_WILDCARD_ACCESS_URL = "*--apps.sydney.fly.dev.coder.com"
+  CODER_VERBOSE = "true"

 [http_service]
  internal_port = 3000
@@ -21,6 +22,12 @@ primary_region = "syd"
  auto_start_machines = true
  min_machines_running = 0

+# Ref: https://fly.io/docs/reference/configuration/#http_service-concurrency
+[http_service.concurrency]
+  type = "requests"
+  soft_limit = 50
+  hard_limit = 100
+
 [[vm]]
  cpu_kind = "shared"
  cpus = 2
@@ -88,10 +88,9 @@ provider "kubernetes" {
 data "coder_workspace" "me" {}

 resource "coder_agent" "main" {
-  os                     = "linux"
-  arch                   = "amd64"
-  startup_script_timeout = 180
-  startup_script         = <<-EOT
+  os             = "linux"
+  arch           = "amd64"
+  startup_script = <<-EOT
    set -e

    # install and start code-server
@@ -46,7 +46,7 @@ jobs:
          fetch-depth: 1
      # For pull requests it's not necessary to checkout the code
      - name: check changed files
-        uses: dorny/paths-filter@v2
+        uses: dorny/paths-filter@v3
        id: filter
        with:
          filters: |
@@ -60,10 +60,7 @@ jobs:
              - "examples/lima/**"
            db:
              - "**.sql"
-              - "coderd/database/queries/**"
-              - "coderd/database/migrations"
-              - "coderd/database/sqlc.yaml"
-              - "coderd/database/dump.sql"
+              - "coderd/database/**"
            go:
              - "**.sql"
              - "**.go"
@@ -129,12 +126,13 @@ jobs:

      - name: Get golangci-lint cache dir
        run: |
-          go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.53.2
+          linter_ver=$(egrep -o 'GOLANGCI_LINT_VERSION=\S+' dogfood/Dockerfile | cut -d '=' -f 2)
+          go install github.com/golangci/golangci-lint/cmd/golangci-lint@v$linter_ver
          dir=$(golangci-lint cache status | awk '/Dir/ { print $2 }')
          echo "LINT_CACHE_DIR=$dir" >> $GITHUB_ENV

      - name: golangci-lint cache
-        uses: buildjet/cache@v3
+        uses: buildjet/cache@v4
        with:
          path: |
            ${{ env.LINT_CACHE_DIR }}
@@ -144,7 +142,7 @@ jobs:

      # Check for any typos
      - name: Check for typos
-        uses: crate-ci/typos@v1.16.24
+        uses: crate-ci/typos@v1.20.10
        with:
          config: .github/workflows/typos.toml

@@ -157,7 +155,7 @@ jobs:

      # Needed for helm chart linting
      - name: Install helm
-        uses: azure/setup-helm@v3
+        uses: azure/setup-helm@v4
        with:
          version: v3.9.2

@@ -185,13 +183,16 @@ jobs:
      - name: Setup sqlc
        uses: ./.github/actions/setup-sqlc

+      - name: Setup Terraform
+        uses: ./.github/actions/setup-tf
+
      - name: go install tools
        run: |
          go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.30
          go install storj.io/drpc/cmd/protoc-gen-go-drpc@v0.0.33
          go install golang.org/x/tools/cmd/goimports@latest
          go install github.com/mikefarah/yq/v4@v4.30.6
-          go install github.com/golang/mock/mockgen@v1.6.0
+          go install go.uber.org/mock/mockgen@v0.4.0

      - name: Install Protoc
        run: |
@@ -204,7 +205,9 @@ jobs:
          popd

      - name: make gen
-        run: "make --output-sync -j -B gen"
+        # no `-j` flag as `make` fails with:
+        # coderd/rbac/object_gen.go:1:1: syntax error: package statement must be first
+        run: "make --output-sync -B gen"

      - name: Check for unstaged files
        run: ./scripts/check_unstaged.sh
@@ -224,11 +227,11 @@ jobs:
        uses: ./.github/actions/setup-node

      - name: Setup Go
-        uses: buildjet/setup-go@v4
+        uses: buildjet/setup-go@v5
        with:
          # This doesn't need caching. It's super fast anyways!
          cache: false
-          go-version: 1.21.5
+          go-version: 1.21.9

      - name: Install shfmt
        run: go install mvdan.cc/sh/v3/cmd/shfmt@v3.7.0
@@ -269,16 +272,6 @@ jobs:
        id: test
        shell: bash
        run: |
-          # Code coverage is more computationally expensive and also
-          # prevents test caching, so we disable it on alternate operating
-          # systems.
-          if [ "${{ matrix.os }}" == "ubuntu-latest" ]; then
-            echo "cover=true" >> $GITHUB_OUTPUT
-            export COVERAGE_FLAGS='-covermode=atomic -coverprofile="gotests.coverage" -coverpkg=./...'
-          else
-            echo "cover=false" >> $GITHUB_OUTPUT
-          fi
-
          # if macOS, install google-chrome for scaletests. As another concern,
          # should we really have this kind of external dependency requirement
          # on standard CI?
@@ -297,7 +290,7 @@ jobs:
          fi
          export TS_DEBUG_DISCO=true
          gotestsum --junitfile="gotests.xml" --jsonfile="gotests.json" \
-            --packages="./..." -- $PARALLEL_FLAG -short -failfast $COVERAGE_FLAGS
+            --packages="./..." -- $PARALLEL_FLAG -short -failfast

      - name: Upload test stats to Datadog
        timeout-minutes: 1
@@ -307,22 +300,10 @@ jobs:
        with:
          api-key: ${{ secrets.DATADOG_API_KEY }}

-      - name: Check code coverage
-        uses: codecov/codecov-action@v3
-        # This action has a tendency to error out unexpectedly, it has
-        # the `fail_ci_if_error` option that defaults to `false`, but
-        # that is no guarantee, see:
-        # https://github.com/codecov/codecov-action/issues/788
-        continue-on-error: true
-        if: steps.test.outputs.cover && github.actor != 'dependabot[bot]' && !github.event.pull_request.head.repo.fork
-        with:
-          token: ${{ secrets.CODECOV_TOKEN }}
-          files: ./gotests.coverage
-          flags: unittest-go-${{ matrix.os }}
-
  test-go-pg:
    runs-on: ${{ github.repository_owner == 'coder' && 'buildjet-8vcpu-ubuntu-2204' || 'ubuntu-latest' }}
-    needs: changes
+    needs:
+      - changes
    if: needs.changes.outputs.go == 'true' || needs.changes.outputs.ci == 'true' || github.ref == 'refs/heads/main'
    # This timeout must be greater than the timeout set by `go test` in
    # `make test-postgres` to ensure we receive a trace of running
@@ -354,19 +335,6 @@ jobs:
        with:
          api-key: ${{ secrets.DATADOG_API_KEY }}

-      - name: Check code coverage
-        uses: codecov/codecov-action@v3
-        # This action has a tendency to error out unexpectedly, it has
-        # the `fail_ci_if_error` option that defaults to `false`, but
-        # that is no guarantee, see:
-        # https://github.com/codecov/codecov-action/issues/788
-        continue-on-error: true
-        if: github.actor != 'dependabot[bot]' && !github.event.pull_request.head.repo.fork
-        with:
-          token: ${{ secrets.CODECOV_TOKEN }}
-          files: ./gotests.coverage
-          flags: unittest-go-postgres-linux
-
  test-go-race:
    runs-on: ${{ github.repository_owner == 'coder' && 'buildjet-8vcpu-ubuntu-2204' || 'ubuntu-latest' }}
    needs: changes
@@ -413,24 +381,20 @@ jobs:
      - run: pnpm test:ci --max-workers $(nproc)
        working-directory: site

-      - name: Check code coverage
-        uses: codecov/codecov-action@v3
-        # This action has a tendency to error out unexpectedly, it has
-        # the `fail_ci_if_error` option that defaults to `false`, but
-        # that is no guarantee, see:
-        # https://github.com/codecov/codecov-action/issues/788
-        continue-on-error: true
-        if: github.actor != 'dependabot[bot]' && !github.event.pull_request.head.repo.fork
-        with:
-          token: ${{ secrets.CODECOV_TOKEN }}
-          files: ./site/coverage/lcov.info
-          flags: unittest-js
-
  test-e2e:
    runs-on: ${{ github.repository_owner == 'coder' && 'buildjet-16vcpu-ubuntu-2204' || 'ubuntu-latest' }}
    needs: changes
    if: needs.changes.outputs.go == 'true' || needs.changes.outputs.ts == 'true' || needs.changes.outputs.ci == 'true' || github.ref == 'refs/heads/main'
    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        variant:
+          - enterprise: false
+            name: test-e2e
+          - enterprise: true
+            name: test-e2e-enterprise
+    name: ${{ matrix.variant.name }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
@@ -443,52 +407,48 @@ jobs:
      - name: Setup Go
        uses: ./.github/actions/setup-go

-      - name: Setup Terraform
-        uses: ./.github/actions/setup-tf
+      # Assume that the checked-in versions are up-to-date
+      - run: make gen/mark-fresh
+        name: make gen

-      - name: go install tools
-        run: |
-          go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.30
-          go install storj.io/drpc/cmd/protoc-gen-go-drpc@v0.0.33
-          go install golang.org/x/tools/cmd/goimports@latest
-          go install github.com/mikefarah/yq/v4@v4.30.6
-          go install github.com/golang/mock/mockgen@v1.6.0
-
-      - name: Install Protoc
-        run: |
-          mkdir -p /tmp/proto
-          pushd /tmp/proto
-          curl -L -o protoc.zip https://github.com/protocolbuffers/protobuf/releases/download/v23.3/protoc-23.3-linux-x86_64.zip
-          unzip protoc.zip
-          cp -r ./bin/* /usr/local/bin
-          cp -r ./include /usr/local/bin/include
-          popd
-
-      - name: Build
-        run: |
-          make -B site/out/index.html
+      - run: pnpm build
+        working-directory: site

      - run: pnpm playwright:install
        working-directory: site

-      - run: pnpm playwright:test --workers 1
+      # Run tests that don't require an enterprise license without an enterprise license
+      - run: pnpm playwright:test --forbid-only --workers 1
+        if: ${{ !matrix.variant.enterprise }}
        env:
          DEBUG: pw:api
        working-directory: site

+      # Run all of the tests with an enterprise license
+      - run: pnpm playwright:test --forbid-only --workers 1
+        if: ${{ matrix.variant.enterprise }}
+        env:
+          DEBUG: pw:api
+          CODER_E2E_ENTERPRISE_LICENSE: ${{ secrets.CODER_E2E_ENTERPRISE_LICENSE }}
+          CODER_E2E_REQUIRE_ENTERPRISE_TESTS: "1"
+        working-directory: site
+        # Temporarily allow these to fail so that I can gather data about which
+        # tests are failing.
+        continue-on-error: true
+
      - name: Upload Playwright Failed Tests
        if: always() && github.actor != 'dependabot[bot]' && runner.os == 'Linux' && !github.event.pull_request.head.repo.fork
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
        with:
-          name: failed-test-videos
+          name: failed-test-videos${{ matrix.variant.enterprise && '-enterprise' || '-agpl' }}
          path: ./site/test-results/**/*.webm
          retention-days: 7

      - name: Upload pprof dumps
        if: always() && github.actor != 'dependabot[bot]' && runner.os == 'Linux' && !github.event.pull_request.head.repo.fork
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
        with:
-          name: debug-pprof-dumps
+          name: debug-pprof-dumps${{ matrix.variant.enterprise && '-enterprise' || '-agpl'  }}
          path: ./site/test-results/**/debug-pprof-*.txt
          retention-days: 7

@@ -518,7 +478,8 @@ jobs:
          NODE_OPTIONS: "--max_old_space_size=4096"
          STORYBOOK: true
        with:
-          buildScriptName: "storybook:build"
+          # Do a fast, testing build for change previews
+          buildScriptName: "storybook:ci"
          exitOnceUploaded: true
          # This will prevent CI from failing when Chromatic detects visual changes
          exitZeroOnChanges: true
@@ -532,6 +493,8 @@ jobs:
          # Run TurboSnap to trace file dependencies to related stories
          # and tell chromatic to only take snapshots of relevent stories
          onlyChanged: true
+          # Avoid uploading single files, because that's very slow
+          zip: true

      # This is a separate step for mainline only that auto accepts and changes
      # instead of holding CI up. Since we squash/merge, this is defensive to
@@ -549,6 +512,7 @@ jobs:
          autoAcceptChanges: true
          # This will prevent CI from failing when Chromatic detects visual changes
          exitZeroOnChanges: true
+          # Do a full build with documentation for mainline builds
          buildScriptName: "storybook:build"
          projectToken: 695c25b6cb65
          workingDir: "./site"
@@ -556,6 +520,8 @@ jobs:
          # Run TurboSnap to trace file dependencies to related stories
          # and tell chromatic to only take snapshots of relevent stories
          onlyChanged: true
+          # Avoid uploading single files, because that's very slow
+          zip: true

  offlinedocs:
    name: offlinedocs
@@ -594,7 +560,7 @@ jobs:
          go install storj.io/drpc/cmd/protoc-gen-go-drpc@v0.0.33
          go install golang.org/x/tools/cmd/goimports@latest
          go install github.com/mikefarah/yq/v4@v4.30.6
-          go install github.com/golang/mock/mockgen@v1.6.0
+          go install go.uber.org/mock/mockgen@v0.4.0

      - name: Setup sqlc
        uses: ./.github/actions/setup-sqlc
@@ -610,8 +576,10 @@ jobs:
          pnpm lint

      - name: Build
+        # no `-j` flag as `make` fails with:
+        # coderd/rbac/object_gen.go:1:1: syntax error: package statement must be first
        run: |
-          make -j build/coder_docs_"$(./scripts/version.sh)".tgz
+          make build/coder_docs_"$(./scripts/version.sh)".tgz

  required:
    runs-on: ubuntu-latest
@@ -626,6 +594,7 @@ jobs:
      - test-e2e
      - offlinedocs
      - sqlc-vet
+      - dependency-license-review
    # Allow this job to run even if the needed jobs fail, are skipped or
    # cancelled.
    if: always()
@@ -642,6 +611,7 @@ jobs:
          echo "- test-js: ${{ needs.test-js.result }}"
          echo "- test-e2e: ${{ needs.test-e2e.result }}"
          echo "- offlinedocs: ${{ needs.offlinedocs.result }}"
+          echo "- dependency-license-review: ${{ needs.dependency-license-review.result }}"
          echo

          # We allow skipped jobs to pass, but not failed or cancelled jobs.
@@ -657,7 +627,7 @@ jobs:
    # to main branch. We are only building this for amd64 platform. (>95% pulls
    # are for amd64)
    needs: changes
-    if: github.ref == 'refs/heads/main' && needs.changes.outputs.docs-only == 'false'
+    if: github.ref == 'refs/heads/main' && needs.changes.outputs.docs-only == 'false' && !github.event.pull_request.head.repo.fork
    runs-on: ${{ github.repository_owner == 'coder' && 'buildjet-8vcpu-ubuntu-2204' || 'ubuntu-latest' }}
    env:
      DOCKER_CLI_EXPERIMENTAL: "enabled"
@@ -683,7 +653,7 @@ jobs:
        uses: ./.github/actions/setup-go

      - name: Install nfpm
-        run: go install github.com/goreleaser/nfpm/v2/cmd/nfpm@v2.16.0
+        run: go install github.com/goreleaser/nfpm/v2/cmd/nfpm@v2.35.1

      - name: Install zstd
        run: sudo apt-get install -y zstd
@@ -694,47 +664,71 @@ jobs:
          go mod download

          version="$(./scripts/version.sh)"
+          tag="main-$(echo "$version" | sed 's/+/-/g')"
+          echo "tag=$tag" >> $GITHUB_OUTPUT
+
          make gen/mark-fresh
          make -j \
-            build/coder_linux_amd64 \
+            build/coder_linux_{amd64,arm64,armv7} \
            build/coder_"$version"_windows_amd64.zip \
            build/coder_"$version"_linux_amd64.{tar.gz,deb}

-      - name: Build and Push Linux amd64 Docker Image
+      - name: Build Linux Docker images
        id: build-docker
+        env:
+          CODER_IMAGE_BASE: ghcr.io/coder/coder-preview
+          CODER_IMAGE_TAG_PREFIX: main
+          DOCKER_CLI_EXPERIMENTAL: "enabled"
        run: |
          set -euxo pipefail
+
+          # build Docker images for each architecture
          version="$(./scripts/version.sh)"
          tag="main-$(echo "$version" | sed 's/+/-/g')"
-
-          export CODER_IMAGE_BUILD_BASE_TAG="$(CODER_IMAGE_BASE=coder-base ./scripts/image_tag.sh --version "$version")"
-          ./scripts/build_docker.sh \
-            --arch amd64 \
-            --target "ghcr.io/coder/coder-preview:$tag" \
-            --version $version \
-            --push \
-            build/coder_linux_amd64
-
-          # Tag as main
-          docker tag "ghcr.io/coder/coder-preview:$tag" ghcr.io/coder/coder-preview:main
-          docker push ghcr.io/coder/coder-preview:main
-
-          # Store the tag in an output variable so we can use it in other jobs
          echo "tag=$tag" >> $GITHUB_OUTPUT

+          # build images for each architecture
+          make -j build/coder_"$version"_linux_{amd64,arm64,armv7}.tag
+
+          # only push if we are on main branch
+          if [ "${{ github.ref }}" == "refs/heads/main" ]; then
+            # build and push multi-arch manifest, this depends on the other images
+            # being pushed so will automatically push them
+            make -j push/build/coder_"$version"_linux_{amd64,arm64,armv7}.tag
+
+            # Define specific tags
+            tags=("$tag" "main" "latest")
+
+            # Create and push a multi-arch manifest for each tag
+            # we are adding `latest` tag and keeping `main` for backward
+            # compatibality
+            for t in "${tags[@]}"; do
+                ./scripts/build_docker_multiarch.sh \
+                    --push \
+                    --target "ghcr.io/coder/coder-preview:$t" \
+                    --version $version \
+                    $(cat build/coder_"$version"_linux_{amd64,arm64,armv7}.tag)
+            done
+          fi
+
      - name: Prune old images
-        uses: vlaurin/action-ghcr-prune@v0.5.0
+        if: github.ref == 'refs/heads/main'
+        uses: vlaurin/action-ghcr-prune@v0.6.0
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          organization: coder
          container: coder-preview
          keep-younger-than: 7 # days
+          keep-tags: latest
          keep-tags-regexes: ^pr
-          prune-tags-regexes: ^main-
+          prune-tags-regexes: |
+            ^main-
+            ^v
          prune-untagged: true

      - name: Upload build artifacts
-        uses: actions/upload-artifact@v3
+        if: github.ref == 'refs/heads/main'
+        uses: actions/upload-artifact@v4
        with:
          name: coder
          path: |
@@ -775,7 +769,7 @@ jobs:
        uses: fluxcd/flux2/action@main
        with:
          # Keep this up to date with the version of flux installed in dogfood cluster
-          version: "2.2.0"
+          version: "2.2.1"

      - name: Get Cluster Credentials
        uses: "google-github-actions/get-gke-credentials@v2"
@@ -827,68 +821,14 @@ jobs:
          flyctl deploy --image "$IMAGE" --app paris-coder --config ./.github/fly-wsproxies/paris-coder.toml --env "CODER_PROXY_SESSION_TOKEN=$TOKEN_PARIS" --yes
          flyctl deploy --image "$IMAGE" --app sydney-coder --config ./.github/fly-wsproxies/sydney-coder.toml --env "CODER_PROXY_SESSION_TOKEN=$TOKEN_SYDNEY" --yes
          flyctl deploy --image "$IMAGE" --app sao-paulo-coder --config ./.github/fly-wsproxies/sao-paulo-coder.toml --env "CODER_PROXY_SESSION_TOKEN=$TOKEN_SAO_PAULO" --yes
+          flyctl deploy --image "$IMAGE" --app jnb-coder --config ./.github/fly-wsproxies/jnb-coder.toml --env "CODER_PROXY_SESSION_TOKEN=$TOKEN_JNB" --yes
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
          IMAGE: ${{ needs.build.outputs.IMAGE }}
          TOKEN_PARIS: ${{ secrets.FLY_PARIS_CODER_PROXY_SESSION_TOKEN }}
          TOKEN_SYDNEY: ${{ secrets.FLY_SYDNEY_CODER_PROXY_SESSION_TOKEN }}
          TOKEN_SAO_PAULO: ${{ secrets.FLY_SAO_PAULO_CODER_PROXY_SESSION_TOKEN }}
-
-  deploy-legacy-proxies:
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    needs: build
-    if: github.ref == 'refs/heads/main' && !github.event.pull_request.head.repo.fork
-    permissions:
-      contents: read
-      id-token: write
-    steps:
-      - name: Authenticate to Google Cloud
-        uses: google-github-actions/auth@v2
-        with:
-          workload_identity_provider: projects/573722524737/locations/global/workloadIdentityPools/github/providers/github
-          service_account: coder-ci@coder-dogfood.iam.gserviceaccount.com
-
-      - name: Set up Google Cloud SDK
-        uses: google-github-actions/setup-gcloud@v2
-
-      - name: Download build artifacts
-        uses: actions/download-artifact@v3
-        with:
-          name: coder
-          path: ./build
-
-      - name: Install Release
-        run: |
-          set -euo pipefail
-
-          regions=(
-            # gcp-region-id instance-name systemd-service-name
-            "australia-southeast1-b coder-sydney coder-workspace-proxy"
-            "europe-west3-c coder-europe coder-workspace-proxy"
-            "southamerica-east1-b coder-brazil coder-workspace-proxy"
-          )
-
-          deb_pkg=$(find ./build -name "coder_*_linux_amd64.deb" -print -quit)
-          if [ -z "$deb_pkg" ]; then
-              echo "deb package $deb_pkg not found"
-              ls -l ./build
-              exit 1
-          fi
-
-          gcloud config set project coder-dogfood
-          for region in "${regions[@]}"; do
-            echo "::group::$region"
-            set -- $region
-
-            set -x
-            gcloud config set compute/zone "$1"
-            gcloud compute scp "$deb_pkg" "${2}:/tmp/coder.deb"
-            gcloud compute ssh "$2" -- /bin/sh -c "set -eux; sudo dpkg -i --force-confdef /tmp/coder.deb; sudo systemctl daemon-reload; sudo service '$3' restart"
-            set +x
-
-            echo "::endgroup::"
-          done
+          TOKEN_JNB: ${{ secrets.FLY_JNB_CODER_PROXY_SESSION_TOKEN }}

  # sqlc-vet runs a postgres docker container, runs Coder migrations, and then
  # runs sqlc-vet to ensure all queries are valid. This catches any mistakes
@@ -896,7 +836,7 @@ jobs:
  sqlc-vet:
    runs-on: ${{ github.repository_owner == 'coder' && 'buildjet-8vcpu-ubuntu-2204' || 'ubuntu-latest' }}
    needs: changes
-    if: needs.changes.outputs.db == 'true' || github.ref == 'refs/heads/main'
+    if: needs.changes.outputs.db == 'true' || needs.changes.outputs.ci == 'true' || github.ref == 'refs/heads/main'
    steps:
      - name: Checkout
        uses: actions/checkout@v4
@@ -912,3 +852,44 @@ jobs:
      - name: Setup and run sqlc vet
        run: |
          make sqlc-vet
+
+  # dependency-license-review checks that no license-incompatible dependencies have been introduced.
+  # This action is not intended to do a vulnerability check since that is handled by a separate action.
+  dependency-license-review:
+    runs-on: ubuntu-latest
+    if: github.ref != 'refs/heads/main'
+    steps:
+      - name: "Checkout Repository"
+        uses: actions/checkout@v4
+      - name: "Dependency Review"
+        id: review
+        # TODO: Replace this with the latest release once https://github.com/actions/dependency-review-action/pull/761 is merged.
+        uses: actions/dependency-review-action@49fbbe0acb033b7824f26d00b005d7d598d76301
+        with:
+          allow-licenses: Apache-2.0, BSD-2-Clause, BSD-3-Clause, CC0-1.0, ISC, MIT, MIT-0, MPL-2.0
+          allow-dependencies-licenses: "pkg:golang/github.com/pelletier/go-toml/v2"
+          license-check: true
+          vulnerability-check: false
+      - name: "Report"
+        # make sure this step runs even if the previous failed
+        if: always()
+        shell: bash
+        env:
+          VULNERABLE_CHANGES: ${{ steps.review.outputs.invalid-license-changes }}
+        run: |
+          fields=( "unlicensed" "unresolved" "forbidden" )
+
+          # This is unfortunate that we have to do this but the action does not support failing on
+          # an unknown license. The unknown dependency could easily have a GPL license which
+          # would be problematic for us.
+          # Track https://github.com/actions/dependency-review-action/issues/672 for when
+          # we can remove this brittle workaround.
+          for field in "${fields[@]}"; do
+            # Use jq to check if the array is not empty
+            if [[ $(echo "$VULNERABLE_CHANGES" | jq ".${field} | length") -ne 0 ]]; then
+              echo "Invalid or unknown licenses detected, contact @sreya to ensure your added dependency falls under one of our allowed licenses."
+              echo "$VULNERABLE_CHANGES" | jq
+              exit 1
+            fi
+          done
+          echo "No incompatible licenses detected"
@@ -26,7 +26,7 @@ jobs:
      pull-requests: write
    steps:
      - name: auto-approve dependabot
-        uses: hmarr/auto-approve-action@v3
+        uses: hmarr/auto-approve-action@v4
        if: github.actor == 'dependabot[bot]'

  cla:
@@ -34,7 +34,7 @@ jobs:
    steps:
      - name: cla
        if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target'
-        uses: contributor-assistant/github-action@v2.3.1
+        uses: contributor-assistant/github-action@v2.3.2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # the below token should have repo scope and must be manually added by you in the repository's secret
@@ -7,16 +7,19 @@ on:
    paths:
      - "dogfood/**"
      - ".github/workflows/dogfood.yaml"
-  # Uncomment these lines when testing with CI.
-  # pull_request:
-  #   paths:
-  #     - "dogfood/**"
-  #     - ".github/workflows/dogfood.yaml"
+      - "flake.lock"
+      - "flake.nix"
+  pull_request:
+    paths:
+      - "dogfood/**"
+      - ".github/workflows/dogfood.yaml"
+      - "flake.lock"
+      - "flake.nix"
  workflow_dispatch:

 jobs:
-  deploy_image:
-    runs-on: buildjet-4vcpu-ubuntu-2204
+  build_image:
+    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
@@ -33,46 +36,78 @@ jobs:
          tag=${tag//\//--}
          echo "tag=${tag}" >> $GITHUB_OUTPUT

+      - name: Set up Depot CLI
+        uses: depot/setup-action@v1
+
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to DockerHub
+        if: github.ref == 'refs/heads/main'
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_PASSWORD }}

-      - name: Build and push
-        uses: docker/build-push-action@v5
+      - name: Build and push Non-Nix image
+        uses: depot/build-push-action@v1
        with:
+          project: b4q6ltmpzh
+          token: ${{ secrets.DEPOT_TOKEN }}
+          buildx-fallback: true
          context: "{{defaultContext}}:dogfood"
          pull: true
-          push: true
+          save: true
+          push: ${{ github.ref == 'refs/heads/main' }}
          tags: "codercom/oss-dogfood:${{ steps.docker-tag-name.outputs.tag }},codercom/oss-dogfood:latest"
-          cache-from: type=registry,ref=codercom/oss-dogfood:latest
-          cache-to: type=inline
+
+      - name: Build and push Nix image
+        uses: depot/build-push-action@v1
+        with:
+          project: b4q6ltmpzh
+          token: ${{ secrets.DEPOT_TOKEN }}
+          buildx-fallback: true
+          context: "."
+          file: "dogfood/Dockerfile.nix"
+          pull: true
+          save: true
+          push: ${{ github.ref == 'refs/heads/main' }}
+          tags: "codercom/oss-dogfood-nix:${{ steps.docker-tag-name.outputs.tag }},codercom/oss-dogfood-nix:latest"

  deploy_template:
-    needs: deploy_image
+    needs: build_image
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

+      - name: Setup Terraform
+        uses: ./.github/actions/setup-tf
+
+      - name: Terraform init and validate
+        run: |
+          cd dogfood
+          terraform init -upgrade
+          terraform validate
+
      - name: Get short commit SHA
+        if: github.ref == 'refs/heads/main'
        id: vars
        run: echo "sha_short=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT

      - name: Get latest commit title
+        if: github.ref == 'refs/heads/main'
        id: message
        run: echo "pr_title=$(git log --format=%s -n 1 ${{ github.sha }})" >> $GITHUB_OUTPUT

      - name: "Get latest Coder binary from the server"
+        if: github.ref == 'refs/heads/main'
        run: |
          curl -fsSL "https://dev.coder.com/bin/coder-linux-amd64" -o "./coder"
          chmod +x "./coder"

      - name: "Push template"
+        if: github.ref == 'refs/heads/main'
        run: |
          ./coder templates push $CODER_TEMPLATE_NAME --directory $CODER_TEMPLATE_DIR --yes --name=$CODER_TEMPLATE_VERSION --message="$CODER_TEMPLATE_MESSAGE"
        env:
@@ -17,6 +17,9 @@
    },
    {
      "pattern": "tailscale.com"
+    },
+    {
+      "pattern": "wireguard.com"
    }
  ],
  "aliveStatusCodes": [200, 0]
@@ -14,4 +14,4 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Assign author
-        uses: toshimaru/auto-author-assign@v2.0.1
+        uses: toshimaru/auto-author-assign@v2.1.0
@@ -9,10 +9,6 @@ on:
      - main
  workflow_dispatch:
    inputs:
-      pr_number:
-        description: "PR number"
-        type: number
-        required: true
      experiments:
        description: "Experiments to enable"
        required: false
@@ -123,7 +119,7 @@ jobs:
          echo "NEW=$NEW" >> $GITHUB_OUTPUT

      - name: Check changed files
-        uses: dorny/paths-filter@v2
+        uses: dorny/paths-filter@v3
        id: filter
        with:
          base: ${{ github.ref }}
@@ -167,7 +163,7 @@ jobs:
    runs-on: "ubuntu-latest"
    steps:
      - name: Find Comment
-        uses: peter-evans/find-comment@v2
+        uses: peter-evans/find-comment@v3
        id: fc
        with:
          issue-number: ${{ needs.get_info.outputs.PR_NUMBER }}
@@ -177,7 +173,7 @@ jobs:

      - name: Comment on PR
        id: comment_id
-        uses: peter-evans/create-or-update-comment@v3
+        uses: peter-evans/create-or-update-comment@v4
        with:
          comment-id: ${{ steps.fc.outputs.comment-id }}
          issue-number: ${{ needs.get_info.outputs.PR_NUMBER }}
@@ -355,6 +351,7 @@ jobs:
      - name: Install/Upgrade Helm chart
        run: |
          set -euo pipefail
+          helm dependency update --skip-refresh ./helm/coder
          helm upgrade --install "pr${{ env.PR_NUMBER }}" ./helm/coder \
          --namespace "pr${{ env.PR_NUMBER }}" \
          --values ./pr-deploy-values.yaml \
@@ -419,7 +416,7 @@ jobs:

          # Create template
          cd ./.github/pr-deployments/template
-          coder templates create -y --variable namespace=pr${{ env.PR_NUMBER }} kubernetes
+          coder templates push -y --variable namespace=pr${{ env.PR_NUMBER }} kubernetes

          # Create workspace
          coder create --template="kubernetes" kube --parameter cpu=2 --parameter memory=4 --parameter home_disk_size=2 -y
@@ -444,7 +441,7 @@ jobs:
          echo "Slack notification sent"

      - name: Find Comment
-        uses: peter-evans/find-comment@v2
+        uses: peter-evans/find-comment@v3
        id: fc
        with:
          issue-number: ${{ env.PR_NUMBER }}
@@ -453,7 +450,7 @@ jobs:
          direction: last

      - name: Comment on PR
-        uses: peter-evans/create-or-update-comment@v3
+        uses: peter-evans/create-or-update-comment@v4
        env:
          STATUS: ${{ needs.get_info.outputs.NEW == 'true' && 'Created' || 'Updated' }}
        with:
@@ -1,11 +1,16 @@
 # GitHub release workflow.
 name: Release
 on:
-  push:
-    tags:
-      - "v*"
  workflow_dispatch:
    inputs:
+      release_channel:
+        type: choice
+        description: Release channel
+        options:
+          - mainline
+          - stable
+      release_notes:
+        description: Release notes for the publishing the release. This is required to create a release.
      dry_run:
        description: Perform a dry-run release (devel). Note that ref must be an annotated tag when run without dry-run.
        type: boolean
@@ -28,6 +33,8 @@ env:
  # https://github.blog/changelog/2022-06-10-github-actions-inputs-unified-across-manual-and-reusable-workflows/
  CODER_RELEASE: ${{ !inputs.dry_run }}
  CODER_DRY_RUN: ${{ inputs.dry_run }}
+  CODER_RELEASE_CHANNEL: ${{ inputs.release_channel }}
+  CODER_RELEASE_NOTES: ${{ inputs.release_notes }}

 jobs:
  release:
@@ -62,21 +69,45 @@ jobs:
          echo "CODER_FORCE_VERSION=$version" >> $GITHUB_ENV
          echo "$version"

-      - name: Create release notes
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # We always have to set this since there might be commits on
-          # main that didn't have a PR.
-          CODER_IGNORE_MISSING_COMMIT_METADATA: "1"
+      # Verify that all expectations for a release are met.
+      - name: Verify release input
+        if: ${{ !inputs.dry_run }}
+        run: |
+          set -euo pipefail
+
+          if [[ "${GITHUB_REF}" != "refs/tags/v"* ]]; then
+            echo "Ref must be a semver tag when creating a release, did you use scripts/release.sh?"
+            exit 1
+          fi
+
+          # 2.10.2 -> release/2.10
+          version="$(./scripts/version.sh)"
+          release_branch=release/${version%.*}
+          branch_contains_tag=$(git branch --remotes --contains "${GITHUB_REF}" --list "*/${release_branch}" --format='%(refname)')
+          if [[ -z "${branch_contains_tag}" ]]; then
+            echo "Ref tag must exist in a branch named ${release_branch} when creating a release, did you use scripts/release.sh?"
+            exit 1
+          fi
+
+          if [[ -z "${CODER_RELEASE_NOTES}" ]]; then
+            echo "Release notes are required to create a release, did you use scripts/release.sh?"
+            exit 1
+          fi
+
+          echo "Release inputs verified:"
+          echo
+          echo "- Ref: ${GITHUB_REF}"
+          echo "- Version: ${version}"
+          echo "- Release channel: ${CODER_RELEASE_CHANNEL}"
+          echo "- Release branch: ${release_branch}"
+          echo "- Release notes: true"
+
+      - name: Create release notes file
        run: |
          set -euo pipefail
-          ref=HEAD
-          old_version="$(git describe --abbrev=0 "$ref^1")"
-          version="v$(./scripts/version.sh)"

-          # Generate notes.
          release_notes_file="$(mktemp -t release_notes.XXXXXX)"
-          ./scripts/release/generate_release_notes.sh --check-for-changelog --old-version "$old_version" --new-version "$version" --ref "$ref" >> "$release_notes_file"
+          echo "$CODER_RELEASE_NOTES" > "$release_notes_file"
          echo CODER_RELEASE_NOTES_FILE="$release_notes_file" >> $GITHUB_ENV

      - name: Show release notes
@@ -97,13 +128,20 @@ jobs:
      - name: Setup Node
        uses: ./.github/actions/setup-node

+      # Necessary for signing Windows binaries.
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: "zulu"
+          java-version: "11.0"
+
      - name: Install nsis and zstd
        run: sudo apt-get install -y nsis zstd

      - name: Install nfpm
        run: |
          set -euo pipefail
-          wget -O /tmp/nfpm.deb https://github.com/goreleaser/nfpm/releases/download/v2.18.1/nfpm_amd64.deb
+          wget -O /tmp/nfpm.deb https://github.com/goreleaser/nfpm/releases/download/v2.35.1/nfpm_2.35.1_amd64.deb
          sudo dpkg -i /tmp/nfpm.deb
          rm /tmp/nfpm.deb

@@ -130,6 +168,32 @@ jobs:
          AC_CERTIFICATE_PASSWORD: ${{ secrets.AC_CERTIFICATE_PASSWORD }}
          AC_APIKEY_P8_BASE64: ${{ secrets.AC_APIKEY_P8_BASE64 }}

+      - name: Setup Windows EV Signing Certificate
+        run: |
+          set -euo pipefail
+          touch /tmp/ev_cert.pem
+          chmod 600 /tmp/ev_cert.pem
+          echo "$EV_SIGNING_CERT" > /tmp/ev_cert.pem
+          wget https://github.com/ebourg/jsign/releases/download/6.0/jsign-6.0.jar -O /tmp/jsign-6.0.jar
+        env:
+          EV_SIGNING_CERT: ${{ secrets.EV_SIGNING_CERT }}
+
+      # - name: Test migrations from current ref to main
+      #   run: |
+      #     make test-migrations
+
+      # Setup GCloud for signing Windows binaries.
+      - name: Authenticate to Google Cloud
+        id: gcloud_auth
+        uses: google-github-actions/auth@v2
+        with:
+          workload_identity_provider: ${{ secrets.GCP_CODE_SIGNING_WORKLOAD_ID_PROVIDER }}
+          service_account: ${{ secrets.GCP_CODE_SIGNING_SERVICE_ACCOUNT }}
+          token_format: "access_token"
+
+      - name: Setup GCloud SDK
+        uses: "google-github-actions/setup-gcloud@v2"
+
      - name: Build binaries
        run: |
          set -euo pipefail
@@ -144,16 +208,26 @@ jobs:
            build/coder_helm_"$version".tgz \
            build/provisioner_helm_"$version".tgz
        env:
+          CODER_SIGN_WINDOWS: "1"
          CODER_SIGN_DARWIN: "1"
          AC_CERTIFICATE_FILE: /tmp/apple_cert.p12
          AC_CERTIFICATE_PASSWORD_FILE: /tmp/apple_cert_password.txt
          AC_APIKEY_ISSUER_ID: ${{ secrets.AC_APIKEY_ISSUER_ID }}
          AC_APIKEY_ID: ${{ secrets.AC_APIKEY_ID }}
          AC_APIKEY_FILE: /tmp/apple_apikey.p8
+          EV_KEY: ${{ secrets.EV_KEY }}
+          EV_KEYSTORE: ${{ secrets.EV_KEYSTORE }}
+          EV_TSA_URL: ${{ secrets.EV_TSA_URL }}
+          EV_CERTIFICATE_PATH: /tmp/ev_cert.pem
+          GCLOUD_ACCESS_TOKEN: ${{ steps.gcloud_auth.outputs.access_token }}
+          JSIGN_PATH: /tmp/jsign-6.0.jar

      - name: Delete Apple Developer certificate and API key
        run: rm -f /tmp/{apple_cert.p12,apple_cert_password.txt,apple_apikey.p8}

+      - name: Delete Windows EV Signing Cert
+        run: rm /tmp/ev_cert.pem
+
      - name: Determine base image tag
        id: image-base-tag
        run: |
@@ -261,6 +335,9 @@ jobs:
          set -euo pipefail

          publish_args=()
+          if [[ $CODER_RELEASE_CHANNEL == "stable" ]]; then
+            publish_args+=(--stable)
+          fi
          if [[ $CODER_DRY_RUN == *t* ]]; then
            publish_args+=(--dry-run)
          fi
@@ -306,7 +383,7 @@ jobs:

      - name: Upload artifacts to actions (if dry-run)
        if: ${{ inputs.dry_run }}
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
        with:
          name: release-artifacts
          path: |
@@ -321,7 +398,7 @@ jobs:

      - name: Start Packer builds
        if: ${{ !inputs.dry_run }}
-        uses: peter-evans/repository-dispatch@v2
+        uses: peter-evans/repository-dispatch@v3
        with:
          token: ${{ secrets.CDRCI_GITHUB_TOKEN }}
          repository: coder/packages
@@ -408,6 +485,11 @@ jobs:
    if: ${{ !inputs.dry_run }}

    steps:
+      - name: Sync fork
+        run: gh repo sync cdrci/winget-pkgs -b master
+        env:
+          GH_TOKEN: ${{ secrets.CDRCI_GITHUB_TOKEN }}
+
      - name: Checkout
        uses: actions/checkout@v4
        with:
@@ -480,65 +562,28 @@ jobs:
          # different repo.
          GH_TOKEN: ${{ secrets.CDRCI_GITHUB_TOKEN }}

-  publish-chocolatey:
-    name: Publish to Chocolatey
-    runs-on: windows-latest
+  # publish-sqlc pushes the latest schema to sqlc cloud.
+  # At present these pushes cannot be tagged, so the last push is always the latest.
+  publish-sqlc:
+    name: "Publish to schema sqlc cloud"
+    runs-on: "ubuntu-latest"
    needs: release
    if: ${{ !inputs.dry_run }}
-
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
-          fetch-depth: 0
+          fetch-depth: 1

-      # Same reason as for release.
-      - name: Fetch git tags
-        run: git fetch --tags --force
+      # We need golang to run the migration main.go
+      - name: Setup Go
+        uses: ./.github/actions/setup-go

-      # From https://chocolatey.org
-      - name: Install Chocolatey
+      - name: Setup sqlc
+        uses: ./.github/actions/setup-sqlc
+
+      - name: Push schema to sqlc cloud
+        # Don't block a release on this
+        continue-on-error: true
        run: |
-          Set-ExecutionPolicy Bypass -Scope Process -Force
-          [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
-
-          iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
-
-      - name: Build chocolatey package
-        run: |
-          cd scripts/chocolatey
-
-          # The package version is the same as the tag minus the leading "v".
-          # The version in this output already has the leading "v" removed but
-          # we do it again to be safe.
-          $version = "${{ needs.release.outputs.version }}".Trim('v')
-
-          $release_assets = gh release view --repo coder/coder "v${version}" --json assets | `
-            ConvertFrom-Json
-
-          # Get the URL for the Windows ZIP from the release assets.
-          $zip_url = $release_assets.assets | `
-            Where-Object name -Match ".*_windows_amd64.zip$" | `
-            Select -ExpandProperty url
-
-          echo "ZIP URL: ${zip_url}"
-          echo "Package version: ${version}"
-
-          echo "Downloading ZIP..."
-          Invoke-WebRequest $zip_url -OutFile assets.zip
-
-          echo "Extracting ZIP..."
-          Expand-Archive assets.zip -DestinationPath assets/
-
-          # No need to specify nuspec if there's only one in the directory.
-          choco pack --version=$version binary_path=assets/coder.exe
-
-          choco apikey --api-key $env:CHOCO_API_KEY --source https://push.chocolatey.org/
-
-          # No need to specify nupkg if there's only one in the directory.
-          choco push --source https://push.chocolatey.org/
-
-        env:
-          CHOCO_API_KEY: ${{ secrets.CHOCO_API_KEY }}
-          # We need a GitHub token for the gh CLI to function under GitHub Actions
-          GH_TOKEN: ${{ secrets.CDRCI_GITHUB_TOKEN }}
+          make sqlc-push
@@ -28,21 +28,21 @@ jobs:
      - name: Checkout
        uses: actions/checkout@v4

-      - name: Initialize CodeQL
-        uses: github/codeql-action/init@v2
-        with:
-          languages: go, javascript
-
      - name: Setup Go
        uses: ./.github/actions/setup-go

+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: go, javascript
+
      # Workaround to prevent CodeQL from building the dashboard.
      - name: Remove Makefile
        run: |
          rm Makefile

      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v2
+        uses: github/codeql-action/analyze@v3

      - name: Send Slack notification on failure
        if: ${{ failure() }}
@@ -75,7 +75,7 @@ jobs:
      - name: Install yq
        run: go run github.com/mikefarah/yq/v4@v4.30.6
      - name: Install mockgen
-        run: go install github.com/golang/mock/mockgen@v1.6.0
+        run: go install go.uber.org/mock/mockgen@v0.4.0
      - name: Install protoc-gen-go
        run: go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.30
      - name: Install protoc-gen-go-drpc
@@ -113,16 +113,8 @@ jobs:
          make -j "$image_job"
          echo "image=$(cat "$image_job")" >> $GITHUB_OUTPUT

-      - name: Run Prisma Cloud image scan
-        uses: PaloAltoNetworks/prisma-cloud-scan@v1
-        with:
-          pcc_console_url: ${{ secrets.PRISMA_CLOUD_URL }}
-          pcc_user: ${{ secrets.PRISMA_CLOUD_ACCESS_KEY }}
-          pcc_pass: ${{ secrets.PRISMA_CLOUD_SECRET_KEY }}
-          image_name: ${{ steps.build.outputs.image }}
-
      - name: Run Trivy vulnerability scanner
-        uses: aquasecurity/trivy-action@91713af97dc80187565512baba96e4364e983601
+        uses: aquasecurity/trivy-action@d710430a6722f083d3b36b8339ff66b32f22ee55
        with:
          image-ref: ${{ steps.build.outputs.image }}
          format: sarif
@@ -130,18 +122,28 @@ jobs:
          severity: "CRITICAL,HIGH"

      - name: Upload Trivy scan results to GitHub Security tab
-        uses: github/codeql-action/upload-sarif@v2
+        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: trivy-results.sarif
          category: "Trivy"

      - name: Upload Trivy scan results as an artifact
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
        with:
          name: trivy
          path: trivy-results.sarif
          retention-days: 7

+      # Prisma cloud scan runs last because it fails the entire job if it
+      # detects vulnerabilities. :|
+      - name: Run Prisma Cloud image scan
+        uses: PaloAltoNetworks/prisma-cloud-scan@v1
+        with:
+          pcc_console_url: ${{ secrets.PRISMA_CLOUD_URL }}
+          pcc_user: ${{ secrets.PRISMA_CLOUD_ACCESS_KEY }}
+          pcc_pass: ${{ secrets.PRISMA_CLOUD_SECRET_KEY }}
+          image_name: ${{ steps.build.outputs.image }}
+
      - name: Send Slack notification on failure
        if: ${{ failure() }}
        run: |
@@ -68,7 +68,7 @@ jobs:
                    repo: context.repo.repo,
                    issue_number: issue.number,
                    state: 'closed',
-                    state_reason: 'not planned'
+                    state_reason: 'not_planned'
                  });
                }
              } else {
@@ -14,7 +14,8 @@ darcula = "darcula"
 Hashi = "Hashi"
 trialer = "trialer"
 encrypter = "encrypter"
-hel = "hel" # as in helsinki
+hel = "hel"             # as in helsinki
+pn = "pn"               # this is used as proto node

 [files]
 extend-exclude = [
@@ -30,4 +31,6 @@ extend-exclude = [
 	"**/*_test.go",
 	"**/*.test.tsx",
 	"**/pnpm-lock.yaml",
+	"tailnet/testdata/**",
+	"site/src/pages/SetupPage/countries.tsx",
 ]
@@ -4,6 +4,11 @@ on:
  schedule:
    - cron: "0 9 * * 1"
  workflow_dispatch: # allows to run manually for testing
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "docs/**"

 jobs:
  check-docs:
@@ -24,7 +29,7 @@ jobs:
          file-path: "./README.md"

      - name: Send Slack notification
-        if: failure()
+        if: failure() && github.event_name != 'workflow_dispatch'
        run: |
          curl -X POST -H 'Content-type: application/json' -d '{"msg":"Broken links found in the documentation. Please check the logs at ${{ env.LOGS_URL }}"}' ${{ secrets.DOCS_LINK_SLACK_WEBHOOK }}
          echo "Sent Slack notification"
@@ -21,8 +21,8 @@
    "contravariance",
    "cronstrue",
    "databasefake",
-    "dbmem",
    "dbgen",
+    "dbmem",
    "dbtype",
    "DERP",
    "derphttp",
@@ -60,6 +60,7 @@
    "idtoken",
    "Iflag",
    "incpatch",
+    "initialisms",
    "ipnstate",
    "isatty",
    "Jobf",
@@ -113,18 +114,19 @@
    "Signup",
    "slogtest",
    "sourcemapped",
+    "spinbutton",
    "Srcs",
    "stdbuf",
    "stretchr",
    "STTY",
    "stuntest",
-    "tanstack",
    "tailbroker",
    "tailcfg",
    "tailexchange",
    "tailnet",
    "tailnettest",
    "Tailscale",
+    "tanstack",
    "tbody",
    "TCGETS",
    "tcpip",
@@ -141,6 +143,7 @@
    "tios",
    "tmpdir",
    "tokenconfig",
+    "Topbar",
    "tparallel",
    "trialer",
    "trimprefix",
@@ -168,10 +171,10 @@
    "workspaceapps",
    "workspacebuilds",
    "workspacename",
-    "wsconncache",
    "wsjson",
    "xerrors",
    "xlarge",
+    "xsmall",
    "yamux"
  ],
  "cSpell.ignorePaths": ["site/package.json", ".vscode/settings.json"],
@@ -200,7 +200,8 @@ endef
 # calling this manually.
 $(CODER_ALL_BINARIES): go.mod go.sum \
 	$(GO_SRC_FILES) \
-	$(shell find ./examples/templates)
+	$(shell find ./examples/templates) \
+	site/static/error.html

 	$(get-mode-os-arch-ext)
 	if [[ "$$os" != "windows" ]] && [[ "$$ext" != "" ]]; then
@@ -361,6 +362,8 @@ $(foreach chart,$(charts),build/$(chart)_helm_$(VERSION).tgz): build/%_helm_$(VE

 site/out/index.html: site/package.json $(shell find ./site $(FIND_EXCLUSIONS) -type f \( -name '*.ts' -o -name '*.tsx' \))
 	cd site
+	# prevents this directory from getting to big, and causing "too much data" errors
+	rm -rf out/assets/
 	../scripts/pnpm_install.sh
 	pnpm build

@@ -380,32 +383,44 @@ install: build/coder_$(VERSION)_$(GOOS)_$(GOARCH)$(GOOS_BIN_EXT)
 	cp "$<" "$$output_file"
 .PHONY: install

-fmt: fmt/prettier fmt/terraform fmt/shfmt fmt/go
+BOLD := $(shell tput bold 2>/dev/null)
+GREEN := $(shell tput setaf 2 2>/dev/null)
+RESET := $(shell tput sgr0 2>/dev/null)
+
+fmt: fmt/eslint fmt/prettier fmt/terraform fmt/shfmt fmt/go
 .PHONY: fmt

 fmt/go:
+	echo "$(GREEN)==>$(RESET) $(BOLD)fmt/go$(RESET)"
 	# VS Code users should check out
 	# https://github.com/mvdan/gofumpt#visual-studio-code
 	go run mvdan.cc/gofumpt@v0.4.0 -w -l .
 .PHONY: fmt/go

+fmt/eslint:
+	echo "$(GREEN)==>$(RESET) $(BOLD)fmt/eslint$(RESET)"
+	cd site
+	pnpm run lint:fix
+.PHONY: fmt/eslint
+
 fmt/prettier:
-	echo "--- prettier"
+	echo "$(GREEN)==>$(RESET) $(BOLD)fmt/prettier$(RESET)"
 	cd site
 # Avoid writing files in CI to reduce file write activity
 ifdef CI
 	pnpm run format:check
 else
-	pnpm run format:write
+	pnpm run format
 endif
 .PHONY: fmt/prettier

 fmt/terraform: $(wildcard *.tf)
+	echo "$(GREEN)==>$(RESET) $(BOLD)fmt/terraform$(RESET)"
 	terraform fmt -recursive
 .PHONY: fmt/terraform

 fmt/shfmt: $(SHELL_SRC_FILES)
-	echo "--- shfmt"
+	echo "$(GREEN)==>$(RESET) $(BOLD)fmt/shfmt$(RESET)"
 # Only do diff check in CI, errors on diff.
 ifdef CI
 	shfmt -d $(SHELL_SRC_FILES)
@@ -414,7 +429,7 @@ else
 endif
 .PHONY: fmt/shfmt

-lint: lint/shellcheck lint/go lint/ts lint/helm lint/site-icons
+lint: lint/shellcheck lint/go lint/ts lint/examples lint/helm lint/site-icons
 .PHONY: lint

 lint/site-icons:
@@ -433,6 +448,10 @@ lint/go:
 	golangci-lint run
 .PHONY: lint/go

+lint/examples:
+	go run ./scripts/examplegen/main.go -lint
+.PHONY: lint/examples
+
 # Use shfmt to determine the shell files, takes editorconfig into consideration.
 lint/shellcheck: $(SHELL_SRC_FILES)
 	echo "--- shellcheck"
@@ -470,12 +489,16 @@ gen: \
 	coderd/apidoc/swagger.json \
 	.prettierignore.include \
 	.prettierignore \
+	provisioner/terraform/testdata/version \
 	site/.prettierrc.yaml \
 	site/.prettierignore \
 	site/.eslintignore \
 	site/e2e/provisionerGenerated.ts \
 	site/src/theme/icons.json \
-	examples/examples.gen.json
+	examples/examples.gen.json \
+	tailnet/tailnettest/coordinatormock.go \
+	tailnet/tailnettest/coordinateemock.go \
+	tailnet/tailnettest/multiagentmock.go
 .PHONY: gen

 # Mark all generated files as fresh so make thinks they're up-to-date. This is
@@ -502,6 +525,9 @@ gen/mark-fresh:
 		site/e2e/provisionerGenerated.ts \
 		site/src/theme/icons.json \
 		examples/examples.gen.json \
+		tailnet/tailnettest/coordinatormock.go \
+		tailnet/tailnettest/coordinateemock.go \
+		tailnet/tailnettest/multiagentmock.go \
 	"
 	for file in $$files; do
 		echo "$$file"
@@ -529,6 +555,9 @@ coderd/database/querier.go: coderd/database/sqlc.yaml coderd/database/dump.sql $
 coderd/database/dbmock/dbmock.go: coderd/database/db.go coderd/database/querier.go
 	go generate ./coderd/database/dbmock/

+tailnet/tailnettest/coordinatormock.go tailnet/tailnettest/multiagentmock.go tailnet/tailnettest/coordinateemock.go: tailnet/coordinator.go tailnet/multiagent.go
+	go generate ./tailnet/tailnettest/
+
 tailnet/proto/tailnet.pb.go: tailnet/proto/tailnet.proto
 	protoc \
 		--go_out=. \
@@ -563,7 +592,8 @@ provisionerd/proto/provisionerd.pb.go: provisionerd/proto/provisionerd.proto

 site/src/api/typesGenerated.ts: $(wildcard scripts/apitypings/*) $(shell find ./codersdk $(FIND_EXCLUSIONS) -type f -name '*.go')
 	go run ./scripts/apitypings/ > $@
-	pnpm run format:write:only "$@"
+	./scripts/pnpm_install.sh
+	pnpm exec prettier --write "$@"

 site/e2e/provisionerGenerated.ts: provisionerd/proto/provisionerd.pb.go provisionersdk/proto/provisioner.pb.go
 	cd site
@@ -572,7 +602,8 @@ site/e2e/provisionerGenerated.ts: provisionerd/proto/provisionerd.pb.go provisio

 site/src/theme/icons.json: $(wildcard scripts/gensite/*) $(wildcard site/static/icon/*)
 	go run ./scripts/gensite/ -icons "$@"
-	pnpm run format:write:only "$@"
+	./scripts/pnpm_install.sh
+	pnpm exec prettier --write "$@"

 examples/examples.gen.json: scripts/examplegen/main.go examples/examples.go $(shell find ./examples/templates)
 	go run ./scripts/examplegen/main.go > examples/examples.gen.json
@@ -582,19 +613,23 @@ coderd/rbac/object_gen.go: scripts/rbacgen/main.go coderd/rbac/object.go

 docs/admin/prometheus.md: scripts/metricsdocgen/main.go scripts/metricsdocgen/metrics
 	go run scripts/metricsdocgen/main.go
-	pnpm run format:write:only ./docs/admin/prometheus.md
+	./scripts/pnpm_install.sh
+	pnpm exec prettier --write ./docs/admin/prometheus.md

 docs/cli.md: scripts/clidocgen/main.go examples/examples.gen.json $(GO_SRC_FILES)
 	CI=true BASE_PATH="." go run ./scripts/clidocgen
-	pnpm run format:write:only ./docs/cli.md ./docs/cli/*.md ./docs/manifest.json
+	./scripts/pnpm_install.sh
+	pnpm exec prettier --write ./docs/cli.md ./docs/cli/*.md ./docs/manifest.json

-docs/admin/audit-logs.md: scripts/auditdocgen/main.go enterprise/audit/table.go coderd/rbac/object_gen.go
+docs/admin/audit-logs.md: coderd/database/querier.go scripts/auditdocgen/main.go enterprise/audit/table.go coderd/rbac/object_gen.go
 	go run scripts/auditdocgen/main.go
-	pnpm run format:write:only ./docs/admin/audit-logs.md
+	./scripts/pnpm_install.sh
+	pnpm exec prettier --write ./docs/admin/audit-logs.md

 coderd/apidoc/swagger.json: $(shell find ./scripts/apidocgen $(FIND_EXCLUSIONS) -type f) $(wildcard coderd/*.go) $(wildcard enterprise/coderd/*.go) $(wildcard codersdk/*.go) $(wildcard enterprise/wsproxy/wsproxysdk/*.go) $(DB_GEN_FILES) .swaggo docs/manifest.json coderd/rbac/object_gen.go
 	./scripts/apidocgen/generate.sh
-	pnpm run format:write:only ./docs/api ./docs/manifest.json ./coderd/apidoc/swagger.json
+	./scripts/pnpm_install.sh
+	pnpm exec prettier --write ./docs/api ./docs/manifest.json ./coderd/apidoc/swagger.json

 update-golden-files: \
 	cli/testdata/.gen-golden \
@@ -609,7 +644,7 @@ update-golden-files: \
 .PHONY: update-golden-files

 cli/testdata/.gen-golden: $(wildcard cli/testdata/*.golden) $(wildcard cli/*.tpl) $(GO_SRC_FILES) $(wildcard cli/*_test.go)
-	go test ./cli -run="Test(CommandHelp|ServerYAML)" -update
+	go test ./cli -run="Test(CommandHelp|ServerYAML|ErrorExamples)" -update
 	touch "$@"

 enterprise/cli/testdata/.gen-golden: $(wildcard enterprise/cli/testdata/*.golden) $(wildcard cli/*.tpl) $(GO_SRC_FILES) $(wildcard enterprise/cli/*_test.go)
@@ -640,6 +675,12 @@ provisioner/terraform/testdata/.gen-golden: $(wildcard provisioner/terraform/tes
 	go test ./provisioner/terraform -run="Test.*Golden$$" -update
 	touch "$@"

+provisioner/terraform/testdata/version:
+	if [[ "$(shell cat provisioner/terraform/testdata/version.txt)" != "$(shell terraform version -json | jq -r '.terraform_version')" ]]; then
+		./provisioner/terraform/testdata/generate.sh
+	fi
+.PHONY: provisioner/terraform/testdata/version
+
 scripts/ci-report/testdata/.gen-golden: $(wildcard scripts/ci-report/testdata/*) $(wildcard scripts/ci-report/*.go)
 	go test ./scripts/ci-report -run=TestOutputMatchesGoldenFile -update
 	touch "$@"
@@ -708,6 +749,27 @@ test:
 	gotestsum --format standard-quiet -- -v -short -count=1 ./...
 .PHONY: test

+# sqlc-cloud-is-setup will fail if no SQLc auth token is set. Use this as a
+# dependency for any sqlc-cloud related targets.
+sqlc-cloud-is-setup:
+	if [[ "$(SQLC_AUTH_TOKEN)" == "" ]]; then
+		echo "ERROR: 'SQLC_AUTH_TOKEN' must be set to auth with sqlc cloud before running verify." 1>&2
+		exit 1
+	fi
+.PHONY: sqlc-cloud-is-setup
+
+sqlc-push: sqlc-cloud-is-setup test-postgres-docker
+	echo "--- sqlc push"
+	SQLC_DATABASE_URL="postgresql://postgres:postgres@localhost:5432/$(shell go run scripts/migrate-ci/main.go)" \
+	sqlc push -f coderd/database/sqlc.yaml && echo "Passed sqlc push"
+.PHONY: sqlc-push
+
+sqlc-verify: sqlc-cloud-is-setup test-postgres-docker
+	echo "--- sqlc verify"
+	SQLC_DATABASE_URL="postgresql://postgres:postgres@localhost:5432/$(shell go run scripts/migrate-ci/main.go)" \
+	sqlc verify -f coderd/database/sqlc.yaml && echo "Passed sqlc verify"
+.PHONY: sqlc-verify
+
 sqlc-vet: test-postgres-docker
 	echo "--- sqlc vet"
 	SQLC_DATABASE_URL="postgresql://postgres:postgres@localhost:5432/$(shell go run scripts/migrate-ci/main.go)" \
@@ -729,6 +791,15 @@ test-postgres: test-postgres-docker
 		-count=1
 .PHONY: test-postgres

+test-migrations: test-postgres-docker
+	echo "--- test migrations"
+	set -euo pipefail
+	COMMIT_FROM=$(shell git rev-parse --short HEAD)
+	COMMIT_TO=$(shell git rev-parse --short main)
+	echo "DROP DATABASE IF EXISTS migrate_test_$${COMMIT_FROM}; CREATE DATABASE migrate_test_$${COMMIT_FROM};" | psql 'postgresql://postgres:postgres@localhost:5432/postgres?sslmode=disable'
+	go run ./scripts/migrate-test/main.go --from="$$COMMIT_FROM" --to="$$COMMIT_TO" --postgres-url="postgresql://postgres:postgres@localhost:5432/migrate_test_$${COMMIT_FROM}?sslmode=disable"
+
+# NOTE: we set --memory to the same size as a GitHub runner.
 test-postgres-docker:
 	docker rm -f test-postgres-docker || true
 	docker run \
@@ -741,6 +812,7 @@ test-postgres-docker:
 		--name test-postgres-docker \
 		--restart no \
 		--detach \
+		--memory 16GB \
 		gcr.io/coder-dev-1/postgres:13 \
 		-c shared_buffers=1GB \
 		-c work_mem=1GB \
@@ -7,7 +7,7 @@
  </a>

  <h1>
-  Self-Hosted Remote Development Environments
+  Self-Hosted Cloud Development Environments
  </h1>

  <a href="https://coder.com#gh-light-mode-only">
@@ -23,7 +23,6 @@
 [Quickstart](#quickstart) | [Docs](https://coder.com/docs) | [Why Coder](https://coder.com/why) | [Enterprise](https://coder.com/docs/v2/latest/enterprise)

 [![discord](https://img.shields.io/discord/747933592273027093?label=discord)](https://discord.gg/coder)
-[![codecov](https://codecov.io/gh/coder/coder/branch/main/graph/badge.svg?token=TNLW3OAP6G)](https://codecov.io/gh/coder/coder)
 [![release](https://img.shields.io/github/v/release/coder/coder)](https://github.com/coder/coder/releases/latest)
 [![godoc](https://pkg.go.dev/badge/github.com/coder/coder.svg)](https://pkg.go.dev/github.com/coder/coder)
 [![Go Report Card](https://goreportcard.com/badge/github.com/coder/coder)](https://goreportcard.com/report/github.com/coder/coder)
@@ -31,9 +30,9 @@

 </div>

-[Coder](https://coder.com) enables organizations to set up development environments in the cloud. Environments are defined with Terraform, connected through a secure high-speed Wireguard® tunnel, and are automatically shut down when not in use to save on costs. Coder gives engineering teams the flexibility to use the cloud for workloads that are most beneficial to them.
+[Coder](https://coder.com) enables organizations to set up development environments in their public or private cloud infrastructure. Cloud development environments are defined with Terraform, connected through a secure high-speed Wireguard® tunnel, and are automatically shut down when not in use to save on costs. Coder gives engineering teams the flexibility to use the cloud for workloads that are most beneficial to them.

- Define development environments in Terraform
+- Define cloud development environments in Terraform
  - EC2 VMs, Kubernetes Pods, Docker Containers, etc.
 - Automatically shutdown idle resources to save on costs
 - Onboard developers in seconds instead of days
@@ -44,7 +43,7 @@

 ## Quickstart

-The most convenient way to try Coder is to install it on your local machine and experiment with provisioning development environments using Docker (works on Linux, macOS, and Windows).
+The most convenient way to try Coder is to install it on your local machine and experiment with provisioning cloud development environments using Docker (works on Linux, macOS, and Windows).

 ```
 # First, install Coder
@@ -53,8 +52,8 @@ curl -L https://coder.com/install.sh | sh
 # Start the Coder server (caches data in ~/.cache/coder)
 coder server

-# Navigate to http://localhost:3000 to create your initial user
-# Create a Docker template, and provision a workspace
+# Navigate to http://localhost:3000 to create your initial user,
+# create a Docker template, and provision a workspace
 ```

 ## Install
@@ -68,11 +67,11 @@ Releases.
 curl -L https://coder.com/install.sh | sh
 ```

-You can run the install script with `--dry-run` to see the commands that will be used to install without executing them. You can modify the installation process by including flags. Run the install script with `--help` for reference.
+You can run the install script with `--dry-run` to see the commands that will be used to install without executing them. Run the install script with `--help` for additional flags.

 > See [install](https://coder.com/docs/v2/latest/install) for additional methods.

-Once installed, you can start a production deployment<sup>1</sup> with a single command:
+Once installed, you can start a production deployment with a single command:

 ```shell
 # Automatically sets up an external access URL on *.try.coder.app
@@ -82,8 +81,6 @@ coder server
 coder server --postgres-url <url> --access-url <url>
 ```

-> <sup>1</sup> For production deployments, set up an external PostgreSQL instance for reliability.
-
 Use `coder --help` to get a list of flags and environment variables. Use our [install guides](https://coder.com/docs/v2/latest/install) for a full walkthrough.

 ## Documentation
@@ -96,19 +93,13 @@ Browse our docs [here](https://coder.com/docs/v2) or visit a specific section be
 - [**Administration**](https://coder.com/docs/v2/latest/admin): Learn how to operate Coder
 - [**Enterprise**](https://coder.com/docs/v2/latest/enterprise): Learn about our paid features built for large teams

-## Community and Support
+## Support

 Feel free to [open an issue](https://github.com/coder/coder/issues/new) if you have questions, run into bugs, or have a feature request.

 [Join our Discord](https://discord.gg/coder) to provide feedback on in-progress features, and chat with the community using Coder!

-## Contributing
-
-Contributions are welcome! Read the [contributing docs](https://coder.com/docs/v2/latest/CONTRIBUTING) to get started.
-
-Find our list of contributors [here](https://github.com/coder/coder/graphs/contributors).
-
-## Related
+## Integrations

 We are always working on new integrations. Feel free to open an issue to request an integration. Contributions are welcome in any official or community repositories.

@@ -116,10 +107,18 @@ We are always working on new integrations. Feel free to open an issue to request

 - [**VS Code Extension**](https://marketplace.visualstudio.com/items?itemName=coder.coder-remote): Open any Coder workspace in VS Code with a single click
 - [**JetBrains Gateway Extension**](https://plugins.jetbrains.com/plugin/19620-coder): Open any Coder workspace in JetBrains Gateway with a single click
+- [**Dev Container Builder**](https://github.com/coder/envbuilder): Build development environments using `devcontainer.json` on Docker, Kubernetes, and OpenShift
+- [**Module Registry**](https://registry.coder.com): Extend development environments with common use-cases
+- [**Kubernetes Log Stream**](https://github.com/coder/coder-logstream-kube): Stream Kubernetes Pod events to the Coder startup logs
 - [**Self-Hosted VS Code Extension Marketplace**](https://github.com/coder/code-marketplace): A private extension marketplace that works in restricted or airgapped networks integrating with [code-server](https://github.com/coder/code-server).

 ### Community

 - [**Provision Coder with Terraform**](https://github.com/ElliotG/coder-oss-tf): Provision Coder on Google GKE, Azure AKS, AWS EKS, DigitalOcean DOKS, IBMCloud K8s, OVHCloud K8s, and Scaleway K8s Kapsule with Terraform
- [**Coder GitHub Action**](https://github.com/marketplace/actions/update-coder-template): A GitHub Action that updates Coder templates
- [**Various Templates**](./examples/templates/community-templates.md): Hetzner Cloud, Docker in Docker, and other templates the community has built.
+- [**Coder Template GitHub Action**](https://github.com/marketplace/actions/update-coder-template): A GitHub Action that updates Coder templates
+
+## Contributing
+
+We are always happy to see new contributors to Coder. If you are new to the Coder codebase, we have
+[a guide on how to get started](https://coder.com/docs/v2/latest/CONTRIBUTING). We'd love to see your
+contributions!
@@ -5,9 +5,9 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
-	"math/rand"
 	"net"
 	"net/http"
 	"net/http/httptest"
@@ -27,7 +27,6 @@ import (
 	"time"

 	"github.com/bramvdbogaerde/go-scp"
-	"github.com/golang/mock/gomock"
 	"github.com/google/uuid"
 	"github.com/pion/udp"
 	"github.com/pkg/sftp"
@@ -37,6 +36,7 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"go.uber.org/goleak"
+	"go.uber.org/mock/gomock"
 	"golang.org/x/crypto/ssh"
 	"golang.org/x/exp/slices"
 	"golang.org/x/xerrors"
@@ -46,14 +46,16 @@ import (
 	"cdr.dev/slog"
 	"cdr.dev/slog/sloggers/sloghuman"
 	"cdr.dev/slog/sloggers/slogtest"
-
 	"github.com/coder/coder/v2/agent"
 	"github.com/coder/coder/v2/agent/agentproc"
 	"github.com/coder/coder/v2/agent/agentproc/agentproctest"
 	"github.com/coder/coder/v2/agent/agentssh"
 	"github.com/coder/coder/v2/agent/agenttest"
+	"github.com/coder/coder/v2/agent/proto"
 	"github.com/coder/coder/v2/codersdk"
 	"github.com/coder/coder/v2/codersdk/agentsdk"
+	"github.com/coder/coder/v2/codersdk/workspacesdk"
+	"github.com/coder/coder/v2/cryptorand"
 	"github.com/coder/coder/v2/pty/ptytest"
 	"github.com/coder/coder/v2/tailnet"
 	"github.com/coder/coder/v2/tailnet/tailnettest"
@@ -85,11 +87,11 @@ func TestAgent_Stats_SSH(t *testing.T) {
 	err = session.Shell()
 	require.NoError(t, err)

-	var s *agentsdk.Stats
+	var s *proto.Stats
 	require.Eventuallyf(t, func() bool {
 		var ok bool
 		s, ok = <-stats
-		return ok && s.ConnectionCount > 0 && s.RxBytes > 0 && s.TxBytes > 0 && s.SessionCountSSH == 1
+		return ok && s.ConnectionCount > 0 && s.RxBytes > 0 && s.TxBytes > 0 && s.SessionCountSsh == 1
 	}, testutil.WaitLong, testutil.IntervalFast,
 		"never saw stats: %+v", s,
 	)
@@ -111,18 +113,18 @@ func TestAgent_Stats_ReconnectingPTY(t *testing.T) {
 	require.NoError(t, err)
 	defer ptyConn.Close()

-	data, err := json.Marshal(codersdk.ReconnectingPTYRequest{
+	data, err := json.Marshal(workspacesdk.ReconnectingPTYRequest{
 		Data: "echo test\r\n",
 	})
 	require.NoError(t, err)
 	_, err = ptyConn.Write(data)
 	require.NoError(t, err)

-	var s *agentsdk.Stats
+	var s *proto.Stats
 	require.Eventuallyf(t, func() bool {
 		var ok bool
 		s, ok = <-stats
-		return ok && s.ConnectionCount > 0 && s.RxBytes > 0 && s.TxBytes > 0 && s.SessionCountReconnectingPTY == 1
+		return ok && s.ConnectionCount > 0 && s.RxBytes > 0 && s.TxBytes > 0 && s.SessionCountReconnectingPty == 1
 	}, testutil.WaitLong, testutil.IntervalFast,
 		"never saw stats: %+v", s,
 	)
@@ -174,19 +176,19 @@ func TestAgent_Stats_Magic(t *testing.T) {
 		require.NoError(t, err)
 		err = session.Shell()
 		require.NoError(t, err)
-		var s *agentsdk.Stats
 		require.Eventuallyf(t, func() bool {
-			var ok bool
-			s, ok = <-stats
+			s, ok := <-stats
+			t.Logf("got stats: ok=%t, ConnectionCount=%d, RxBytes=%d, TxBytes=%d, SessionCountVSCode=%d, ConnectionMedianLatencyMS=%f",
+				ok, s.ConnectionCount, s.RxBytes, s.TxBytes, s.SessionCountVscode, s.ConnectionMedianLatencyMs)
 			return ok && s.ConnectionCount > 0 && s.RxBytes > 0 && s.TxBytes > 0 &&
 				// Ensure that the connection didn't count as a "normal" SSH session.
 				// This was a special one, so it should be labeled specially in the stats!
-				s.SessionCountVSCode == 1 &&
+				s.SessionCountVscode == 1 &&
 				// Ensure that connection latency is being counted!
 				// If it isn't, it's set to -1.
-				s.ConnectionMedianLatencyMS >= 0
+				s.ConnectionMedianLatencyMs >= 0
 		}, testutil.WaitLong, testutil.IntervalFast,
-			"never saw stats: %+v", s,
+			"never saw stats",
 		)
 		// The shell will automatically exit if there is no stdin!
 		_ = stdin.Close()
@@ -240,14 +242,14 @@ func TestAgent_Stats_Magic(t *testing.T) {
 			_ = tunneledConn.Close()
 		})

-		var s *agentsdk.Stats
 		require.Eventuallyf(t, func() bool {
-			var ok bool
-			s, ok = <-stats
+			s, ok := <-stats
+			t.Logf("got stats with conn open: ok=%t, ConnectionCount=%d, SessionCountJetBrains=%d",
+				ok, s.ConnectionCount, s.SessionCountJetbrains)
 			return ok && s.ConnectionCount > 0 &&
-				s.SessionCountJetBrains == 1
+				s.SessionCountJetbrains == 1
 		}, testutil.WaitLong, testutil.IntervalFast,
-			"never saw stats with conn open: %+v", s,
+			"never saw stats with conn open",
 		)

 		// Kill the server and connection after checking for the echo.
@@ -256,12 +258,13 @@ func TestAgent_Stats_Magic(t *testing.T) {
 		_ = tunneledConn.Close()

 		require.Eventuallyf(t, func() bool {
-			var ok bool
-			s, ok = <-stats
-			return ok && s.ConnectionCount == 0 &&
-				s.SessionCountJetBrains == 0
+			s, ok := <-stats
+			t.Logf("got stats after disconnect %t, %d",
+				ok, s.SessionCountJetbrains)
+			return ok &&
+				s.SessionCountJetbrains == 0
 		}, testutil.WaitLong, testutil.IntervalFast,
-			"never saw stats after conn closes: %+v", s,
+			"never saw stats after conn closes",
 		)
 	})
 }
@@ -279,6 +282,91 @@ func TestAgent_SessionExec(t *testing.T) {
 	require.Equal(t, "test", strings.TrimSpace(string(output)))
 }

+//nolint:tparallel // Sub tests need to run sequentially.
+func TestAgent_Session_EnvironmentVariables(t *testing.T) {
+	t.Parallel()
+
+	tmpdir := t.TempDir()
+
+	// Defined by the coder script runner, hardcoded here since we don't
+	// have a reference to it.
+	scriptBinDir := filepath.Join(tmpdir, "coder-script-data", "bin")
+
+	manifest := agentsdk.Manifest{
+		EnvironmentVariables: map[string]string{
+			"MY_MANIFEST":         "true",
+			"MY_OVERRIDE":         "false",
+			"MY_SESSION_MANIFEST": "false",
+		},
+	}
+	banner := codersdk.ServiceBannerConfig{}
+	session := setupSSHSession(t, manifest, banner, nil, func(_ *agenttest.Client, opts *agent.Options) {
+		opts.ScriptDataDir = tmpdir
+		opts.EnvironmentVariables["MY_OVERRIDE"] = "true"
+	})
+
+	err := session.Setenv("MY_SESSION_MANIFEST", "true")
+	require.NoError(t, err)
+	err = session.Setenv("MY_SESSION", "true")
+	require.NoError(t, err)
+
+	command := "sh"
+	echoEnv := func(t *testing.T, w io.Writer, env string) {
+		if runtime.GOOS == "windows" {
+			_, err := fmt.Fprintf(w, "echo %%%s%%\r\n", env)
+			require.NoError(t, err)
+		} else {
+			_, err := fmt.Fprintf(w, "echo $%s\n", env)
+			require.NoError(t, err)
+		}
+	}
+	if runtime.GOOS == "windows" {
+		command = "cmd.exe"
+	}
+	stdin, err := session.StdinPipe()
+	require.NoError(t, err)
+	defer stdin.Close()
+	stdout, err := session.StdoutPipe()
+	require.NoError(t, err)
+
+	err = session.Start(command)
+	require.NoError(t, err)
+
+	// Context is fine here since we're not doing a parallel subtest.
+	ctx := testutil.Context(t, testutil.WaitLong)
+	go func() {
+		<-ctx.Done()
+		_ = session.Close()
+	}()
+
+	s := bufio.NewScanner(stdout)
+
+	//nolint:paralleltest // These tests need to run sequentially.
+	for k, partialV := range map[string]string{
+		"CODER":               "true",  // From the agent.
+		"MY_MANIFEST":         "true",  // From the manifest.
+		"MY_OVERRIDE":         "true",  // From the agent environment variables option, overrides manifest.
+		"MY_SESSION_MANIFEST": "false", // From the manifest, overrides session env.
+		"MY_SESSION":          "true",  // From the session.
+		"PATH":                scriptBinDir + string(filepath.ListSeparator),
+	} {
+		t.Run(k, func(t *testing.T) {
+			echoEnv(t, stdin, k)
+			// Windows is unreliable, so keep scanning until we find a match.
+			for s.Scan() {
+				got := strings.TrimSpace(s.Text())
+				t.Logf("%s=%s", k, got)
+				if strings.Contains(got, partialV) {
+					break
+				}
+			}
+			if err := s.Err(); !errors.Is(err, io.EOF) {
+				require.NoError(t, err)
+			}
+		})
+	}
+}
+
 func TestAgent_GitSSH(t *testing.T) {
 	t.Parallel()
 	session := setupSSHSession(t, agentsdk.Manifest{}, codersdk.ServiceBannerConfig{}, nil)
@@ -750,7 +838,7 @@ func TestAgent_TCPRemoteForwarding(t *testing.T) {
 	var ll net.Listener
 	var err error
 	for {
-		randomPort = pickRandomPort()
+		randomPort = testutil.RandomPortNoListen(t)
 		addr := net.TCPAddrFromAddrPort(netip.AddrPortFrom(localhost, randomPort))
 		ll, err = sshClient.ListenTCP(addr)
 		if err != nil {
@@ -925,7 +1013,7 @@ func TestAgent_EnvironmentVariableExpansion(t *testing.T) {
 func TestAgent_CoderEnvVars(t *testing.T) {
 	t.Parallel()

-	for _, key := range []string{"CODER"} {
+	for _, key := range []string{"CODER", "CODER_WORKSPACE_NAME", "CODER_WORKSPACE_AGENT_NAME"} {
 		key := key
 		t.Run(key, func(t *testing.T) {
 			t.Parallel()
@@ -1345,9 +1433,10 @@ func TestAgent_Lifecycle(t *testing.T) {
 					RunOnStop: true,
 				}},
 			},
-			make(chan *agentsdk.Stats, 50),
+			make(chan *proto.Stats, 50),
 			tailnet.NewCoordinator(logger),
 		)
+		defer client.Close()

 		fs := afero.NewMemMapFs()
 		agent := agent.New(agent.Options{
@@ -1392,56 +1481,52 @@ func TestAgent_Startup(t *testing.T) {

 	t.Run("EmptyDirectory", func(t *testing.T) {
 		t.Parallel()
+		ctx := testutil.Context(t, testutil.WaitShort)

 		_, client, _, _, _ := setupAgent(t, agentsdk.Manifest{
 			Directory: "",
 		}, 0)
-		assert.Eventually(t, func() bool {
-			return client.GetStartup().Version != ""
-		}, testutil.WaitShort, testutil.IntervalFast)
-		require.Equal(t, "", client.GetStartup().ExpandedDirectory)
+		startup := testutil.RequireRecvCtx(ctx, t, client.GetStartup())
+		require.Equal(t, "", startup.GetExpandedDirectory())
 	})

 	t.Run("HomeDirectory", func(t *testing.T) {
 		t.Parallel()
+		ctx := testutil.Context(t, testutil.WaitShort)

 		_, client, _, _, _ := setupAgent(t, agentsdk.Manifest{
 			Directory: "~",
 		}, 0)
-		assert.Eventually(t, func() bool {
-			return client.GetStartup().Version != ""
-		}, testutil.WaitShort, testutil.IntervalFast)
+		startup := testutil.RequireRecvCtx(ctx, t, client.GetStartup())
 		homeDir, err := os.UserHomeDir()
 		require.NoError(t, err)
-		require.Equal(t, homeDir, client.GetStartup().ExpandedDirectory)
+		require.Equal(t, homeDir, startup.GetExpandedDirectory())
 	})

 	t.Run("NotAbsoluteDirectory", func(t *testing.T) {
 		t.Parallel()
+		ctx := testutil.Context(t, testutil.WaitShort)

 		_, client, _, _, _ := setupAgent(t, agentsdk.Manifest{
 			Directory: "coder/coder",
 		}, 0)
-		assert.Eventually(t, func() bool {
-			return client.GetStartup().Version != ""
-		}, testutil.WaitShort, testutil.IntervalFast)
+		startup := testutil.RequireRecvCtx(ctx, t, client.GetStartup())
 		homeDir, err := os.UserHomeDir()
 		require.NoError(t, err)
-		require.Equal(t, filepath.Join(homeDir, "coder/coder"), client.GetStartup().ExpandedDirectory)
+		require.Equal(t, filepath.Join(homeDir, "coder/coder"), startup.GetExpandedDirectory())
 	})

 	t.Run("HomeEnvironmentVariable", func(t *testing.T) {
 		t.Parallel()
+		ctx := testutil.Context(t, testutil.WaitShort)

 		_, client, _, _, _ := setupAgent(t, agentsdk.Manifest{
 			Directory: "$HOME",
 		}, 0)
-		assert.Eventually(t, func() bool {
-			return client.GetStartup().Version != ""
-		}, testutil.WaitShort, testutil.IntervalFast)
+		startup := testutil.RequireRecvCtx(ctx, t, client.GetStartup())
 		homeDir, err := os.UserHomeDir()
 		require.NoError(t, err)
-		require.Equal(t, homeDir, client.GetStartup().ExpandedDirectory)
+		require.Equal(t, homeDir, startup.GetExpandedDirectory())
 	})
 }

@@ -1521,7 +1606,7 @@ func TestAgent_ReconnectingPTY(t *testing.T) {
 			require.NoError(t, tr1.ReadUntil(ctx, matchPrompt), "find prompt")
 			require.NoError(t, tr2.ReadUntil(ctx, matchPrompt), "find prompt")

-			data, err := json.Marshal(codersdk.ReconnectingPTYRequest{
+			data, err := json.Marshal(workspacesdk.ReconnectingPTYRequest{
 				Data: "echo test\r",
 			})
 			require.NoError(t, err)
@@ -1549,7 +1634,7 @@ func TestAgent_ReconnectingPTY(t *testing.T) {
 			require.NoError(t, tr3.ReadUntil(ctx, matchEchoOutput), "find echo output")

 			// Exit should cause the connection to close.
-			data, err = json.Marshal(codersdk.ReconnectingPTYRequest{
+			data, err = json.Marshal(workspacesdk.ReconnectingPTYRequest{
 				Data: "exit\r",
 			})
 			require.NoError(t, err)
@@ -1635,9 +1720,10 @@ func TestAgent_Dial(t *testing.T) {
 			go func() {
 				defer close(done)
 				c, err := l.Accept()
-				assert.NoError(t, err, "accept connection")
-				defer c.Close()
-				testAccept(ctx, t, c)
+				if assert.NoError(t, err, "accept connection") {
+					defer c.Close()
+					testAccept(ctx, t, c)
+				}
 			}()

 			//nolint:dogsled
@@ -1662,11 +1748,13 @@ func TestAgent_UpdatedDERP(t *testing.T) {
 	require.NotNil(t, originalDerpMap)

 	coordinator := tailnet.NewCoordinator(logger)
-	defer func() {
+	// use t.Cleanup so the coordinator closing doesn't deadlock with in-memory
+	// coordination
+	t.Cleanup(func() {
 		_ = coordinator.Close()
-	}()
+	})
 	agentID := uuid.New()
-	statsCh := make(chan *agentsdk.Stats, 50)
+	statsCh := make(chan *proto.Stats, 50)
 	fs := afero.NewMemMapFs()
 	client := agenttest.NewClient(t,
 		logger.Named("agent"),
@@ -1679,49 +1767,57 @@ func TestAgent_UpdatedDERP(t *testing.T) {
 		statsCh,
 		coordinator,
 	)
-	closer := agent.New(agent.Options{
+	t.Cleanup(func() {
+		t.Log("closing client")
+		client.Close()
+	})
+	uut := agent.New(agent.Options{
 		Client:                 client,
 		Filesystem:             fs,
 		Logger:                 logger.Named("agent"),
 		ReconnectingPTYTimeout: time.Minute,
 	})
-	defer func() {
-		_ = closer.Close()
-	}()
+	t.Cleanup(func() {
+		t.Log("closing agent")
+		_ = uut.Close()
+	})

 	// Setup a client connection.
-	newClientConn := func(derpMap *tailcfg.DERPMap) *codersdk.WorkspaceAgentConn {
+	newClientConn := func(derpMap *tailcfg.DERPMap, name string) *workspacesdk.AgentConn {
 		conn, err := tailnet.NewConn(&tailnet.Options{
 			Addresses: []netip.Prefix{netip.PrefixFrom(tailnet.IP(), 128)},
 			DERPMap:   derpMap,
-			Logger:    logger.Named("client"),
+			Logger:    logger.Named(name),
 		})
 		require.NoError(t, err)
-		clientConn, serverConn := net.Pipe()
-		serveClientDone := make(chan struct{})
 		t.Cleanup(func() {
-			_ = clientConn.Close()
-			_ = serverConn.Close()
+			t.Logf("closing conn %s", name)
 			_ = conn.Close()
-			<-serveClientDone
 		})
-		go func() {
-			defer close(serveClientDone)
-			err := coordinator.ServeClient(serverConn, uuid.New(), agentID)
-			assert.NoError(t, err)
-		}()
-		sendNode, _ := tailnet.ServeCoordinator(clientConn, func(nodes []*tailnet.Node) error {
-			return conn.UpdateNodes(nodes, false)
+		testCtx, testCtxCancel := context.WithCancel(context.Background())
+		t.Cleanup(testCtxCancel)
+		clientID := uuid.New()
+		coordination := tailnet.NewInMemoryCoordination(
+			testCtx, logger,
+			clientID, agentID,
+			coordinator, conn)
+		t.Cleanup(func() {
+			t.Logf("closing coordination %s", name)
+			err := coordination.Close()
+			if err != nil {
+				t.Logf("error closing in-memory coordination: %s", err.Error())
+			}
+			t.Logf("closed coordination %s", name)
 		})
-		conn.SetNodeCallback(sendNode)
 		// Force DERP.
 		conn.SetBlockEndpoints(true)

-		sdkConn := codersdk.NewWorkspaceAgentConn(conn, codersdk.WorkspaceAgentConnOptions{
+		sdkConn := workspacesdk.NewAgentConn(conn, workspacesdk.AgentConnOptions{
 			AgentID:   agentID,
-			CloseFunc: func() error { return codersdk.ErrSkipClose },
+			CloseFunc: func() error { return workspacesdk.ErrSkipClose },
 		})
 		t.Cleanup(func() {
+			t.Logf("closing sdkConn %s", name)
 			_ = sdkConn.Close()
 		})
 		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
@@ -1732,7 +1828,7 @@ func TestAgent_UpdatedDERP(t *testing.T) {

 		return sdkConn
 	}
-	conn1 := newClientConn(originalDerpMap)
+	conn1 := newClientConn(originalDerpMap, "client1")

 	// Change the DERP map.
 	newDerpMap, _ := tailnettest.RunDERPAndSTUN(t)
@@ -1747,31 +1843,36 @@ func TestAgent_UpdatedDERP(t *testing.T) {
 	}

 	// Push a new DERP map to the agent.
-	err := client.PushDERPMapUpdate(agentsdk.DERPMapUpdate{
-		DERPMap: newDerpMap,
-	})
+	err := client.PushDERPMapUpdate(newDerpMap)
 	require.NoError(t, err)
+	t.Logf("pushed DERPMap update to agent")

 	require.Eventually(t, func() bool {
-		conn := closer.TailnetConn()
+		conn := uut.TailnetConn()
 		if conn == nil {
 			return false
 		}
 		regionIDs := conn.DERPMap().RegionIDs()
-		return len(regionIDs) == 1 && regionIDs[0] == 2 && conn.Node().PreferredDERP == 2
+		preferredDERP := conn.Node().PreferredDERP
+		t.Logf("agent Conn DERPMap with regionIDs %v, PreferredDERP %d", regionIDs, preferredDERP)
+		return len(regionIDs) == 1 && regionIDs[0] == 2 && preferredDERP == 2
 	}, testutil.WaitLong, testutil.IntervalFast)
+	t.Logf("agent got the new DERPMap")

 	// Connect from a second client and make sure it uses the new DERP map.
-	conn2 := newClientConn(newDerpMap)
+	conn2 := newClientConn(newDerpMap, "client2")
 	require.Equal(t, []int{2}, conn2.DERPMap().RegionIDs())
+	t.Log("conn2 got the new DERPMap")

 	// If the first client gets a DERP map update, it should be able to
 	// reconnect just fine.
 	conn1.SetDERPMap(newDerpMap)
 	require.Equal(t, []int{2}, conn1.DERPMap().RegionIDs())
+	t.Log("set the new DERPMap on conn1")
 	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
 	defer cancel()
 	require.True(t, conn1.AwaitReachable(ctx))
+	t.Log("conn1 reached agent with new DERP")
 }

 func TestAgent_Speedtest(t *testing.T) {
@@ -1802,7 +1903,7 @@ func TestAgent_Reconnect(t *testing.T) {
 	defer coordinator.Close()

 	agentID := uuid.New()
-	statsCh := make(chan *agentsdk.Stats, 50)
+	statsCh := make(chan *proto.Stats, 50)
 	derpMap, _ := tailnettest.RunDERPAndSTUN(t)
 	client := agenttest.NewClient(t,
 		logger,
@@ -1813,6 +1914,7 @@ func TestAgent_Reconnect(t *testing.T) {
 		statsCh,
 		coordinator,
 	)
+	defer client.Close()
 	initialized := atomic.Int32{}
 	closer := agent.New(agent.Options{
 		ExchangeToken: func(ctx context.Context) (string, error) {
@@ -1846,9 +1948,10 @@ func TestAgent_WriteVSCodeConfigs(t *testing.T) {
 			GitAuthConfigs: 1,
 			DERPMap:        &tailcfg.DERPMap{},
 		},
-		make(chan *agentsdk.Stats, 50),
+		make(chan *proto.Stats, 50),
 		coordinator,
 	)
+	defer client.Close()
 	filesystem := afero.NewMemMapFs()
 	closer := agent.New(agent.Options{
 		ExchangeToken: func(ctx context.Context) (string, error) {
@@ -1872,11 +1975,21 @@ func TestAgent_WriteVSCodeConfigs(t *testing.T) {
 func TestAgent_DebugServer(t *testing.T) {
 	t.Parallel()

+	logDir := t.TempDir()
+	logPath := filepath.Join(logDir, "coder-agent.log")
+	randLogStr, err := cryptorand.String(32)
+	require.NoError(t, err)
+	require.NoError(t, os.WriteFile(logPath, []byte(randLogStr), 0o600))
 	derpMap, _ := tailnettest.RunDERPAndSTUN(t)
 	//nolint:dogsled
 	conn, _, _, _, agnt := setupAgent(t, agentsdk.Manifest{
 		DERPMap: derpMap,
-	}, 0)
+	}, 0, func(c *agenttest.Client, o *agent.Options) {
+		o.ExchangeToken = func(context.Context) (string, error) {
+			return "token", nil
+		}
+		o.LogDir = logDir
+	})

 	awaitReachableCtx := testutil.Context(t, testutil.WaitLong)
 	ok := conn.AwaitReachable(awaitReachableCtx)
@@ -1957,6 +2070,114 @@ func TestAgent_DebugServer(t *testing.T) {
 			require.Contains(t, string(resBody), `invalid state "blah", must be a boolean`)
 		})
 	})
+
+	t.Run("Manifest", func(t *testing.T) {
+		t.Parallel()
+
+		ctx := testutil.Context(t, testutil.WaitLong)
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, srv.URL+"/debug/manifest", nil)
+		require.NoError(t, err)
+
+		res, err := srv.Client().Do(req)
+		require.NoError(t, err)
+		defer res.Body.Close()
+		require.Equal(t, http.StatusOK, res.StatusCode)
+
+		var v agentsdk.Manifest
+		require.NoError(t, json.NewDecoder(res.Body).Decode(&v))
+		require.NotNil(t, v)
+	})
+
+	t.Run("Logs", func(t *testing.T) {
+		t.Parallel()
+
+		ctx := testutil.Context(t, testutil.WaitLong)
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, srv.URL+"/debug/logs", nil)
+		require.NoError(t, err)
+
+		res, err := srv.Client().Do(req)
+		require.NoError(t, err)
+		require.Equal(t, http.StatusOK, res.StatusCode)
+		defer res.Body.Close()
+		resBody, err := io.ReadAll(res.Body)
+		require.NoError(t, err)
+		require.NotEmpty(t, string(resBody))
+		require.Contains(t, string(resBody), randLogStr)
+	})
+}
+
+func TestAgent_ScriptLogging(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("bash scripts only")
+	}
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitMedium)
+
+	derpMap, _ := tailnettest.RunDERPAndSTUN(t)
+	logsCh := make(chan *proto.BatchCreateLogsRequest, 100)
+	lsStart := uuid.UUID{0x11}
+	lsStop := uuid.UUID{0x22}
+	//nolint:dogsled
+	_, _, _, _, agnt := setupAgent(
+		t,
+		agentsdk.Manifest{
+			DERPMap: derpMap,
+			Scripts: []codersdk.WorkspaceAgentScript{
+				{
+					LogSourceID: lsStart,
+					RunOnStart:  true,
+					Script: `#!/bin/sh
+i=0
+while [ $i -ne 5 ]
+do
+        i=$(($i+1))
+        echo "start $i"
+done
+`,
+				},
+				{
+					LogSourceID: lsStop,
+					RunOnStop:   true,
+					Script: `#!/bin/sh
+i=0
+while [ $i -ne 3000 ]
+do
+        i=$(($i+1))
+        echo "stop $i"
+done
+`, // send a lot of stop logs to make sure we don't truncate shutdown logs before closing the API conn
+				},
+			},
+		},
+		0,
+		func(cl *agenttest.Client, _ *agent.Options) {
+			cl.SetLogsChannel(logsCh)
+		},
+	)
+
+	n := 1
+	for n <= 5 {
+		logs := testutil.RequireRecvCtx(ctx, t, logsCh)
+		require.NotNil(t, logs)
+		for _, l := range logs.GetLogs() {
+			require.Equal(t, fmt.Sprintf("start %d", n), l.GetOutput())
+			n++
+		}
+	}
+
+	err := agnt.Close()
+	require.NoError(t, err)
+
+	n = 1
+	for n <= 3000 {
+		logs := testutil.RequireRecvCtx(ctx, t, logsCh)
+		require.NotNil(t, logs)
+		for _, l := range logs.GetLogs() {
+			require.Equal(t, fmt.Sprintf("stop %d", n), l.GetOutput())
+			n++
+		}
+		t.Logf("got %d stop logs", n-1)
+	}
 }

 // setupAgentSSHClient creates an agent, dials it, and sets up an ssh.Client for it
@@ -1974,15 +2195,17 @@ func setupSSHSession(
 	manifest agentsdk.Manifest,
 	serviceBanner codersdk.ServiceBannerConfig,
 	prepareFS func(fs afero.Fs),
+	opts ...func(*agenttest.Client, *agent.Options),
 ) *ssh.Session {
 	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
 	defer cancel()
-	//nolint:dogsled
-	conn, _, _, fs, _ := setupAgent(t, manifest, 0, func(c *agenttest.Client, _ *agent.Options) {
+	opts = append(opts, func(c *agenttest.Client, o *agent.Options) {
 		c.SetServiceBannerFunc(func() (codersdk.ServiceBannerConfig, error) {
 			return serviceBanner, nil
 		})
 	})
+	//nolint:dogsled
+	conn, _, _, fs, _ := setupAgent(t, manifest, 0, opts...)
 	if prepareFS != nil {
 		prepareFS(fs)
 	}
@@ -2000,41 +2223,56 @@ func setupSSHSession(
 }

 func setupAgent(t *testing.T, metadata agentsdk.Manifest, ptyTimeout time.Duration, opts ...func(*agenttest.Client, *agent.Options)) (
-	*codersdk.WorkspaceAgentConn,
+	*workspacesdk.AgentConn,
 	*agenttest.Client,
-	<-chan *agentsdk.Stats,
+	<-chan *proto.Stats,
 	afero.Fs,
 	agent.Agent,
 ) {
-	logger := slogtest.Make(t, nil).Leveled(slog.LevelDebug)
+	logger := slogtest.Make(t, &slogtest.Options{
+		// Agent can drop errors when shutting down, and some, like the
+		// fasthttplistener connection closed error, are unexported.
+		IgnoreErrors: true,
+	}).Leveled(slog.LevelDebug)
 	if metadata.DERPMap == nil {
 		metadata.DERPMap, _ = tailnettest.RunDERPAndSTUN(t)
 	}
 	if metadata.AgentID == uuid.Nil {
 		metadata.AgentID = uuid.New()
 	}
+	if metadata.AgentName == "" {
+		metadata.AgentName = "test-agent"
+	}
+	if metadata.WorkspaceName == "" {
+		metadata.WorkspaceName = "test-workspace"
+	}
+	if metadata.WorkspaceID == uuid.Nil {
+		metadata.WorkspaceID = uuid.New()
+	}
 	coordinator := tailnet.NewCoordinator(logger)
 	t.Cleanup(func() {
 		_ = coordinator.Close()
 	})
-	statsCh := make(chan *agentsdk.Stats, 50)
+	statsCh := make(chan *proto.Stats, 50)
 	fs := afero.NewMemMapFs()
-	c := agenttest.NewClient(t, logger.Named("agent"), metadata.AgentID, metadata, statsCh, coordinator)
+	c := agenttest.NewClient(t, logger.Named("agenttest"), metadata.AgentID, metadata, statsCh, coordinator)
+	t.Cleanup(c.Close)

 	options := agent.Options{
 		Client:                 c,
 		Filesystem:             fs,
 		Logger:                 logger.Named("agent"),
 		ReconnectingPTYTimeout: ptyTimeout,
+		EnvironmentVariables:   map[string]string{},
 	}

 	for _, opt := range opts {
 		opt(c, &options)
 	}

-	closer := agent.New(options)
+	agnt := agent.New(options)
 	t.Cleanup(func() {
-		_ = closer.Close()
+		_ = agnt.Close()
 	})
 	conn, err := tailnet.NewConn(&tailnet.Options{
 		Addresses: []netip.Prefix{netip.PrefixFrom(tailnet.IP(), 128)},
@@ -2042,23 +2280,23 @@ func setupAgent(t *testing.T, metadata agentsdk.Manifest, ptyTimeout time.Durati
 		Logger:    logger.Named("client"),
 	})
 	require.NoError(t, err)
-	clientConn, serverConn := net.Pipe()
-	serveClientDone := make(chan struct{})
 	t.Cleanup(func() {
-		_ = clientConn.Close()
-		_ = serverConn.Close()
 		_ = conn.Close()
-		<-serveClientDone
 	})
-	go func() {
-		defer close(serveClientDone)
-		coordinator.ServeClient(serverConn, uuid.New(), metadata.AgentID)
-	}()
-	sendNode, _ := tailnet.ServeCoordinator(clientConn, func(nodes []*tailnet.Node) error {
-		return conn.UpdateNodes(nodes, false)
+	testCtx, testCtxCancel := context.WithCancel(context.Background())
+	t.Cleanup(testCtxCancel)
+	clientID := uuid.New()
+	coordination := tailnet.NewInMemoryCoordination(
+		testCtx, logger,
+		clientID, metadata.AgentID,
+		coordinator, conn)
+	t.Cleanup(func() {
+		err := coordination.Close()
+		if err != nil {
+			t.Logf("error closing in-mem coordination: %s", err.Error())
+		}
 	})
-	conn.SetNodeCallback(sendNode)
-	agentConn := codersdk.NewWorkspaceAgentConn(conn, codersdk.WorkspaceAgentConnOptions{
+	agentConn := workspacesdk.NewAgentConn(conn, workspacesdk.AgentConnOptions{
 		AgentID: metadata.AgentID,
 	})
 	t.Cleanup(func() {
@@ -2071,7 +2309,7 @@ func setupAgent(t *testing.T, metadata agentsdk.Manifest, ptyTimeout time.Durati
 	if !agentConn.AwaitReachable(ctx) {
 		t.Fatal("agent not reachable")
 	}
-	return agentConn, c, statsCh, fs, closer
+	return agentConn, c, statsCh, fs, agnt
 }

 var dialTestPayload = []byte("dean-was-here123")
@@ -2291,11 +2529,11 @@ func TestAgent_ManageProcessPriority(t *testing.T) {
 			logger        = slog.Make(sloghuman.Sink(io.Discard))
 		)

+		requireFileWrite(t, fs, "/proc/self/oom_score_adj", "-500")
+
 		// Create some processes.
 		for i := 0; i < 4; i++ {
-			// Create a prioritized process. This process should
-			// have it's oom_score_adj set to -500 and its nice
-			// score should be untouched.
+			// Create a prioritized process.
 			var proc agentproc.Process
 			if i == 0 {
 				proc = agentproctest.GenerateProcess(t, fs,
@@ -2313,8 +2551,8 @@ func TestAgent_ManageProcessPriority(t *testing.T) {
 					},
 				)

-				syscaller.EXPECT().SetPriority(proc.PID, 10).Return(nil)
 				syscaller.EXPECT().GetPriority(proc.PID).Return(20, nil)
+				syscaller.EXPECT().SetPriority(proc.PID, 10).Return(nil)
 			}
 			syscaller.EXPECT().
 				Kill(proc.PID, syscall.Signal(0)).
@@ -2333,6 +2571,9 @@ func TestAgent_ManageProcessPriority(t *testing.T) {
 		})
 		actualProcs := <-modProcs
 		require.Len(t, actualProcs, len(expectedProcs)-1)
+		for _, proc := range actualProcs {
+			requireFileEquals(t, fs, fmt.Sprintf("/proc/%d/oom_score_adj", proc.PID), "0")
+		}
 	})

 	t.Run("IgnoreCustomNice", func(t *testing.T) {
@@ -2351,8 +2592,11 @@ func TestAgent_ManageProcessPriority(t *testing.T) {
 			logger        = slog.Make(sloghuman.Sink(io.Discard))
 		)

+		err := afero.WriteFile(fs, "/proc/self/oom_score_adj", []byte("0"), 0o644)
+		require.NoError(t, err)
+
 		// Create some processes.
-		for i := 0; i < 2; i++ {
+		for i := 0; i < 3; i++ {
 			proc := agentproctest.GenerateProcess(t, fs)
 			syscaller.EXPECT().
 				Kill(proc.PID, syscall.Signal(0)).
@@ -2380,7 +2624,59 @@ func TestAgent_ManageProcessPriority(t *testing.T) {
 		})
 		actualProcs := <-modProcs
 		// We should ignore the process with a custom nice score.
-		require.Len(t, actualProcs, 1)
+		require.Len(t, actualProcs, 2)
+		for _, proc := range actualProcs {
+			_, ok := expectedProcs[proc.PID]
+			require.True(t, ok)
+			requireFileEquals(t, fs, fmt.Sprintf("/proc/%d/oom_score_adj", proc.PID), "998")
+		}
+	})
+
+	t.Run("CustomOOMScore", func(t *testing.T) {
+		t.Parallel()
+
+		if runtime.GOOS != "linux" {
+			t.Skip("Skipping non-linux environment")
+		}
+
+		var (
+			fs        = afero.NewMemMapFs()
+			ticker    = make(chan time.Time)
+			syscaller = agentproctest.NewMockSyscaller(gomock.NewController(t))
+			modProcs  = make(chan []*agentproc.Process)
+			logger    = slog.Make(sloghuman.Sink(io.Discard))
+		)
+
+		err := afero.WriteFile(fs, "/proc/self/oom_score_adj", []byte("0"), 0o644)
+		require.NoError(t, err)
+
+		// Create some processes.
+		for i := 0; i < 3; i++ {
+			proc := agentproctest.GenerateProcess(t, fs)
+			syscaller.EXPECT().
+				Kill(proc.PID, syscall.Signal(0)).
+				Return(nil)
+			syscaller.EXPECT().GetPriority(proc.PID).Return(20, nil)
+			syscaller.EXPECT().SetPriority(proc.PID, 10).Return(nil)
+		}
+
+		_, _, _, _, _ = setupAgent(t, agentsdk.Manifest{}, 0, func(c *agenttest.Client, o *agent.Options) {
+			o.Syscaller = syscaller
+			o.ModifiedProcesses = modProcs
+			o.EnvironmentVariables = map[string]string{
+				agent.EnvProcPrioMgmt: "1",
+				agent.EnvProcOOMScore: "-567",
+			}
+			o.Filesystem = fs
+			o.Logger = logger
+			o.ProcessManagementTick = ticker
+		})
+		actualProcs := <-modProcs
+		// We should ignore the process with a custom nice score.
+		require.Len(t, actualProcs, 3)
+		for _, proc := range actualProcs {
+			requireFileEquals(t, fs, fmt.Sprintf("/proc/%d/oom_score_adj", proc.PID), "-567")
+		}
 	})

 	t.Run("DisabledByDefault", func(t *testing.T) {
@@ -2472,20 +2768,6 @@ func (s *syncWriter) Write(p []byte) (int, error) {
 	return s.w.Write(p)
 }

-// pickRandomPort picks a random port number for the ephemeral range. We do this entirely randomly
-// instead of opening a listener and closing it to find a port that is likely to be free, since
-// sometimes the OS reallocates the port very quickly.
-func pickRandomPort() uint16 {
-	const (
-		// Overlap of windows, linux in https://en.wikipedia.org/wiki/Ephemeral_port
-		min = 49152
-		max = 60999
-	)
-	n := max - min
-	x := rand.Intn(n) //nolint: gosec
-	return uint16(min + x)
-}
-
 // echoOnce accepts a single connection, reads 4 bytes and echos them back
 func echoOnce(t *testing.T, ll net.Listener) {
 	t.Helper()
@@ -2515,3 +2797,17 @@ func requireEcho(t *testing.T, conn net.Conn) {
 	require.NoError(t, err)
 	require.Equal(t, "test", string(b))
 }
+
+func requireFileWrite(t testing.TB, fs afero.Fs, fp, data string) {
+	t.Helper()
+	err := afero.WriteFile(fs, fp, []byte(data), 0o600)
+	require.NoError(t, err)
+}
+
+func requireFileEquals(t testing.TB, fs afero.Fs, fp, expect string) {
+	t.Helper()
+	actual, err := afero.ReadFile(fs, fp)
+	require.NoError(t, err)
+
+	require.Equal(t, expect, string(actual))
+}
@@ -2,6 +2,7 @@ package agentproctest

 import (
 	"fmt"
+	"strconv"
 	"testing"

 	"github.com/spf13/afero"
@@ -29,8 +30,9 @@ func GenerateProcess(t *testing.T, fs afero.Fs, muts ...func(*agentproc.Process)
 	cmdline := fmt.Sprintf("%s\x00%s\x00%s", arg1, arg2, arg3)

 	process := agentproc.Process{
-		CmdLine: cmdline,
-		PID:     int32(pid),
+		CmdLine:     cmdline,
+		PID:         int32(pid),
+		OOMScoreAdj: 0,
 	}

 	for _, mut := range muts {
@@ -45,5 +47,9 @@ func GenerateProcess(t *testing.T, fs afero.Fs, muts ...func(*agentproc.Process)
 	err = afero.WriteFile(fs, fmt.Sprintf("%s/cmdline", process.Dir), []byte(process.CmdLine), 0o444)
 	require.NoError(t, err)

+	score := strconv.Itoa(process.OOMScoreAdj)
+	err = afero.WriteFile(fs, fmt.Sprintf("%s/oom_score_adj", process.Dir), []byte(score), 0o444)
+	require.NoError(t, err)
+
 	return process
 }
@@ -1,5 +1,10 @@
 // Code generated by MockGen. DO NOT EDIT.
 // Source: github.com/coder/coder/v2/agent/agentproc (interfaces: Syscaller)
+//
+// Generated by this command:
+//
+//	mockgen -destination ./syscallermock.go -package agentproctest github.com/coder/coder/v2/agent/agentproc Syscaller
+//

 // Package agentproctest is a generated GoMock package.
 package agentproctest
@@ -8,7 +13,7 @@ import (
 	reflect "reflect"
 	syscall "syscall"

-	gomock "github.com/golang/mock/gomock"
+	gomock "go.uber.org/mock/gomock"
 )

 // MockSyscaller is a mock of Syscaller interface.
@@ -44,7 +49,7 @@ func (m *MockSyscaller) GetPriority(arg0 int32) (int, error) {
 }

 // GetPriority indicates an expected call of GetPriority.
-func (mr *MockSyscallerMockRecorder) GetPriority(arg0 interface{}) *gomock.Call {
+func (mr *MockSyscallerMockRecorder) GetPriority(arg0 any) *gomock.Call {
 	mr.mock.ctrl.T.Helper()
 	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "GetPriority", reflect.TypeOf((*MockSyscaller)(nil).GetPriority), arg0)
 }
@@ -58,7 +63,7 @@ func (m *MockSyscaller) Kill(arg0 int32, arg1 syscall.Signal) error {
 }

 // Kill indicates an expected call of Kill.
-func (mr *MockSyscallerMockRecorder) Kill(arg0, arg1 interface{}) *gomock.Call {
+func (mr *MockSyscallerMockRecorder) Kill(arg0, arg1 any) *gomock.Call {
 	mr.mock.ctrl.T.Helper()
 	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Kill", reflect.TypeOf((*MockSyscaller)(nil).Kill), arg0, arg1)
 }
@@ -72,7 +77,7 @@ func (m *MockSyscaller) SetPriority(arg0 int32, arg1 int) error {
 }

 // SetPriority indicates an expected call of SetPriority.
-func (mr *MockSyscallerMockRecorder) SetPriority(arg0, arg1 interface{}) *gomock.Call {
+func (mr *MockSyscallerMockRecorder) SetPriority(arg0, arg1 any) *gomock.Call {
 	mr.mock.ctrl.T.Helper()
 	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "SetPriority", reflect.TypeOf((*MockSyscaller)(nil).SetPriority), arg0, arg1)
 }
@@ -5,9 +5,9 @@ import (
 	"syscall"
 	"testing"

-	"github.com/golang/mock/gomock"
 	"github.com/spf13/afero"
 	"github.com/stretchr/testify/require"
+	"go.uber.org/mock/gomock"
 	"golang.org/x/xerrors"

 	"github.com/coder/coder/v2/agent/agentproc"
@@ -5,6 +5,7 @@ package agentproc

 import (
 	"errors"
+	"os"
 	"path/filepath"
 	"strconv"
 	"strings"
@@ -50,10 +51,26 @@ func List(fs afero.Fs, syscaller Syscaller) ([]*Process, error) {
 			}
 			return nil, xerrors.Errorf("read cmdline: %w", err)
 		}
+
+		oomScore, err := afero.ReadFile(fs, filepath.Join(defaultProcDir, entry, "oom_score_adj"))
+		if err != nil {
+			if xerrors.Is(err, os.ErrPermission) {
+				continue
+			}
+
+			return nil, xerrors.Errorf("read oom_score_adj: %w", err)
+		}
+
+		oom, err := strconv.Atoi(strings.TrimSpace(string(oomScore)))
+		if err != nil {
+			return nil, xerrors.Errorf("convert oom score: %w", err)
+		}
+
 		processes = append(processes, &Process{
-			PID:     int32(pid),
-			CmdLine: string(cmdline),
-			Dir:     filepath.Join(defaultProcDir, entry),
+			PID:         int32(pid),
+			CmdLine:     string(cmdline),
+			Dir:         filepath.Join(defaultProcDir, entry),
+			OOMScoreAdj: oom,
 		})
 	}

@@ -14,7 +14,8 @@ type Syscaller interface {
 const defaultProcDir = "/proc"

 type Process struct {
-	Dir     string
-	CmdLine string
-	PID     int32
+	Dir         string
+	CmdLine     string
+	PID         int32
+	OOMScoreAdj int
 }
@@ -13,6 +13,7 @@ import (
 	"sync/atomic"
 	"time"

+	"github.com/google/uuid"
 	"github.com/prometheus/client_golang/prometheus"
 	"github.com/robfig/cron/v3"
 	"github.com/spf13/afero"
@@ -41,13 +42,19 @@ var (
 	parser = cron.NewParser(cron.Second | cron.Minute | cron.Hour | cron.Dom | cron.Month | cron.DowOptional)
 )

+type ScriptLogger interface {
+	Send(ctx context.Context, log ...agentsdk.Log) error
+	Flush(context.Context) error
+}
+
 // Options are a set of options for the runner.
 type Options struct {
-	LogDir     string
-	Logger     slog.Logger
-	SSHServer  *agentssh.Server
-	Filesystem afero.Fs
-	PatchLogs  func(ctx context.Context, req agentsdk.PatchLogs) error
+	DataDirBase     string
+	LogDir          string
+	Logger          slog.Logger
+	SSHServer       *agentssh.Server
+	Filesystem      afero.Fs
+	GetScriptLogger func(logSourceID uuid.UUID) ScriptLogger
 }

 // New creates a runner for the provided scripts.
@@ -59,6 +66,7 @@ func New(opts Options) *Runner {
 		cronCtxCancel: cronCtxCancel,
 		cron:          cron.New(cron.WithParser(parser)),
 		closed:        make(chan struct{}),
+		dataDir:       filepath.Join(opts.DataDirBase, "coder-script-data"),
 		scriptsExecuted: prometheus.NewCounterVec(prometheus.CounterOpts{
 			Namespace: "agent",
 			Subsystem: "scripts",
@@ -78,6 +86,7 @@ type Runner struct {
 	cron          *cron.Cron
 	initialized   atomic.Bool
 	scripts       []codersdk.WorkspaceAgentScript
+	dataDir       string

 	// scriptsExecuted includes all scripts executed by the workspace agent. Agents
 	// execute startup scripts, and scripts on a cron schedule. Both will increment
@@ -85,6 +94,17 @@ type Runner struct {
 	scriptsExecuted *prometheus.CounterVec
 }

+// DataDir returns the directory where scripts data is stored.
+func (r *Runner) DataDir() string {
+	return r.dataDir
+}
+
+// ScriptBinDir returns the directory where scripts can store executable
+// binaries.
+func (r *Runner) ScriptBinDir() string {
+	return filepath.Join(r.dataDir, "bin")
+}
+
 func (r *Runner) RegisterMetrics(reg prometheus.Registerer) {
 	if reg == nil {
 		// If no registry, do nothing.
@@ -104,6 +124,11 @@ func (r *Runner) Init(scripts []codersdk.WorkspaceAgentScript) error {
 	r.scripts = scripts
 	r.Logger.Info(r.cronCtx, "initializing agent scripts", slog.F("script_count", len(scripts)), slog.F("log_dir", r.LogDir))

+	err := r.Filesystem.MkdirAll(r.ScriptBinDir(), 0o700)
+	if err != nil {
+		return xerrors.Errorf("create script bin dir: %w", err)
+	}
+
 	for _, script := range scripts {
 		if script.Cron == "" {
 			continue
@@ -129,7 +154,18 @@ func (r *Runner) StartCron() {
 	// has exited by the time the `cron.Stop()` context returns, so we need to
 	// track it manually.
 	err := r.trackCommandGoroutine(func() {
-		r.cron.Run()
+		// Since this is run async, in quick unit tests, it is possible the
+		// Close() function gets called before we even start the cron.
+		// In these cases, the Run() will never end.
+		// So if we are closed, we just return, and skip the Run() entirely.
+		select {
+		case <-r.cronCtx.Done():
+			// The cronCtx is canceled before cron.Close() happens. So if the ctx is
+			// canceled, then Close() will be called, or it is about to be called.
+			// So do nothing!
+		default:
+			r.cron.Run()
+		}
 	})
 	if err != nil {
 		r.Logger.Warn(context.Background(), "start cron failed", slog.Error(err))
@@ -197,7 +233,18 @@ func (r *Runner) run(ctx context.Context, script codersdk.WorkspaceAgentScript)
 	if !filepath.IsAbs(logPath) {
 		logPath = filepath.Join(r.LogDir, logPath)
 	}
-	logger := r.Logger.With(slog.F("log_path", logPath))
+
+	scriptDataDir := filepath.Join(r.DataDir(), script.LogSourceID.String())
+	err := r.Filesystem.MkdirAll(scriptDataDir, 0o700)
+	if err != nil {
+		return xerrors.Errorf("%s script: create script temp dir: %w", scriptDataDir, err)
+	}
+
+	logger := r.Logger.With(
+		slog.F("log_source_id", script.LogSourceID),
+		slog.F("log_path", logPath),
+		slog.F("script_data_dir", scriptDataDir),
+	)
 	logger.Info(ctx, "running agent script", slog.F("script", script.Script))

 	fileWriter, err := r.Filesystem.OpenFile(logPath, os.O_CREATE|os.O_RDWR, 0o600)
@@ -227,20 +274,27 @@ func (r *Runner) run(ctx context.Context, script codersdk.WorkspaceAgentScript)
 	cmd.WaitDelay = 10 * time.Second
 	cmd.Cancel = cmdCancel(cmd)

-	send, flushAndClose := agentsdk.LogsSender(script.LogSourceID, r.PatchLogs, logger)
+	// Expose env vars that can be used in the script for storing data
+	// and binaries. In the future, we may want to expose more env vars
+	// for the script to use, like CODER_SCRIPT_DATA_DIR for persistent
+	// storage.
+	cmd.Env = append(cmd.Env, "CODER_SCRIPT_DATA_DIR="+scriptDataDir)
+	cmd.Env = append(cmd.Env, "CODER_SCRIPT_BIN_DIR="+r.ScriptBinDir())
+
+	scriptLogger := r.GetScriptLogger(script.LogSourceID)
 	// If ctx is canceled here (or in a writer below), we may be
 	// discarding logs, but that's okay because we're shutting down
 	// anyway. We could consider creating a new context here if we
 	// want better control over flush during shutdown.
 	defer func() {
-		if err := flushAndClose(ctx); err != nil {
+		if err := scriptLogger.Flush(ctx); err != nil {
 			logger.Warn(ctx, "flush startup logs failed", slog.Error(err))
 		}
 	}()

-	infoW := agentsdk.LogsWriter(ctx, send, script.LogSourceID, codersdk.LogLevelInfo)
+	infoW := agentsdk.LogsWriter(ctx, scriptLogger.Send, script.LogSourceID, codersdk.LogLevelInfo)
 	defer infoW.Close()
-	errW := agentsdk.LogsWriter(ctx, send, script.LogSourceID, codersdk.LogLevelError)
+	errW := agentsdk.LogsWriter(ctx, scriptLogger.Send, script.LogSourceID, codersdk.LogLevelError)
 	defer errW.Close()
 	cmd.Stdout = io.MultiWriter(fileWriter, infoW)
 	cmd.Stderr = io.MultiWriter(fileWriter, errW)
@@ -315,6 +369,7 @@ func (r *Runner) Close() error {
 		return nil
 	}
 	close(r.closed)
+	// Must cancel the cron ctx BEFORE stopping the cron.
 	r.cronCtxCancel()
 	<-r.cron.Stop().Done()
 	r.cmdCloseWait.Wait()
@@ -2,13 +2,16 @@ package agentscripts_test

 import (
 	"context"
+	"path/filepath"
+	"runtime"
 	"testing"
 	"time"

+	"github.com/google/uuid"
 	"github.com/prometheus/client_golang/prometheus"
 	"github.com/spf13/afero"
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-	"go.uber.org/atomic"
 	"go.uber.org/goleak"

 	"cdr.dev/slog/sloggers/slogtest"
@@ -16,6 +19,7 @@ import (
 	"github.com/coder/coder/v2/agent/agentssh"
 	"github.com/coder/coder/v2/codersdk"
 	"github.com/coder/coder/v2/codersdk/agentsdk"
+	"github.com/coder/coder/v2/testutil"
 )

 func TestMain(m *testing.M) {
@@ -24,21 +28,75 @@ func TestMain(m *testing.M) {

 func TestExecuteBasic(t *testing.T) {
 	t.Parallel()
-	logs := make(chan agentsdk.PatchLogs, 1)
-	runner := setup(t, func(ctx context.Context, req agentsdk.PatchLogs) error {
-		logs <- req
-		return nil
+	ctx := testutil.Context(t, testutil.WaitShort)
+	fLogger := newFakeScriptLogger()
+	runner := setup(t, func(uuid2 uuid.UUID) agentscripts.ScriptLogger {
+		return fLogger
 	})
 	defer runner.Close()
 	err := runner.Init([]codersdk.WorkspaceAgentScript{{
-		Script: "echo hello",
+		LogSourceID: uuid.New(),
+		Script:      "echo hello",
 	}})
 	require.NoError(t, err)
 	require.NoError(t, runner.Execute(context.Background(), func(script codersdk.WorkspaceAgentScript) bool {
 		return true
 	}))
-	log := <-logs
-	require.Equal(t, "hello", log.Logs[0].Output)
+	log := testutil.RequireRecvCtx(ctx, t, fLogger.logs)
+	require.Equal(t, "hello", log.Output)
+}
+
+func TestEnv(t *testing.T) {
+	t.Parallel()
+	fLogger := newFakeScriptLogger()
+	runner := setup(t, func(uuid2 uuid.UUID) agentscripts.ScriptLogger {
+		return fLogger
+	})
+	defer runner.Close()
+	id := uuid.New()
+	script := "echo $CODER_SCRIPT_DATA_DIR\necho $CODER_SCRIPT_BIN_DIR\n"
+	if runtime.GOOS == "windows" {
+		script = `
+			cmd.exe /c echo %CODER_SCRIPT_DATA_DIR%
+			cmd.exe /c echo %CODER_SCRIPT_BIN_DIR%
+		`
+	}
+	err := runner.Init([]codersdk.WorkspaceAgentScript{{
+		LogSourceID: id,
+		Script:      script,
+	}})
+	require.NoError(t, err)
+
+	ctx := testutil.Context(t, testutil.WaitLong)
+
+	done := testutil.Go(t, func() {
+		err := runner.Execute(ctx, func(script codersdk.WorkspaceAgentScript) bool {
+			return true
+		})
+		assert.NoError(t, err)
+	})
+	defer func() {
+		select {
+		case <-ctx.Done():
+		case <-done:
+		}
+	}()
+
+	var log []agentsdk.Log
+	for {
+		select {
+		case <-ctx.Done():
+			require.Fail(t, "timed out waiting for logs")
+		case l := <-fLogger.logs:
+			t.Logf("log: %s", l.Output)
+			log = append(log, l)
+		}
+		if len(log) >= 2 {
+			break
+		}
+	}
+	require.Contains(t, log[0].Output, filepath.Join(runner.DataDir(), id.String()))
+	require.Contains(t, log[1].Output, runner.ScriptBinDir())
 }

 func TestTimeout(t *testing.T) {
@@ -46,35 +104,78 @@ func TestTimeout(t *testing.T) {
 	runner := setup(t, nil)
 	defer runner.Close()
 	err := runner.Init([]codersdk.WorkspaceAgentScript{{
-		Script:  "sleep infinity",
-		Timeout: time.Millisecond,
+		LogSourceID: uuid.New(),
+		Script:      "sleep infinity",
+		Timeout:     time.Millisecond,
 	}})
 	require.NoError(t, err)
 	require.ErrorIs(t, runner.Execute(context.Background(), nil), agentscripts.ErrTimeout)
 }

-func setup(t *testing.T, patchLogs func(ctx context.Context, req agentsdk.PatchLogs) error) *agentscripts.Runner {
+// TestCronClose exists because cron.Run() can happen after cron.Close().
+// If this happens, there used to be a deadlock.
+func TestCronClose(t *testing.T) {
+	t.Parallel()
+	runner := agentscripts.New(agentscripts.Options{})
+	runner.StartCron()
+	require.NoError(t, runner.Close(), "close runner")
+}
+
+func setup(t *testing.T, getScriptLogger func(logSourceID uuid.UUID) agentscripts.ScriptLogger) *agentscripts.Runner {
 	t.Helper()
-	if patchLogs == nil {
+	if getScriptLogger == nil {
 		// noop
-		patchLogs = func(ctx context.Context, req agentsdk.PatchLogs) error {
-			return nil
+		getScriptLogger = func(uuid uuid.UUID) agentscripts.ScriptLogger {
+			return noopScriptLogger{}
 		}
 	}
 	fs := afero.NewMemMapFs()
 	logger := slogtest.Make(t, nil)
-	s, err := agentssh.NewServer(context.Background(), logger, prometheus.NewRegistry(), fs, 0, "")
+	s, err := agentssh.NewServer(context.Background(), logger, prometheus.NewRegistry(), fs, nil)
 	require.NoError(t, err)
-	s.AgentToken = func() string { return "" }
-	s.Manifest = atomic.NewPointer(&agentsdk.Manifest{})
 	t.Cleanup(func() {
 		_ = s.Close()
 	})
 	return agentscripts.New(agentscripts.Options{
-		LogDir:     t.TempDir(),
-		Logger:     logger,
-		SSHServer:  s,
-		Filesystem: fs,
-		PatchLogs:  patchLogs,
+		LogDir:          t.TempDir(),
+		DataDirBase:     t.TempDir(),
+		Logger:          logger,
+		SSHServer:       s,
+		Filesystem:      fs,
+		GetScriptLogger: getScriptLogger,
 	})
 }
+
+type noopScriptLogger struct{}
+
+func (noopScriptLogger) Send(context.Context, ...agentsdk.Log) error {
+	return nil
+}
+
+func (noopScriptLogger) Flush(context.Context) error {
+	return nil
+}
+
+type fakeScriptLogger struct {
+	logs chan agentsdk.Log
+}
+
+func (f *fakeScriptLogger) Send(ctx context.Context, logs ...agentsdk.Log) error {
+	for _, log := range logs {
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case f.logs <- log:
+			// OK!
+		}
+	}
+	return nil
+}
+
+func (*fakeScriptLogger) Flush(context.Context) error {
+	return nil
+}
+
+func newFakeScriptLogger() *fakeScriptLogger {
+	return &fakeScriptLogger{make(chan agentsdk.Log, 100)}
+}
@@ -32,7 +32,6 @@ import (

 	"github.com/coder/coder/v2/agent/usershell"
 	"github.com/coder/coder/v2/codersdk"
-	"github.com/coder/coder/v2/codersdk/agentsdk"
 	"github.com/coder/coder/v2/pty"
 )

@@ -55,6 +54,28 @@ const (
 	MagicProcessCmdlineJetBrains = "idea.vendor.name=JetBrains"
 )

+// Config sets configuration parameters for the agent SSH server.
+type Config struct {
+	// MaxTimeout sets the absolute connection timeout, none if empty. If set to
+	// 3 seconds or more, keep alive will be used instead.
+	MaxTimeout time.Duration
+	// MOTDFile returns the path to the message of the day file. If set, the
+	// file will be displayed to the user upon login.
+	MOTDFile func() string
+	// ServiceBanner returns the configuration for the Coder service banner.
+	ServiceBanner func() *codersdk.ServiceBannerConfig
+	// UpdateEnv updates the environment variables for the command to be
+	// executed. It can be used to add, modify or replace environment variables.
+	UpdateEnv func(current []string) (updated []string, err error)
+	// WorkingDirectory sets the working directory for commands and defines
+	// where users will land when they connect via SSH. Default is the home
+	// directory of the user.
+	WorkingDirectory func() string
+	// X11SocketDir is the directory where X11 sockets are created. Default is
+	// /tmp/.X11-unix.
+	X11SocketDir string
+}
+
 type Server struct {
 	mu        sync.RWMutex // Protects following.
 	fs        afero.Fs
@@ -66,14 +87,10 @@ type Server struct {
 	// a lock on mu but protected by closing.
 	wg sync.WaitGroup

-	logger       slog.Logger
-	srv          *ssh.Server
-	x11SocketDir string
+	logger slog.Logger
+	srv    *ssh.Server

-	Env           map[string]string
-	AgentToken    func() string
-	Manifest      *atomic.Pointer[agentsdk.Manifest]
-	ServiceBanner *atomic.Pointer[codersdk.ServiceBannerConfig]
+	config *Config

 	connCountVSCode     atomic.Int64
 	connCountJetBrains  atomic.Int64
@@ -82,7 +99,7 @@ type Server struct {
 	metrics *sshServerMetrics
 }

-func NewServer(ctx context.Context, logger slog.Logger, prometheusRegistry *prometheus.Registry, fs afero.Fs, maxTimeout time.Duration, x11SocketDir string) (*Server, error) {
+func NewServer(ctx context.Context, logger slog.Logger, prometheusRegistry *prometheus.Registry, fs afero.Fs, config *Config) (*Server, error) {
 	// Clients' should ignore the host key when connecting.
 	// The agent needs to authenticate with coderd to SSH,
 	// so SSH authentication doesn't improve security.
@@ -94,21 +111,43 @@ func NewServer(ctx context.Context, logger slog.Logger, prometheusRegistry *prom
 	if err != nil {
 		return nil, err
 	}
-	if x11SocketDir == "" {
-		x11SocketDir = filepath.Join(os.TempDir(), ".X11-unix")
+	if config == nil {
+		config = &Config{}
+	}
+	if config.X11SocketDir == "" {
+		config.X11SocketDir = filepath.Join(os.TempDir(), ".X11-unix")
+	}
+	if config.UpdateEnv == nil {
+		config.UpdateEnv = func(current []string) ([]string, error) { return current, nil }
+	}
+	if config.MOTDFile == nil {
+		config.MOTDFile = func() string { return "" }
+	}
+	if config.ServiceBanner == nil {
+		config.ServiceBanner = func() *codersdk.ServiceBannerConfig { return &codersdk.ServiceBannerConfig{} }
+	}
+	if config.WorkingDirectory == nil {
+		config.WorkingDirectory = func() string {
+			home, err := userHomeDir()
+			if err != nil {
+				return ""
+			}
+			return home
+		}
 	}

 	forwardHandler := &ssh.ForwardedTCPHandler{}
-	unixForwardHandler := &forwardedUnixHandler{log: logger}
+	unixForwardHandler := newForwardedUnixHandler(logger)

 	metrics := newSSHServerMetrics(prometheusRegistry)
 	s := &Server{
-		listeners:    make(map[net.Listener]struct{}),
-		fs:           fs,
-		conns:        make(map[net.Conn]struct{}),
-		sessions:     make(map[ssh.Session]struct{}),
-		logger:       logger,
-		x11SocketDir: x11SocketDir,
+		listeners: make(map[net.Listener]struct{}),
+		fs:        fs,
+		conns:     make(map[net.Conn]struct{}),
+		sessions:  make(map[ssh.Session]struct{}),
+		logger:    logger,
+
+		config: config,

 		metrics: metrics,
 	}
@@ -172,14 +211,16 @@ func NewServer(ctx context.Context, logger slog.Logger, prometheusRegistry *prom
 		},
 	}

-	// The MaxTimeout functionality has been substituted with the introduction of the KeepAlive feature.
-	// In cases where very short timeouts are set, the SSH server will automatically switch to the connection timeout for both read and write operations.
-	if maxTimeout >= 3*time.Second {
+	// The MaxTimeout functionality has been substituted with the introduction
+	// of the KeepAlive feature. In cases where very short timeouts are set, the
+	// SSH server will automatically switch to the connection timeout for both
+	// read and write operations.
+	if config.MaxTimeout >= 3*time.Second {
 		srv.ClientAliveCountMax = 3
-		srv.ClientAliveInterval = maxTimeout / time.Duration(srv.ClientAliveCountMax)
+		srv.ClientAliveInterval = config.MaxTimeout / time.Duration(srv.ClientAliveCountMax)
 		srv.MaxTimeout = 0
 	} else {
-		srv.MaxTimeout = maxTimeout
+		srv.MaxTimeout = config.MaxTimeout
 	}

 	s.srv = srv
@@ -400,7 +441,7 @@ func (s *Server) startPTYSession(logger slog.Logger, session ptySession, magicTy
 	session.DisablePTYEmulation()

 	if isLoginShell(session.RawCommand()) {
-		serviceBanner := s.ServiceBanner.Load()
+		serviceBanner := s.config.ServiceBanner()
 		if serviceBanner != nil {
 			err := showServiceBanner(session, serviceBanner)
 			if err != nil {
@@ -411,15 +452,10 @@ func (s *Server) startPTYSession(logger slog.Logger, session ptySession, magicTy
 	}

 	if !isQuietLogin(s.fs, session.RawCommand()) {
-		manifest := s.Manifest.Load()
-		if manifest != nil {
-			err := showMOTD(s.fs, session, manifest.MOTDFile)
-			if err != nil {
-				logger.Error(ctx, "agent failed to show MOTD", slog.Error(err))
-				s.metrics.sessionErrors.WithLabelValues(magicTypeLabel, "yes", "motd").Add(1)
-			}
-		} else {
-			logger.Warn(ctx, "metadata lookup failed, unable to show MOTD")
+		err := showMOTD(s.fs, session, s.config.MOTDFile())
+		if err != nil {
+			logger.Error(ctx, "agent failed to show MOTD", slog.Error(err))
+			s.metrics.sessionErrors.WithLabelValues(magicTypeLabel, "yes", "motd").Add(1)
 		}
 	}

@@ -557,7 +593,7 @@ func (s *Server) sftpHandler(logger slog.Logger, session ssh.Session) {
 	defer server.Close()

 	err = server.Serve()
-	if errors.Is(err, io.EOF) {
+	if err == nil || errors.Is(err, io.EOF) {
 		// Unless we call `session.Exit(0)` here, the client won't
 		// receive `exit-status` because `(*sftp.Server).Close()`
 		// calls `Close()` on the underlying connection (session),
@@ -589,11 +625,6 @@ func (s *Server) CreateCommand(ctx context.Context, script string, env []string)
 		return nil, xerrors.Errorf("get user shell: %w", err)
 	}

-	manifest := s.Manifest.Load()
-	if manifest == nil {
-		return nil, xerrors.Errorf("no metadata was provided")
-	}
-
 	// OpenSSH executes all commands with the users current shell.
 	// We replicate that behavior for IDE support.
 	caller := "-c"
@@ -638,7 +669,7 @@ func (s *Server) CreateCommand(ctx context.Context, script string, env []string)
 	}

 	cmd := pty.CommandContext(ctx, name, args...)
-	cmd.Dir = manifest.Directory
+	cmd.Dir = s.config.WorkingDirectory()

 	// If the metadata directory doesn't exist, we run the command
 	// in the users home directory.
@@ -652,21 +683,7 @@ func (s *Server) CreateCommand(ctx context.Context, script string, env []string)
 		cmd.Dir = homedir
 	}
 	cmd.Env = append(os.Environ(), env...)
-	executablePath, err := os.Executable()
-	if err != nil {
-		return nil, xerrors.Errorf("getting os executable: %w", err)
-	}
-	// Set environment variables reliable detection of being inside a
-	// Coder workspace.
-	cmd.Env = append(cmd.Env, "CODER=true")
 	cmd.Env = append(cmd.Env, fmt.Sprintf("USER=%s", username))
-	// Git on Windows resolves with UNIX-style paths.
-	// If using backslashes, it's unable to find the executable.
-	unixExecutablePath := strings.ReplaceAll(executablePath, "\\", "/")
-	cmd.Env = append(cmd.Env, fmt.Sprintf(`GIT_SSH_COMMAND=%s gitssh --`, unixExecutablePath))
-
-	// Specific Coder subcommands require the agent token exposed!
-	cmd.Env = append(cmd.Env, fmt.Sprintf("CODER_AGENT_TOKEN=%s", s.AgentToken()))

 	// Set SSH connection environment variables (these are also set by OpenSSH
 	// and thus expected to be present by SSH clients). Since the agent does
@@ -677,26 +694,9 @@ func (s *Server) CreateCommand(ctx context.Context, script string, env []string)
 	cmd.Env = append(cmd.Env, fmt.Sprintf("SSH_CLIENT=%s %s %s", srcAddr, srcPort, dstPort))
 	cmd.Env = append(cmd.Env, fmt.Sprintf("SSH_CONNECTION=%s %s %s %s", srcAddr, srcPort, dstAddr, dstPort))

-	// This adds the ports dialog to code-server that enables
-	// proxying a port dynamically.
-	cmd.Env = append(cmd.Env, fmt.Sprintf("VSCODE_PROXY_URI=%s", manifest.VSCodePortProxyURI))
-
-	// Hide Coder message on code-server's "Getting Started" page
-	cmd.Env = append(cmd.Env, "CS_DISABLE_GETTING_STARTED_OVERRIDE=true")
-
-	// Load environment variables passed via the agent.
-	// These should override all variables we manually specify.
-	for envKey, value := range manifest.EnvironmentVariables {
-		// Expanding environment variables allows for customization
-		// of the $PATH, among other variables. Customers can prepend
-		// or append to the $PATH, so allowing expand is required!
-		cmd.Env = append(cmd.Env, fmt.Sprintf("%s=%s", envKey, os.ExpandEnv(value)))
-	}
-
-	// Agent-level environment variables should take over all!
-	// This is used for setting agent-specific variables like "CODER_AGENT_TOKEN".
-	for envKey, value := range s.Env {
-		cmd.Env = append(cmd.Env, fmt.Sprintf("%s=%s", envKey, value))
+	cmd.Env, err = s.config.UpdateEnv(cmd.Env)
+	if err != nil {
+		return nil, xerrors.Errorf("apply env: %w", err)
 	}

 	return cmd, nil
@@ -37,7 +37,7 @@ func Test_sessionStart_orphan(t *testing.T) {
 	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitMedium)
 	defer cancel()
 	logger := slogtest.Make(t, nil)
-	s, err := NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), 0, "")
+	s, err := NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), nil)
 	require.NoError(t, err)
 	defer s.Close()

@@ -17,14 +17,12 @@ import (
 	"github.com/spf13/afero"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-	"go.uber.org/atomic"
 	"go.uber.org/goleak"
 	"golang.org/x/crypto/ssh"

 	"cdr.dev/slog/sloggers/slogtest"

 	"github.com/coder/coder/v2/agent/agentssh"
-	"github.com/coder/coder/v2/codersdk/agentsdk"
 	"github.com/coder/coder/v2/pty/ptytest"
 	"github.com/coder/coder/v2/testutil"
 )
@@ -38,14 +36,10 @@ func TestNewServer_ServeClient(t *testing.T) {

 	ctx := context.Background()
 	logger := slogtest.Make(t, nil)
-	s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), 0, "")
+	s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), nil)
 	require.NoError(t, err)
 	defer s.Close()

-	// The assumption is that these are set before serving SSH connections.
-	s.AgentToken = func() string { return "" }
-	s.Manifest = atomic.NewPointer(&agentsdk.Manifest{})
-
 	ln, err := net.Listen("tcp", "127.0.0.1:0")
 	require.NoError(t, err)

@@ -83,13 +77,11 @@ func TestNewServer_ExecuteShebang(t *testing.T) {

 	ctx := context.Background()
 	logger := slogtest.Make(t, nil)
-	s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), 0, "")
+	s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), nil)
 	require.NoError(t, err)
 	t.Cleanup(func() {
 		_ = s.Close()
 	})
-	s.AgentToken = func() string { return "" }
-	s.Manifest = atomic.NewPointer(&agentsdk.Manifest{})

 	t.Run("Basic", func(t *testing.T) {
 		t.Parallel()
@@ -116,14 +108,10 @@ func TestNewServer_CloseActiveConnections(t *testing.T) {

 	ctx := context.Background()
 	logger := slogtest.Make(t, &slogtest.Options{IgnoreErrors: true})
-	s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), 0, "")
+	s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), nil)
 	require.NoError(t, err)
 	defer s.Close()

-	// The assumption is that these are set before serving SSH connections.
-	s.AgentToken = func() string { return "" }
-	s.Manifest = atomic.NewPointer(&agentsdk.Manifest{})
-
 	ln, err := net.Listen("tcp", "127.0.0.1:0")
 	require.NoError(t, err)

@@ -171,14 +159,10 @@ func TestNewServer_Signal(t *testing.T) {

 		ctx := context.Background()
 		logger := slogtest.Make(t, nil)
-		s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), 0, "")
+		s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), nil)
 		require.NoError(t, err)
 		defer s.Close()

-		// The assumption is that these are set before serving SSH connections.
-		s.AgentToken = func() string { return "" }
-		s.Manifest = atomic.NewPointer(&agentsdk.Manifest{})
-
 		ln, err := net.Listen("tcp", "127.0.0.1:0")
 		require.NoError(t, err)

@@ -240,14 +224,10 @@ func TestNewServer_Signal(t *testing.T) {

 		ctx := context.Background()
 		logger := slogtest.Make(t, nil)
-		s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), 0, "")
+		s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), nil)
 		require.NoError(t, err)
 		defer s.Close()

-		// The assumption is that these are set before serving SSH connections.
-		s.AgentToken = func() string { return "" }
-		s.Manifest = atomic.NewPointer(&agentsdk.Manifest{})
-
 		ln, err := net.Listen("tcp", "127.0.0.1:0")
 		require.NoError(t, err)

@@ -2,11 +2,14 @@ package agentssh

 import (
 	"context"
+	"errors"
 	"fmt"
+	"io/fs"
 	"net"
 	"os"
 	"path/filepath"
 	"sync"
+	"syscall"

 	"github.com/gliderlabs/ssh"
 	gossh "golang.org/x/crypto/ssh"
@@ -33,22 +36,29 @@ type forwardedStreamLocalPayload struct {
 type forwardedUnixHandler struct {
 	sync.Mutex
 	log      slog.Logger
-	forwards map[string]net.Listener
+	forwards map[forwardKey]net.Listener
+}
+
+type forwardKey struct {
+	sessionID string
+	addr      string
+}
+
+func newForwardedUnixHandler(log slog.Logger) *forwardedUnixHandler {
+	return &forwardedUnixHandler{
+		log:      log,
+		forwards: make(map[forwardKey]net.Listener),
+	}
 }

 func (h *forwardedUnixHandler) HandleSSHRequest(ctx ssh.Context, _ *ssh.Server, req *gossh.Request) (bool, []byte) {
 	h.log.Debug(ctx, "handling SSH unix forward")
-	h.Lock()
-	if h.forwards == nil {
-		h.forwards = make(map[string]net.Listener)
-	}
-	h.Unlock()
 	conn, ok := ctx.Value(ssh.ContextKeyConn).(*gossh.ServerConn)
 	if !ok {
 		h.log.Warn(ctx, "SSH unix forward request from client with no gossh connection")
 		return false, nil
 	}
-	log := h.log.With(slog.F("remote_addr", conn.RemoteAddr()))
+	log := h.log.With(slog.F("session_id", ctx.SessionID()), slog.F("remote_addr", conn.RemoteAddr()))

 	switch req.Type {
 	case "streamlocal-forward@openssh.com":
@@ -62,14 +72,22 @@ func (h *forwardedUnixHandler) HandleSSHRequest(ctx ssh.Context, _ *ssh.Server,
 		addr := reqPayload.SocketPath
 		log = log.With(slog.F("socket_path", addr))
 		log.Debug(ctx, "request begin SSH unix forward")
+
+		key := forwardKey{
+			sessionID: ctx.SessionID(),
+			addr:      addr,
+		}
+
 		h.Lock()
-		_, ok := h.forwards[addr]
+		_, ok := h.forwards[key]
 		h.Unlock()
 		if ok {
-			log.Warn(ctx, "SSH unix forward request for socket path that is already being forwarded (maybe to another client?)",
-				slog.F("socket_path", addr),
-			)
-			return false, nil
+			// In cases where `ExitOnForwardFailure=yes` is set, returning false
+			// here will cause the connection to be closed. To avoid this, and
+			// to match OpenSSH behavior, we silently ignore the second forward
+			// request.
+			log.Warn(ctx, "SSH unix forward request for socket path that is already being forwarded on this session, ignoring")
+			return true, nil
 		}

 		// Create socket parent dir if not exists.
@@ -83,12 +101,20 @@ func (h *forwardedUnixHandler) HandleSSHRequest(ctx ssh.Context, _ *ssh.Server,
 			return false, nil
 		}

-		ln, err := net.Listen("unix", addr)
+		// Remove existing socket if it exists. We do not use os.Remove() here
+		// so that directories are kept. Note that it's possible that we will
+		// overwrite a regular file here. Both of these behaviors match OpenSSH,
+		// however, which is why we unlink.
+		err = unlink(addr)
+		if err != nil && !errors.Is(err, fs.ErrNotExist) {
+			log.Warn(ctx, "remove existing socket for SSH unix forward request", slog.Error(err))
+			return false, nil
+		}
+
+		lc := &net.ListenConfig{}
+		ln, err := lc.Listen(ctx, "unix", addr)
 		if err != nil {
-			log.Warn(ctx, "listen on Unix socket for SSH unix forward request",
-				slog.F("socket_path", addr),
-				slog.Error(err),
-			)
+			log.Warn(ctx, "listen on Unix socket for SSH unix forward request", slog.Error(err))
 			return false, nil
 		}
 		log.Debug(ctx, "SSH unix forward listening on socket")
@@ -99,7 +125,7 @@ func (h *forwardedUnixHandler) HandleSSHRequest(ctx ssh.Context, _ *ssh.Server,
 		//
 		// This is also what the upstream TCP version of this code does.
 		h.Lock()
-		h.forwards[addr] = ln
+		h.forwards[key] = ln
 		h.Unlock()
 		log.Debug(ctx, "SSH unix forward added to cache")

@@ -115,9 +141,7 @@ func (h *forwardedUnixHandler) HandleSSHRequest(ctx ssh.Context, _ *ssh.Server,
 				c, err := ln.Accept()
 				if err != nil {
 					if !xerrors.Is(err, net.ErrClosed) {
-						log.Warn(ctx, "accept on local Unix socket for SSH unix forward request",
-							slog.Error(err),
-						)
+						log.Warn(ctx, "accept on local Unix socket for SSH unix forward request", slog.Error(err))
 					}
 					// closed below
 					log.Debug(ctx, "SSH unix forward listener closed")
@@ -131,10 +155,7 @@ func (h *forwardedUnixHandler) HandleSSHRequest(ctx ssh.Context, _ *ssh.Server,
 				go func() {
 					ch, reqs, err := conn.OpenChannel("forwarded-streamlocal@openssh.com", payload)
 					if err != nil {
-						h.log.Warn(ctx, "open SSH unix forward channel to client",
-							slog.F("socket_path", addr),
-							slog.Error(err),
-						)
+						h.log.Warn(ctx, "open SSH unix forward channel to client", slog.Error(err))
 						_ = c.Close()
 						return
 					}
@@ -144,12 +165,11 @@ func (h *forwardedUnixHandler) HandleSSHRequest(ctx ssh.Context, _ *ssh.Server,
 			}

 			h.Lock()
-			ln2, ok := h.forwards[addr]
-			if ok && ln2 == ln {
-				delete(h.forwards, addr)
+			if ln2, ok := h.forwards[key]; ok && ln2 == ln {
+				delete(h.forwards, key)
 			}
 			h.Unlock()
-			log.Debug(ctx, "SSH unix forward listener removed from cache", slog.F("path", addr))
+			log.Debug(ctx, "SSH unix forward listener removed from cache")
 			_ = ln.Close()
 		}()

@@ -162,13 +182,22 @@ func (h *forwardedUnixHandler) HandleSSHRequest(ctx ssh.Context, _ *ssh.Server,
 			h.log.Warn(ctx, "parse cancel-streamlocal-forward@openssh.com (SSH unix forward) request payload from client", slog.Error(err))
 			return false, nil
 		}
-		log.Debug(ctx, "request to cancel SSH unix forward", slog.F("path", reqPayload.SocketPath))
-		h.Lock()
-		ln, ok := h.forwards[reqPayload.SocketPath]
-		h.Unlock()
-		if ok {
-			_ = ln.Close()
+		log.Debug(ctx, "request to cancel SSH unix forward", slog.F("socket_path", reqPayload.SocketPath))
+
+		key := forwardKey{
+			sessionID: ctx.SessionID(),
+			addr:      reqPayload.SocketPath,
 		}
+
+		h.Lock()
+		ln, ok := h.forwards[key]
+		delete(h.forwards, key)
+		h.Unlock()
+		if !ok {
+			log.Warn(ctx, "SSH unix forward not found in cache")
+			return true, nil
+		}
+		_ = ln.Close()
 		return true, nil

 	default:
@@ -209,3 +238,15 @@ func directStreamLocalHandler(_ *ssh.Server, _ *gossh.ServerConn, newChan gossh.

 	Bicopy(ctx, ch, dconn)
 }
+
+// unlink removes files and unlike os.Remove, directories are kept.
+func unlink(path string) error {
+	// Ignore EINTR like os.Remove, see ignoringEINTR in os/file_posix.go
+	// for more details.
+	for {
+		err := syscall.Unlink(path)
+		if !errors.Is(err, syscall.EINTR) {
+			return err
+		}
+	}
+}
@@ -1,6 +1,7 @@
 package agentssh

 import (
+	"context"
 	"strings"
 	"sync"

@@ -26,6 +27,7 @@ type localForwardChannelData struct {
 type JetbrainsChannelWatcher struct {
 	gossh.NewChannel
 	jetbrainsCounter *atomic.Int64
+	logger           slog.Logger
 }

 func NewJetbrainsChannelWatcher(ctx ssh.Context, logger slog.Logger, newChannel gossh.NewChannel, counter *atomic.Int64) gossh.NewChannel {
@@ -58,6 +60,7 @@ func NewJetbrainsChannelWatcher(ctx ssh.Context, logger slog.Logger, newChannel
 	return &JetbrainsChannelWatcher{
 		NewChannel:       newChannel,
 		jetbrainsCounter: counter,
+		logger:           logger.With(slog.F("destination_port", d.DestPort)),
 	}
 }

@@ -67,11 +70,15 @@ func (w *JetbrainsChannelWatcher) Accept() (gossh.Channel, <-chan *gossh.Request
 		return c, r, err
 	}
 	w.jetbrainsCounter.Add(1)
+	// nolint: gocritic // JetBrains is a proper noun and should be capitalized
+	w.logger.Debug(context.Background(), "JetBrains watcher accepted channel")

 	return &ChannelOnClose{
 		Channel: c,
 		done: func() {
 			w.jetbrainsCounter.Add(-1)
+			// nolint: gocritic // JetBrains is a proper noun and should be capitalized
+			w.logger.Debug(context.Background(), "JetBrains watcher channel closed")
 		},
 	}, r, err
 }
@@ -3,6 +3,7 @@
 package agentssh

 import (
+	"errors"
 	"fmt"
 	"os"

@@ -11,24 +12,37 @@ import (
 )

 func getListeningPortProcessCmdline(port uint32) (string, error) {
-	tabs, err := netstat.TCPSocks(func(s *netstat.SockTabEntry) bool {
+	acceptFn := func(s *netstat.SockTabEntry) bool {
 		return s.LocalAddr != nil && uint32(s.LocalAddr.Port) == port
-	})
-	if err != nil {
-		return "", xerrors.Errorf("inspect port %d: %w", port, err)
 	}
-	if len(tabs) == 0 {
-		return "", nil
+	tabs4, err4 := netstat.TCPSocks(acceptFn)
+	tabs6, err6 := netstat.TCP6Socks(acceptFn)
+
+	// In the common case, we want to check ipv4 listening addresses.  If this
+	// fails, we should return an error.  We also need to check ipv6.  The
+	// assumption is, if we have an err4, and 0 ipv6 addresses listed, then we are
+	// interested in the err4 (and vice versa).  So return both errors (at least 1
+	// is non-nil) if the other list is empty.
+	if (err4 != nil && len(tabs6) == 0) || (err6 != nil && len(tabs4) == 0) {
+		return "", xerrors.Errorf("inspect port %d: %w", port, errors.Join(err4, err6))
 	}

-	// Defensive check.
-	if tabs[0].Process == nil {
+	var proc *netstat.Process
+	if len(tabs4) > 0 {
+		proc = tabs4[0].Process
+	} else if len(tabs6) > 0 {
+		proc = tabs6[0].Process
+	}
+	if proc == nil {
+		// Either nothing is listening on this port or we were unable to read the
+		// process details (permission issues reading /proc/$pid/* potentially).
+		// Or, perhaps /proc/net/tcp{,6} is not listing the port for some reason.
 		return "", nil
 	}

 	// The process name provided by go-netstat does not include the full command
 	// line so grab that instead.
-	pid := tabs[0].Process.Pid
+	pid := proc.Pid
 	data, err := os.ReadFile(fmt.Sprintf("/proc/%d/cmdline", pid))
 	if err != nil {
 		return "", xerrors.Errorf("read /proc/%d/cmdline: %w", pid, err)
@@ -6,6 +6,7 @@ import (
 	"encoding/hex"
 	"errors"
 	"fmt"
+	"io"
 	"net"
 	"os"
 	"path/filepath"
@@ -31,9 +32,9 @@ func (s *Server) x11Callback(ctx ssh.Context, x11 ssh.X11) bool {
 		return false
 	}

-	err = s.fs.MkdirAll(s.x11SocketDir, 0o700)
+	err = s.fs.MkdirAll(s.config.X11SocketDir, 0o700)
 	if err != nil {
-		s.logger.Warn(ctx, "failed to make the x11 socket dir", slog.F("dir", s.x11SocketDir), slog.Error(err))
+		s.logger.Warn(ctx, "failed to make the x11 socket dir", slog.F("dir", s.config.X11SocketDir), slog.Error(err))
 		s.metrics.x11HandlerErrors.WithLabelValues("socker_dir").Add(1)
 		return false
 	}
@@ -56,7 +57,7 @@ func (s *Server) x11Handler(ctx ssh.Context, x11 ssh.X11) bool {
 		return false
 	}
 	// We want to overwrite the socket so that subsequent connections will succeed.
-	socketPath := filepath.Join(s.x11SocketDir, fmt.Sprintf("X%d", x11.ScreenNumber))
+	socketPath := filepath.Join(s.config.X11SocketDir, fmt.Sprintf("X%d", x11.ScreenNumber))
 	err := os.Remove(socketPath)
 	if err != nil && !errors.Is(err, os.ErrNotExist) {
 		s.logger.Warn(ctx, "failed to remove existing X11 socket", slog.Error(err))
@@ -141,7 +142,7 @@ func addXauthEntry(ctx context.Context, fs afero.Fs, host string, display string
 	}

 	// Open or create the Xauthority file
-	file, err := fs.OpenFile(xauthPath, os.O_RDWR|os.O_CREATE|os.O_APPEND, 0o600)
+	file, err := fs.OpenFile(xauthPath, os.O_RDWR|os.O_CREATE, 0o600)
 	if err != nil {
 		return xerrors.Errorf("failed to open Xauthority file: %w", err)
 	}
@@ -153,7 +154,105 @@ func addXauthEntry(ctx context.Context, fs afero.Fs, host string, display string
 		return xerrors.Errorf("failed to decode auth cookie: %w", err)
 	}

-	// Write Xauthority entry
+	// Read the Xauthority file and look for an existing entry for the host,
+	// display, and auth protocol. If an entry is found, overwrite the auth
+	// cookie (if it fits). Otherwise, mark the entry for deletion.
+	type deleteEntry struct {
+		start, end int
+	}
+	var deleteEntries []deleteEntry
+	pos := 0
+	updated := false
+	for {
+		entry, err := readXauthEntry(file)
+		if err != nil {
+			if errors.Is(err, io.EOF) {
+				break
+			}
+			return xerrors.Errorf("failed to read Xauthority entry: %w", err)
+		}
+
+		nextPos := pos + entry.Len()
+		cookieStartPos := nextPos - len(entry.authCookie)
+
+		if entry.family == 0x0100 && entry.address == host && entry.display == display && entry.authProtocol == authProtocol {
+			if !updated && len(entry.authCookie) == len(authCookieBytes) {
+				// Overwrite the auth cookie
+				_, err := file.WriteAt(authCookieBytes, int64(cookieStartPos))
+				if err != nil {
+					return xerrors.Errorf("failed to write auth cookie: %w", err)
+				}
+				updated = true
+			} else {
+				// Mark entry for deletion.
+				if len(deleteEntries) > 0 && deleteEntries[len(deleteEntries)-1].end == pos {
+					deleteEntries[len(deleteEntries)-1].end = nextPos
+				} else {
+					deleteEntries = append(deleteEntries, deleteEntry{
+						start: pos,
+						end:   nextPos,
+					})
+				}
+			}
+		}
+
+		pos = nextPos
+	}
+
+	// In case the magic cookie changed, or we've previously bloated the
+	// Xauthority file, we may have to delete entries.
+	if len(deleteEntries) > 0 {
+		// Read the entire file into memory. This is not ideal, but it's the
+		// simplest way to delete entries from the middle of the file. The
+		// Xauthority file is small, so this should be fine.
+		_, err = file.Seek(0, io.SeekStart)
+		if err != nil {
+			return xerrors.Errorf("failed to seek Xauthority file: %w", err)
+		}
+		data, err := io.ReadAll(file)
+		if err != nil {
+			return xerrors.Errorf("failed to read Xauthority file: %w", err)
+		}
+
+		// Delete the entries in reverse order.
+		for i := len(deleteEntries) - 1; i >= 0; i-- {
+			entry := deleteEntries[i]
+			// Safety check: ensure the entry is still there.
+			if entry.start > len(data) || entry.end > len(data) {
+				continue
+			}
+			data = append(data[:entry.start], data[entry.end:]...)
+		}
+
+		// Write the data back to the file.
+		_, err = file.Seek(0, io.SeekStart)
+		if err != nil {
+			return xerrors.Errorf("failed to seek Xauthority file: %w", err)
+		}
+		_, err = file.Write(data)
+		if err != nil {
+			return xerrors.Errorf("failed to write Xauthority file: %w", err)
+		}
+
+		// Truncate the file.
+		err = file.Truncate(int64(len(data)))
+		if err != nil {
+			return xerrors.Errorf("failed to truncate Xauthority file: %w", err)
+		}
+	}
+
+	// Return if we've already updated the entry.
+	if updated {
+		return nil
+	}
+
+	// Ensure we're at the end (append).
+	_, err = file.Seek(0, io.SeekEnd)
+	if err != nil {
+		return xerrors.Errorf("failed to seek Xauthority file: %w", err)
+	}
+
+	// Append Xauthority entry.
 	family := uint16(0x0100) // FamilyLocal
 	err = binary.Write(file, binary.BigEndian, family)
 	if err != nil {
@@ -198,3 +297,96 @@ func addXauthEntry(ctx context.Context, fs afero.Fs, host string, display string

 	return nil
 }
+
+// xauthEntry is an representation of an Xauthority entry.
+//
+// The Xauthority file format is as follows:
+//
+// - 16-bit family
+// - 16-bit address length
+// - address
+// - 16-bit display length
+// - display
+// - 16-bit auth protocol length
+// - auth protocol
+// - 16-bit auth cookie length
+// - auth cookie
+type xauthEntry struct {
+	family       uint16
+	address      string
+	display      string
+	authProtocol string
+	authCookie   []byte
+}
+
+func (e xauthEntry) Len() int {
+	// 5 * uint16 = 10 bytes for the family/length fields.
+	return 2*5 + len(e.address) + len(e.display) + len(e.authProtocol) + len(e.authCookie)
+}
+
+func readXauthEntry(r io.Reader) (xauthEntry, error) {
+	var entry xauthEntry
+
+	// Read family
+	err := binary.Read(r, binary.BigEndian, &entry.family)
+	if err != nil {
+		return xauthEntry{}, xerrors.Errorf("failed to read family: %w", err)
+	}
+
+	// Read address
+	var addressLength uint16
+	err = binary.Read(r, binary.BigEndian, &addressLength)
+	if err != nil {
+		return xauthEntry{}, xerrors.Errorf("failed to read address length: %w", err)
+	}
+
+	addressBytes := make([]byte, addressLength)
+	_, err = r.Read(addressBytes)
+	if err != nil {
+		return xauthEntry{}, xerrors.Errorf("failed to read address: %w", err)
+	}
+	entry.address = string(addressBytes)
+
+	// Read display
+	var displayLength uint16
+	err = binary.Read(r, binary.BigEndian, &displayLength)
+	if err != nil {
+		return xauthEntry{}, xerrors.Errorf("failed to read display length: %w", err)
+	}
+
+	displayBytes := make([]byte, displayLength)
+	_, err = r.Read(displayBytes)
+	if err != nil {
+		return xauthEntry{}, xerrors.Errorf("failed to read display: %w", err)
+	}
+	entry.display = string(displayBytes)
+
+	// Read auth protocol
+	var authProtocolLength uint16
+	err = binary.Read(r, binary.BigEndian, &authProtocolLength)
+	if err != nil {
+		return xauthEntry{}, xerrors.Errorf("failed to read auth protocol length: %w", err)
+	}
+
+	authProtocolBytes := make([]byte, authProtocolLength)
+	_, err = r.Read(authProtocolBytes)
+	if err != nil {
+		return xauthEntry{}, xerrors.Errorf("failed to read auth protocol: %w", err)
+	}
+	entry.authProtocol = string(authProtocolBytes)
+
+	// Read auth cookie
+	var authCookieLength uint16
+	err = binary.Read(r, binary.BigEndian, &authCookieLength)
+	if err != nil {
+		return xauthEntry{}, xerrors.Errorf("failed to read auth cookie length: %w", err)
+	}
+
+	entry.authCookie = make([]byte, authCookieLength)
+	_, err = r.Read(entry.authCookie)
+	if err != nil {
+		return xauthEntry{}, xerrors.Errorf("failed to read auth cookie: %w", err)
+	}
+
+	return entry, nil
+}
@@ -0,0 +1,254 @@
+package agentssh
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/spf13/afero"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func Test_addXauthEntry(t *testing.T) {
+	t.Parallel()
+
+	type testEntry struct {
+		address      string
+		display      string
+		authProtocol string
+		authCookie   string
+	}
+	tests := []struct {
+		name         string
+		authFile     []byte
+		wantAuthFile []byte
+		entries      []testEntry
+	}{
+		{
+			name:     "add entry",
+			authFile: nil,
+			wantAuthFile: []byte{
+				// w/unix:0  MIT-MAGIC-COOKIE-1  00
+				//
+				// 00000000: 0100 0001 7700 0130 0012 4d49 542d 4d41  ....w..0..MIT-MA
+				// 00000010: 4749 432d 434f 4f4b 4945 2d31 0001 00    GIC-COOKIE-1...
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x30,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x01, 0x00,
+			},
+			entries: []testEntry{
+				{
+					address:      "w",
+					display:      "0",
+					authProtocol: "MIT-MAGIC-COOKIE-1",
+					authCookie:   "00",
+				},
+			},
+		},
+		{
+			name:     "add two entries",
+			authFile: []byte{},
+			wantAuthFile: []byte{
+				// w/unix:0  MIT-MAGIC-COOKIE-1  00
+				// w/unix:1  MIT-MAGIC-COOKIE-1  11
+				//
+				// 00000000: 0100 0001 7700 0130 0012 4d49 542d 4d41  ....w..0..MIT-MA
+				// 00000010: 4749 432d 434f 4f4b 4945 2d31 0001 0001  GIC-COOKIE-1....
+				// 00000020: 0000 0177 0001 3100 124d 4954 2d4d 4147  ...w..1..MIT-MAG
+				// 00000030: 4943 2d43 4f4f 4b49 452d 3100 0111       IC-COOKIE-1...
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x30,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x01, 0x00,
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x31,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x01, 0x11,
+			},
+			entries: []testEntry{
+				{
+					address:      "w",
+					display:      "0",
+					authProtocol: "MIT-MAGIC-COOKIE-1",
+					authCookie:   "00",
+				},
+				{
+					address:      "w",
+					display:      "1",
+					authProtocol: "MIT-MAGIC-COOKIE-1",
+					authCookie:   "11",
+				},
+			},
+		},
+		{
+			name: "update entry with new auth cookie length",
+			authFile: []byte{
+				// w/unix:0  MIT-MAGIC-COOKIE-1  00
+				// w/unix:1  MIT-MAGIC-COOKIE-1  11
+				//
+				// 00000000: 0100 0001 7700 0130 0012 4d49 542d 4d41  ....w..0..MIT-MA
+				// 00000010: 4749 432d 434f 4f4b 4945 2d31 0001 0001  GIC-COOKIE-1....
+				// 00000020: 0000 0177 0001 3100 124d 4954 2d4d 4147  ...w..1..MIT-MAG
+				// 00000030: 4943 2d43 4f4f 4b49 452d 3100 0111       IC-COOKIE-1...
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x30,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x01, 0x00,
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x31,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x01, 0x11,
+			},
+			wantAuthFile: []byte{
+				// The order changed, due to new length of auth cookie resulting
+				// in remove + append, we verify that the implementation is
+				// behaving as expected (changing the order is not a requirement,
+				// simply an implementation detail).
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x31,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x01, 0x11,
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x30,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x02, 0xff, 0xff,
+			},
+			entries: []testEntry{
+				{
+					address:      "w",
+					display:      "0",
+					authProtocol: "MIT-MAGIC-COOKIE-1",
+					authCookie:   "ffff",
+				},
+			},
+		},
+		{
+			name: "update entry",
+			authFile: []byte{
+				// 00000000: 0100 0001 7700 0130 0012 4d49 542d 4d41  ....w..0..MIT-MA
+				// 00000010: 4749 432d 434f 4f4b 4945 2d31 0001 0001  GIC-COOKIE-1....
+				// 00000020: 0000 0177 0001 3100 124d 4954 2d4d 4147  ...w..1..MIT-MAG
+				// 00000030: 4943 2d43 4f4f 4b49 452d 3100 0111       IC-COOKIE-1...
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x30,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x01, 0x00,
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x31,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x01, 0x11,
+			},
+			wantAuthFile: []byte{
+				// 00000000: 0100 0001 7700 0130 0012 4d49 542d 4d41  ....w..0..MIT-MA
+				// 00000010: 4749 432d 434f 4f4b 4945 2d31 0001 0001  GIC-COOKIE-1....
+				// 00000020: 0000 0177 0001 3100 124d 4954 2d4d 4147  ...w..1..MIT-MAG
+				// 00000030: 4943 2d43 4f4f 4b49 452d 3100 0111       IC-COOKIE-1...
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x30,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x01, 0xff,
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x31,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x01, 0x11,
+			},
+			entries: []testEntry{
+				{
+					address:      "w",
+					display:      "0",
+					authProtocol: "MIT-MAGIC-COOKIE-1",
+					authCookie:   "ff",
+				},
+			},
+		},
+		{
+			name: "clean up old entries",
+			authFile: []byte{
+				// w/unix:0  MIT-MAGIC-COOKIE-1  80507df050756cdefa504b65adb3bcfb
+				// w/unix:0  MIT-MAGIC-COOKIE-1  267b37f6cbc11b97beb826bb1aab8570
+				// w/unix:0  MIT-MAGIC-COOKIE-1  516e22e2b11d1bd0115dff09c028ca5c
+				//
+				// 00000000: 0100 0001 7700 0130 0012 4d49 542d 4d41  ....w..0..MIT-MA
+				// 00000010: 4749 432d 434f 4f4b 4945 2d31 0010 8050  GIC-COOKIE-1...P
+				// 00000020: 7df0 5075 6cde fa50 4b65 adb3 bcfb 0100  }.Pul..PKe......
+				// 00000030: 0001 7700 0130 0012 4d49 542d 4d41 4749  ..w..0..MIT-MAGI
+				// 00000040: 432d 434f 4f4b 4945 2d31 0010 267b 37f6  C-COOKIE-1..&{7.
+				// 00000050: cbc1 1b97 beb8 26bb 1aab 8570 0100 0001  ......&....p....
+				// 00000060: 7700 0130 0012 4d49 542d 4d41 4749 432d  w..0..MIT-MAGIC-
+				// 00000070: 434f 4f4b 4945 2d31 0010 516e 22e2 b11d  COOKIE-1..Qn"...
+				// 00000080: 1bd0 115d ff09 c028 ca5c                 ...]...(.\
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x30,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x10, 0x80, 0x50,
+				0x7d, 0xf0, 0x50, 0x75, 0x6c, 0xde, 0xfa, 0x50,
+				0x4b, 0x65, 0xad, 0xb3, 0xbc, 0xfb, 0x01, 0x00,
+				0x00, 0x01, 0x77, 0x00, 0x01, 0x30, 0x00, 0x12,
+				0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41, 0x47, 0x49,
+				0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b, 0x49, 0x45,
+				0x2d, 0x31, 0x00, 0x10, 0x26, 0x7b, 0x37, 0xf6,
+				0xcb, 0xc1, 0x1b, 0x97, 0xbe, 0xb8, 0x26, 0xbb,
+				0x1a, 0xab, 0x85, 0x70, 0x01, 0x00, 0x00, 0x01,
+				0x77, 0x00, 0x01, 0x30, 0x00, 0x12, 0x4d, 0x49,
+				0x54, 0x2d, 0x4d, 0x41, 0x47, 0x49, 0x43, 0x2d,
+				0x43, 0x4f, 0x4f, 0x4b, 0x49, 0x45, 0x2d, 0x31,
+				0x00, 0x10, 0x51, 0x6e, 0x22, 0xe2, 0xb1, 0x1d,
+				0x1b, 0xd0, 0x11, 0x5d, 0xff, 0x09, 0xc0, 0x28,
+				0xca, 0x5c,
+			},
+			wantAuthFile: []byte{
+				// w/unix:0  MIT-MAGIC-COOKIE-1  516e5bc892b7162b844abd1fc1a7c16e
+				//
+				// 00000000: 0100 0001 7700 0130 0012 4d49 542d 4d41  ....w..0..MIT-MA
+				// 00000010: 4749 432d 434f 4f4b 4945 2d31 0010 516e  GIC-COOKIE-1..Qn
+				// 00000020: 5bc8 92b7 162b 844a bd1f c1a7 c16e       [....+.J.....n
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x30,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x10, 0x51, 0x6e,
+				0x5b, 0xc8, 0x92, 0xb7, 0x16, 0x2b, 0x84, 0x4a,
+				0xbd, 0x1f, 0xc1, 0xa7, 0xc1, 0x6e,
+			},
+			entries: []testEntry{
+				{
+					address:      "w",
+					display:      "0",
+					authProtocol: "MIT-MAGIC-COOKIE-1",
+					authCookie:   "516e5bc892b7162b844abd1fc1a7c16e",
+				},
+			},
+		},
+	}
+
+	homedir, err := os.UserHomeDir()
+	require.NoError(t, err)
+
+	for _, tt := range tests {
+		tt := tt
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			fs := afero.NewMemMapFs()
+			if tt.authFile != nil {
+				err := afero.WriteFile(fs, filepath.Join(homedir, ".Xauthority"), tt.authFile, 0o600)
+				require.NoError(t, err)
+			}
+
+			for _, entry := range tt.entries {
+				err := addXauthEntry(context.Background(), fs, entry.address, entry.display, entry.authProtocol, entry.authCookie)
+				require.NoError(t, err)
+			}
+
+			gotAuthFile, err := afero.ReadFile(fs, filepath.Join(homedir, ".Xauthority"))
+			require.NoError(t, err)
+
+			if diff := cmp.Diff(tt.wantAuthFile, gotAuthFile); diff != "" {
+				assert.Failf(t, "addXauthEntry() mismatch", "(-want +got):\n%s", diff)
+			}
+		})
+	}
+}
@@ -14,13 +14,11 @@ import (
 	"github.com/spf13/afero"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-	"go.uber.org/atomic"
 	gossh "golang.org/x/crypto/ssh"

 	"cdr.dev/slog"
 	"cdr.dev/slog/sloggers/slogtest"
 	"github.com/coder/coder/v2/agent/agentssh"
-	"github.com/coder/coder/v2/codersdk/agentsdk"
 	"github.com/coder/coder/v2/testutil"
 )

@@ -34,14 +32,12 @@ func TestServer_X11(t *testing.T) {
 	logger := slogtest.Make(t, nil).Leveled(slog.LevelDebug)
 	fs := afero.NewOsFs()
 	dir := t.TempDir()
-	s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), fs, 0, dir)
+	s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), fs, &agentssh.Config{
+		X11SocketDir: dir,
+	})
 	require.NoError(t, err)
 	defer s.Close()

-	// The assumption is that these are set before serving SSH connections.
-	s.AgentToken = func() string { return "" }
-	s.Manifest = atomic.NewPointer(&agentsdk.Manifest{})
-
 	ln, err := net.Listen("tcp", "127.0.0.1:0")
 	require.NoError(t, err)

@@ -3,164 +3,133 @@ package agenttest
 import (
 	"context"
 	"io"
-	"net"
 	"sync"
+	"sync/atomic"
 	"testing"
 	"time"

 	"github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 	"golang.org/x/exp/maps"
+	"golang.org/x/exp/slices"
 	"golang.org/x/xerrors"
+	"google.golang.org/protobuf/types/known/durationpb"
+	"storj.io/drpc"
+	"storj.io/drpc/drpcmux"
+	"storj.io/drpc/drpcserver"
+	"tailscale.com/tailcfg"

 	"cdr.dev/slog"
+	agentproto "github.com/coder/coder/v2/agent/proto"
 	"github.com/coder/coder/v2/codersdk"
 	"github.com/coder/coder/v2/codersdk/agentsdk"
+	drpcsdk "github.com/coder/coder/v2/codersdk/drpc"
 	"github.com/coder/coder/v2/tailnet"
+	"github.com/coder/coder/v2/tailnet/proto"
 	"github.com/coder/coder/v2/testutil"
 )

+const statsInterval = 500 * time.Millisecond
+
 func NewClient(t testing.TB,
 	logger slog.Logger,
 	agentID uuid.UUID,
 	manifest agentsdk.Manifest,
-	statsChan chan *agentsdk.Stats,
+	statsChan chan *agentproto.Stats,
 	coordinator tailnet.Coordinator,
 ) *Client {
 	if manifest.AgentID == uuid.Nil {
 		manifest.AgentID = agentID
 	}
+	coordPtr := atomic.Pointer[tailnet.Coordinator]{}
+	coordPtr.Store(&coordinator)
+	mux := drpcmux.New()
+	derpMapUpdates := make(chan *tailcfg.DERPMap)
+	drpcService := &tailnet.DRPCService{
+		CoordPtr:               &coordPtr,
+		Logger:                 logger.Named("tailnetsvc"),
+		DerpMapUpdateFrequency: time.Microsecond,
+		DerpMapFn:              func() *tailcfg.DERPMap { return <-derpMapUpdates },
+	}
+	err := proto.DRPCRegisterTailnet(mux, drpcService)
+	require.NoError(t, err)
+	mp, err := agentsdk.ProtoFromManifest(manifest)
+	require.NoError(t, err)
+	fakeAAPI := NewFakeAgentAPI(t, logger, mp, statsChan)
+	err = agentproto.DRPCRegisterAgent(mux, fakeAAPI)
+	require.NoError(t, err)
+	server := drpcserver.NewWithOptions(mux, drpcserver.Options{
+		Log: func(err error) {
+			if xerrors.Is(err, io.EOF) {
+				return
+			}
+			logger.Debug(context.Background(), "drpc server error", slog.Error(err))
+		},
+	})
 	return &Client{
 		t:              t,
 		logger:         logger.Named("client"),
 		agentID:        agentID,
-		manifest:       manifest,
-		statsChan:      statsChan,
 		coordinator:    coordinator,
-		derpMapUpdates: make(chan agentsdk.DERPMapUpdate),
+		server:         server,
+		fakeAgentAPI:   fakeAAPI,
+		derpMapUpdates: derpMapUpdates,
 	}
 }

 type Client struct {
-	t                    testing.TB
-	logger               slog.Logger
-	agentID              uuid.UUID
-	manifest             agentsdk.Manifest
-	metadata             map[string]agentsdk.Metadata
-	statsChan            chan *agentsdk.Stats
-	coordinator          tailnet.Coordinator
-	LastWorkspaceAgent   func()
-	PatchWorkspaceLogs   func() error
-	GetServiceBannerFunc func() (codersdk.ServiceBannerConfig, error)
+	t                  testing.TB
+	logger             slog.Logger
+	agentID            uuid.UUID
+	coordinator        tailnet.Coordinator
+	server             *drpcserver.Server
+	fakeAgentAPI       *FakeAgentAPI
+	LastWorkspaceAgent func()

-	mu              sync.Mutex // Protects following.
-	lifecycleStates []codersdk.WorkspaceAgentLifecycle
-	startup         agentsdk.PostStartupRequest
-	logs            []agentsdk.Log
-	derpMapUpdates  chan agentsdk.DERPMapUpdate
+	mu             sync.Mutex // Protects following.
+	logs           []agentsdk.Log
+	derpMapUpdates chan *tailcfg.DERPMap
+	derpMapOnce    sync.Once
 }

-func (c *Client) Manifest(_ context.Context) (agentsdk.Manifest, error) {
-	return c.manifest, nil
+func (*Client) RewriteDERPMap(*tailcfg.DERPMap) {}
+
+func (c *Client) Close() {
+	c.derpMapOnce.Do(func() { close(c.derpMapUpdates) })
 }

-func (c *Client) Listen(_ context.Context) (net.Conn, error) {
-	clientConn, serverConn := net.Pipe()
-	closed := make(chan struct{})
+func (c *Client) ConnectRPC(ctx context.Context) (drpc.Conn, error) {
+	conn, lis := drpcsdk.MemTransportPipe()
 	c.LastWorkspaceAgent = func() {
-		_ = serverConn.Close()
-		_ = clientConn.Close()
-		<-closed
+		_ = conn.Close()
+		_ = lis.Close()
 	}
 	c.t.Cleanup(c.LastWorkspaceAgent)
+	serveCtx, cancel := context.WithCancel(ctx)
+	c.t.Cleanup(cancel)
+	streamID := tailnet.StreamID{
+		Name: "agenttest",
+		ID:   c.agentID,
+		Auth: tailnet.AgentCoordinateeAuth{ID: c.agentID},
+	}
+	serveCtx = tailnet.WithStreamID(serveCtx, streamID)
 	go func() {
-		_ = c.coordinator.ServeAgent(serverConn, c.agentID, "")
-		close(closed)
+		_ = c.server.Serve(serveCtx, lis)
 	}()
-	return clientConn, nil
-}
-
-func (c *Client) ReportStats(ctx context.Context, _ slog.Logger, statsChan <-chan *agentsdk.Stats, setInterval func(time.Duration)) (io.Closer, error) {
-	doneCh := make(chan struct{})
-	ctx, cancel := context.WithCancel(ctx)
-
-	go func() {
-		defer close(doneCh)
-
-		setInterval(500 * time.Millisecond)
-		for {
-			select {
-			case <-ctx.Done():
-				return
-			case stat := <-statsChan:
-				select {
-				case c.statsChan <- stat:
-				case <-ctx.Done():
-					return
-				default:
-					// We don't want to send old stats.
-					continue
-				}
-			}
-		}
-	}()
-	return closeFunc(func() error {
-		cancel()
-		<-doneCh
-		close(c.statsChan)
-		return nil
-	}), nil
+	return conn, nil
 }

 func (c *Client) GetLifecycleStates() []codersdk.WorkspaceAgentLifecycle {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	return c.lifecycleStates
+	return c.fakeAgentAPI.GetLifecycleStates()
 }

-func (c *Client) PostLifecycle(ctx context.Context, req agentsdk.PostLifecycleRequest) error {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	c.lifecycleStates = append(c.lifecycleStates, req.State)
-	c.logger.Debug(ctx, "post lifecycle", slog.F("req", req))
-	return nil
-}
-
-func (c *Client) PostAppHealth(ctx context.Context, req agentsdk.PostAppHealthsRequest) error {
-	c.logger.Debug(ctx, "post app health", slog.F("req", req))
-	return nil
-}
-
-func (c *Client) GetStartup() agentsdk.PostStartupRequest {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	return c.startup
+func (c *Client) GetStartup() <-chan *agentproto.Startup {
+	return c.fakeAgentAPI.startupCh
 }

 func (c *Client) GetMetadata() map[string]agentsdk.Metadata {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	return maps.Clone(c.metadata)
-}
-
-func (c *Client) PostMetadata(ctx context.Context, req agentsdk.PostMetadataRequest) error {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	if c.metadata == nil {
-		c.metadata = make(map[string]agentsdk.Metadata)
-	}
-	for _, md := range req.Metadata {
-		c.metadata[md.Key] = md
-		c.logger.Debug(ctx, "post metadata", slog.F("key", md.Key), slog.F("md", md))
-	}
-	return nil
-}
-
-func (c *Client) PostStartup(ctx context.Context, startup agentsdk.PostStartupRequest) error {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	c.startup = startup
-	c.logger.Debug(ctx, "post startup", slog.F("req", startup))
-	return nil
+	return c.fakeAgentAPI.GetMetadata()
 }

 func (c *Client) GetStartupLogs() []agentsdk.Log {
@@ -169,35 +138,11 @@ func (c *Client) GetStartupLogs() []agentsdk.Log {
 	return c.logs
 }

-func (c *Client) PatchLogs(ctx context.Context, logs agentsdk.PatchLogs) error {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	if c.PatchWorkspaceLogs != nil {
-		return c.PatchWorkspaceLogs()
-	}
-	c.logs = append(c.logs, logs.Logs...)
-	c.logger.Debug(ctx, "patch startup logs", slog.F("req", logs))
-	return nil
-}
-
 func (c *Client) SetServiceBannerFunc(f func() (codersdk.ServiceBannerConfig, error)) {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-
-	c.GetServiceBannerFunc = f
+	c.fakeAgentAPI.SetServiceBannerFunc(f)
 }

-func (c *Client) GetServiceBanner(ctx context.Context) (codersdk.ServiceBannerConfig, error) {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	c.logger.Debug(ctx, "get service banner")
-	if c.GetServiceBannerFunc != nil {
-		return c.GetServiceBannerFunc()
-	}
-	return codersdk.ServiceBannerConfig{}, nil
-}
-
-func (c *Client) PushDERPMapUpdate(update agentsdk.DERPMapUpdate) error {
+func (c *Client) PushDERPMapUpdate(update *tailcfg.DERPMap) error {
 	timer := time.NewTimer(testutil.WaitShort)
 	defer timer.Stop()
 	select {
@@ -209,16 +154,139 @@ func (c *Client) PushDERPMapUpdate(update agentsdk.DERPMapUpdate) error {
 	return nil
 }

-func (c *Client) DERPMapUpdates(_ context.Context) (<-chan agentsdk.DERPMapUpdate, io.Closer, error) {
-	closed := make(chan struct{})
-	return c.derpMapUpdates, closeFunc(func() error {
-		close(closed)
-		return nil
-	}), nil
+func (c *Client) SetLogsChannel(ch chan<- *agentproto.BatchCreateLogsRequest) {
+	c.fakeAgentAPI.SetLogsChannel(ch)
 }

-type closeFunc func() error
+type FakeAgentAPI struct {
+	sync.Mutex
+	t      testing.TB
+	logger slog.Logger

-func (c closeFunc) Close() error {
-	return c()
+	manifest        *agentproto.Manifest
+	startupCh       chan *agentproto.Startup
+	statsCh         chan *agentproto.Stats
+	appHealthCh     chan *agentproto.BatchUpdateAppHealthRequest
+	logsCh          chan<- *agentproto.BatchCreateLogsRequest
+	lifecycleStates []codersdk.WorkspaceAgentLifecycle
+	metadata        map[string]agentsdk.Metadata
+
+	getServiceBannerFunc func() (codersdk.ServiceBannerConfig, error)
+}
+
+func (f *FakeAgentAPI) GetManifest(context.Context, *agentproto.GetManifestRequest) (*agentproto.Manifest, error) {
+	return f.manifest, nil
+}
+
+func (f *FakeAgentAPI) SetServiceBannerFunc(fn func() (codersdk.ServiceBannerConfig, error)) {
+	f.Lock()
+	defer f.Unlock()
+	f.getServiceBannerFunc = fn
+	f.logger.Info(context.Background(), "updated ServiceBannerFunc")
+}
+
+func (f *FakeAgentAPI) GetServiceBanner(context.Context, *agentproto.GetServiceBannerRequest) (*agentproto.ServiceBanner, error) {
+	f.Lock()
+	defer f.Unlock()
+	if f.getServiceBannerFunc == nil {
+		return &agentproto.ServiceBanner{}, nil
+	}
+	sb, err := f.getServiceBannerFunc()
+	if err != nil {
+		return nil, err
+	}
+	return agentsdk.ProtoFromServiceBanner(sb), nil
+}
+
+func (f *FakeAgentAPI) UpdateStats(ctx context.Context, req *agentproto.UpdateStatsRequest) (*agentproto.UpdateStatsResponse, error) {
+	f.logger.Debug(ctx, "update stats called", slog.F("req", req))
+	// empty request is sent to get the interval; but our tests don't want empty stats requests
+	if req.Stats != nil {
+		f.statsCh <- req.Stats
+	}
+	return &agentproto.UpdateStatsResponse{ReportInterval: durationpb.New(statsInterval)}, nil
+}
+
+func (f *FakeAgentAPI) GetLifecycleStates() []codersdk.WorkspaceAgentLifecycle {
+	f.Lock()
+	defer f.Unlock()
+	return slices.Clone(f.lifecycleStates)
+}
+
+func (f *FakeAgentAPI) UpdateLifecycle(_ context.Context, req *agentproto.UpdateLifecycleRequest) (*agentproto.Lifecycle, error) {
+	f.Lock()
+	defer f.Unlock()
+	s, err := agentsdk.LifecycleStateFromProto(req.GetLifecycle().GetState())
+	if assert.NoError(f.t, err) {
+		f.lifecycleStates = append(f.lifecycleStates, s)
+	}
+	return req.GetLifecycle(), nil
+}
+
+func (f *FakeAgentAPI) BatchUpdateAppHealths(ctx context.Context, req *agentproto.BatchUpdateAppHealthRequest) (*agentproto.BatchUpdateAppHealthResponse, error) {
+	f.logger.Debug(ctx, "batch update app health", slog.F("req", req))
+	f.appHealthCh <- req
+	return &agentproto.BatchUpdateAppHealthResponse{}, nil
+}
+
+func (f *FakeAgentAPI) AppHealthCh() <-chan *agentproto.BatchUpdateAppHealthRequest {
+	return f.appHealthCh
+}
+
+func (f *FakeAgentAPI) UpdateStartup(_ context.Context, req *agentproto.UpdateStartupRequest) (*agentproto.Startup, error) {
+	f.startupCh <- req.GetStartup()
+	return req.GetStartup(), nil
+}
+
+func (f *FakeAgentAPI) GetMetadata() map[string]agentsdk.Metadata {
+	f.Lock()
+	defer f.Unlock()
+	return maps.Clone(f.metadata)
+}
+
+func (f *FakeAgentAPI) BatchUpdateMetadata(ctx context.Context, req *agentproto.BatchUpdateMetadataRequest) (*agentproto.BatchUpdateMetadataResponse, error) {
+	f.Lock()
+	defer f.Unlock()
+	if f.metadata == nil {
+		f.metadata = make(map[string]agentsdk.Metadata)
+	}
+	for _, md := range req.Metadata {
+		smd := agentsdk.MetadataFromProto(md)
+		f.metadata[md.Key] = smd
+		f.logger.Debug(ctx, "post metadata", slog.F("key", md.Key), slog.F("md", md))
+	}
+	return &agentproto.BatchUpdateMetadataResponse{}, nil
+}
+
+func (f *FakeAgentAPI) SetLogsChannel(ch chan<- *agentproto.BatchCreateLogsRequest) {
+	f.Lock()
+	defer f.Unlock()
+	f.logsCh = ch
+}
+
+func (f *FakeAgentAPI) BatchCreateLogs(ctx context.Context, req *agentproto.BatchCreateLogsRequest) (*agentproto.BatchCreateLogsResponse, error) {
+	f.logger.Info(ctx, "batch create logs called", slog.F("req", req))
+	f.Lock()
+	ch := f.logsCh
+	f.Unlock()
+	if ch != nil {
+		select {
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		case ch <- req:
+			// ok
+		}
+	}
+	return &agentproto.BatchCreateLogsResponse{}, nil
+}
+
+func NewFakeAgentAPI(t testing.TB, logger slog.Logger, manifest *agentproto.Manifest, statsCh chan *agentproto.Stats) *FakeAgentAPI {
+	return &FakeAgentAPI{
+		t:           t,
+		logger:      logger.Named("FakeAgentAPI"),
+		manifest:    manifest,
+		statsCh:     statsCh,
+		startupCh:   make(chan *agentproto.Startup, 100),
+		appHealthCh: make(chan *agentproto.BatchUpdateAppHealthRequest, 100),
+	}
 }
@@ -35,7 +35,13 @@ func (a *agent) apiHandler() http.Handler {
 		ignorePorts:   cpy,
 		cacheDuration: cacheDuration,
 	}
+	promHandler := PrometheusMetricsHandler(a.prometheusRegistry, a.logger)
 	r.Get("/api/v0/listening-ports", lp.handler)
+	r.Get("/debug/logs", a.HandleHTTPDebugLogs)
+	r.Get("/debug/magicsock", a.HandleHTTPDebugMagicsock)
+	r.Get("/debug/magicsock/debug-logging/{state}", a.HandleHTTPMagicsockDebugLoggingState)
+	r.Get("/debug/manifest", a.HandleHTTPDebugManifest)
+	r.Get("/debug/prometheus", promHandler.ServeHTTP)

 	return r
 }
@@ -26,7 +26,12 @@ type WorkspaceAppHealthReporter func(ctx context.Context)

 // NewWorkspaceAppHealthReporter creates a WorkspaceAppHealthReporter that reports app health to coderd.
 func NewWorkspaceAppHealthReporter(logger slog.Logger, apps []codersdk.WorkspaceApp, postWorkspaceAgentAppHealth PostWorkspaceAgentAppHealth) WorkspaceAppHealthReporter {
+	logger = logger.Named("apphealth")
+
 	runHealthcheckLoop := func(ctx context.Context) error {
+		ctx, cancel := context.WithCancel(ctx)
+		defer cancel()
+
 		// no need to run this loop if no apps for this workspace.
 		if len(apps) == 0 {
 			return nil
@@ -87,6 +92,7 @@ func NewWorkspaceAppHealthReporter(logger slog.Logger, apps []codersdk.Workspace
 						return nil
 					}()
 					if err != nil {
+						nowUnhealthy := false
 						mu.Lock()
 						if failures[app.ID] < int(app.Healthcheck.Threshold) {
 							// increment the failure count and keep status the same.
@@ -96,14 +102,21 @@ func NewWorkspaceAppHealthReporter(logger slog.Logger, apps []codersdk.Workspace
 							// set to unhealthy if we hit the failure threshold.
 							// we stop incrementing at the threshold to prevent the failure value from increasing forever.
 							health[app.ID] = codersdk.WorkspaceAppHealthUnhealthy
+							nowUnhealthy = true
 						}
 						mu.Unlock()
+						logger.Debug(ctx, "error checking app health",
+							slog.F("id", app.ID.String()),
+							slog.F("slug", app.Slug),
+							slog.F("now_unhealthy", nowUnhealthy), slog.Error(err),
+						)
 					} else {
 						mu.Lock()
 						// we only need one successful health check to be considered healthy.
 						health[app.ID] = codersdk.WorkspaceAppHealthHealthy
 						failures[app.ID] = 0
 						mu.Unlock()
+						logger.Debug(ctx, "workspace app healthy", slog.F("id", app.ID.String()), slog.F("slug", app.Slug))
 					}

 					t.Reset(time.Duration(app.Healthcheck.Interval) * time.Second)
@@ -137,7 +150,9 @@ func NewWorkspaceAppHealthReporter(logger slog.Logger, apps []codersdk.Workspace
 					Healths: lastHealth,
 				})
 				if err != nil {
-					logger.Error(ctx, "failed to report workspace app stat", slog.Error(err))
+					logger.Error(ctx, "failed to report workspace app health", slog.Error(err))
+				} else {
+					logger.Debug(ctx, "sent workspace app health", slog.F("health", lastHealth))
 				}
 			}
 		}
@@ -4,16 +4,21 @@ import (
 	"context"
 	"net/http"
 	"net/http/httptest"
+	"strings"
 	"sync"
 	"sync/atomic"
 	"testing"
 	"time"

+	"github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"

 	"cdr.dev/slog"
 	"cdr.dev/slog/sloggers/slogtest"
 	"github.com/coder/coder/v2/agent"
+	"github.com/coder/coder/v2/agent/agenttest"
+	"github.com/coder/coder/v2/agent/proto"
 	"github.com/coder/coder/v2/coderd/httpapi"
 	"github.com/coder/coder/v2/codersdk"
 	"github.com/coder/coder/v2/codersdk/agentsdk"
@@ -40,12 +45,23 @@ func TestAppHealth_Healthy(t *testing.T) {
 			},
 			Health: codersdk.WorkspaceAppHealthInitializing,
 		},
+		{
+			Slug: "app3",
+			Healthcheck: codersdk.Healthcheck{
+				Interval:  2,
+				Threshold: 1,
+			},
+			Health: codersdk.WorkspaceAppHealthInitializing,
+		},
 	}
 	handlers := []http.Handler{
 		nil,
 		http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 			httpapi.Write(r.Context(), w, http.StatusOK, nil)
 		}),
+		http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			httpapi.Write(r.Context(), w, http.StatusOK, nil)
+		}),
 	}
 	getApps, closeFn := setupAppReporter(ctx, t, apps, handlers)
 	defer closeFn()
@@ -58,7 +74,7 @@ func TestAppHealth_Healthy(t *testing.T) {
 			return false
 		}

-		return apps[1].Health == codersdk.WorkspaceAppHealthHealthy
+		return apps[1].Health == codersdk.WorkspaceAppHealthHealthy && apps[2].Health == codersdk.WorkspaceAppHealthHealthy
 	}, testutil.WaitLong, testutil.IntervalSlow)
 }

@@ -163,6 +179,12 @@ func TestAppHealth_NotSpamming(t *testing.T) {

 func setupAppReporter(ctx context.Context, t *testing.T, apps []codersdk.WorkspaceApp, handlers []http.Handler) (agent.WorkspaceAgentApps, func()) {
 	closers := []func(){}
+	for i, app := range apps {
+		if app.ID == uuid.Nil {
+			app.ID = uuid.New()
+			apps[i] = app
+		}
+	}
 	for i, handler := range handlers {
 		if handler == nil {
 			continue
@@ -181,23 +203,43 @@ func setupAppReporter(ctx context.Context, t *testing.T, apps []codersdk.Workspa
 		var newApps []codersdk.WorkspaceApp
 		return append(newApps, apps...), nil
 	}
-	postWorkspaceAgentAppHealth := func(_ context.Context, req agentsdk.PostAppHealthsRequest) error {
-		mu.Lock()
-		for id, health := range req.Healths {
-			for i, app := range apps {
-				if app.ID != id {
-					continue
+
+	// We don't care about manifest or stats in this test since it's not using
+	// a full agent and these RPCs won't get called.
+	//
+	// We use a proper fake agent API so we can test the conversion code and the
+	// request code as well. Before we were bypassing these by using a custom
+	// post function.
+	fakeAAPI := agenttest.NewFakeAgentAPI(t, slogtest.Make(t, nil), nil, nil)
+
+	// Process events from the channel and update the health of the apps.
+	go func() {
+		appHealthCh := fakeAAPI.AppHealthCh()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case req := <-appHealthCh:
+				mu.Lock()
+				for _, update := range req.Updates {
+					updateID, err := uuid.FromBytes(update.Id)
+					assert.NoError(t, err)
+					updateHealth := codersdk.WorkspaceAppHealth(strings.ToLower(proto.AppHealth_name[int32(update.Health)]))
+
+					for i, app := range apps {
+						if app.ID != updateID {
+							continue
+						}
+						app.Health = updateHealth
+						apps[i] = app
+					}
 				}
-				app.Health = health
-				apps[i] = app
+				mu.Unlock()
 			}
 		}
-		mu.Unlock()
+	}()

-		return nil
-	}
-
-	go agent.NewWorkspaceAppHealthReporter(slogtest.Make(t, nil).Leveled(slog.LevelDebug), apps, postWorkspaceAgentAppHealth)(ctx)
+	go agent.NewWorkspaceAppHealthReporter(slogtest.Make(t, nil).Leveled(slog.LevelDebug), apps, agentsdk.AppHealthPoster(fakeAAPI))(ctx)

 	return workspaceAgentApps, func() {
 		for _, closeFn := range closers {
@@ -10,8 +10,7 @@ import (
 	"tailscale.com/util/clientmetric"

 	"cdr.dev/slog"
-
-	"github.com/coder/coder/v2/codersdk/agentsdk"
+	"github.com/coder/coder/v2/agent/proto"
 )

 type agentMetrics struct {
@@ -53,8 +52,8 @@ func newAgentMetrics(registerer prometheus.Registerer) *agentMetrics {
 	}
 }

-func (a *agent) collectMetrics(ctx context.Context) []agentsdk.AgentMetric {
-	var collected []agentsdk.AgentMetric
+func (a *agent) collectMetrics(ctx context.Context) []*proto.Stats_Metric {
+	var collected []*proto.Stats_Metric

 	// Tailscale internal metrics
 	metrics := clientmetric.Metrics()
@@ -63,7 +62,7 @@ func (a *agent) collectMetrics(ctx context.Context) []agentsdk.AgentMetric {
 			continue
 		}

-		collected = append(collected, agentsdk.AgentMetric{
+		collected = append(collected, &proto.Stats_Metric{
 			Name:  m.Name(),
 			Type:  asMetricType(m.Type()),
 			Value: float64(m.Value()),
@@ -81,16 +80,16 @@ func (a *agent) collectMetrics(ctx context.Context) []agentsdk.AgentMetric {
 			labels := toAgentMetricLabels(metric.Label)

 			if metric.Counter != nil {
-				collected = append(collected, agentsdk.AgentMetric{
+				collected = append(collected, &proto.Stats_Metric{
 					Name:   metricFamily.GetName(),
-					Type:   agentsdk.AgentMetricTypeCounter,
+					Type:   proto.Stats_Metric_COUNTER,
 					Value:  metric.Counter.GetValue(),
 					Labels: labels,
 				})
 			} else if metric.Gauge != nil {
-				collected = append(collected, agentsdk.AgentMetric{
+				collected = append(collected, &proto.Stats_Metric{
 					Name:   metricFamily.GetName(),
-					Type:   agentsdk.AgentMetricTypeGauge,
+					Type:   proto.Stats_Metric_GAUGE,
 					Value:  metric.Gauge.GetValue(),
 					Labels: labels,
 				})
@@ -102,14 +101,14 @@ func (a *agent) collectMetrics(ctx context.Context) []agentsdk.AgentMetric {
 	return collected
 }

-func toAgentMetricLabels(metricLabels []*prompb.LabelPair) []agentsdk.AgentMetricLabel {
+func toAgentMetricLabels(metricLabels []*prompb.LabelPair) []*proto.Stats_Metric_Label {
 	if len(metricLabels) == 0 {
 		return nil
 	}

-	labels := make([]agentsdk.AgentMetricLabel, 0, len(metricLabels))
+	labels := make([]*proto.Stats_Metric_Label, 0, len(metricLabels))
 	for _, metricLabel := range metricLabels {
-		labels = append(labels, agentsdk.AgentMetricLabel{
+		labels = append(labels, &proto.Stats_Metric_Label{
 			Name:  metricLabel.GetName(),
 			Value: metricLabel.GetValue(),
 		})
@@ -130,12 +129,12 @@ func isIgnoredMetric(metricName string) bool {
 	return false
 }

-func asMetricType(typ clientmetric.Type) agentsdk.AgentMetricType {
+func asMetricType(typ clientmetric.Type) proto.Stats_Metric_Type {
 	switch typ {
 	case clientmetric.TypeGauge:
-		return agentsdk.AgentMetricTypeGauge
+		return proto.Stats_Metric_GAUGE
 	case clientmetric.TypeCounter:
-		return agentsdk.AgentMetricTypeCounter
+		return proto.Stats_Metric_COUNTER
 	default:
 		panic(fmt.Sprintf("unknown metric type: %d", typ))
 	}
@@ -9,6 +9,7 @@ import (
 	"golang.org/x/xerrors"

 	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/coder/v2/codersdk/workspacesdk"
 )

 func (lp *listeningPortsHandler) getListeningPorts() ([]codersdk.WorkspaceAgentListeningPort, error) {
@@ -32,7 +33,7 @@ func (lp *listeningPortsHandler) getListeningPorts() ([]codersdk.WorkspaceAgentL
 	seen := make(map[uint16]struct{}, len(tabs))
 	ports := []codersdk.WorkspaceAgentListeningPort{}
 	for _, tab := range tabs {
-		if tab.LocalAddr == nil || tab.LocalAddr.Port < codersdk.WorkspaceAgentMinimumListeningPort {
+		if tab.LocalAddr == nil || tab.LocalAddr.Port < workspacesdk.AgentMinimumListeningPort {
 			continue
 		}

@@ -8,7 +8,7 @@ import "google/protobuf/timestamp.proto";
 import "google/protobuf/duration.proto";

 message WorkspaceApp {
-	bytes uuid = 1;
+	bytes id = 1;
 	string url = 2;
 	bool external = 3;
 	string slug = 4;
@@ -26,12 +26,12 @@ message WorkspaceApp {
 	}
 	SharingLevel sharing_level = 10;

-	message HealthCheck {
+	message Healthcheck {
 		string url = 1;
-		int32 interval = 2;
+		google.protobuf.Duration interval = 2;
 		int32 threshold = 3;
 	}
-	HealthCheck healthcheck = 11;
+	Healthcheck healthcheck = 11;

 	enum Health {
 		HEALTH_UNSPECIFIED = 0;
@@ -43,11 +43,54 @@ message WorkspaceApp {
 	Health health = 12;
 }

+message WorkspaceAgentScript {
+	bytes log_source_id = 1;
+	string log_path = 2;
+	string script = 3;
+	string cron = 4;
+	bool run_on_start = 5;
+	bool run_on_stop = 6;
+	bool start_blocks_login = 7;
+	google.protobuf.Duration timeout = 8;
+}
+
+message WorkspaceAgentMetadata {
+	message Result {
+		google.protobuf.Timestamp collected_at = 1;
+		int64 age = 2;
+		string value = 3;
+		string error = 4;
+	}
+	Result result = 1;
+
+	message Description {
+		string display_name = 1;
+		string key = 2;
+		string script = 3;
+		google.protobuf.Duration interval = 4;
+		google.protobuf.Duration timeout = 5;
+	}
+	Description description = 2;
+}
+
 message Manifest {
-	uint32 git_auth_configs = 1;
-	string vs_code_port_proxy_uri = 2;
-	repeated WorkspaceApp apps = 3;
-	coder.tailnet.v2.DERPMap derp_map = 4;
+	bytes agent_id = 1;
+	string agent_name = 15;
+	string owner_username = 13;
+	bytes workspace_id = 14;
+	string workspace_name = 16;
+	uint32 git_auth_configs = 2;
+	map<string, string> environment_variables = 3;
+	string directory = 4;
+	string vs_code_port_proxy_uri = 5;
+	string motd_path = 6;
+	bool disable_direct_connections = 7;
+	bool derp_force_websockets = 8;
+
+	coder.tailnet.v2.DERPMap derp_map = 9;
+	repeated WorkspaceAgentScript scripts = 10;
+	repeated WorkspaceApp apps = 11;
+	repeated WorkspaceAgentMetadata.Description metadata = 12;
 }

 message GetManifestRequest {}
@@ -100,8 +143,14 @@ message Stats {
 		Type type = 2;

 		double value = 3;
-		map<string, string> labels = 4;
+
+		message Label {
+			string name = 1;
+			string value = 2;
+		}
+		repeated Label labels = 4;
 	}
+	repeated Metric metrics = 12;
 }

 message UpdateStatsRequest{
@@ -109,14 +158,14 @@ message UpdateStatsRequest{
 }

 message UpdateStatsResponse {
-	google.protobuf.Duration report_interval_nanoseconds = 1;
+	google.protobuf.Duration report_interval = 1;
 }

 message Lifecycle {
 	enum State {
 		STATE_UNSPECIFIED = 0;
 		CREATED = 1;
-		STARTED = 2;
+		STARTING = 2;
 		START_TIMEOUT = 3;
 		START_ERROR = 4;
 		READY = 5;
@@ -126,6 +175,7 @@ message Lifecycle {
 		OFF = 9;
 	}
 	State state = 1;
+	google.protobuf.Timestamp changed_at = 2;
 }

 message UpdateLifecycleRequest {
@@ -142,7 +192,7 @@ enum AppHealth {

 message BatchUpdateAppHealthRequest {
 	message HealthUpdate {
-		bytes uuid = 1;
+		bytes id = 1;
 		AppHealth health = 2;
 	}
 	repeated HealthUpdate updates = 1;
@@ -153,7 +203,13 @@ message BatchUpdateAppHealthResponse {}
 message Startup {
 	string version = 1;
 	string expanded_directory = 2;
-	repeated string subsystems = 3;
+	enum Subsystem {
+		SUBSYSTEM_UNSPECIFIED = 0;
+		ENVBOX = 1;
+		ENVBUILDER = 2;
+		EXECTRACE = 3;
+	}
+	repeated Subsystem subsystems = 3;
 }

 message UpdateStartupRequest{
@@ -162,10 +218,7 @@ message UpdateStartupRequest{

 message Metadata {
 	string key = 1;
-	google.protobuf.Timestamp collected_at = 2;
-	int64 age = 3;
-	string value = 4;
-	string error = 5;
+	WorkspaceAgentMetadata.Result result = 2;
 }

 message BatchUpdateMetadataRequest {
@@ -190,11 +243,13 @@ message Log {
 }

 message BatchCreateLogsRequest {
-	bytes source_id = 1;
+	bytes log_source_id = 1;
 	repeated Log logs = 2;
 }

-message BatchCreateLogsResponse {}
+message BatchCreateLogsResponse {
+	bool log_limit_exceeded = 1;
+}

 service Agent {
 	rpc GetManifest(GetManifestRequest) returns (Manifest);
@@ -205,7 +260,4 @@ service Agent {
 	rpc UpdateStartup(UpdateStartupRequest) returns (Startup);
 	rpc BatchUpdateMetadata(BatchUpdateMetadataRequest) returns (BatchUpdateMetadataResponse);
 	rpc BatchCreateLogs(BatchCreateLogsRequest) returns (BatchCreateLogsResponse);
-
-	rpc StreamDERPMaps(tailnet.v2.StreamDERPMapsRequest) returns (stream tailnet.v2.DERPMap);
-	rpc CoordinateTailnet(stream tailnet.v2.CoordinateRequest) returns (stream tailnet.v2.CoordinateResponse);
 }
@@ -7,7 +7,6 @@ package proto
 import (
 	context "context"
 	errors "errors"
-	proto1 "github.com/coder/coder/v2/tailnet/proto"
 	protojson "google.golang.org/protobuf/encoding/protojson"
 	proto "google.golang.org/protobuf/proto"
 	drpc "storj.io/drpc"
@@ -47,8 +46,6 @@ type DRPCAgentClient interface {
 	UpdateStartup(ctx context.Context, in *UpdateStartupRequest) (*Startup, error)
 	BatchUpdateMetadata(ctx context.Context, in *BatchUpdateMetadataRequest) (*BatchUpdateMetadataResponse, error)
 	BatchCreateLogs(ctx context.Context, in *BatchCreateLogsRequest) (*BatchCreateLogsResponse, error)
-	StreamDERPMaps(ctx context.Context, in *proto1.StreamDERPMapsRequest) (DRPCAgent_StreamDERPMapsClient, error)
-	CoordinateTailnet(ctx context.Context) (DRPCAgent_CoordinateTailnetClient, error)
 }

 type drpcAgentClient struct {
@@ -133,85 +130,6 @@ func (c *drpcAgentClient) BatchCreateLogs(ctx context.Context, in *BatchCreateLo
 	return out, nil
 }

-func (c *drpcAgentClient) StreamDERPMaps(ctx context.Context, in *proto1.StreamDERPMapsRequest) (DRPCAgent_StreamDERPMapsClient, error) {
-	stream, err := c.cc.NewStream(ctx, "/coder.agent.v2.Agent/StreamDERPMaps", drpcEncoding_File_agent_proto_agent_proto{})
-	if err != nil {
-		return nil, err
-	}
-	x := &drpcAgent_StreamDERPMapsClient{stream}
-	if err := x.MsgSend(in, drpcEncoding_File_agent_proto_agent_proto{}); err != nil {
-		return nil, err
-	}
-	if err := x.CloseSend(); err != nil {
-		return nil, err
-	}
-	return x, nil
-}
-
-type DRPCAgent_StreamDERPMapsClient interface {
-	drpc.Stream
-	Recv() (*proto1.DERPMap, error)
-}
-
-type drpcAgent_StreamDERPMapsClient struct {
-	drpc.Stream
-}
-
-func (x *drpcAgent_StreamDERPMapsClient) GetStream() drpc.Stream {
-	return x.Stream
-}
-
-func (x *drpcAgent_StreamDERPMapsClient) Recv() (*proto1.DERPMap, error) {
-	m := new(proto1.DERPMap)
-	if err := x.MsgRecv(m, drpcEncoding_File_agent_proto_agent_proto{}); err != nil {
-		return nil, err
-	}
-	return m, nil
-}
-
-func (x *drpcAgent_StreamDERPMapsClient) RecvMsg(m *proto1.DERPMap) error {
-	return x.MsgRecv(m, drpcEncoding_File_agent_proto_agent_proto{})
-}
-
-func (c *drpcAgentClient) CoordinateTailnet(ctx context.Context) (DRPCAgent_CoordinateTailnetClient, error) {
-	stream, err := c.cc.NewStream(ctx, "/coder.agent.v2.Agent/CoordinateTailnet", drpcEncoding_File_agent_proto_agent_proto{})
-	if err != nil {
-		return nil, err
-	}
-	x := &drpcAgent_CoordinateTailnetClient{stream}
-	return x, nil
-}
-
-type DRPCAgent_CoordinateTailnetClient interface {
-	drpc.Stream
-	Send(*proto1.CoordinateRequest) error
-	Recv() (*proto1.CoordinateResponse, error)
-}
-
-type drpcAgent_CoordinateTailnetClient struct {
-	drpc.Stream
-}
-
-func (x *drpcAgent_CoordinateTailnetClient) GetStream() drpc.Stream {
-	return x.Stream
-}
-
-func (x *drpcAgent_CoordinateTailnetClient) Send(m *proto1.CoordinateRequest) error {
-	return x.MsgSend(m, drpcEncoding_File_agent_proto_agent_proto{})
-}
-
-func (x *drpcAgent_CoordinateTailnetClient) Recv() (*proto1.CoordinateResponse, error) {
-	m := new(proto1.CoordinateResponse)
-	if err := x.MsgRecv(m, drpcEncoding_File_agent_proto_agent_proto{}); err != nil {
-		return nil, err
-	}
-	return m, nil
-}
-
-func (x *drpcAgent_CoordinateTailnetClient) RecvMsg(m *proto1.CoordinateResponse) error {
-	return x.MsgRecv(m, drpcEncoding_File_agent_proto_agent_proto{})
-}
-
 type DRPCAgentServer interface {
 	GetManifest(context.Context, *GetManifestRequest) (*Manifest, error)
 	GetServiceBanner(context.Context, *GetServiceBannerRequest) (*ServiceBanner, error)
@@ -221,8 +139,6 @@ type DRPCAgentServer interface {
 	UpdateStartup(context.Context, *UpdateStartupRequest) (*Startup, error)
 	BatchUpdateMetadata(context.Context, *BatchUpdateMetadataRequest) (*BatchUpdateMetadataResponse, error)
 	BatchCreateLogs(context.Context, *BatchCreateLogsRequest) (*BatchCreateLogsResponse, error)
-	StreamDERPMaps(*proto1.StreamDERPMapsRequest, DRPCAgent_StreamDERPMapsStream) error
-	CoordinateTailnet(DRPCAgent_CoordinateTailnetStream) error
 }

 type DRPCAgentUnimplementedServer struct{}
@@ -259,17 +175,9 @@ func (s *DRPCAgentUnimplementedServer) BatchCreateLogs(context.Context, *BatchCr
 	return nil, drpcerr.WithCode(errors.New("Unimplemented"), drpcerr.Unimplemented)
 }

-func (s *DRPCAgentUnimplementedServer) StreamDERPMaps(*proto1.StreamDERPMapsRequest, DRPCAgent_StreamDERPMapsStream) error {
-	return drpcerr.WithCode(errors.New("Unimplemented"), drpcerr.Unimplemented)
-}
-
-func (s *DRPCAgentUnimplementedServer) CoordinateTailnet(DRPCAgent_CoordinateTailnetStream) error {
-	return drpcerr.WithCode(errors.New("Unimplemented"), drpcerr.Unimplemented)
-}
-
 type DRPCAgentDescription struct{}

-func (DRPCAgentDescription) NumMethods() int { return 10 }
+func (DRPCAgentDescription) NumMethods() int { return 8 }

 func (DRPCAgentDescription) Method(n int) (string, drpc.Encoding, drpc.Receiver, interface{}, bool) {
 	switch n {
@@ -345,23 +253,6 @@ func (DRPCAgentDescription) Method(n int) (string, drpc.Encoding, drpc.Receiver,
 						in1.(*BatchCreateLogsRequest),
 					)
 			}, DRPCAgentServer.BatchCreateLogs, true
-	case 8:
-		return "/coder.agent.v2.Agent/StreamDERPMaps", drpcEncoding_File_agent_proto_agent_proto{},
-			func(srv interface{}, ctx context.Context, in1, in2 interface{}) (drpc.Message, error) {
-				return nil, srv.(DRPCAgentServer).
-					StreamDERPMaps(
-						in1.(*proto1.StreamDERPMapsRequest),
-						&drpcAgent_StreamDERPMapsStream{in2.(drpc.Stream)},
-					)
-			}, DRPCAgentServer.StreamDERPMaps, true
-	case 9:
-		return "/coder.agent.v2.Agent/CoordinateTailnet", drpcEncoding_File_agent_proto_agent_proto{},
-			func(srv interface{}, ctx context.Context, in1, in2 interface{}) (drpc.Message, error) {
-				return nil, srv.(DRPCAgentServer).
-					CoordinateTailnet(
-						&drpcAgent_CoordinateTailnetStream{in1.(drpc.Stream)},
-					)
-			}, DRPCAgentServer.CoordinateTailnet, true
 	default:
 		return "", nil, nil, nil, false
 	}
@@ -498,42 +389,3 @@ func (x *drpcAgent_BatchCreateLogsStream) SendAndClose(m *BatchCreateLogsRespons
 	}
 	return x.CloseSend()
 }
-
-type DRPCAgent_StreamDERPMapsStream interface {
-	drpc.Stream
-	Send(*proto1.DERPMap) error
-}
-
-type drpcAgent_StreamDERPMapsStream struct {
-	drpc.Stream
-}
-
-func (x *drpcAgent_StreamDERPMapsStream) Send(m *proto1.DERPMap) error {
-	return x.MsgSend(m, drpcEncoding_File_agent_proto_agent_proto{})
-}
-
-type DRPCAgent_CoordinateTailnetStream interface {
-	drpc.Stream
-	Send(*proto1.CoordinateResponse) error
-	Recv() (*proto1.CoordinateRequest, error)
-}
-
-type drpcAgent_CoordinateTailnetStream struct {
-	drpc.Stream
-}
-
-func (x *drpcAgent_CoordinateTailnetStream) Send(m *proto1.CoordinateResponse) error {
-	return x.MsgSend(m, drpcEncoding_File_agent_proto_agent_proto{})
-}
-
-func (x *drpcAgent_CoordinateTailnetStream) Recv() (*proto1.CoordinateRequest, error) {
-	m := new(proto1.CoordinateRequest)
-	if err := x.MsgRecv(m, drpcEncoding_File_agent_proto_agent_proto{}); err != nil {
-		return nil, err
-	}
-	return m, nil
-}
-
-func (x *drpcAgent_CoordinateTailnetStream) RecvMsg(m *proto1.CoordinateRequest) error {
-	return x.MsgRecv(m, drpcEncoding_File_agent_proto_agent_proto{})
-}
@@ -0,0 +1,26 @@
+package proto
+
+func LabelsEqual(a, b []*Stats_Metric_Label) bool {
+	am := make(map[string]string, len(a))
+	for _, lbl := range a {
+		v := lbl.GetValue()
+		if v == "" {
+			// Prometheus considers empty labels as equivalent to being absent
+			continue
+		}
+		am[lbl.GetName()] = lbl.GetValue()
+	}
+	lenB := 0
+	for _, lbl := range b {
+		v := lbl.GetValue()
+		if v == "" {
+			// Prometheus considers empty labels as equivalent to being absent
+			continue
+		}
+		lenB++
+		if am[lbl.GetName()] != v {
+			return false
+		}
+	}
+	return len(am) == lenB
+}
@@ -0,0 +1,77 @@
+package proto_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/v2/agent/proto"
+)
+
+func TestLabelsEqual(t *testing.T) {
+	t.Parallel()
+	for _, tc := range []struct {
+		name string
+		a    []*proto.Stats_Metric_Label
+		b    []*proto.Stats_Metric_Label
+		eq   bool
+	}{
+		{
+			name: "mainlineEq",
+			a: []*proto.Stats_Metric_Label{
+				{Name: "credulity", Value: "sus"},
+				{Name: "color", Value: "aquamarine"},
+			},
+			b: []*proto.Stats_Metric_Label{
+				{Name: "credulity", Value: "sus"},
+				{Name: "color", Value: "aquamarine"},
+			},
+			eq: true,
+		},
+		{
+			name: "emptyValue",
+			a: []*proto.Stats_Metric_Label{
+				{Name: "credulity", Value: "sus"},
+				{Name: "color", Value: "aquamarine"},
+				{Name: "singularity", Value: ""},
+			},
+			b: []*proto.Stats_Metric_Label{
+				{Name: "credulity", Value: "sus"},
+				{Name: "color", Value: "aquamarine"},
+			},
+			eq: true,
+		},
+		{
+			name: "extra",
+			a: []*proto.Stats_Metric_Label{
+				{Name: "credulity", Value: "sus"},
+				{Name: "color", Value: "aquamarine"},
+				{Name: "opacity", Value: "seyshells"},
+			},
+			b: []*proto.Stats_Metric_Label{
+				{Name: "credulity", Value: "sus"},
+				{Name: "color", Value: "aquamarine"},
+			},
+			eq: false,
+		},
+		{
+			name: "different",
+			a: []*proto.Stats_Metric_Label{
+				{Name: "credulity", Value: "sus"},
+				{Name: "color", Value: "aquamarine"},
+			},
+			b: []*proto.Stats_Metric_Label{
+				{Name: "credulity", Value: "legit"},
+				{Name: "color", Value: "aquamarine"},
+			},
+			eq: false,
+		},
+	} {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			require.Equal(t, tc.eq, proto.LabelsEqual(tc.a, tc.b))
+			require.Equal(t, tc.eq, proto.LabelsEqual(tc.b, tc.a))
+		})
+	}
+}
@@ -0,0 +1,10 @@
+package proto
+
+import (
+	"github.com/coder/coder/v2/tailnet/proto"
+)
+
+// CurrentVersion is the current version of the agent API.  It is tied to the
+// tailnet API version to avoid confusion, since agents connect to the tailnet
+// API over the same websocket.
+var CurrentVersion = proto.CurrentVersion
@@ -14,8 +14,7 @@ import (
 	"golang.org/x/xerrors"

 	"cdr.dev/slog"
-
-	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/coder/v2/codersdk/workspacesdk"
 	"github.com/coder/coder/v2/pty"
 )

@@ -197,7 +196,7 @@ func (s *ptyState) waitForStateOrContext(ctx context.Context, state State) (Stat
 func readConnLoop(ctx context.Context, conn net.Conn, ptty pty.PTYCmd, metrics *prometheus.CounterVec, logger slog.Logger) {
 	decoder := json.NewDecoder(conn)
 	for {
-		var req codersdk.ReconnectingPTYRequest
+		var req workspacesdk.ReconnectingPTYRequest
 		err := decoder.Decode(&req)
 		if xerrors.Is(err, io.EOF) {
 			return
@@ -81,6 +81,13 @@ func newScreen(ctx context.Context, cmd *pty.Cmd, options *Options, logger slog.
 	rpty.id = hex.EncodeToString(buf)

 	settings := []string{
+		// Disable the startup message that appears for five seconds.
+		"startup_message off",
+		// Some message are hard-coded, the best we can do is set msgwait to 0
+		// which seems to hide them. This can happen for example if screen shows
+		// the version message when starting up.
+		"msgminwait 0",
+		"msgwait 0",
 		// Tell screen not to handle motion for xterm* terminals which allows
 		// scrolling the terminal via the mouse wheel or scroll bar (by default
 		// screen uses it to cycle through the command history).  There does not
@@ -0,0 +1,126 @@
+package agent
+
+import (
+	"context"
+	"sync"
+	"time"
+
+	"golang.org/x/xerrors"
+	"tailscale.com/types/netlogtype"
+
+	"cdr.dev/slog"
+	"github.com/coder/coder/v2/agent/proto"
+)
+
+const maxConns = 2048
+
+type networkStatsSource interface {
+	SetConnStatsCallback(maxPeriod time.Duration, maxConns int, dump func(start, end time.Time, virtual, physical map[netlogtype.Connection]netlogtype.Counts))
+}
+
+type statsCollector interface {
+	Collect(ctx context.Context, networkStats map[netlogtype.Connection]netlogtype.Counts) *proto.Stats
+}
+
+type statsDest interface {
+	UpdateStats(ctx context.Context, req *proto.UpdateStatsRequest) (*proto.UpdateStatsResponse, error)
+}
+
+// statsReporter is a subcomponent of the agent that handles registering the stats callback on the
+// networkStatsSource (tailnet.Conn in prod), handling the callback, calling back to the
+// statsCollector (agent in prod) to collect additional stats, then sending the update to the
+// statsDest (agent API in prod)
+type statsReporter struct {
+	*sync.Cond
+	networkStats *map[netlogtype.Connection]netlogtype.Counts
+	unreported   bool
+	lastInterval time.Duration
+
+	source    networkStatsSource
+	collector statsCollector
+	logger    slog.Logger
+}
+
+func newStatsReporter(logger slog.Logger, source networkStatsSource, collector statsCollector) *statsReporter {
+	return &statsReporter{
+		Cond:      sync.NewCond(&sync.Mutex{}),
+		logger:    logger,
+		source:    source,
+		collector: collector,
+	}
+}
+
+func (s *statsReporter) callback(_, _ time.Time, virtual, _ map[netlogtype.Connection]netlogtype.Counts) {
+	s.L.Lock()
+	defer s.L.Unlock()
+	s.logger.Debug(context.Background(), "got stats callback")
+	s.networkStats = &virtual
+	s.unreported = true
+	s.Broadcast()
+}
+
+// reportLoop programs the source (tailnet.Conn) to send it stats via the
+// callback, then reports them to the dest.
+//
+// It's intended to be called within the larger retry loop that establishes a
+// connection to the agent API, then passes that connection to go routines like
+// this that use it.  There is no retry and we fail on the first error since
+// this will be inside a larger retry loop.
+func (s *statsReporter) reportLoop(ctx context.Context, dest statsDest) error {
+	// send an initial, blank report to get the interval
+	resp, err := dest.UpdateStats(ctx, &proto.UpdateStatsRequest{})
+	if err != nil {
+		return xerrors.Errorf("initial update: %w", err)
+	}
+	s.lastInterval = resp.ReportInterval.AsDuration()
+	s.source.SetConnStatsCallback(s.lastInterval, maxConns, s.callback)
+
+	// use a separate goroutine to monitor the context so that we notice immediately, rather than
+	// waiting for the next callback (which might never come if we are closing!)
+	ctxDone := false
+	go func() {
+		<-ctx.Done()
+		s.L.Lock()
+		defer s.L.Unlock()
+		ctxDone = true
+		s.Broadcast()
+	}()
+	defer s.logger.Debug(ctx, "reportLoop exiting")
+
+	s.L.Lock()
+	defer s.L.Unlock()
+	for {
+		for !s.unreported && !ctxDone {
+			s.Wait()
+		}
+		if ctxDone {
+			return nil
+		}
+		networkStats := *s.networkStats
+		s.unreported = false
+		if err = s.reportLocked(ctx, dest, networkStats); err != nil {
+			return xerrors.Errorf("report stats: %w", err)
+		}
+	}
+}
+
+func (s *statsReporter) reportLocked(
+	ctx context.Context, dest statsDest, networkStats map[netlogtype.Connection]netlogtype.Counts,
+) error {
+	// here we want to do our collecting/reporting while it is unlocked, but then relock
+	// when we return to reportLoop.
+	s.L.Unlock()
+	defer s.L.Lock()
+	stats := s.collector.Collect(ctx, networkStats)
+	resp, err := dest.UpdateStats(ctx, &proto.UpdateStatsRequest{Stats: stats})
+	if err != nil {
+		return err
+	}
+	interval := resp.GetReportInterval().AsDuration()
+	if interval != s.lastInterval {
+		s.logger.Info(ctx, "new stats report interval", slog.F("interval", interval))
+		s.lastInterval = interval
+		s.source.SetConnStatsCallback(s.lastInterval, maxConns, s.callback)
+	}
+	return nil
+}
@@ -0,0 +1,271 @@
+package agent
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"net/netip"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"google.golang.org/protobuf/types/known/durationpb"
+	"tailscale.com/types/ipproto"
+
+	"tailscale.com/types/netlogtype"
+
+	"cdr.dev/slog"
+	"cdr.dev/slog/sloggers/slogjson"
+	"cdr.dev/slog/sloggers/slogtest"
+	"github.com/coder/coder/v2/agent/proto"
+	"github.com/coder/coder/v2/testutil"
+)
+
+func TestStatsReporter(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+	logger := slogtest.Make(t, nil).Leveled(slog.LevelDebug)
+	fSource := newFakeNetworkStatsSource(ctx, t)
+	fCollector := newFakeCollector(t)
+	fDest := newFakeStatsDest()
+	uut := newStatsReporter(logger, fSource, fCollector)
+
+	loopErr := make(chan error, 1)
+	loopCtx, loopCancel := context.WithCancel(ctx)
+	go func() {
+		err := uut.reportLoop(loopCtx, fDest)
+		loopErr <- err
+	}()
+
+	// initial request to get duration
+	req := testutil.RequireRecvCtx(ctx, t, fDest.reqs)
+	require.NotNil(t, req)
+	require.Nil(t, req.Stats)
+	interval := time.Second * 34
+	testutil.RequireSendCtx(ctx, t, fDest.resps, &proto.UpdateStatsResponse{ReportInterval: durationpb.New(interval)})
+
+	// call to source to set the callback and interval
+	gotInterval := testutil.RequireRecvCtx(ctx, t, fSource.period)
+	require.Equal(t, interval, gotInterval)
+
+	// callback returning netstats
+	netStats := map[netlogtype.Connection]netlogtype.Counts{
+		{
+			Proto: ipproto.TCP,
+			Src:   netip.MustParseAddrPort("192.168.1.33:4887"),
+			Dst:   netip.MustParseAddrPort("192.168.2.99:9999"),
+		}: {
+			TxPackets: 22,
+			TxBytes:   23,
+			RxPackets: 24,
+			RxBytes:   25,
+		},
+	}
+	fSource.callback(time.Now(), time.Now(), netStats, nil)
+
+	// collector called to complete the stats
+	gotNetStats := testutil.RequireRecvCtx(ctx, t, fCollector.calls)
+	require.Equal(t, netStats, gotNetStats)
+
+	// while we are collecting the stats, send in two new netStats to simulate
+	// what happens if we don't keep up.  Only the latest should be kept.
+	netStats0 := map[netlogtype.Connection]netlogtype.Counts{
+		{
+			Proto: ipproto.TCP,
+			Src:   netip.MustParseAddrPort("192.168.1.33:4887"),
+			Dst:   netip.MustParseAddrPort("192.168.2.99:9999"),
+		}: {
+			TxPackets: 10,
+			TxBytes:   10,
+			RxPackets: 10,
+			RxBytes:   10,
+		},
+	}
+	fSource.callback(time.Now(), time.Now(), netStats0, nil)
+	netStats1 := map[netlogtype.Connection]netlogtype.Counts{
+		{
+			Proto: ipproto.TCP,
+			Src:   netip.MustParseAddrPort("192.168.1.33:4887"),
+			Dst:   netip.MustParseAddrPort("192.168.2.99:9999"),
+		}: {
+			TxPackets: 11,
+			TxBytes:   11,
+			RxPackets: 11,
+			RxBytes:   11,
+		},
+	}
+	fSource.callback(time.Now(), time.Now(), netStats1, nil)
+
+	// complete first collection
+	stats := &proto.Stats{SessionCountJetbrains: 55}
+	testutil.RequireSendCtx(ctx, t, fCollector.stats, stats)
+
+	// destination called to report the first stats
+	update := testutil.RequireRecvCtx(ctx, t, fDest.reqs)
+	require.NotNil(t, update)
+	require.Equal(t, stats, update.Stats)
+	testutil.RequireSendCtx(ctx, t, fDest.resps, &proto.UpdateStatsResponse{ReportInterval: durationpb.New(interval)})
+
+	// second update -- only netStats1 is reported
+	gotNetStats = testutil.RequireRecvCtx(ctx, t, fCollector.calls)
+	require.Equal(t, netStats1, gotNetStats)
+	stats = &proto.Stats{SessionCountJetbrains: 66}
+	testutil.RequireSendCtx(ctx, t, fCollector.stats, stats)
+	update = testutil.RequireRecvCtx(ctx, t, fDest.reqs)
+	require.NotNil(t, update)
+	require.Equal(t, stats, update.Stats)
+	interval2 := 27 * time.Second
+	testutil.RequireSendCtx(ctx, t, fDest.resps, &proto.UpdateStatsResponse{ReportInterval: durationpb.New(interval2)})
+
+	// set the new interval
+	gotInterval = testutil.RequireRecvCtx(ctx, t, fSource.period)
+	require.Equal(t, interval2, gotInterval)
+
+	loopCancel()
+	err := testutil.RequireRecvCtx(ctx, t, loopErr)
+	require.NoError(t, err)
+}
+
+type fakeNetworkStatsSource struct {
+	sync.Mutex
+	ctx      context.Context
+	t        testing.TB
+	callback func(start, end time.Time, virtual, physical map[netlogtype.Connection]netlogtype.Counts)
+	period   chan time.Duration
+}
+
+func (f *fakeNetworkStatsSource) SetConnStatsCallback(maxPeriod time.Duration, _ int, dump func(start time.Time, end time.Time, virtual map[netlogtype.Connection]netlogtype.Counts, physical map[netlogtype.Connection]netlogtype.Counts)) {
+	f.Lock()
+	defer f.Unlock()
+	f.callback = dump
+	select {
+	case <-f.ctx.Done():
+		f.t.Error("timeout")
+	case f.period <- maxPeriod:
+		// OK
+	}
+}
+
+func newFakeNetworkStatsSource(ctx context.Context, t testing.TB) *fakeNetworkStatsSource {
+	f := &fakeNetworkStatsSource{
+		ctx:    ctx,
+		t:      t,
+		period: make(chan time.Duration),
+	}
+	return f
+}
+
+type fakeCollector struct {
+	t     testing.TB
+	calls chan map[netlogtype.Connection]netlogtype.Counts
+	stats chan *proto.Stats
+}
+
+func (f *fakeCollector) Collect(ctx context.Context, networkStats map[netlogtype.Connection]netlogtype.Counts) *proto.Stats {
+	select {
+	case <-ctx.Done():
+		f.t.Error("timeout on collect")
+		return nil
+	case f.calls <- networkStats:
+		// ok
+	}
+	select {
+	case <-ctx.Done():
+		f.t.Error("timeout on collect")
+		return nil
+	case s := <-f.stats:
+		return s
+	}
+}
+
+func newFakeCollector(t testing.TB) *fakeCollector {
+	return &fakeCollector{
+		t:     t,
+		calls: make(chan map[netlogtype.Connection]netlogtype.Counts),
+		stats: make(chan *proto.Stats),
+	}
+}
+
+type fakeStatsDest struct {
+	reqs  chan *proto.UpdateStatsRequest
+	resps chan *proto.UpdateStatsResponse
+}
+
+func (f *fakeStatsDest) UpdateStats(ctx context.Context, req *proto.UpdateStatsRequest) (*proto.UpdateStatsResponse, error) {
+	select {
+	case <-ctx.Done():
+		return nil, ctx.Err()
+	case f.reqs <- req:
+		// OK
+	}
+	select {
+	case <-ctx.Done():
+		return nil, ctx.Err()
+	case resp := <-f.resps:
+		return resp, nil
+	}
+}
+
+func newFakeStatsDest() *fakeStatsDest {
+	return &fakeStatsDest{
+		reqs:  make(chan *proto.UpdateStatsRequest),
+		resps: make(chan *proto.UpdateStatsResponse),
+	}
+}
+
+func Test_logDebouncer(t *testing.T) {
+	t.Parallel()
+
+	var (
+		buf    bytes.Buffer
+		logger = slog.Make(slogjson.Sink(&buf))
+		ctx    = context.Background()
+	)
+
+	debouncer := &logDebouncer{
+		logger:   logger,
+		messages: map[string]time.Time{},
+		interval: time.Minute,
+	}
+
+	fields := map[string]interface{}{
+		"field_1": float64(1),
+		"field_2": "2",
+	}
+
+	debouncer.Error(ctx, "my message", "field_1", 1, "field_2", "2")
+	debouncer.Warn(ctx, "another message", "field_1", 1, "field_2", "2")
+	// Shouldn't log this.
+	debouncer.Warn(ctx, "another message", "field_1", 1, "field_2", "2")
+
+	require.Len(t, debouncer.messages, 2)
+
+	type entry struct {
+		Msg    string                 `json:"msg"`
+		Level  string                 `json:"level"`
+		Fields map[string]interface{} `json:"fields"`
+	}
+
+	assertLog := func(msg string, level string, fields map[string]interface{}) {
+		line, err := buf.ReadString('\n')
+		require.NoError(t, err)
+
+		var e entry
+		err = json.Unmarshal([]byte(line), &e)
+		require.NoError(t, err)
+		require.Equal(t, msg, e.Msg)
+		require.Equal(t, level, e.Level)
+		require.Equal(t, fields, e.Fields)
+	}
+	assertLog("my message", "ERROR", fields)
+	assertLog("another message", "WARN", fields)
+
+	debouncer.messages["another message"] = time.Now().Add(-2 * time.Minute)
+	debouncer.Warn(ctx, "another message", "field_1", 1, "field_2", "2")
+	assertLog("another message", "WARN", fields)
+	// Assert nothing else was written.
+	_, err := buf.ReadString('\n')
+	require.ErrorIs(t, err, io.EOF)
+}
@@ -0,0 +1,89 @@
+package apiversion
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+
+	"golang.org/x/xerrors"
+)
+
+// New returns an *APIVersion with the given major.minor and
+// additional supported major versions.
+func New(maj, min int) *APIVersion {
+	v := &APIVersion{
+		supportedMajor:   maj,
+		supportedMinor:   min,
+		additionalMajors: make([]int, 0),
+	}
+	return v
+}
+
+type APIVersion struct {
+	supportedMajor   int
+	supportedMinor   int
+	additionalMajors []int
+}
+
+func (v *APIVersion) WithBackwardCompat(majs ...int) *APIVersion {
+	v.additionalMajors = append(v.additionalMajors, majs[:]...)
+	return v
+}
+
+func (v *APIVersion) String() string {
+	return fmt.Sprintf("%d.%d", v.supportedMajor, v.supportedMinor)
+}
+
+// Validate validates the given version against the given constraints:
+// A given major.minor version is valid iff:
+//  1. The requested major version is contained within v.supportedMajors
+//  2. If the requested major version is the 'current major', then
+//     the requested minor version must be less than or equal to the supported
+//     minor version.
+//
+// For example, given majors {1, 2} and minor 2, then:
+// - 0.x is not supported,
+// - 1.x is supported,
+// - 2.0, 2.1, and 2.2 are supported,
+// - 2.3+ is not supported.
+func (v *APIVersion) Validate(version string) error {
+	major, minor, err := Parse(version)
+	if err != nil {
+		return err
+	}
+	if major > v.supportedMajor {
+		return xerrors.Errorf("server is at version %d.%d, behind requested major version %s",
+			v.supportedMajor, v.supportedMinor, version)
+	}
+	if major == v.supportedMajor {
+		if minor > v.supportedMinor {
+			return xerrors.Errorf("server is at version %d.%d, behind requested minor version %s",
+				v.supportedMajor, v.supportedMinor, version)
+		}
+		return nil
+	}
+	for _, mjr := range v.additionalMajors {
+		if major == mjr {
+			return nil
+		}
+	}
+	return xerrors.Errorf("version %s is no longer supported", version)
+}
+
+// Parse parses a valid major.minor version string into (major, minor).
+// Both major and minor must be valid integers separated by a period '.'.
+func Parse(version string) (major int, minor int, err error) {
+	parts := strings.Split(version, ".")
+	if len(parts) != 2 {
+		return 0, 0, xerrors.Errorf("invalid version string: %s", version)
+	}
+	major, err = strconv.Atoi(parts[0])
+	if err != nil {
+		return 0, 0, xerrors.Errorf("invalid major version: %s", version)
+	}
+	minor, err = strconv.Atoi(parts[1])
+	if err != nil {
+		return 0, 0, xerrors.Errorf("invalid minor version: %s", version)
+	}
+	return major, minor, nil
+}
@@ -0,0 +1,90 @@
+package apiversion_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/v2/apiversion"
+)
+
+func TestAPIVersionValidate(t *testing.T) {
+	t.Parallel()
+
+	// Given
+	v := apiversion.New(2, 1).WithBackwardCompat(1)
+
+	for _, tc := range []struct {
+		name          string
+		version       string
+		expectedError string
+	}{
+		{
+			name:    "OK",
+			version: "2.1",
+		},
+		{
+			name:    "MinorOK",
+			version: "2.0",
+		},
+		{
+			name:    "MajorOK",
+			version: "1.0",
+		},
+		{
+			name:          "TooNewMinor",
+			version:       "2.2",
+			expectedError: "behind requested minor version",
+		},
+		{
+			name:          "TooNewMajor",
+			version:       "3.1",
+			expectedError: "behind requested major version",
+		},
+		{
+			name:          "Malformed0",
+			version:       "cats",
+			expectedError: "invalid version string",
+		},
+		{
+			name:          "Malformed1",
+			version:       "cats.dogs",
+			expectedError: "invalid major version",
+		},
+		{
+			name:          "Malformed2",
+			version:       "1.dogs",
+			expectedError: "invalid minor version",
+		},
+		{
+			name:          "Malformed3",
+			version:       "1.0.1",
+			expectedError: "invalid version string",
+		},
+		{
+			name:          "Malformed4",
+			version:       "11",
+			expectedError: "invalid version string",
+		},
+		{
+			name:          "TooOld",
+			version:       "0.8",
+			expectedError: "no longer supported",
+		},
+	} {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			// When
+			err := v.Validate(tc.version)
+
+			// Then
+			if tc.expectedError == "" {
+				require.NoError(t, err)
+			} else {
+				require.ErrorContains(t, err, tc.expectedError)
+			}
+		})
+	}
+}
@@ -18,10 +18,8 @@ import (
 	"cloud.google.com/go/compute/metadata"
 	"golang.org/x/xerrors"
 	"gopkg.in/natefinch/lumberjack.v2"
-	"tailscale.com/util/clientmetric"

 	"github.com/prometheus/client_golang/prometheus"
-	"github.com/prometheus/common/expfmt"

 	"cdr.dev/slog"
 	"cdr.dev/slog/sloggers/sloghuman"
@@ -31,15 +29,16 @@ import (
 	"github.com/coder/coder/v2/agent/agentproc"
 	"github.com/coder/coder/v2/agent/reaper"
 	"github.com/coder/coder/v2/buildinfo"
-	"github.com/coder/coder/v2/cli/clibase"
 	"github.com/coder/coder/v2/codersdk"
 	"github.com/coder/coder/v2/codersdk/agentsdk"
+	"github.com/coder/serpent"
 )

-func (r *RootCmd) workspaceAgent() *clibase.Cmd {
+func (r *RootCmd) workspaceAgent() *serpent.Command {
 	var (
 		auth                string
 		logDir              string
+		scriptDataDir       string
 		pprofAddress        string
 		noReap              bool
 		sshMaxTimeout       time.Duration
@@ -50,12 +49,12 @@ func (r *RootCmd) workspaceAgent() *clibase.Cmd {
 		slogJSONPath        string
 		slogStackdriverPath string
 	)
-	cmd := &clibase.Cmd{
+	cmd := &serpent.Command{
 		Use:   "agent",
 		Short: `Starts the Coder workspace agent.`,
 		// This command isn't useful to manually execute.
 		Hidden: true,
-		Handler: func(inv *clibase.Invocation) error {
+		Handler: func(inv *serpent.Invocation) error {
 			ctx, cancel := context.WithCancel(inv.Context())
 			defer cancel()

@@ -124,7 +123,7 @@ func (r *RootCmd) workspaceAgent() *clibase.Cmd {
 				args := append(os.Args, "--no-reap")
 				err := reaper.ForkReap(
 					reaper.WithExecArgs(args...),
-					reaper.WithCatchSignals(InterruptSignals...),
+					reaper.WithCatchSignals(StopSignals...),
 				)
 				if err != nil {
 					logger.Error(ctx, "agent process reaper unable to fork", slog.Error(err))
@@ -143,12 +142,12 @@ func (r *RootCmd) workspaceAgent() *clibase.Cmd {
 			// Note that we don't want to handle these signals in the
 			// process that runs as PID 1, that's why we do this after
 			// the reaper forked.
-			ctx, stopNotify := inv.SignalNotifyContext(ctx, InterruptSignals...)
+			ctx, stopNotify := inv.SignalNotifyContext(ctx, StopSignals...)
 			defer stopNotify()

 			// DumpHandler does signal handling, so we call it after the
 			// reaper.
-			go DumpHandler(ctx)
+			go DumpHandler(ctx, "agent")

 			logWriter := &lumberjackWriteCloseFixer{w: &lumberjack.Logger{
 				Filename: filepath.Join(logDir, "coder-agent.log"),
@@ -278,12 +277,21 @@ func (r *RootCmd) workspaceAgent() *clibase.Cmd {
 				subsystems = append(subsystems, subsystem)
 			}

-			procTicker := time.NewTicker(time.Second)
-			defer procTicker.Stop()
+			environmentVariables := map[string]string{
+				"GIT_ASKPASS": executablePath,
+			}
+			if v, ok := os.LookupEnv(agent.EnvProcPrioMgmt); ok {
+				environmentVariables[agent.EnvProcPrioMgmt] = v
+			}
+			if v, ok := os.LookupEnv(agent.EnvProcOOMScore); ok {
+				environmentVariables[agent.EnvProcOOMScore] = v
+			}
+
 			agnt := agent.New(agent.Options{
 				Client:            client,
 				Logger:            logger,
 				LogDir:            logDir,
+				ScriptDataDir:     scriptDataDir,
 				TailnetListenPort: uint16(tailnetListenPort),
 				ExchangeToken: func(ctx context.Context) (string, error) {
 					if exchangeToken == nil {
@@ -296,13 +304,10 @@ func (r *RootCmd) workspaceAgent() *clibase.Cmd {
 					client.SetSessionToken(resp.SessionToken)
 					return resp.SessionToken, nil
 				},
-				EnvironmentVariables: map[string]string{
-					"GIT_ASKPASS":         executablePath,
-					agent.EnvProcPrioMgmt: os.Getenv(agent.EnvProcPrioMgmt),
-				},
-				IgnorePorts:   ignorePorts,
-				SSHMaxTimeout: sshMaxTimeout,
-				Subsystems:    subsystems,
+				EnvironmentVariables: environmentVariables,
+				IgnorePorts:          ignorePorts,
+				SSHMaxTimeout:        sshMaxTimeout,
+				Subsystems:           subsystems,

 				PrometheusRegistry: prometheusRegistry,
 				Syscaller:          agentproc.NewSyscaller(),
@@ -311,7 +316,8 @@ func (r *RootCmd) workspaceAgent() *clibase.Cmd {
 				ModifiedProcesses: nil,
 			})

-			prometheusSrvClose := ServeHandler(ctx, logger, prometheusMetricsHandler(prometheusRegistry, logger), prometheusAddress, "prometheus")
+			promHandler := agent.PrometheusMetricsHandler(prometheusRegistry, logger)
+			prometheusSrvClose := ServeHandler(ctx, logger, promHandler, prometheusAddress, "prometheus")
 			defer prometheusSrvClose()

 			debugSrvClose := ServeHandler(ctx, logger, agnt.HTTPDebug(), debugAddress, "debug")
@@ -322,26 +328,33 @@ func (r *RootCmd) workspaceAgent() *clibase.Cmd {
 		},
 	}

-	cmd.Options = clibase.OptionSet{
+	cmd.Options = serpent.OptionSet{
 		{
 			Flag:        "auth",
 			Default:     "token",
 			Description: "Specify the authentication type to use for the agent.",
 			Env:         "CODER_AGENT_AUTH",
-			Value:       clibase.StringOf(&auth),
+			Value:       serpent.StringOf(&auth),
 		},
 		{
 			Flag:        "log-dir",
 			Default:     os.TempDir(),
 			Description: "Specify the location for the agent log files.",
 			Env:         "CODER_AGENT_LOG_DIR",
-			Value:       clibase.StringOf(&logDir),
+			Value:       serpent.StringOf(&logDir),
+		},
+		{
+			Flag:        "script-data-dir",
+			Default:     os.TempDir(),
+			Description: "Specify the location for storing script data.",
+			Env:         "CODER_AGENT_SCRIPT_DATA_DIR",
+			Value:       serpent.StringOf(&scriptDataDir),
 		},
 		{
 			Flag:        "pprof-address",
 			Default:     "127.0.0.1:6060",
 			Env:         "CODER_AGENT_PPROF_ADDRESS",
-			Value:       clibase.StringOf(&pprofAddress),
+			Value:       serpent.StringOf(&pprofAddress),
 			Description: "The address to serve pprof.",
 		},
 		{
@@ -349,7 +362,7 @@ func (r *RootCmd) workspaceAgent() *clibase.Cmd {

 			Env:         "",
 			Description: "Do not start a process reaper.",
-			Value:       clibase.BoolOf(&noReap),
+			Value:       serpent.BoolOf(&noReap),
 		},
 		{
 			Flag: "ssh-max-timeout",
@@ -357,27 +370,27 @@ func (r *RootCmd) workspaceAgent() *clibase.Cmd {
 			Default:     "72h",
 			Env:         "CODER_AGENT_SSH_MAX_TIMEOUT",
 			Description: "Specify the max timeout for a SSH connection, it is advisable to set it to a minimum of 60s, but no more than 72h.",
-			Value:       clibase.DurationOf(&sshMaxTimeout),
+			Value:       serpent.DurationOf(&sshMaxTimeout),
 		},
 		{
 			Flag:        "tailnet-listen-port",
 			Default:     "0",
 			Env:         "CODER_AGENT_TAILNET_LISTEN_PORT",
 			Description: "Specify a static port for Tailscale to use for listening.",
-			Value:       clibase.Int64Of(&tailnetListenPort),
+			Value:       serpent.Int64Of(&tailnetListenPort),
 		},
 		{
 			Flag:        "prometheus-address",
 			Default:     "127.0.0.1:2112",
 			Env:         "CODER_AGENT_PROMETHEUS_ADDRESS",
-			Value:       clibase.StringOf(&prometheusAddress),
+			Value:       serpent.StringOf(&prometheusAddress),
 			Description: "The bind address to serve Prometheus metrics.",
 		},
 		{
 			Flag:        "debug-address",
 			Default:     "127.0.0.1:2113",
 			Env:         "CODER_AGENT_DEBUG_ADDRESS",
-			Value:       clibase.StringOf(&debugAddress),
+			Value:       serpent.StringOf(&debugAddress),
 			Description: "The bind address to serve a debug HTTP server.",
 		},
 		{
@@ -386,7 +399,7 @@ func (r *RootCmd) workspaceAgent() *clibase.Cmd {
 			Flag:        "log-human",
 			Env:         "CODER_AGENT_LOGGING_HUMAN",
 			Default:     "/dev/stderr",
-			Value:       clibase.StringOf(&slogHumanPath),
+			Value:       serpent.StringOf(&slogHumanPath),
 		},
 		{
 			Name:        "JSON Log Location",
@@ -394,7 +407,7 @@ func (r *RootCmd) workspaceAgent() *clibase.Cmd {
 			Flag:        "log-json",
 			Env:         "CODER_AGENT_LOGGING_JSON",
 			Default:     "",
-			Value:       clibase.StringOf(&slogJSONPath),
+			Value:       serpent.StringOf(&slogJSONPath),
 		},
 		{
 			Name:        "Stackdriver Log Location",
@@ -402,7 +415,7 @@ func (r *RootCmd) workspaceAgent() *clibase.Cmd {
 			Flag:        "log-stackdriver",
 			Env:         "CODER_AGENT_LOGGING_STACKDRIVER",
 			Default:     "",
-			Value:       clibase.StringOf(&slogStackdriverPath),
+			Value:       serpent.StringOf(&slogStackdriverPath),
 		},
 	}

@@ -490,26 +503,3 @@ func urlPort(u string) (int, error) {
 	}
 	return -1, xerrors.Errorf("invalid port: %s", u)
 }
-
-func prometheusMetricsHandler(prometheusRegistry *prometheus.Registry, logger slog.Logger) http.Handler {
-	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		w.Header().Set("Content-Type", "text/plain")
-
-		// Based on: https://github.com/tailscale/tailscale/blob/280255acae604796a1113861f5a84e6fa2dc6121/ipn/localapi/localapi.go#L489
-		clientmetric.WritePrometheusExpositionFormat(w)
-
-		metricFamilies, err := prometheusRegistry.Gather()
-		if err != nil {
-			logger.Error(context.Background(), "Prometheus handler can't gather metric families", slog.Error(err))
-			return
-		}
-
-		for _, metricFamily := range metricFamilies {
-			_, err = expfmt.MetricFamilyToText(w, metricFamily)
-			if err != nil {
-				logger.Error(context.Background(), "expfmt.MetricFamilyToText failed", slog.Error(err))
-				return
-			}
-		}
-	})
-}
@@ -19,6 +19,7 @@ import (
 	"github.com/coder/coder/v2/coderd/database"
 	"github.com/coder/coder/v2/coderd/database/dbfake"
 	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/coder/v2/codersdk/workspacesdk"
 	"github.com/coder/coder/v2/provisionersdk/proto"
 	"github.com/coder/coder/v2/testutil"
 )
@@ -83,14 +84,16 @@ func TestWorkspaceAgent(t *testing.T) {

 		ctx := inv.Context()
 		clitest.Start(t, inv)
-		coderdtest.AwaitWorkspaceAgents(t, client, r.Workspace.ID)
+		coderdtest.NewWorkspaceAgentWaiter(t, client, r.Workspace.ID).
+			MatchResources(matchAgentWithVersion).Wait()
 		workspace, err := client.Workspace(ctx, r.Workspace.ID)
 		require.NoError(t, err)
 		resources := workspace.LatestBuild.Resources
 		if assert.NotEmpty(t, workspace.LatestBuild.Resources) && assert.NotEmpty(t, resources[0].Agents) {
 			assert.NotEmpty(t, resources[0].Agents[0].Version)
 		}
-		dialer, err := client.DialWorkspaceAgent(ctx, resources[0].Agents[0].ID, nil)
+		dialer, err := workspacesdk.New(client).
+			DialAgent(ctx, resources[0].Agents[0].ID, nil)
 		require.NoError(t, err)
 		defer dialer.Close()
 		require.True(t, dialer.AwaitReachable(ctx))
@@ -120,14 +123,17 @@ func TestWorkspaceAgent(t *testing.T) {

 		clitest.Start(t, inv)
 		ctx := inv.Context()
-		coderdtest.AwaitWorkspaceAgents(t, client, r.Workspace.ID)
+		coderdtest.NewWorkspaceAgentWaiter(t, client, r.Workspace.ID).
+			MatchResources(matchAgentWithVersion).
+			Wait()
 		workspace, err := client.Workspace(ctx, r.Workspace.ID)
 		require.NoError(t, err)
 		resources := workspace.LatestBuild.Resources
 		if assert.NotEmpty(t, resources) && assert.NotEmpty(t, resources[0].Agents) {
 			assert.NotEmpty(t, resources[0].Agents[0].Version)
 		}
-		dialer, err := client.DialWorkspaceAgent(ctx, resources[0].Agents[0].ID, nil)
+		dialer, err := workspacesdk.New(client).
+			DialAgent(ctx, resources[0].Agents[0].ID, nil)
 		require.NoError(t, err)
 		defer dialer.Close()
 		require.True(t, dialer.AwaitReachable(ctx))
@@ -161,14 +167,16 @@ func TestWorkspaceAgent(t *testing.T) {
 		)

 		ctx := inv.Context()
-		coderdtest.AwaitWorkspaceAgents(t, client, r.Workspace.ID)
+		coderdtest.NewWorkspaceAgentWaiter(t, client, r.Workspace.ID).
+			MatchResources(matchAgentWithVersion).
+			Wait()
 		workspace, err := client.Workspace(ctx, r.Workspace.ID)
 		require.NoError(t, err)
 		resources := workspace.LatestBuild.Resources
 		if assert.NotEmpty(t, resources) && assert.NotEmpty(t, resources[0].Agents) {
 			assert.NotEmpty(t, resources[0].Agents[0].Version)
 		}
-		dialer, err := client.DialWorkspaceAgent(ctx, resources[0].Agents[0].ID, nil)
+		dialer, err := workspacesdk.New(client).DialAgent(ctx, resources[0].Agents[0].ID, nil)
 		require.NoError(t, err)
 		defer dialer.Close()
 		require.True(t, dialer.AwaitReachable(ctx))
@@ -212,7 +220,8 @@ func TestWorkspaceAgent(t *testing.T) {

 		clitest.Start(t, inv)

-		resources := coderdtest.AwaitWorkspaceAgents(t, client, r.Workspace.ID)
+		resources := coderdtest.NewWorkspaceAgentWaiter(t, client, r.Workspace.ID).
+			MatchResources(matchAgentWithSubsystems).Wait()
 		require.Len(t, resources, 1)
 		require.Len(t, resources[0].Agents, 1)
 		require.Len(t, resources[0].Agents[0].Subsystems, 2)
@@ -221,3 +230,29 @@ func TestWorkspaceAgent(t *testing.T) {
 		require.Equal(t, codersdk.AgentSubsystemExectrace, resources[0].Agents[0].Subsystems[1])
 	})
 }
+
+func matchAgentWithVersion(rs []codersdk.WorkspaceResource) bool {
+	if len(rs) < 1 {
+		return false
+	}
+	if len(rs[0].Agents) < 1 {
+		return false
+	}
+	if rs[0].Agents[0].Version == "" {
+		return false
+	}
+	return true
+}
+
+func matchAgentWithSubsystems(rs []codersdk.WorkspaceResource) bool {
+	if len(rs) < 1 {
+		return false
+	}
+	if len(rs[0].Agents) < 1 {
+		return false
+	}
+	if len(rs[0].Agents[0].Subsystems) < 1 {
+		return false
+	}
+	return true
+}
@@ -6,22 +6,22 @@ import (

 	"golang.org/x/xerrors"

-	"github.com/coder/coder/v2/cli/clibase"
 	"github.com/coder/coder/v2/cli/cliui"
 	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/serpent"
 )

-func (r *RootCmd) autoupdate() *clibase.Cmd {
+func (r *RootCmd) autoupdate() *serpent.Command {
 	client := new(codersdk.Client)
-	cmd := &clibase.Cmd{
+	cmd := &serpent.Command{
 		Annotations: workspaceCommand,
 		Use:         "autoupdate <workspace> <always|never>",
 		Short:       "Toggle auto-update policy for a workspace",
-		Middleware: clibase.Chain(
-			clibase.RequireNArgs(2),
+		Middleware: serpent.Chain(
+			serpent.RequireNArgs(2),
 			r.InitClient(client),
 		),
-		Handler: func(inv *clibase.Invocation) error {
+		Handler: func(inv *serpent.Invocation) error {
 			policy := strings.ToLower(inv.Args[1])
 			err := validateAutoUpdatePolicy(policy)
 			if err != nil {
@@ -1,80 +0,0 @@
-// Package clibase offers an all-in-one solution for a highly configurable CLI
-// application. Within Coder, we use it for all of our subcommands, which
-// demands more functionality than cobra/viber offers.
-//
-// The Command interface is loosely based on the chi middleware pattern and
-// http.Handler/HandlerFunc.
-package clibase
-
-import (
-	"strings"
-
-	"golang.org/x/exp/maps"
-)
-
-// Group describes a hierarchy of groups that an option or command belongs to.
-type Group struct {
-	Parent      *Group `json:"parent,omitempty"`
-	Name        string `json:"name,omitempty"`
-	YAML        string `json:"yaml,omitempty"`
-	Description string `json:"description,omitempty"`
-}
-
-// Ancestry returns the group and all of its parents, in order.
-func (g *Group) Ancestry() []Group {
-	if g == nil {
-		return nil
-	}
-
-	groups := []Group{*g}
-	for p := g.Parent; p != nil; p = p.Parent {
-		// Prepend to the slice so that the order is correct.
-		groups = append([]Group{*p}, groups...)
-	}
-	return groups
-}
-
-func (g *Group) FullName() string {
-	var names []string
-	for _, g := range g.Ancestry() {
-		names = append(names, g.Name)
-	}
-	return strings.Join(names, " / ")
-}
-
-// Annotations is an arbitrary key-mapping used to extend the Option and Command types.
-// Its methods won't panic if the map is nil.
-type Annotations map[string]string
-
-// Mark sets a value on the annotations map, creating one
-// if it doesn't exist. Mark does not mutate the original and
-// returns a copy. It is suitable for chaining.
-func (a Annotations) Mark(key string, value string) Annotations {
-	var aa Annotations
-	if a != nil {
-		aa = maps.Clone(a)
-	} else {
-		aa = make(Annotations)
-	}
-	aa[key] = value
-	return aa
-}
-
-// IsSet returns true if the key is set in the annotations map.
-func (a Annotations) IsSet(key string) bool {
-	if a == nil {
-		return false
-	}
-	_, ok := a[key]
-	return ok
-}
-
-// Get retrieves a key from the map, returning false if the key is not found
-// or the map is nil.
-func (a Annotations) Get(key string) (string, bool) {
-	if a == nil {
-		return "", false
-	}
-	v, ok := a[key]
-	return v, ok
-}
@@ -1,621 +0,0 @@
-package clibase
-
-import (
-	"context"
-	"errors"
-	"flag"
-	"fmt"
-	"io"
-	"os"
-	"os/signal"
-	"strings"
-	"testing"
-	"unicode"
-
-	"cdr.dev/slog"
-
-	"github.com/spf13/pflag"
-	"golang.org/x/exp/slices"
-	"golang.org/x/xerrors"
-	"gopkg.in/yaml.v3"
-
-	"github.com/coder/coder/v2/coderd/util/slice"
-)
-
-// Cmd describes an executable command.
-type Cmd struct {
-	// Parent is the direct parent of the command.
-	Parent *Cmd
-	// Children is a list of direct descendants.
-	Children []*Cmd
-	// Use is provided in form "command [flags] [args...]".
-	Use string
-
-	// Aliases is a list of alternative names for the command.
-	Aliases []string
-
-	// Short is a one-line description of the command.
-	Short string
-
-	// Hidden determines whether the command should be hidden from help.
-	Hidden bool
-
-	// RawArgs determines whether the command should receive unparsed arguments.
-	// No flags are parsed when set, and the command is responsible for parsing
-	// its own flags.
-	RawArgs bool
-
-	// Long is a detailed description of the command,
-	// presented on its help page. It may contain examples.
-	Long        string
-	Options     OptionSet
-	Annotations Annotations
-
-	// Middleware is called before the Handler.
-	// Use Chain() to combine multiple middlewares.
-	Middleware  MiddlewareFunc
-	Handler     HandlerFunc
-	HelpHandler HandlerFunc
-}
-
-// AddSubcommands adds the given subcommands, setting their
-// Parent field automatically.
-func (c *Cmd) AddSubcommands(cmds ...*Cmd) {
-	for _, cmd := range cmds {
-		cmd.Parent = c
-		c.Children = append(c.Children, cmd)
-	}
-}
-
-// Walk calls fn for the command and all its children.
-func (c *Cmd) Walk(fn func(*Cmd)) {
-	fn(c)
-	for _, child := range c.Children {
-		child.Parent = c
-		child.Walk(fn)
-	}
-}
-
-// PrepareAll performs initialization and linting on the command and all its children.
-func (c *Cmd) PrepareAll() error {
-	if c.Use == "" {
-		return xerrors.New("command must have a Use field so that it has a name")
-	}
-	var merr error
-
-	for i := range c.Options {
-		opt := &c.Options[i]
-		if opt.Name == "" {
-			switch {
-			case opt.Flag != "":
-				opt.Name = opt.Flag
-			case opt.Env != "":
-				opt.Name = opt.Env
-			case opt.YAML != "":
-				opt.Name = opt.YAML
-			default:
-				merr = errors.Join(merr, xerrors.Errorf("option must have a Name, Flag, Env or YAML field"))
-			}
-		}
-		if opt.Description != "" {
-			// Enforce that description uses sentence form.
-			if unicode.IsLower(rune(opt.Description[0])) {
-				merr = errors.Join(merr, xerrors.Errorf("option %q description should start with a capital letter", opt.Name))
-			}
-			if !strings.HasSuffix(opt.Description, ".") {
-				merr = errors.Join(merr, xerrors.Errorf("option %q description should end with a period", opt.Name))
-			}
-		}
-	}
-
-	slices.SortFunc(c.Options, func(a, b Option) int {
-		return slice.Ascending(a.Name, b.Name)
-	})
-	slices.SortFunc(c.Children, func(a, b *Cmd) int {
-		return slice.Ascending(a.Name(), b.Name())
-	})
-	for _, child := range c.Children {
-		child.Parent = c
-		err := child.PrepareAll()
-		if err != nil {
-			merr = errors.Join(merr, xerrors.Errorf("command %v: %w", child.Name(), err))
-		}
-	}
-	return merr
-}
-
-// Name returns the first word in the Use string.
-func (c *Cmd) Name() string {
-	return strings.Split(c.Use, " ")[0]
-}
-
-// FullName returns the full invocation name of the command,
-// as seen on the command line.
-func (c *Cmd) FullName() string {
-	var names []string
-	if c.Parent != nil {
-		names = append(names, c.Parent.FullName())
-	}
-	names = append(names, c.Name())
-	return strings.Join(names, " ")
-}
-
-// FullName returns usage of the command, preceded
-// by the usage of its parents.
-func (c *Cmd) FullUsage() string {
-	var uses []string
-	if c.Parent != nil {
-		uses = append(uses, c.Parent.FullName())
-	}
-	uses = append(uses, c.Use)
-	return strings.Join(uses, " ")
-}
-
-// FullOptions returns the options of the command and its parents.
-func (c *Cmd) FullOptions() OptionSet {
-	var opts OptionSet
-	if c.Parent != nil {
-		opts = append(opts, c.Parent.FullOptions()...)
-	}
-	opts = append(opts, c.Options...)
-	return opts
-}
-
-// Invoke creates a new invocation of the command, with
-// stdio discarded.
-//
-// The returned invocation is not live until Run() is called.
-func (c *Cmd) Invoke(args ...string) *Invocation {
-	return &Invocation{
-		Command: c,
-		Args:    args,
-		Stdout:  io.Discard,
-		Stderr:  io.Discard,
-		Stdin:   strings.NewReader(""),
-		Logger:  slog.Make(),
-	}
-}
-
-// Invocation represents an instance of a command being executed.
-type Invocation struct {
-	ctx         context.Context
-	Command     *Cmd
-	parsedFlags *pflag.FlagSet
-	Args        []string
-	// Environ is a list of environment variables. Use EnvsWithPrefix to parse
-	// os.Environ.
-	Environ Environ
-	Stdout  io.Writer
-	Stderr  io.Writer
-	Stdin   io.Reader
-	Logger  slog.Logger
-	Net     Net
-
-	// testing
-	signalNotifyContext func(parent context.Context, signals ...os.Signal) (ctx context.Context, stop context.CancelFunc)
-}
-
-// WithOS returns the invocation as a main package, filling in the invocation's unset
-// fields with OS defaults.
-func (inv *Invocation) WithOS() *Invocation {
-	return inv.with(func(i *Invocation) {
-		i.Stdout = os.Stdout
-		i.Stderr = os.Stderr
-		i.Stdin = os.Stdin
-		i.Args = os.Args[1:]
-		i.Environ = ParseEnviron(os.Environ(), "")
-		i.Net = osNet{}
-	})
-}
-
-// WithTestSignalNotifyContext allows overriding the default implementation of SignalNotifyContext.
-// This should only be used in testing.
-func (inv *Invocation) WithTestSignalNotifyContext(
-	_ testing.TB, // ensure we only call this from tests
-	f func(parent context.Context, signals ...os.Signal) (ctx context.Context, stop context.CancelFunc),
-) *Invocation {
-	return inv.with(func(i *Invocation) {
-		i.signalNotifyContext = f
-	})
-}
-
-// SignalNotifyContext is equivalent to signal.NotifyContext, but supports being overridden in
-// tests.
-func (inv *Invocation) SignalNotifyContext(parent context.Context, signals ...os.Signal) (ctx context.Context, stop context.CancelFunc) {
-	if inv.signalNotifyContext == nil {
-		return signal.NotifyContext(parent, signals...)
-	}
-	return inv.signalNotifyContext(parent, signals...)
-}
-
-func (inv *Invocation) WithTestParsedFlags(
-	_ testing.TB, // ensure we only call this from tests
-	parsedFlags *pflag.FlagSet,
-) *Invocation {
-	return inv.with(func(i *Invocation) {
-		i.parsedFlags = parsedFlags
-	})
-}
-
-func (inv *Invocation) Context() context.Context {
-	if inv.ctx == nil {
-		return context.Background()
-	}
-	return inv.ctx
-}
-
-func (inv *Invocation) ParsedFlags() *pflag.FlagSet {
-	if inv.parsedFlags == nil {
-		panic("flags not parsed, has Run() been called?")
-	}
-	return inv.parsedFlags
-}
-
-type runState struct {
-	allArgs      []string
-	commandDepth int
-
-	flagParseErr error
-}
-
-func copyFlagSetWithout(fs *pflag.FlagSet, without string) *pflag.FlagSet {
-	fs2 := pflag.NewFlagSet("", pflag.ContinueOnError)
-	fs2.Usage = func() {}
-	fs.VisitAll(func(f *pflag.Flag) {
-		if f.Name == without {
-			return
-		}
-		fs2.AddFlag(f)
-	})
-	return fs2
-}
-
-// run recursively executes the command and its children.
-// allArgs is wired through the stack so that global flags can be accepted
-// anywhere in the command invocation.
-func (inv *Invocation) run(state *runState) error {
-	err := inv.Command.Options.ParseEnv(inv.Environ)
-	if err != nil {
-		return xerrors.Errorf("parsing env: %w", err)
-	}
-
-	// Now the fun part, argument parsing!
-
-	children := make(map[string]*Cmd)
-	for _, child := range inv.Command.Children {
-		child.Parent = inv.Command
-		for _, name := range append(child.Aliases, child.Name()) {
-			if _, ok := children[name]; ok {
-				return xerrors.Errorf("duplicate command name: %s", name)
-			}
-			children[name] = child
-		}
-	}
-
-	if inv.parsedFlags == nil {
-		inv.parsedFlags = pflag.NewFlagSet(inv.Command.Name(), pflag.ContinueOnError)
-		// We handle Usage ourselves.
-		inv.parsedFlags.Usage = func() {}
-	}
-
-	// If we find a duplicate flag, we want the deeper command's flag to override
-	// the shallow one. Unfortunately, pflag has no way to remove a flag, so we
-	// have to create a copy of the flagset without a value.
-	inv.Command.Options.FlagSet().VisitAll(func(f *pflag.Flag) {
-		if inv.parsedFlags.Lookup(f.Name) != nil {
-			inv.parsedFlags = copyFlagSetWithout(inv.parsedFlags, f.Name)
-		}
-		inv.parsedFlags.AddFlag(f)
-	})
-
-	var parsedArgs []string
-
-	if !inv.Command.RawArgs {
-		// Flag parsing will fail on intermediate commands in the command tree,
-		// so we check the error after looking for a child command.
-		state.flagParseErr = inv.parsedFlags.Parse(state.allArgs)
-		parsedArgs = inv.parsedFlags.Args()
-	}
-
-	// Set value sources for flags.
-	for i, opt := range inv.Command.Options {
-		if fl := inv.parsedFlags.Lookup(opt.Flag); fl != nil && fl.Changed {
-			inv.Command.Options[i].ValueSource = ValueSourceFlag
-		}
-	}
-
-	// Read YAML configs, if any.
-	for _, opt := range inv.Command.Options {
-		path, ok := opt.Value.(*YAMLConfigPath)
-		if !ok || path.String() == "" {
-			continue
-		}
-
-		byt, err := os.ReadFile(path.String())
-		if err != nil {
-			return xerrors.Errorf("reading yaml: %w", err)
-		}
-
-		var n yaml.Node
-		err = yaml.Unmarshal(byt, &n)
-		if err != nil {
-			return xerrors.Errorf("decoding yaml: %w", err)
-		}
-
-		err = inv.Command.Options.UnmarshalYAML(&n)
-		if err != nil {
-			return xerrors.Errorf("applying yaml: %w", err)
-		}
-	}
-
-	err = inv.Command.Options.SetDefaults()
-	if err != nil {
-		return xerrors.Errorf("setting defaults: %w", err)
-	}
-
-	// Run child command if found (next child only)
-	// We must do subcommand detection after flag parsing so we don't mistake flag
-	// values for subcommand names.
-	if len(parsedArgs) > state.commandDepth {
-		nextArg := parsedArgs[state.commandDepth]
-		if child, ok := children[nextArg]; ok {
-			child.Parent = inv.Command
-			inv.Command = child
-			state.commandDepth++
-			return inv.run(state)
-		}
-	}
-
-	// Flag parse errors are irrelevant for raw args commands.
-	if !inv.Command.RawArgs && state.flagParseErr != nil && !errors.Is(state.flagParseErr, pflag.ErrHelp) {
-		return xerrors.Errorf(
-			"parsing flags (%v) for %q: %w",
-			state.allArgs,
-			inv.Command.FullName(), state.flagParseErr,
-		)
-	}
-
-	// All options should be set. Check all required options have sources,
-	// meaning they were set by the user in some way (env, flag, etc).
-	var missing []string
-	for _, opt := range inv.Command.Options {
-		if opt.Required && opt.ValueSource == ValueSourceNone {
-			missing = append(missing, opt.Flag)
-		}
-	}
-	if len(missing) > 0 {
-		return xerrors.Errorf("Missing values for the required flags: %s", strings.Join(missing, ", "))
-	}
-
-	if inv.Command.RawArgs {
-		// If we're at the root command, then the name is omitted
-		// from the arguments, so we can just use the entire slice.
-		if state.commandDepth == 0 {
-			inv.Args = state.allArgs
-		} else {
-			argPos, err := findArg(inv.Command.Name(), state.allArgs, inv.parsedFlags)
-			if err != nil {
-				panic(err)
-			}
-			inv.Args = state.allArgs[argPos+1:]
-		}
-	} else {
-		// In non-raw-arg mode, we want to skip over flags.
-		inv.Args = parsedArgs[state.commandDepth:]
-	}
-
-	mw := inv.Command.Middleware
-	if mw == nil {
-		mw = Chain()
-	}
-
-	ctx := inv.ctx
-	if ctx == nil {
-		ctx = context.Background()
-	}
-
-	ctx, cancel := context.WithCancel(ctx)
-	defer cancel()
-	inv = inv.WithContext(ctx)
-
-	if inv.Command.Handler == nil || errors.Is(state.flagParseErr, pflag.ErrHelp) {
-		if inv.Command.HelpHandler == nil {
-			return xerrors.Errorf("no handler or help for command %s", inv.Command.FullName())
-		}
-		return inv.Command.HelpHandler(inv)
-	}
-
-	err = mw(inv.Command.Handler)(inv)
-	if err != nil {
-		return &RunCommandError{
-			Cmd: inv.Command,
-			Err: err,
-		}
-	}
-	return nil
-}
-
-type RunCommandError struct {
-	Cmd *Cmd
-	Err error
-}
-
-func (e *RunCommandError) Unwrap() error {
-	return e.Err
-}
-
-func (e *RunCommandError) Error() string {
-	return fmt.Sprintf("running command %q: %+v", e.Cmd.FullName(), e.Err)
-}
-
-// findArg returns the index of the first occurrence of arg in args, skipping
-// over all flags.
-func findArg(want string, args []string, fs *pflag.FlagSet) (int, error) {
-	for i := 0; i < len(args); i++ {
-		arg := args[i]
-		if !strings.HasPrefix(arg, "-") {
-			if arg == want {
-				return i, nil
-			}
-			continue
-		}
-
-		// This is a flag!
-		if strings.Contains(arg, "=") {
-			// The flag contains the value in the same arg, just skip.
-			continue
-		}
-
-		// We need to check if NoOptValue is set, then we should not wait
-		// for the next arg to be the value.
-		f := fs.Lookup(strings.TrimLeft(arg, "-"))
-		if f == nil {
-			return -1, xerrors.Errorf("unknown flag: %s", arg)
-		}
-		if f.NoOptDefVal != "" {
-			continue
-		}
-
-		if i == len(args)-1 {
-			return -1, xerrors.Errorf("flag %s requires a value", arg)
-		}
-
-		// Skip the value.
-		i++
-	}
-
-	return -1, xerrors.Errorf("arg %s not found", want)
-}
-
-// Run executes the command.
-// If two command share a flag name, the first command wins.
-//
-//nolint:revive
-func (inv *Invocation) Run() (err error) {
-	defer func() {
-		// Pflag is panicky, so additional context is helpful in tests.
-		if flag.Lookup("test.v") == nil {
-			return
-		}
-		if r := recover(); r != nil {
-			err = xerrors.Errorf("panic recovered for %s: %v", inv.Command.FullName(), r)
-			panic(err)
-		}
-	}()
-	// We close Stdin to prevent deadlocks, e.g. when the command
-	// has ended but an io.Copy is still reading from Stdin.
-	defer func() {
-		if inv.Stdin == nil {
-			return
-		}
-		rc, ok := inv.Stdin.(io.ReadCloser)
-		if !ok {
-			return
-		}
-		e := rc.Close()
-		err = errors.Join(err, e)
-	}()
-	err = inv.run(&runState{
-		allArgs: inv.Args,
-	})
-	return err
-}
-
-// WithContext returns a copy of the Invocation with the given context.
-func (inv *Invocation) WithContext(ctx context.Context) *Invocation {
-	return inv.with(func(i *Invocation) {
-		i.ctx = ctx
-	})
-}
-
-// with returns a copy of the Invocation with the given function applied.
-func (inv *Invocation) with(fn func(*Invocation)) *Invocation {
-	i2 := *inv
-	fn(&i2)
-	return &i2
-}
-
-// MiddlewareFunc returns the next handler in the chain,
-// or nil if there are no more.
-type MiddlewareFunc func(next HandlerFunc) HandlerFunc
-
-func chain(ms ...MiddlewareFunc) MiddlewareFunc {
-	return MiddlewareFunc(func(next HandlerFunc) HandlerFunc {
-		if len(ms) > 0 {
-			return chain(ms[1:]...)(ms[0](next))
-		}
-		return next
-	})
-}
-
-// Chain returns a Handler that first calls middleware in order.
-//
-//nolint:revive
-func Chain(ms ...MiddlewareFunc) MiddlewareFunc {
-	// We need to reverse the array to provide top-to-bottom execution
-	// order when defining a command.
-	reversed := make([]MiddlewareFunc, len(ms))
-	for i := range ms {
-		reversed[len(ms)-1-i] = ms[i]
-	}
-	return chain(reversed...)
-}
-
-func RequireNArgs(want int) MiddlewareFunc {
-	return RequireRangeArgs(want, want)
-}
-
-// RequireRangeArgs returns a Middleware that requires the number of arguments
-// to be between start and end (inclusive). If end is -1, then the number of
-// arguments must be at least start.
-func RequireRangeArgs(start, end int) MiddlewareFunc {
-	if start < 0 {
-		panic("start must be >= 0")
-	}
-	return func(next HandlerFunc) HandlerFunc {
-		return func(i *Invocation) error {
-			got := len(i.Args)
-			switch {
-			case start == end && got != start:
-				switch start {
-				case 0:
-					if len(i.Command.Children) > 0 {
-						return xerrors.Errorf("unrecognized subcommand %q", i.Args[0])
-					}
-					return xerrors.Errorf("wanted no args but got %v %v", got, i.Args)
-				default:
-					return xerrors.Errorf(
-						"wanted %v args but got %v %v",
-						start,
-						got,
-						i.Args,
-					)
-				}
-			case start > 0 && end == -1:
-				switch {
-				case got < start:
-					return xerrors.Errorf(
-						"wanted at least %v args but got %v",
-						start,
-						got,
-					)
-				default:
-					return next(i)
-				}
-			case start > end:
-				panic("start must be <= end")
-			case got < start || got > end:
-				return xerrors.Errorf(
-					"wanted between %v and %v args but got %v",
-					start, end,
-					got,
-				)
-			default:
-				return next(i)
-			}
-		}
-	}
-}
-
-// HandlerFunc handles an Invocation of a command.
-type HandlerFunc func(i *Invocation) error
@@ -1,719 +0,0 @@
-package clibase_test
-
-import (
-	"bytes"
-	"context"
-	"fmt"
-	"os"
-	"strings"
-	"testing"
-
-	"github.com/stretchr/testify/require"
-	"golang.org/x/xerrors"
-
-	"github.com/coder/coder/v2/cli/clibase"
-)
-
-// ioBufs is the standard input, output, and error for a command.
-type ioBufs struct {
-	Stdin  bytes.Buffer
-	Stdout bytes.Buffer
-	Stderr bytes.Buffer
-}
-
-// fakeIO sets Stdin, Stdout, and Stderr to buffers.
-func fakeIO(i *clibase.Invocation) *ioBufs {
-	var b ioBufs
-	i.Stdout = &b.Stdout
-	i.Stderr = &b.Stderr
-	i.Stdin = &b.Stdin
-	return &b
-}
-
-func TestCommand(t *testing.T) {
-	t.Parallel()
-
-	cmd := func() *clibase.Cmd {
-		var (
-			verbose bool
-			lower   bool
-			prefix  string
-			reqBool bool
-			reqStr  string
-		)
-		return &clibase.Cmd{
-			Use: "root [subcommand]",
-			Options: clibase.OptionSet{
-				clibase.Option{
-					Name:  "verbose",
-					Flag:  "verbose",
-					Value: clibase.BoolOf(&verbose),
-				},
-				clibase.Option{
-					Name:  "prefix",
-					Flag:  "prefix",
-					Value: clibase.StringOf(&prefix),
-				},
-			},
-			Children: []*clibase.Cmd{
-				{
-					Use:   "required-flag --req-bool=true --req-string=foo",
-					Short: "Example with required flags",
-					Options: clibase.OptionSet{
-						clibase.Option{
-							Name:     "req-bool",
-							Flag:     "req-bool",
-							Value:    clibase.BoolOf(&reqBool),
-							Required: true,
-						},
-						clibase.Option{
-							Name: "req-string",
-							Flag: "req-string",
-							Value: clibase.Validate(clibase.StringOf(&reqStr), func(value *clibase.String) error {
-								ok := strings.Contains(value.String(), " ")
-								if !ok {
-									return xerrors.Errorf("string must contain a space")
-								}
-								return nil
-							}),
-							Required: true,
-						},
-					},
-					Handler: func(i *clibase.Invocation) error {
-						_, _ = i.Stdout.Write([]byte(fmt.Sprintf("%s-%t", reqStr, reqBool)))
-						return nil
-					},
-				},
-				{
-					Use:   "toupper [word]",
-					Short: "Converts a word to upper case",
-					Middleware: clibase.Chain(
-						clibase.RequireNArgs(1),
-					),
-					Aliases: []string{"up"},
-					Options: clibase.OptionSet{
-						clibase.Option{
-							Name:  "lower",
-							Flag:  "lower",
-							Value: clibase.BoolOf(&lower),
-						},
-					},
-					Handler: func(i *clibase.Invocation) error {
-						_, _ = i.Stdout.Write([]byte(prefix))
-						w := i.Args[0]
-						if lower {
-							w = strings.ToLower(w)
-						} else {
-							w = strings.ToUpper(w)
-						}
-						_, _ = i.Stdout.Write(
-							[]byte(
-								w,
-							),
-						)
-						if verbose {
-							i.Stdout.Write([]byte("!!!"))
-						}
-						return nil
-					},
-				},
-			},
-		}
-	}
-
-	t.Run("SimpleOK", func(t *testing.T) {
-		t.Parallel()
-		i := cmd().Invoke("toupper", "hello")
-		io := fakeIO(i)
-		i.Run()
-		require.Equal(t, "HELLO", io.Stdout.String())
-	})
-
-	t.Run("Alias", func(t *testing.T) {
-		t.Parallel()
-		i := cmd().Invoke(
-			"up", "hello",
-		)
-		io := fakeIO(i)
-		i.Run()
-		require.Equal(t, "HELLO", io.Stdout.String())
-	})
-
-	t.Run("NoSubcommand", func(t *testing.T) {
-		t.Parallel()
-		i := cmd().Invoke(
-			"na",
-		)
-		io := fakeIO(i)
-		err := i.Run()
-		require.Empty(t, io.Stdout.String())
-		require.Error(t, err)
-	})
-
-	t.Run("BadArgs", func(t *testing.T) {
-		t.Parallel()
-		i := cmd().Invoke(
-			"toupper",
-		)
-		io := fakeIO(i)
-		err := i.Run()
-		require.Empty(t, io.Stdout.String())
-		require.Error(t, err)
-	})
-
-	t.Run("UnknownFlags", func(t *testing.T) {
-		t.Parallel()
-		i := cmd().Invoke(
-			"toupper", "--unknown",
-		)
-		io := fakeIO(i)
-		err := i.Run()
-		require.Empty(t, io.Stdout.String())
-		require.Error(t, err)
-	})
-
-	t.Run("Verbose", func(t *testing.T) {
-		t.Parallel()
-		i := cmd().Invoke(
-			"--verbose", "toupper", "hello",
-		)
-		io := fakeIO(i)
-		require.NoError(t, i.Run())
-		require.Equal(t, "HELLO!!!", io.Stdout.String())
-	})
-
-	t.Run("Verbose=", func(t *testing.T) {
-		t.Parallel()
-		i := cmd().Invoke(
-			"--verbose=true", "toupper", "hello",
-		)
-		io := fakeIO(i)
-		require.NoError(t, i.Run())
-		require.Equal(t, "HELLO!!!", io.Stdout.String())
-	})
-
-	t.Run("PrefixSpace", func(t *testing.T) {
-		t.Parallel()
-		i := cmd().Invoke(
-			"--prefix", "conv: ", "toupper", "hello",
-		)
-		io := fakeIO(i)
-		require.NoError(t, i.Run())
-		require.Equal(t, "conv: HELLO", io.Stdout.String())
-	})
-
-	t.Run("GlobalFlagsAnywhere", func(t *testing.T) {
-		t.Parallel()
-		i := cmd().Invoke(
-			"toupper", "--prefix", "conv: ", "hello", "--verbose",
-		)
-		io := fakeIO(i)
-		require.NoError(t, i.Run())
-		require.Equal(t, "conv: HELLO!!!", io.Stdout.String())
-	})
-
-	t.Run("LowerVerbose", func(t *testing.T) {
-		t.Parallel()
-		i := cmd().Invoke(
-			"toupper", "--verbose", "hello", "--lower",
-		)
-		io := fakeIO(i)
-		require.NoError(t, i.Run())
-		require.Equal(t, "hello!!!", io.Stdout.String())
-	})
-
-	t.Run("ParsedFlags", func(t *testing.T) {
-		t.Parallel()
-		i := cmd().Invoke(
-			"toupper", "--verbose", "hello", "--lower",
-		)
-		_ = fakeIO(i)
-		require.NoError(t, i.Run())
-		require.Equal(t,
-			"true",
-			i.ParsedFlags().Lookup("verbose").Value.String(),
-		)
-	})
-
-	t.Run("NoDeepChild", func(t *testing.T) {
-		t.Parallel()
-		i := cmd().Invoke(
-			"root", "level", "level", "toupper", "--verbose", "hello", "--lower",
-		)
-		fio := fakeIO(i)
-		require.Error(t, i.Run(), fio.Stdout.String())
-	})
-
-	t.Run("RequiredFlagsMissing", func(t *testing.T) {
-		t.Parallel()
-		i := cmd().Invoke(
-			"required-flag",
-		)
-		fio := fakeIO(i)
-		err := i.Run()
-		require.Error(t, err, fio.Stdout.String())
-		require.ErrorContains(t, err, "Missing values")
-	})
-
-	t.Run("RequiredFlagsMissingBool", func(t *testing.T) {
-		t.Parallel()
-		i := cmd().Invoke(
-			"required-flag", "--req-string", "foo bar",
-		)
-		fio := fakeIO(i)
-		err := i.Run()
-		require.Error(t, err, fio.Stdout.String())
-		require.ErrorContains(t, err, "Missing values for the required flags: req-bool")
-	})
-
-	t.Run("RequiredFlagsMissingString", func(t *testing.T) {
-		t.Parallel()
-		i := cmd().Invoke(
-			"required-flag", "--req-bool", "true",
-		)
-		fio := fakeIO(i)
-		err := i.Run()
-		require.Error(t, err, fio.Stdout.String())
-		require.ErrorContains(t, err, "Missing values for the required flags: req-string")
-	})
-
-	t.Run("RequiredFlagsInvalid", func(t *testing.T) {
-		t.Parallel()
-		i := cmd().Invoke(
-			"required-flag", "--req-string", "nospace",
-		)
-		fio := fakeIO(i)
-		err := i.Run()
-		require.Error(t, err, fio.Stdout.String())
-		require.ErrorContains(t, err, "string must contain a space")
-	})
-
-	t.Run("RequiredFlagsOK", func(t *testing.T) {
-		t.Parallel()
-		i := cmd().Invoke(
-			"required-flag", "--req-bool", "true", "--req-string", "foo bar",
-		)
-		fio := fakeIO(i)
-		err := i.Run()
-		require.NoError(t, err, fio.Stdout.String())
-	})
-}
-
-func TestCommand_DeepNest(t *testing.T) {
-	t.Parallel()
-	cmd := &clibase.Cmd{
-		Use: "1",
-		Children: []*clibase.Cmd{
-			{
-				Use: "2",
-				Children: []*clibase.Cmd{
-					{
-						Use: "3",
-						Handler: func(i *clibase.Invocation) error {
-							i.Stdout.Write([]byte("3"))
-							return nil
-						},
-					},
-				},
-			},
-		},
-	}
-	inv := cmd.Invoke("2", "3")
-	stdio := fakeIO(inv)
-	err := inv.Run()
-	require.NoError(t, err)
-	require.Equal(t, "3", stdio.Stdout.String())
-}
-
-func TestCommand_FlagOverride(t *testing.T) {
-	t.Parallel()
-	var flag string
-
-	cmd := &clibase.Cmd{
-		Use: "1",
-		Options: clibase.OptionSet{
-			{
-				Name:  "flag",
-				Flag:  "f",
-				Value: clibase.DiscardValue,
-			},
-		},
-		Children: []*clibase.Cmd{
-			{
-				Use: "2",
-				Options: clibase.OptionSet{
-					{
-						Name:  "flag",
-						Flag:  "f",
-						Value: clibase.StringOf(&flag),
-					},
-				},
-				Handler: func(i *clibase.Invocation) error {
-					return nil
-				},
-			},
-		},
-	}
-
-	err := cmd.Invoke("2", "--f", "mhmm").Run()
-	require.NoError(t, err)
-
-	require.Equal(t, "mhmm", flag)
-}
-
-func TestCommand_MiddlewareOrder(t *testing.T) {
-	t.Parallel()
-
-	mw := func(letter string) clibase.MiddlewareFunc {
-		return func(next clibase.HandlerFunc) clibase.HandlerFunc {
-			return (func(i *clibase.Invocation) error {
-				_, _ = i.Stdout.Write([]byte(letter))
-				return next(i)
-			})
-		}
-	}
-
-	cmd := &clibase.Cmd{
-		Use:   "toupper [word]",
-		Short: "Converts a word to upper case",
-		Middleware: clibase.Chain(
-			mw("A"),
-			mw("B"),
-			mw("C"),
-		),
-		Handler: (func(i *clibase.Invocation) error {
-			return nil
-		}),
-	}
-
-	i := cmd.Invoke(
-		"hello", "world",
-	)
-	io := fakeIO(i)
-	require.NoError(t, i.Run())
-	require.Equal(t, "ABC", io.Stdout.String())
-}
-
-func TestCommand_RawArgs(t *testing.T) {
-	t.Parallel()
-
-	cmd := func() *clibase.Cmd {
-		return &clibase.Cmd{
-			Use: "root",
-			Options: clibase.OptionSet{
-				{
-					Name:  "password",
-					Flag:  "password",
-					Value: clibase.StringOf(new(string)),
-				},
-			},
-			Children: []*clibase.Cmd{
-				{
-					Use:     "sushi <args...>",
-					Short:   "Throws back raw output",
-					RawArgs: true,
-					Handler: (func(i *clibase.Invocation) error {
-						if v := i.ParsedFlags().Lookup("password").Value.String(); v != "codershack" {
-							return xerrors.Errorf("password %q is wrong!", v)
-						}
-						i.Stdout.Write([]byte(strings.Join(i.Args, " ")))
-						return nil
-					}),
-				},
-			},
-		}
-	}
-
-	t.Run("OK", func(t *testing.T) {
-		// Flag parsed before the raw arg command should still work.
-		t.Parallel()
-
-		i := cmd().Invoke(
-			"--password", "codershack", "sushi", "hello", "--verbose", "world",
-		)
-		io := fakeIO(i)
-		require.NoError(t, i.Run())
-		require.Equal(t, "hello --verbose world", io.Stdout.String())
-	})
-
-	t.Run("BadFlag", func(t *testing.T) {
-		// Verbose before the raw arg command should fail.
-		t.Parallel()
-
-		i := cmd().Invoke(
-			"--password", "codershack", "--verbose", "sushi", "hello", "world",
-		)
-		io := fakeIO(i)
-		require.Error(t, i.Run())
-		require.Empty(t, io.Stdout.String())
-	})
-
-	t.Run("NoPassword", func(t *testing.T) {
-		// Flag parsed before the raw arg command should still work.
-		t.Parallel()
-		i := cmd().Invoke(
-			"sushi", "hello", "--verbose", "world",
-		)
-		_ = fakeIO(i)
-		require.Error(t, i.Run())
-	})
-}
-
-func TestCommand_RootRaw(t *testing.T) {
-	t.Parallel()
-	cmd := &clibase.Cmd{
-		RawArgs: true,
-		Handler: func(i *clibase.Invocation) error {
-			i.Stdout.Write([]byte(strings.Join(i.Args, " ")))
-			return nil
-		},
-	}
-
-	inv := cmd.Invoke("hello", "--verbose", "--friendly")
-	stdio := fakeIO(inv)
-	err := inv.Run()
-	require.NoError(t, err)
-
-	require.Equal(t, "hello --verbose --friendly", stdio.Stdout.String())
-}
-
-func TestCommand_HyphenHyphen(t *testing.T) {
-	t.Parallel()
-	cmd := &clibase.Cmd{
-		Handler: (func(i *clibase.Invocation) error {
-			i.Stdout.Write([]byte(strings.Join(i.Args, " ")))
-			return nil
-		}),
-	}
-
-	inv := cmd.Invoke("--", "--verbose", "--friendly")
-	stdio := fakeIO(inv)
-	err := inv.Run()
-	require.NoError(t, err)
-
-	require.Equal(t, "--verbose --friendly", stdio.Stdout.String())
-}
-
-func TestCommand_ContextCancels(t *testing.T) {
-	t.Parallel()
-
-	var gotCtx context.Context
-
-	cmd := &clibase.Cmd{
-		Handler: (func(i *clibase.Invocation) error {
-			gotCtx = i.Context()
-			if err := gotCtx.Err(); err != nil {
-				return xerrors.Errorf("unexpected context error: %w", i.Context().Err())
-			}
-			return nil
-		}),
-	}
-
-	err := cmd.Invoke().Run()
-	require.NoError(t, err)
-
-	require.Error(t, gotCtx.Err())
-}
-
-func TestCommand_Help(t *testing.T) {
-	t.Parallel()
-
-	cmd := func() *clibase.Cmd {
-		return &clibase.Cmd{
-			Use: "root",
-			HelpHandler: (func(i *clibase.Invocation) error {
-				i.Stdout.Write([]byte("abdracadabra"))
-				return nil
-			}),
-			Handler: (func(i *clibase.Invocation) error {
-				return xerrors.New("should not be called")
-			}),
-		}
-	}
-
-	t.Run("NoHandler", func(t *testing.T) {
-		t.Parallel()
-
-		c := cmd()
-		c.HelpHandler = nil
-		err := c.Invoke("--help").Run()
-		require.Error(t, err)
-	})
-
-	t.Run("Long", func(t *testing.T) {
-		t.Parallel()
-
-		inv := cmd().Invoke("--help")
-		stdio := fakeIO(inv)
-		err := inv.Run()
-		require.NoError(t, err)
-
-		require.Contains(t, stdio.Stdout.String(), "abdracadabra")
-	})
-
-	t.Run("Short", func(t *testing.T) {
-		t.Parallel()
-
-		inv := cmd().Invoke("-h")
-		stdio := fakeIO(inv)
-		err := inv.Run()
-		require.NoError(t, err)
-
-		require.Contains(t, stdio.Stdout.String(), "abdracadabra")
-	})
-}
-
-func TestCommand_SliceFlags(t *testing.T) {
-	t.Parallel()
-
-	cmd := func(want ...string) *clibase.Cmd {
-		var got []string
-		return &clibase.Cmd{
-			Use: "root",
-			Options: clibase.OptionSet{
-				{
-					Name:    "arr",
-					Flag:    "arr",
-					Default: "bad,bad,bad",
-					Value:   clibase.StringArrayOf(&got),
-				},
-			},
-			Handler: (func(i *clibase.Invocation) error {
-				require.Equal(t, want, got)
-				return nil
-			}),
-		}
-	}
-
-	err := cmd("good", "good", "good").Invoke("--arr", "good", "--arr", "good", "--arr", "good").Run()
-	require.NoError(t, err)
-
-	err = cmd("bad", "bad", "bad").Invoke().Run()
-	require.NoError(t, err)
-}
-
-func TestCommand_EmptySlice(t *testing.T) {
-	t.Parallel()
-
-	cmd := func(want ...string) *clibase.Cmd {
-		var got []string
-		return &clibase.Cmd{
-			Use: "root",
-			Options: clibase.OptionSet{
-				{
-					Name:    "arr",
-					Flag:    "arr",
-					Default: "def,def,def",
-					Env:     "ARR",
-					Value:   clibase.StringArrayOf(&got),
-				},
-			},
-			Handler: (func(i *clibase.Invocation) error {
-				require.Equal(t, want, got)
-				return nil
-			}),
-		}
-	}
-
-	// Base-case, uses default.
-	err := cmd("def", "def", "def").Invoke().Run()
-	require.NoError(t, err)
-
-	// Empty-env uses default, too.
-	inv := cmd("def", "def", "def").Invoke()
-	inv.Environ.Set("ARR", "")
-	require.NoError(t, err)
-
-	// Reset to nothing at all via flag.
-	inv = cmd().Invoke("--arr", "")
-	inv.Environ.Set("ARR", "cant see")
-	err = inv.Run()
-	require.NoError(t, err)
-
-	// Reset to a specific value with flag.
-	inv = cmd("great").Invoke("--arr", "great")
-	inv.Environ.Set("ARR", "")
-	err = inv.Run()
-	require.NoError(t, err)
-}
-
-func TestCommand_DefaultsOverride(t *testing.T) {
-	t.Parallel()
-
-	test := func(name string, want string, fn func(t *testing.T, inv *clibase.Invocation)) {
-		t.Run(name, func(t *testing.T) {
-			t.Parallel()
-
-			var (
-				got    string
-				config clibase.YAMLConfigPath
-			)
-			cmd := &clibase.Cmd{
-				Options: clibase.OptionSet{
-					{
-						Name:    "url",
-						Flag:    "url",
-						Default: "def.com",
-						Env:     "URL",
-						Value:   clibase.StringOf(&got),
-						YAML:    "url",
-					},
-					{
-						Name:    "config",
-						Flag:    "config",
-						Default: "",
-						Value:   &config,
-					},
-				},
-				Handler: (func(i *clibase.Invocation) error {
-					_, _ = fmt.Fprintf(i.Stdout, "%s", got)
-					return nil
-				}),
-			}
-
-			inv := cmd.Invoke()
-			stdio := fakeIO(inv)
-			fn(t, inv)
-			err := inv.Run()
-			require.NoError(t, err)
-			require.Equal(t, want, stdio.Stdout.String())
-		})
-	}
-
-	test("DefaultOverNothing", "def.com", func(t *testing.T, inv *clibase.Invocation) {})
-
-	test("FlagOverDefault", "good.com", func(t *testing.T, inv *clibase.Invocation) {
-		inv.Args = []string{"--url", "good.com"}
-	})
-
-	test("EnvOverDefault", "good.com", func(t *testing.T, inv *clibase.Invocation) {
-		inv.Environ.Set("URL", "good.com")
-	})
-
-	test("FlagOverEnv", "good.com", func(t *testing.T, inv *clibase.Invocation) {
-		inv.Environ.Set("URL", "bad.com")
-		inv.Args = []string{"--url", "good.com"}
-	})
-
-	test("FlagOverYAML", "good.com", func(t *testing.T, inv *clibase.Invocation) {
-		fi, err := os.CreateTemp(t.TempDir(), "config.yaml")
-		require.NoError(t, err)
-		defer fi.Close()
-
-		_, err = fi.WriteString("url: bad.com")
-		require.NoError(t, err)
-
-		inv.Args = []string{"--config", fi.Name(), "--url", "good.com"}
-	})
-
-	test("YAMLOverDefault", "good.com", func(t *testing.T, inv *clibase.Invocation) {
-		fi, err := os.CreateTemp(t.TempDir(), "config.yaml")
-		require.NoError(t, err)
-		defer fi.Close()
-
-		_, err = fi.WriteString("url: good.com")
-		require.NoError(t, err)
-
-		inv.Args = []string{"--config", fi.Name()}
-	})
-}
@@ -1,76 +0,0 @@
-package clibase
-
-import "strings"
-
-// name returns the name of the environment variable.
-func envName(line string) string {
-	return strings.ToUpper(
-		strings.SplitN(line, "=", 2)[0],
-	)
-}
-
-// value returns the value of the environment variable.
-func envValue(line string) string {
-	tokens := strings.SplitN(line, "=", 2)
-	if len(tokens) < 2 {
-		return ""
-	}
-	return tokens[1]
-}
-
-// Var represents a single environment variable of form
-// NAME=VALUE.
-type EnvVar struct {
-	Name  string
-	Value string
-}
-
-type Environ []EnvVar
-
-func (e Environ) ToOS() []string {
-	var env []string
-	for _, v := range e {
-		env = append(env, v.Name+"="+v.Value)
-	}
-	return env
-}
-
-func (e Environ) Lookup(name string) (string, bool) {
-	for _, v := range e {
-		if v.Name == name {
-			return v.Value, true
-		}
-	}
-	return "", false
-}
-
-func (e Environ) Get(name string) string {
-	v, _ := e.Lookup(name)
-	return v
-}
-
-func (e *Environ) Set(name, value string) {
-	for i, v := range *e {
-		if v.Name == name {
-			(*e)[i].Value = value
-			return
-		}
-	}
-	*e = append(*e, EnvVar{Name: name, Value: value})
-}
-
-// ParseEnviron returns all environment variables starting with
-// prefix without said prefix.
-func ParseEnviron(environ []string, prefix string) Environ {
-	var filtered []EnvVar
-	for _, line := range environ {
-		name := envName(line)
-		if strings.HasPrefix(name, prefix) {
-			filtered = append(filtered, EnvVar{
-				Name:  strings.TrimPrefix(name, prefix),
-				Value: envValue(line),
-			})
-		}
-	}
-	return filtered
-}
@@ -1,44 +0,0 @@
-package clibase_test
-
-import (
-	"reflect"
-	"testing"
-
-	"github.com/coder/coder/v2/cli/clibase"
-)
-
-func TestFilterNamePrefix(t *testing.T) {
-	t.Parallel()
-	type args struct {
-		environ []string
-		prefix  string
-	}
-	tests := []struct {
-		name string
-		args args
-		want clibase.Environ
-	}{
-		{"empty", args{[]string{}, "SHIRE"}, nil},
-		{
-			"ONE",
-			args{
-				[]string{
-					"SHIRE_BRANDYBUCK=hmm",
-				},
-				"SHIRE_",
-			},
-			[]clibase.EnvVar{
-				{Name: "BRANDYBUCK", Value: "hmm"},
-			},
-		},
-	}
-	for _, tt := range tests {
-		tt := tt
-		t.Run(tt.name, func(t *testing.T) {
-			t.Parallel()
-			if got := clibase.ParseEnviron(tt.args.environ, tt.args.prefix); !reflect.DeepEqual(got, tt.want) {
-				t.Errorf("FilterNamePrefix() = %v, want %v", got, tt.want)
-			}
-		})
-	}
-}
@@ -1,50 +0,0 @@
-package clibase
-
-import (
-	"net"
-	"strconv"
-
-	"github.com/pion/udp"
-	"golang.org/x/xerrors"
-)
-
-// Net abstracts CLI commands interacting with the operating system networking.
-//
-// At present, it covers opening local listening sockets, since doing this
-// in testing is a challenge without flakes, since it's hard to pick a port we
-// know a priori will be free.
-type Net interface {
-	// Listen has the same semantics as `net.Listen` but also supports `udp`
-	Listen(network, address string) (net.Listener, error)
-}
-
-// osNet is an implementation that call the real OS for networking.
-type osNet struct{}
-
-func (osNet) Listen(network, address string) (net.Listener, error) {
-	switch network {
-	case "tcp", "tcp4", "tcp6", "unix", "unixpacket":
-		return net.Listen(network, address)
-	case "udp":
-		host, port, err := net.SplitHostPort(address)
-		if err != nil {
-			return nil, xerrors.Errorf("split %q: %w", address, err)
-		}
-
-		var portInt int
-		portInt, err = strconv.Atoi(port)
-		if err != nil {
-			return nil, xerrors.Errorf("parse port %v from %q as int: %w", port, address, err)
-		}
-
-		// Use pion here so that we get a stream-style net.Conn listener, instead
-		// of a packet-oriented connection that can read and write to multiple
-		// addresses.
-		return udp.Listen(network, &net.UDPAddr{
-			IP:   net.ParseIP(host),
-			Port: portInt,
-		})
-	default:
-		return nil, xerrors.Errorf("unknown listen network %q", network)
-	}
-}
@@ -1,346 +0,0 @@
-package clibase
-
-import (
-	"bytes"
-	"encoding/json"
-	"os"
-	"strings"
-
-	"github.com/hashicorp/go-multierror"
-	"github.com/spf13/pflag"
-	"golang.org/x/xerrors"
-)
-
-type ValueSource string
-
-const (
-	ValueSourceNone    ValueSource = ""
-	ValueSourceFlag    ValueSource = "flag"
-	ValueSourceEnv     ValueSource = "env"
-	ValueSourceYAML    ValueSource = "yaml"
-	ValueSourceDefault ValueSource = "default"
-)
-
-// Option is a configuration option for a CLI application.
-type Option struct {
-	Name        string `json:"name,omitempty"`
-	Description string `json:"description,omitempty"`
-	// Required means this value must be set by some means. It requires
-	// `ValueSource != ValueSourceNone`
-	// If `Default` is set, then `Required` is ignored.
-	Required bool `json:"required,omitempty"`
-
-	// Flag is the long name of the flag used to configure this option. If unset,
-	// flag configuring is disabled.
-	Flag string `json:"flag,omitempty"`
-	// FlagShorthand is the one-character shorthand for the flag. If unset, no
-	// shorthand is used.
-	FlagShorthand string `json:"flag_shorthand,omitempty"`
-
-	// Env is the environment variable used to configure this option. If unset,
-	// environment configuring is disabled.
-	Env string `json:"env,omitempty"`
-
-	// YAML is the YAML key used to configure this option. If unset, YAML
-	// configuring is disabled.
-	YAML string `json:"yaml,omitempty"`
-
-	// Default is parsed into Value if set.
-	Default string `json:"default,omitempty"`
-	// Value includes the types listed in values.go.
-	Value pflag.Value `json:"value,omitempty"`
-
-	// Annotations enable extensions to clibase higher up in the stack. It's useful for
-	// help formatting and documentation generation.
-	Annotations Annotations `json:"annotations,omitempty"`
-
-	// Group is a group hierarchy that helps organize this option in help, configs
-	// and other documentation.
-	Group *Group `json:"group,omitempty"`
-
-	// UseInstead is a list of options that should be used instead of this one.
-	// The field is used to generate a deprecation warning.
-	UseInstead []Option `json:"use_instead,omitempty"`
-
-	Hidden bool `json:"hidden,omitempty"`
-
-	ValueSource ValueSource `json:"value_source,omitempty"`
-}
-
-// optionNoMethods is just a wrapper around Option so we can defer to the
-// default json.Unmarshaler behavior.
-type optionNoMethods Option
-
-func (o *Option) UnmarshalJSON(data []byte) error {
-	// If an option has no values, we have no idea how to unmarshal it.
-	// So just discard the json data.
-	if o.Value == nil {
-		o.Value = &DiscardValue
-	}
-
-	return json.Unmarshal(data, (*optionNoMethods)(o))
-}
-
-func (o Option) YAMLPath() string {
-	if o.YAML == "" {
-		return ""
-	}
-	var gs []string
-	for _, g := range o.Group.Ancestry() {
-		gs = append(gs, g.YAML)
-	}
-	return strings.Join(append(gs, o.YAML), ".")
-}
-
-// OptionSet is a group of options that can be applied to a command.
-type OptionSet []Option
-
-// UnmarshalJSON implements json.Unmarshaler for OptionSets. Options have an
-// interface Value type that cannot handle unmarshalling because the types cannot
-// be inferred. Since it is a slice, instantiating the Options first does not
-// help.
-//
-// However, we typically do instantiate the slice to have the correct types.
-// So this unmarshaller will attempt to find the named option in the existing
-// set, if it cannot, the value is discarded. If the option exists, the value
-// is unmarshalled into the existing option, and replaces the existing option.
-//
-// The value is discarded if it's type cannot be inferred. This behavior just
-// feels "safer", although it should never happen if the correct option set
-// is passed in. The situation where this could occur is if a client and server
-// are on different versions with different options.
-func (optSet *OptionSet) UnmarshalJSON(data []byte) error {
-	dec := json.NewDecoder(bytes.NewBuffer(data))
-	// Should be a json array, so consume the starting open bracket.
-	t, err := dec.Token()
-	if err != nil {
-		return xerrors.Errorf("read array open bracket: %w", err)
-	}
-	if t != json.Delim('[') {
-		return xerrors.Errorf("expected array open bracket, got %q", t)
-	}
-
-	// As long as json elements exist, consume them. The counter is used for
-	// better errors.
-	var i int
-OptionSetDecodeLoop:
-	for dec.More() {
-		var opt Option
-		// jValue is a placeholder value that allows us to capture the
-		// raw json for the value to attempt to unmarshal later.
-		var jValue jsonValue
-		opt.Value = &jValue
-		err := dec.Decode(&opt)
-		if err != nil {
-			return xerrors.Errorf("decode %d option: %w", i, err)
-		}
-		// This counter is used to contextualize errors to show which element of
-		// the array we failed to decode. It is only used in the error above, as
-		// if the above works, we can instead use the Option.Name which is more
-		// descriptive and useful. So increment here for the next decode.
-		i++
-
-		// Try to see if the option already exists in the option set.
-		// If it does, just update the existing option.
-		for optIndex, have := range *optSet {
-			if have.Name == opt.Name {
-				if jValue != nil {
-					err := json.Unmarshal(jValue, &(*optSet)[optIndex].Value)
-					if err != nil {
-						return xerrors.Errorf("decode option %q value: %w", have.Name, err)
-					}
-					// Set the opt's value
-					opt.Value = (*optSet)[optIndex].Value
-				} else {
-					// Hopefully the user passed empty values in the option set. There is no easy way
-					// to tell, and if we do not do this, it breaks json.Marshal if we do it again on
-					// this new option set.
-					opt.Value = (*optSet)[optIndex].Value
-				}
-				// Override the existing.
-				(*optSet)[optIndex] = opt
-				// Go to the next option to decode.
-				continue OptionSetDecodeLoop
-			}
-		}
-
-		// If the option doesn't exist, the value will be discarded.
-		// We do this because we cannot infer the type of the value.
-		opt.Value = DiscardValue
-		*optSet = append(*optSet, opt)
-	}
-
-	t, err = dec.Token()
-	if err != nil {
-		return xerrors.Errorf("read array close bracket: %w", err)
-	}
-	if t != json.Delim(']') {
-		return xerrors.Errorf("expected array close bracket, got %q", t)
-	}
-
-	return nil
-}
-
-// Add adds the given Options to the OptionSet.
-func (optSet *OptionSet) Add(opts ...Option) {
-	*optSet = append(*optSet, opts...)
-}
-
-// Filter will only return options that match the given filter. (return true)
-func (optSet OptionSet) Filter(filter func(opt Option) bool) OptionSet {
-	cpy := make(OptionSet, 0)
-	for _, opt := range optSet {
-		if filter(opt) {
-			cpy = append(cpy, opt)
-		}
-	}
-	return cpy
-}
-
-// FlagSet returns a pflag.FlagSet for the OptionSet.
-func (optSet *OptionSet) FlagSet() *pflag.FlagSet {
-	if optSet == nil {
-		return &pflag.FlagSet{}
-	}
-
-	fs := pflag.NewFlagSet("", pflag.ContinueOnError)
-	for _, opt := range *optSet {
-		if opt.Flag == "" {
-			continue
-		}
-		var noOptDefValue string
-		{
-			no, ok := opt.Value.(NoOptDefValuer)
-			if ok {
-				noOptDefValue = no.NoOptDefValue()
-			}
-		}
-
-		val := opt.Value
-		if val == nil {
-			val = DiscardValue
-		}
-
-		fs.AddFlag(&pflag.Flag{
-			Name:        opt.Flag,
-			Shorthand:   opt.FlagShorthand,
-			Usage:       opt.Description,
-			Value:       val,
-			DefValue:    "",
-			Changed:     false,
-			Deprecated:  "",
-			NoOptDefVal: noOptDefValue,
-			Hidden:      opt.Hidden,
-		})
-	}
-	fs.Usage = func() {
-		_, _ = os.Stderr.WriteString("Override (*FlagSet).Usage() to print help text.\n")
-	}
-	return fs
-}
-
-// ParseEnv parses the given environment variables into the OptionSet.
-// Use EnvsWithPrefix to filter out prefixes.
-func (optSet *OptionSet) ParseEnv(vs []EnvVar) error {
-	if optSet == nil {
-		return nil
-	}
-
-	var merr *multierror.Error
-
-	// We parse environment variables first instead of using a nested loop to
-	// avoid N*M complexity when there are a lot of options and environment
-	// variables.
-	envs := make(map[string]string)
-	for _, v := range vs {
-		envs[v.Name] = v.Value
-	}
-
-	for i, opt := range *optSet {
-		if opt.Env == "" {
-			continue
-		}
-
-		envVal, ok := envs[opt.Env]
-		if !ok {
-			// Homebrew strips all environment variables that do not start with `HOMEBREW_`.
-			// This prevented using brew to invoke the Coder agent, because the environment
-			// variables to not get passed down.
-			//
-			// A customer wanted to use their custom tap inside a workspace, which was failing
-			// because the agent lacked the environment variables to authenticate with Git.
-			envVal, ok = envs[`HOMEBREW_`+opt.Env]
-		}
-		// Currently, empty values are treated as if the environment variable is
-		// unset. This behavior is technically not correct as there is now no
-		// way for a user to change a Default value to an empty string from
-		// the environment. Unfortunately, we have old configuration files
-		// that rely on the faulty behavior.
-		//
-		// TODO: We should remove this hack in May 2023, when deployments
-		// have had months to migrate to the new behavior.
-		if !ok || envVal == "" {
-			continue
-		}
-
-		(*optSet)[i].ValueSource = ValueSourceEnv
-		if err := opt.Value.Set(envVal); err != nil {
-			merr = multierror.Append(
-				merr, xerrors.Errorf("parse %q: %w", opt.Name, err),
-			)
-		}
-	}
-
-	return merr.ErrorOrNil()
-}
-
-// SetDefaults sets the default values for each Option, skipping values
-// that already have a value source.
-func (optSet *OptionSet) SetDefaults() error {
-	if optSet == nil {
-		return nil
-	}
-
-	var merr *multierror.Error
-
-	for i, opt := range *optSet {
-		// Skip values that may have already been set by the user.
-		if opt.ValueSource != ValueSourceNone {
-			continue
-		}
-
-		if opt.Default == "" {
-			continue
-		}
-
-		if opt.Value == nil {
-			merr = multierror.Append(
-				merr,
-				xerrors.Errorf(
-					"parse %q: no Value field set\nFull opt: %+v",
-					opt.Name, opt,
-				),
-			)
-			continue
-		}
-		(*optSet)[i].ValueSource = ValueSourceDefault
-		if err := opt.Value.Set(opt.Default); err != nil {
-			merr = multierror.Append(
-				merr, xerrors.Errorf("parse %q: %w", opt.Name, err),
-			)
-		}
-	}
-	return merr.ErrorOrNil()
-}
-
-// ByName returns the Option with the given name, or nil if no such option
-// exists.
-func (optSet *OptionSet) ByName(name string) *Option {
-	for i := range *optSet {
-		opt := &(*optSet)[i]
-		if opt.Name == name {
-			return opt
-		}
-	}
-	return nil
-}
@@ -1,391 +0,0 @@
-package clibase_test
-
-import (
-	"bytes"
-	"encoding/json"
-	"regexp"
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-
-	"github.com/coder/coder/v2/cli/clibase"
-	"github.com/coder/coder/v2/coderd/coderdtest"
-	"github.com/coder/coder/v2/codersdk"
-)
-
-func TestOptionSet_ParseFlags(t *testing.T) {
-	t.Parallel()
-
-	t.Run("SimpleString", func(t *testing.T) {
-		t.Parallel()
-
-		var workspaceName clibase.String
-
-		os := clibase.OptionSet{
-			clibase.Option{
-				Name:          "Workspace Name",
-				Value:         &workspaceName,
-				Flag:          "workspace-name",
-				FlagShorthand: "n",
-			},
-		}
-
-		var err error
-		err = os.FlagSet().Parse([]string{"--workspace-name", "foo"})
-		require.NoError(t, err)
-		require.EqualValues(t, "foo", workspaceName)
-
-		err = os.FlagSet().Parse([]string{"-n", "f"})
-		require.NoError(t, err)
-		require.EqualValues(t, "f", workspaceName)
-	})
-
-	t.Run("StringArray", func(t *testing.T) {
-		t.Parallel()
-
-		var names clibase.StringArray
-
-		os := clibase.OptionSet{
-			clibase.Option{
-				Name:          "name",
-				Value:         &names,
-				Flag:          "name",
-				FlagShorthand: "n",
-			},
-		}
-
-		err := os.SetDefaults()
-		require.NoError(t, err)
-
-		err = os.FlagSet().Parse([]string{"--name", "foo", "--name", "bar"})
-		require.NoError(t, err)
-		require.EqualValues(t, []string{"foo", "bar"}, names)
-	})
-
-	t.Run("ExtraFlags", func(t *testing.T) {
-		t.Parallel()
-
-		var workspaceName clibase.String
-
-		os := clibase.OptionSet{
-			clibase.Option{
-				Name:  "Workspace Name",
-				Value: &workspaceName,
-			},
-		}
-
-		err := os.FlagSet().Parse([]string{"--some-unknown", "foo"})
-		require.Error(t, err)
-	})
-
-	t.Run("RegexValid", func(t *testing.T) {
-		t.Parallel()
-
-		var regexpString clibase.Regexp
-
-		os := clibase.OptionSet{
-			clibase.Option{
-				Name:  "RegexpString",
-				Value: &regexpString,
-				Flag:  "regexp-string",
-			},
-		}
-
-		err := os.FlagSet().Parse([]string{"--regexp-string", "$test^"})
-		require.NoError(t, err)
-	})
-
-	t.Run("RegexInvalid", func(t *testing.T) {
-		t.Parallel()
-
-		var regexpString clibase.Regexp
-
-		os := clibase.OptionSet{
-			clibase.Option{
-				Name:  "RegexpString",
-				Value: &regexpString,
-				Flag:  "regexp-string",
-			},
-		}
-
-		err := os.FlagSet().Parse([]string{"--regexp-string", "(("})
-		require.Error(t, err)
-	})
-}
-
-func TestOptionSet_ParseEnv(t *testing.T) {
-	t.Parallel()
-
-	t.Run("SimpleString", func(t *testing.T) {
-		t.Parallel()
-
-		var workspaceName clibase.String
-
-		os := clibase.OptionSet{
-			clibase.Option{
-				Name:  "Workspace Name",
-				Value: &workspaceName,
-				Env:   "WORKSPACE_NAME",
-			},
-		}
-
-		err := os.ParseEnv([]clibase.EnvVar{
-			{Name: "WORKSPACE_NAME", Value: "foo"},
-		})
-		require.NoError(t, err)
-		require.EqualValues(t, "foo", workspaceName)
-	})
-
-	t.Run("EmptyValue", func(t *testing.T) {
-		t.Parallel()
-
-		var workspaceName clibase.String
-
-		os := clibase.OptionSet{
-			clibase.Option{
-				Name:    "Workspace Name",
-				Value:   &workspaceName,
-				Default: "defname",
-				Env:     "WORKSPACE_NAME",
-			},
-		}
-
-		err := os.SetDefaults()
-		require.NoError(t, err)
-
-		err = os.ParseEnv(clibase.ParseEnviron([]string{"CODER_WORKSPACE_NAME="}, "CODER_"))
-		require.NoError(t, err)
-		require.EqualValues(t, "defname", workspaceName)
-	})
-
-	t.Run("StringSlice", func(t *testing.T) {
-		t.Parallel()
-
-		var actual clibase.StringArray
-		expected := []string{"foo", "bar", "baz"}
-
-		os := clibase.OptionSet{
-			clibase.Option{
-				Name:  "name",
-				Value: &actual,
-				Env:   "NAMES",
-			},
-		}
-
-		err := os.SetDefaults()
-		require.NoError(t, err)
-
-		err = os.ParseEnv([]clibase.EnvVar{
-			{Name: "NAMES", Value: "foo,bar,baz"},
-		})
-		require.NoError(t, err)
-		require.EqualValues(t, expected, actual)
-	})
-
-	t.Run("StructMapStringString", func(t *testing.T) {
-		t.Parallel()
-
-		var actual clibase.Struct[map[string]string]
-		expected := map[string]string{"foo": "bar", "baz": "zap"}
-
-		os := clibase.OptionSet{
-			clibase.Option{
-				Name:  "labels",
-				Value: &actual,
-				Env:   "LABELS",
-			},
-		}
-
-		err := os.SetDefaults()
-		require.NoError(t, err)
-
-		err = os.ParseEnv([]clibase.EnvVar{
-			{Name: "LABELS", Value: `{"foo":"bar","baz":"zap"}`},
-		})
-		require.NoError(t, err)
-		require.EqualValues(t, expected, actual.Value)
-	})
-
-	t.Run("Homebrew", func(t *testing.T) {
-		t.Parallel()
-
-		var agentToken clibase.String
-
-		os := clibase.OptionSet{
-			clibase.Option{
-				Name:  "Agent Token",
-				Value: &agentToken,
-				Env:   "AGENT_TOKEN",
-			},
-		}
-
-		err := os.ParseEnv([]clibase.EnvVar{
-			{Name: "HOMEBREW_AGENT_TOKEN", Value: "foo"},
-		})
-		require.NoError(t, err)
-		require.EqualValues(t, "foo", agentToken)
-	})
-}
-
-func TestOptionSet_JsonMarshal(t *testing.T) {
-	t.Parallel()
-
-	// This unit test ensures if the source optionset is missing the option
-	// and cannot determine the type, it will not panic. The unmarshal will
-	// succeed with a best effort.
-	t.Run("MissingSrcOption", func(t *testing.T) {
-		t.Parallel()
-
-		var str clibase.String = "something"
-		var arr clibase.StringArray = []string{"foo", "bar"}
-		opts := clibase.OptionSet{
-			clibase.Option{
-				Name:  "StringOpt",
-				Value: &str,
-			},
-			clibase.Option{
-				Name:  "ArrayOpt",
-				Value: &arr,
-			},
-		}
-		data, err := json.Marshal(opts)
-		require.NoError(t, err, "marshal option set")
-
-		tgt := clibase.OptionSet{}
-		err = json.Unmarshal(data, &tgt)
-		require.NoError(t, err, "unmarshal option set")
-		for i := range opts {
-			compareOptionsExceptValues(t, opts[i], tgt[i])
-			require.Empty(t, tgt[i].Value.String(), "unknown value types are empty")
-		}
-	})
-
-	t.Run("RegexCase", func(t *testing.T) {
-		t.Parallel()
-
-		val := clibase.Regexp(*regexp.MustCompile(".*"))
-		opts := clibase.OptionSet{
-			clibase.Option{
-				Name:    "Regex",
-				Value:   &val,
-				Default: ".*",
-			},
-		}
-		data, err := json.Marshal(opts)
-		require.NoError(t, err, "marshal option set")
-
-		var foundVal clibase.Regexp
-		newOpts := clibase.OptionSet{
-			clibase.Option{
-				Name:  "Regex",
-				Value: &foundVal,
-			},
-		}
-		err = json.Unmarshal(data, &newOpts)
-		require.NoError(t, err, "unmarshal option set")
-
-		require.EqualValues(t, opts[0].Value.String(), newOpts[0].Value.String())
-	})
-
-	t.Run("AllValues", func(t *testing.T) {
-		t.Parallel()
-
-		vals := coderdtest.DeploymentValues(t)
-		opts := vals.Options()
-		sources := []clibase.ValueSource{
-			clibase.ValueSourceNone,
-			clibase.ValueSourceFlag,
-			clibase.ValueSourceEnv,
-			clibase.ValueSourceYAML,
-			clibase.ValueSourceDefault,
-		}
-		for i := range opts {
-			opts[i].ValueSource = sources[i%len(sources)]
-		}
-
-		data, err := json.Marshal(opts)
-		require.NoError(t, err, "marshal option set")
-
-		newOpts := (&codersdk.DeploymentValues{}).Options()
-		err = json.Unmarshal(data, &newOpts)
-		require.NoError(t, err, "unmarshal option set")
-
-		for i := range opts {
-			exp := opts[i]
-			found := newOpts[i]
-
-			compareOptionsExceptValues(t, exp, found)
-			compareValues(t, exp, found)
-		}
-
-		thirdOpts := (&codersdk.DeploymentValues{}).Options()
-		data, err = json.Marshal(newOpts)
-		require.NoError(t, err, "marshal option set")
-
-		err = json.Unmarshal(data, &thirdOpts)
-		require.NoError(t, err, "unmarshal option set")
-		// Compare to the original opts again
-		for i := range opts {
-			exp := opts[i]
-			found := thirdOpts[i]
-
-			compareOptionsExceptValues(t, exp, found)
-			compareValues(t, exp, found)
-		}
-	})
-}
-
-func compareOptionsExceptValues(t *testing.T, exp, found clibase.Option) {
-	t.Helper()
-
-	require.Equalf(t, exp.Name, found.Name, "option name %q", exp.Name)
-	require.Equalf(t, exp.Description, found.Description, "option description %q", exp.Name)
-	require.Equalf(t, exp.Required, found.Required, "option required %q", exp.Name)
-	require.Equalf(t, exp.Flag, found.Flag, "option flag %q", exp.Name)
-	require.Equalf(t, exp.FlagShorthand, found.FlagShorthand, "option flag shorthand %q", exp.Name)
-	require.Equalf(t, exp.Env, found.Env, "option env %q", exp.Name)
-	require.Equalf(t, exp.YAML, found.YAML, "option yaml %q", exp.Name)
-	require.Equalf(t, exp.Default, found.Default, "option default %q", exp.Name)
-	require.Equalf(t, exp.ValueSource, found.ValueSource, "option value source %q", exp.Name)
-	require.Equalf(t, exp.Hidden, found.Hidden, "option hidden %q", exp.Name)
-	require.Equalf(t, exp.Annotations, found.Annotations, "option annotations %q", exp.Name)
-	require.Equalf(t, exp.Group, found.Group, "option group %q", exp.Name)
-	// UseInstead is the same comparison problem, just check the length
-	require.Equalf(t, len(exp.UseInstead), len(found.UseInstead), "option use instead %q", exp.Name)
-}
-
-func compareValues(t *testing.T, exp, found clibase.Option) {
-	t.Helper()
-
-	if (exp.Value == nil || found.Value == nil) || (exp.Value.String() != found.Value.String() && found.Value.String() == "") {
-		// If the string values are different, this can be a "nil" issue.
-		// So only run this case if the found string is the empty string.
-		// We use MarshalYAML for struct strings, and it will return an
-		// empty string '""' for nil slices/maps/etc.
-		// So use json to compare.
-
-		expJSON, err := json.Marshal(exp.Value)
-		require.NoError(t, err, "marshal")
-		foundJSON, err := json.Marshal(found.Value)
-		require.NoError(t, err, "marshal")
-
-		expJSON = normalizeJSON(expJSON)
-		foundJSON = normalizeJSON(foundJSON)
-		assert.Equalf(t, string(expJSON), string(foundJSON), "option value %q", exp.Name)
-	} else {
-		assert.Equal(t,
-			exp.Value.String(),
-			found.Value.String(),
-			"option value %q", exp.Name)
-	}
-}
-
-// normalizeJSON handles the fact that an empty map/slice is not the same
-// as a nil empty/slice. For our purposes, they are the same.
-func normalizeJSON(data []byte) []byte {
-	if bytes.Equal(data, []byte("[]")) || bytes.Equal(data, []byte("{}")) {
-		return []byte("null")
-	}
-	return data
-}
@@ -1,567 +0,0 @@
-package clibase
-
-import (
-	"encoding/csv"
-	"encoding/json"
-	"fmt"
-	"net"
-	"net/url"
-	"reflect"
-	"regexp"
-	"strconv"
-	"strings"
-	"time"
-
-	"github.com/spf13/pflag"
-	"golang.org/x/xerrors"
-	"gopkg.in/yaml.v3"
-)
-
-// NoOptDefValuer describes behavior when no
-// option is passed into the flag.
-//
-// This is useful for boolean or otherwise binary flags.
-type NoOptDefValuer interface {
-	NoOptDefValue() string
-}
-
-// Validator is a wrapper around a pflag.Value that allows for validation
-// of the value after or before it has been set.
-type Validator[T pflag.Value] struct {
-	Value T
-	// validate is called after the value is set.
-	validate func(T) error
-}
-
-func Validate[T pflag.Value](opt T, validate func(value T) error) *Validator[T] {
-	return &Validator[T]{Value: opt, validate: validate}
-}
-
-func (i *Validator[T]) String() string {
-	return i.Value.String()
-}
-
-func (i *Validator[T]) Set(input string) error {
-	err := i.Value.Set(input)
-	if err != nil {
-		return err
-	}
-	if i.validate != nil {
-		err = i.validate(i.Value)
-		if err != nil {
-			return err
-		}
-	}
-	return nil
-}
-
-func (i *Validator[T]) Type() string {
-	return i.Value.Type()
-}
-
-// values.go contains a standard set of value types that can be used as
-// Option Values.
-
-type Int64 int64
-
-func Int64Of(i *int64) *Int64 {
-	return (*Int64)(i)
-}
-
-func (i *Int64) Set(s string) error {
-	ii, err := strconv.ParseInt(s, 10, 64)
-	*i = Int64(ii)
-	return err
-}
-
-func (i Int64) Value() int64 {
-	return int64(i)
-}
-
-func (i Int64) String() string {
-	return strconv.Itoa(int(i))
-}
-
-func (Int64) Type() string {
-	return "int"
-}
-
-type Bool bool
-
-func BoolOf(b *bool) *Bool {
-	return (*Bool)(b)
-}
-
-func (b *Bool) Set(s string) error {
-	if s == "" {
-		*b = Bool(false)
-		return nil
-	}
-	bb, err := strconv.ParseBool(s)
-	*b = Bool(bb)
-	return err
-}
-
-func (*Bool) NoOptDefValue() string {
-	return "true"
-}
-
-func (b Bool) String() string {
-	return strconv.FormatBool(bool(b))
-}
-
-func (b Bool) Value() bool {
-	return bool(b)
-}
-
-func (Bool) Type() string {
-	return "bool"
-}
-
-type String string
-
-func StringOf(s *string) *String {
-	return (*String)(s)
-}
-
-func (*String) NoOptDefValue() string {
-	return ""
-}
-
-func (s *String) Set(v string) error {
-	*s = String(v)
-	return nil
-}
-
-func (s String) String() string {
-	return string(s)
-}
-
-func (s String) Value() string {
-	return string(s)
-}
-
-func (String) Type() string {
-	return "string"
-}
-
-var _ pflag.SliceValue = &StringArray{}
-
-// StringArray is a slice of strings that implements pflag.Value and pflag.SliceValue.
-type StringArray []string
-
-func StringArrayOf(ss *[]string) *StringArray {
-	return (*StringArray)(ss)
-}
-
-func (s *StringArray) Append(v string) error {
-	*s = append(*s, v)
-	return nil
-}
-
-func (s *StringArray) Replace(vals []string) error {
-	*s = vals
-	return nil
-}
-
-func (s *StringArray) GetSlice() []string {
-	return *s
-}
-
-func readAsCSV(v string) ([]string, error) {
-	return csv.NewReader(strings.NewReader(v)).Read()
-}
-
-func writeAsCSV(vals []string) string {
-	var sb strings.Builder
-	err := csv.NewWriter(&sb).Write(vals)
-	if err != nil {
-		return fmt.Sprintf("error: %s", err)
-	}
-	return sb.String()
-}
-
-func (s *StringArray) Set(v string) error {
-	if v == "" {
-		*s = nil
-		return nil
-	}
-	ss, err := readAsCSV(v)
-	if err != nil {
-		return err
-	}
-	*s = append(*s, ss...)
-	return nil
-}
-
-func (s StringArray) String() string {
-	return writeAsCSV([]string(s))
-}
-
-func (s StringArray) Value() []string {
-	return []string(s)
-}
-
-func (StringArray) Type() string {
-	return "string-array"
-}
-
-type Duration time.Duration
-
-func DurationOf(d *time.Duration) *Duration {
-	return (*Duration)(d)
-}
-
-func (d *Duration) Set(v string) error {
-	dd, err := time.ParseDuration(v)
-	*d = Duration(dd)
-	return err
-}
-
-func (d *Duration) Value() time.Duration {
-	return time.Duration(*d)
-}
-
-func (d *Duration) String() string {
-	return time.Duration(*d).String()
-}
-
-func (Duration) Type() string {
-	return "duration"
-}
-
-func (d *Duration) MarshalYAML() (interface{}, error) {
-	return yaml.Node{
-		Kind:  yaml.ScalarNode,
-		Value: d.String(),
-	}, nil
-}
-
-func (d *Duration) UnmarshalYAML(n *yaml.Node) error {
-	return d.Set(n.Value)
-}
-
-type URL url.URL
-
-func URLOf(u *url.URL) *URL {
-	return (*URL)(u)
-}
-
-func (u *URL) Set(v string) error {
-	uu, err := url.Parse(v)
-	if err != nil {
-		return err
-	}
-	*u = URL(*uu)
-	return nil
-}
-
-func (u *URL) String() string {
-	uu := url.URL(*u)
-	return uu.String()
-}
-
-func (u *URL) MarshalYAML() (interface{}, error) {
-	return yaml.Node{
-		Kind:  yaml.ScalarNode,
-		Value: u.String(),
-	}, nil
-}
-
-func (u *URL) UnmarshalYAML(n *yaml.Node) error {
-	return u.Set(n.Value)
-}
-
-func (u *URL) MarshalJSON() ([]byte, error) {
-	return json.Marshal(u.String())
-}
-
-func (u *URL) UnmarshalJSON(b []byte) error {
-	var s string
-	err := json.Unmarshal(b, &s)
-	if err != nil {
-		return err
-	}
-	return u.Set(s)
-}
-
-func (*URL) Type() string {
-	return "url"
-}
-
-func (u *URL) Value() *url.URL {
-	return (*url.URL)(u)
-}
-
-// HostPort is a host:port pair.
-type HostPort struct {
-	Host string
-	Port string
-}
-
-func (hp *HostPort) Set(v string) error {
-	if v == "" {
-		return xerrors.Errorf("must not be empty")
-	}
-	var err error
-	hp.Host, hp.Port, err = net.SplitHostPort(v)
-	return err
-}
-
-func (hp *HostPort) String() string {
-	if hp.Host == "" && hp.Port == "" {
-		return ""
-	}
-	// Warning: net.JoinHostPort must be used over concatenation to support
-	// IPv6 addresses.
-	return net.JoinHostPort(hp.Host, hp.Port)
-}
-
-func (hp *HostPort) MarshalJSON() ([]byte, error) {
-	return json.Marshal(hp.String())
-}
-
-func (hp *HostPort) UnmarshalJSON(b []byte) error {
-	var s string
-	err := json.Unmarshal(b, &s)
-	if err != nil {
-		return err
-	}
-	if s == "" {
-		hp.Host = ""
-		hp.Port = ""
-		return nil
-	}
-	return hp.Set(s)
-}
-
-func (hp *HostPort) MarshalYAML() (interface{}, error) {
-	return yaml.Node{
-		Kind:  yaml.ScalarNode,
-		Value: hp.String(),
-	}, nil
-}
-
-func (hp *HostPort) UnmarshalYAML(n *yaml.Node) error {
-	return hp.Set(n.Value)
-}
-
-func (*HostPort) Type() string {
-	return "host:port"
-}
-
-var (
-	_ yaml.Marshaler   = new(Struct[struct{}])
-	_ yaml.Unmarshaler = new(Struct[struct{}])
-)
-
-// Struct is a special value type that encodes an arbitrary struct.
-// It implements the flag.Value interface, but in general these values should
-// only be accepted via config for ergonomics.
-//
-// The string encoding type is YAML.
-type Struct[T any] struct {
-	Value T
-}
-
-//nolint:revive
-func (s *Struct[T]) Set(v string) error {
-	return yaml.Unmarshal([]byte(v), &s.Value)
-}
-
-//nolint:revive
-func (s *Struct[T]) String() string {
-	byt, err := yaml.Marshal(s.Value)
-	if err != nil {
-		return "decode failed: " + err.Error()
-	}
-	return string(byt)
-}
-
-func (s *Struct[T]) MarshalYAML() (interface{}, error) {
-	var n yaml.Node
-	err := n.Encode(s.Value)
-	if err != nil {
-		return nil, err
-	}
-	return n, nil
-}
-
-func (s *Struct[T]) UnmarshalYAML(n *yaml.Node) error {
-	// HACK: for compatibility with flags, we use nil slices instead of empty
-	// slices. In most cases, nil slices and empty slices are treated
-	// the same, so this behavior may be removed at some point.
-	if typ := reflect.TypeOf(s.Value); typ.Kind() == reflect.Slice && len(n.Content) == 0 {
-		reflect.ValueOf(&s.Value).Elem().Set(reflect.Zero(typ))
-		return nil
-	}
-	return n.Decode(&s.Value)
-}
-
-//nolint:revive
-func (s *Struct[T]) Type() string {
-	return fmt.Sprintf("struct[%T]", s.Value)
-}
-
-func (s *Struct[T]) MarshalJSON() ([]byte, error) {
-	return json.Marshal(s.Value)
-}
-
-func (s *Struct[T]) UnmarshalJSON(b []byte) error {
-	return json.Unmarshal(b, &s.Value)
-}
-
-// DiscardValue does nothing but implements the pflag.Value interface.
-// It's useful in cases where you want to accept an option, but access the
-// underlying value directly instead of through the Option methods.
-var DiscardValue discardValue
-
-type discardValue struct{}
-
-func (discardValue) Set(string) error {
-	return nil
-}
-
-func (discardValue) String() string {
-	return ""
-}
-
-func (discardValue) Type() string {
-	return "discard"
-}
-
-func (discardValue) UnmarshalJSON([]byte) error {
-	return nil
-}
-
-// jsonValue is intentionally not exported. It is just used to store the raw JSON
-// data for a value to defer it's unmarshal. It implements the pflag.Value to be
-// usable in an Option.
-type jsonValue json.RawMessage
-
-func (jsonValue) Set(string) error {
-	return xerrors.Errorf("json value is read-only")
-}
-
-func (jsonValue) String() string {
-	return ""
-}
-
-func (jsonValue) Type() string {
-	return "json"
-}
-
-func (j *jsonValue) UnmarshalJSON(data []byte) error {
-	if j == nil {
-		return xerrors.New("json.RawMessage: UnmarshalJSON on nil pointer")
-	}
-	*j = append((*j)[0:0], data...)
-	return nil
-}
-
-var _ pflag.Value = (*Enum)(nil)
-
-type Enum struct {
-	Choices []string
-	Value   *string
-}
-
-func EnumOf(v *string, choices ...string) *Enum {
-	return &Enum{
-		Choices: choices,
-		Value:   v,
-	}
-}
-
-func (e *Enum) Set(v string) error {
-	for _, c := range e.Choices {
-		if v == c {
-			*e.Value = v
-			return nil
-		}
-	}
-	return xerrors.Errorf("invalid choice: %s, should be one of %v", v, e.Choices)
-}
-
-func (e *Enum) Type() string {
-	return fmt.Sprintf("enum[%v]", strings.Join(e.Choices, "|"))
-}
-
-func (e *Enum) String() string {
-	return *e.Value
-}
-
-type Regexp regexp.Regexp
-
-func (r *Regexp) MarshalJSON() ([]byte, error) {
-	return json.Marshal(r.String())
-}
-
-func (r *Regexp) UnmarshalJSON(data []byte) error {
-	var source string
-	err := json.Unmarshal(data, &source)
-	if err != nil {
-		return err
-	}
-
-	exp, err := regexp.Compile(source)
-	if err != nil {
-		return xerrors.Errorf("invalid regex expression: %w", err)
-	}
-	*r = Regexp(*exp)
-	return nil
-}
-
-func (r *Regexp) MarshalYAML() (interface{}, error) {
-	return yaml.Node{
-		Kind:  yaml.ScalarNode,
-		Value: r.String(),
-	}, nil
-}
-
-func (r *Regexp) UnmarshalYAML(n *yaml.Node) error {
-	return r.Set(n.Value)
-}
-
-func (r *Regexp) Set(v string) error {
-	exp, err := regexp.Compile(v)
-	if err != nil {
-		return xerrors.Errorf("invalid regex expression: %w", err)
-	}
-	*r = Regexp(*exp)
-	return nil
-}
-
-func (r Regexp) String() string {
-	return r.Value().String()
-}
-
-func (r *Regexp) Value() *regexp.Regexp {
-	if r == nil {
-		return nil
-	}
-	return (*regexp.Regexp)(r)
-}
-
-func (Regexp) Type() string {
-	return "regexp"
-}
-
-var _ pflag.Value = (*YAMLConfigPath)(nil)
-
-// YAMLConfigPath is a special value type that encodes a path to a YAML
-// configuration file where options are read from.
-type YAMLConfigPath string
-
-func (p *YAMLConfigPath) Set(v string) error {
-	*p = YAMLConfigPath(v)
-	return nil
-}
-
-func (p *YAMLConfigPath) String() string {
-	return string(*p)
-}
-
-func (*YAMLConfigPath) Type() string {
-	return "yaml-config-path"
-}
@@ -1,295 +0,0 @@
-package clibase
-
-import (
-	"errors"
-	"fmt"
-	"strings"
-
-	"github.com/mitchellh/go-wordwrap"
-	"golang.org/x/xerrors"
-	"gopkg.in/yaml.v3"
-)
-
-var (
-	_ yaml.Marshaler   = new(OptionSet)
-	_ yaml.Unmarshaler = new(OptionSet)
-)
-
-// deepMapNode returns the mapping node at the given path,
-// creating it if it doesn't exist.
-func deepMapNode(n *yaml.Node, path []string, headComment string) *yaml.Node {
-	if len(path) == 0 {
-		return n
-	}
-
-	// Name is every two nodes.
-	for i := 0; i < len(n.Content)-1; i += 2 {
-		if n.Content[i].Value == path[0] {
-			// Found matching name, recurse.
-			return deepMapNode(n.Content[i+1], path[1:], headComment)
-		}
-	}
-
-	// Not found, create it.
-	nameNode := yaml.Node{
-		Kind:        yaml.ScalarNode,
-		Value:       path[0],
-		HeadComment: headComment,
-	}
-	valueNode := yaml.Node{
-		Kind: yaml.MappingNode,
-	}
-	n.Content = append(n.Content, &nameNode)
-	n.Content = append(n.Content, &valueNode)
-	return deepMapNode(&valueNode, path[1:], headComment)
-}
-
-// MarshalYAML converts the option set to a YAML node, that can be
-// converted into bytes via yaml.Marshal.
-//
-// The node is returned to enable post-processing higher up in
-// the stack.
-//
-// It is isomorphic with FromYAML.
-func (optSet *OptionSet) MarshalYAML() (any, error) {
-	root := yaml.Node{
-		Kind: yaml.MappingNode,
-	}
-
-	for _, opt := range *optSet {
-		if opt.YAML == "" {
-			continue
-		}
-
-		defValue := opt.Default
-		if defValue == "" {
-			defValue = "<unset>"
-		}
-		comment := wordwrap.WrapString(
-			fmt.Sprintf("%s\n(default: %s, type: %s)", opt.Description, defValue, opt.Value.Type()),
-			80,
-		)
-		nameNode := yaml.Node{
-			Kind:        yaml.ScalarNode,
-			Value:       opt.YAML,
-			HeadComment: comment,
-		}
-		var valueNode yaml.Node
-		if opt.Value == nil {
-			valueNode = yaml.Node{
-				Kind:  yaml.ScalarNode,
-				Value: "null",
-			}
-		} else if m, ok := opt.Value.(yaml.Marshaler); ok {
-			v, err := m.MarshalYAML()
-			if err != nil {
-				return nil, xerrors.Errorf(
-					"marshal %q: %w", opt.Name, err,
-				)
-			}
-			valueNode, ok = v.(yaml.Node)
-			if !ok {
-				return nil, xerrors.Errorf(
-					"marshal %q: unexpected underlying type %T",
-					opt.Name, v,
-				)
-			}
-		} else {
-			// The all-other types case.
-			//
-			// A bit of a hack, we marshal and then unmarshal to get
-			// the underlying node.
-			byt, err := yaml.Marshal(opt.Value)
-			if err != nil {
-				return nil, xerrors.Errorf(
-					"marshal %q: %w", opt.Name, err,
-				)
-			}
-
-			var docNode yaml.Node
-			err = yaml.Unmarshal(byt, &docNode)
-			if err != nil {
-				return nil, xerrors.Errorf(
-					"unmarshal %q: %w", opt.Name, err,
-				)
-			}
-			if len(docNode.Content) != 1 {
-				return nil, xerrors.Errorf(
-					"unmarshal %q: expected one node, got %d",
-					opt.Name, len(docNode.Content),
-				)
-			}
-
-			valueNode = *docNode.Content[0]
-		}
-		var group []string
-		for _, g := range opt.Group.Ancestry() {
-			if g.YAML == "" {
-				return nil, xerrors.Errorf(
-					"group yaml name is empty for %q, groups: %+v",
-					opt.Name,
-					opt.Group,
-				)
-			}
-			group = append(group, g.YAML)
-		}
-		var groupDesc string
-		if opt.Group != nil {
-			groupDesc = wordwrap.WrapString(opt.Group.Description, 80)
-		}
-		parentValueNode := deepMapNode(
-			&root, group,
-			groupDesc,
-		)
-		parentValueNode.Content = append(
-			parentValueNode.Content,
-			&nameNode,
-			&valueNode,
-		)
-	}
-	return &root, nil
-}
-
-// mapYAMLNodes converts parent into a map with keys of form "group.subgroup.option"
-// and values as the corresponding YAML nodes.
-func mapYAMLNodes(parent *yaml.Node) (map[string]*yaml.Node, error) {
-	if parent.Kind != yaml.MappingNode {
-		return nil, xerrors.Errorf("expected mapping node, got type %v", parent.Kind)
-	}
-	if len(parent.Content)%2 != 0 {
-		return nil, xerrors.Errorf("expected an even number of k/v pairs, got %d", len(parent.Content))
-	}
-	var (
-		key  string
-		m    = make(map[string]*yaml.Node, len(parent.Content)/2)
-		merr error
-	)
-	for i, child := range parent.Content {
-		if i%2 == 0 {
-			if child.Kind != yaml.ScalarNode {
-				// We immediately because the rest of the code is bound to fail
-				// if we don't know to expect a key or a value.
-				return nil, xerrors.Errorf("expected scalar node for key, got type %v", child.Kind)
-			}
-			key = child.Value
-			continue
-		}
-
-		// We don't know if this is a grouped simple option or complex option,
-		// so we store both "key" and "group.key". Since we're storing pointers,
-		// the additional memory is of little concern.
-		m[key] = child
-		if child.Kind != yaml.MappingNode {
-			continue
-		}
-
-		sub, err := mapYAMLNodes(child)
-		if err != nil {
-			merr = errors.Join(merr, xerrors.Errorf("mapping node %q: %w", key, err))
-			continue
-		}
-		for k, v := range sub {
-			m[key+"."+k] = v
-		}
-	}
-
-	return m, nil
-}
-
-func (o *Option) setFromYAMLNode(n *yaml.Node) error {
-	o.ValueSource = ValueSourceYAML
-	if um, ok := o.Value.(yaml.Unmarshaler); ok {
-		return um.UnmarshalYAML(n)
-	}
-
-	switch n.Kind {
-	case yaml.ScalarNode:
-		return o.Value.Set(n.Value)
-	case yaml.SequenceNode:
-		// We treat empty values as nil for consistency with other option
-		// mechanisms.
-		if len(n.Content) == 0 {
-			o.Value = nil
-			return nil
-		}
-		return n.Decode(o.Value)
-	case yaml.MappingNode:
-		return xerrors.Errorf("mapping nodes must implement yaml.Unmarshaler")
-	default:
-		return xerrors.Errorf("unexpected node kind %v", n.Kind)
-	}
-}
-
-// UnmarshalYAML converts the given YAML node into the option set.
-// It is isomorphic with ToYAML.
-func (optSet *OptionSet) UnmarshalYAML(rootNode *yaml.Node) error {
-	// The rootNode will be a DocumentNode if it's read from a file. We do
-	// not support multiple documents in a single file.
-	if rootNode.Kind == yaml.DocumentNode {
-		if len(rootNode.Content) != 1 {
-			return xerrors.Errorf("expected one node in document, got %d", len(rootNode.Content))
-		}
-		rootNode = rootNode.Content[0]
-	}
-
-	yamlNodes, err := mapYAMLNodes(rootNode)
-	if err != nil {
-		return xerrors.Errorf("mapping nodes: %w", err)
-	}
-
-	matchedNodes := make(map[string]*yaml.Node, len(yamlNodes))
-
-	var merr error
-	for i := range *optSet {
-		opt := &(*optSet)[i]
-		if opt.YAML == "" {
-			continue
-		}
-		var group []string
-		for _, g := range opt.Group.Ancestry() {
-			if g.YAML == "" {
-				return xerrors.Errorf(
-					"group yaml name is empty for %q, groups: %+v",
-					opt.Name,
-					opt.Group,
-				)
-			}
-			group = append(group, g.YAML)
-			delete(yamlNodes, strings.Join(group, "."))
-		}
-
-		key := strings.Join(append(group, opt.YAML), ".")
-		node, ok := yamlNodes[key]
-		if !ok {
-			continue
-		}
-
-		matchedNodes[key] = node
-		if opt.ValueSource != ValueSourceNone {
-			continue
-		}
-		if err := opt.setFromYAMLNode(node); err != nil {
-			merr = errors.Join(merr, xerrors.Errorf("setting %q: %w", opt.YAML, err))
-		}
-	}
-
-	// Remove all matched nodes and their descendants from yamlNodes so we
-	// can accurately report unknown options.
-	for k := range yamlNodes {
-		var key string
-		for _, part := range strings.Split(k, ".") {
-			if key != "" {
-				key += "."
-			}
-			key += part
-			if _, ok := matchedNodes[key]; ok {
-				delete(yamlNodes, k)
-			}
-		}
-	}
-	for k := range yamlNodes {
-		merr = errors.Join(merr, xerrors.Errorf("unknown option %q", k))
-	}
-
-	return merr
-}
@@ -1,202 +0,0 @@
-package clibase_test
-
-import (
-	"testing"
-
-	"github.com/spf13/pflag"
-	"github.com/stretchr/testify/require"
-	"golang.org/x/exp/slices"
-	"gopkg.in/yaml.v3"
-
-	"github.com/coder/coder/v2/cli/clibase"
-)
-
-func TestOptionSet_YAML(t *testing.T) {
-	t.Parallel()
-
-	t.Run("RequireKey", func(t *testing.T) {
-		t.Parallel()
-		var workspaceName clibase.String
-		os := clibase.OptionSet{
-			clibase.Option{
-				Name:    "Workspace Name",
-				Value:   &workspaceName,
-				Default: "billie",
-			},
-		}
-
-		node, err := os.MarshalYAML()
-		require.NoError(t, err)
-		require.Len(t, node.(*yaml.Node).Content, 0)
-	})
-
-	t.Run("SimpleString", func(t *testing.T) {
-		t.Parallel()
-
-		var workspaceName clibase.String
-
-		os := clibase.OptionSet{
-			clibase.Option{
-				Name:        "Workspace Name",
-				Value:       &workspaceName,
-				Default:     "billie",
-				Description: "The workspace's name.",
-				Group:       &clibase.Group{YAML: "names"},
-				YAML:        "workspaceName",
-			},
-		}
-
-		err := os.SetDefaults()
-		require.NoError(t, err)
-
-		n, err := os.MarshalYAML()
-		require.NoError(t, err)
-		// Visually inspect for now.
-		byt, err := yaml.Marshal(n)
-		require.NoError(t, err)
-		t.Logf("Raw YAML:\n%s", string(byt))
-	})
-}
-
-func TestOptionSet_YAMLUnknownOptions(t *testing.T) {
-	t.Parallel()
-	os := clibase.OptionSet{
-		{
-			Name:        "Workspace Name",
-			Default:     "billie",
-			Description: "The workspace's name.",
-			YAML:        "workspaceName",
-			Value:       new(clibase.String),
-		},
-	}
-
-	const yamlDoc = `something: else`
-	err := yaml.Unmarshal([]byte(yamlDoc), &os)
-	require.Error(t, err)
-	require.Empty(t, os[0].Value.String())
-
-	os[0].YAML = "something"
-
-	err = yaml.Unmarshal([]byte(yamlDoc), &os)
-	require.NoError(t, err)
-
-	require.Equal(t, "else", os[0].Value.String())
-}
-
-// TestOptionSet_YAMLIsomorphism tests that the YAML representations of an
-// OptionSet converts to the same OptionSet when read back in.
-func TestOptionSet_YAMLIsomorphism(t *testing.T) {
-	t.Parallel()
-	// This is used to form a generic.
-	//nolint:unused
-	type kid struct {
-		Name string `yaml:"name"`
-		Age  int    `yaml:"age"`
-	}
-
-	for _, tc := range []struct {
-		name      string
-		os        clibase.OptionSet
-		zeroValue func() pflag.Value
-	}{
-		{
-			name: "SimpleString",
-			os: clibase.OptionSet{
-				{
-					Name:        "Workspace Name",
-					Default:     "billie",
-					Description: "The workspace's name.",
-					Group:       &clibase.Group{YAML: "names"},
-					YAML:        "workspaceName",
-				},
-			},
-			zeroValue: func() pflag.Value {
-				return clibase.StringOf(new(string))
-			},
-		},
-		{
-			name: "Array",
-			os: clibase.OptionSet{
-				{
-					YAML:    "names",
-					Default: "jill,jack,joan",
-				},
-			},
-			zeroValue: func() pflag.Value {
-				return clibase.StringArrayOf(&[]string{})
-			},
-		},
-		{
-			name: "ComplexObject",
-			os: clibase.OptionSet{
-				{
-					YAML: "kids",
-					Default: `- name: jill
-  age: 12
- name: jack
-  age: 13`,
-				},
-			},
-			zeroValue: func() pflag.Value {
-				return &clibase.Struct[[]kid]{}
-			},
-		},
-		{
-			name: "DeepGroup",
-			os: clibase.OptionSet{
-				{
-					YAML:    "names",
-					Default: "jill,jack,joan",
-					Group:   &clibase.Group{YAML: "kids", Parent: &clibase.Group{YAML: "family"}},
-				},
-			},
-			zeroValue: func() pflag.Value {
-				return clibase.StringArrayOf(&[]string{})
-			},
-		},
-	} {
-		tc := tc
-		t.Run(tc.name, func(t *testing.T) {
-			t.Parallel()
-
-			// Set initial values.
-			for i := range tc.os {
-				tc.os[i].Value = tc.zeroValue()
-			}
-			err := tc.os.SetDefaults()
-			require.NoError(t, err)
-
-			y, err := tc.os.MarshalYAML()
-			require.NoError(t, err)
-
-			toByt, err := yaml.Marshal(y)
-			require.NoError(t, err)
-
-			t.Logf("Raw YAML:\n%s", string(toByt))
-
-			var y2 yaml.Node
-			err = yaml.Unmarshal(toByt, &y2)
-			require.NoError(t, err)
-
-			os2 := slices.Clone(tc.os)
-			for i := range os2 {
-				os2[i].Value = tc.zeroValue()
-				os2[i].ValueSource = clibase.ValueSourceNone
-			}
-
-			// os2 values should be zeroed whereas tc.os should be
-			// set to defaults.
-			// This check makes sure we aren't mixing pointers.
-			require.NotEqual(t, tc.os, os2)
-			err = os2.UnmarshalYAML(&y2)
-			require.NoError(t, err)
-
-			want := tc.os
-			for i := range want {
-				want[i].ValueSource = clibase.ValueSourceYAML
-			}
-
-			require.Equal(t, tc.os, os2)
-		})
-	}
-}
@@ -0,0 +1,211 @@
+package clilog
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"regexp"
+	"strings"
+
+	"golang.org/x/xerrors"
+
+	"cdr.dev/slog"
+	"cdr.dev/slog/sloggers/sloghuman"
+	"cdr.dev/slog/sloggers/slogjson"
+	"cdr.dev/slog/sloggers/slogstackdriver"
+	"github.com/coder/coder/v2/coderd/tracing"
+	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/serpent"
+)
+
+type (
+	Option  func(*Builder)
+	Builder struct {
+		Filter      []string
+		Human       string
+		JSON        string
+		Stackdriver string
+		Trace       bool
+		Verbose     bool
+	}
+)
+
+func New(opts ...Option) *Builder {
+	b := &Builder{}
+	for _, opt := range opts {
+		opt(b)
+	}
+	return b
+}
+
+func WithFilter(filters ...string) Option {
+	return func(b *Builder) {
+		b.Filter = filters
+	}
+}
+
+func WithHuman(loc string) Option {
+	return func(b *Builder) {
+		b.Human = loc
+	}
+}
+
+func WithJSON(loc string) Option {
+	return func(b *Builder) {
+		b.JSON = loc
+	}
+}
+
+func WithStackdriver(loc string) Option {
+	return func(b *Builder) {
+		b.Stackdriver = loc
+	}
+}
+
+func WithTrace() Option {
+	return func(b *Builder) {
+		b.Trace = true
+	}
+}
+
+func WithVerbose() Option {
+	return func(b *Builder) {
+		b.Verbose = true
+	}
+}
+
+func FromDeploymentValues(vals *codersdk.DeploymentValues) Option {
+	return func(b *Builder) {
+		b.Filter = vals.Logging.Filter.Value()
+		b.Human = vals.Logging.Human.Value()
+		b.JSON = vals.Logging.JSON.Value()
+		b.Stackdriver = vals.Logging.Stackdriver.Value()
+		b.Trace = vals.Trace.Enable.Value()
+		b.Verbose = vals.Verbose.Value()
+	}
+}
+
+func (b *Builder) Build(inv *serpent.Invocation) (log slog.Logger, closeLog func(), err error) {
+	var (
+		sinks   = []slog.Sink{}
+		closers = []func() error{}
+	)
+	defer func() {
+		if err != nil {
+			for _, closer := range closers {
+				_ = closer()
+			}
+		}
+	}()
+
+	noopClose := func() {}
+
+	addSinkIfProvided := func(sinkFn func(io.Writer) slog.Sink, loc string) error {
+		switch loc {
+		case "":
+
+		case "/dev/stdout":
+			sinks = append(sinks, sinkFn(inv.Stdout))
+
+		case "/dev/stderr":
+			sinks = append(sinks, sinkFn(inv.Stderr))
+
+		default:
+			fi, err := os.OpenFile(loc, os.O_WRONLY|os.O_CREATE|os.O_APPEND, 0o644)
+			if err != nil {
+				return xerrors.Errorf("open log file %q: %w", loc, err)
+			}
+			closers = append(closers, fi.Close)
+			sinks = append(sinks, sinkFn(fi))
+		}
+		return nil
+	}
+
+	err = addSinkIfProvided(sloghuman.Sink, b.Human)
+	if err != nil {
+		return slog.Logger{}, noopClose, xerrors.Errorf("add human sink: %w", err)
+	}
+	err = addSinkIfProvided(slogjson.Sink, b.JSON)
+	if err != nil {
+		return slog.Logger{}, noopClose, xerrors.Errorf("add json sink: %w", err)
+	}
+	err = addSinkIfProvided(slogstackdriver.Sink, b.Stackdriver)
+	if err != nil {
+		return slog.Logger{}, noopClose, xerrors.Errorf("add stackdriver sink: %w", err)
+	}
+
+	if b.Trace {
+		sinks = append(sinks, tracing.SlogSink{})
+	}
+
+	// User should log to null device if they don't want logs.
+	if len(sinks) == 0 {
+		return slog.Logger{}, noopClose, xerrors.New("no loggers provided, use /dev/null to disable logging")
+	}
+
+	filter := &debugFilterSink{next: sinks}
+
+	err = filter.compile(b.Filter)
+	if err != nil {
+		return slog.Logger{}, noopClose, xerrors.Errorf("compile filters: %w", err)
+	}
+
+	level := slog.LevelInfo
+	// Debug logging is always enabled if a filter is present.
+	if b.Verbose || filter.re != nil {
+		level = slog.LevelDebug
+	}
+
+	return inv.Logger.AppendSinks(filter).Leveled(level), func() {
+		for _, closer := range closers {
+			_ = closer()
+		}
+	}, nil
+}
+
+var _ slog.Sink = &debugFilterSink{}
+
+type debugFilterSink struct {
+	next []slog.Sink
+	re   *regexp.Regexp
+}
+
+func (f *debugFilterSink) compile(res []string) error {
+	if len(res) == 0 {
+		return nil
+	}
+
+	var reb strings.Builder
+	for i, re := range res {
+		_, _ = fmt.Fprintf(&reb, "(%s)", re)
+		if i != len(res)-1 {
+			_, _ = reb.WriteRune('|')
+		}
+	}
+
+	re, err := regexp.Compile(reb.String())
+	if err != nil {
+		return xerrors.Errorf("compile regex: %w", err)
+	}
+	f.re = re
+	return nil
+}
+
+func (f *debugFilterSink) LogEntry(ctx context.Context, ent slog.SinkEntry) {
+	if ent.Level == slog.LevelDebug {
+		logName := strings.Join(ent.LoggerNames, ".")
+		if f.re != nil && !f.re.MatchString(logName) && !f.re.MatchString(ent.Message) {
+			return
+		}
+	}
+	for _, sink := range f.next {
+		sink.LogEntry(ctx, ent)
+	}
+}
+
+func (f *debugFilterSink) Sync() {
+	for _, sink := range f.next {
+		sink.Sync()
+	}
+}
@@ -0,0 +1,243 @@
+package clilog_test
+
+import (
+	"encoding/json"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/coder/coder/v2/cli/clilog"
+	"github.com/coder/coder/v2/coderd/coderdtest"
+	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/serpent"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestBuilder(t *testing.T) {
+	t.Parallel()
+
+	t.Run("NoConfiguration", func(t *testing.T) {
+		t.Parallel()
+
+		cmd := &serpent.Command{
+			Use:     "test",
+			Handler: testHandler(t),
+		}
+		err := cmd.Invoke().Run()
+		require.ErrorContains(t, err, "no loggers provided, use /dev/null to disable logging")
+	})
+
+	t.Run("Verbose", func(t *testing.T) {
+		t.Parallel()
+
+		tempFile := filepath.Join(t.TempDir(), "test.log")
+		cmd := &serpent.Command{
+			Use: "test",
+			Handler: testHandler(t,
+				clilog.WithHuman(tempFile),
+				clilog.WithVerbose(),
+			),
+		}
+		err := cmd.Invoke().Run()
+		require.NoError(t, err)
+		assertLogs(t, tempFile, debugLog, infoLog, warnLog, filterLog)
+	})
+
+	t.Run("WithFilter", func(t *testing.T) {
+		t.Parallel()
+
+		tempFile := filepath.Join(t.TempDir(), "test.log")
+		cmd := &serpent.Command{
+			Use: "test",
+			Handler: testHandler(t,
+				clilog.WithHuman(tempFile),
+				// clilog.WithVerbose(), // implicit
+				clilog.WithFilter("important debug message"),
+			),
+		}
+		err := cmd.Invoke().Run()
+		require.NoError(t, err)
+		assertLogs(t, tempFile, infoLog, warnLog, filterLog)
+	})
+
+	t.Run("WithHuman", func(t *testing.T) {
+		t.Parallel()
+
+		tempFile := filepath.Join(t.TempDir(), "test.log")
+		cmd := &serpent.Command{
+			Use:     "test",
+			Handler: testHandler(t, clilog.WithHuman(tempFile)),
+		}
+		err := cmd.Invoke().Run()
+		require.NoError(t, err)
+		assertLogs(t, tempFile, infoLog, warnLog)
+	})
+
+	t.Run("WithJSON", func(t *testing.T) {
+		t.Parallel()
+
+		tempFile := filepath.Join(t.TempDir(), "test.log")
+		cmd := &serpent.Command{
+			Use:     "test",
+			Handler: testHandler(t, clilog.WithJSON(tempFile), clilog.WithVerbose()),
+		}
+		err := cmd.Invoke().Run()
+		require.NoError(t, err)
+		assertLogsJSON(t, tempFile, debug, debugLog, info, infoLog, warn, warnLog, debug, filterLog)
+	})
+
+	t.Run("FromDeploymentValues", func(t *testing.T) {
+		t.Parallel()
+
+		t.Run("Defaults", func(t *testing.T) {
+			stdoutPath := filepath.Join(t.TempDir(), "stdout")
+			stderrPath := filepath.Join(t.TempDir(), "stderr")
+
+			stdout, err := os.OpenFile(stdoutPath, os.O_WRONLY|os.O_CREATE|os.O_APPEND, 0o644)
+			require.NoError(t, err)
+			t.Cleanup(func() { _ = stdout.Close() })
+
+			stderr, err := os.OpenFile(stderrPath, os.O_WRONLY|os.O_CREATE|os.O_APPEND, 0o644)
+			require.NoError(t, err)
+			t.Cleanup(func() { _ = stderr.Close() })
+
+			// Use the default deployment values.
+			dv := coderdtest.DeploymentValues(t)
+			cmd := &serpent.Command{
+				Use:     "test",
+				Handler: testHandler(t, clilog.FromDeploymentValues(dv)),
+			}
+			inv := cmd.Invoke()
+			inv.Stdout = stdout
+			inv.Stderr = stderr
+			err = inv.Run()
+			require.NoError(t, err)
+
+			assertLogs(t, stdoutPath, "")
+			assertLogs(t, stderrPath, infoLog, warnLog)
+		})
+
+		t.Run("Override", func(t *testing.T) {
+			tempFile := filepath.Join(t.TempDir(), "test.log")
+			tempJSON := filepath.Join(t.TempDir(), "test.json")
+			dv := &codersdk.DeploymentValues{
+				Logging: codersdk.LoggingConfig{
+					Filter: []string{"foo", "baz"},
+					Human:  serpent.String(tempFile),
+					JSON:   serpent.String(tempJSON),
+				},
+				Verbose: true,
+				Trace: codersdk.TraceConfig{
+					Enable: true,
+				},
+			}
+			cmd := &serpent.Command{
+				Use:     "test",
+				Handler: testHandler(t, clilog.FromDeploymentValues(dv)),
+			}
+			err := cmd.Invoke().Run()
+			require.NoError(t, err)
+			assertLogs(t, tempFile, infoLog, warnLog)
+			assertLogsJSON(t, tempJSON, info, infoLog, warn, warnLog)
+		})
+	})
+
+	t.Run("NotFound", func(t *testing.T) {
+		t.Parallel()
+
+		tempFile := filepath.Join(t.TempDir(), "doesnotexist", "test.log")
+		cmd := &serpent.Command{
+			Use: "test",
+			Handler: func(inv *serpent.Invocation) error {
+				logger, closeLog, err := clilog.New(
+					clilog.WithFilter("foo", "baz"),
+					clilog.WithHuman(tempFile),
+					clilog.WithVerbose(),
+				).Build(inv)
+				if err != nil {
+					return err
+				}
+				defer closeLog()
+				logger.Error(inv.Context(), "you will never see this")
+				return nil
+			},
+		}
+		err := cmd.Invoke().Run()
+		require.ErrorIs(t, err, fs.ErrNotExist)
+	})
+}
+
+var (
+	debug     = "DEBUG"
+	info      = "INFO"
+	warn      = "WARN"
+	debugLog  = "this is a debug message"
+	infoLog   = "this is an info message"
+	warnLog   = "this is a warning message"
+	filterLog = "this is an important debug message you want to see"
+)
+
+func testHandler(t testing.TB, opts ...clilog.Option) serpent.HandlerFunc {
+	t.Helper()
+
+	return func(inv *serpent.Invocation) error {
+		logger, closeLog, err := clilog.New(opts...).Build(inv)
+		if err != nil {
+			return err
+		}
+		defer closeLog()
+		logger.Debug(inv.Context(), debugLog)
+		logger.Info(inv.Context(), infoLog)
+		logger.Warn(inv.Context(), warnLog)
+		logger.Debug(inv.Context(), filterLog)
+		return nil
+	}
+}
+
+func assertLogs(t testing.TB, path string, expected ...string) {
+	t.Helper()
+
+	data, err := os.ReadFile(path)
+	require.NoError(t, err)
+
+	logs := strings.Split(strings.TrimSpace(string(data)), "\n")
+	if !assert.Len(t, logs, len(expected)) {
+		t.Logf(string(data))
+		t.FailNow()
+	}
+	for i, log := range logs {
+		require.Contains(t, log, expected[i])
+	}
+}
+
+func assertLogsJSON(t testing.TB, path string, levelExpected ...string) {
+	t.Helper()
+
+	data, err := os.ReadFile(path)
+	require.NoError(t, err)
+
+	if len(levelExpected)%2 != 0 {
+		t.Errorf("levelExpected must be a list of level-message pairs")
+		return
+	}
+
+	logs := strings.Split(strings.TrimSpace(string(data)), "\n")
+	if !assert.Len(t, logs, len(levelExpected)/2) {
+		t.Logf(string(data))
+		t.FailNow()
+	}
+	for i, log := range logs {
+		var entry struct {
+			Level   string `json:"level"`
+			Message string `json:"msg"`
+		}
+		err := json.NewDecoder(strings.NewReader(log)).Decode(&entry)
+		require.NoError(t, err)
+		require.Equal(t, levelExpected[2*i], entry.Level)
+		require.Equal(t, levelExpected[2*i+1], entry.Message)
+	}
+}
@@ -0,0 +1,2 @@
+// Package clilog provides a fluent API for configuring structured logging.
+package clilog
@@ -20,16 +20,16 @@ import (
 	"cdr.dev/slog"
 	"cdr.dev/slog/sloggers/slogtest"
 	"github.com/coder/coder/v2/cli"
-	"github.com/coder/coder/v2/cli/clibase"
 	"github.com/coder/coder/v2/cli/config"
 	"github.com/coder/coder/v2/codersdk"
 	"github.com/coder/coder/v2/provisioner/echo"
 	"github.com/coder/coder/v2/testutil"
+	"github.com/coder/serpent"
 )

 // New creates a CLI instance with a configuration pointed to a
 // temporary testing directory.
-func New(t testing.TB, args ...string) (*clibase.Invocation, config.Root) {
+func New(t testing.TB, args ...string) (*serpent.Invocation, config.Root) {
 	var root cli.RootCmd

 	cmd, err := root.Command(root.AGPL())
@@ -56,15 +56,15 @@ func (l *logWriter) Write(p []byte) (n int, err error) {
 }

 func NewWithCommand(
-	t testing.TB, cmd *clibase.Cmd, args ...string,
-) (*clibase.Invocation, config.Root) {
+	t testing.TB, cmd *serpent.Command, args ...string,
+) (*serpent.Invocation, config.Root) {
 	configDir := config.Root(t.TempDir())
 	// I really would like to fail test on error logs, but realistically, turning on by default
 	// in all our CLI tests is going to create a lot of flaky noise.
 	logger := slogtest.Make(t, &slogtest.Options{IgnoreErrors: true}).
 		Leveled(slog.LevelDebug).
 		Named("cli")
-	i := &clibase.Invocation{
+	i := &serpent.Invocation{
 		Command: cmd,
 		Args:    append([]string{"--global-config", string(configDir)}, args...),
 		Stdin:   io.LimitReader(nil, 0),
@@ -140,7 +140,11 @@ func extractTar(t *testing.T, data []byte, directory string) {

 // Start runs the command in a goroutine and cleans it up when the test
 // completed.
-func Start(t *testing.T, inv *clibase.Invocation) {
+func Start(t *testing.T, inv *serpent.Invocation) {
+	StartWithAssert(t, inv, nil)
+}
+
+func StartWithAssert(t *testing.T, inv *serpent.Invocation, assertCallback func(t *testing.T, err error)) { //nolint:revive
 	t.Helper()

 	closeCh := make(chan struct{})
@@ -155,6 +159,12 @@ func Start(t *testing.T, inv *clibase.Invocation) {
 	go func() {
 		defer close(closeCh)
 		err := waiter.Wait()
+
+		if assertCallback != nil {
+			assertCallback(t, err)
+			return
+		}
+
 		switch {
 		case errors.Is(err, context.Canceled):
 			return
@@ -165,7 +175,7 @@ func Start(t *testing.T, inv *clibase.Invocation) {
 }

 // Run runs the command and asserts that there is no error.
-func Run(t *testing.T, inv *clibase.Invocation) {
+func Run(t *testing.T, inv *serpent.Invocation) {
 	t.Helper()

 	err := inv.Run()
@@ -218,7 +228,7 @@ func (w *ErrorWaiter) RequireAs(want interface{}) {

 // StartWithWaiter runs the command in a goroutine but returns the error instead
 // of asserting it. This is useful for testing error cases.
-func StartWithWaiter(t *testing.T, inv *clibase.Invocation) *ErrorWaiter {
+func StartWithWaiter(t *testing.T, inv *serpent.Invocation) *ErrorWaiter {
 	t.Helper()

 	var (
@@ -13,12 +13,12 @@ import (

 	"github.com/stretchr/testify/require"

-	"github.com/coder/coder/v2/cli/clibase"
 	"github.com/coder/coder/v2/cli/config"
 	"github.com/coder/coder/v2/coderd/coderdtest"
 	"github.com/coder/coder/v2/coderd/database/dbtestutil"
 	"github.com/coder/coder/v2/codersdk"
 	"github.com/coder/coder/v2/testutil"
+	"github.com/coder/serpent"
 )

 // UpdateGoldenFiles indicates golden files should be updated.
@@ -48,7 +48,7 @@ func DefaultCases() []CommandHelpCase {

 // TestCommandHelp will test the help output of the given commands
 // using golden files.
-func TestCommandHelp(t *testing.T, getRoot func(t *testing.T) *clibase.Cmd, cases []CommandHelpCase) {
+func TestCommandHelp(t *testing.T, getRoot func(t *testing.T) *serpent.Command, cases []CommandHelpCase) {
 	t.Parallel()
 	rootClient, replacements := prepareTestData(t)

@@ -87,40 +87,45 @@ ExtractCommandPathsLoop:

 			StartWithWaiter(t, inv.WithContext(ctx)).RequireSuccess()

-			actual := outBuf.Bytes()
-			if len(actual) == 0 {
-				t.Fatal("no output")
-			}
-
-			for k, v := range replacements {
-				actual = bytes.ReplaceAll(actual, []byte(k), []byte(v))
-			}
-
-			actual = NormalizeGoldenFile(t, actual)
-			goldenPath := filepath.Join("testdata", strings.Replace(tt.Name, " ", "_", -1)+".golden")
-			if *UpdateGoldenFiles {
-				t.Logf("update golden file for: %q: %s", tt.Name, goldenPath)
-				err := os.WriteFile(goldenPath, actual, 0o600)
-				require.NoError(t, err, "update golden file")
-			}
-
-			expected, err := os.ReadFile(goldenPath)
-			require.NoError(t, err, "read golden file, run \"make update-golden-files\" and commit the changes")
-
-			expected = NormalizeGoldenFile(t, expected)
-			require.Equal(
-				t, string(expected), string(actual),
-				"golden file mismatch: %s, run \"make update-golden-files\", verify and commit the changes",
-				goldenPath,
-			)
+			TestGoldenFile(t, tt.Name, outBuf.Bytes(), replacements)
 		})
 	}
 }

-// NormalizeGoldenFile replaces any strings that are system or timing dependent
+// TestGoldenFile will test the given bytes slice input against the
+// golden file with the given file name, optionally using the given replacements.
+func TestGoldenFile(t *testing.T, fileName string, actual []byte, replacements map[string]string) {
+	if len(actual) == 0 {
+		t.Fatal("no output")
+	}
+
+	for k, v := range replacements {
+		actual = bytes.ReplaceAll(actual, []byte(k), []byte(v))
+	}
+
+	actual = normalizeGoldenFile(t, actual)
+	goldenPath := filepath.Join("testdata", strings.ReplaceAll(fileName, " ", "_")+".golden")
+	if *UpdateGoldenFiles {
+		t.Logf("update golden file for: %q: %s", fileName, goldenPath)
+		err := os.WriteFile(goldenPath, actual, 0o600)
+		require.NoError(t, err, "update golden file")
+	}
+
+	expected, err := os.ReadFile(goldenPath)
+	require.NoError(t, err, "read golden file, run \"make update-golden-files\" and commit the changes")
+
+	expected = normalizeGoldenFile(t, expected)
+	require.Equal(
+		t, string(expected), string(actual),
+		"golden file mismatch: %s, run \"make update-golden-files\", verify and commit the changes",
+		goldenPath,
+	)
+}
+
+// normalizeGoldenFile replaces any strings that are system or timing dependent
 // with a placeholder so that the golden files can be compared with a simple
 // equality check.
-func NormalizeGoldenFile(t *testing.T, byt []byte) []byte {
+func normalizeGoldenFile(t *testing.T, byt []byte) []byte {
 	// Replace any timestamps with a placeholder.
 	byt = timestampRegex.ReplaceAll(byt, []byte("[timestamp]"))

@@ -148,7 +153,7 @@ func NormalizeGoldenFile(t *testing.T, byt []byte) []byte {
 	return byt
 }

-func extractVisibleCommandPaths(cmdPath []string, cmds []*clibase.Cmd) [][]string {
+func extractVisibleCommandPaths(cmdPath []string, cmds []*serpent.Command) [][]string {
 	var cmdPaths [][]string
 	for _, c := range cmds {
 		if c.Hidden {
@@ -167,7 +172,11 @@ func prepareTestData(t *testing.T) (*codersdk.Client, map[string]string) {
 	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
 	defer cancel()

-	db, pubsub := dbtestutil.NewDB(t)
+	// This needs to be a fixed timezone because timezones increase the length
+	// of timestamp strings. The increased length can pad table formatting's
+	// and differ the table header spacings.
+	//nolint:gocritic
+	db, pubsub := dbtestutil.NewDB(t, dbtestutil.WithTimezone("UTC"))
 	rootClient := coderdtest.New(t, &coderdtest.Options{
 		Database:                 db,
 		Pubsub:                   pubsub,
@@ -3,7 +3,7 @@ package clitest
 import (
 	"testing"

-	"github.com/coder/coder/v2/cli/clibase"
+	"github.com/coder/serpent"
 )

 // HandlersOK asserts that all commands have a handler.
@@ -11,11 +11,11 @@ import (
 // non-root commands (like 'groups' or 'users'), a handler is required.
 // These handlers are likely just the 'help' handler, but this must be
 // explicitly set.
-func HandlersOK(t *testing.T, cmd *clibase.Cmd) {
-	cmd.Walk(func(cmd *clibase.Cmd) {
+func HandlersOK(t *testing.T, cmd *serpent.Command) {
+	cmd.Walk(func(cmd *serpent.Command) {
 		if cmd.Handler == nil {
 			// If you see this error, make the Handler a helper invoker.
-			//   Handler: func(inv *clibase.Invocation) error {
+			//   Handler: func(inv *serpent.Invocation) error {
 			//	   return inv.Command.HelpHandler(inv)
 			//	 },
 			t.Errorf("command %q has no handler, change to a helper invoker using: 'inv.Command.HelpHandler(inv)'", cmd.Name())
@@ -2,13 +2,17 @@ package cliui

 import (
 	"context"
+	"fmt"
 	"io"
+	"strconv"
+	"strings"
 	"time"

 	"github.com/google/uuid"
 	"golang.org/x/xerrors"

 	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/coder/v2/tailnet"
 )

 var errAgentShuttingDown = xerrors.New("agent is shutting down")
@@ -200,28 +204,28 @@ func Agent(ctx context.Context, writer io.Writer, agentID uuid.UUID, opts AgentO

 			switch agent.LifecycleState {
 			case codersdk.WorkspaceAgentLifecycleReady:
-				sw.Complete(stage, agent.ReadyAt.Sub(*agent.StartedAt))
+				sw.Complete(stage, safeDuration(sw, agent.ReadyAt, agent.StartedAt))
 			case codersdk.WorkspaceAgentLifecycleStartTimeout:
 				sw.Fail(stage, 0)
 				sw.Log(time.Time{}, codersdk.LogLevelWarn, "Warning: A startup script timed out and your workspace may be incomplete.")
 			case codersdk.WorkspaceAgentLifecycleStartError:
-				sw.Fail(stage, agent.ReadyAt.Sub(*agent.StartedAt))
+				sw.Fail(stage, safeDuration(sw, agent.ReadyAt, agent.StartedAt))
 				// Use zero time (omitted) to separate these from the startup logs.
 				sw.Log(time.Time{}, codersdk.LogLevelWarn, "Warning: A startup script exited with an error and your workspace may be incomplete.")
-				sw.Log(time.Time{}, codersdk.LogLevelWarn, troubleshootingMessage(agent, "https://coder.com/docs/v2/latest/templates#startup-script-exited-with-an-error"))
+				sw.Log(time.Time{}, codersdk.LogLevelWarn, troubleshootingMessage(agent, "https://coder.com/docs/v2/latest/templates/troubleshooting#startup-script-exited-with-an-error"))
 			default:
 				switch {
 				case agent.LifecycleState.Starting():
 					// Use zero time (omitted) to separate these from the startup logs.
 					sw.Log(time.Time{}, codersdk.LogLevelWarn, "Notice: The startup scripts are still running and your workspace may be incomplete.")
-					sw.Log(time.Time{}, codersdk.LogLevelWarn, troubleshootingMessage(agent, "https://coder.com/docs/v2/latest/templates#your-workspace-may-be-incomplete"))
+					sw.Log(time.Time{}, codersdk.LogLevelWarn, troubleshootingMessage(agent, "https://coder.com/docs/v2/latest/templates/troubleshooting#your-workspace-may-be-incomplete"))
 					// Note: We don't complete or fail the stage here, it's
 					// intentionally left open to indicate this stage didn't
 					// complete.
 				case agent.LifecycleState.ShuttingDown():
 					// We no longer know if the startup script failed or not,
 					// but we need to tell the user something.
-					sw.Complete(stage, agent.ReadyAt.Sub(*agent.StartedAt))
+					sw.Complete(stage, safeDuration(sw, agent.ReadyAt, agent.StartedAt))
 					return errAgentShuttingDown
 				}
 			}
@@ -236,15 +240,15 @@ func Agent(ctx context.Context, writer io.Writer, agentID uuid.UUID, opts AgentO
 			stage := "The workspace agent lost connection"
 			sw.Start(stage)
 			sw.Log(time.Now(), codersdk.LogLevelWarn, "Wait for it to reconnect or restart your workspace.")
-			sw.Log(time.Now(), codersdk.LogLevelWarn, troubleshootingMessage(agent, "https://coder.com/docs/v2/latest/templates#agent-connection-issues"))
+			sw.Log(time.Now(), codersdk.LogLevelWarn, troubleshootingMessage(agent, "https://coder.com/docs/v2/latest/templates/troubleshooting#agent-connection-issues"))

-			disconnectedAt := *agent.DisconnectedAt
+			disconnectedAt := agent.DisconnectedAt
 			for agent.Status == codersdk.WorkspaceAgentDisconnected {
 				if agent, err = fetch(); err != nil {
 					return xerrors.Errorf("fetch: %w", err)
 				}
 			}
-			sw.Complete(stage, agent.LastConnectedAt.Sub(disconnectedAt))
+			sw.Complete(stage, safeDuration(sw, agent.LastConnectedAt, disconnectedAt))
 		}
 	}
 }
@@ -257,8 +261,79 @@ func troubleshootingMessage(agent codersdk.WorkspaceAgent, url string) string {
 	return m
 }

+// safeDuration returns a-b. If a or b is nil, it returns 0.
+// This is because we often dereference a time pointer, which can
+// cause a panic. These dereferences are used to calculate durations,
+// which are not critical, and therefor should not break things
+// when it fails.
+// A panic has been observed in a test.
+func safeDuration(sw *stageWriter, a, b *time.Time) time.Duration {
+	if a == nil || b == nil {
+		if sw != nil {
+			// Ideally the message includes which fields are <nil>, but you can
+			// use the surrounding log lines to figure that out. And passing more
+			// params makes this unwieldy.
+			sw.Log(time.Now(), codersdk.LogLevelWarn, "Warning: Failed to calculate duration from a time being <nil>.")
+		}
+		return 0
+	}
+	return a.Sub(*b)
+}
+
 type closeFunc func() error

 func (c closeFunc) Close() error {
 	return c()
 }
+
+func PeerDiagnostics(w io.Writer, d tailnet.PeerDiagnostics) {
+	if d.PreferredDERP > 0 {
+		rn, ok := d.DERPRegionNames[d.PreferredDERP]
+		if !ok {
+			rn = "unknown"
+		}
+		_, _ = fmt.Fprintf(w, "✔ preferred DERP region: %d (%s)\n", d.PreferredDERP, rn)
+	} else {
+		_, _ = fmt.Fprint(w, "✘ not connected to DERP\n")
+	}
+	if d.SentNode {
+		_, _ = fmt.Fprint(w, "✔ sent local data to Coder networking coodinator\n")
+	} else {
+		_, _ = fmt.Fprint(w, "✘ have not sent local data to Coder networking coordinator\n")
+	}
+	if d.ReceivedNode != nil {
+		dp := d.ReceivedNode.DERP
+		dn := ""
+		// should be 127.3.3.40:N where N is the DERP region
+		ap := strings.Split(dp, ":")
+		if len(ap) == 2 {
+			dp = ap[1]
+			di, err := strconv.Atoi(dp)
+			if err == nil {
+				var ok bool
+				dn, ok = d.DERPRegionNames[di]
+				if ok {
+					dn = fmt.Sprintf("(%s)", dn)
+				} else {
+					dn = "(unknown)"
+				}
+			}
+		}
+		_, _ = fmt.Fprintf(w,
+			"✔ received remote agent data from Coder networking coordinator\n    preferred DERP region: %s %s\n    endpoints: %s\n",
+			dp, dn, strings.Join(d.ReceivedNode.Endpoints, ", "))
+	} else {
+		_, _ = fmt.Fprint(w, "✘ have not received remote agent data from Coder networking coordinator\n")
+	}
+	if !d.LastWireguardHandshake.IsZero() {
+		ago := time.Since(d.LastWireguardHandshake)
+		symbol := "✔"
+		// wireguard is supposed to refresh handshake on 5 minute intervals
+		if ago > 5*time.Minute {
+			symbol = "⚠"
+		}
+		_, _ = fmt.Fprintf(w, "%s Wireguard handshake %s ago\n", symbol, ago.Round(time.Second))
+	} else {
+		_, _ = fmt.Fprint(w, "✘ Wireguard is not connected\n")
+	}
+}
@@ -6,6 +6,7 @@ import (
 	"context"
 	"io"
 	"os"
+	"regexp"
 	"strings"
 	"sync/atomic"
 	"testing"
@@ -15,13 +16,15 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"golang.org/x/xerrors"
+	"tailscale.com/tailcfg"

-	"github.com/coder/coder/v2/cli/clibase"
 	"github.com/coder/coder/v2/cli/clitest"
 	"github.com/coder/coder/v2/cli/cliui"
 	"github.com/coder/coder/v2/coderd/util/ptr"
 	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/coder/v2/tailnet"
 	"github.com/coder/coder/v2/testutil"
+	"github.com/coder/serpent"
 )

 func TestAgent(t *testing.T) {
@@ -379,8 +382,8 @@ func TestAgent(t *testing.T) {
 			output := make(chan string, 100) // Buffered to avoid blocking, overflow is discarded.
 			logs := make(chan []codersdk.WorkspaceAgentLog, 1)

-			cmd := &clibase.Cmd{
-				Handler: func(inv *clibase.Invocation) error {
+			cmd := &serpent.Command{
+				Handler: func(inv *serpent.Invocation) error {
 					tc.opts.Fetch = func(_ context.Context, _ uuid.UUID) (codersdk.WorkspaceAgent, error) {
 						t.Log("iter", len(tc.iter))
 						var err error
@@ -447,8 +450,8 @@ func TestAgent(t *testing.T) {
 		t.Parallel()
 		var fetchCalled uint64

-		cmd := &clibase.Cmd{
-			Handler: func(inv *clibase.Invocation) error {
+		cmd := &serpent.Command{
+			Handler: func(inv *serpent.Invocation) error {
 				buf := bytes.Buffer{}
 				err := cliui.Agent(inv.Context(), &buf, uuid.Nil, cliui.AgentOptions{
 					FetchInterval: 10 * time.Millisecond,
@@ -476,3 +479,191 @@ func TestAgent(t *testing.T) {
 		require.NoError(t, cmd.Invoke().Run())
 	})
 }
+
+func TestPeerDiagnostics(t *testing.T) {
+	t.Parallel()
+	testCases := []struct {
+		name  string
+		diags tailnet.PeerDiagnostics
+		want  []*regexp.Regexp // must be ordered, can omit lines
+	}{
+		{
+			name: "noPreferredDERP",
+			diags: tailnet.PeerDiagnostics{
+				PreferredDERP:          0,
+				DERPRegionNames:        make(map[int]string),
+				SentNode:               true,
+				ReceivedNode:           &tailcfg.Node{DERP: "127.3.3.40:999"},
+				LastWireguardHandshake: time.Now(),
+			},
+			want: []*regexp.Regexp{
+				regexp.MustCompile("^✘ not connected to DERP$"),
+			},
+		},
+		{
+			name: "preferredDERP",
+			diags: tailnet.PeerDiagnostics{
+				PreferredDERP: 23,
+				DERPRegionNames: map[int]string{
+					23: "testo",
+				},
+				SentNode:               true,
+				ReceivedNode:           &tailcfg.Node{DERP: "127.3.3.40:999"},
+				LastWireguardHandshake: time.Now(),
+			},
+			want: []*regexp.Regexp{
+				regexp.MustCompile(`^✔ preferred DERP region: 23 \(testo\)$`),
+			},
+		},
+		{
+			name: "sentNode",
+			diags: tailnet.PeerDiagnostics{
+				PreferredDERP:          0,
+				DERPRegionNames:        map[int]string{},
+				SentNode:               true,
+				ReceivedNode:           &tailcfg.Node{DERP: "127.3.3.40:999"},
+				LastWireguardHandshake: time.Time{},
+			},
+			want: []*regexp.Regexp{
+				regexp.MustCompile(`^✔ sent local data to Coder networking coodinator$`),
+			},
+		},
+		{
+			name: "didntSendNode",
+			diags: tailnet.PeerDiagnostics{
+				PreferredDERP:          0,
+				DERPRegionNames:        map[int]string{},
+				SentNode:               false,
+				ReceivedNode:           &tailcfg.Node{DERP: "127.3.3.40:999"},
+				LastWireguardHandshake: time.Time{},
+			},
+			want: []*regexp.Regexp{
+				regexp.MustCompile(`^✘ have not sent local data to Coder networking coordinator$`),
+			},
+		},
+		{
+			name: "receivedNodeDERPOKNoEndpoints",
+			diags: tailnet.PeerDiagnostics{
+				PreferredDERP:          0,
+				DERPRegionNames:        map[int]string{999: "Embedded"},
+				SentNode:               true,
+				ReceivedNode:           &tailcfg.Node{DERP: "127.3.3.40:999"},
+				LastWireguardHandshake: time.Time{},
+			},
+			want: []*regexp.Regexp{
+				regexp.MustCompile(`^✔ received remote agent data from Coder networking coordinator$`),
+				regexp.MustCompile(`preferred DERP region: 999 \(Embedded\)$`),
+				regexp.MustCompile(`endpoints: $`),
+			},
+		},
+		{
+			name: "receivedNodeDERPUnknownNoEndpoints",
+			diags: tailnet.PeerDiagnostics{
+				PreferredDERP:          0,
+				DERPRegionNames:        map[int]string{},
+				SentNode:               true,
+				ReceivedNode:           &tailcfg.Node{DERP: "127.3.3.40:999"},
+				LastWireguardHandshake: time.Time{},
+			},
+			want: []*regexp.Regexp{
+				regexp.MustCompile(`^✔ received remote agent data from Coder networking coordinator$`),
+				regexp.MustCompile(`preferred DERP region: 999 \(unknown\)$`),
+				regexp.MustCompile(`endpoints: $`),
+			},
+		},
+		{
+			name: "receivedNodeEndpointsNoDERP",
+			diags: tailnet.PeerDiagnostics{
+				PreferredDERP:          0,
+				DERPRegionNames:        map[int]string{999: "Embedded"},
+				SentNode:               true,
+				ReceivedNode:           &tailcfg.Node{Endpoints: []string{"99.88.77.66:4555", "33.22.11.0:3444"}},
+				LastWireguardHandshake: time.Time{},
+			},
+			want: []*regexp.Regexp{
+				regexp.MustCompile(`^✔ received remote agent data from Coder networking coordinator$`),
+				regexp.MustCompile(`preferred DERP region:\s*$`),
+				regexp.MustCompile(`endpoints: 99\.88\.77\.66:4555, 33\.22\.11\.0:3444$`),
+			},
+		},
+		{
+			name: "didntReceiveNode",
+			diags: tailnet.PeerDiagnostics{
+				PreferredDERP:          0,
+				DERPRegionNames:        map[int]string{},
+				SentNode:               false,
+				ReceivedNode:           nil,
+				LastWireguardHandshake: time.Time{},
+			},
+			want: []*regexp.Regexp{
+				regexp.MustCompile(`^✘ have not received remote agent data from Coder networking coordinator$`),
+			},
+		},
+		{
+			name: "noWireguardHandshake",
+			diags: tailnet.PeerDiagnostics{
+				PreferredDERP:          0,
+				DERPRegionNames:        map[int]string{},
+				SentNode:               false,
+				ReceivedNode:           nil,
+				LastWireguardHandshake: time.Time{},
+			},
+			want: []*regexp.Regexp{
+				regexp.MustCompile(`^✘ Wireguard is not connected$`),
+			},
+		},
+		{
+			name: "wireguardHandshakeRecent",
+			diags: tailnet.PeerDiagnostics{
+				PreferredDERP:          0,
+				DERPRegionNames:        map[int]string{},
+				SentNode:               false,
+				ReceivedNode:           nil,
+				LastWireguardHandshake: time.Now().Add(-5 * time.Second),
+			},
+			want: []*regexp.Regexp{
+				regexp.MustCompile(`^✔ Wireguard handshake \d+s ago$`),
+			},
+		},
+		{
+			name: "wireguardHandshakeOld",
+			diags: tailnet.PeerDiagnostics{
+				PreferredDERP:          0,
+				DERPRegionNames:        map[int]string{},
+				SentNode:               false,
+				ReceivedNode:           nil,
+				LastWireguardHandshake: time.Now().Add(-450 * time.Second), // 7m30s
+			},
+			want: []*regexp.Regexp{
+				regexp.MustCompile(`^⚠ Wireguard handshake 7m\d+s ago$`),
+			},
+		},
+	}
+	for _, tc := range testCases {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			r, w := io.Pipe()
+			go func() {
+				defer w.Close()
+				cliui.PeerDiagnostics(w, tc.diags)
+			}()
+			s := bufio.NewScanner(r)
+			i := 0
+			got := make([]string, 0)
+			for s.Scan() {
+				got = append(got, s.Text())
+				if i < len(tc.want) {
+					reg := tc.want[i]
+					if reg.Match(s.Bytes()) {
+						i++
+					}
+				}
+			}
+			if i < len(tc.want) {
+				t.Logf("failed to match regexp: %s\ngot:\n%s", tc.want[i].String(), strings.Join(got, "\n"))
+				t.FailNow()
+			}
+		})
+	}
+}
@@ -0,0 +1,21 @@
+package cliui
+
+import (
+	"fmt"
+
+	"github.com/coder/pretty"
+	"github.com/coder/serpent"
+)
+
+func DeprecationWarning(message string) serpent.MiddlewareFunc {
+	return func(next serpent.HandlerFunc) serpent.HandlerFunc {
+		return func(i *serpent.Invocation) error {
+			_, _ = fmt.Fprintln(i.Stdout, "\n"+pretty.Sprint(DefaultStyles.Wrap,
+				pretty.Sprint(
+					DefaultStyles.Warn,
+					"DEPRECATION WARNING: This command will be removed in a future release."+"\n"+message+"\n"),
+			))
+			return next(i)
+		}
+	}
+}
@@ -8,11 +8,11 @@ import (

 	"github.com/stretchr/testify/assert"

-	"github.com/coder/coder/v2/cli/clibase"
 	"github.com/coder/coder/v2/cli/cliui"
 	"github.com/coder/coder/v2/codersdk"
 	"github.com/coder/coder/v2/pty/ptytest"
 	"github.com/coder/coder/v2/testutil"
+	"github.com/coder/serpent"
 )

 func TestExternalAuth(t *testing.T) {
@@ -22,8 +22,8 @@ func TestExternalAuth(t *testing.T) {
 	defer cancel()

 	ptty := ptytest.New(t)
-	cmd := &clibase.Cmd{
-		Handler: func(inv *clibase.Invocation) error {
+	cmd := &serpent.Command{
+		Handler: func(inv *serpent.Invocation) error {
 			var fetched atomic.Bool
 			return cliui.ExternalAuth(inv.Context(), inv.Stdout, cliui.ExternalAuthOptions{
 				Fetch: func(ctx context.Context) ([]codersdk.TemplateVersionExternalAuth, error) {
@@ -1,8 +1,8 @@
 package cliui

 import (
-	"github.com/coder/coder/v2/cli/clibase"
 	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/serpent"
 )

 var defaultQuery = "owner:me"
@@ -11,12 +11,12 @@ var defaultQuery = "owner:me"
 // and allows easy integration to a CLI command.
 // Example usage:
 //
-//	func (r *RootCmd) MyCmd() *clibase.Cmd {
+//	func (r *RootCmd) MyCmd() *serpent.Command {
 //	  var (
 //	    filter cliui.WorkspaceFilter
 //	    ...
 //	  )
-//	  cmd := &clibase.Cmd{
+//	  cmd := &serpent.Command{
 //	    ...
 //	  }
 //	  filter.AttachOptions(&cmd.Options)
@@ -44,20 +44,20 @@ func (w *WorkspaceFilter) Filter() codersdk.WorkspaceFilter {
 	return f
 }

-func (w *WorkspaceFilter) AttachOptions(opts *clibase.OptionSet) {
+func (w *WorkspaceFilter) AttachOptions(opts *serpent.OptionSet) {
 	*opts = append(*opts,
-		clibase.Option{
+		serpent.Option{
 			Flag:          "all",
 			FlagShorthand: "a",
 			Description:   "Specifies whether all workspaces will be listed or not.",

-			Value: clibase.BoolOf(&w.all),
+			Value: serpent.BoolOf(&w.all),
 		},
-		clibase.Option{
+		serpent.Option{
 			Flag:        "search",
 			Description: "Search for a workspace with a query.",
 			Default:     defaultQuery,
-			Value:       clibase.StringOf(&w.searchQuery),
+			Value:       serpent.StringOf(&w.searchQuery),
 		},
 	)
 }
@@ -9,12 +9,12 @@ import (

 	"golang.org/x/xerrors"

-	"github.com/coder/coder/v2/cli/clibase"
+	"github.com/coder/serpent"
 )

 type OutputFormat interface {
 	ID() string
-	AttachOptions(opts *clibase.OptionSet)
+	AttachOptions(opts *serpent.OptionSet)
 	Format(ctx context.Context, data any) (string, error)
 }

@@ -49,7 +49,7 @@ func NewOutputFormatter(formats ...OutputFormat) *OutputFormatter {

 // AttachOptions attaches the --output flag to the given command, and any
 // additional flags required by the output formatters.
-func (f *OutputFormatter) AttachOptions(opts *clibase.OptionSet) {
+func (f *OutputFormatter) AttachOptions(opts *serpent.OptionSet) {
 	for _, format := range f.formats {
 		format.AttachOptions(opts)
 	}
@@ -60,11 +60,11 @@ func (f *OutputFormatter) AttachOptions(opts *clibase.OptionSet) {
 	}

 	*opts = append(*opts,
-		clibase.Option{
+		serpent.Option{
 			Flag:          "output",
 			FlagShorthand: "o",
 			Default:       f.formats[0].ID(),
-			Value:         clibase.StringOf(&f.formatID),
+			Value:         serpent.StringOf(&f.formatID),
 			Description:   "Output format. Available formats: " + strings.Join(formatNames, ", ") + ".",
 		},
 	)
@@ -106,7 +106,7 @@ func TableFormat(out any, defaultColumns []string) OutputFormat {
 	}

 	// Get the list of table column headers.
-	headers, defaultSort, err := typeToTableHeaders(v.Type().Elem())
+	headers, defaultSort, err := typeToTableHeaders(v.Type().Elem(), true)
 	if err != nil {
 		panic("parse table headers: " + err.Error())
 	}
@@ -129,13 +129,13 @@ func (*tableFormat) ID() string {
 }

 // AttachOptions implements OutputFormat.
-func (f *tableFormat) AttachOptions(opts *clibase.OptionSet) {
+func (f *tableFormat) AttachOptions(opts *serpent.OptionSet) {
 	*opts = append(*opts,
-		clibase.Option{
+		serpent.Option{
 			Flag:          "column",
 			FlagShorthand: "c",
 			Default:       strings.Join(f.defaultColumns, ","),
-			Value:         clibase.StringArrayOf(&f.columns),
+			Value:         serpent.StringArrayOf(&f.columns),
 			Description:   "Columns to display in table output. Available columns: " + strings.Join(f.allColumns, ", ") + ".",
 		},
 	)
@@ -161,7 +161,7 @@ func (jsonFormat) ID() string {
 }

 // AttachOptions implements OutputFormat.
-func (jsonFormat) AttachOptions(_ *clibase.OptionSet) {}
+func (jsonFormat) AttachOptions(_ *serpent.OptionSet) {}

 // Format implements OutputFormat.
 func (jsonFormat) Format(_ context.Context, data any) (string, error) {
@@ -187,7 +187,7 @@ func (textFormat) ID() string {
 	return "text"
 }

-func (textFormat) AttachOptions(_ *clibase.OptionSet) {}
+func (textFormat) AttachOptions(_ *serpent.OptionSet) {}

 func (textFormat) Format(_ context.Context, data any) (string, error) {
 	return fmt.Sprintf("%s", data), nil
@@ -213,7 +213,7 @@ func (d *DataChangeFormat) ID() string {
 	return d.format.ID()
 }

-func (d *DataChangeFormat) AttachOptions(opts *clibase.OptionSet) {
+func (d *DataChangeFormat) AttachOptions(opts *serpent.OptionSet) {
 	d.format.AttachOptions(opts)
 }

@@ -8,13 +8,13 @@ import (

 	"github.com/stretchr/testify/require"

-	"github.com/coder/coder/v2/cli/clibase"
 	"github.com/coder/coder/v2/cli/cliui"
+	"github.com/coder/serpent"
 )

 type format struct {
 	id              string
-	attachOptionsFn func(opts *clibase.OptionSet)
+	attachOptionsFn func(opts *serpent.OptionSet)
 	formatFn        func(ctx context.Context, data any) (string, error)
 }

@@ -24,7 +24,7 @@ func (f *format) ID() string {
 	return f.id
 }

-func (f *format) AttachOptions(opts *clibase.OptionSet) {
+func (f *format) AttachOptions(opts *serpent.OptionSet) {
 	if f.attachOptionsFn != nil {
 		f.attachOptionsFn(opts)
 	}
@@ -85,12 +85,12 @@ func Test_OutputFormatter(t *testing.T) {
 			cliui.JSONFormat(),
 			&format{
 				id: "foo",
-				attachOptionsFn: func(opts *clibase.OptionSet) {
-					opts.Add(clibase.Option{
+				attachOptionsFn: func(opts *serpent.OptionSet) {
+					opts.Add(serpent.Option{
 						Name:          "foo",
 						Flag:          "foo",
 						FlagShorthand: "f",
-						Value:         clibase.DiscardValue,
+						Value:         serpent.DiscardValue,
 						Description:   "foo flag 1234",
 					})
 				},
@@ -101,7 +101,7 @@ func Test_OutputFormatter(t *testing.T) {
 			},
 		)

-		cmd := &clibase.Cmd{}
+		cmd := &serpent.Command{}
 		f.AttachOptions(&cmd.Options)

 		fs := cmd.Options.FlagSet()
@@ -5,12 +5,12 @@ import (
 	"fmt"
 	"strings"

-	"github.com/coder/coder/v2/cli/clibase"
 	"github.com/coder/coder/v2/codersdk"
 	"github.com/coder/pretty"
+	"github.com/coder/serpent"
 )

-func RichParameter(inv *clibase.Invocation, templateVersionParameter codersdk.TemplateVersionParameter) (string, error) {
+func RichParameter(inv *serpent.Invocation, templateVersionParameter codersdk.TemplateVersionParameter, defaultOverrides map[string]string) (string, error) {
 	label := templateVersionParameter.Name
 	if templateVersionParameter.DisplayName != "" {
 		label = templateVersionParameter.DisplayName
@@ -26,6 +26,11 @@ func RichParameter(inv *clibase.Invocation, templateVersionParameter codersdk.Te
 		_, _ = fmt.Fprintln(inv.Stdout, "  "+strings.TrimSpace(strings.Join(strings.Split(templateVersionParameter.DescriptionPlaintext, "\n"), "\n  "))+"\n")
 	}

+	defaultValue := templateVersionParameter.DefaultValue
+	if v, ok := defaultOverrides[templateVersionParameter.Name]; ok {
+		defaultValue = v
+	}
+
 	var err error
 	var value string
 	if templateVersionParameter.Type == "list(string)" {
@@ -58,7 +63,7 @@ func RichParameter(inv *clibase.Invocation, templateVersionParameter codersdk.Te
 		var richParameterOption *codersdk.TemplateVersionParameterOption
 		richParameterOption, err = RichSelect(inv, RichSelectOptions{
 			Options:    templateVersionParameter.Options,
-			Default:    templateVersionParameter.DefaultValue,
+			Default:    defaultValue,
 			HideSearch: true,
 		})
 		if err == nil {
@@ -69,7 +74,7 @@ func RichParameter(inv *clibase.Invocation, templateVersionParameter codersdk.Te
 	} else {
 		text := "Enter a value"
 		if !templateVersionParameter.Required {
-			text += fmt.Sprintf(" (default: %q)", templateVersionParameter.DefaultValue)
+			text += fmt.Sprintf(" (default: %q)", defaultValue)
 		}
 		text += ":"

@@ -87,7 +92,7 @@ func RichParameter(inv *clibase.Invocation, templateVersionParameter codersdk.Te

 	// If they didn't specify anything, use the default value if set.
 	if len(templateVersionParameter.Options) == 0 && value == "" {
-		value = templateVersionParameter.DefaultValue
+		value = defaultValue
 	}

 	return value, nil
@@ -13,8 +13,8 @@ import (
 	"github.com/mattn/go-isatty"
 	"golang.org/x/xerrors"

-	"github.com/coder/coder/v2/cli/clibase"
 	"github.com/coder/pretty"
+	"github.com/coder/serpent"
 )

 // PromptOptions supply a set of options to the prompt.
@@ -30,13 +30,13 @@ const skipPromptFlag = "yes"

 // SkipPromptOption adds a "--yes/-y" flag to the cmd that can be used to skip
 // prompts.
-func SkipPromptOption() clibase.Option {
-	return clibase.Option{
+func SkipPromptOption() serpent.Option {
+	return serpent.Option{
 		Flag:          skipPromptFlag,
 		FlagShorthand: "y",
 		Description:   "Bypass prompts.",
 		// Discard
-		Value: clibase.BoolOf(new(bool)),
+		Value: serpent.BoolOf(new(bool)),
 	}
 }

@@ -46,7 +46,7 @@ const (
 )

 // Prompt asks the user for input.
-func Prompt(inv *clibase.Invocation, opts PromptOptions) (string, error) {
+func Prompt(inv *serpent.Invocation, opts PromptOptions) (string, error) {
 	// If the cmd has a "yes" flag for skipping confirm prompts, honor it.
 	// If it's not a "Confirm" prompt, then don't skip. As the default value of
 	// "yes" makes no sense.
@@ -71,9 +71,9 @@ func Prompt(inv *clibase.Invocation, opts PromptOptions) (string, error) {
 		} else {
 			renderedNo = Bold(ConfirmNo)
 		}
-		pretty.Fprintf(inv.Stdout, DefaultStyles.Placeholder, "(%s/%s) ", renderedYes, renderedNo)
+		_, _ = fmt.Fprintf(inv.Stdout, "(%s/%s) ", renderedYes, renderedNo)
 	} else if opts.Default != "" {
-		_, _ = fmt.Fprint(inv.Stdout, pretty.Sprint(DefaultStyles.Placeholder, "("+opts.Default+") "))
+		_, _ = fmt.Fprintf(inv.Stdout, "(%s) ", pretty.Sprint(DefaultStyles.Placeholder, opts.Default))
 	}
 	interrupt := make(chan os.Signal, 1)

@@ -11,11 +11,11 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"

-	"github.com/coder/coder/v2/cli/clibase"
 	"github.com/coder/coder/v2/cli/cliui"
 	"github.com/coder/coder/v2/pty"
 	"github.com/coder/coder/v2/pty/ptytest"
 	"github.com/coder/coder/v2/testutil"
+	"github.com/coder/serpent"
 )

 func TestPrompt(t *testing.T) {
@@ -77,7 +77,7 @@ func TestPrompt(t *testing.T) {
 			resp, err := newPrompt(ptty, cliui.PromptOptions{
 				Text:      "ShouldNotSeeThis",
 				IsConfirm: true,
-			}, func(inv *clibase.Invocation) {
+			}, func(inv *serpent.Invocation) {
 				inv.Command.Options = append(inv.Command.Options, cliui.SkipPromptOption())
 				inv.Args = []string{"-y"}
 			})
@@ -145,10 +145,10 @@ func TestPrompt(t *testing.T) {
 	})
 }

-func newPrompt(ptty *ptytest.PTY, opts cliui.PromptOptions, invOpt func(inv *clibase.Invocation)) (string, error) {
+func newPrompt(ptty *ptytest.PTY, opts cliui.PromptOptions, invOpt func(inv *serpent.Invocation)) (string, error) {
 	value := ""
-	cmd := &clibase.Cmd{
-		Handler: func(inv *clibase.Invocation) error {
+	cmd := &serpent.Command{
+		Handler: func(inv *serpent.Invocation) error {
 			var err error
 			value, err = cliui.Prompt(inv, opts)
 			return err
@@ -210,8 +210,8 @@ func TestPasswordTerminalState(t *testing.T) {

 // nolint:unused
 func passwordHelper() {
-	cmd := &clibase.Cmd{
-		Handler: func(inv *clibase.Invocation) error {
+	cmd := &serpent.Command{
+		Handler: func(inv *serpent.Invocation) error {
 			cliui.Prompt(inv, cliui.PromptOptions{
 				Text:   "Password:",
 				Secret: true,
@@ -54,6 +54,11 @@ func (err *ProvisionerJobError) Error() string {
 	return err.Message
 }

+const (
+	ProvisioningStateQueued  = "Queued"
+	ProvisioningStateRunning = "Running"
+)
+
 // ProvisionerJob renders a provisioner job with interactive cancellation.
 func ProvisionerJob(ctx context.Context, wr io.Writer, opts ProvisionerJobOptions) error {
 	if opts.FetchInterval == 0 {
@@ -63,8 +68,9 @@ func ProvisionerJob(ctx context.Context, wr io.Writer, opts ProvisionerJobOption
 	defer cancelFunc()

 	var (
-		currentStage          = "Queued"
+		currentStage          = ProvisioningStateQueued
 		currentStageStartedAt = time.Now().UTC()
+		currentQueuePos       = -1

 		errChan  = make(chan error, 1)
 		job      codersdk.ProvisionerJob
@@ -74,7 +80,20 @@ func ProvisionerJob(ctx context.Context, wr io.Writer, opts ProvisionerJobOption
 	sw := &stageWriter{w: wr, verbose: opts.Verbose, silentLogs: opts.Silent}

 	printStage := func() {
-		sw.Start(currentStage)
+		out := currentStage
+
+		if currentStage == ProvisioningStateQueued && currentQueuePos > 0 {
+			var queuePos string
+			if currentQueuePos == 1 {
+				queuePos = "next"
+			} else {
+				queuePos = fmt.Sprintf("position: %d", currentQueuePos)
+			}
+
+			out = pretty.Sprintf(DefaultStyles.Warn, "%s (%s)", currentStage, queuePos)
+		}
+
+		sw.Start(out)
 	}

 	updateStage := func(stage string, startedAt time.Time) {
@@ -103,15 +122,26 @@ func ProvisionerJob(ctx context.Context, wr io.Writer, opts ProvisionerJobOption
 			errChan <- xerrors.Errorf("fetch: %w", err)
 			return
 		}
+		if job.QueuePosition != currentQueuePos {
+			initialState := currentQueuePos == -1
+
+			currentQueuePos = job.QueuePosition
+			// Print an update when the queue position changes, but:
+			//   - not initially, because the stage is printed at startup
+			//   - not when we're first in the queue, because it's redundant
+			if !initialState && currentQueuePos != 0 {
+				printStage()
+			}
+		}
 		if job.StartedAt == nil {
 			return
 		}
-		if currentStage != "Queued" {
+		if currentStage != ProvisioningStateQueued {
 			// If another stage is already running, there's no need
 			// for us to notify the user we're running!
 			return
 		}
-		updateStage("Running", *job.StartedAt)
+		updateStage(ProvisioningStateRunning, *job.StartedAt)
 	}

 	if opts.Cancel != nil {
@@ -143,8 +173,8 @@ func ProvisionerJob(ctx context.Context, wr io.Writer, opts ProvisionerJobOption
 	}

 	// The initial stage needs to print after the signal handler has been registered.
-	printStage()
 	updateJob()
+	printStage()

 	logs, closer, err := opts.Logs()
 	if err != nil {
@@ -2,8 +2,10 @@ package cliui_test

 import (
 	"context"
+	"fmt"
 	"io"
 	"os"
+	"regexp"
 	"runtime"
 	"sync"
 	"testing"
@@ -11,11 +13,13 @@ import (

 	"github.com/stretchr/testify/assert"

-	"github.com/coder/coder/v2/cli/clibase"
+	"github.com/coder/coder/v2/testutil"
+
 	"github.com/coder/coder/v2/cli/cliui"
 	"github.com/coder/coder/v2/coderd/database/dbtime"
 	"github.com/coder/coder/v2/codersdk"
 	"github.com/coder/coder/v2/pty/ptytest"
+	"github.com/coder/serpent"
 )

 // This cannot be ran in parallel because it uses a signal.
@@ -25,7 +29,11 @@ func TestProvisionerJob(t *testing.T) {
 		t.Parallel()

 		test := newProvisionerJob(t)
-		go func() {
+
+		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+		defer cancel()
+
+		testutil.Go(t, func() {
 			<-test.Next
 			test.JobMutex.Lock()
 			test.Job.Status = codersdk.ProvisionerJobRunning
@@ -39,20 +47,26 @@ func TestProvisionerJob(t *testing.T) {
 			test.Job.CompletedAt = &now
 			close(test.Logs)
 			test.JobMutex.Unlock()
-		}()
-		test.PTY.ExpectMatch("Queued")
-		test.Next <- struct{}{}
-		test.PTY.ExpectMatch("Queued")
-		test.PTY.ExpectMatch("Running")
-		test.Next <- struct{}{}
-		test.PTY.ExpectMatch("Running")
+		})
+		testutil.Eventually(ctx, t, func(ctx context.Context) (done bool) {
+			test.PTY.ExpectMatch(cliui.ProvisioningStateQueued)
+			test.Next <- struct{}{}
+			test.PTY.ExpectMatch(cliui.ProvisioningStateQueued)
+			test.PTY.ExpectMatch(cliui.ProvisioningStateRunning)
+			test.Next <- struct{}{}
+			test.PTY.ExpectMatch(cliui.ProvisioningStateRunning)
+			return true
+		}, testutil.IntervalFast)
 	})

 	t.Run("Stages", func(t *testing.T) {
 		t.Parallel()

 		test := newProvisionerJob(t)
-		go func() {
+		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+		defer cancel()
+
+		testutil.Go(t, func() {
 			<-test.Next
 			test.JobMutex.Lock()
 			test.Job.Status = codersdk.ProvisionerJobRunning
@@ -70,13 +84,86 @@ func TestProvisionerJob(t *testing.T) {
 			test.Job.CompletedAt = &now
 			close(test.Logs)
 			test.JobMutex.Unlock()
-		}()
-		test.PTY.ExpectMatch("Queued")
-		test.Next <- struct{}{}
-		test.PTY.ExpectMatch("Queued")
-		test.PTY.ExpectMatch("Something")
-		test.Next <- struct{}{}
-		test.PTY.ExpectMatch("Something")
+		})
+		testutil.Eventually(ctx, t, func(ctx context.Context) (done bool) {
+			test.PTY.ExpectMatch(cliui.ProvisioningStateQueued)
+			test.Next <- struct{}{}
+			test.PTY.ExpectMatch(cliui.ProvisioningStateQueued)
+			test.PTY.ExpectMatch("Something")
+			test.Next <- struct{}{}
+			test.PTY.ExpectMatch("Something")
+			return true
+		}, testutil.IntervalFast)
+	})
+
+	t.Run("Queue Position", func(t *testing.T) {
+		t.Parallel()
+
+		stage := cliui.ProvisioningStateQueued
+
+		tests := []struct {
+			name     string
+			queuePos int
+			expected string
+		}{
+			{
+				name:     "first",
+				queuePos: 0,
+				expected: fmt.Sprintf("%s$", stage),
+			},
+			{
+				name:     "next",
+				queuePos: 1,
+				expected: fmt.Sprintf(`%s %s$`, stage, regexp.QuoteMeta("(next)")),
+			},
+			{
+				name:     "other",
+				queuePos: 4,
+				expected: fmt.Sprintf(`%s %s$`, stage, regexp.QuoteMeta("(position: 4)")),
+			},
+		}
+
+		for _, tc := range tests {
+			tc := tc
+
+			t.Run(tc.name, func(t *testing.T) {
+				t.Parallel()
+
+				test := newProvisionerJob(t)
+				test.JobMutex.Lock()
+				test.Job.QueuePosition = tc.queuePos
+				test.Job.QueueSize = tc.queuePos
+				test.JobMutex.Unlock()
+
+				ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+				defer cancel()
+
+				testutil.Go(t, func() {
+					<-test.Next
+					test.JobMutex.Lock()
+					test.Job.Status = codersdk.ProvisionerJobRunning
+					now := dbtime.Now()
+					test.Job.StartedAt = &now
+					test.JobMutex.Unlock()
+					<-test.Next
+					test.JobMutex.Lock()
+					test.Job.Status = codersdk.ProvisionerJobSucceeded
+					now = dbtime.Now()
+					test.Job.CompletedAt = &now
+					close(test.Logs)
+					test.JobMutex.Unlock()
+				})
+				testutil.Eventually(ctx, t, func(ctx context.Context) (done bool) {
+					test.PTY.ExpectRegexMatch(tc.expected)
+					test.Next <- struct{}{}
+					test.PTY.ExpectMatch(cliui.ProvisioningStateQueued) // step completed
+					test.PTY.ExpectMatch(cliui.ProvisioningStateRunning)
+					test.Next <- struct{}{}
+					test.PTY.ExpectMatch(cliui.ProvisioningStateRunning)
+					return true
+				}, testutil.IntervalFast)
+			})
+		}
 	})

 	// This cannot be ran in parallel because it uses a signal.
@@ -90,7 +177,11 @@ func TestProvisionerJob(t *testing.T) {
 		}

 		test := newProvisionerJob(t)
-		go func() {
+
+		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+		defer cancel()
+
+		testutil.Go(t, func() {
 			<-test.Next
 			currentProcess, err := os.FindProcess(os.Getpid())
 			assert.NoError(t, err)
@@ -103,12 +194,15 @@ func TestProvisionerJob(t *testing.T) {
 			test.Job.CompletedAt = &now
 			close(test.Logs)
 			test.JobMutex.Unlock()
-		}()
-		test.PTY.ExpectMatch("Queued")
-		test.Next <- struct{}{}
-		test.PTY.ExpectMatch("Gracefully canceling")
-		test.Next <- struct{}{}
-		test.PTY.ExpectMatch("Queued")
+		})
+		testutil.Eventually(ctx, t, func(ctx context.Context) (done bool) {
+			test.PTY.ExpectMatch(cliui.ProvisioningStateQueued)
+			test.Next <- struct{}{}
+			test.PTY.ExpectMatch("Gracefully canceling")
+			test.Next <- struct{}{}
+			test.PTY.ExpectMatch(cliui.ProvisioningStateQueued)
+			return true
+		}, testutil.IntervalFast)
 	})
 }

@@ -127,8 +221,8 @@ func newProvisionerJob(t *testing.T) provisionerJobTest {
 	}
 	jobLock := sync.Mutex{}
 	logs := make(chan codersdk.ProvisionerJobLog, 1)
-	cmd := &clibase.Cmd{
-		Handler: func(inv *clibase.Invocation) error {
+	cmd := &serpent.Command{
+		Handler: func(inv *serpent.Invocation) error {
 			return cliui.ProvisionerJob(inv.Context(), inv.Stdout, cliui.ProvisionerJobOptions{
 				FetchInterval: time.Millisecond,
 				Fetch: func() (codersdk.ProvisionerJob, error) {
@@ -10,8 +10,8 @@ import (
 	"github.com/AlecAivazis/survey/v2/terminal"
 	"golang.org/x/xerrors"

-	"github.com/coder/coder/v2/cli/clibase"
 	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/serpent"
 )

 func init() {
@@ -68,7 +68,7 @@ type RichSelectOptions struct {
 }

 // RichSelect displays a list of user options including name and description.
-func RichSelect(inv *clibase.Invocation, richOptions RichSelectOptions) (*codersdk.TemplateVersionParameterOption, error) {
+func RichSelect(inv *serpent.Invocation, richOptions RichSelectOptions) (*codersdk.TemplateVersionParameterOption, error) {
 	opts := make([]string, len(richOptions.Options))
 	var defaultOpt string
 	for i, option := range richOptions.Options {
@@ -102,7 +102,7 @@ func RichSelect(inv *clibase.Invocation, richOptions RichSelectOptions) (*coders
 }

 // Select displays a list of user options.
-func Select(inv *clibase.Invocation, opts SelectOptions) (string, error) {
+func Select(inv *serpent.Invocation, opts SelectOptions) (string, error) {
 	// The survey library used *always* fails when testing on Windows,
 	// as it requires a live TTY (can't be a conpty). We should fork
 	// this library to add a dummy fallback, that simply reads/writes
@@ -138,7 +138,7 @@ func Select(inv *clibase.Invocation, opts SelectOptions) (string, error) {
 	return value, err
 }

-func MultiSelect(inv *clibase.Invocation, items []string) ([]string, error) {
+func MultiSelect(inv *serpent.Invocation, items []string) ([]string, error) {
 	// Similar hack is applied to Select()
 	if flag.Lookup("test.v") != nil {
 		return items, nil
@@ -6,10 +6,10 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"

-	"github.com/coder/coder/v2/cli/clibase"
 	"github.com/coder/coder/v2/cli/cliui"
 	"github.com/coder/coder/v2/codersdk"
 	"github.com/coder/coder/v2/pty/ptytest"
+	"github.com/coder/serpent"
 )

 func TestSelect(t *testing.T) {
@@ -31,8 +31,8 @@ func TestSelect(t *testing.T) {

 func newSelect(ptty *ptytest.PTY, opts cliui.SelectOptions) (string, error) {
 	value := ""
-	cmd := &clibase.Cmd{
-		Handler: func(inv *clibase.Invocation) error {
+	cmd := &serpent.Command{
+		Handler: func(inv *serpent.Invocation) error {
 			var err error
 			value, err = cliui.Select(inv, opts)
 			return err
@@ -72,8 +72,8 @@ func TestRichSelect(t *testing.T) {

 func newRichSelect(ptty *ptytest.PTY, opts cliui.RichSelectOptions) (string, error) {
 	value := ""
-	cmd := &clibase.Cmd{
-		Handler: func(inv *clibase.Invocation) error {
+	cmd := &serpent.Command{
+		Handler: func(inv *serpent.Invocation) error {
 			richOption, err := cliui.RichSelect(inv, opts)
 			if err == nil {
 				value = richOption.Value
@@ -105,8 +105,8 @@ func TestMultiSelect(t *testing.T) {

 func newMultiSelect(ptty *ptytest.PTY, items []string) ([]string, error) {
 	var values []string
-	cmd := &clibase.Cmd{
-		Handler: func(inv *clibase.Invocation) error {
+	cmd := &serpent.Command{
+		Handler: func(inv *serpent.Invocation) error {
 			selectedItems, err := cliui.MultiSelect(inv, items)
 			if err == nil {
 				values = selectedItems
@@ -70,7 +70,7 @@ func DisplayTable(out any, sort string, filterColumns []string) (string, error)
 	}

 	// Get the list of table column headers.
-	headersRaw, defaultSort, err := typeToTableHeaders(v.Type().Elem())
+	headersRaw, defaultSort, err := typeToTableHeaders(v.Type().Elem(), true)
 	if err != nil {
 		return "", xerrors.Errorf("get table headers recursively for type %q: %w", v.Type().Elem().String(), err)
 	}
@@ -230,7 +230,11 @@ func isStructOrStructPointer(t reflect.Type) bool {
 // typeToTableHeaders converts a type to a slice of column names. If the given
 // type is invalid (not a struct or a pointer to a struct, has invalid table
 // tags, etc.), an error is returned.
-func typeToTableHeaders(t reflect.Type) ([]string, string, error) {
+//
+// requireDefault is only needed for the root call. This is recursive, so nested
+// structs do not need the default sort name.
+// nolint:revive
+func typeToTableHeaders(t reflect.Type, requireDefault bool) ([]string, string, error) {
 	if !isStructOrStructPointer(t) {
 		return nil, "", xerrors.Errorf("typeToTableHeaders called with a non-struct or a non-pointer-to-a-struct type")
 	}
@@ -246,6 +250,12 @@ func typeToTableHeaders(t reflect.Type) ([]string, string, error) {
 		if err != nil {
 			return nil, "", xerrors.Errorf("parse struct tags for field %q in type %q: %w", field.Name, t.String(), err)
 		}
+
+		if name == "" && (recursive && skip) {
+			return nil, "", xerrors.Errorf("a name is required for the field %q. "+
+				"recursive_line will ensure this is never shown to the user, but is still needed", field.Name)
+		}
+		// If recurse and skip is set, the name is intentionally empty.
 		if name == "" {
 			continue
 		}
@@ -262,7 +272,7 @@ func typeToTableHeaders(t reflect.Type) ([]string, string, error) {
 				return nil, "", xerrors.Errorf("field %q in type %q is marked as recursive but does not contain a struct or a pointer to a struct", field.Name, t.String())
 			}

-			childNames, _, err := typeToTableHeaders(fieldType)
+			childNames, defaultSort, err := typeToTableHeaders(fieldType, false)
 			if err != nil {
 				return nil, "", xerrors.Errorf("get child field header names for field %q in type %q: %w", field.Name, fieldType.String(), err)
 			}
@@ -273,13 +283,16 @@ func typeToTableHeaders(t reflect.Type) ([]string, string, error) {
 				}
 				headers = append(headers, fullName)
 			}
+			if defaultSortName == "" {
+				defaultSortName = defaultSort
+			}
 			continue
 		}

 		headers = append(headers, name)
 	}

-	if defaultSortName == "" {
+	if defaultSortName == "" && requireDefault {
 		return nil, "", xerrors.Errorf("no field marked as default_sort in type %q", t.String())
 	}

@@ -46,12 +46,12 @@ type tableTest2 struct {

 type tableTest3 struct {
 	NotIncluded string     // no table tag
-	Sub         tableTest2 `table:"inner,recursive,default_sort"`
+	Sub         tableTest2 `table:"inner,recursive"`
 }

 type tableTest4 struct {
 	Inline    tableTest2 `table:"ignored,recursive_inline"`
-	SortField string     `table:"sort_field,default_sort"`
+	SortField string     `table:"sort_field"`
 }

 func Test_DisplayTable(t *testing.T) {
@@ -4,6 +4,7 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"strings"

 	"github.com/kirsle/configdir"
 	"golang.org/x/xerrors"
@@ -69,6 +70,14 @@ func (r Root) PostgresPort() File {
 // File provides convenience methods for interacting with *os.File.
 type File string

+func (f File) Exists() bool {
+	if f == "" {
+		return false
+	}
+	_, err := os.Stat(string(f))
+	return err == nil
+}
+
 // Delete deletes the file.
 func (f File) Delete() error {
 	if f == "" {
@@ -85,13 +94,14 @@ func (f File) Write(s string) error {
 	return write(string(f), 0o600, []byte(s))
 }

-// Read reads the file to a string.
+// Read reads the file to a string. All leading and trailing whitespace
+// is removed.
 func (f File) Read() (string, error) {
 	if f == "" {
 		return "", xerrors.Errorf("empty file path")
 	}
 	byt, err := read(string(f))
-	return string(byt), err
+	return strings.TrimSpace(string(byt)), err
 }

 // open opens a file in the configuration directory,
--- a/Show More
+++ b/Show More