Skip to main content
POST
Execute a command in a sandbox

Authorizations

X-Access-Token
string
header
required

Sandbox data-plane token — the sandbox_access_token returned by the create/connect endpoints. Used for /files, Sandbox-Exec, and other data-plane endpoints; the control plane (/api/v2) does not accept it, and conversely the control plane's Authorization: Bearer is invalid on the data plane.

The token is bound to its sandbox: using sandbox A's token against sandbox B's host fails. It stays valid until the sandbox's lifetime ends; there is no separate rotation endpoint (rotate_traffic_token rotates the port traffic token traffic_access_token and does not affect this one).

Headers

X-Request-ID
string

Optional request correlation identifier echoed in the response.

Required string length: 1 - 128

Query Parameters

wait
boolean
default:false

Wait for a terminal result before responding. Defaults to false.

wait_timeout_seconds
integer
default:25

Maximum time to wait when wait=true, in seconds. Values from 1 through 25 are accepted. A wait timeout never cancels the execution.

Required range: 1 <= x <= 25

Body

application/json
action
enum<string>
required

Execution action. The sealed data plane currently supports exec only.

Available options:
exec
parameters
object
required

Response

Execution completed within the requested wait window.

execution_id
string<uuid>
required
sandbox_id
string
required

Echo of the data-plane addressing key (i.e. sandbox_key; the data plane identifies the instance by the key in the host).

status
enum<string>
required

Public lifecycle status of a sandbox execution.

Available options:
pending,
running,
canceling,
succeeded,
failed,
canceled
exit_code
integer<int32> | null
required

Process exit code; null while non-terminal or when canceled.

stdout
string | null
required

Captured standard output, or null while not yet available.

stderr
string | null
required

Captured standard error, or null while not yet available.

stdout_truncated
boolean | null
required
stderr_truncated
boolean | null
required
started_at
string<date-time> | null
required
completed_at
string<date-time> | null
required
request_id
string

Echo of X-Request-ID when supplied.