Skip to main content
Connect to an interactive terminal session on a computer via WebSocket. This provides a full PTY (pseudo-terminal) interface, enabling real-time bidirectional communication with the computer’s shell.

Connection URL

Authentication

The terminal WebSocket requires the computer’s password as the token query parameter. This is the same password used for VNC connections. Retrieve it from the Get VNC Password endpoint before connecting. Connections without a valid token are rejected with close code 4401.

Query Parameters

string
required
Computer password. Retrieve via the Get VNC Password endpoint.
number
default:"80"
Number of columns for the terminal.
number
default:"24"
Number of rows for the terminal.

Message Protocol

All messages are JSON-encoded. The WebSocket uses a simple request/response protocol with the following message types.

Client → Server Messages

Send keyboard input to the terminal.
string
required
Must be "input".
string
required
The input string to send. Use \r for Enter key.
Resize the terminal dimensions.
string
required
Must be "resize".
number
required
New number of columns.
number
required
New number of rows.
Send a heartbeat ping to keep the connection alive.

Server → Client Messages

Terminal output data.
string
Always "output".
string
The terminal output. May contain ANSI escape codes for colors and formatting.
Error message from the server.
string
Always "error".
string
Human-readable error description.
The shell process has exited.
string
Always "exit".
number
Exit code of the shell process.
Response to a ping message.

Examples

Integration with xterm.js

For browser-based terminal UIs, we recommend using xterm.js:

Best Practices

Heartbeat

Send periodic ping messages (every 30 seconds) to keep the connection alive and detect disconnections early.

Reconnection

Implement automatic reconnection with exponential backoff. Start with 2 seconds and increase up to 30 seconds.

Resize Events

Send resize messages whenever the terminal container size changes to ensure proper text wrapping.

ANSI Support

The terminal output may contain ANSI escape codes. Use a library like xterm.js that handles these automatically.
The terminal WebSocket provides direct shell access. For running individual commands programmatically, consider using the Execute Bash endpoint instead.

Close codes