Skip to content
LogoLogo

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 to 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:

createos sandbox tunnel --remote 3000 --local 3000 "$SANDBOX_ID"

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:

{ "keys": ["ssh-ed25519 <public-key> <comment>"] }

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.