# 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:

```sh
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](/docs/cli/install).

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

```sh
npx skills add pompeii-labs/workbenches
```

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

```sh
npm install -g opencode-ai
```

## 2. Sign in

```sh
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](/workbenches), then save one under an alias. The official creator is a good first one:

```sh
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:

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

## 4. Connect a model provider

```sh
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](/docs/cli/models).

## 5. Check it, then run it locally

```sh
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:

```sh
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:

```sh
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](/docs/cli/run) and [Sessions](/docs/cli/sessions).

## 6. Set up workbenches.dev for cloud runs

Sign in at [workbenches.dev](/dashboard) 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](/docs/cloud/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](/docs/cloud/secrets).

## 7. Connect your coding agent

Claude Code:

```sh
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](/docs/mcp/connect).

## 8. Start a cloud run

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

```json
{
    "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](/docs/mcp/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:

```sh
claude mcp add wb -- wb mcp
```

See [Local wb mcp](/docs/mcp/local).

## Next

- [Write your own Workbench](/docs/authoring/method).
- [Connect a machine as a worker](/docs/workers/setup).
- [Call the API directly](/docs/api/overview).