Skip to main content
All endpoints except GET /health require Authorization: Bearer <apiKey>.

​
GET /health

Health check endpoint. No authentication required. Response: 
{
  "status": "ok",
  "version": "0.1.0"
}

​
POST /execute

Execute code and return the full result. Request body: 
{
  "request": {
    "code": "print('hello')",
    "runtime": "python",
    "timeoutMs": 5000,
    "env": { "MY_VAR": "value" },
    "stdin": "input data",
    "files": { "/sandbox/data.csv": "a,b\n1,2" },
    "outputPaths": ["/sandbox/out.txt"],
    "installPackages": ["numpy"]
  },
  "options": {
    "network": "none",
    "memoryLimit": "512m",
    "cpuLimit": 1.0,
    "timeoutMs": 30000,
    "sandboxSize": "64m",
    "tmpSize": "64m"
  },
  "sessionId": "optional-session-id"
}
​
request
ExecutionRequest
required
The code execution request. See ExecutionRequest for all fields.
​
options
Isol8Options
Engine options for this execution. Merged with server config defaults.
​
sessionId
string
Optional session ID for persistent mode. When provided, the server creates or reuses a persistent DockerIsol8 instance.
Success response (200): 
{
  "stdout": "hello\n",
  "stderr": "",
  "exitCode": 0,
  "durationMs": 82,
  "truncated": false,
  "executionId": "550e8400-e29b-41d4-a716-446655440000",
  "runtime": "python",
  "timestamp": "2026-02-14T12:00:00.000Z",
  "containerId": "abc123"
}
Error response (500): 
{
  "error": "Execution failed: container OOM killed"
}

​
POST /execute/stream

Execute code and stream output via Server-Sent Events. Always uses ephemeral mode (ignores sessionId). Request body: Same as POST /execute. Response: SSE stream with Content-Type: text/event-stream. 
data: {"type":"stdout","data":"Hello\n"}

data: {"type":"stderr","data":"Warning: deprecated\n"}

data: {"type":"exit","data":"0"}

​
Event Types

TypeDescription
stdoutA chunk of standard output
stderrA chunk of standard error
exitExit code as a string
errorError message (container failure, timeout)

​
Example with curl

curl -N -X POST http://localhost:3000/execute/stream \
  -H "Authorization: Bearer my-key" \
  -H "Content-Type: application/json" \
  -d '{"request": {"code": "for i in range(3): print(i)", "runtime": "python"}}'

​
POST /file

Upload a file to a persistent session container. Request body: 
{
  "sessionId": "my-session",
  "path": "/sandbox/data.csv",
  "content": "Y29sMSxjb2wyCjEsMg=="
}
​
sessionId
string
required
The session ID of the persistent container.
​
path
string
required
Absolute file path inside the container.
​
content
string
required
Base64-encoded file content.
Success response (200): 
{ "ok": true }
Error response (404): 
{ "error": "Session not found" }

​
GET /file

Download a file from a persistent session container. Query parameters:
​
sessionId
string
required
The session ID.
​
path
string
required
Absolute file path inside the container.
Example: 
curl "http://localhost:3000/file?sessionId=my-session&path=/sandbox/output.json" \
  -H "Authorization: Bearer my-key"
Success response (200): 
{
  "content": "eyJyZXN1bHQiOiAxfQ=="
}
Error responses:
  • 400 — Missing sessionId or path parameter
  • 404 — Session not found

​
DELETE /session/:id

Stop and remove a persistent session. Destroys the container and frees resources. Example: 
curl -X DELETE http://localhost:3000/session/my-session \
  -H "Authorization: Bearer my-key"
Response (200): 
{ "ok": true }
Returns { "ok": true } even if the session didn’t exist (idempotent).