Run a command

Runs a command in the sandbox. By default the response waits for it to exit (at most `timeout_ms`, up to 60 seconds) and returns its exit code and output. With `?stream=true` (or `Accept: text/event-stream`) output arrives as `exec.stdout` and `exec.stderr` events while it runs, ending with `exec.exit`; streamed commands may run up to an hour. With `background: true` the response returns at once with the process, whose output you read from `GET /v1/sandboxes/{sandbox_id}/logs`. `cmd` as a string runs through `/bin/sh -c`; as an array it is executed directly. Output is UTF-8 (invalid bytes become U+FFFD) and each stream is capped at 1 MiB in a buffered response.

POST /v1/sandboxes/{sandbox_id}/exec
Runs a command in the sandbox. By default the response waits for it to exit (at most `timeout_ms`, up to 60 seconds) and returns its exit code and output. With `?stream=true` (or `Accept: text/event-stream`) output arrives as `exec.stdout` and `exec.stderr` events while it runs, ending with `exec.exit`; streamed commands may run up to an hour. With `background: true` the response returns at once with the process, whose output you read from `GET /v1/sandboxes/{sandbox_id}/logs`. `cmd` as a string runs through `/bin/sh -c`; as an array it is executed directly. Output is UTF-8 (invalid bytes become U+FFFD) and each stream is capped at 1 MiB in a buffered response.

Authentication

Bearer Token (b3os_sk_ API key or b3os_pat_ token) API Key (cookie: __Host-b3os_session)

Path Parameters

sandbox_id string required path
The sandbox ID (`sbx_…`).
Example: "sbx_01m5t68q1b590rj801nbzsqzkk"

Query Parameters

stream boolean optional query
Stream output as server-sent events.

Request Body required

application/json
cmd string | string[] REQUIRED
A shell command line (run with `/bin/sh -c`) or an argv array.
One of:
Option 1string
Option 2
Array of: string
cwd string
env object
Extra environment variables for this command.
stdin string
Written to the command's standard input, which is then closed.
timeout_ms integer
Kill the command after this long. At most 60000 unless the output is streamed or the command runs in the background.
background boolean
Return at once; read output from the logs stream.
user string
Enum: user, root

Responses

200 The command exited (buffered), or the output stream.
application/json
object string REQUIRED
Enum: exec_result
exit_code integer | null REQUIRED
The exit status; `null` when the command was killed by a signal.
signal string | null REQUIRED
The signal that ended the command, such as `KILL` after a timeout.
timed_out boolean REQUIRED
stdout string REQUIRED
stderr string REQUIRED
stdout_truncated boolean REQUIRED
More than 1 MiB of stdout was produced; the rest was dropped.
stderr_truncated boolean REQUIRED
duration_ms number REQUIRED
timing object
Server-side phase durations in milliseconds with microsecond resolution: the same phases as the `Server-Timing` header, keyed `<phase>_ms`. `total_ms` is always present. Phase names are product-specific and documented per operation. Example values in this reference are illustrative, not measurements.
total_ms number REQUIRED
202 The command started in the background.
400 The request failed validation (`invalid_request`, `invalid_url`).
401 Missing, malformed, expired or revoked credentials (`unauthorized`).
403 Authenticated but not allowed (`forbidden`, `egress_denied`).
404 No such sandbox in this project (`sandbox_not_found`).
409 The sandbox is paused or stopped (`sandbox_not_running`).
413 The request body exceeds this operation's limit.
415 The Content-Type is not accepted by this operation.
429 A rate, concurrency or quota limit applies (`rate_limited`, `concurrency_limited`, `quota_exceeded`).
500 Something failed inside B3OS (`internal`). Retry with backoff.
502 The agent inside the microVM did not answer (`guest_unreachable`).
503 The node or the product is not available right now (`node_unavailable`, `product_unavailable`, `capacity_unavailable`). 
curl -X POST 'https://beta-api.b3os.org/v1/sandboxes/sbx_01m5t68q1b590rj801nbzsqzkk/exec' \  -H 'Authorization: Bearer YOUR_API_TOKEN' \  -H 'Content-Type: application/json' \  -d '{  "cmd": "string",  "cwd": "/workspace",  "env": {},  "stdin": "string",  "timeout_ms": 30000,  "background": false,  "user": "user"}'
const response = await fetch('https://beta-api.b3os.org/v1/sandboxes/sbx_01m5t68q1b590rj801nbzsqzkk/exec', {  method: 'POST',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN",      "Content-Type": "application/json"  },  body: JSON.stringify({    "cmd": "string",    "cwd": "/workspace",    "env": {},    "stdin": "string",    "timeout_ms": 30000,    "background": false,    "user": "user"  })});const data = await response.json();console.log(data);
import requestsheaders = {    'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.post('https://beta-api.b3os.org/v1/sandboxes/sbx_01m5t68q1b590rj801nbzsqzkk/exec', headers=headers, json={  "cmd": "string",  "cwd": "/workspace",  "env": {},  "stdin": "string",  "timeout_ms": 30000,  "background": false,  "user": "user"})print(response.json())
200 Response 
{  "object": "exec_result",  "exit_code": 0,  "signal": null,  "timed_out": false,  "stdout": "4\n",  "stderr": "",  "stdout_truncated": false,  "stderr_truncated": false,  "duration_ms": 21.6,  "timing": {    "dispatch_ms": 0.2,    "spawn_ms": 0.5,    "run_ms": 20.8,    "total_ms": 21.9  }}
Previous Fork a sandbox
Next Run code in a kernel
Ask a question... ⌘I