> ## Documentation Index > Fetch the complete documentation index at: https://docs.boat.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create sandbox > Provision a new cloud computer. Store the returned `sandbox.id` with your product job/session record. Send an `Idempotency-Key` header to make this call safe to retry after a lost response without creating a second billable sandbox. ## OpenAPI ````yaml openapi/boat-v1.yaml POST /sandboxes openapi: 3.1.0 info: title: Boat Public API v1 version: 1.0.0 description: > Public JSON API for creating, operating, prompting, observing, and exposing sandboxes from backend services, CI jobs, hosted workers, and Boat automation products. The v1 reference intentionally documents the developer integration surface only. Dashboard billing actions are not part of v1. servers: - url: https://boat.dev/api/v1 security: - BoatBearerAuth: [] tags: - name: Boat description: >- Unified Boat account, setup, lifecycle, prompting, event history, desktop access, and SSH operations. paths: /sandboxes: post: tags: - Boat summary: Create sandbox description: >- Provision a new cloud computer. Store the returned `sandbox.id` with your product job/session record. Send an `Idempotency-Key` header to make this call safe to retry after a lost response without creating a second billable sandbox. operationId: create parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/OrgId' - $ref: '#/components/parameters/OrgHeader' requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/CreateSandboxRequest' responses: '202': description: Boat accepted for provisioning. content: application/json: schema: $ref: '#/components/schemas/CreateSandboxResponse' examples: provisioning: value: ok: true type: sandbox.created status: provisioning ttlSeconds: 3600 sandbox: id: bx_23456789 name: Sandbox 2026-05-31 12:00 state: provisioning url: null ip: null createdAt: '2026-05-31T12:00:00Z' updatedAt: '2026-05-31T12:00:00Z' archiveAfter: '2026-05-31T13:00:00Z' desktopAvailable: false desktopUrl: null snapshotAvailable: false snapshotCompletedAt: null '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 description: >- Optional exactly-once key for creating a sandbox. Send your own opaque, account-unique value (a UUID) to make `POST /sandboxes` safe to retry when the response is lost (network timeout, 5xx): the first request creates the sandbox and binds it to the key; every later request with the **same account, key, and request body** returns that same sandbox instead of creating a second, billable one. Behavior: keys are retained for **24 hours**; a concurrent or early retry while the first sandbox is still being minted returns `409` `idempotency_in_progress` (retry shortly, same key); reusing a key with a **different body** returns `409` `idempotency_key_reused`; timeouts and 5xx are safe to retry with the same key; a create that fails before the sandbox exists releases the key within ~2 minutes so a retry can create the sandbox. Omit the header to keep the default (non-idempotent) behavior. OrgId: name: org in: query required: false schema: type: string description: >- Billing wallet for this request. A team id you belong to reads that team's limits / bills a create to that team. Your own account id is personal. Sandboxes, snapshots, and environments stay creator-private. OrgHeader: name: X-Boat-Org in: header required: false schema: type: string description: Same as the `org` query parameter. Query wins when both are set. schemas: CreateSandboxRequest: type: object description: Options for provisioning a new cloud computer. properties: type: type: string enum: - small - default - large - xlarge default: default description: >- Machine size. `small` consumes machine time at half rate and `large` at twice the default rate (see the Billing guide). `xlarge` costs $0.20 per running hour, requires the effective $100 plan or higher, and requires an explicit bare-metal operator allocation. A fork inherits the source sandbox's type unless the fork request passes its own, and resume and fork can move a sandbox between sizes. ttlSeconds: oneOf: - type: integer minimum: 1 maximum: 2592000 - type: 'null' default: 3600 description: >- 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. env: type: object additionalProperties: type: string description: >- Per-sandbox environment variables injected into the sandbox's tool environment, on top of the account environment's variables (per-sandbox 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`, `BOAT_ID`, `SERVICE_PREVIEW_TOKEN`, `BOAT_CLI_TOKEN`) are rejected with `invalid_env`. Forked sandboxes inherit the source sandbox's env unless the fork request supplies its own `env`. environment: type: string default: base description: >- Name of the sandbox environment to attach to this sandbox. Environments are managed in the Boat dashboard and bundle the repositories, secrets, and credential toggles a sandbox gets. Omit to use your default environment (`base` unless you changed it). Unknown names are rejected with `unknown_environment`. An environment marked "safe for third parties" passes nothing to the sandbox, exactly like `noEnv`. examples: - base - customer-demos noEnv: type: boolean default: false description: >- Create a sandbox 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 sandboxes. For sandboxes you give to your own users. SSH, SCP, desktop, snapshots, and public URLs still work; pass `env` to give the sandbox a secret of its own. A fork of a no-env sandbox is always no-env. Equivalent to attaching an environment marked "safe for third parties". setupScript: type: string maxLength: 65536 description: >- Shell script that runs on the sandbox after it is ready. Ready means "ready to accept the user", not "setup done": the script starts in the background once provisioning completes and never blocks the sandbox becoming usable. It runs as the sandbox user via `bash`, with the sandbox's environment applied, and its output goes to a log file on the sandbox. Observe the outcome as `setupStatus` (pending/running/done/failed) and `setupError` on the sandbox. Rejected with a 400 `invalid_setup_script` error when it is not a string or exceeds 64KB. org: type: string description: >- Bill this sandbox to a team you belong to (the team's shared wallet). Your own account id means personal billing. Listing, snapshots, and environments stay yours: the org is a wallet, not a shared workspace. Takes precedence over `teamId` and over the `X-Boat-Org` / `?org=` request scope. teamId: type: string description: Legacy alias for `org`. Ignored when `org` is also set. from: type: string description: >- Create the sandbox from a named snapshot (saved with `POST /named-snapshots`, or `boat snapshot ` in the CLI). The sandbox starts from that exact frozen state. Omitting `type` inherits the type the snapshot was saved from; env and no-env inherit from the snapshot's source sandbox unless the request passes its own, with the same rules as forking. examples: - ttlSeconds: 3600 - ttlSeconds: null - type: large ttlSeconds: 3600 - ttlSeconds: 3600 env: DATABASE_URL: postgres://user:pass@host:5432/app FEATURE_FLAG: '1' - ttlSeconds: null noEnv: true CreateSandboxResponse: allOf: - $ref: '#/components/schemas/SuccessBase' - type: object required: - status - ttlSeconds - sandbox properties: type: type: string const: sandbox.created status: type: string enum: - provisioning ttlSeconds: type: - integer - 'null' sandbox: $ref: '#/components/schemas/Sandbox' SuccessBase: type: object required: - ok - type properties: ok: type: boolean examples: - true type: type: string description: Stable success envelope discriminator added by v1. Sandbox: type: object required: - id - name - state - desktopAvailable - snapshotAvailable properties: id: type: string pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$ examples: - bx_23456789 name: type: string examples: - Boat 2026-05-31 12:00 state: type: string enum: - init - provisioning - provisioned - cloning - ready - idle - running - archiving - archived - error type: type: string enum: - small - default - large - xlarge description: >- Current machine size: what the sandbox was created with, or the size it was last resumed or forked onto. Legacy bare-metal sandboxes read as `default`. vcpu: type: integer description: vCPUs guaranteed by this sandbox's type. examples: - 4 memoryGB: type: integer description: RAM in GB guaranteed by this sandbox's type. examples: - 8 billingMultiplier: type: number description: >- Rate at which this sandbox consumes machine time. 0.5 for `small`, 1 for `default`, 2 for `large`, and 50/9 for `xlarge`. examples: - 1 url: type: - string - 'null' format: uri description: Machine URL when assigned. ip: type: - string - 'null' description: Machine IPv6 or IPv4 address when assigned. createdAt: type: - string - 'null' format: date-time updatedAt: type: - string - 'null' format: date-time archiveAfter: type: - string - 'null' format: date-time description: Automatic archival time, or null when auto-stop is disabled. desktopAvailable: type: boolean desktopUrl: type: - string - 'null' format: uri description: Secret-bearing desktop stream URL when available. Redact from logs. snapshotAvailable: type: boolean snapshotCompletedAt: type: - string - 'null' format: date-time description: >- Timestamp of the most recent successfully completed snapshot, or null. subdomain: type: - string - 'null' description: >- The sandbox's stable three-word subdomain slug (e.g. "frazil-pneuma-rallye"), or null before one is assigned. lastSnapshotAttemptAt: type: - string - 'null' format: date-time description: >- Timestamp of the most recent snapshot attempt of any status (queued, in_progress, completed, failed, cancelled), or null. Use with snapshotCompletedAt to detect snapshots that keep failing. lastSnapshotStatus: type: - string - 'null' enum: - queued - in_progress - completed - failed - cancelled - null description: >- Status of the most recent snapshot attempt, or null if none. A value other than completed while snapshotCompletedAt stays stale indicates failing snapshots. setupStatus: type: - string - 'null' enum: - pending - running - done - failed - null description: >- Outcome of the create-time `setupScript`: `pending` (stored, not yet started), `running` (executing on the sandbox in the background), `done` (exit code 0) or `failed` (non-zero exit, or the sandbox lost track of the process). Null when the sandbox was created without a setup script. setupError: type: - string - 'null' description: >- Short failure detail (exit code plus a stderr tail) when `setupStatus` is `failed`; while `pending`, may carry the last start/upload error from a retry in progress. Otherwise null. environment: type: - string - 'null' description: >- Name of the sandbox environment this sandbox is running, or null if it is attached to none (a `noEnv` sandbox, or one whose environment was deleted). A sandbox freezes onto one environment version when it starts and keeps it for life, so this is what the sandbox actually holds, not what the environment says today. examples: - base environmentVersion: type: - integer - 'null' description: >- Version number of `environment` that this sandbox is pinned to. Compare it against the environment's latest version to see whether an upgrade is pending: a sandbox below the latest is still running the older configuration until someone calls `POST /environments/{environmentId}/upgrade`. examples: - 3 ErrorEnvelope: type: object required: - ok - type - status - code - message - error - requestId properties: ok: type: boolean examples: - false type: type: string examples: - sandbox.error status: type: integer examples: - 409 code: type: string examples: - provider_not_configured message: type: string examples: - Prompting is locked until Codex is configured on the Agents page. requestId: type: string examples: - req_01HX... error: type: object required: - code - message - status properties: code: type: string message: type: string status: type: integer details: type: object additionalProperties: true responses: Unauthorized: description: Missing or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: unauthorized: value: ok: false type: sandbox.error status: 401 code: unauthorized message: Unauthorized error: code: unauthorized message: Unauthorized status: 401 requestId: req_01HX... PaymentRequired: description: >- Account cannot currently create or operate sandboxes. The error body may include a dashboard billing URL, but billing actions are not part of the v1 API. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' Conflict: description: Request conflicts with current account or sandbox state. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' RateLimited: description: >- Machine start or concurrent-sandbox limit reached. Create, fork and resume each count as one machine start against your plan's start limits (see the Billing guide; `rate_limited`, naming the window you hit). A sandbox that would exceed your plan's concurrent-sandbox cap is refused with `limit_reached`, or `member_limit_reached` when an organization owner has capped you below the plan. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: BoatBearerAuth: type: http scheme: bearer bearerFormat: sandbox_api_key description: >- Boat bearer token in the form `boat_...`. Service API keys authenticate sandbox operations. ````