Skip to main content
The terminal uses a persistent WebSocket connection. It does not accept separate HTTP requests for individual shell commands. The browser SDK helper handles this protocol. Direct clients can use the wire format on this page.

​
Create credentials

Request a terminal session from the server. The response contains wsUrl, expiresAt, and an optional protocols array. The URL and protocols can contain temporary credentials. They belong only to the deployment owner.

​
Open the socket

Pass the protocols to the WebSocket constructor:
The organization API key does not belong in this connection. A socket-open event does not mean that the shell is ready.

​
Control messages

Control messages use text frames with JSON: Before input, wait for ready. After readiness, send the latest terminal dimensions. The SDK clamps dimensions to integers from 1 through 500. A direct client must also send valid positive dimensions.

​
Input and output

Terminal data uses binary frames. Input is UTF-8 text:
Binary output arrives as ArrayBuffer data. A terminal renderer can consume those bytes as a Uint8Array. A text decoder must preserve partial UTF-8 characters between output frames. xterm accepts byte arrays directly.

​
Reconnect and expiration

Every reconnect requires a new terminal-session request. The previous URL and protocols are not reusable credentials for a new connection. The client does not replay previous input. A closed socket does not end the lab. An expired or ended lab can reject session creation. The learner must request a separate lab launch to start another environment. expiresAt is the deadline for connection authorization. It does not set the shell lifetime or deployment deadline. An existing connection can continue after token expiration until the lab ends.