curl --request POST \
--url https://{sandbox_key}.{domain}/shell/control \
--header 'Content-Type: application/json' \
--header 'X-Access-Token: <api-key>' \
--data '
{
"action": "resize",
"cols": 120,
"rows": 32
}
'{
"request_id": "req-7f3c",
"sandbox_key": "sandbox-key",
"status": "attached"
}Control the sandbox shell (resize / close)
Out-of-band control channel for the shell. Control commands never travel over the WebSocket; this is a plain HTTP call and works from any replica.
action=resizeapplies a new terminal size to the live PTY. It requires an active attach (otherwise409 Shell.NotAttached).action=closeirrevocably terminates the shell: the PTY is killed, the state is deleted, and any existing WebSocket is severed within about one second. The old shell can never be re-attached; the nextPOST /shellcreates a brand-new session. Close does not require an active connection.
Unknown action values or extra fields are rejected with
400 Shell.InvalidRequest.
curl --request POST \
--url https://{sandbox_key}.{domain}/shell/control \
--header 'Content-Type: application/json' \
--header 'X-Access-Token: <api-key>' \
--data '
{
"action": "resize",
"cols": 120,
"rows": 32
}
'{
"request_id": "req-7f3c",
"sandbox_key": "sandbox-key",
"status": "attached"
}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
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.
1 - 128Body
Exactly one control command:
action=resizerequirescolsandrows(each 1..1000) and an active WebSocket attach.action=closetakes no other fields and does not require an active connection. Unknownactionvalues or extra fields are rejected with400 Shell.InvalidRequest.
resize applies a new terminal size to the live PTY; close
irrevocably terminates the shell (PTY killed, state deleted, any
existing WebSocket severed within about one second).
resize, close Terminal width in columns. Required when action=resize; must be omitted for close.
1 <= x <= 1000Terminal height in rows. Required when action=resize; must be omitted for close.
1 <= x <= 1000Response
Control applied. status=attached after a successful resize;
status=closed after a successful close.
Server-generated request ID (req-<uuid>), identical to the X-Request-ID response header.
Echo of the data-plane addressing key (i.e. sandbox_key, the leftmost label of the request host).
Public status of the sandbox shell session.
creating: a launch is in progress (only appears with202).ready: the PTY exists and can be attached.attached: the shell exists and currently has an active WebSocket connection (a second attach would get409).closed: the shell has been terminated byaction=closeand can never be re-attached.
creating, ready, attached, closed