v1

latestOpenAPI 3.1.02026-07-22304756.7 KB

Box

Create box

Provision a new cloud computer. Store the returned box.id with your product job/session record.

post/boxes

Request body

ttlSecondsinteger nullable

Number of seconds before automatic archival. null disables auto-stop. The backend also accepts the string infinite for legacy compatibility; new clients should send null.

envobject

Per-box environment variables injected into the box's tool environment, on top of the account environment's variables (per-box values win on conflicts). Keys must match [A-Za-z_][A-Za-z0-9_]{0,127}; at most 100 variables and 64KB total. Reserved names (ASCII_TOKEN, ASCII_API_URL, AGENT_ID, PRODUCT_MODE, ENVIRONMENT_ID, BOX_ID, SERVICE_PREVIEW_TOKEN, BOX_CLI_TOKEN) are rejected with invalid_env. Forked boxes inherit the source box's env unless the fork request supplies its own env.

noEnvboolean

Create a box with none of the secrets attached to your account (no environment variables, secret files, or credentials), confined to itself so it cannot act on your account or other boxes. For boxes you give to your own users. SSH, SCP, desktop, snapshots, and public URLs still work; pass env to give the box a secret of its own. A fork of a no-env box is always no-env.

Example request

{
  "ttlSeconds": 3600
}

Response

Box accepted for provisioning.

okboolean required

type'box.created' required

Stable success envelope discriminator added by v1.

status'provisioning' required

ttlSecondsinteger nullable required

Example response

{
  "ok": true,
  "box": {
    "id": "bx_23456789",
    "name": "Box 2026-05-31 12:00"
  }
}