Documentation
SSH host, ticket and relay
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.
Host trust /ssh-host
GET /ssh-host will require sandboxes:read or sandboxes:write. A 200 response will return host_ca_public_key (the Ed25519 host CA) and host_key_alias (sbx_… .sandbox.runzivo.dev). It will work for a stopped sandbox and create no credentials. Keep StrictHostKeyChecking yes and use the returned CA and HostKeyAlias.
Ticket /ssh-ticket
POST /ssh-ticket will require sandboxes:write and a running sandbox. The JSON field public_key will be required. It will need to contain one Ed25519 or ECDSA P-256 OpenSSH public key without options, at most 4096 UTF-8 bytes. The request body will be limited to 8 KiB. A 201 response will return url, ticket, expires_at, certificate, certificate_expires_at, principal=user, host_ca_public_key and host_key_alias. Planned limits: the ticket will be single use and last 30 seconds. The user certificate will be valid for fifteen minutes. Never log either one.
Relay /ssh
GET /ssh?ticket=… will take the issued ticket instead of a bearer header. A 101 response will upgrade to a WebSocket. Binary frames will carry raw SSH bytes. A text frame {"type":"eof"} will half-close one direction. OpenSSH will need the CLI ProxyCommand. There will be no public SSH port. Planned limits: two sessions per sandbox, a 30-minute idle timeout and an 8 MiB unread-output cap.
Errors
The host route will return 401, 403, 404, 500 and 503. The ticket route will also return 400, 409 and 429 ticket_limit_reached. The relay will also return 400, 409, 426 websocket_required and 429 rate_limited. A 503 with sandbox_ssh_unavailable will mean SSH, its CAs or the run’s host certificate are unavailable. The message and message_fr_CA fields will sometimes suggest a restart. Other missing prerequisites will return sandboxes_unavailable or sandbox_exec_unavailable.