API Reference
REST API for sandbox lifecycle, execution, files, snapshots, fork, hibernate, audit, and network policy.
Full spec: openapi.yaml (OpenAPI 3.1)
Base URL: https://run-<region>.isorun.ai (the region segment matches the one embedded in your API key).
All /v1/* endpoints require Authorization: Bearer <api-key>.
The base URL's region segment is fixed by your API key, isorun_live_us_... resolves to https://run-us.isorun.ai. You don't choose it per request.
Create a sandbox
curl -X POST https://run-us.isorun.ai/v1/runs \
-H "Authorization: Bearer $ISORUN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "python:3.12-slim", "vcpus": 1, "mem_mib": 1024}'{
"id": "run78cbccbab85efc28",
"status": "running",
"image": "python:3.12-slim",
"region": "us",
"vcpus": 1,
"mem_mib": 1024,
"disk_mib": 4096,
"create_ms": 9,
"created_at": "2026-05-26T12:00:00Z"
}Optional fields: disk_mib, timeout (auto-destroy seconds), network: { allow, deny }, network_profile, credentials.
Execute a command
curl -X POST https://run-us.isorun.ai/v1/runs/run78cbccbab85efc28/exec \
-H "Authorization: Bearer $ISORUN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"command": "python3 -c \"print(1+1)\"", "timeout": 30}'{
"exit_code": 0,
"stdout": "2\n",
"stderr": ""
}Destroy a sandbox
curl -X DELETE https://run-us.isorun.ai/v1/runs/run78cbccbab85efc28 \
-H "Authorization: Bearer $ISORUN_API_KEY"{
"status": "destroyed",
"cpu_ms": 48,
"mem_peak_bytes": 48926720,
"uptime_ms": 59000,
"cost_cents": 0.0007
}All endpoints
| Method | Path | Description |
|---|---|---|
GET | /healthz | Health check (no auth) |
POST | /v1/runs | Create a sandbox |
GET | /v1/runs | List active sandboxes |
GET | /v1/runs/{id} | Get sandbox status |
DELETE | /v1/runs/{id} | Destroy a sandbox |
PATCH | /v1/runs/{id} | Reset the auto-destroy timer |
POST | /v1/runs/{id}/exec | Execute command (JSON response) |
POST | /v1/runs/{id}/exec/stream | Execute command (SSE stream) |
GET | /v1/runs/{id}/terminal?token=KEY | WebSocket PTY terminal |
GET | /v1/runs/{id}/shell | WebSocket long-lived bash session |
POST | /v1/runs/{id}/snapshot | Snapshot a running sandbox |
POST | /v1/runs/restore | Restore from snapshot |
POST | /v1/runs/{id}/fork | Fork the running sandbox |
POST | /v1/runs/{id}/hibernate | Pause + persist to disk |
POST | /v1/runs/{id}/resume | Restore a hibernated sandbox |
POST | /v1/runs/{id}/files/upload?path=PATH | Upload file |
GET | /v1/runs/{id}/files/download?path=PATH | Download file |
GET | /v1/runs/{id}/files?path=PATH | List directory |
GET | /v1/runs/{id}/audit | NDJSON audit trail |
GET | /v1/runs/{id}/proxy/{port}/* | Reverse-proxy a guest port |
GET | /v1/snapshots | List snapshots |
DELETE | /v1/snapshots/{id} | Delete a snapshot |
GET | /v1/runs/history | Past (destroyed) sandboxes |
GET | /v1/usage | Usage / cost rollup |
GET | /v1/network-profiles | List named egress profiles |
GET | /v1/images | List supported OCI images |
POST | /v1/images/build | Build an image from a registry |
See the OpenAPI spec for request/response schemas, error codes, and parameter constraints.
Next steps
- TypeScript SDK, the typed client over these endpoints.
- Authentication, how API keys and regions work.
- Network filtering, the
networkandnetwork_profilecreate fields.