Reference / Agent Sandboxes

Start a sandbox

Start a stopped or failed sandbox without resetting its original expiry.

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

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.
`sandboxId`string · pathRequired	The id returned when the sandbox was created: sbx_ followed by 24 lowercase hexadecimal characters.

Request body

No request body is required.

Behavior and limits

Conflicts include sandbox_expired, sandbox_wrong_state, sandbox_limit_reached, credit_exhausted, size_unavailable and workspace_blocked. A start returns a status transition, not a ready terminal.

Responses

HTTP response codes
Status	Meaning
200 OK	application/json
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.
404 Not found	No sandbox with this ID exists in the authorized workspace.
409 Conflict	The operation is not allowed in the current sandbox state. See the operation notes for other possible conflict codes.
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, and SANDBOX_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/${SANDBOX_ID}/start" \
  --header "Authorization: Bearer ${RUNZIVO_TOKEN}"

Response example

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

200 · application/json

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

All response examples (also available without JavaScript)

200 OK

Illustrative response; values and timing vary in your workspace.

application/json

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

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"
  }
}

404 Not found

No sandbox with this ID exists in the authorized workspace.

application/json

{
  "error": {
    "code": "sandbox_not_found"
  }
}

409 Conflict

The operation is not allowed in the current sandbox state. See the operation notes for other possible conflict codes.

application/json

{
  "error": {
    "code": "sandbox_wrong_state"
  }
}

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"
  }
}