Connection URL
Authentication
The terminal WebSocket requires the computer’s password as thetoken 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
input
input
resize
resize
ping
ping
Send a heartbeat ping to keep the connection alive.
Server → Client Messages
output
output
pong
pong
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.