# 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](/docs/workers/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`:

```json
{
    "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.

## Share or unshare

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

```json
{
    "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](/docs/api/runs#errors). `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.

### Start a sign-in

`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.