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

Ignored. The server generates its own request ID (req-<uuid>) for every request and returns it in the X-Request-ID response header and the body's request_id.

Required string length: 1 - 128
Idempotency-Key
string

Optional key that makes POST /executions safe to retry: 1 to 64 printable ASCII characters without whitespace. Resubmitting the same key with identical parameters returns the same execution in its current state instead of starting a new one; the same key with different parameters returns 400 Execution.IdempotentParameterMismatch. A key that is empty or not 1 to 64 printable ASCII characters returns 400 Execution.InvalidRequest. The key is remembered for a limited time after the execution reaches a terminal state; after that, the same key starts a new execution.

Required string length: 1 - 64

Query Parameters

wait
boolean
default:false

Wait for a terminal result before responding. Defaults to false. Must be true or false; any other value returns 400 Execution.InvalidRequest.

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. Only valid together with wait=true (otherwise 400 Execution.InvalidRequest); a value outside 1..25 or not an integer returns 400 Execution.InvalidWaitTimeout.

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.

request_id
string
required

Server-generated request ID (req-<uuid>), identical to the X-Request-ID response header.

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. timed_out means the per-command time limit (execution_timeout_seconds) was reached and the command was terminated (SIGTERM, then SIGKILL after a grace period); exit_code is then null.

Available options:
pending,
running,
cancelling,
succeeded,
failed,
cancelled,
timed_out
exit_code
integer<int32> | null
required

Exit status of the command. A command killed by a signal (for example an out-of-memory kill) reports 128 + signal (137 for SIGKILL) with status failed and no termination_reason. Null while non-terminal, and when the execution was cancelled, timed out, or its runtime was terminated.

stdout
string | null
required

Captured standard output, or null while not yet available. At most 1 MiB is kept; further output is dropped and stdout_truncated is true.

stderr
string | null
required

Captured standard error, or null while not yet available. At most 1 MiB is kept; further output is dropped and stderr_truncated is true.

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

Why an execution that did not finish on its own ended. Omitted when the command exited by itself, including when it was killed by a signal from inside the sandbox (see exit_code). explicit_cancel: the execution was cancelled (status cancelled). execution_timeout: the execution reached its timeout (status timed_out). runtime_terminated: the command's process is gone without having reported an outcome, for example the sandbox was resumed from a pause without memory, or its output stream was lost for good, so the outcome of the command is unknown (status failed). Pausing a sandbox does not by itself end an execution: after a pause with memory the command continues and the execution reports its real result.

Available options:
explicit_cancel,
execution_timeout,
runtime_terminated
Example:

"runtime_terminated"

failure_reason
enum<string>

Classified process startup failure. Omitted when no recognized startup cause is available. cwd_not_found means the working directory does not exist; cwd_not_directory means the working directory is not a directory; permission_denied means startup was denied without a reliably identified operation. Contains no path or raw upstream error. Runtime interruptions use termination_reason.

Available options:
cwd_not_found,
cwd_not_directory,
permission_denied