WBX Sandbox
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.

EndpointWhat it does
POST /v1/sandboxes/{id}/processStart: {"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}/processList processes (running and recently finished).
GET /v1/sandboxes/{id}/process/{pid}Process detail and exit status.
GET /v1/sandboxes/{id}/process/{pid}/streamNDJSON: output so far, then live, then {"type":"exit"}.
POST /v1/sandboxes/{id}/process/{pid}/stdinSend 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}/resizeResize a terminal: {"cols": 160, "rows": 40}.
DELETE /v1/sandboxes/{id}/process/{pid}Kill the process and its children.
POST /v1/sandboxes/{id}/envAdd 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.