API reference

Workers

A worker is a member's own machine that takes runs in place of a cloud sandbox. It is registered and operated with wb worker; see Setup. Every member may read the organization's workers and their logs. Another organization's worker reads as 404.

The worker object#

Field	Type	Meaning
`id`	UUID
`organization_id`	UUID
`name`	string, 1 to 80 characters
`slug`	string	From the name, unique among the organization's workers. Pass it as `worker` to `POST /v1/runs`.
`owner_member_id`	UUID or null
`owner_name`	string or null
`shared`	boolean	Shared with the organization, or personal to its owner.
`online`	boolean
`machine`	object or null	`os` (`linux`, `macos`, `windows`), `arch` (`x64`, `arm64`), `cpus`, `memory_gb`, `gpus` (each `name`, optional `memory_gb`), `docker` (`version`, or null), `runners` (each `name`, `version`).
`runtimes`	list of `docker`, `local`	The runtimes it offers.
`slots`	object	`busy`, `total`.
`current_runs`	integer	Its runs that have not ended, waiting ones included.
`wb_version`	string or null
`connected_at`, `seen_at`	date-time or null
`created_at`	date-time

Register a worker#

POST /v1/workers with { "name": "mini" }

Key runs:write of a member. 10 a minute per address; past that, 429. This is what wb worker start does with the CLI's login key. The key's member owns the new personal worker.

Response 201:

{
    "worker": { "id": "uuid", "slug": "mini", "name": "mini", "shared": false },
    "key": "wbk_..."
}

The worker key, wbk_ and 64 hex characters, is returned once. Only its hash is kept. Each registration is audited.

List workers#

GET /v1/workers

Key runs:read, or session: member.

Query	Type	Meaning
`organization`	slug	For a session.

Response 200 { "workers": [ ... ] }.

Get a worker#

GET /v1/workers/:id

Key runs:read, or session: member. Response 200: the worker.

PATCH /v1/workers/:id with { "shared": true }

Its owner: a session, or a key with runs:write. Response 200: the worker. A shared worker takes runs from every member; a personal one only from its owner.

Read its log#

GET /v1/workers/:id/logs

Key runs:read, or session: member. The latest 300 lines, scrubbed of secrets:

{
    "lines": [
        {
            "at": "2026-10-28T14:02:11Z",
            "text": "online, 1 slot, docker 27.3.1, runtimes docker"
        }
    ]
}

Remove a worker#

DELETE /v1/workers/:id

Its owner, or an owner or admin (a session, or a key with runs:write). Response 204. Its key stops working, its connection closes, and the runs it held fail. The slug is freed.

DELETE /v1/workers/self, with the worker key, revokes the worker's own key with the same effect. wb worker remove calls it.

Runs on a worker#

Pass worker to POST /v1/runs. The refusals (404, 403, 409 worker_offline, 422 worker_unsuitable) are on Runs and sessions. GET /v1/runs?worker=<uuid> lists a worker's runs.

Member sign-ins#

wb connect --worker <slug> <runner> uses these to sign a member in to a runner on a worker.

POST /v1/workers/:slug/connections

Key runs:write of a member who may run on the worker (it is shared, or theirs).

Field	Type	Meaning
`runner`	string	`opencode`, `claude-code`, or `pi`.
`provider`	string	The provider, such as `openai`.
`method`	string	The method, such as `chatgpt` or `api-key`.

Response 201 { "id": "uuid", "owner": "Ada Lovelace" }. owner names whose machine it is when it is not the caller's own, or is null. 409 worker_offline when the worker is not connected. A sign-in expires 10 minutes after it was created.

Attach the terminal#

GET /v1/workers/:slug/connections/:id/terminal?cols=<n>&rows=<n>

The same member, as a WebSocket. Nothing runs on the worker until this terminal attaches. It relays the runner's sign-in terminal to the member at that size; closing it cancels the sign-in. Terminal bytes and secrets are relayed, never stored or logged. Whatever the runner signs in with stays on the worker, in that member's directory.

The worker's own socket#

GET /v1/workers/connect is the WebSocket a worker holds with its wbk_ key. PUT /v1/runs/:id/outcome and GET /v1/runs/:id/package carry a worker run's outcome and package with credentials only the worker receives. These are for wb worker itself and are not documented here.