Run a command in a running sandbox

With Accept: application/x-ndjson the output is streamed as it is produced, one ExecEvent JSON object per line, ending with an exit (or error) event. Otherwise the call waits and returns an ExecResult with the collected output (capped at 4 MiB per stream; stream larger output).

POST/v1/sandboxes/{sandbox}/exec

Authorization

AuthorizationBearer token · headerrequired

Org-scoped API key, pols_....

Path parameters

sandboxstringrequired

Sandbox ID (sbx_...) or name.

Request body

requiredapplication/json

commandstring[]required

Program and arguments, none containing NUL. Use ["bash", "-lc", "..."] for a shell.

min items 1

envobject

Extra environment variables for this command.

cwdstring

Working directory, an absolute path. Defaults to the user's home.

rootboolean

Run as root instead of the default sandbox user (user, uid 1000, passwordless sudo).

default: false

stdinstring

Data written to the command's standard input.

timeout_secondsinteger

min 1 · max 86400 · default: 600

Responses

200

The command ran (whatever its exit code).

exit_codeintegerrequired

stdoutstringrequired

stderrstringrequired

truncatedboolean

Output exceeded the cap and was cut.

429

Rate limited (rate_limited): too many requests or failed authentications from this address, too many requests or lifecycle calls for this org, or too many of its exec, file, computer and CDP calls in progress at once. Retry after Retry-After seconds.

errorobjectrequired

Show properties

codestringrequired

Stable machine-readable code: bad_request (400), unauthorized (401), forbidden (403), quota_exceeded (403), not_found (404), conflict (409), rate_limited (429, see Retry-After), internal (500), runtime_error (502, the sandbox host failed), unavailable (503, the feature is not configured on this deployment), timeout (504, or 408 when a request body stalls).

messagestringrequired

default

Error.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

Request

curl -X POST 'https://api.pols.so/v1/sandboxes/string/exec' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "command": [
    "string"
  ],
  "env": {
    "property1": "string",
    "property2": "string"
  },
  "cwd": "string",
  "root": false,
  "stdin": "string",
  "timeout_seconds": 600
}'

const response = await fetch("https://api.pols.so/v1/sandboxes/string/exec", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"command\": [\n    \"string\"\n  ],\n  \"env\": {\n    \"property1\": \"string\",\n    \"property2\": \"string\"\n  },\n  \"cwd\": \"string\",\n  \"root\": false,\n  \"stdin\": \"string\",\n  \"timeout_seconds\": 600\n}"
});

import requests

response = requests.post(
    "https://api.pols.so/v1/sandboxes/string/exec",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"command\": [\n    \"string\"\n  ],\n  \"env\": {\n    \"property1\": \"string\",\n    \"property2\": \"string\"\n  },\n  \"cwd\": \"string\",\n  \"root\": false,\n  \"stdin\": \"string\",\n  \"timeout_seconds\": 600\n}",
)

Response

{
  "exit_code": 0,
  "stdout": "string",
  "stderr": "string",
  "truncated": true
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}