Documentation
Upcoming sandbox API endpoints
Coming soon. These API features are not available yet.
Authentication and prefix
Use a bearer access token or workspace API key. Paths below follow /v1/customer/tenants/{tenantId}/sandboxes/{sandboxId}. Permissions never grant access to another workspace. Runzivo turns SSH, repository tokens and OpenHands on separately. None is on yet.
SSH and repository access
- GET /ssh-host: sandboxes:read. 200 with host_ca_public_key and host_key_alias. Public trust material, no connection ticket.
- POST /ssh-ticket: sandboxes:write. {public_key}. 201. Single-use ticket: 30 seconds. User certificate: fifteen minutes. Never log credentials.
- GET /ssh?ticket=...: 101 WebSocket. Raw SSH bytes. Use the CLI proxy and keep host-key verification.
- POST /repository-token: {repository, push?}. 200. One authorized owner/name. The push field defaults to false. Read requires sandboxes:write plus repositories:read. Push requires sandboxes:write plus repositories:write. Guest delivery is not automatic.
OpenHands task contract
- GET /agent: 200. POST /agent with {}: 202. DELETE /agent: 200. Read status, start or stop the server. Active does not prove readiness.
- POST /agent/tasks: {session_id, prompt, model_budget_micro_usd?}. 202. Requires sandboxes:write and ai_chat:use. The budget is an internal ceiling, not a price.
- GET /agent/tasks: 200. GET /agent/tasks/output?task_id=ID&after=N: 200 NDJSON. Status for readers. Events for sandbox writers.
- POST /agent/tasks/steer: {task_id, prompt}. POST /agent/tasks/pause or /agent/tasks/resume: {task_id}. Owner only. Controls are queued. Do not automatically retry a follow-up.
- DELETE /agent/tasks?task_id=ID: 200. Sandbox writers can cancel the task and its server.