Docs
Sign in

Sandboxes

Run code and commands

Send source code to run, or a shell command to exec. Both execute inside the sandbox and return its output; neither goes through a scheduler on the way.

Once a sandbox exists, these calls go straight from the API to the machine your sandbox lives on, and from there to the agent inside the VM over vsock.

Run source code

POST /session/{sandbox_id}/run

curl -sS -X POST "$SPAWN_API_URL/session/$SANDBOX_ID/run" \
  -H "Authorization: Bearer $SPAWN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "python",
    "code": "print(6 * 7)",
    "timeout": 10
  }'
Response 200 OK 
{
  "status": "success",
  "request_id": "eb3d0130-2de1-4f86-8651-038b9a747dab",
  "session_id": "3ecb0221-faf1-4976-a8ae-6fd6262de59a",
  "result": {
    "stdout": "42\n",
    "stderr": "",
    "exit_code": 0,
    "termination_reason": "success",
    "duration_ms": 54.1,
    "guest_duration_ms": 17.8
  },
  "usage": {
    "execution_time_ms": 17.8,
    "queue_wait_ms": 0,
    "timeout_limit_ms": 30000
  },
  "session": {
    "state": "active",
    "last_used": "2026-08-17T11:01:00Z",
    "expires_at": "2026-08-17T11:03:00Z",
    "run_count": 1
  },
  ...
}
language string required
python, node or bash.
code string required
The source to run.
timeout integer
Seconds before the run is stopped. Defaults to your account’s default and is capped at limits.max_execution_ms.

Runtimes stay warm

Python and Node run in long-lived interpreters inside the sandbox, so variables, imports and loaded data carry over from one run to the next — much like cells in a notebook:

Two runs, one interpreter 
{ "language": "python", "code": "import json\ndata = {'answer': 42}" }
{ "language": "python", "code": "print(json.dumps(data))" }   → stdout: {"answer": 42}

Interpreter state lives in memory only. It’s reset if the sandbox is paused and resumed; files on disk are kept.

Timings

guest_duration_ms is how long the code ran inside the VM. duration_ms is the whole round trip measured by the API, including the hop to the machine and back.

Run a shell command

POST /session/{sandbox_id}/exec

Runs a command in the sandbox’s shell with access to its whole filesystem. The response has the same shape as run.

curl -sS -X POST "$SPAWN_API_URL/session/$SANDBOX_ID/exec" \
  -H "Authorization: Bearer $SPAWN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "cd /workspace && node --version",
    "timeout": 10
  }'
command string required
The shell command to run.
timeout integer
Seconds before the command is stopped.

When code fails

If your code or command exits with a non-zero code, the HTTP request still succeeds with 200 — the sandbox did its job. The body tells you the program failed:

200 OK 
{
  "status": "error",
  "error": {
    "code": "execution_failed",
    "message": "process exited with code 1"
  },
  "result": {
    "stdout": "",
    "stderr": "Traceback (most recent call last): ...",
    "exit_code": 1,
    ...
  },
  ...
}

For exec the code is exec_failed. Check status or result.exit_code, and show stderr to your agent so it can fix its code and try again.

Ctrl I