Workbenches is an open standard. Read why
Docs Quickstart

Getting started

Quickstart

This page takes you from nothing to a local run, a cloud run on workbenches.dev, and a coding agent that can drive Workbenches through MCP.

1. Install wb#

macOS or Linux, arm64 or x64:

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

The installer verifies the release checksum, installs to ~/.local/bin (or $XDG_BIN_HOME), and never uses sudo. If wb is not found, run export PATH="$HOME/.local/bin:$PATH" and add that line to your shell profile. Details are on Install and update.

Or give your coding agent the Workbench skills and let it install and drive wb for you:

npx skills add pompeii-labs/workbenches

wb does not ship a model harness. Install the runner the Workbench uses. Most use OpenCode:

npm install -g opencode-ai

2. Sign in#

wb login
wb whoami

wb login opens a browser approval that connects one organization; your personal organization exists from your first sign-in. Local runs do not need a login. You need one to save internal registry Workbenches, publish, and use workers.

3. Find and save a Workbench#

Browse the registry, then save one under an alias. The official creator is a good first one:

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

wb view shows the package's runner, model and which provider routes are ready, runtimes, instructions, skills, and requirements. Saving or viewing a Workbench never starts an agent.

You can also save from GitHub or a local directory:

wb add https://github.com/owner/repository --name core --as core
wb add ./.workbenches/core --as core-local

4. Connect a model provider#

wb connect creator

Choose a provider and an authentication method for the Workbench's model. wb connect saves the default for that runner and runtime, puts the credential where the runtime reads it, and ends with Ready: <Provider> for <Runner> in <runtime>. A provider key in your environment, or passed with --env-file, also works for a single run. See Models and connections.

5. Check it, then run it locally#

wb smoke creator

smoke checks that the runtime, runner, authentication, and declared tools are ready, with no model request.

From the project directory you want the agent to inspect:

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

This is a real model run on your provider credentials. --final prints only the final answer. For longer work, detach and supervise:

wb run creator --task-file ./brief.md --detach --json
wb wait wb_... --timeout 120 --json
wb send wb_... "Focus on the test suite" --json

See Run and Sessions.

6. Set up workbenches.dev for cloud runs#

Sign in at workbenches.dev and open your organization's setup page. A cloud run needs:

  1. An OpenRouter key. Sign in with OpenRouter or paste a key; it is saved as the organization's OPENROUTER_API_KEY secret. Model tokens are always your own.
  2. A payment method. Required before any cloud run, even within the included sandbox hours. See Sandbox time and plans.
  3. GitHub, for repository work. Connect GitHub for the repository's owner so runs can push their branch and open pull requests. A public repository can be read without it.
  4. A coding agent connected to MCP, below.

Add a secret for every other environment variable a Workbench requires on the organization's secrets page. See Organization secrets.

7. Connect your coding agent#

Claude Code:

claude mcp add --transport http workbenches https://mcp.workbenches.dev
claude mcp login workbenches

The login opens your browser to sign in. Codex, Cursor, OpenCode, and clients that need an API key are on Connect an agent.

8. Start a cloud run#

Ask your agent for the work, naming the Workbench and the repository. It calls the MCP tools:

{
    "tool": "run",
    "arguments": {
        "workbench": "acme/code-review",
        "task": "Review the open migration and open a draft pull request with fixes.",
        "repository": "acme/api",
        "ref": "main"
    }
}

The run executes in a fresh sandbox on workbenches.dev. The agent waits with wait, answers questions with answer, and reports the pull request the run's own agent opened. Follow the same run on its page in the dashboard. See The run loop.

Only Workbenches with a sandboxed runtime, an OpenCode runner, and an OpenRouter route run in the cloud. search returns only sandboxed Workbenches by default; check the rest with view.

9. Or drive local work from your agent#

For runs on your own machine, give the agent the local server instead:

claude mcp add wb -- wb mcp

See Local wb mcp.

Next#