Find and inspect

Before a Workbench can run it must be saved under an alias. This page covers finding packages, saving them, inspecting what they will do, and checking that they can run.

Package references#

A package must sit at .workbenches/<name>/workbench.yml. The engine refuses any other location.

Browse#

Published Workbenches are listed in the registry. There is no CLI search command; agents search through MCP (see Tools).

wb list shows what a source publishes:

wb list                                # saved aliases (same as wb list --saved)
wb list .                              # packages in this repository
wb list /path/to/repository
wb list https://github.com/owner/repository
wb list owner/repository

Remote inspection uses the GitHub API. It never clones or creates a temporary checkout. Public repositories need no credentials; private ones use GITHUB_TOKEN or GH_TOKEN. An inaccessible private repository and a missing one are reported the same way, because GitHub does not distinguish them.

Save#

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

Remote additions are frozen snapshots until wb upgrade. Local additions are live: each new run reads the registered absolute package directory, so edits need no re-add. Identical additions are idempotent. A collision never overwrites: Saved Workbench X has changed. Rerun with --force to replace it.

Every session captures its own package bytes, so a resumed session keeps its original package even after edits, upgrades, or removal.

Internal registry Workbenches#

An internal Workbench is visible only to its organization's members and keys. Sign in to that organization first:

wb login --org acme
wb add acme/core

Without a key the registry answers as if it did not exist: Registry Workbench does not exist: org/name. Internal workbenches need a key for their organization. Registry reads attach a held key automatically: for publisher/name, the key of the organization whose slug matches publisher, otherwise the default organization's key, otherwise none. Expired keys are never sent, and keys go only to the registry, never to GitHub.

Saved internal Workbenches show as internal in wb list --saved (a trailing column in piped output) and in wb view. origin.visibility in wb view --json keeps the wire value private.

Manage saved Workbenches#

wb list
wb view project-core
wb view project-core --json
wb remove project-core

Upgrade saved Workbenches#

wb upgrade project-core   # one alias
wb upgrade                # every saved remote Workbench

upgrade refreshes saved remote Workbenches from their recorded source. It downloads and verifies the candidate before atomically repointing the alias. If the upgrade fails, the existing snapshot is unchanged. It uses the same key rule as registry reads.

View#

wb view <reference> shows the resolved contract without running anything: runner, model and its allowed routes and which are ready, every declared runtime, requirements, tools, environment names (never values), workspaces, provenance, and visibility. For a Workbench with gpu: true it also shows the GPUs found on this machine and whether the local runtime accepts them (gpu in --json).

wb view project-core
wb view .#core --json

Viewing or adding a Workbench never starts an agent.

Validate#

wb validate .#core
wb validate owner/repository

wb validate (alias wb v) parses the manifest and checks the package's local files against the schema for its spec. It proves the package is well formed, nothing more.

Smoke#

wb smoke project-core
wb smoke project-core --runtime docker
wb smoke project-core --json

wb smoke prepares the selected runtime and checks that the runner, every declared tool, authentication, instructions, and skills are ready inside it. It makes no model request.

On local and docker it is free. On e2b and daytona it creates a real sandbox, which is billable usage with that provider.

smoke lists the requirements it checked, applied, and could not check, and the GPUs it checked. The JSON shape is on JSON output.

Build#

wb build project-core
wb build project-core --runtime e2b --json

wb build pulls or builds and caches the image for a docker or e2b runtime. wb run does this automatically; build prepares it ahead of time. Published tags are pulled and run by their resolved digest. Local builds use a content-addressed cache and a staged build context that excludes common credential stores and secret-bearing files.

Dry run#

wb run project-core --task "Review this migration" --dry-run

--dry-run resolves, preflights, and translates the run without launching the runner. A terminal shows a summary; --json or piped output returns the complete translation. Environment values are never shown. It needs a task and cannot be combined with --repo.

What each check proves#

None of these says whether the package produces good work. Only real runs do.