API Reference

Request

{
  "template": "standard",                  // required: "standard" | "browser" | "cua" | "canvas"
  "agent": "claude-code",                  // optional: "deictic" | "claude-code" | "codex"
  "llm_key": "sk-ant-...",                 // required iff agent is set
  "task": "summarize README.md",           // optional: one-shot prompt; absent ⇒ agent waits on WS
  "model": "claude-sonnet-4-5",            // required for deictic; prefix-validated for claude-code/codex
  "session_id": "abcd-1234",               // optional: codex resume uuid
  "wire_version": 2,                       // optional, default 2; set 1 only for legacy single-agent
  "idle_timeout_seconds": 60,              // optional, default 60
  "max_lifetime_seconds": 7200,            // optional, default + hard cap 7200
  "workspace_enabled": false,              // optional, default false
  "app_id": "my-app",                      // required iff workspace_enabled
  "capset_id": "default",                  // required iff workspace_enabled
  "app_json": {                            // optional; nested capability_sets schema (see notes)
    "name": "My App",
    "capability_sets": [{
      "name": "general",
      "agents": [{
        "name": "primary",
        "capability_name": "general",
        "capability_description": "general-purpose worker",
        "tools": ["read_file", "write_file", "shell_exec"]
      }]
    }]
  },
  "persistence_url": "https://chat.example.com/persist", // optional; HTTPS-only, public-IP only
  "persistence_auth_header": "Bearer sk_…",              // optional; verbatim Authorization header
  "env_vars": { "MY_VAR": "value" },       // optional; reserved keys rejected
  "metadata": { "tag": "prod" }            // optional free-form
}

Response

{
  "vm_id": "sbx_7f3k9m2x",
  "state": "running",
  "host_port": 30090,
  "endpoint": "http://worker-ip:9090"     // optional; orchestrator's self-reported node endpoint
}

Status codes

Notes

• Reserved env-var keys cannot be passed via env_vars or agent_env: AGENT_TYPE, LLM_KEY, LLM_MODEL, TASK, SESSION_ID, AGENT_CMD, AGENT_SESSION_MODE, E2A_PERSISTENCE_URL, E2A_PERSISTENCE_AUTH_HEADER, WORKSPACE_USER_ID, WORKSPACE_APP_ID, WORKSPACE_CAPSET_ID, WORKSPACE_MODE.
• app_json schema (NESTED — replaces the legacy flat tools/system_prompt shape from PR #90): { name, capability_sets: [{ name, agents: [{ name, capability_name, capability_description, tools }] }] }. Multiple agents across one or more capability_sets enable planner-routed multi-agent execution on wire_version=2. Omitting app_json yields the e2a default — single agent, four-tool default (read_file, write_file, list_directory, shell_exec). Submitting the legacy flat shape (top-level tools or system_prompt) returns HTTP 400.
• wire_version=1 is supported only for single-agent app_json (one agent across all capability_sets). Multi-agent + wire_version=1 returns HTTP 400 with "multi-agent requires wire_version=2". Default is 2.
• persistence_url enables customer-supplied conversation persistence (Bring-Your-Own HTTP backend implementing the Persistence wire contract). MUST be HTTPS; SSRF allowlist rejects loopback, link-local, RFC1918, IPv6 ULA fc00::/7, cloud-metadata IPs, IPv4 0.0.0.0/8 — both literal IPs and hostnames that resolve to disallowed ranges. persistence_auth_header (any scheme: Bearer / Basic / ApiKey / custom) is sent verbatim as the HTTP Authorization header on every persistence call. See the BYO Persistence guide for a worked customer-backend example.
• agent_cmd must be absolute and start with /home/user/ or /workspace/. Max 512 bytes.
• Workspace mounting is performed at WS-attach time, not at VM boot. workspace_enabled + app_id + capset_id surface the config; the runtime mounts on session open.

Response

// Full success — returns JSON array of VmResponse objects
[
  { "vm_id": "sbx_7f3k9m2x", "state": "running", "vcpu": 1, "cpu_fraction": 0.5, ... },
  ...
]

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

Status codes

Notes

• partial: true appears when at least one worker failed or timed out and the merged list is incomplete. Clients should surface this to users rather than treating it as empty state.
• Filtering happens on the worker side — the orchestrator only returns VMs whose metadata user_id matches the Bearer's user.

Response

{
  "vm_id": "sbx_7f3k9m2x",
  "state": "running",
  "vcpu": 1,
  "cpu_fraction": 0.5,
  "memory_mib": 512,
  "rootfs": "standard.ext4",
  "metadata": { "tag": "prod", "user_id": "usr_abc" },
  "agent_exit_code": 0,                          // optional; present once agent exits
  "agent_status": "completed"                    // optional; "running" | "completed" | "failed"
}

Status codes

Notes

• agent_exit_code and agent_status are omitted for non-agent sandboxes and for VMs not in the Running state.
• agent_status transitions from running → completed (exit 0) or failed (non-zero exit). The sentinel is /tmp/agent.exit inside the VM.

Response

{
  "vm_id": "sbx_7f3k9m2x",
  "state": "destroyed"
}

Status codes

Notes

• Active WebSocket proxy tasks receive an explicit Close frame (code 1001, reason "sandbox destroyed") rather than waiting for TCP keepalive to observe the dead upstream.

Request

{
  "command": "echo hello && ls /workspace"
}

Response

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

Status codes

Query parameters

Response

{
  "content": "...",
  "truncated": false,
  "total_bytes": 12345
}

Status codes

Notes

• truncated: true means the content returned is smaller than the underlying file (total_bytes). With bytes mode, the first partial line is also dropped so the body never starts mid-line.
• Absolute body cap is 1 MiB regardless of lines or bytes — requests above that ceiling trim from the start at the first newline.

Query parameters

Response

// Content-Type: application/octet-stream
// Body: raw file bytes

Status codes

Query parameters

Request

// Content-Type: application/octet-stream
// Body: raw file bytes

Response

{
  "status": "uploaded"
}

Status codes

Request

// Body is optional; defaults to { "reason": "user_request" } when empty.
{
  "reason": "user_request"                 // "credits_exhausted" | "user_request" | "admin_action" | "timeout"
}

Response

{
  "vm_id": "sbx_7f3k9m2x",
  "cancelled": true,                       // true if any WS subscriber received the broadcast
  "reason": "user_request"
}

Status codes

Notes

• The cancel broadcast is a cooperative signal — the agent running in the sandbox decides how to react. Deidict + claude-code + codex handle it by wrapping up and writing to /tmp/result.txt before exit.
• To forcibly destroy the VM, use DELETE /v1/sandboxes/{id}.

Request

{
  "agent": { "kind": "deictic", "version": "b4232d5" },
  "template": "cua",                       // required: "cua" | "browser" | "standard"
  "llm": {
    "vendor": "anthropic",                 // required: "anthropic" | "openai" | "google" | "deepseek"
    "model": "claude-sonnet-4-5",          // optional: override default model for vendor
    "base_url": "https://proxy.example.com/v1"  // optional: custom LLM endpoint (HTTPS only)
  },
  "secrets": ["my-llm-keys"],              // optional: secret bundle names to inject (see Secrets API)
  "app": { "id": "my-app", "set_id": "default", "capability_sets": {} },
  "user_id": "user_uuid_123",              // required; flat tenant model = your tenant_id
  "ttl_seconds": 3600                      // optional, default 3600, hard cap 7200
}

Response

{
  "chat_session_id": "ses_abc123",
  "jwt": "eyJ...",                         // session JWT — exp ≈ ttl_seconds; HS256
  "connect_url": "wss://rt.e2a.bot/v1/sessions/ses_abc123/ws",
  "expires_at": "2026-04-28T13:00:00Z"
}

Status codes

Notes

• Templates accepted: standard | browser | cua. Discover via GET /v1/templates.
• agent.kind accepted: deictic (only at MVP). codex + claude-code are post-MVP additions.
• The session JWT in connect_url is short-lived (1h default); the WSS handshake validates it server-side. Browser clients can pass it via ?token= query (Authorization header is not browser-set on WS).
• secrets: array of bundle names created via POST /v1/tenants/me/secrets. At most 10 bundles per session. Keys are merged; collision across bundles returns 400. LLM_API_KEY is the universal key name for LLM credentials (vendor-agnostic).
• llm.model regex: ^[a-zA-Z0-9._-]{1,128}$. llm.base_url must be HTTPS and pass the SSRF allowlist (no loopback, RFC1918, link-local, cloud-metadata IPs).

Request

{
  "chat_session_id": "ses_abc123",
  "ttl_seconds": 3600
}

Response

{
  "chat_session_id": "ses_abc123",
  "jwt": "eyJ...",                         // NEW JWT — fresh exp
  "connect_url": "wss://rt.e2a.bot/v1/sessions/ses_abc123/ws",
  "expires_at": "2026-04-28T13:00:00Z",
  "resumed_from": {
    "previous_status": "completed"         // pre-resume state.status; "unknown" when state predates the field
  }
}

Status codes

Notes

• Idempotent for ~30s: rapid double-resume calls within the lock-cache window return the SAME jwt + connect_url payload (Redis lock per chat_session_id).
• Cross-tenant probe distinguishes 403 (exists, you don't own it) from 404 (never existed) — better audit signal for enumeration attacks.
• Reconciler-driven retry vs customer-driven resume share the claim_retry atomic primitive (canary scope) to prevent double-spawn under contention.
• Resume recovers the original llm.model, llm.base_url, and secrets references from state storage — no need to re-specify them.

Status codes

Notes

• Full frame shape + close codes documented in the Protocols section's WebSocket entry.
• Single connection per chat_session_id at a time; second concurrent upgrade closes the first with code 1011.

Session JWT claims

Frames

{ "type": "exec", "command": "ls -la" }           // client → server
{ "type": "stdout", "data": "total 68\n" }         // server → client
{ "type": "exit", "exit_code": 0 }                  // server → client

{ "type": "system", "event": "cancel", "reason": "timeout" }

{ "type": "system", "event": "config_update", "keys": ["LLM_API_KEY"] }

code=1001, reason="server shutting down"
code=1001, reason="sandbox destroyed"
code=1011, reason="upstream unavailable"

Notes

• The session JWT is not exposed to the client — the orchestrator mints it internally and forwards it to the runtime via the upstream upgrade URL.
• Text frames sent by the agent may be intercepted by the orchestrator's metering path (runtime_event messages are counted toward billing). Binary frames are never parsed.

Flow

1. Create session with template: "cua" via POST /v1/sessions (or set env_vars.CUA_ENABLED="true" for custom setups).
2. Open WebSocket to wss://rt.e2a.bot/v1/sessions/{chat_session_id}/ws using the JWT returned at create time. The session JWT carries cua_enabled: true, which unlocks the CUA tool context on the runtime side.
3. Agent calls tools: screenshot, locate_element (OmniParser YOLO+OCR), mouse_click, mouse_move, keyboard_type, press_key, scroll, shell_exec.
4. Each screenshot response is delivered to the client as a binary WebSocket frame (raw PNG).
5. Mouse and keyboard events from the client (or from the agent reasoning loop) are sent as text frames and replayed into the VM via xdotool/enigo.

Notes

• Default display geometry is 1920x1080x24. OmniParser runs locally at http://127.0.0.1:8765 inside the VM and serves YOLO icon detection + Florence-2 captioning.
• The runtime does not re-compress screenshots — image quality and encoding are whatever the agent's capture path produces (PNG by default).

Flow

1. Submit POST /v1/sandboxes with agent, task, llm_key, model, and (optionally) session_id for codex resume.
2. Orchestrator injects AGENT_TYPE, TASK, LLM_KEY, LLM_MODEL, SESSION_ID into the VM's /app/config/env.json.
3. Inside the VM, bootstrap-agent.sh dispatches based on AGENT_TYPE — runs /usr/local/bin/agent (deictic), claude --print … (claude-code), or codex exec … (codex).
4. Agent stdout is tee'd to /tmp/result.txt. Agent exit code is written to /tmp/agent.exit.
5. Poll GET /v1/sandboxes/{id} — agent_status transitions running → completed | failed, agent_exit_code becomes populated.
6. Retrieve output via GET /v1/sandboxes/{id}/logs (tails /tmp/result.txt), or via POST /v1/sandboxes/{id}/exec with cat /tmp/result.txt for a single synchronous read.

Notes

• Known agent types: deictic, claude-code, codex.
• claude-code and codex are pre-baked npm-installed CLIs. ANTHROPIC_BASE_URL and OPENAI_BASE_URL are allow-listed for proxy scenarios (e.g., enterprise gateways).
• The same flow can be made interactive instead of one-shot: omit task at create time and drive the agent via WebSocket.