Skip to main content
Run a buffered command

Authorizations

Authorization
string
header
required

BoxRouter API key; never an upstream provider key.

Headers

Idempotency-Key
string

Optional for this operation. Preserve the same stable identifier when retrying an uncertain response; never reuse it for new work. If omitted where allowed, Cloud generates a request-scoped key that cannot reconcile a later retry. Do not include credentials or payloads. Stable identifier for one logical mutation.

Required string length: 1 - 128

Path Parameters

sandbox_id
string
required

Workspace-owned BoxRouter sandbox ID, not an upstream ID.

Minimum string length: 1
Pattern: ^[^\u0000]*$

Body

application/json

The one command request body. output chooses how the output comes back; a body that leaves it out asks for text. output_limit_bytes bounds each stream in either form.

command
string
required

Bash source executed once, including an empty script. NUL characters are invalid. Must not appear in operational logs by default.

Pattern: ^[^\u0000]*$
env
object | null

Literal environment overrides for this command only, applied after shell initialization. Omission or null retains the provider environment. Not logged.

cwd
string | null

Absolute sandbox working directory for this command only. Omitted, the command runs in the sandbox's default directory.

Pattern: ^/[^\u0000]*$
timeout_seconds
integer
default:60

Execution limit in seconds. At the deadline the command's process group receives TERM, then KILL 5 seconds later; children that leave the process group are not ended. The call may return shortly after the deadline while it finishes collecting output, and answers 200 with timed_out true, exit_code null and the output written until then.

Required range: x >= 1
output
enum<string>
default:text

How the result carries what the command wrote. text: stdout and stderr as strings, with invalid bytes replaced. bytes: stdout_base64 and stderr_base64 instead, the exact bytes, so a caller reads one pair or the other and never both (D26).

Available options:
text,
bytes
output_limit_bytes
integer
default:524288

The most bytes returned from each of stdout and stderr: 512 KiB by default and at most, half the advertised limits.buffered_output_bytes (1 MiB) that both streams share. Output over the limit does not fail the command: the result carries the exit status and the first output_limit_bytes of that stream, with its truncated flag true. A value above the maximum is a validation error before any dispatch. Use a process for complete large output.

Required range: 1 <= x <= 524288

Response

Command exited or reached its timeout; stdout and stderr are separate and hold everything it wrote, up to the limit.

What a command answers. A nonzero exit_code and a timeout are both a 200 with a result, never an HTTP failure; a client that wants an error raises it from the result (check).

stdout
string
required
stderr
string
required
exit_code
integer | null
required

The command's exit status. Null only when timed_out is true: a command that was ended at its deadline did not exit on its own, so it has no status.

timed_out
boolean
required

True when the command reached its timeout_seconds and BoxRouter ended its process group. The result then carries the output the command wrote before that point, and exit_code is null. False for every command that exited on its own, whatever its exit_code.

stdout_truncated
boolean
required

True when the stream wrote more than output_limit_bytes and only the first output_limit_bytes are returned.

stderr_truncated
boolean
required

True when the stream wrote more than output_limit_bytes and only the first output_limit_bytes are returned.

native_error
string | null

Provider-reported error for this command, unchanged, when the provider supplies one; otherwise null. It supplements exit_code without changing its meaning.