Sign in
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"
}

Changes

Changed in 2 of the 5 revisions of this API.12

  • 4a016f074bc011See the full diff
    • ▲

      removed the media type application/x-ndjson for the response with the status 200

      response-media-type-removed

    • ○

      added the media type text/event-stream for the response with the status 200

      response-media-type-added

  • b236bf76f9a71See the full diff
    • ○

      added the new optional request property env

      new-optional-request-property

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog