Sandboxes
Commands and processes
Run a command and wait for its result, stream its output as it runs, or start a long-running program – a server, a Jupyter kernel – in the background and attach to it later.
Run and wait
r = sb.run("pip install requests && python3 main.py", cwd="/home/user", timeout=120)
print(r.exit_code, r.stdout, r.stderr, r.duration_ms)
sb.run("make test").check() # raises unless exit code 0
r = sb.run_code("print(sum(range(100)))") # python, node or bash
curl -s -X POST https://sandbox.wbx.cz/v1/sandboxes/SB_ID/exec \
-H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"cmd": "pip install requests && python3 main.py", "cwd": "/home/user", "timeout_ms": 120000}'
POST /v1/sandboxes/{id}/exec – body: cmd (run by /bin/sh -c), optional cwd, env, timeout_ms (0 = no limit), stdin. Response:
{"exit_code": 0, "stdout": "…", "stderr": "", "duration_ms": 2140, "timed_out": false, "truncated": false}
A command that fails does not raise an error in the SDK – check exit_code or call check(). Output is capped at 16 MB per stream (truncated: true) – redirect large output to a file and download it.
Stream output
sb.run("python3 train.py", on_stdout=lambda s: print(s, end=""))
for ev in sb.stream("python3 train.py"): # start, stdout, stderr, exit
print(ev)
curl -sN -X POST https://sandbox.wbx.cz/v1/sandboxes/SB_ID/exec/stream \
-H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"cmd": "python3 train.py"}'
POST /v1/sandboxes/{id}/exec/stream takes the same body; the response is NDJSON, one event per line as the command runs:
{"type":"start","pid":123}
{"type":"stdout","data":"step 1\n"}
{"type":"stderr","data":"warning: …\n"}
{"type":"exit","exit_code":0,"duration_ms":930,"timed_out":false}
Background processes and terminals
For servers, Jupyter kernels or anything long-running. Output is kept (the last 1 MB per stream), so you can attach later.
| Endpoint | What it does |
|---|---|
| POST /v1/sandboxes/{id}/process | Start: {"cmd": "python3 -m http.server 8000", "tag": "web"}. Add "pty": {"cols": 120, "rows": 30} for an interactive terminal, "stdin": true to send input. Returns {"pid": …}. |
| GET /v1/sandboxes/{id}/process | List processes (running and recently finished). |
| GET /v1/sandboxes/{id}/process/{pid} | Process detail and exit status. |
| GET /v1/sandboxes/{id}/process/{pid}/stream | NDJSON: output so far, then live, then {"type":"exit"}. |
| POST /v1/sandboxes/{id}/process/{pid}/stdin | Send input: {"data": "text\n"}; {"eof": true} closes stdin. |
| POST /v1/sandboxes/{id}/process/{pid}/signal | {"signal": "SIGTERM"} (or SIGINT, SIGHUP, SIGKILL). |
| POST /v1/sandboxes/{id}/process/{pid}/resize | Resize a terminal: {"cols": 160, "rows": 40}. |
| DELETE /v1/sandboxes/{id}/process/{pid} | Kill the process and its children. |
| POST /v1/sandboxes/{id}/env | Add environment variables for later commands: {"env": {"KEY": "value"}}. |
A web server in the background. A simple alternative to the process API:
nohup python3 -m http.server 8000 >/tmp/srv.log 2>&1 & in an ordinary command. Then open it through a public URL.