Terminals
Terminals let you run interactive programs inside a sandbox over WebSocket. Use them for shells or other programs that need a TTY. For non-interactive tasks, commands are simpler.
The examples use $SANDBOX for the sandbox ID, as in the quickstart, and $TERMINAL for the terminal ID.
Start a terminal
POST /v1/sandboxes/{sandbox_id}/terminals starts a terminal as the sandbox's default user. You can use sudo to run commands as root.
An empty request body starts a login shell in /home/user, with a default size of 80 columns and 24 rows.
curl https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/terminals \
-H "Authorization: Bearer $KELN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"cols": 120, "rows": 40}'
{
"id": "term_0123456789abcdefghij",
"object": "terminal",
"sandbox_id": "sbx_4k2v9q0m7c1x8z5n3b6d",
"state": "running",
"cols": 120,
"rows": 40,
"exit_code": null,
"created_at": 1793740900,
"ended_at": null
}
| Field | Default | Meaning |
|---|---|---|
command |
none | A shell command executed using bash -lc. |
argv |
none | A program and its arguments, run directly. |
cwd |
the user's home | Working directory. Must be an absolute path. |
env |
none | Environment variables. |
cols, rows |
80, 24 | Terminal dimensions. Each must be between 1 and 1000. |
Provide either command or argv, or neither to start a login shell.
Terminals always run as user. A request that sets user returns 400 unsupported_parameter.
Attach over WebSocket
GET /v1/sandboxes/{sandbox_id}/terminals/{terminal_id}/ws opens a WebSocket connection to the terminal.
Authenticate using the Authorization: Bearer header, as with other API requests. Browsers can't set this header on WebSocket connections, so connect through your own server and keep your API key there.
All messages use binary frames. The first byte identifies the message type:
| Direction | First byte | Remaining bytes |
|---|---|---|
| Client to server | 0x00 |
Input bytes. |
| Client to server | 0x01 |
New terminal size: columns followed by rows, each a big-endian 16-bit integer. |
| Server to client | 0x00 |
Output bytes. |
| Server to client | 0x03 |
Exit code as a big-endian 32-bit integer. The server then closes the connection. |
Keln ignores text frames and unrecognized message types.
This Python example uses websockets 14 or later. It starts a terminal, sends 2 commands, and prints the output:
import asyncio
import os
import sys
import requests
import websockets
KEY = os.environ["KELN_API_KEY"]
SANDBOX = os.environ["SANDBOX"]
HEADERS = {"Authorization": f"Bearer {KEY}"}
async def main():
terminal = requests.post(
f"https://sandbox.keln.ai/v1/sandboxes/{SANDBOX}/terminals",
headers=HEADERS,
json={"cols": 100, "rows": 30},
).json()
url = f"wss://sandbox.keln.ai/v1/sandboxes/{SANDBOX}/terminals/{terminal['id']}/ws"
async with websockets.connect(url, additional_headers=HEADERS) as socket:
await socket.send(b"\x00" + b"echo hello from a terminal\n")
await socket.send(b"\x00" + b"exit 7\n")
async for frame in socket:
if frame[0] == 0x00:
sys.stdout.buffer.write(frame[1:])
sys.stdout.buffer.flush()
elif frame[0] == 0x03:
print("exit code", int.from_bytes(frame[1:5], "big"))
break
asyncio.run(main())
You can reconnect to a terminal after a disconnection. To receive all of a program's output, keep a client connected.
Each open WebSocket connection counts toward the workspace's limit of 256 concurrent streams.
Resize
Resize a terminal by sending a 0x01 frame over WebSocket or calling the API. Both methods have the same effect.
curl https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/terminals/$TERMINAL/resize \
-H "Authorization: Bearer $KELN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"cols": 160, "rows": 50}'
List and end terminals
| Endpoint | Description |
|---|---|
GET /v1/sandboxes/{sandbox_id}/terminals |
Lists terminals in the sandbox, oldest first. |
GET /v1/sandboxes/{sandbox_id}/terminals/{terminal_id} |
Returns a specific terminal. |
DELETE /v1/sandboxes/{sandbox_id}/terminals/{terminal_id} |
Stops the terminal's program. If it has already exited, returns 200 with the terminal unchanged. |
Terminals do not survive a sandbox pause.
Errors
| Code | Meaning |
|---|---|
400 invalid_parameter |
Invalid parameter, or the program or cwd doesn't exist or isn't permitted. |
400 unsupported_parameter |
The request sets user. |
404 terminal_not_found |
The terminal doesn't exist in this sandbox. |
409 sandbox_paused |
The sandbox is paused. Resume it first. |
429 too_many_terminals |
The sandbox has reached its terminal limit. End a terminal and retry. |
429 too_many_streams |
The workspace has reached its limit of 256 open streams. |