v5

latestOpenAPI 3.0.3raw.githubusercontent.com2026-07-01224150.1 KB

Runtime

Run a shell command

Runs cmd inside the sandbox via a shell, so pipes, &&, redirects, and installed CLI tools all work. Sandbox must be in status ready.

Pass stream: true to receive stdout / stderr as they arrive. The response then uses Content-Type: text/event-stream with one JSON object per data: line; the final event is { "type": "done", ... }. See ExecStreamFrame for the event shape.

post/sandboxes/{id}/exec

Path parameters

idstring required

24-char hex id of the sandbox.

Request body

cmdstring required

Shell command to run. Pipes / && / redirects all work.

timeout_secondsinteger

Defaults to 30. Process is killed at the limit.

cwdstring

Absolute path inside the sandbox. Defaults to /.

envobject

Extra environment variables for this command only. Layered on top of the sandbox's existing environment; same-named keys here override the sandbox-level ones for this call. Values must be strings. Scoped to a single invocation, the next call starts with the sandbox defaults again.

streamboolean

When true, the server keeps the connection open and streams stdout/stderr as Server-Sent Events (text/event-stream). Each event is a JSON object on a data: line; the last event is always { "type": "done", ... } or { "type": "error", ... }.

Example request

{
  "env": {
    "NODE_ENV": "production",
    "DATABASE_URL": "postgres://..."
  }
}

Response

Command completed.

When the request body has stream: true, the response is text/event-stream, one ExecStreamFrame per data: event, the last being a done event.

messagestring required

Example response

{
  "message": "Exec completed"
}