Running Workbenches

Run

wb run starts a Workbench on a task. It accepts a saved alias only; --dir and --repo select what the agent works on, never the package source.

wb run <alias> [task] [options]

Give it a task#

A run needs exactly one task:

wb run project-core "Explain the storage architecture"
wb run project-core --task "Review this migration"
wb run project-core --task-file ./brief.md
cat brief.md | wb run project-core --stdin

Option	Effect
`[task]`	The task as a positional argument.
`--task <text>`	The same, as an option.
`--task-file <file>`	Read the task from a UTF-8 file. Use it for long briefs.
`--stdin`	Read the task from standard input.

Without one, the run fails with wb run requires a task. Unknown options are rejected.

Choose the output#

Option	Output
none	A colorized, terminal-safe Markdown stream of the run, the same for every runner.
`--final`	Only the final assistant response.
`--json`	Normalized events as NDJSON, one per line. See Event protocol.
`--detach`	Start in the background and print the session ID. With `--json`, print a launch receipt.
`--color`	Force color in human output. `NO_COLOR` or `--no-color` turns it off.

--final and --json cannot be combined. Stdout carries only the selected output. Errors go to stderr as error: <message>, or a red ✗ <message> in a terminal.

wb run project-core --task "Review this migration" --final
wb run project-core --task "Review this migration" --json
wb run project-core --task-file ./brief.md --detach --json

Once a run has started, --json reports a failure as run.failed on stdout with a non-zero exit. A failure before it starts (arguments, preflight, authentication, worker startup) prints error: <message> on stderr, emits no events, and exits 1 or 3.

Detach#

--detach creates a durable session and run, launches a background worker, and returns. Supervise it with wait, send, and answer; see Sessions. A detached run cannot start a first-time runner sign-in, which needs a person at a terminal: run one foreground task first.

Choose the workspace#

`--dir`#

wb run project-core --dir ./app --task "Add pagination"

The primary workspace defaults to the current directory. --dir selects another. It is the runner's working directory and is read-write.

`--workspace`#

wb run project-core --dir ./app --workspace api=../api \
  --workspace schemas=../schemas --task "Review the cross-repository change"

--workspace NAME=PATH binds a named workspace the manifest declares. It is repeatable. Missing required bindings, undeclared names, unavailable directories, and duplicate paths fail before the runner launches.

Inside a run each location is WORKBENCH_WORKSPACE_<NAME>, with hyphens as underscores, such as WORKBENCH_WORKSPACE_API. Local runs use the host path. Docker, E2B, and Daytona use /workspaces/<name>. Docker enforces read-only declarations at the mount. E2B and Daytona copy the directories and return read-write changes as pending outcomes. On the local runtime access is a preflight check, not a sandbox.

`--repo`#

wb run project-core --repo owner/project --task "Audit authentication"
wb run project-core --repo owner/project --ref main \
  --task "Add pagination and tests and open a draft PR"

--repo owner/name runs against an isolated GitHub checkout instead of your directory. --ref picks a branch, tag, or commit and defaults to the repository's default branch.

The engine resolves the ref to an exact commit and checks it out in the session's managed storage. It never uploads or synchronizes your current directory.
Access uses GH_TOKEN, then GITHUB_TOKEN, then an existing gh auth login. This is separate from wb connect.
The runner gets GH_TOKEN and Git configured to use gh for HTTPS. Commits use the authenticated account's GitHub no-reply identity.
The agent uses ordinary git and gh to commit, push, open or update a pull request, and inspect CI. Nothing is published automatically when a run ends.
The token keeps its real permissions. Repository mode is not a restriction to pull request operations, so use a suitably scoped token.
Private repositories need read access. Opening a pull request needs Contents and Pull requests write. CI inspection needs Actions and Checks read.
The checkout is shallow. Submodules are kept but not initialized, and Git LFS files are not downloaded.
--repo cannot be combined with --dir, --workspace, host Docker access, or --dry-run.

Workbench authors do not need to declare git or gh. For Docker and E2B the engine adds a cached tooling layer on top of the image. On Daytona it installs them in the sandbox, which needs a root user or passwordless sudo when the image lacks them.

Resume keeps the managed checkout and the runner's Git state. A confirmed pull request URL the agent records as a pull_request outcome link is returned with the outcome.

Bind environment values#

wb run project-core --task "Review this migration" --env-file .env.workbench
wb run project-core --task "Review this migration" \
  --env API_URL=https://api.example.com

Option	Effect
`--env-file <file>`	Read values from a dotenv file. Entries the Workbench does not declare are ignored.
`--env NAME=value`	Set one value. Repeatable. An undeclared name is rejected as a likely typo, unless it is a provider key for an allowed route or the selected sandbox runtime's key.

Precedence is --env, then --env-file, then the inherited environment. Values are used only for that invocation and never written to run metadata or events. Prefer --env-file or the environment for secrets, because command-line values stay in shell history. A required variable that is missing fails with Missing required environment variable: NAME.

Only declared values, the selected provider's credential variables, and the selected runner's private credential store reach the run. After a model route is chosen, other providers' keys are stripped.

Pick the connection#

wb run project-core --connection openrouter --task "Review this migration"

--connection <provider> uses one authenticated provider for this run without changing your saved default. It must match a route the Workbench allows. Resolution order is --connection, then the wb connect default for the runner and runtime, then the first allowed authenticated route in manifest order. See Models and connections.

Pick the runtime#

wb run project-core --runtime docker --task "Review this migration"

--runtime <name> selects a runtime the Workbench declares. Without it the first declared runtime is used. Naming one it does not declare fails and lists the declared ones. See Runtimes.

Track it in a project#

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

--project <name-or-slug> groups the session under a local project. It must already exist; --project never creates one, and an unknown name fails before anything is dispatched with a suggestion such as No project "X". Did you mean "Y"?. See Projects, status, studio, and MCP.

Other options#

Option	Effect
`--allow-host-docker`	Grant a declared host Docker engine binding for this run. Gives the run effective administrative access to the Docker host.
`--allow-unchecked-gpu`	Accept a local GPU requirement when discovery finds no GPU.
`--dry-run`	Resolve, preflight, and translate without launching.

What happens#

The package is resolved and validated, and its bytes are captured for the session.
The selected runtime is checked against the Workbench's requirements.
The runtime is prepared: an image pulled or built, a container or sandbox created, the workspace mounted or copied.
Every declared tool, the runner, and authentication are verified inside it.
The runner launches. Only now can a model request happen.

Preflight failure stops the run before spending model tokens. A run spends your provider credentials and billing, and sandbox time on E2B and Daytona.

The agent's context#

The engine gives the runner a short <workbench_context> block before the package instructions, explaining the outbox and result delivery, and a <workbench_runtime> block with the actual workspace paths, access, and outbox path. It never includes environment values or credentials. The agent writes requested files to WORKBENCH_OUTPUT_DIR; see Outcomes.

Run