Sandboxes API

Compute primitives: isolated execution with exec, files, logs. For stateful agent conversations, use Sessions API.

Templates

standard

Minimal Linux rootfs

browser

Chromium headless

cua

Xvfb + fluxbox + Chromium + OmniParser for agent desktop control

canvas

HTML canvas rendering

Create Sandbox

POSTapi.e2a.bot/v1/sandboxes

Create a new sandbox. Optionally attach an agent for one-shot execution.

Request

{
  "template": "standard",                  // required: "standard" | "browser" | "cua" | "canvas"
  "agent": "claude-code",                  // optional: "deictic" | "claude-code" | "codex" 
  "llm_key": "sk-ant-...",                 // required if agent is set
  "task": "summarize README.md",           // optional: one-shot prompt
  "model": "claude-sonnet-4-5",            // required for deictic; prefix-validated for claude-code/codex
  "idle_timeout_seconds": 60,              // optional, default 60
  "max_lifetime_seconds": 7200,            // optional, default + hard cap 7200
  "env_vars": { "MY_VAR": "value" },       // optional; reserved keys rejected
  "metadata": { "tag": "prod" }            // optional free-form
}

Response (201)

{
  "vm_id": "sbx_7f3k9m2x",
  "state": "running",
  "host_port": 30090,
  "endpoint": "http://worker-ip:9090"
}
CodeMeaningWhen
201Createdsandbox provisioned and Running
400Bad requestmissing required field, reserved env-var key, agent without llm_key
401Unauthorizedmissing or invalid API key
409Conflictno capacity on any worker
501Not implementedunknown agent type or template
503Service unavailableno workers registered

List Sandboxes

GETapi.e2a.bot/v1/sandboxes

List all sandboxes owned by the authenticated user.

Response (200)

[
  {
    "vm_id": "sbx_7f3k9m2x",
    "state": "running",
    "vcpu": 1,
    "cpu_fraction": 0.5,
    "memory_mib": 512,
    "metadata": { "tag": "prod", "user_id": "usr_abc" }
  }
]

// Partial failure returns wrapped object:
{ "sandboxes": [...], "partial": true }

Get Sandbox

GETapi.e2a.bot/v1/sandboxes/{id}

Get details for a specific sandbox.

Response (200)

{
  "vm_id": "sbx_7f3k9m2x",
  "state": "running",
  "vcpu": 1,
  "cpu_fraction": 0.5,
  "memory_mib": 512,
  "rootfs": "standard.ext4",
  "metadata": { "tag": "prod" },
  "agent_exit_code": 0,                    // optional; present once agent exits
  "agent_status": "completed"              // "running" | "completed" | "failed"
}
CodeMeaningWhen
200OKsandbox found and caller owns it
401Unauthorizedmissing or invalid API key
404Not foundno such sandbox or cross-tenant access

Execute Command

POSTapi.e2a.bot/v1/sandboxes/{id}/exec

Execute a shell command inside the sandbox via SSH. Blocking.

Request

curl -X POST https://api.e2a.bot/v1/sandboxes/sbx_7f3k9m2x/exec \
  -H "Authorization: Bearer e2a_live_..." \
  -H "Content-Type: application/json" \
  -d '{"command": "echo hello && ls /workspace"}'

Response (200)

{
  "output": "hello\ntotal 0\n"
}

Destroy Sandbox

DELETEapi.e2a.bot/v1/sandboxes/{id}

Destroy a sandbox. Synchronous — returns once teardown is complete.

Response (200)

{
  "vm_id": "sbx_7f3k9m2x",
  "state": "destroyed"
}
CodeMeaningWhen
200OKsandbox destroyed
401Unauthorizedmissing or invalid API key
404Not foundno such sandbox or cross-tenant access

Get Logs

GETapi.e2a.bot/v1/sandboxes/{id}/logs

Fetch stdout/stderr logs from the sandbox.

Query Parameters

NameTypeDescription
limitintegerMax lines (default 100)
sinceISO 8601Only logs after this timestamp

Cancel Sandbox

POSTapi.e2a.bot/v1/sandboxes/{id}/cancel

Send a cooperative cancel signal to the agent. Agent decides how to respond.

Response (200)

{
  "vm_id": "sbx_7f3k9m2x",
  "cancelled": true,
  "reason": "user_request"
}

To forcibly destroy the VM, use DELETE /v1/sandboxes/{id}.

Previous

Authentication

Next

Sessions API