Skip to content
pols.so docs
Esc
↑↓navigate↵open⌘Jpreview

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).

A command that runs past timeout_seconds is killed: the call answers 504 timeout, or a stream ends with an error event with timed_out: true. Closing the connection (aborting the call) kills the command too. Killing ends the command’s whole process group (background jobs included), not processes that left it, such as daemons that start their own session.

A cwd that does not exist or that the user cannot enter is not an API error: the command does not run and the call reports exit code 125 with the reason on stderr, like env -C. A command that is not found exits 127.

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. If it does not exist or is not accessible, the command exits 125 without running.

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, which is then closed. Without it, standard input is empty (reads see end of file at once), so a command never waits for input. Exec is not interactive: input cannot be sent while the command runs.

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), insufficient_credit (402, no credit left to start a sandbox), forbidden (403), quota_exceeded (403), trial_limit (403, beyond what a trial org may run), not_found (404), conflict (409), billing_details_required (409, save the billing details before topping up), topup_not_available (409, the org cannot top up as it would be taxed; the message says why), withdrawal_consent_required (409, a consumer orders a top-up or the subscription only with withdrawal_consent), desktop_controlled (409, a person viewing the desktop has taken control of it, see control), rate_limited (429, see Retry-After), trial_capacity (429, all trial capacity in use; retry after Retry-After), host_capacity (429, the host is short of memory right now, so nothing new starts there; retry after Retry-After), internal (500), runtime_error (502, the sandbox host failed), payment_provider_error (502, Mollie could not be reached or refused a payment), unavailable (503, the feature is not configured on this deployment), waking (503, the sandbox is still waking from standby or booting; retry), timeout (504, or 408 when a request body stalls).

messagestringrequired
controlDesktopControl

Who has control of a sandbox's desktop. In an error, it is present only with code desktop_controlled.

Show properties
heldbooleanrequired

Someone viewing the desktop has taken control of it.

holderstring

Only when held; their name as the desktop's viewers see it, their user's name or else their API key's.

sincestring<date-time>

Only when held; when they took control.

expires_atstring<date-time>

Only when held; when control lapses unless they use the desktop before.

default

Error.

errorobjectrequired
Show properties
codestringrequired

Stable machine-readable code: bad_request (400), unauthorized (401), insufficient_credit (402, no credit left to start a sandbox), forbidden (403), quota_exceeded (403), trial_limit (403, beyond what a trial org may run), not_found (404), conflict (409), billing_details_required (409, save the billing details before topping up), topup_not_available (409, the org cannot top up as it would be taxed; the message says why), withdrawal_consent_required (409, a consumer orders a top-up or the subscription only with withdrawal_consent), desktop_controlled (409, a person viewing the desktop has taken control of it, see control), rate_limited (429, see Retry-After), trial_capacity (429, all trial capacity in use; retry after Retry-After), host_capacity (429, the host is short of memory right now, so nothing new starts there; retry after Retry-After), internal (500), runtime_error (502, the sandbox host failed), payment_provider_error (502, Mollie could not be reached or refused a payment), unavailable (503, the feature is not configured on this deployment), waking (503, the sandbox is still waking from standby or booting; retry), timeout (504, or 408 when a request body stalls).

messagestringrequired
controlDesktopControl

Who has control of a sandbox's desktop. In an error, it is present only with code desktop_controlled.

Show properties
heldbooleanrequired

Someone viewing the desktop has taken control of it.

holderstring

Only when held; their name as the desktop's viewers see it, their user's name or else their API key's.

sincestring<date-time>

Only when held; when they took control.

expires_atstring<date-time>

Only when held; when control lapses unless they use the desktop before.

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
}'
Response
{
  "exit_code": 0,
  "stdout": "string",
  "stderr": "string",
  "truncated": true
}