Skip to main content
POST
/
sandboxes
/
{id}
/
exec
Run a shell command
curl --request POST \
  --url https://sandbox.brimble.io/sandboxes/{id}/exec \
  --header 'Content-Type: application/json' \
  --header 'x-brimble-key: <api-key>' \
  --data '
{
  "cmd": "<string>",
  "timeout_seconds": 150,
  "cwd": "<string>",
  "env": {
    "NODE_ENV": "production",
    "DATABASE_URL": "postgres://..."
  },
  "stream": true
}
'
{
  "message": "Exec completed",
  "data": {
    "stdout": "<string>",
    "stderr": "<string>",
    "exit_code": 123,
    "duration_ms": 123
  }
}

Authorizations

​
x-brimble-key
string
header
required

Your account-level Brimble API key. Find it in the dashboard under your profile drawer → API key (click the avatar in the sidebar). Available on paid plans only.

Path Parameters

​
id
string
required

24-char hex id of the sandbox.

Pattern: ^[a-f0-9]{24}$

Body

application/json
​
cmd
string
required

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

​
timeout_seconds
integer

Defaults to 30. Process is killed at the limit.

Required range: 1 <= x <= 300
​
cwd
string

Absolute path inside the sandbox. Defaults to /.

​
env
object

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.

Example:
{
  "NODE_ENV": "production",
  "DATABASE_URL": "postgres://..."
}
​
stream
boolean

When true, the server keeps the connection open and streams stdout/stderr chunks as NDJSON (application/x-ndjson) instead of buffering. The last frame is always { "type": "done", ... }.

Response

Command completed.

When the request body has stream: true, the response is application/x-ndjson, one ExecStreamFrame per line, the last being a done frame.

​
message
string
required
Example:

"Exec completed"

​
data
object
required
Last modified on May 20, 2026