Reference / Agent Sandboxes

Create a sandbox

Create a sandbox and request its first start.

POST/v1/customer/tenants/{tenantId}/sandboxes

Base URL: https://api.runzivo.dev

Authentication

Send Authorization: Bearer <token> with a customer access token or workspace API key.

API key permission: sandboxes:write. These are permissions, not legacy scopes. A key with the all:all scope also works, limited by its creator's current workspace permissions.

Parameters

Path and query parameters
Field	Description
`tenantId`string · pathRequired	Your workspace's tenant ID. Replace the placeholder with an ID your token can access.

Request body

Send Content-Type: application/json.

JSON request fields
Field	Description
`name`stringRequired	1–80 characters after trimming. A live sandbox name must be unique in the workspace.
`size`stringRequired	2vcpu-8gb, 4vcpu-16gb, 8vcpu-32gb or 16vcpu-64gb. Choose a size from the list response's sizes field.
`disk_gib`integerOptional	5–64 GiB; default 20.
`client_operation_id`stringOptional	8–200 characters. Reusing this value returns the sandbox first created for it.

Behavior and limits

Send application/json. Request body limit: 4 KiB. Unknown JSON fields are rejected.
A successful request returns 201 and a bare Sandbox object. Poll its status; a response is not proof that the VM is ready.
Conflicts include sandbox_limit_reached, credit_exhausted, sandbox_name_taken, size_unavailable and workspace_blocked. The eight-hour lifetime runs from the first start, not from the browser or CLI opening.

Responses

HTTP response codes
Status	Meaning
201 Created	application/json
400 Invalid request	Malformed JSON, unknown fields or invalid values. Terminal upgrades also reject malformed handshakes.
401 Unauthorized	Missing or invalid bearer token. A ticketed terminal request can instead return ticket_invalid.
403 Forbidden	The caller lacks workspace membership or permission, or the API key is not allowed. Codes include tenant_membership_required, permission_required and api_key_scope_required.
409 Conflict	Creation was refused by the workspace limit, credit, name, size or workspace controls. Codes include sandbox_limit_reached, credit_exhausted, sandbox_name_taken, size_unavailable and workspace_blocked.
500 Internal error	The server could not complete the request.
503 Unavailable	Sandbox service is unavailable. Exec and terminal operations can also return sandbox_exec_unavailable.

Examples use synthetic IDs, dates and values. Read the actual response and status in your workspace.

Sandbox response fields

Success returns a Sandbox object directly, with these fields.

Sandbox object
Field	Description
`id`stringRequired	Sandbox ID: sbx_ followed by 24 lowercase hexadecimal characters.
`name`stringRequired	Workspace sandbox name.
`size`stringRequired	The selected size identifier.
`disk_gib`integerRequired	Workspace disk size in GiB.
`status`stringRequired	pending, starting, running, stopping, stopped, deleting, deleted, expired or failed.
`error`object \| nullRequired	null, or {code, message} explaining a failed sandbox.
`created_at`date-timeRequired	When the sandbox was created.
`started_at`date-time \| nullRequired	First start; null until it starts.
`expires_at`date-time \| nullRequired	First start plus eight hours. Stopping does not pause the lifetime.
`remaining_seconds`integerRequired	Lifetime left; 28800 before first start, 0 once expired or deleted.
`runtime_seconds`integerRequired	Seconds the VM has been up; excludes stopped time.
`credits_used`numberRequired	Unit-minutes charged at the size's multiplier.

Sandbox limits and billing →

Page tools

View as Markdown

Ask AI about this page

Open in ChatGPT Open in Claude Open in Cursor

Claude shows a caution banner on any prefilled prompt. That is expected: review the prompt, then send it.

Request example

Illustrative request. Set RUNZIVO_TOKEN and TENANT_ID in your shell. Replace placeholders with your own values. This page does not send requests.

cURL

curl --request POST \
  "https://api.runzivo.dev/v1/customer/tenants/${TENANT_ID}/sandboxes" \
  --header "Authorization: Bearer ${RUNZIVO_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "docs-example",
  "size": "2vcpu-8gb",
  "disk_gib": 20,
  "client_operation_id": "docs-create-example-01"
}'

Response example

application/json · Illustrative response; values and timing vary in your workspace.

201 · application/json

{
  "id": "sbx_000000000000000000000001",
  "name": "docs-example",
  "size": "2vcpu-8gb",
  "disk_gib": 20,
  "status": "pending",
  "error": null,
  "created_at": "2026-10-31T12:00:00Z",
  "started_at": null,
  "expires_at": null,
  "remaining_seconds": 28800,
  "runtime_seconds": 0,
  "credits_used": 0
}

All response examples (also available without JavaScript)

201 Created

Illustrative response; values and timing vary in your workspace.

application/json

{
  "id": "sbx_000000000000000000000001",
  "name": "docs-example",
  "size": "2vcpu-8gb",
  "disk_gib": 20,
  "status": "pending",
  "error": null,
  "created_at": "2026-10-31T12:00:00Z",
  "started_at": null,
  "expires_at": null,
  "remaining_seconds": 28800,
  "runtime_seconds": 0,
  "credits_used": 0
}

400 Invalid request

Malformed JSON, unknown fields or invalid values. Terminal upgrades also reject malformed handshakes.

application/json

{
  "error": {
    "code": "invalid_request"
  }
}

401 Unauthorized

Missing or invalid bearer token. A ticketed terminal request can instead return ticket_invalid.

application/json

{
  "error": {
    "code": "unauthorized"
  }
}

403 Forbidden

The caller lacks workspace membership or permission, or the API key is not allowed. Codes include tenant_membership_required, permission_required and api_key_scope_required.

application/json

{
  "error": {
    "code": "permission_required"
  }
}

409 Conflict

Creation was refused by the workspace limit, credit, name, size or workspace controls. Codes include sandbox_limit_reached, credit_exhausted, sandbox_name_taken, size_unavailable and workspace_blocked.

application/json

{
  "error": {
    "code": "sandbox_limit_reached"
  }
}

500 Internal error

The server could not complete the request.

application/json

{
  "error": {
    "code": "internal_error"
  }
}

503 Unavailable

Sandbox service is unavailable. Exec and terminal operations can also return sandbox_exec_unavailable.

application/json

{
  "error": {
    "code": "sandboxes_unavailable"
  }
}