Reference / Agent Sandboxes

Create a terminal ticket

Issue a single-use ticket so a browser can open the terminal without an Authorization header.

POST/v1/customer/tenants/{tenantId}/sandboxes/{sandboxId}/terminal-ticket

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

Requires a running sandbox. A ticket lasts about 30 seconds and is bound to one sandbox and workspace.
Append the URL-encoded ticket as ?ticket= to the returned terminal URL. Do not log the query string. A sandbox can have at most ten unused tickets (429 ticket_limit_reached).
Browser WebSocket connections cannot supply Authorization. Use the ticket without an Authorization header; API and CLI clients can instead authenticate the terminal directly.

Responses

HTTP response codes
Status	Meaning
201 Created	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.
429 Too many tickets	Ten unused tickets already exist for this sandbox.
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.

Ticket response fields

Terminal ticket
Field	Description
`url`stringRequired	Absolute wss URL of this sandbox's terminal.
`ticket`stringRequired	Single-use ticket, valid for about 30 seconds. Append as a URL-encoded query parameter.
`expires_at`date-timeRequired	When the ticket expires.

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}/terminal-ticket" \
  --header "Authorization: Bearer ${RUNZIVO_TOKEN}"

Response example

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

201 · application/json

{
  "url": "wss://api.runzivo.dev/v1/customer/tenants/<tenant-id>/sandboxes/sbx_000000000000000000000001/terminal",
  "ticket": "<single-use-ticket>",
  "expires_at": "2026-10-31T12:00:30Z"
}

All response examples (also available without JavaScript)

201 Created

Illustrative response; values and timing vary in your workspace.

application/json

{
  "url": "wss://api.runzivo.dev/v1/customer/tenants/<tenant-id>/sandboxes/sbx_000000000000000000000001/terminal",
  "ticket": "<single-use-ticket>",
  "expires_at": "2026-10-31T12:00:30Z"
}

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

429 Too many tickets

Ten unused tickets already exist for this sandbox.

application/json

{
  "error": {
    "code": "ticket_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"
  }
}