Sandboxes
A sandbox is the container a coding session runs in: which applications it clones and starts, in what order, and its image, size and environment variables. Create, update and delete sandboxes, choose the workspace's default, and set the attached applications and their startup order. See Sandboxes.
List sandboxes in a workspace
Returns the workspace's sandboxes - reusable workspace-container specs (image, size, sidecar env, environment variables with secret values masked). The runnable config lives on the attached Applications, surfaced as the ordered applicationIds. As an MCP tool it is offered to Owners and Admins, on their own AI assistant.
path Parameters
workspaceIdWorkspace UUID
query Parameters
pagePage number (1-indexed, default 1)
limitItems per page (default 50)
sortByField to sort by
sortOrderSort direction (default desc)
searchFull-text search across searchable fields
List sandboxes in a workspace › Responses
List of sandboxes
Create a sandbox
Create a reusable sandbox (container image URI + resource hints + sidecar env). Attach Applications separately. Needs sandbox:create (Owner, Admin, Power User and Developer by default).
path Parameters
workspaceIdWorkspace UUID
Create a sandbox › Request Body
namedescriptionsizeSandbox size: small (2 vCPU, 8 GB), medium (4 vCPU, 16 GB) or large (8 vCPU, 32 GB)
isDefaultCreate a sandbox › Responses
Created sandbox
Get a sandbox by ID
Returns one sandbox: its size, its environment variables (secret values masked) and the ids of the applications it runs, in startup order. As an MCP tool it is offered to Owners and Admins, on their own AI assistant.
path Parameters
workspaceIdWorkspace UUID
idSandbox UUID
Get a sandbox by ID › Responses
Sandbox details
Update a sandbox
Update name, image, env vars, resource hints, or default flag. A secret env entry sent with an empty value preserves the stored secret. Needs sandbox:update (Owner, Admin, Power User and Developer by default).
path Parameters
workspaceIdWorkspace UUID
idSandbox UUID
Update a sandbox › Request Body
namesizeSandbox size: small (2 vCPU, 8 GB), medium (4 vCPU, 16 GB) or large (8 vCPU, 32 GB)
isDefaultUpdate a sandbox › Responses
Updated sandbox
Delete a sandbox
Sessions referencing it fall back to the workspace default (FK ON DELETE SET NULL). Needs sandbox:delete (Owner, Admin, Power User and Developer by default).
path Parameters
workspaceIdWorkspace UUID
idSandbox UUID
Delete a sandbox › Responses
Deleted
Set the ordered applications attached to a sandbox
Replaces the sandbox's attached applications with the given ordered list (array order = startup order). Needs sandbox:update (Owner, Admin, Power User and Developer by default). A session's credential is refused with 403: every later session on the sandbox takes these applications' repositories and base branches. As an MCP tool it is offered to Owners and Admins, on their own AI assistant.
path Parameters
workspaceIdWorkspace UUID
idSandbox UUID
Set the ordered applications attached to a sandbox › Request Body
applicationIdsEvery application the sandbox runs, by id (from list-applications), in startup order: the first starts first. Replaces the whole list, so send the ones to keep too; [] detaches them all. New sessions on the sandbox take these applications' repositories, and the first one's base branch is what their pull requests merge into. At most 50.
Set the ordered applications attached to a sandbox › Responses
Updated sandbox
Set a sandbox's size
Sets the sandbox's size: small (2 vCPU, 8 GB), medium (4 vCPU, 16 GB) or large (8 vCPU, 32 GB). The new size applies from the sandbox's next hosted run, which starts on a new machine and continues from the work the coding agent pushed to the session's branch; a run already going keeps its size. Sandbox time is billed at the size's own rate. Owner and Admin only: needs configuration-tools:manage as well as sandbox:update. A coding session's token is refused with 403. Answers the updated sandbox.
path Parameters
workspaceIdWorkspace UUID
idSandbox UUID
Set a sandbox's size › Request Body
sizesmall (2 vCPU, 8 GB), medium (4 vCPU, 16 GB) or large (8 vCPU, 32 GB). Applies from the sandbox's next hosted run, which starts on a new machine and continues from the work the coding agent pushed: a run already going keeps its size. Sandbox time is billed at the size's own hourly rate.
Set a sandbox's size › Responses
The updated sandbox, secret values masked
Change a sandbox's environment variables
Adds, replaces and removes the sandbox's own environment variables by key, which every session in the sandbox gets beside its applications' own: set adds a key or replaces it, remove deletes one, and every variable not named is kept as it is. A secret is stored encrypted and never shown again. Leaving secret out keeps a variable's kind, and leaving a secret's value out keeps its stored value. Refused with 400: a secret with no value to keep, a secret made plain without a new value, a key in both set and remove, and more than 100 variables in the result. Owner and Admin only: needs configuration-tools:manage as well as sandbox:update. A coding session's token is refused with 403. Answers the updated sandbox, secret values masked.
path Parameters
workspaceIdWorkspace UUID
idSandbox UUID
Change a sandbox's environment variables › Request Body
Variables to add, or to replace by key, each { key, value?, secret? }. A key already stored is replaced in place; a new one is added at the end. Every key once.
removeKeys to delete. A key that is not set is ignored. A key cannot be in both set and remove.
Change a sandbox's environment variables › Responses
The updated sandbox, secret values masked