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.
Request body for creating an ephemeral sandbox.
| Field | Type | Required | Description |
|---|---|---|---|
runtime | string | null | No | Runtime image. node22 is available today; other values are rolling out and fail placement until their images ship. |
resources | object | No | Resource shape. Defaults: 1 vCPU, 512 MB memory, 5 GB disk. |
timeout_ms | integer | null (int64) | No | Hard lifetime in milliseconds (60000..86400000, default 300000). The sandbox also stops earlier at its idle timeout. |
ports | array<integer (int32)> | No | Guest ports to expose. |
source | object | No | {type: "git", url, branch?} clones a repository into the sandbox. |
env | object | No | Environment variables for the guest. |
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.
Request body for running a command inside a sandbox.
| Field | Type | Required | Description |
|---|---|---|---|
cmd | string | Yes | |
args | array<string> | No | |
cwd | string | null | No | Working directory inside the guest. |
env | object | No | |
detached | boolean | null | No | Run without waiting for completion. |
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.
Request body for extending a sandbox's hard deadline.
| Field | Type | Required | Description |
|---|---|---|---|
duration_ms | integer (int64) | Yes | Milliseconds to add to the current expiry. |
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.
Request body for writing files into a sandbox. Writable roots inside the guest are /app, /scalix, /build, and /tmp.
| Field | Type | Required | Description |
|---|---|---|---|
files | array<object> | Yes | Files to write: [{path, content}]. |
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