# Overview

A Workbench is a versioned expert package: the instructions, model, runner, skills, tools, runtime, and authorization requirements a project's maintainers use for one class of work, packaged once so every compatible run starts prepared.

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, and the checks that prove the work is done, so the agent does not have to rediscover them.

## What a Workbench contains

A Workbench is a small directory in a repository:

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

Its manifest, `workbench.yml`, declares:

| Part         | What it is                                                                                       |
| ------------ | ------------------------------------------------------------------------------------------------ |
| Instructions | A Markdown file the maintainers write: the role, the method, the rules, and what done means.     |
| Runner       | The agent harness that executes the work: OpenCode, Pi, or Claude Code.                          |
| Model        | The model the work was tested with, as `lab/model`, and optionally which providers may serve it. |
| Skills       | Portable, on-demand skill directories the runner loads when they apply.                          |
| Tools        | CLI executables that must exist in the runtime before a run starts.                              |
| MCP servers  | Remote MCP integrations.                                                                         |
| Environment  | The names of environment variables the work reads, never their values.                           |
| Workspaces   | Named extra repositories or directories, with read-only or read-write access.                    |
| Requirements | What the environment must satisfy: OS, architecture, CPU, memory, disk, GPU.                     |
| Runtimes     | Where it can run: local, Docker, E2B, or Daytona, and the image each needs.                      |

```yaml
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 author locks the runner and model policy. The person running a Workbench brings their own model and runtime credentials, and cannot swap the runner, model, or routes, so a published Workbench stays equivalent to what its maintainer tested.

The Workbench engine reads this manifest; the runner does not. The engine validates the package, prepares the runtime, checks every requirement and tool inside it before any model request, and translates the package into the runner's native configuration.

## What a Workbench is not

A Workbench is not an agent, a workflow, or a user interface. It does not define a DAG, a task planner, a chat product, a schedule, approval stages, or retries. It is the portable, versioned environment that prepares an agent to do the work. Whatever orchestrates it, a person at a terminal, a coding agent, or a product, decides when it runs, what it is asked, and what happens to the result.

## The open source engine

`wb` is the open source reference engine and CLI for the standard, licensed under the Apache License 2.0. It runs Workbenches on your machine, in Docker, or in E2B or Daytona sandboxes with your own keys, supervises multi-turn sessions, and returns results as outcomes you can inspect, export, and apply. It works without any account.

- [Install it](/docs/cli/install), then follow the [Quickstart](/docs/quickstart).
- The [CLI reference](/docs/cli/run) covers every command.
- The [Workbench standard](/docs/standard/manifest) specifies the manifest, the event protocol, and the outcomes contract. Any host can implement it; the engine is one implementation.

## workbenches.dev

workbenches.dev is an optional service built on the same standard:

- **The registry.** Search, save, and publish Workbenches as immutable versions. Organization Workbenches are internal until a reviewed publish makes them public. See [Publishing](/docs/authoring/publishing).
- **Cloud runs.** Run a Workbench in a hosted sandbox, on a GitHub repository, with the agent opening its own pull request. See [Running on workbenches.dev](/docs/cloud/runs).
- **The MCP server.** `mcp.workbenches.dev` lets a coding agent search, run, and supervise Workbenches. See [MCP](/docs/mcp/connect).
- **Workers.** Connect your own machines to take cloud runs. See [Workers](/docs/workers/setup).
- **The API.** Everything above over HTTP. See the [API reference](/docs/api/overview).

The engine uses workbenches.dev for registry access, publishing, workers, and the model catalog it downloads and caches from `metadata.workbenches.dev`. Runs on your machine or with your own sandbox keys need no workbenches.dev account and are never metered.

## Who these docs are for

- **People running Workbenches**: start with the [Quickstart](/docs/quickstart) and the [CLI](/docs/cli/install).
- **People writing Workbenches**: start with [The method](/docs/authoring/method).
- **Agents driving Workbenches**: the [MCP tools](/docs/mcp/tools), [the run loop](/docs/mcp/loop), [Sessions](/docs/cli/sessions), and [JSON output](/docs/cli/json) are the exact contracts.