Containers & Virtual Workers

CLI WebSocket connect

Upgrades to a WebSocket connection routed to the `CLIController` Durable Object. 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

Pull the next agent task for a Virtual Worker session

The in-pod agentic CLI runner pulls the task dispatched to this session. The session is resolved from the verified data token (IDOR guard). Requires scope `agent.task.read`. Returns `null` when no task is pending.

Auth Container data token

Responses

Report Virtual Worker task completion

The in-pod runner reports the task result. `virtual_worker_id` and `worker_task_id` come from the task pull; the server re-validates both belong to this session (any mismatch is a 4xx). Requires scope `agent.task.complete`. Bridges to the cron-gated completion stored procedure using a platform-side credential the agent never holds.

Auth Container data token

Request Body

Responses

Get the agent's own container session status

Returns the container session record for the calling agent's own session. The session id is taken from the verified data token — the agent cannot read another session by guessing an id. Authorized by the container data token.

Auth Container data token

Responses

Read back the agent's own session log

Lists and concatenates the persisted NDJSON chunks for the calling agent's own session in chunk-sequence order. The org and session prefix are derived from the verified data token (IDOR guard). Bounded list pagination and a concatenation cap (32 MiB, 2000 chunks) prevent unbounded buffering; `truncated: true` signals that more chunks remain.

Auth Container data token

Responses

Append a session-log chunk

Writes one immutable NDJSON chunk of `SessionLogEvent` records to the session's R2 log store. The org and session prefix are derived from the verified data token — the agent can only write under its own session prefix. Requires scope `terminal.activity.write`. An optional monotonic `chunk_seq` may be supplied as a query parameter or `x-session-log-chunk-seq` header to derive the object key; if omitted the key is the SHA-256 of the body (idempotent re-POST). Max size is enforced via `Content-Length` pre-check and a buffered re-check.

Auth Container data token

Parameters

Request Body

Array of `SessionLogEvent` objects. Max 1 MiB total.

Responses

List container sizes (data-plane, read context)

Returns the container size catalog for the calling agent's organization. Provisioning new containers is denied to delegated actors. Authorized by the container data token.

Auth Container data token

Responses

Append a terminal activity batch

Writes one bounded batch of already-redacted terminal `ActivityEvent` records to the activity index. The batch's `containerSessionId` must match the principal's own session id. Requires scope `terminal.activity.write`.

Auth Container data token

Request Body

Responses

Append a terminal bulk-transcript segment

Writes one immutable terminal bulk-transcript segment (redacted NDJSON, ≤16 MiB) to R2 keyed by the principal's org/session prefix, then records the R2 key and advances the monotonic segment watermark in the database. `transcript_seq` is required; `terminal_id` is optional but recommended. Both may be supplied as query parameters or the `x-terminal-id` / `x-transcript-seq` headers. Requires scope `terminal.activity.write`.

Auth Container data token

Parameters

Responses

Get the in-container agent's own identity

Returns the resolved identity of the in-container agent — user id, org id, environment id, session id, and delegated scope set — derived offline from the verified data token. No database call is made. Authorized by the container data token.

Auth Container data token

Responses

Fetch code-API config for a CF sandbox container

Used by a Cloudflare sandbox container to retrieve its per-session code-API configuration (bridge URL and short-TTL bridge token). The container presents its `x-bb-config-fetch` credential in a request header; the API validates it against the session's stored hash via the backing Durable Object. Returns only `{ bridge_url, token }` — never the secret reference or refresh credential. `Cache-Control: no-store` is always set. Returns `401` for an invalid/missing credential and `404` for an unknown size or session.

Public Public: no authentication

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

Sandbox egress proxy (GET)

Proxies an HTTP GET from the sandbox to an external domain. The target URL must be supplied via the `x-bb-egress-target` header or the `target` query parameter. The domain is validated against the org's egress allowlist, and egress byte usage is reserved before forwarding. Requires `project.update` permission.

Auth Session JWT (Bearer)

Parameters

Responses

Sandbox egress proxy (POST)

Proxies an HTTP POST from the sandbox to an external domain. Same domain allowlist and quota reservation as GET. Requires `project.update` permission.

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

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 email mailbox to a Virtual Worker

Binds a bbmail mailbox to this Virtual Worker so incoming messages create tasks in the worker's dispatch queue.

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

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

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 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, email, SaaS package, or project). Tasks arriving on the bound channel are routed to this worker's dispatch queue.

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