Execute a command in a sandbox
Starts an asynchronous shell execution in the sandbox. The request body keeps the
action=exec and parameters shape used by the runtime contract. The effective URL is
the sandbox data-plane host; the sandbox ID is obtained from the leftmost Host label and
is not repeated in the path. The endpoint does not include the control-plane /api/v2 prefix.
When wait=true, the server waits for a terminal result for at most
wait_timeout_seconds seconds; a timeout returns 202 without canceling the execution.
Authorizations
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
Optional request correlation identifier echoed in the response.
1 - 128Query Parameters
Wait for a terminal result before responding. Defaults to false.
Maximum time to wait when wait=true, in seconds. Values from 1 through 25
are accepted. A wait timeout never cancels the execution.
1 <= x <= 25Body
Response
Execution completed within the requested wait window.
Echo of the data-plane addressing key (i.e. sandbox_key; the data plane identifies the instance by the key in the host).
Public lifecycle status of a sandbox execution.
pending, running, canceling, succeeded, failed, canceled Process exit code; null while non-terminal or when canceled.
Captured standard output, or null while not yet available.
Captured standard error, or null while not yet available.
Echo of X-Request-ID when supplied.