Skip to content

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
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. 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):

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) 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 -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.

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.

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}'
{
  "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.

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.

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.

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