System Architecture
LMESH is designed as an event-driven, low-latency terminal streaming pipeline. Below is the technical breakdown of the monorepo packages, binary WebSocket framing, concurrency control, and security boundaries.
Package Ecosystem
LMESH is structured as a TypeScript monorepo with strict module boundaries separating OS shell execution, network relaying, and browser presentation:
Native host agent. Spawns local POSIX PTY / Windows ConPTY instances via node-pty, manages raw stdin/stdout streams, and captures terminal escape sequences.
Relay broker. Manages stateful WebSocket sessions, validates authorization tokens, coordinates Redis Pub/Sub multi-instance clusters, and persists audit logs to PostgreSQL.
Next.js client interface. Instantiates WebGL-accelerated xterm.js canvases, renders collaborative session dashboards, and manages OAuth authentication flows.
Data Flow & Transmission
networkingData moves bidirectionally across persistent WebSocket connections with zero polling overhead:
WebSocket Protocol Framing
framingLMESH envelopes all terminal control messages and binary terminal chunks into standardized JSON protocol frames:
{
"type": "input" | "output" | "resize" | "grant_control" | "revoke_control" | "safety_mode",
"sessionId": "x7k2m9p",
"payload": "base64_or_utf8_string",
"meta": {
"rows": 34,
"cols": 120,
"sender": "@octocat"
},
"timestamp": 1788944000000
}Security & Concurrency Guarantees
safeguardsLMESH enforces hardware and protocol safeguards to guarantee that remote terminal sharing cannot compromise the host operating system:
Only one client possesses write access to the PTY stdin stream at any time. Broadcasted viewer keystrokes are dropped server-side without queuing.
The host retains master override capability. Striking Escape or Ctrl+] instantly severs remote control.
The CLI sets LMESH_ACTIVE=1 in the child shell environment. Any attempt to spawn nested shared shells is caught and blocked.
Because the host establishes an outbound WebSocket connection to the relay, no inbound firewall ports or router NAT rules need to be opened.
Horizontal Scaling via Redis
clusterIn multi-node production setups, relay servers run statelessly behind a load balancer. When a host connects to Node A and collaborators connect to Node B, Redis Pub/Sub automatically bridges chunk broadcasting and control events with sub-millisecond propagation latency.