> ## 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. # Execute Sandbox command > Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. With `stream: true` the output arrives as the command writes it, as newline-delimited JSON (`application/x-ndjson`): `{"type":"started"}`, then `{"type":"stdout"|"stderr","data":"..."}` per chunk, and last `{"type":"exit",...}` (the synchronous result without stdout/stderr) or `{"type":"error","error":"...","message":"..."}`. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. A command sent while the sandbox is still starting (right after a resume) waits up to 60s for it to be ready instead of failing; 409 boat_starting (retryable) is returned only if it is still not ready by then. A sandbox that is not starting (`error`, `stopped`) returns 409 sandbox_not_ready with `retryable: false` and its `state` at once: resume or recover it first. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox. ## OpenAPI ````yaml openapi/boat-v1.yaml POST /sandboxes/{sandboxId}/commands 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/{sandboxId}/commands: post: tags: - Boat summary: Execute a command in a sandbox description: >- Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/sandboxes/{sandboxId}/commands/{processId}` for status and logs. With `stream: true` the output arrives as the command writes it, as newline-delimited JSON (`application/x-ndjson`): `{"type":"started"}`, then `{"type":"stdout"|"stderr","data":"..."}` per chunk, and last `{"type":"exit",...}` (the synchronous result without stdout/stderr) or `{"type":"error","error":"...","message":"..."}`. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. A command sent while the sandbox is still starting (right after a resume) waits up to 60s for it to be ready instead of failing; 409 boat_starting (retryable) is returned only if it is still not ready by then. A sandbox that is not starting (`error`, `stopped`) returns 409 sandbox_not_ready with `retryable: false` and its `state` at once: resume or recover it first. Command execution is never retried automatically: a 502 boat_direct_failed means the command may already be running on the sandbox. operationId: command parameters: - $ref: '#/components/parameters/SandboxId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CommandRequest' responses: '200': description: >- Command result (synchronous), process start confirmation (detached), or the output stream (`stream: true`). content: application/json: schema: oneOf: - $ref: '#/components/schemas/CommandResponse' - $ref: '#/components/schemas/CommandStartedResponse' application/x-ndjson: schema: $ref: '#/components/schemas/CommandStreamFrame' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' components: parameters: SandboxId: name: sandboxId in: path required: true schema: type: string pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$ description: Public Sandbox id returned by create/list/get sandbox calls. schemas: CommandRequest: type: object required: - command properties: command: type: string cwd: type: string description: Relative working directory inside the sandbox work directory. timeoutSeconds: type: integer minimum: 1 maximum: 600 default: 30 description: >- Command timeout in seconds. Values outside 1-600 are rejected with a 400 invalid_timeout error. detached: type: boolean default: false description: >- Start the command in the background and return a process id immediately instead of waiting for it to finish. Output goes to a log file on the sandbox; poll the status endpoint for it. stream: type: boolean default: false description: >- Stream the output as the command writes it: the response is newline-delimited JSON (application/x-ndjson), one CommandStreamFrame per line. Ignored with detached. CommandResponse: allOf: - $ref: '#/components/schemas/SuccessBase' - type: object required: - success - exitCode - stdout - stderr - timedOut properties: type: type: string const: command.finished success: type: boolean exitCode: type: - integer - 'null' signal: type: - string - 'null' oomKilled: type: boolean description: >- True when the memory ceiling killed the command or one of its processes and the command failed. stdout: type: string stderr: type: string stdoutTruncated: type: boolean stderrTruncated: type: boolean timedOut: type: boolean cwd: type: string startedAt: type: string format: date-time finishedAt: type: string format: date-time CommandStartedResponse: allOf: - $ref: '#/components/schemas/SuccessBase' - type: object required: - success - processId - pid - command - startedAt properties: type: type: string const: command.started success: type: boolean processId: type: integer description: Process id to poll with the command status endpoint. pid: type: integer command: type: string cwd: type: string startedAt: type: string format: date-time logPath: type: string description: Stdout log file on the sandbox (~/.ascii/processes/.log). errLogPath: type: string description: Stderr log file on the sandbox. CommandStreamFrame: type: object description: >- One line of a streamed command. `started` first, then `stdout`/`stderr` chunks, then exactly one `exit` (the synchronous result, without stdout/stderr) or `error`. required: - type properties: type: type: string enum: - started - stdout - stderr - exit - error data: type: string description: 'stdout/stderr: the chunk of output, UTF-8.' exitCode: type: - integer - 'null' success: type: boolean timedOut: type: boolean error: type: string message: type: string retryable: type: boolean description: >- error: true when the command provably never ran (the sandbox is still restoring its disk), so sending it again is safe. SuccessBase: type: object required: - ok - type properties: ok: type: boolean examples: - true type: type: string description: Stable success envelope discriminator added by v1. 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: BadRequest: description: Invalid request body or parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: invalid: value: ok: false type: sandbox.error status: 400 code: invalid_json message: Request body must be valid JSON. error: code: invalid_json message: Request body must be valid JSON. status: 400 requestId: req_01HX... 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... NotFound: description: Resource not found. 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' securitySchemes: BoatBearerAuth: type: http scheme: bearer bearerFormat: sandbox_api_key description: >- Boat bearer token in the form `boat_...`. Service API keys authenticate sandbox operations. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.