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.
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
Body
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.
Response
Control applied. status=attached after a successful resize;
status=closed after a successful close.
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