# Upcoming sandbox API endpoints

Coming soon. Planned API contract, subject to change. 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 available in production 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. Planned limits: a single-use ticket lasting 30 seconds and a user certificate valid for 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 will require sandboxes:write plus repositories:read. Push will require 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}. Require sandboxes:write and ai_chat:use. Owner only. Controls are queued. Do not automatically retry a follow-up.
- DELETE /agent/tasks?task_id=ID: 200. Any sandbox writer will be allowed to cancel the task and its server.

## Related pages and language

[SSH](https://runzivo.dev/docs/sandboxes-devx-api-ssh/)

[Repository token](https://runzivo.dev/docs/sandboxes-devx-api-repository-token/)

[OpenHands server](https://runzivo.dev/docs/sandboxes-devx-api-agent-server/)

[OpenHands tasks](https://runzivo.dev/docs/sandboxes-devx-api-agent-tasks/)

[Controls and events](https://runzivo.dev/docs/sandboxes-devx-api-agent-controls/)

[Français (Canada)](https://runzivo.dev/docs/sandboxes-devx-api-fr-ca/)

On this page and page tools