Execd: Code Interpreter and Isolated Execution API

The code interpreter API runs inside every sandbox via the execd daemon at http://localhost:44772. It exposes a Jupyter-compatible execution model with persistent kernel contexts: a context (session) is created once and reused across multiple code executions, maintaining in-memory state such as imported modules, defined variables, and open resources. Execution output is streamed in real-time using Server-Sent Events (SSE). Supported languages include Python, Bash, Java, JavaScript, and Go. The API also provides isolated execution sessions that run code in a namespace-isolated environment with a configurable workspace mount mode.

OpenSandbox SDK clients wrap these endpoints with higher-level abstractions. If you are using the SDK, you typically do not call these endpoints directly. Direct HTTP access requires a valid X-EXECD-ACCESS-TOKEN header.

POST /code/context

Creates a new code execution context for the specified language. Returns a context object containing a session ID (id) and the runtime language. The session ID is passed to subsequent POST /code requests to route executions into the correct kernel. Auth: X-EXECD-ACCESS-TOKEN header required.

Request Body

language

string

Execution runtime to initialize. Examples: python, bash, java, javascript, go.

Response — 200 OK

string

Unique session identifier to use in subsequent code execution requests.

language

string

required

The execution runtime associated with this context.

Example

curl -X POST http://localhost:44772/code/context \
  -H "X-EXECD-ACCESS-TOKEN: your-token" \
  -H "Content-Type: application/json" \
  -d '{"language": "python"}'

GET /code/contexts

Lists all active code execution contexts. The language query parameter is required and filters the results to contexts under that runtime. Auth: X-EXECD-ACCESS-TOKEN header required.

Query Parameters

language

string

required

Filter contexts by execution runtime (e.g. python, bash, java).

Response — 200 OK

An array of CodeContext objects:

[].id

string

Unique session identifier.

[].language

string

required

Execution runtime.

Example

curl "http://localhost:44772/code/contexts?language=python" \
  -H "X-EXECD-ACCESS-TOKEN: your-token"

GET /code/contexts/

Retrieves details of a specific code execution context by ID. Auth: X-EXECD-ACCESS-TOKEN header required.

Path Parameters

context_id

string

required

Session/context ID to retrieve.

Response — 200 OK

string

Unique session identifier.

language

string

required

Execution runtime.

Example

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

DELETE /code/contexts/

Deletes a specific code execution context by ID. Terminates the underlying kernel process and releases all associated resources. Auth: X-EXECD-ACCESS-TOKEN header required.

Path Parameters

context_id

string

required

Session/context ID to delete.

Example

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

DELETE /code/contexts

Bulk-deletes all code execution contexts under the specified language. This is a convenience cleanup operation — individual context IDs do not need to be enumerated. Auth: X-EXECD-ACCESS-TOKEN header required.

Query Parameters

language

string

required

Target execution runtime whose contexts should be deleted.

Example

curl -X DELETE "http://localhost:44772/code/contexts?language=python" \
  -H "X-EXECD-ACCESS-TOKEN: your-token"

POST /code

Executes code in a specified context using the Jupyter kernel model. Output is streamed in real-time via SSE. If no context is provided, a stateless execution is performed. Supports Python, JavaScript, and other runtimes depending on the installed kernels. Auth: X-EXECD-ACCESS-TOKEN header required.

Request Body

code

string

required

Source code to execute.

context

object

Target execution context. If omitted, a stateless execution is performed.

Show context fields

context.id

string

Session ID returned by POST /code/context.

context.language

string

required

Execution runtime language.

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

SSE stream with the following event types:

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.

results

object

Execution output in various MIME types on result events. Keys are MIME types (e.g. "text/plain", "text/html").

execution_count

integer

Incremental cell execution counter in the context session.

execution_time

integer

Execution duration in milliseconds. Present on execution_complete.

error

object

Structured error details on error events.

Show error fields

error.ename

string

Error name/type, e.g. "NameError".

error.evalue

string

Error value/message.

error.traceback

array

Stack trace lines as an array of strings.

Example

curl -X POST http://localhost:44772/code \
  -H "X-EXECD-ACCESS-TOKEN: your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "context": { "id": "session-123", "language": "python" },
    "code": "import numpy as np\nresult = np.array([1, 2, 3])\nprint(result)"
  }'

DELETE /code

Interrupts the currently running code execution in the specified context. Sends a kernel interrupt signal (equivalent to Jupyter kernel interrupt) to terminate the active execution and release 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/code?id=session-123" \
  -H "X-EXECD-ACCESS-TOKEN: your-token"

Supported Languages

Language	Runtime
`python`	IPython kernel (Jupyter)
`bash`	Bash shell interpreter
`java`	JVM-based kernel
`javascript`	Node.js kernel
`go`	Go runtime kernel

Context state is preserved across multiple POST /code calls within the same context.id. This means variables, imports, and function definitions defined in earlier cells remain available in subsequent executions — just like a Jupyter notebook.

Isolated Execution

The isolated execution API provides per-session namespace isolation for code and file operations. Each isolated session runs in its own sandboxed environment with a configurable workspace mount mode (rw, overlay, or ro). All isolated endpoints are served at the /v1/isolated path prefix and require the same X-EXECD-ACCESS-TOKEN header.

Isolated sessions depend on the isolator subsystem. Call GET /v1/isolated/capabilities to verify availability before creating sessions. All isolated endpoints return 503 Service Unavailable when the isolation subsystem is not ready.

GET /v1/isolated/capabilities

Returns whether the isolator subsystem is available, the isolator backend name and version, and which optional features (commit_supported, diff_supported) are enabled on this deployment. Auth: X-EXECD-ACCESS-TOKEN header required.

Response — 200 OK

available

boolean

Whether the isolation subsystem is available.

isolator

string

Isolator backend identifier.

version

string

Isolator version string.

message

string

Diagnostic message when isolation is unavailable.

commit_supported

boolean

Whether the commit operation is supported by this backend.

diff_supported

boolean

Whether the diff operation is supported by this backend.

Example

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

POST /v1/isolated/session

Creates a new isolated bash session with a scoped workspace. Returns a session UUID and creation timestamp. Auth: X-EXECD-ACCESS-TOKEN header required.

Request Body

workspace

object

required

Workspace specification for the isolated session.

Show workspace fields

workspace.path

string

required

Absolute path to the workspace directory inside the sandbox.

workspace.mode

string

Mount mode. Enum: rw (read-write), overlay (copy-on-write), ro (read-only).

profile

string

Security profile. Enum: strict, balanced.

extra_writable

array

Additional absolute paths to make writable inside the session (array of strings).

Whether to share the host network namespace. Default: false.

env_passthrough

object

Environment variable passthrough policy.

Show env_passthrough fields

env_passthrough.mode

string

Passthrough mode. Enum: allow, deny.

env_passthrough.keys

array

Environment variable keys to allow or deny (array of strings).

uid

integer

Unix user ID for the session process.

gid

integer

Unix group ID for the session process.

idle_timeout_seconds

integer

Seconds of inactivity before the session is automatically destroyed.

Response — 201 Created

session_id

string

required

UUID of the newly created isolated session.

created_at

string

required

RFC 3339 session creation timestamp.

Example

curl -X POST http://localhost:44772/v1/isolated/session \
  -H "X-EXECD-ACCESS-TOKEN: your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace": { "path": "/workspace", "mode": "overlay" },
    "profile": "balanced",
    "idle_timeout_seconds": 300
  }'

GET /v1/isolated/session/

Returns the current state of an isolated session, including status, creation time, last run time, and remaining idle seconds. Auth: X-EXECD-ACCESS-TOKEN header required.

Path Parameters

sessionId

string

required

UUID of the isolated session.

Response — 200 OK

status

string

required

Session status. Enum: active, dead, destroyed.

created_at

string

RFC 3339 creation timestamp.

last_run_at

string

RFC 3339 timestamp of the most recent run.

idle_remaining_seconds

integer

Seconds until idle timeout fires. null when no idle timeout is configured.

Example

curl http://localhost:44772/v1/isolated/session/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-EXECD-ACCESS-TOKEN: your-token"

DELETE /v1/isolated/session/

Destroys an isolated session, terminating the underlying process and releasing all associated resources. Auth: X-EXECD-ACCESS-TOKEN header required.

Path Parameters

sessionId

string

required

UUID of the isolated session to delete.

Example

curl -X DELETE \
  http://localhost:44772/v1/isolated/session/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-EXECD-ACCESS-TOKEN: your-token"

POST /v1/isolated/session//run

Executes a shell command or script inside an isolated session and streams output in real-time via SSE. Optionally inject environment variables or enforce a timeout. Auth: X-EXECD-ACCESS-TOKEN header required.

Path Parameters

sessionId

string

required

UUID of the isolated session.

Request Body

code

string

required

Shell command or script to execute inside the isolated session.

envs

object

Additional environment variables to inject (key-value string pairs).

timeout_seconds

integer

Maximum execution time in seconds. The process is forcefully terminated when the limit is reached.

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/v1/isolated/session/550e8400-e29b-41d4-a716-446655440000/run \
  -H "X-EXECD-ACCESS-TOKEN: your-token" \
  -H "Content-Type: application/json" \
  -d '{"code": "echo hello && ls /workspace", "timeout_seconds": 30}'

GET /v1/isolated/session//diff

Returns a diff of upper-layer filesystem changes made within the isolated session. This is a stub endpoint — returns 503 Service Unavailable until the backend implements the feature. Auth: X-EXECD-ACCESS-TOKEN header required.

Path Parameters

sessionId

string

required

UUID of the isolated session.

POST /v1/isolated/session//commit

Commits upper-layer filesystem changes back to the underlying workspace. This is a stub endpoint — returns 503 Service Unavailable until the backend implements the feature. Auth: X-EXECD-ACCESS-TOKEN header required.

Path Parameters

sessionId

string

required

UUID of the isolated session.

Isolated Session File Operations

The following endpoints mirror the standard file and directory endpoints but scope all paths within the isolated session’s namespace. All require the X-EXECD-ACCESS-TOKEN header and a sessionId UUID path parameter. Unsupported operations return 503 Service Unavailable.

Method	Path	Description
`GET`	`/v1/isolated/session/{sessionId}/files/info`	Get file metadata for one or more paths.
`GET`	`/v1/isolated/session/{sessionId}/files/download`	Download a file; supports `offset`/`limit` and `Range` header.
`POST`	`/v1/isolated/session/{sessionId}/files/upload`	Upload a file via `multipart/form-data`.
`DELETE`	`/v1/isolated/session/{sessionId}/files`	Delete one or more files (`path` query, repeatable).
`POST`	`/v1/isolated/session/{sessionId}/files/mv`	Move or rename files (array of `{src, dest}` pairs).
`POST`	`/v1/isolated/session/{sessionId}/files/permissions`	Change file owner/group/mode (map of path to `Permission`).
`POST`	`/v1/isolated/session/{sessionId}/files/replace`	Batch replace file content; supports `verbose` query parameter.
`GET`	`/v1/isolated/session/{sessionId}/files/search`	Search files by glob pattern under a root directory.
`GET`	`/v1/isolated/session/{sessionId}/directories/list`	List directory contents with optional `depth` control.
`POST`	`/v1/isolated/session/{sessionId}/directories`	Create directories with permissions (`mkdir -p` semantics).
`DELETE`	`/v1/isolated/session/{sessionId}/directories`	Recursively delete directories (`path` query, repeatable).

Request and response schemas for these endpoints are identical to their non-isolated counterparts documented on the Files page. The only difference is that paths are resolved within the isolated session’s namespace.

Overview

Lifecycle API

Execution API

Egress & Diagnostics

Documentation Index

​POST /code/context

​Request Body

​Response — 200 OK

​Example

​GET /code/contexts

​Query Parameters

​Response — 200 OK

​Example

​GET /code/contexts/

​Path Parameters

​Response — 200 OK

​Example

​DELETE /code/contexts/

​Path Parameters

​Example

​DELETE /code/contexts

​Query Parameters

​Example

​POST /code

​Request Body

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

​Example

​DELETE /code

​Query Parameters

​Example

​Supported Languages

​Isolated Execution

​GET /v1/isolated/capabilities

​Response — 200 OK

​Example

​POST /v1/isolated/session

​Request Body

​Response — 201 Created

​Example

​GET /v1/isolated/session/

​Path Parameters

​Response — 200 OK

​Example

​DELETE /v1/isolated/session/

​Path Parameters

​Example

​POST /v1/isolated/session//run

​Path Parameters

​Request Body

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

​Example

​GET /v1/isolated/session//diff

​Path Parameters

​POST /v1/isolated/session//commit

​Path Parameters

​Isolated Session File Operations

Build docs developers (and LLMs) love

POST /code/context

Request Body

Response — 200 OK

Example

GET /code/contexts

Query Parameters

Response — 200 OK

Example

GET /code/contexts/

Path Parameters

Response — 200 OK

Example

DELETE /code/contexts/

Path Parameters

Example

DELETE /code/contexts

Query Parameters

Example

POST /code

Request Body

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

Example

DELETE /code

Query Parameters

Example

Supported Languages

Isolated Execution

GET /v1/isolated/capabilities

Response — 200 OK

Example

POST /v1/isolated/session

Request Body

Response — 201 Created

Example

GET /v1/isolated/session/

Path Parameters

Response — 200 OK

Example

DELETE /v1/isolated/session/

Path Parameters

Example

POST /v1/isolated/session//run

Path Parameters

Request Body

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

Example

GET /v1/isolated/session//diff

Path Parameters

POST /v1/isolated/session//commit

Path Parameters

Isolated Session File Operations