Skip to main content
POST
Launch the sandbox interactive shell

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

Body

application/json

Empty object. Any unknown field is rejected with 400 Shell.InvalidRequest.

Response

The shell exists (created by this call, or already present). status=ready means the PTY exists and can be attached; status=attached means the shell exists and currently has an active WebSocket connection (a second attach would get 409).

request_id
string
required

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

sandbox_key
string
required

Echo of the data-plane addressing key (i.e. sandbox_key, the leftmost label of the request host).

status
enum<string>
required

Public status of the sandbox shell session.

  • creating: a launch is in progress (only appears with 202).
  • ready: the PTY exists and can be attached.
  • attached: the shell exists and currently has an active WebSocket connection (a second attach would get 409).
  • closed: the shell has been terminated by action=close and can never be re-attached.
Available options:
creating,
ready,
attached,
closed
connect_url
string
required

Relative path of the WebSocket attach endpoint. The full attach address is wss://{sandbox_key}.{domain}{connect_url} — the same data-plane host this request was sent to, with the scheme switched to wss. This is always the sandbox's own data-plane endpoint.

Example:

"/shell/connect"