Containers & Virtual Workers

CLI WebSocket connect

Upgrades to a WebSocket connection routed to the `CLIController` service. The JWT session token must be passed as the `Sec-WebSocket-Protocol` header value. This is the persistent control-channel connection used by the `bb` CLI and IDE extensions.

Auth Session JWT (Bearer)

Parameters

Responses

List active CLI connections (admin)

Returns metadata about active CLIController DO connections. Requires administrator-level authentication.

Auth Session JWT (Bearer)

Responses

CLI service health

Returns a lightweight liveness probe for the CLI WebSocket service. No authentication required.

Public Public: no authentication

Responses

CLI service info

Returns service version and capability metadata used by the CLI to negotiate protocol versions. No authentication required.

Public Public: no authentication

Responses

CLI WebSocket test page

Returns an HTML page for manually testing CLI WebSocket connections. Intended for development and diagnostics only. No authentication required.

Public Public: no authentication

Responses

Spin up a container session

Provisions a new container session on the requested backend and size. The organization and environment are resolved from the session; the caller never passes `org_id`. The backend and size must be within the org/project execution policy. Optionally binds the session to a project (applies the per-project policy override). Returns immediately with the session record; the container transitions to `running` asynchronously.

Auth Session JWT (Bearer)

Request Body

Responses

Get container token JWKS

Returns the Ed25519 public key set (JWKS) used to verify container connect tokens and data tokens offline (alg=EdDSA). Serves the public key only: the private signing key is never reachable here. Returns an empty key set (200) when no key is configured so a verifier always receives a well-formed JWKS. Cache-Control is set to `public, max-age=300`; verifiers should refresh after that window.

Public Public: no authentication

Responses

Get container session status

Returns the current status and metadata for a container session. Sessions belonging to another organization are reported as `404 NOT_FOUND` (anti-enumeration).

Auth Session JWT (Bearer)

Parameters

Responses

Tear down a container session

Gracefully stops the container and marks the session as torn down. An optional `reason` query parameter is recorded in the audit trail.

Auth Session JWT (Bearer)

Parameters

Responses

Issue a connect ticket and UI token

Issues a one-time WebSocket connect ticket and a short-TTL Ed25519 UI connect token for the specified session. The ticket is a single-use opaque capability redeemed by the in-container gateway on the WebSocket upgrade; the connect token is an Ed25519 JWT presented to the gateway. Both are bound to the calling user and the session id. The session must be in `running` or `idle` state and must belong to the calling user's org/env. Also returns the public gateway URL (`endpoint`) when the ingress domain is configured.

Auth Session JWT (Bearer)

Parameters

Responses

Get org container execution policy

Returns the organization-wide container execution policy (allowed backends, sizes, default backend/size, idle settings, billing mode, residency constraints, and the master on/off toggle). The organization is resolved from the session.

Auth Session JWT (Bearer)

Responses

Set org container execution policy

Replaces the organization-wide container execution policy. All fields are optional; absent fields are left unchanged. `containers_enabled: false` disables container provisioning for every member of the org and environment.

Auth Session JWT (Bearer)

Request Body

Responses

Get per-project container policy override

Returns the per-project container execution policy override. When no override is set all fields are null, meaning the project inherits the org policy.

Auth Session JWT (Bearer)

Parameters

Responses

Set per-project container policy override

Replaces the per-project container execution policy override. Pass `clear: true` to delete the override and fall back to the org policy. Setting a field to `null` means "inherit the org value". `allowed_backends` and `allowed_sizes` must be subsets of the org policy's allow-sets (validated server-side).

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Get SaaS package container config

Returns the container configuration for a SaaS package, including whether containers are enabled and which backends and sizes the package's subscribers may use.

Auth Session JWT (Bearer)

Parameters

Responses

Set SaaS package container config

Replaces the container configuration for a SaaS package. Controls which backends and sizes the package's subscribers may use and whether containers are enabled for that package at all.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Set container resale pricing for a SaaS package

Sets the per-hour resale credit cost for a specific backend + size combination for a SaaS package. This markup is charged to the package's subscribers when they use containers with that combination.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

List container size catalog

Returns the container size catalog entries available to the caller's organization, including CPU, memory, and per-hour credit cost for each size and backend combination.

Auth Session JWT (Bearer)

Responses

Provision a sandbox container

Provision a new Cloudflare Container DO sandbox session. Generates a session ID, registers billing, and starts the container. The orgId is prepended to all R2 artifact paths to prevent cross-org IDOR. The caller needs `project.update` permission when a `project_id` is provided.

Auth Session JWT (Bearer)

Request Body

Responses

List sandbox artifacts

Lists R2 artifact objects for this sandbox session. Each key is prefixed with the org ID to prevent cross-org object enumeration.

Auth Session JWT (Bearer)

Parameters

Responses

Download a sandbox artifact

Downloads a specific named artifact from R2. The `Content-Type` header is enforced based on safe file extension mapping: arbitrary types are not forwarded from R2 metadata to prevent content-type sniffing attacks.

Auth Session JWT (Bearer)

Parameters

Responses

Redirect to remote display (Xpra)

302 redirect to the Xpra remote-display endpoint proxied through `/v1/sandbox/proxy/{sessionId}/xpra/`. Requires the proxy cookie to be set first.

Auth Session JWT (Bearer)

Parameters

Responses

Redirect to Jupyter Lab

302 redirect to the Jupyter Lab endpoint proxied through `/v1/sandbox/proxy/{sessionId}/jupyter/lab`. Requires the proxy cookie to be set first.

Auth Session JWT (Bearer)

Parameters

Responses

Create a sandbox proxy cookie

Mints a short-lived (5-minute) `__Secure-bb_sandbox_proxy` cookie (HttpOnly, Secure, SameSite=None) that authorises transparent proxying through `/v1/sandbox/proxy/{sessionId}/*`. Rate-limited.

Auth Session JWT (Bearer)

Parameters

Responses

Revoke all sandbox proxy cookies for the current user

Invalidates every active `__Secure-bb_sandbox_proxy` HttpOnly cookie previously issued to the authenticated user. Call this on logout or credential rotation.

Auth Session JWT (Bearer)

Responses

Transparent proxy into sandbox container

Transparently proxies any HTTP method into the running Cloudflare Container DO for this session. Authentication is via the `__Secure-bb_sandbox_proxy` cookie issued by `POST /v1/sandbox/proxy-session/{sessionId}`. All traffic is org-scoped at the DO level: the orgId prefix in the container name prevents cross-org IDOR.

Public Public: no authentication

Parameters

Responses

Resume a stopped sandbox session

Re-starts a previously stopped sandbox session and restores its last snapshot. Requires `project.update` permission.

Auth Session JWT (Bearer)

Parameters

Responses

Get sandbox snapshot metadata

Returns metadata for the most recent R2 snapshot of this sandbox session, if one exists.

Auth Session JWT (Bearer)

Parameters

Responses

Get sandbox session status

Returns the live status of a sandbox session, including container state, whether the session can be resumed, and sandbox-specific metadata.

Auth Session JWT (Bearer)

Parameters

Responses

Tear down a sandbox session

Stops the container, finalises billing, and deletes the session. Requires `project.update` permission.

Auth Session JWT (Bearer)

Parameters

Responses

Sandbox terminal action

Perform a terminal action inside the sandbox: create a named multiplexed terminal, write input, read pending output, or execute a one-shot command. Requires `project.update` permission.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Redirect to VS Code server

302 redirect to the VS Code code-server endpoint proxied through `/v1/sandbox/proxy/{sessionId}/code-server/`. Requires the proxy cookie to be set first via `POST /v1/sandbox/proxy-session/{sessionId}`.

Auth Session JWT (Bearer)

Parameters

Responses

List terminal sessions

Returns a filtered list of the user's terminal sessions for the authenticated org.

Auth Session JWT (Bearer)

Parameters

Responses

Create a terminal session

Registers a new CLI/IDE terminal session and returns a one-time producer ticket used to upgrade the WebSocket connection at `GET /v1/terminal/ws`.

Auth Session JWT (Bearer)

Request Body

Responses

Join a terminal session as a consumer

Returns a single-use consumer ticket that authorises a read-only (or read-write if `can_input` is true) WebSocket connection to the terminal session DO.

Auth Session JWT (Bearer)

Parameters

Responses

Mark a terminal session as active after resumption

Flips a previously-terminated session back to `active` status after the host extension has successfully reconnected. Optionally updates the extension instance ID.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Resume a terminal session

Returns the resume argv and a fresh producer ticket to reconnect the producer WebSocket for a previously disconnected session.

Auth Session JWT (Bearer)

Parameters

Responses

Terminate a terminal session

Marks a terminal session as terminated and closes the associated WebSocket connections.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Terminal session WebSocket upgrade

Upgrades to a WebSocket connection routed to the `TerminalSessionDO` for the given session. The one-time ticket previously issued by `POST /v1/terminal/sessions` (producer) or `POST /v1/terminal/sessions/{id}/join` (consumer) must be passed as the `Sec-WebSocket-Protocol` header value. The ticket is single-use and short-lived; it is consumed on the first valid upgrade and cannot be reused.

Auth One-time ?token= ticket

Parameters

Responses

List tools

Returns a paginated list of tools available to the authenticated org. Optionally filtered by `status`.

Auth Session JWT (Bearer)

Parameters

Responses

Create a tool

Creates a new callable tool for the authenticated org. The `endpoint_url` is validated to prevent SSRF: private IP ranges and localhost are rejected.

Auth Session JWT (Bearer)

Request Body

Responses

Get a tool

Returns the full definition of a specific tool by ID.

Auth Session JWT (Bearer)

Parameters

Responses

Update a tool

Updates an existing tool definition. At least one field must be supplied. The `endpoint_url` is validated to prevent SSRF.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Delete a tool

Permanently deletes a tool. Any Virtual Workers that reference this tool will have it removed from their callable set.

Auth Session JWT (Bearer)

Parameters

Responses

List Virtual Workers

Returns all Virtual Workers accessible to the authenticated user within the current org.

Auth Session JWT (Bearer)

Responses

Create a Virtual Worker

Creates a new Virtual Worker for the authenticated org. The worker is created in `paused` status and must be explicitly resumed before it will process tasks.

Auth Session JWT (Bearer)

Request Body

Responses

Request an autonomy approval

Creates a pending approval request for an action that this worker's autonomy policy requires human sign-off on before proceeding.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Set Virtual Worker autonomy configuration

Configures the worker's autonomy level: which action classes require human approval, which are permitted autonomously, and escalation policies. Approval-required actions are queued to the `/v1/virtual-workers/approvals` surface.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Read a Virtual Worker's calendar

Returns the worker's calendar for a window of local dates: each day's shift status and hours, the worker's holidays, and the events the worker is a party to (an attendee by user or by its inbox address, the organizer, or an event on a calendar the worker owns), with recurring events expanded into instances. Requires read access to the worker. Private and confidential events the caller is not a party to are returned as busy blocks without title or organizer. Descriptions, locations, guest lists, conferencing details and attachments are never returned. An invitation that reached the worker only as an emailed calendar file is not shown (it appears as a message in the worker's inbox). The response is not cacheable.

Auth Session JWT (Bearer)

Parameters

Responses

List Claude Max connections

Returns all Claude Max OAuth connections linked to this Virtual Worker.

Auth Session JWT (Bearer)

Parameters

Responses

Revoke a Claude Max connection

Revokes and deletes a Claude Max OAuth connection from this Virtual Worker.

Auth Session JWT (Bearer)

Parameters

Responses

Complete Claude Max OAuth link

Completes the server-side PKCE token exchange using the authorization code returned by the Claude OAuth callback. The resulting access token is encrypted at rest.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Start Claude Max OAuth link (PKCE)

Initiates PKCE OAuth flow to link a Claude Max account to this Virtual Worker. Returns an authorization URL to redirect the user to, plus a `link_token` to present on completion.

Auth Session JWT (Bearer)

Parameters

Responses

Dispatch next queued task to a Virtual Worker

Claims the next pending task from the worker's dispatch queue, runs the AI turn, records it, and optionally posts the result as a note. Returns `claimed: false` when the queue is empty.

Auth Session JWT (Bearer)

Parameters

Responses

Assign an inbox to a Virtual Worker

Makes an existing BB Mail inbox the worker's email address. The caller needs write access to the worker and owner rights on the inbox: an inbox the caller owns, or one owned by a worker the caller owns. The inbox passes to the worker: the worker becomes its owner, the previous owner's access grant is revoked, and an inbox the worker had before passes back to the worker's owner. Assigning the worker's current inbox again changes nothing. An inbox that belongs to another worker is refused (`409 CONFLICT`), and so is an inbox that is a person's sign-in address (`403 FORBIDDEN`). A worker or inbox the caller cannot see answers `404 NOT_FOUND`.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

List Virtual Worker holidays

Returns all configured holiday dates for a Virtual Worker. The worker will not process tasks on holiday dates.

Auth Session JWT (Bearer)

Parameters

Responses

Add a holiday to a Virtual Worker

Adds a specific date on which the Virtual Worker will not process tasks.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Delete a Virtual Worker holiday

Removes a previously-added holiday date from the worker.

Auth Session JWT (Bearer)

Parameters

Responses

Create an inbox for a Virtual Worker

Creates a new BB Mail inbox owned by the worker and makes it the worker's email address, in one transaction: either both happen or neither does. The caller needs worker management permission, permission to create documents, and write access to the worker; the caller does not become an owner of the new inbox. The domain must be one of the organization's domains with verified ownership. An inbox the worker had before passes back to the worker's owner.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Give a Virtual Worker's account its own authenticator

A virtual worker signs in to Backbuild as its own account, and every account must have a second factor, so a worker without one cannot use the app. This call enrols an authenticator (TOTP) factor on the worker's account. The secret is generated and stored by Backbuild and is never returned. Safe to repeat: when the worker already has an active authenticator, nothing changes and `enrolled` is false. Enrolling a factor signs the worker's account out of its other sessions (`sessions_revoked`), so run it before starting work rather than during a turn. Only works on a virtual worker's account, never a person's. Requires the permission to manage virtual workers; every enrolment is recorded in the audit log.

Auth Session JWT (Bearer)

Parameters

Responses

Run a task on a Virtual Worker (direct)

Synchronously runs a real AI turn against this Virtual Worker using the worker's system prompt, tools, and Claude Max connection. Records the turn via the worker session. Returns the AI response and token usage.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Read a Virtual Worker's tool and model fallback policy

A runtime policy says which coding tool and model a worker's turn uses first, and what it falls back to when that tool is unavailable (out of usage, rate-limited, or without a working account). A skill can carry its own policy; a skill without one inherits the worker's default policy. Returns the policy for one skill (with `skill_id`) or the worker's default (without it), the policy that is actually in effect, and each linked tool's availability right now, so a person choosing a fallback can see which tools are up. Requires the permission to manage virtual workers and access to this worker.

Auth Session JWT (Bearer)

Parameters

Responses

Set a Virtual Worker's tool and model fallback policy

A runtime policy says which coding tool and model a worker's turn uses first, and what it falls back to when that tool is unavailable (out of usage, rate-limited, or without a working account). A skill can carry its own policy; a skill without one inherits the worker's default policy. With `skill_id`, sets that skill's policy; without it, sets the worker's default that every skill without its own policy inherits. A null `runtime_policy` clears it, back to inheriting. The server checks every tool, model and effort against the model catalog (`GET /v1/virtual-workers/agent-tool-models`) and against the coding tools linked to this worker, so a policy can only name what the worker can actually use. Every change is recorded in the audit log with the policy before and after.

Auth Session JWT (Bearer)

Parameters

Request Body

{
  "runtime_policy": {
    "preferred": {
      "tool": "claude_code",
      "model": null,
      "effort": null
    },
    "fallbacks": [
      {
        "tool": "codex"
      },
      {
        "tool": "any"
      }
    ]
  }
}

Responses

List Virtual Worker shares

Returns all active capability shares for this Virtual Worker, including cross-org shares.

Auth Session JWT (Bearer)

Parameters

Responses

Create a Virtual Worker share

Grants a specific capability of this Virtual Worker to a target user, org, or public. Use `scope: 'public'` to enable org-external invocation.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Revoke a Virtual Worker share

Revokes a previously-granted capability share. Effective immediately: in-flight tasks already dispatched via the share may still complete.

Auth Session JWT (Bearer)

Parameters

Responses

Set Virtual Worker shift schedule

Configures the worker's active-hours schedule. Tasks outside the shift window are deferred until the next shift start.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Set Virtual Worker status

Pause, resume, or retire a Virtual Worker. A `retired` worker cannot be re-activated.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Set Virtual Worker usage policy

Configures weekly credit targets and hard thresholds for this worker. When the hard threshold is reached, the worker is automatically paused.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

List the coding-tool model catalog

Lists the models each coding tool can run, with the label to show, the reasoning efforts it accepts, its default effort, and whether the model has been verified to work. This is the catalog a runtime policy is checked against. Any active member of an organization can read it.

Auth Session JWT (Bearer)

Parameters

Responses

List pending worker approvals

Returns worker autonomy approval requests pending human decision. Filtered to the authenticated org. Optional `status` query parameter.

Auth Session JWT (Bearer)

Parameters

Responses

Decide on a worker approval request

Approves or declines a pending worker approval request. A declined request causes the worker to receive an autonomy denial on the in-progress task.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Create a worker channel binding

Binds a Virtual Worker to an inbound channel (helpdesk, chat, SaaS package, or project). Tasks arriving on the bound channel are routed to this worker's dispatch queue. Requires worker management permission and write access to the worker. An email binding is not created here: assign an inbox with `POST /v1/virtual-workers/{id}/email` or create one with `POST /v1/virtual-workers/{id}/mailbox`.

Auth Session JWT (Bearer)

Request Body

Responses

List Virtual Worker sessions

Returns container sessions associated with Virtual Workers. Optionally filtered by `virtual_worker_id`.

Auth Session JWT (Bearer)

Parameters

Responses