Sandboxes API
Ephemeral microVM sandboxes for agent code execution
REST API endpoints for Sandboxes. 9 operations.
List your sandboxes
GET /v1/sandboxesAuth: Bearer API key
Responses
| Status | Description |
|---|---|
200 | {sandboxes: [...], total} |
401 | Missing or invalid API key |
operationId: sandboxList
Create an ephemeral sandbox
POST /v1/sandboxesBoots an isolated microVM. Ephemeral sandboxes are disposable: they stop at their idle or hard timeout and nothing on the rootfs persists past stop. Compute is billed per vCPU-hour and GB-hour of allocation while running.
Auth: Bearer API key
Request body
application/json (required) — schema SandboxCreateRequest.
Responses
| Status | Description |
|---|---|
201 | Sandbox created (initially PROVISIONING) |
401 | Missing or invalid API key |
402 | Credit exhausted or plan limit reached |
503 | No capacity for the requested resources |
operationId: sandboxCreate
Delete a sandbox and tear down its microVM
DELETE /v1/sandboxes/{id}Auth: Bearer API key
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Sandbox id |
Responses
| Status | Description |
|---|---|
204 | Deleted |
404 | Not found |
operationId: sandboxDelete
Get a sandbox by id
GET /v1/sandboxes/{id}Auth: Bearer API key
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Sandbox id |
Responses
| Status | Description |
|---|---|
200 | Sandbox details |
404 | Not found |
operationId: sandboxGet
Run a command inside a running sandbox (synchronous)
POST /v1/sandboxes/{id}/commandsAuth: Bearer API key
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Sandbox id |
Request body
application/json (required) — schema SandboxCommandRequest.
Responses
| Status | Description |
|---|---|
200 | Command result |
400 | Sandbox is not running |
404 | Not found |
operationId: sandboxRunCommand
Extend a sandbox's hard deadline
POST /v1/sandboxes/{id}/extendAuth: Bearer API key
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Sandbox id |
Request body
application/json (required) — schema SandboxExtendRequest.
Responses
| Status | Description |
|---|---|
200 | Updated sandbox |
404 | Not found |
operationId: sandboxExtend
Write files into a sandbox
POST /v1/sandboxes/{id}/filesAuth: Bearer API key
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Sandbox id |
Request body
application/json (required) — schema SandboxWriteFilesRequest.
Responses
| Status | Description |
|---|---|
204 | Files written |
404 | Not found |
502 | Path outside the allowed guest roots |
operationId: sandboxWriteFiles
Read a file from a sandbox. The guest path follows /files/
GET /v1/sandboxes/{id}/files/{path}Auth: Bearer API key
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Sandbox id |
path | path | string | Yes | Guest file path, e.g. app/output.json |
Responses
| Status | Description |
|---|---|
200 | File content (application/octet-stream) |
404 | File or sandbox not found |
operationId: sandboxReadFile
Snapshot a sandbox - not available
POST /v1/sandboxes/{id}/snapshotEphemeral sandboxes are disposable; state does not persist past stop. This endpoint returns 501 until snapshots ship (demand-gated).
Auth: Bearer API key
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Sandbox id |
Responses
| Status | Description |
|---|---|
501 | Snapshots are not available for ephemeral sandboxes |
operationId: sandboxSnapshot