Documentation
OpenHands server lifecycle
Coming soon. Planned API contract, subject to change. These features are not available yet in production.
Authentication and path
Paths follow /v1/customer/tenants/{tenantId}/sandboxes/{sandboxId}. Requests will use a bearer customer access token or a workspace API key. The sandbox and repository grants below are key permissions, not legacy scopes. A key with all:all will also work, within its creator’s current permissions. The SSH relay uses its ticket instead of a bearer token.
GET, POST and DELETE /agent
GET will require sandboxes:read or sandboxes:write and will return 200. POST will require sandboxes:write. Its only optional body will be {}. POST will return 202 for a queued or existing session. DELETE will require sandboxes:write and return 200 with stopped or idle. DELETE will be idempotent and stay allowed after the feature is turned off. An active status will not prove the server is ready.
Response fields and availability
SandboxAgent will contain enabled, status (idle, active, stopped or failed), nullable session_id and exit_code, reason, tasks_available, task_unavailable_reason (empty, model_proxy_required, model_limit or permission_required) and readiness=unverified. Starting will need the feature turned on, the OpenHands image and a running sandbox. Otherwise POST will return 503 with sandbox_agent_unavailable, sandbox_exec_unavailable or sandboxes_unavailable. Reads and saved output will stay available after the feature is turned off. Not every read will return 503 in that state.
GET /agent/output
This route will require read permission. The session_id parameter will be required (sxe_ plus 24 hex characters). The after parameter will be an optional integer of 0 or more, default 0. A 200 response will use application/x-ndjson. Each stdout or stderr line will carry seq and base64 data, followed by exit fields when the stream closes. Planned limits: 8 MiB of server output, kept up to 24 hours after closure. Readers will rotate after 110 seconds. Reconnect with the last seq. Disconnecting will not cancel the server. A 404 with sandbox_agent_not_started will mean the server has not started. A 409 with sandbox_agent_session_changed will mean you need to refresh the status. Other statuses will be 400, 401, 403, 500 and 503.