Devtools

devtools is the install channel of a Workstation or a WorkstationConfig. Each entry names a curated recipe that the in-VM agent runs to put a tool on the workstation. Unlike packages (a flat name handed to the system package manager), a devtool encapsulates whatever the tool actually needs: an upstream repository and signing key, a static binary download, a global npm install, a systemd unit, a shell-integration snippet, or a running Kubernetes cluster.

devtools:
  - name: docker
  - name: nodejs
    version: "24"
  - name: playwright
    config:
      browsers: [chromium, firefox]

Each entry accepts exactly three keys — a typo in any other key is rejected:

The recipes

Languages and toolchains

• go — the Go toolchain, pinned from upstream or from the distribution.
• golangci-lint — the Go linter, installed with the Go toolchain.
• nodejs — Node.js and npm, distribution or a pinned major.

Containers and Kubernetes

• docker — engine, CLI, Compose v2, and buildx.
• kind — the kind binary, and optionally a whole cluster with ingress and a load balancer.
• kubectl — the Kubernetes CLI.
• helm — Helm 3.
• kubectx — fast context switching.
• kubens — fast namespace switching.

AI coding tools and editors

• claude-code — the Claude Code CLI.
• codex — the Codex CLI.
• vscode-web — the code-server browser IDE, autostarted, with the Claude Code extension.

Cloud CLIs

• gcloud — the Google Cloud CLI.
• aws — the AWS CLI v2.
• az — the Azure CLI.

Version control

• git — git itself.
• gh — the GitHub CLI.

Testing and shell

• playwright — the Playwright CLI plus browser engines and their OS dependencies.
• fzf — the fuzzy finder, wired into login shells.

Host integration

• passthrough-www-browser — relay URLs opened inside the workstation to your laptop’s browser.

How devtools behave

They install in declared order. A recipe that depends on another tool ensures it itself (claude-code will install Node.js if it is missing), but declaring the dependency first makes the order explicit and lets you pin its version.

They are deduplicated by name across layers, last-wins on the whole entry. If a workstation and two configs all declare nodejs, one nodejs install happens, using the entry from the highest-priority layer — including its version and config. Position in the merged list follows where the name was first seen.

They install after packages and before files, sources, scripts, and services. So a provisioning script can assume docker compose or go build works the very first time the workstation sets itself up.

They are gated on the workstation’s real state, not just bookkeeping. Before running a recipe the agent probes whether the tool is genuinely present (for docker, that includes docker compose and docker buildx; for a configured kind, that the cluster still exists). A tool removed out-of-band is reinstalled the next time the workstation applies its configuration, and an already-installed tool is a fast no-op.

Changing version or config re-runs the recipe. The entry’s identity folds its version and its config blob, so editing either makes the next setup run apply it.

An unknown name is a loud failure. A typo does not silently no-op; the workstation reports the failing step and stays Configured: False.

Devtools versus tool configuration

A devtool installs software. A toolconfig configures software that is already installed — it writes the tool’s dotfiles on every setup run and installs nothing. Several names appear in both channels (claude-code, codex, vscode-web, git, gh) and are meant to be used together:

devtools:
  - name: git                    # install git
toolconfigs:
  - name: git                    # give it an identity
    config:
      userName: Ada Lovelace
      userEmail: ada@example.com

Distribution support

Every recipe supports Debian and Ubuntu. Most also work on Alpine, using apk packages. Three do not and fail with a clear message on a musl workstation: gcloud, aws, and az. Each page states its support.

Downloads always resolve the workstation’s architecture (amd64 or arm64) at install time, so the same manifest works on an x86 cloud VM and an Apple-Silicon local VM.

• goThe Go toolchain: an exact upstream release, or the distribution package.
• golangci-lintThe golangci-lint Go linter, built with the workstation's Go toolchain onto the system PATH.
• nodejsNode.js and npm: the distribution package, or a pinned major from the upstream apt repository.
• dockerThe Docker engine, CLI, Compose v2, and buildx — with the login user in the docker group.
• kindThe kind binary — and, with a config blob, a running Kubernetes cluster with ingress and a load balancer.
• kubectlThe Kubernetes CLI, installed as a static binary for the workstation's architecture.
• helmHelm 3, installed from the official installer script.
• kubectxFast switching between Kubernetes contexts.
• kubensFast switching between Kubernetes namespaces.
• claude-codeThe Claude Code CLI, installed globally with npm and configured to bypass permission prompts by default.
• codexThe Codex CLI, installed globally with npm.
• vscode-webcode-server, the browser IDE — installed, autostarted, and preloaded with the Claude Code extension.
• gcloudThe Google Cloud CLI, from Google's official apt repository.
• awsThe AWS CLI v2, from Amazon's official self-contained bundle.
• azThe Azure CLI, from Microsoft's official apt repository.
• gitgit itself — the install companion to the git tool configuration.
• ghThe GitHub CLI — the install companion to the gh tool configuration.
• playwrightThe Playwright CLI plus browser engines and their system dependencies, in a shared cache every shell can read.
• fzfThe fzf fuzzy finder, with key bindings and completion wired into login shells.
• passthrough-www-browserRelay URLs opened inside the workstation to your laptop's real browser — for OAuth and device-code logins.