Workbench

Package expert AI environments and run them anywhere.

A Workbench is a versioned, executable expert environment: the instructions, skills, tools, runtime, harness, and model configuration a project's maintainers use, packaged once. Every compatible run starts prepared instead of rebuilding that context from scratch.

Install the skills

The first step is to give your coding agent the Workbench skills. Your agent then installs and drives wb for you.

npx skills add pompeii-labs/workbenches

This installs four skills:

• wb-cli: install wb, connect credentials, and run, resume, and supervise Workbenches
• wb-subagents: delegate bounded, checkable work to a Workbench and collect the result
• wb-authoring: author, review, and trial a spec 1 Workbench package, gate first
• wb-publishing: push a Workbench to your organization and submit it for public review

Or install the CLI directly

Native binaries are available for macOS and Linux on arm64 and x64.

curl -fsSL https://workbenches.dev/install.sh | sh

The installer verifies the release checksum and creates workbench and wb commands in $XDG_BIN_HOME when it is set, else ~/.local/bin. It does not invoke sudo or edit your shell startup files. The default is the newest stable release; --version pins any version, prereleases included, for example curl -fsSL https://workbenches.dev/install.sh | sh -s -- --version 1.0.0. Flags passed through a pipe need sh -s -- --bin-dir DIR.

wb --version
wb update --check

Why Workbenches

Models are generalists. Projects are not. Every time a general-purpose agent enters an unfamiliar codebase, it spends time and tokens rebuilding architecture, conventions, tooling, and operating procedures the maintainers already know. A Workbench packages that knowledge once.

Same model, same spend: 36 working results with Workbenches, 20 without.

Both sides run the same agent (OpenCode 1.18) on the same model (openai/gpt-5.6-terra); the only difference is the Workbench. Eight tasks, two per row, five attempts per task and side, identical requests and starting projects, graded by scripts that run the result. Cost per working result includes failed attempts. Lux is our own database. Plain OpenCode was cheaper per working result on two of the eight tasks. Tasks, every failure, caveats, and how to reproduce: workbenchmarks.

A Workbench can run in your current directory, inside Docker, in an E2B or Daytona sandbox, or against an isolated GitHub checkout. The package belongs to its author, and the user brings their own model and runtime credentials. Runs execute through the selected harness, not a hosted Workbench agent service. The CLI downloads and caches model-routing metadata; first use requires an internet connection, and subsequent commands can use cached metadata if that service is unavailable.

Spec 1 is the Workbench standard; spec 0 is frozen legacy that engines still read. The spec 1 manifest, the run/resume/attach --json event stream, the wait --json result, send/answer --json receipts, detached run/resume --json receipts, smoke --json, exit codes, install.sh, and wb update are covered by the 1.0 stability promise. Everything else may change in minor versions.

The CLI reports anonymous save and run counts, but only for registry Workbenches published by an organization you do not hold a login for. Packages from your own organizations, local paths, GitHub sources, and private versions are never reported. A one-time notice appears before the first report. Set DO_NOT_TRACK=1 to disable reporting entirely.

Quick start

Save and inspect your first Workbench

Browse the registry for published Workbenches. Start with the official creator, which helps you decide what expertise to package for your project:

wb add pompeii/creator --as creator
wb view creator

The creator runs locally through OpenCode. Install OpenCode before continuing. Inspecting the package shows its model, runtime, instructions, skills, and requirements; adding or inspecting it does not start an agent.

Connect and run

wb connect creator
wb smoke creator

Choose an authentication method for the creator's model provider. Workbench uses the package's harness, model, and runtime rather than asking you to configure a different environment. smoke checks that the runtime, harness, authentication, and declared tools are ready. It makes no model request, but on E2B and Daytona it creates a billable sandbox.

From the project directory you want the agent to inspect, run:

wb run creator --task "Inspect this repository and recommend one focused Workbench to create. Do not change files." --final

This starts a real model run and prints its final recommendation. It uses your provider credentials and billing. For multi-turn work, start with --detach, observe with wb wait, and continue with wb send. Bare wb displays command help.

When you are ready to author the package, use wb create core --task "Create a focused expert for this repository"; see Create a Workbench below.

Runtime credentials are configured separately. For example, save an E2B API key once with:

wb connect --runtime e2b

An inherited E2B_API_KEY still overrides the saved value for a single process. Daytona works the same way with wb connect --runtime daytona and DAYTONA_API_KEY.

Other package sources

Save a registry publication, a package from GitHub, or a local package before running its alias. The following are example references; replace them with your own:

wb add publisher/core --as project-core
wb add https://github.com/owner/repository --name core --as project-core-git
wb add ./.workbenches/core --as project-core-local
wb run project-core "Explain this repository's architecture"

Use --final when you only want the final response or --json for normalized NDJSON events:

wb run project-core --task "Review this migration" --final
wb run project-core --task "Review this migration" --json

Remote additions are frozen until wb upgrade. Local additions are live: each new run reads the registered absolute package directory. Every session captures its own package bytes, so resumed sessions keep their original package even after edits, upgrades, or removal. run accepts saved aliases only; --dir and --repo select the work target, never the package source. wb login connects one organization per approval, so run wb login --org <slug> for each you push from, then manage them with wb org list, wb org use <slug>, wb whoami, and wb logout [--org <slug>].

Create a project before starting tracked work. Names resolve case-insensitively by display name or slug. Projects are local to this machine and work the same with or without wb login:

wb project create "Demo"
wb run project-core --project demo --task "Review this migration" --detach
wb project list

Coding agents can use the same projects and detached runs through wb mcp, and wb studio shows them on a local dashboard; see Local Studio API and Connect an agent.

Share with your team, then publish

Every organization workbench is internal until you publish it. wb push stores a new version under organization/<manifest-name>; only your organization's members and keys can see it. Teammates save it with wb add, using the held key for org automatically (wb login --org <org> first; without the key an internal workbench reports as missing):

wb push .#core                 # stores acme/core@<version>, internal
wb add acme/core               # teammates: save the internal workbench
wb publish acme/core           # submit the latest version for public review
wb unpublish acme/core         # make a public workbench internal again

Each push needs a higher manifest version than the last. Publishing is the one act that makes a stored version public, and it always goes through review. wb publish .#core pushes and submits in one step. Saved internal workbenches show as internal in wb list --saved and wb view.

Self-hosted workers for workbenches.dev

If you run Workbenches on workbenches.dev, wb login and then wb worker start --name <name> connects this machine to it as a self-hosted runner: runs you start there execute here instead of in a hosted sandbox. A worker is yours alone until you share it with your organization. Each member connects their own runners on it from any machine with wb connect --worker <slug> <runner>. This needs a workbenches.dev account; nothing else in wb depends on it. See Workers.

What is in a Workbench?

A Workbench is a small, versioned package owned by a project or expert:

.workbenches/
  core/
    workbench.yml
    instructions.md
    skills/

Its manifest selects the harness, model policy, runtime, instructions, skills, tools, integrations, and environment requirements for the work:

spec: 1
version: 0.1.0

name: core
description: Understand, review, and improve this project.

runner: opencode
model:
  id: openai/gpt-5.6-sol

instructions: ./instructions.md

requirements:
  os: [linux, macos]
  cpu: 4
  memory_gb: 8

runtimes:
  local: {}
  docker:
    image: ghcr.io/example/core:0.1.0

The Workbench engine reads this manifest; the underlying harness does not. The engine validates the package, prepares the runtime, checks its requirements, and translates the portable configuration into the harness's native interface.

A spec 1 Workbench states what its environment must satisfy in requirements and lists every runtime it supports in runtimes. The first runtime is the default, and wb run --runtime docker picks another. Spec 0, with its single runtime field, is frozen legacy that engines still read.

The format can package:

• maintainer-authored instructions
• a harness and model policy
• portable, on-demand skills
• required CLI tools
• remote MCP integrations
• environment variable requirements without secret values
• named workspaces for multi-repository work
• a local, Docker, E2B, or Daytona runtime and image

Workbench is not a model, agent harness, task planner, or hosted orchestration service. It is the portable expert environment those systems can execute.

Read the specification for the complete manifest. The run event protocol keeps protocol: 0 and its schema at schemas/events/v0. It is versioned separately from the manifest spec number, and changing it would break existing clients.

Run against a GitHub repository

Any compatible Workbench can operate on an isolated checkout without touching your local project:

wb run project-core \
  --repo owner/project \
  --ref main \
  --task "Audit authentication and open a draft PR with any fixes"

Repository access uses GH_TOKEN, then GITHUB_TOKEN, or your existing gh auth login. Workbench resolves the exact starting commit and prepares the checkout in managed session storage; it does not upload or synchronize your current directory.

For Docker, E2B, and Daytona repository runs, the engine supplies git and gh even when the Workbench image does not (on Daytona, an image without git and gh needs a root user or passwordless sudo). The agent uses the normal Git and GitHub CLI rather than a custom PR tool, and the engine does not silently publish work when a run ends.

Use Workbenches as subagents

Long briefs do not need to be crammed into shell arguments. Start a detached run from a file, wait for a result, and continue the same native agent session when needed:

wb run project-core --task-file ./brief.md --detach --json
wb wait wb_... --timeout 120 --json

wb send wb_... --task-file ./followup.md --json
wb wait wb_... --run --after 42 --timeout 120 --json

Each command returns correlated session and run IDs. Sequence cursors belong to one run, so wait on the run_id and after_sequence returned by the command you just issued.

The wb-subagents skill, in skills/wb-subagents, teaches a coding agent to delegate through wb from any project. Install it alone, globally, with:

npx skills add pompeii-labs/workbenches --skill wb-subagents -g

The other skills are wb-cli, wb-authoring, and wb-publishing; npx skills add pompeii-labs/workbenches installs all four.

Create a Workbench

Run the official creator from the repository you want the expert to understand:

wb create core --task "Create a focused expert for this repository"

The creator inspects the repository, writes .workbenches/core/workbench.yml and its supporting files, then validates and smoke-tests the package before finishing. Run the same target with a new brief to edit an existing local package.

For deterministic scaffolding without a model run:

wb init core

Keep the results

Disposable runtimes can return three kinds of durable result:

• changesets for workspace edits with an explicit apply boundary
• artifacts for reports, screenshots, images, and other files
• links for external results such as pull requests

Agents use their ordinary filesystem tools to write requested deliverables to a run-specific outbox. Workbench collects those files before destroying the runtime:

wb outcome wbo_...
wb outcome wbo_... --export ./result
wb outcome wbo_... --apply

Local and Docker edits already live in mounted host directories. E2B and Daytona changes remain pending until you explicitly apply them. Inspecting or exporting an outcome does not require another model turn or a live sandbox.

See Returned results for the complete contract.

Supported today

Workbench preserves the capabilities each harness actually exposes rather than inventing a common protocol they cannot honor. The runner capability table lists each harness's runtimes, steering, MCP support, sign-in, and verified versions.

Runtime boundaries

Local

Local Workbenches run directly on the host in the selected directory. Declared access is checked before launch, but local execution is not an operating-system sandbox.

Docker

Docker Workbenches run in their declared image. The package is read-only, the workspace is mounted with its declared access, and runner credentials that Workbench manages live in a private volume. Host Docker access requires a manifest declaration and an explicit --allow-host-docker grant on every run.

E2B

E2B Workbenches use a reusable template built from the declared image and a fresh sandbox for each execution. Only declared assets are staged; secret-bearing files, dependency trees, and Git metadata are excluded from workspace upload. Remote changes return as pending outcomes instead of silently synchronizing back to the host.

The E2B control key remains on the host. Harness credentials are staged only for the selected harness and synchronized back during orderly cleanup. Treat the sandbox provider and image as part of the credential trust boundary.

Daytona

Daytona Workbenches get a fresh Daytona sandbox created from the entry's published image for each execution (runtimes.daytona requires class; image is optional in the schema, but the reference engine cannot prepare an entry without a published image, and there is no fallback to another runtime's image), using the same staging rules and pending outcomes as E2B. The linux class and multi-turn sessions are supported; native authentication and sandbox recovery are not. Runners that read standard input, Pi and Claude Code, cannot run on Daytona yet. The Daytona key stays on the host, and model credentials come from your environment.

Command overview

wb                         # show command help
wb list                    # list saved Workbenches
wb view project-core       # inspect configuration and readiness
wb validate project-core   # validate a package
wb smoke project-core      # preflight, no model request
wb run project-core --task "Review this project"
wb run project-core --project Demo --task "Review this project"
wb ps                      # list active and resumable sessions
wb status                  # live progress of active and recent runs
wb studio --no-open        # dashboard on 9292, local API on 9293
wb studio --port 9392 --api-port 9393
wb mcp                     # serve Workbench tools to a coding agent over stdio
wb worker start            # self-hosted worker for workbenches.dev
wb send wb_... "Check the rollback too"
wb resume wb_... --task "Run the checks"
wb outcome wbo_...         # inspect returned results
wb upgrade                 # update saved Workbench packages
wb update                  # update the CLI

Run wb <command> --help for command-specific options.

Documentation

• CLI and execution reference
• Workbench package specification
• Execution protocol
• Local Studio API
• Outcome contract
• Source and workspace behavior
• Benchmarks: the same requests with and without a Workbench, graded by running the result, and how to reproduce them
• Contributing
• Security policy

The specification and schemas are the interoperability contract. This repository contains the TypeScript reference engine, not the only permitted Workbench host.

Development

bun install --frozen-lockfile
bun run check
bun run build

See the complete reference for Docker, E2B, real-harness, and release test suites.

License

Workbench is licensed under the Apache License 2.0.