Skip to main content
The terminal WebSocket provides full PTY access to the sandbox shell. It behaves like an SSH session - you send keystrokes, receive output, and can resize the terminal.

Connection

Obtain ws_token from the Token Exchange endpoint with capability: "terminal". Required scope: sessions:terminal

Authentication

The token query parameter authenticates the connection. If the token is invalid or expired, the server closes the WebSocket immediately with code 4001.

Message format

The terminal uses text frames for all communication:

Sending input

Send keystrokes as plain text frames. The server writes them directly to the PTY’s stdin:
Use \r (carriage return) to submit commands, just like pressing Enter in a terminal.

Receiving output

Output from the shell arrives as text frames. These include ANSI escape codes for color, cursor movement, and other terminal formatting. Use a terminal emulator library (e.g. xterm.js) to render them correctly.

Resizing the terminal

Send a JSON control message to resize the PTY:
The server resizes the PTY to match. Send a resize message whenever the user’s terminal viewport changes.

Example: full connection

Connection limits

Only one terminal WebSocket connection is allowed per session at a time. Opening a second connection closes the first with code 4009.

Idle timeout

The server closes idle terminal connections after 10 minutes of no input. Send any character to keep the connection alive.