Terminal Streaming Protocol

A protocol for remote terminal sessions with durable output streaming and resumable connections.

What is Terminal Streaming Protocol?

The Terminal Streaming Protocol enables remote terminal access over HTTP with full resumability. Unlike traditional WebSocket-based terminals, sessions survive disconnections - clients can reconnect and replay any missed output from the exact point they left off.

Built on top of Unbroken Protocol, it combines:

• PTY (Pseudo-Terminal) for shell interaction
• Unbroken Protocol for output persistence and resumption
• HTTP for input delivery

Key Features

Feature	Description
Resumable	Reconnect and continue from any point
Persistent Output	Full session history preserved
Web Native	Works in browsers via SSE
CLI Compatible	Long-polling for terminal clients
Low Latency	Batched I/O for responsive interaction

Architecture

┌─────────────────────────────────────────────────────────────┐
│                         Client                               │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │  Terminal   │    │   Input     │    │   Offset    │     │
│  │  Renderer   │    │   Buffer    │    │   Storage   │     │
│  └──────┬──────┘    └──────┬──────┘    └──────┬──────┘     │
└─────────┼──────────────────┼──────────────────┼─────────────┘
          │ SSE/Long-poll    │ POST             │
          ▼                  ▼                  │
┌─────────────────────────────────────────────────────────────┐
│                    Terminal Server                           │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │   Durable   │◀───│     PTY     │◀───│   Input     │     │
│  │   Stream    │    │   Process   │    │   Handler   │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
└─────────────────────────────────────────────────────────────┘

Quick Example

# Create a terminal session
curl -X PUT http://localhost:9999/terminal/my-session \
  -H "Content-Type: application/json" \
  -d '{"cols": 80, "rows": 24}'

# Stream output (SSE)
curl "http://localhost:9999/terminal/my-session?offset=-1&live=sse"

# Send input
curl -X POST http://localhost:9999/terminal/my-session/input \
  -d "ls -la"$'\r'

# Resize terminal
curl -X POST http://localhost:9999/terminal/my-session/resize \
  -H "Content-Type: application/json" \
  -d '{"cols": 120, "rows": 40}'

Protocol at a Glance

Endpoints

Method	Path	Description
PUT	/terminal/{id}	Create session
GET	/terminal/{id}?offset=X	Read output (catch-up)
GET	/terminal/{id}?offset=X&live=sse	Stream output (SSE)
POST	/terminal/{id}/input	Send input
POST	/terminal/{id}/resize	Resize terminal
DELETE	/terminal/{id}	Kill session
HEAD	/terminal/{id}	Check session exists

Headers

Header	Direction	Description
Stream-Next-Offset	Response	Offset for resumption
Stream-Up-To-Date	Response	At end of output

SSE Event Types

Event	Description
data	Terminal output (JSON-encoded string)
control	Stream metadata with offset

Input Protocol

Input	Bytes	Description
Enter	\r	Carriage return
Ctrl+C	\x03	Interrupt (SIGINT)
Ctrl+D	\x04	End of file
Ctrl+Z	\x1A	Suspend (SIGTSTP)
Up Arrow	\x1b[A	Escape sequence
Down Arrow	\x1b[B	Escape sequence

Use Cases

• Remote Development: SSH-like access over HTTP
• Cloud Shells: Browser-based terminal for cloud platforms
• Session Recording: Full session replay for auditing
• Pair Programming: Share terminal sessions with replay
• CI/CD Logs: Live streaming build output with history

Specification

For the complete protocol specification, see PROTOCOL.md.

Default Port

The terminal server uses port 9999/tcp by default (same as Unbroken Protocol).

Requirements

• Server: Bun runtime with bun-pty package
• Client: Any HTTP client (browser, curl, custom)