# Commands and streaming
`POST /v1/sandboxes/{sandbox_id}/commands` runs a command inside a sandbox. By default, the response streams events as the command starts, produces output, and exits.
Commands keep running if the connection drops. You can reconnect and resume streaming from the last event you received.
The examples use `$SANDBOX` for the sandbox ID, as in the [quickstart](quickstart.md), and `$COMMAND` for the command ID.
## Run a command
Provide either `command` or `argv`, but not both.
| Field | What runs | Use it for |
|---|---|---|
| `command` | A shell command using `bash -lc` | Pipes, `&&`, globs, and other shell syntax |
| `argv` | A program and its arguments, run directly | Arguments that shouldn't be interpreted by a shell |
```bash
curl -N https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/commands \
-H "Authorization: Bearer $KELN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"command": "pip install requests && python3 main.py",
"cwd": "/home/user",
"env": {"MODE": "test"},
"timeout_s": 300
}'
```
| Field | Default | Meaning |
|---|---|---|
| `cwd` | the user's home | Working directory. Must be an absolute path. |
| `env` | none | Environment variables for the command. Every command also gets the sandbox's `env`, and the command's own values override it. |
| `user` | `user` | Run as `user` or `root`. |
| `timeout_s` | none | Maximum running time in seconds. When it's reached, the command is stopped. Pausing the sandbox also pauses the timer. Without a timeout, the command runs until it exits or the sandbox stops. |
| `stdin` | `false` | Keep stdin open for [writing](#write-to-stdin). Otherwise, stdin is closed. |
| `background` | `false` | Return the command immediately instead of streaming events. |
If `cwd` doesn't exist or isn't a directory, the API returns `400 invalid_parameter` with `param: cwd`.
If an `argv` executable doesn't exist or isn't permitted, the API returns the same error with `param: argv`. With `command`, a missing executable makes the command exit with code `127`.
## The event stream
The response streams Server-Sent Events (SSE):
```text
id: 1
event: started
data: {"command_id": "cmd_8x1c4v7b2n5m9k3j6h0g", "pid": 41}
id: 2
event: stdout
data: {"data": "aGVsbG8K", "ts": 1793740800123}
id: 3
event: exit
data: {"exit_code": 0, "signal": null, "oom_killed": false}
```
| Event | Data fields | Meaning |
|---|---|---|
| `started` | `command_id`, `pid` | Command started. |
| `stdout`, `stderr` | `data` (base64-encoded output), `ts` (Unix milliseconds) | Command produced output. |
| `exit` | `exit_code`, `signal`, `oom_killed` | Command finished. The stream closes. |
| `error` | `error` (same format as an [HTTP error](../api/sandboxes.md#errors)) | An error occurred after streaming started. The stream closes, but the command may still be running. |
`id` identifies an event's position in the stream (1, 2, 3...). Event IDs stay the same when you reconnect. Error events have no ID.
Keln sends a `: ping` comment every 15 seconds when the stream is idle. SSE clients ignore these comments.
New event types may be added, so clients should ignore events they don't recognize.
`signal` contains the number of the signal that terminated the command, if applicable. `oom_killed` is `true` if the command was killed for using too much memory.
To print command output in your terminal, use `jq` to decode the stream. This combines stdout and stderr and ignores other event types:
```bash
curl -sN https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/commands \
-H "Authorization: Bearer $KELN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"command": "for i in 1 2 3; do echo $i; sleep 1; done"}' \
| jq -Rrj --unbuffered 'select(startswith("data: ")) | .[6:] | fromjson | .data // empty | @base64d'
```
## Reattach to a stream
Commands keep running if the connection drops. To resume streaming, call the events endpoint with the last event ID you received.
Without `Last-Event-ID`, the stream starts from the beginning. If the command has already exited, the API replays its events through the final `exit` event.
```bash
curl -N https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/commands/$COMMAND/events \
-H "Authorization: Bearer $KELN_API_KEY" \
-H "Last-Event-ID: 2"
```
Every streamed response includes a `Keln-Command-Id` header. You can use it to reconnect even if the connection drops before the `started` event.
## Background commands
Set `background: true` to start a command without keeping the connection open. The API returns `201` with the command object immediately.
You can read its output later through the events endpoint. This is useful for servers and long-running jobs.
```bash
curl https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/commands \
-H "Authorization: Bearer $KELN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"argv": ["python3", "-m", "http.server", "8000"], "background": true}'
```
```json
{
"id": "cmd_8x1c4v7b2n5m9k3j6h0g",
"object": "command",
"sandbox_id": "sbx_4k2v9q0m7c1x8z5n3b6d",
"state": "running",
"argv": ["python3", "-m", "http.server", "8000"],
"exit_code": null,
"signal": null,
"oom_killed": false,
"stdin": false,
"started_at": 1793740802,
"ended_at": null
}
```
`GET /v1/sandboxes/{sandbox_id}/commands` lists running and exited commands, newest first.
`GET /v1/sandboxes/{sandbox_id}/commands/{command_id}` returns a specific command.
## Write to stdin
Start a command with `stdin: true` to keep stdin open. Send data using the stdin endpoint.
Each request writes its raw body to stdin, up to the 1 MB request body limit.
```bash
printf 'first line\n' | curl https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/commands/$COMMAND/stdin \
-H "Authorization: Bearer $KELN_API_KEY" \
-H "Content-Type: application/octet-stream" \
--data-binary @-
curl -X POST https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/commands/$COMMAND/stdin/close \
-H "Authorization: Bearer $KELN_API_KEY"
```
Both endpoints return `204`.
`/stdin/close` sends EOF to the command. Closing stdin more than once still returns `204`.
Writing to a command whose stdin isn't open returns `409 stdin_not_open`.
## Stop a command
`POST /v1/sandboxes/{sandbox_id}/commands/{command_id}/signal` sends a signal to a command.
Specify the signal by name (`SIGTERM` or `TERM`) or as a number from 1 to 64. The response returns the command object.
```bash
curl https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/commands/$COMMAND/signal \
-H "Authorization: Bearer $KELN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"signal": "SIGTERM"}'
```
`DELETE /v1/sandboxes/{sandbox_id}/commands/{command_id}` sends `SIGKILL`.
Killing a command that has already exited returns `200` with the command unchanged.
## Retry safely
Use the `Idempotency-Key` header to safely retry a command request if the connection drops.
Keys are scoped to a sandbox and remain valid for 24 hours.
| Retry | Response |
|---|---|
| Same key, same body | Returns the original command without running it again. Background requests return the command object. Streamed requests replay events from the beginning or from `Last-Event-ID`. |
| Same key, different body | `409 idempotency_key_reused` |
| Same key while the original request is still running | `409 idempotency_key_in_use` |
## Output format
Command output arrives line by line:
- Each event contains one line with its newline. A final line without a newline gets one added.
- `\r\n` becomes `\n`, and `\r` progress updates arrive when the line ends.
- Lines longer than 16 KiB arrive across several events, without newlines added between them.
- Bytes that aren't valid UTF-8 become `U+FFFD`.
To keep a program's exact bytes, write its output to a file and download it using the [file endpoints](files.md).
## Limits and errors
A workspace supports up to 256 concurrent streams. Requests that exceed this limit return `429 too_many_streams` before the command starts.
Background commands don't count toward this limit.
| Code | Meaning |
|---|---|
| `400 invalid_parameter` | Invalid parameter. The `param` field identifies it. |
| `404 sandbox_not_found`, `404 command_not_found` | Sandbox or command not found in this workspace. |
| `409 sandbox_paused` | The sandbox is [paused](pause-resume.md). Resume it first. |
| `409 sandbox_not_running` | The sandbox has stopped. |
| `409 command_exited` | The command has already exited. |
| `409 stdin_not_open` | The command's stdin isn't open. |
| `429 too_many_streams` | The workspace has reached its limit of 256 open streams. |
Commands and streaming
POST /v1/sandboxes/{sandbox_id}/commands runs a command inside a sandbox. By default, the response streams events as the command starts, produces output, and exits.
Commands keep running if the connection drops. You can reconnect and resume streaming from the last event you received.
The examples use $SANDBOX for the sandbox ID, as in the quickstart, and $COMMAND for the command ID.
Run a command
Provide either command or argv, but not both.
Field
What runs
Use it for
command
A shell command using bash -lc
Pipes, &&, globs, and other shell syntax
argv
A program and its arguments, run directly
Arguments that shouldn't be interpreted by a shell
Environment variables for the command. Every command also gets the sandbox's env, and the command's own values override it.
user
user
Run as user or root.
timeout_s
none
Maximum running time in seconds. When it's reached, the command is stopped. Pausing the sandbox also pauses the timer. Without a timeout, the command runs until it exits or the sandbox stops.
stdin
false
Keep stdin open for writing. Otherwise, stdin is closed.
background
false
Return the command immediately instead of streaming events.
If cwd doesn't exist or isn't a directory, the API returns 400 invalid_parameter with param: cwd.
If an argv executable doesn't exist or isn't permitted, the API returns the same error with param: argv. With command, a missing executable makes the command exit with code 127.
An error occurred after streaming started. The stream closes, but the command may still be running.
id identifies an event's position in the stream (1, 2, 3...). Event IDs stay the same when you reconnect. Error events have no ID.
Keln sends a : ping comment every 15 seconds when the stream is idle. SSE clients ignore these comments.
New event types may be added, so clients should ignore events they don't recognize.
signal contains the number of the signal that terminated the command, if applicable. oom_killed is true if the command was killed for using too much memory.
To print command output in your terminal, use jq to decode the stream. This combines stdout and stderr and ignores other event types:
curl-sNhttps://sandbox.keln.ai/v1/sandboxes/$SANDBOX/commands\-H"Authorization: Bearer $KELN_API_KEY"\-H"Content-Type: application/json"\-d'{"command": "for i in 1 2 3; do echo $i; sleep 1; done"}'\|jq-Rrj--unbuffered'select(startswith("data: ")) | .[6:] | fromjson | .data // empty | @base64d'
Reattach to a stream
Commands keep running if the connection drops. To resume streaming, call the events endpoint with the last event ID you received.
Without Last-Event-ID, the stream starts from the beginning. If the command has already exited, the API replays its events through the final exit event.
Killing a command that has already exited returns 200 with the command unchanged.
Retry safely
Use the Idempotency-Key header to safely retry a command request if the connection drops.
Keys are scoped to a sandbox and remain valid for 24 hours.
Retry
Response
Same key, same body
Returns the original command without running it again. Background requests return the command object. Streamed requests replay events from the beginning or from Last-Event-ID.
Same key, different body
409 idempotency_key_reused
Same key while the original request is still running
409 idempotency_key_in_use
Output format
Command output arrives line by line:
Each event contains one line with its newline. A final line without a newline gets one added.
\r\n becomes \n, and \r progress updates arrive when the line ends.
Lines longer than 16 KiB arrive across several events, without newlines added between them.
Bytes that aren't valid UTF-8 become U+FFFD.
To keep a program's exact bytes, write its output to a file and download it using the file endpoints.
Limits and errors
A workspace supports up to 256 concurrent streams. Requests that exceed this limit return 429 too_many_streams before the command starts.
Background commands don't count toward this limit.