WebSocket API

Live terminal streaming over WebSocket at /ws/{session_id}.

Connection

const ws = new WebSocket('wss://localhost:8081/ws/coding-0');

WebSocket connections require authentication via session cookie (same-origin).

Message Format

All messages are JSON except for PNG frame data which is sent as binary.

Server → Client Messages

session_assigned

Sent immediately after connection with server-assigned session word

Fields:

Field	Description
log_session	Server-assigned session identifier for log correlation

status

Sent with each frame containing current state

Fields:

Field	Description
frame	Capture counter for sync
program	Detected program name
state	Current state (Idle, Working, Blocked, Error)
detail	State detail string
scroll	Scroll state object
cols	Terminal width
rows	Terminal height

error

Sent when an error occurs

Fields:

Field	Description
message	Error description

ack

Acknowledgment of received input message

Fields:

Field	Description
msgId	ID of acknowledged message

version_mismatch

Sent when client version doesn't match server

Fields:

Field	Description
client_version	Client's reported version
server_version	Server's required version

session_terminated

Sent when session is terminated due to new login

Fields:

Field	Description
reason	Termination reason (new_login)
ip	IP address of new login
hostname	Hostname of new login location
location	Geographic location of new login

Binary Frames

PNG image data is sent as binary WebSocket frames after each status message.

Client → Server Messages

quality

Update viewer quality settings

Fields:

Field	Description
fps	Frame rate (0.1-10.0)
retina	Enable 2x resolution
palette	Enable 8-bit color quantization
client_version	Client version for sync check

keys

Send literal text to terminal

Fields:

Field	Description
text	Text to send

enter

Send Enter key

ctrl

Send Ctrl+key combination

Fields:

Field	Description
key	Single character (e.g., 'c' for Ctrl+C)

special

Send special key

Fields:

Field	Description
key	Key name: Escape, Tab, Backspace, Up, Down, Left, Right, Home, End, PageUp, PageDown, Delete

scroll

Control scroll mode

Fields:

Field	Description
direction	up, down, or exit

batch

Send multiple actions in sequence

Fields:

Field	Description
actions	Array of action objects

Example Session

const ws = new WebSocket('wss://localhost:8081/ws/coding-0');

ws.onopen = () => {
  // Set quality preferences
  ws.send(JSON.stringify({
    type: 'quality',
    fps: 2.0,
    retina: true,
    client_version: window.CLIENT_VERSION
  }));
};

ws.onmessage = (event) => {
  if (typeof event.data === 'string') {
    const msg = JSON.parse(event.data);
    if (msg.type === 'status') {
      console.log(`State: ${msg.state}`);
    }
  } else {
    // Binary PNG frame
    const blob = new Blob([event.data], { type: 'image/png' });
    img.src = URL.createObjectURL(blob);
  }
};

// Send keystrokes
ws.send(JSON.stringify({ type: 'keys', text: 'hello' }));
ws.send(JSON.stringify({ type: 'enter' }));
ws.send(JSON.stringify({ type: 'ctrl', key: 'c' }));