# 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

**Python**

```
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**

```
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

**Python**

```
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**

```
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](https://sandbox.wbx.cz/docs/sandboxes/urls.md).

Source: https://sandbox.wbx.cz/docs/sandboxes/commands
