Skip to main content

[ REFERENCE / API ]

API reference

Base URL = http://127.0.0.1:9090 (set by SANDBOXD_API_BIND). Auth is off by default for local use; with SANDBOXD_API_AUTH_DISABLED=false + SANDBOXD_API_TOKENS, send -H "Authorization: Bearer <secret>".

Endpoints​

Method & pathBodyPurpose
POST /sandbox{"ports":[3000],"env":{...}}create — id optional (ULID auto); env injects vars (e.g. API keys)
GET /sandboxes—list all sandboxes
GET /sandbox/{id}—get one (status, ports, container id…)
POST /sandbox/{id}/exec{"cmd":["bash","-lc","…"]}run a command (non-interactive: no TTY/stdin)
POST /sandbox/{id}/keepalive—postpone the idle reaper
POST /v1/sandboxes/{id}/stop—stop now to free RAM (wakes on next preview hit)
DELETE /sandbox/{id}—destroy the container, keep the workspace
POST /sandbox/{id}/purge—destroy and delete the workspace
POST /v1/sandboxes/{id}/tasks{"prompt":"…","agent":"opencode"}run a coding agent headlessly
GET /v1/sandboxes/{id}/tasks/{taskId}—task result
GET /v1/sandboxes/{id}/tasks/{taskId}/events—live task event stream (SSE)
GET/PUT /v1/sandboxes/{id}/files{"path","content","append"}list / read / write workspace files
GET /healthz, GET /readyz—liveness / readiness

Notes​

  • Create returns the sandbox row including id and status. env injects variables into the container (e.g. agent provider keys like ANTHROPIC_API_KEY).
  • Exec is non-interactive — no TTY, no stdin.
  • Files: PUT /v1/sandboxes/{id}/files with {"path":"...","content":"...","append":false} writes a file into the workspace; GET /v1/sandboxes/{id}/files lists files and GET /v1/sandboxes/{id}/files/content?path= reads one.
  • Tasks run via runtimed inside the sandbox; the response includes an events_url for the SSE stream. See Agents.
  • Stop vs destroy vs purge: stop frees RAM and wakes on the next preview hit; DELETE destroys the container but keeps the workspace; purge deletes the workspace too.

Authenticated example​

curl -s -XPOST http://127.0.0.1:9090/sandbox \
  -H "Authorization: Bearer secret" \
  -H 'content-type: application/json' \
  -d '{"ports":[3000],"env":{"ANTHROPIC_API_KEY":"sk-ant-..."}}'

A complete, copy-pasteable runbook (including driving sandboxd from your own agent) is in AGENTS.md.