Execd Commands API: Shell, Session, and Status Polling

The execd daemon runs inside every sandbox and exposes a local HTTP API at port 44772. It handles shell command execution, bash session management, file operations, code interpretation, and system metrics. All execd endpoints require the X-EXECD-ACCESS-TOKEN header — the token is provisioned at sandbox startup by the runtime. This page covers health checking, shell command execution, bash session management, and command status polling.

GET /ping

Health check endpoint. Returns 200 OK if the execd daemon is running and responsive. Typically used by orchestration platforms and monitoring systems to verify service availability. Auth: X-EXECD-ACCESS-TOKEN header required.

Example

curl http://localhost:44772/ping \
  -H "X-EXECD-ACCESS-TOKEN: your-token"

POST /command

Executes a shell command and streams output in real-time using Server-Sent Events (SSE). Commands can run in foreground (default) or detached background mode. Optionally specify a timeout, working directory, user/group IDs, and environment variable overrides. Auth: X-EXECD-ACCESS-TOKEN header required.

Request Body

command

string

required

Shell command string to execute. Example: "ls -la /workspace".

cwd

string

Working directory for command execution. Defaults to the sandbox working directory.

background

boolean

When true, the command runs in detached mode. SSE stream still starts immediately but the process continues after the stream closes. Default: false.

timeout

integer

Maximum execution time in milliseconds. The server forcefully terminates the process when reached. Omit to run without a server-enforced timeout.

uid

integer

Unix user ID for running the command. Required when gid is provided.

gid

integer

Unix group ID for running the command. Requires uid to be provided.

envs

object

Environment variables injected into the command process. Key-value string pairs.

Response — 200 OK (`text/event-stream`)

The response is an SSE stream. Each event has a type field and optional payload fields.

type

string

Event type. One of: init, status, stdout, stderr, result, execution_complete, execution_count, error, ping.

text

string

Textual payload for stdout, stderr, status, and init events.

execution_time

integer

Execution duration in milliseconds. Present on execution_complete.

error

object

Error details for error events. Contains ename, evalue, and traceback.

timestamp

integer

Unix milliseconds when the event was generated.

Example

curl -X POST http://localhost:44772/command \
  -H "X-EXECD-ACCESS-TOKEN: your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "ls -la /workspace",
    "cwd": "/workspace",
    "background": false,
    "timeout": 30000,
    "uid": 1000,
    "gid": 1000
  }'

DELETE /command

Interrupts the currently running command execution in the specified context. Sends a termination signal to the process and releases associated resources. Auth: X-EXECD-ACCESS-TOKEN header required.

Query Parameters

string

required

Session ID of the execution context to interrupt.

Example

curl -X DELETE "http://localhost:44772/command?id=session-456" \
  -H "X-EXECD-ACCESS-TOKEN: your-token"

GET /command/status/

Returns the current status of a command (foreground or background) including running state, exit code, error message, and start/finish timestamps. Auth: X-EXECD-ACCESS-TOKEN header required.

Path Parameters

string

required

Command ID returned by POST /command.

Response — 200 OK

string

Command ID.

content

string

Original command string.

running

boolean

Whether the command is still executing.

exit_code

integer

Exit code once the command has finished. null if still running.

error

string

Error message if the command failed.

started_at

string

Start time in RFC 3339 format.

finished_at

string

Finish time in RFC 3339 format. null if still running.

Example

curl http://localhost:44772/command/status/cmd-abc123 \
  -H "X-EXECD-ACCESS-TOKEN: your-token"

GET /command//logs

Returns accumulated stdout and stderr for a background command. Supports incremental reads via a line-based cursor. Intended for polling logs of detached background commands; foreground commands should consume output directly from the SSE stream. Auth: X-EXECD-ACCESS-TOKEN header required.

Path Parameters

string

required

Command ID returned by POST /command.

Query Parameters

cursor

integer

Optional 0-based line cursor. When provided, only lines after this position are returned. Omit to receive the full log. Use the EXECD-COMMANDS-TAIL-CURSOR response header value as the next cursor for incremental polling.

Response — 200 OK

The response body is text/plain log content. The EXECD-COMMANDS-TAIL-CURSOR response header contains the highest available 0-based line index — pass this as cursor in the next request to poll only new lines.

Example

curl http://localhost:44772/command/cmd-abc123/logs \
  -H "X-EXECD-ACCESS-TOKEN: your-token"

POST /session

Creates a persistent bash session that maintains shell state (working directory, environment variables) across multiple command runs. Returns a session_id for use with subsequent POST /session/{sessionId}/run requests. Auth: X-EXECD-ACCESS-TOKEN header required.

Request Body (optional)

cwd

string

Initial working directory for the session. Defaults to the sandbox working directory.

Response — 200 OK

session_id

string

required

Unique session ID for run_in_session and delete_session calls.

Example

curl -X POST http://localhost:44772/session \
  -H "X-EXECD-ACCESS-TOKEN: your-token" \
  -H "Content-Type: application/json" \
  -d '{"cwd": "/workspace"}'

POST /session//run

Executes a shell command inside an existing bash session, streaming output in real-time via SSE. The session maintains state between runs (e.g. cd persists across calls). Auth: X-EXECD-ACCESS-TOKEN header required.

Path Parameters

sessionId

string

required

Session ID returned by POST /session.

Request Body

command

string

required

Shell command to execute in the session.

cwd

string

Working directory override for this individual run.

timeout

integer

Maximum execution time in milliseconds for this run.

Response — 200 OK (`text/event-stream`)

SSE stream with the same event types as POST /command: init, status, stdout, stderr, result, execution_complete, error.

Example

curl -X POST http://localhost:44772/session/session-abc123/run \
  -H "X-EXECD-ACCESS-TOKEN: your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "ls -la",
    "cwd": "/workspace",
    "timeout": 30000
  }'

DELETE /session/

Terminates a bash session, stopping the underlying shell process and releasing all associated resources. Auth: X-EXECD-ACCESS-TOKEN header required.

Path Parameters

sessionId

string

required

Session ID to delete.

Example

curl -X DELETE http://localhost:44772/session/session-abc123 \
  -H "X-EXECD-ACCESS-TOKEN: your-token"

SSE Event Types

Event Type	Description
`init`	Initialization event, fired when execution starts.
`status`	Status update with descriptive text.
`stdout`	Standard output chunk from the process.
`stderr`	Standard error chunk from the process.
`result`	Final execution result (code interpreter contexts).
`execution_complete`	Signals the command/code has finished.
`execution_count`	Cell execution counter increment (Jupyter contexts).
`error`	Structured error with `ename`, `evalue`, and `traceback`.
`ping`	Keep-alive heartbeat.

Overview

Lifecycle API

Execution API

Egress & Diagnostics

Execd Commands API: Shell, Session, and Status Polling

GET /ping

Example

POST /command

Request Body

Response — 200 OK (`text/event-stream`)

Example

DELETE /command

Query Parameters

Example

GET /command/status/

Path Parameters

Response — 200 OK

Example

GET /command//logs

Path Parameters

Query Parameters

Response — 200 OK

Example

POST /session

Request Body (optional)

Response — 200 OK

Example

POST /session//run

Path Parameters

Request Body

Response — 200 OK (`text/event-stream`)

Example

DELETE /session/

Path Parameters

Example

SSE Event Types

Build docs developers (and LLMs) love

Overview

Lifecycle API

Execution API

Egress & Diagnostics

Documentation Index

​GET /ping

​Example

​POST /command

​Request Body

​Response — 200 OK (text/event-stream)

​Example

​DELETE /command

​Query Parameters

​Example

​GET /command/status/

​Path Parameters

​Response — 200 OK

​Example

​GET /command//logs

​Path Parameters

​Query Parameters

​Response — 200 OK

​Example

​POST /session

​Request Body (optional)

​Response — 200 OK

​Example

​POST /session//run

​Path Parameters

​Request Body

​Response — 200 OK (text/event-stream)

​Example

​DELETE /session/

​Path Parameters

​Example

​SSE Event Types

Build docs developers (and LLMs) love

GET /ping

Example

POST /command

Request Body

Response — 200 OK (`text/event-stream`)

Example

DELETE /command

Query Parameters

Example

GET /command/status/

Path Parameters

Response — 200 OK

Example

GET /command//logs

Path Parameters

Query Parameters

Response — 200 OK

Example

POST /session

Request Body (optional)

Response — 200 OK

Example

POST /session//run

Path Parameters

Request Body

Response — 200 OK (`text/event-stream`)

Example

DELETE /session/

Path Parameters

Example

SSE Event Types