Shell & tunnels
Open an interactive shell or forward a local TCP port into a sandbox you own. Authenticate with your API key and resume a paused sandbox before connecting. These API connections do not require an SSH key or public ingress.
Base URL: https://api.sb.createos.sh.
POST /v1/sandboxes/{id}/tunnel/{port}
Open one bidirectional TCP connection to a port inside the sandbox. port must be 1–65535. Authenticate with X-Api-Key and use HTTP/1.1 with Connection: Upgrade and Upgrade: tcp-tunnel headers.
On success, the response is 101 Switching Protocols. After the headers, exchange raw TCP bytes over the upgraded connection. It is not a JSON response or an NDJSON stream. Open a separate tunnel for each forwarded TCP connection.
For local forwarding, use the CLI:
Bash
Keep the command running, then connect to localhost:3000.
POST /v1/sandboxes/{id}/shell
Open an interactive PTY using the same authenticated HTTP/1.1 upgrade. Success returns 101 Switching Protocols with Upgrade: tcp-tunnel. The shell protocol carries terminal input and resize messages; this is not the exec endpoint.
Client-to-server frames start with a one-byte type and a four-byte unsigned big-endian payload length, followed by the payload. Type 0x00 carries terminal input; type 0x01 carries resize data as two unsigned 16-bit big-endian values, rows then columns. Server-to-client output is raw terminal bytes.
Use createos sandbox shell "$SANDBOX_ID" for a terminal client. For a shell you need to detach from and reconnect to later, use a managed PTY.
GET /v1/sandboxes/{id}/shell-ws
WebSocket transport for the interactive PTY. Use wss://api.sb.createos.sh/v1/sandboxes/{id}/shell-ws with an authenticated WebSocket handshake. Clients that cannot set headers can use the supported token query parameter; avoid logging credential-bearing URLs.
The server sends terminal output in binary WebSocket messages. Clients send the shell protocol's input and resize frames in binary messages. Use the managed-process API when you need JSON-based input and resize operations.
Shell endpoints return 409 until the sandbox is running, 404 for an unknown or unowned sandbox, and 502 if the connection cannot be opened. A WebSocket request without the upgrade returns 426. Proxies between your client and the API must support the selected upgrade protocol.
POST /v1/sandboxes/{id}/ssh-pubkeys
Append public keys for SSH-specific access. Body:
JSON
The server deduplicates existing keys and returns { "status": "success", "data": { "count": 1 } }, where count is the total number of authorized keys. Default API shell/tunnel access does not need this step.