Terminal Channel

PTY terminal sessions over WebSocket

Overview

The terminal channel provides multiplexed PTY terminal sessions. Multiple concurrent sessions can run over a single WebSocket connection.

Default terminal settings:

Setting	Value
Shell	bash
TERM	xterm-256color
Columns	80
Rows	24

Client to Server Messages

create

Create a new terminal session.

{
  "channel": "terminal",
  "type": "create",
  "sessionId": "cli-123",
  "cols": 120,
  "rows": 40
}

Field	Type	Required	Description
sessionId	string	Yes	Unique identifier for this terminal session
cols	integer	No	Terminal width in columns (default: 80)
rows	integer	No	Terminal height in rows (default: 24)

input

Send keyboard input to a terminal session.

{
  "channel": "terminal",
  "type": "input",
  "sessionId": "cli-123",
  "data": "ls -la\n"
}

Field	Type	Required	Description
sessionId	string	Yes	Target terminal session
data	string	Yes	Raw input data (include \n for Enter, \t for Tab, etc.)

resize

Resize a terminal session. Send this when the user resizes their terminal UI.

{
  "channel": "terminal",
  "type": "resize",
  "sessionId": "cli-123",
  "cols": 200,
  "rows": 50
}

Field	Type	Required	Description
sessionId	string	Yes	Target terminal session
cols	integer	Yes	New width in columns
rows	integer	Yes	New height in rows

close

Close a terminal session and terminate its process.

{
  "channel": "terminal",
  "type": "close",
  "sessionId": "cli-123"
}

Field	Type	Required	Description
sessionId	string	Yes	Terminal session to close

Server to Client Messages

output

Terminal output data from the PTY.

{
  "channel": "terminal",
  "type": "output",
  "sessionId": "cli-123",
  "data": "total 48\ndrwxr-xr-x  12 user  staff   384 Feb 20 10:30 .\n"
}

Field	Type	Description
sessionId	string	Source terminal session
data	string	Raw terminal output including ANSI escape codes

close

Terminal session has ended (process exited).

{
  "channel": "terminal",
  "type": "close",
  "sessionId": "cli-123",
  "exitCode": 0
}

Field	Type	Description
sessionId	string	Terminal session that closed
exitCode	integer or null	Process exit code, or null if terminated by signal

Example Flow