Open an interactive terminal in a sandbox
Opens an interactive terminal over a WebSocket. Binary frames carry stdin and output; text frames carry resize controls and the exit code. Uses the HTTP/1.1 upgrade; HTTP/2 extended CONNECT (RFC 8441) is not offered. Send {"resize":{"cols":120,"rows":40}} to resize; the last frame received is {"exit":0}.
Required permission
Requires the sandboxes.exec permission. See Permissions for the roles and API key permissions that include it.
Command line
The orl CLI wraps this endpoint:
Guided workflow: orl sandbox pty
orl sandbox pty <sandbox-id>apiKeyAuthorizationBearer <token>OpenRelay API key. Send it as Authorization: Bearer or_… (legacy vl_… keys still work).
sandboxId*stringcmd?stringThe command to run. Defaults to /bin/sh.
cols?integer1 <= value80rows?integer1 <= value24Switching to the WebSocket protocol
curl -X GET 'https://api.openrelay.inc/v1/sandboxes/string/pty'Run a command in a sandbox POST
Runs a command. application/x-ndjson streams one SandboxEvent per line; application/json waits for the exit and answers an ExecResult. The caller names the exec with execId. A request naming an execId the host already knows starts nothing: it replays the exec's output after offset, the seq of the last line already read, and follows the running process. That is how a client reattaches after a lost connection, and every line arrives once. The host keeps an exec's exit code and its most recent 1 MiB of output, the oldest lines dropped first; a reattach from an offset older than that gets a last error line with code OUTPUT_EVICTED. A finished exec is kept while it is one of the sandbox's 16 most recently finished, and after the sandbox ends for up to 10 minutes, sooner when its host holds more than 1,024 ended sandboxes.
List a directory in a sandbox GET
Lists the entries of a directory inside a sandbox, including each entry's name, type and size, without following symbolic links.