# agent-next sandbox gateway (SBX)

E2B-compatible multi-tenant API for agent sandboxes. The stock e2b SDKs work
unmodified: point them at the gateway with these env vars.

  export E2B_API_URL="https://sbx-api.agent-next.com"       # control plane
  export E2B_SANDBOX_URL="https://sbx-api.agent-next.com"   # sandboxes: routed by E2b-Sandbox-Id header
  export E2B_API_KEY="$SBX_API_KEY"        # your tenant key (e2b_… secret)

Base URL for raw HTTP: https://sbx-api.agent-next.com
Auth: X-API-Key header carrying the tenant key (the SDK sends it for you).
Errors: {"code": <status>, "message": "..."} — every 401/402/403/404/429 also
carries `hint` (the next move) + `docs_url`; retriable 429s carry an integer
Retry-After header; a quota 429 also carries `running`/`limit`, and 5xx
answers carry `status` (the public status page) + `error_id`.

## The 5 most useful endpoints

  POST   /sandboxes/{id}/prompt                queue a headless agent task
                                               (managed prompt; watch /events)
  GET    /sandboxes/{id}/events                 its event log (after/limit)
  POST   /v2/sandboxes                        create a sandbox (v1: POST /sandboxes)
  GET    /v2/sandboxes                        list your sandboxes (state/metadata filters)
  POST   /v2/sandboxes/{id}/connect           connect / resume (v1: /sandboxes/{id}/connect)
  DELETE /sandboxes/{id}                      kill a sandbox
  GET    /v0/usage                            your usage + remaining credit hours
  POST   /events/webhooks                      register a lifecycle webhook
                                             (sandbox.lifecycle.*; HMAC-signed
                                             deliveries, secret rotation)

## curl example

  curl -s -H "X-API-Key: $SBX_API_KEY" \
       https://sbx-api.agent-next.com/sandboxes

  curl -s -X POST -H "X-API-Key: $SBX_API_KEY" \
       -H "Content-Type: application/json" \
       -d '{"templateID":"base","timeout":300}' \
       https://sbx-api.agent-next.com/sandboxes

## Safe retries

  Send an Idempotency-Key header (a UUID of your own) on
  POST /sandboxes, POST /v2/sandboxes and POST /sandboxes/{id}/fork:
  the first call creates the sandbox and binds it to the key; a retry
  with the same account key, Idempotency-Key and body returns that same
  sandbox (no second billable one). While the first is still in flight:
  409 idempotency_in_progress. Same key, different body: 409
  idempotency_key_reused. Bindings live 24 h; a failed create releases
  its key so the retry can create. Omit the header for the default
  non-idempotent behavior.

## MCP tools

The same sandbox surface as eleven remote-MCP tools (streamable HTTP):
https://sbx-api.agent-next.com/mcp/v1 — auth is the same X-API-Key header
(OAuth-capable twin endpoint: https://mcp.agent-next.com/mcp). Smoke test
(tools/list must name the eleven tools):

  curl -s https://sbx-api.agent-next.com/mcp/v1 \
    -H "X-API-Key: $SBX_API_KEY" -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

## GPU sandboxes (gated: the key needs a GPU grant or a tier with GPU)

  curl -s -X POST -H "X-API-Key: $SBX_API_KEY" -H "Content-Type: application/json" \
       -d '{"accel":{"vram_gb":2}}' https://sbx-api.agent-next.com/sandboxes
  # 201 -> {"sandboxID":"gl-…","templateID":…,"phase":"resident","accel":{…}}; use it as $ID
  POST   /sandboxes/$ID/exec    {"code": "<python>", "timeout_s": 60}  (Python source)
  POST   /sandboxes/$ID/pause   release the GPU, state kept; /resume restores it
                                (a suspend_mode "none" template freezes and keeps its seat;
                                 on a hard-cap host so does a lease whose processes other than
                                 its worker hold VRAM)
  DELETE /sandboxes/$ID         free the slice (always, in a finally)
  Limits: accel.vram_gb 0.5-32 GiB; timeout_s <= 3600 and an overrun kills the
  lease; one job at a time; 8 live leases per key on each GPU host or node (a
  verified-tier key holds 1 in total; a paused lease counts). No network unless
  the create sets accel.network "internet" on a node that allows it (else 400).
  Idle time bills 0 (only exec and sampled-busy seconds accrue), except
  a suspend_mode "none" lease, which bills its whole residency, and a pause that
  froze the lease, which bills the frozen time.
  Free tier trial (defaults): 1 lease, vram_gb <= 2, class nvidia.5090,
  default template only, no internet egress, idle_timeout_s 60-600; more is a
  403 gpu_free_tier_limit whose message says how to lift it.
  Detail: /llms-full.txt (GPU LEASE LIFECYCLE), /openapi.json (accel schema).

## GPU lease uploads

  PUT /sandboxes/{gl-id}/files/{name} — raw file bytes, streamed into the
  lease OUTPUT_DIR (a lease has no network unless created with accel.network
  "internet"). Use curl --upload-file:
    curl -H "X-API-Key: $SBX_API_KEY" --upload-file input.bin \
      "https://sbx-api.agent-next.com/sandboxes/$GPU_ID/files/inputs/input.bin"
  200 -> {name, size, sha256}. Relative paths only; no symlinks or '..'.
  Front and node cap: GATEWAY_GPU_MAX_UPLOAD_BYTES, default 512 MiB (413).
  Paused/frozen/transitioning -> 409; dead/foreign/unknown -> 404.
  Uploads land in the job's OUTPUT_DIR; GET files/file returns them.
  Any absolute path under /tmp or the lease directory (the parent of
  OUTPUT_DIR): PUT/GET /sandboxes/{gl-id}/files?path=/tmp/cache/weights.
  Other paths -> 400 path_outside_roots; links/non-regular files -> 404.
  Available only with the accel plane/node mode and public container execution.

## GPU lease exec

  POST /sandboxes/{gl-id}/exec — Python code in the persistent lease namespace.
  report is reset to {} at the start of every exec; other variables persist
  across execs and pause/resume. report is user data: report["exit_code"] = 1
  does not change ok:true when the job returns normally. Exceptions/timeouts
  fail the job; a report field alone does not.

## More docs

  /openapi.json    OpenAPI 3.1 spec of every public route
  /llms-full.txt   full endpoint reference in plain text
  /auth.md         no key yet? the agent registration contract
  /health          E2B-style liveness (plain text, no auth)
  /healthz         liveness probe (JSON)
  /v0/facts        the limits and prices the docs quote, as JSON (no auth)

Docs: https://sbx.agent-next.com/docs/ — quickstart, limits, coding agents
Docs: https://sbx.agent-next.com/docs/agents/ — for agents: MCP server, plugin + skill, CLI,
  and one copy-paste setup per client (Claude Code, Codex, zcode, Cursor, Gemini CLI,
  OpenCode, droid, devin, Claude web/desktop, ChatGPT, personal agents, OpenClaw).
  A config is only called working after that client's end-to-end run passes; until
  then it is labelled "being verified". Status as JSON: https://sbx.agent-next.com/docs/agents/clients.json
Docs: https://sbx.agent-next.com/docs/clients/claude-code/ — connect Claude Code over MCP (X-API-Key or OAuth)
Docs: https://sbx.agent-next.com/docs/templates/ — which template to pick, and adding packages at runtime
Docs: https://sbx.agent-next.com/docs/gpu/ — GPU sandboxes: create, exec, pause/resume, files, billing, errors
Docs as Markdown: every docs page has a Markdown twin: its URL plus /index.md,
  e.g. https://sbx.agent-next.com/docs/quickstart/index.md (also errors, limits,
  changelog); /llms-full.txt includes them all.

## Durable checkpoint artifacts

PUT /v1/artifacts/{sha256} publishes raw immutable bytes; GET the same path
retrieves them and GET /v1/artifacts lists bounded metadata. X-API-Key identifies
the tenant. Validate SHA-256 after download. Limits: 16 MiB/object, 64 MiB and
64 objects/key, 1 GiB and 65536 objects globally. Writes are denied while
suspended; authenticated reads remain available. Same database file survives
process restart and disposable sandbox deletion. No replicated-storage,
backup, power-loss or CUDA process migration guarantee.

## Durable trial tasks (candidate API)

The bounded `/v1/tasks` ledger references tenant-owned artifact hashes for
`gpu-scalar-sgd-v1`. Claim returns a token and incremented attempt; begin must
precede external dispatch, renew extends a 10–120 second lease, and finish
requires the live token/attempt. Expired claims can be reclaimed; expired or
cancelled executions require reconciliation and are never automatically
replayed. The ledger does not run GPU jobs or settle usage. Same-file process
restart persistence is tested; HA, power-loss durability and remote GPU
termination are separate responsibilities.