Documentation
Exec and terminal API reference
Run a command with streamed output, or open the sandbox terminal as a WebSocket. Both need a running sandbox and a token that can change sandboxes.
Run a command
POST /v1/customer/tenants/{tenantId}/sandboxes/{sandboxId}/exec with cmd (required, run as bash -lc), cwd (default /workspace), env (up to 64 variables) and timeout_seconds. The body is at most 128 KiB, and cmd at most 64 KiB.
The answer is application/x-ndjson: {"type":"stdout"|"stderr","data":"<base64>"} lines as output arrives, then one exit line with exit_code, timed_out and truncated. When Runzivo ended the command, exit also has reason: sandbox_stopped, sandbox_expired or sandbox_deleted.
Open the terminal
GET /v1/customer/tenants/{tenantId}/sandboxes/{sandboxId}/terminal upgrades to a WebSocket. API and CLI clients send Authorization. Terminal bytes travel as binary frames in both directions, never base64.
The only text frame is the client's window size, {"type":"resize","cols":N,"rows":N} with 1 to 1000 each. Send it once after opening and on every change. Answer the server's ping, sent every 30 seconds, with a pong.
Terminal ticket for browsers
A browser cannot set Authorization on a WebSocket. POST /v1/customer/tenants/{tenantId}/sandboxes/{sandboxId}/terminal-ticket returns url, ticket and expires_at. Open url with ?ticket=<ticket> appended. A ticket works once, lasts 30 seconds and names one sandbox. A sandbox can have 10 unused tickets (429 ticket_limit_reached).
The ticket is in the URL, so do not log the query string of this route in your own proxies.
Close codes and refusals
- 1000: sandbox_stopped, sandbox_expired, sandbox_deleted, shell_exited or idle_timeout.
- 1003: an unknown or invalid text frame. 1008 input_rate: input above 256 KiB per second sustained, or a 1 MiB burst. 1009: a frame over 64 KiB. 1011: a server fault, output_overflow when output is read too slowly.
- 401 ticket_invalid: a bad, used, expired or foreign ticket, before any upgrade.
- 409 sandbox_wrong_state: the sandbox is not running. 409 session_limit_reached: too many commands or terminals. 503 sandbox_exec_unavailable: exec or the terminal is not set up.