GitHub - theblag/lmesh: Share your terminal with a single command. Collaborators join via browser - no SSH, no setup. Role-based access, live command logging, and instant control handoff built in.

Live Multi-user Execution Shell
Real-time, low-latency collaborative terminal streaming and pair programming over secure WebSockets.

Overview • Installation • CLI Usage • Key Capabilities • System Architecture • Self-Hosting • Security Model

Overview

LMESH functions like tmux or tmate modernised for the web. A host starts a session from their local terminal, and remote teammates can join instantly via an encrypted URL in any modern browser without installing software, configuring SSH keys, or opening inbound firewall ports.

LMESH ensures strict host sovereignty through a single-token write mutex: remote users can watch in real time with 60 FPS WebGL terminal rendering, while control handover requires host permission and can be preempted immediately by the host's physical keyboard.

Key Capabilities

Zero Inbound Port Configuration: Uses outbound-only TLS 1.3 WebSocket pipes (wss://). Traverses NATs, corporate firewalls, and VPNs seamlessly.
Single-Token Concurrency Mutex: Strict token gating ensures only one participant holds write access at any time, eliminating keystroke race conditions.
Physical Host Preemption Guard: The host retains root authority. Any local physical keystroke immediately revokes remote write tokens.
Dual Terminal Synchronization: Synchronizes raw PTY buffer dimensions and SIGWINCH resize signals between OS pseudo-terminals (ConPTY on Windows, POSIX OpenPTY on Linux/macOS) and remote xterm.js viewports.
Private Mode (Ctrl+S): In-session hotkey that dynamically redacts sensitive environment variables, passwords, and API credentials from the persistent audit trail.
Horizontal Relay Scalability: Redis Pub/Sub cluster layer handles cross-instance broadcast and multi-node relay synchronization with instance deduplication.
GitHub Device Authorization: Secure login via GitHub OAuth Device Flow on the CLI and standard OAuth 2.0 on the web interface.

Installation

Install the LMESH CLI globally from the npm registry:

# Global installation via npm
npm install -g lmesh-cli

# Or using pnpm / yarn
pnpm add -g lmesh-cli
yarn global add lmesh-cli

Note: Global installation exposes both lmesh and lmesh-cli commands in your system PATH.

Instant Execution (`npx`)

You can also run commands on-the-fly without global installation:

# Authenticate via GitHub
npx lmesh-cli login

# Start sharing your terminal
npx lmesh-cli share

CLI Usage

The CLI automatically connects to the hosted LMESH relay network (wss://lmesh.onrender.com) and pairs with the web viewer at lmesh.vercel.app. Zero server configuration or inbound port forwarding is required.

1. Authenticate with GitHub

lmesh login

The CLI displays an 8-character verification code and opens GitHub Device Authorization. Once approved, verify your profile:

lmesh whoami

2. Share Your Shell

lmesh share

Spawns your local shell (powershell.exe / bash / zsh) inside a virtual pseudo-terminal (PTY) and streams it live over secure WebSockets:

Authenticated as @yourusername
Connecting to relay server at wss://lmesh.onrender.com...
Session created successfully!
Host: @yourusername
Share this link with collaborators:
https://lmesh.vercel.app/x7k2m9p
(Type 'exit' or press Ctrl+] to end session • Ctrl+S for Private Mode)

Collaborators open the link in any modern web browser to view your terminal in 60 FPS WebGL or request keyboard write control.

3. Command Flags & Options

# Share with password protection
lmesh share -w mySecretPassword

# Force read-only mode (collaborators cannot request control)
lmesh share --readonly

# Connect to a custom self-hosted relay
lmesh share -u ws://localhost:3001

Flag	Shorthand	Description
`--password <string>`	`-w`	Protects session access behind a password
`--readonly`	`-r`	Forces view-only mode (disables control requests)
`--url <wss_url>`	`-u`	Specifies custom relay WebSocket endpoint
`--help`	`-h`	Displays command options and flags

4. In-Session Hotkeys

Hotkey	Action	Description
`Ctrl+]` or `exit`	Terminate Session	Instantly closes the session and disconnects all collaborators.
`Ctrl+S`	Private Mode	Toggles audit-log redaction for passwords, API tokens, and secrets.
`y` / `n`	Control Approval	Responds to incoming remote write-token handover requests.
Any physical key	Host Preemption	Immediately revokes collaborator input and restores exclusive host control.

System Architecture

LMESH is divided into three tiers: Host Environment (packages/cli), Edge Relay Cluster (packages/server), and Collaborator Viewport (packages/web).

flowchart TD
    classDef host fill:#101726,stroke:#3b82f6,stroke-width:1.5px,color:#f8fafc;
    classDef daemon fill:#0f2038,stroke:#60a5fa,stroke-width:1.5px,color:#f8fafc;
    classDef relay fill:#1a1429,stroke:#a855f7,stroke-width:1.5px,color:#f8fafc;
    classDef storage fill:#261221,stroke:#ec4899,stroke-width:1.5px,color:#f8fafc;
    classDef client fill:#0c221a,stroke:#10b981,stroke-width:1.5px,color:#f8fafc;
    classDef active fill:#1e293b,stroke:#f59e0b,stroke-width:2px,color:#f8fafc;

    subgraph HOST ["Host Environment (packages/cli)"]
        direction TB
        HostShell["Host Shell<br/><code>bash / zsh / pwsh</code>"]:::host
        PtyEngine["Virtual PTY Engine<br/><code>node-pty (ConPTY / OpenPTY)</code>"]:::host
        CliDaemon["LMESH CLI Daemon<br/><code>Outbound WSS Client</code>"]:::daemon
        PreemptLock["Preemption Guard<br/><code>Physical Keypress Priority</code>"]:::daemon

        HostShell <-->|"Raw IO / SIGWINCH"| PtyEngine
        PtyEngine <-->|"stdio byte stream"| CliDaemon
        PreemptLock -.->|"Preempts remote token"| PtyEngine
    end

    subgraph RELAY ["LMESH Relay Cluster (packages/server)"]
        direction TB
        IngressGw["Ingress Gateway<br/><code>Port 443 • TLS 1.3 WSS</code>"]:::relay
        TokenMutex["Single-Token Mutex<br/><code>Write Lock Engine</code>"]:::relay
        SessionCoord["Session Coordinator<br/><code>JWT Auth & Participant State</code>"]:::relay

        subgraph BACKEND ["State & Clustering Layer"]
            direction LR
            RedisPubSub[("Redis Pub/Sub<br/><code>lmesh:session:* Fanout</code>")]:::storage
            PostgresDB[("PostgreSQL<br/><code>Redacted Audit Logs</code>")]:::storage
        end

        IngressGw <-->|"Control Frames"| TokenMutex
        IngressGw <-->|"Session State"| SessionCoord
        SessionCoord <-->|"Multi-Node Broadcast"| RedisPubSub
        SessionCoord -.->|"Async Persist"| PostgresDB
    end

    subgraph CLIENTS ["Collaborator Viewports (packages/web)"]
        direction TB
        ViewerA["Collaborator A (Viewer)<br/><code>xterm.js WebGL Canvas</code>"]:::client
        ViewerB["Collaborator B (Controller)<br/><code>Active Write Token Holder</code>"]:::active
        WebClient["Browser WebSocket Client<br/><code>Reconnect & Frame Multiplexer</code>"]:::client

        WebClient -->|"Fanout Output"| ViewerA
        WebClient <-->|"Token-Gated Stdin"| ViewerB
    end

    CliDaemon <==>|"Outbound TLS 1.3 WSS<br/>(Zero Inbound NAT Ports)"| IngressGw
    IngressGw <==>|"Multiplexed WSS<br/>(Binary Chunks & Control)"| WebClient

Session Lifecycle & Protocol Flow

sequenceDiagram
    autonumber
    actor Host as Host (Terminal & CLI)
    participant Relay as LMESH Relay Server
    participant Redis as Redis Pub/Sub
    actor Viewer as Collaborator (Web)

    Note over Host,Relay: 1. Session Initialization
    Host->>Relay: session_create (JWT auth, password, read-only flag)
    Relay-->>Host: session_created (session ID & secure viewer URL)

    Note over Relay,Viewer: 2. Collaborator Handshake
    Viewer->>Relay: session_join (session ID, optional password)
    Relay-->>Viewer: session_joined + session_update (initial viewport state)

    Note over Host,Viewer: 3. Real-Time Terminal Streaming & Fanout
    Host->>Relay: terminal_data (PTY stdout escape sequences)
    Relay->>Redis: Publish frame (lmesh:session:id)
    Redis-->>Relay: Multi-node cluster fanout
    Relay-->>Viewer: terminal_data (rendered via xterm.js WebGL)

    Note over Host,Viewer: 4. Token-Gated Control Delegation
    Viewer->>Relay: control_request
    Relay->>Host: control_request (CLI prompts host: y/n)
    Host->>Relay: control_grant
    Relay-->>Viewer: session_update (write token granted)
    Viewer->>Relay: terminal_data (collaborator stdin)
    Relay->>Host: terminal_data (injected into host virtual PTY)
    Host->>Relay: terminal_data (command output stream)
    Relay-->>Viewer: terminal_data (terminal canvas update)

    Note over Host,Viewer: 5. Host Sovereignty & Hardware Preemption
    Host->>Relay: control_revoke (physical keypress detected on host)
    Relay-->>Viewer: session_update (control reclaimed by host)

    Note over Host,Viewer: 6. Graceful Teardown
    Host->>Relay: session_terminate (hotkey Ctrl+])
    Relay-->>Viewer: session_terminated (session closed)

Monorepo Structure

lmesh/
├── packages/
│   ├── cli/       # Host CLI Daemon (node-pty, Commander.js, WebSocket client)
│   ├── server/    # WebSocket Relay Cluster (Express, ws, Redis Pub/Sub, PostgreSQL)
│   └── web/       # Next.js 16 Client (xterm.js WebGL, Tailwind CSS, Auth UI)
└── package.json   # Root workspace orchestration

Subsystem Responsibilities

packages/cli: Hooks into the local terminal via node-pty, buffers raw stdout escape sequences, monitors physical input for preemption and hotkeys, and streams frames over an outbound TLS WebSocket.
packages/server: Stateful relay cluster. Manages active WebSocket connections, enforces password protection, coordinates the single-token write mutex, persists audit logs, and handles multi-server fanout via Redis Pub/Sub.
packages/web: Next.js client interface. Renders terminal output through WebGL-accelerated xterm.js, provides a host dashboard, and handles GitHub OAuth authorization.

Self-Hosting & Local Development

For developers contributing to LMESH or self-hosting the complete relay infrastructure:

Prerequisites

Node.js: v20.x or higher
npm: v10.x or higher
PostgreSQL: PostgreSQL database (e.g. Neon serverless or local)
Redis: Redis instance (required for multi-node clustering)
GitHub OAuth App: Client ID & Client Secret (Device Flow + Web OAuth)

1. Clone & Install

git clone https://github.com/theblag/lmesh.git
cd lmesh

2. Configure & Run the Relay Server

cd packages/server
npm install
cp .env.example .env

Configure .env:

PORT=3001
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
JWT_SECRET=your_super_secret_jwt_key
DATABASE_URL=postgresql://user:password@host/neondb?sslmode=require
REDIS_URL=redis://default:password@host:port
WEB_CLIENT_URL=http://localhost:3000

Start the relay server:

npm run dev

3. Configure & Run the Web Interface

In a separate terminal:

cd packages/web
npm install
npm run dev

The web dashboard is now accessible at http://localhost:3000.

4. Build & Link the CLI Locally

In a separate terminal:

cd packages/cli
npm install
npm run build
npm link

Security Model

Outbound-Only Connectivity: The CLI never opens an inbound listening socket. Attacks targeting local open ports are completely bypassed.
Strict Single-Token Concurrency: The relay server enforces token-gated input. Unapproved keystrokes sent from unauthorized web sockets are rejected.
Physical Host Sovereignty: The host retains ultimate authority over their shell. Remote participants can never lock out the host.
Audit Trail Redaction: When Private Mode (Ctrl+S) is active, commands executed in the session are redacted before being persisted to the database.
Anti-Nesting Lock: Recursive lmesh share execution inside an active session is detected and blocked via environment guards (LMESH_SESSION).

Production Deployment

Frontend (Vercel)

Import repository on Vercel and set the Root Directory to packages/web.
Add environment variable:
- NEXT_PUBLIC_SERVER_URL: https://relay.yourdomain.com

Relay Server (Docker / VPS / Render)

Deploy packages/server as a persistent container or Node.js web service (stateless HTTP serverless is not compatible with stateful WebSockets). Ensure port 443 is SSL-terminated.

License

Distributed under the MIT License. See LICENSE for details.

Name		Name	Last commit message	Last commit date
packages		packages
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md

Navigation Menu

Repository navigation

About

Repository files navigation

Overview

Key Capabilities

Installation

Instant Execution (`npx`)

CLI Usage

1. Authenticate with GitHub

2. Share Your Shell

3. Command Flags & Options

4. In-Session Hotkeys

System Architecture

Session Lifecycle & Protocol Flow

Monorepo Structure

Subsystem Responsibilities

Self-Hosting & Local Development

Prerequisites

1. Clone & Install

2. Configure & Run the Relay Server

3. Configure & Run the Web Interface

4. Build & Link the CLI Locally

Security Model

Production Deployment

Frontend (Vercel)

Relay Server (Docker / VPS / Render)

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Overview

Key Capabilities

Installation

Instant Execution (npx)

CLI Usage

1. Authenticate with GitHub

2. Share Your Shell

3. Command Flags & Options

4. In-Session Hotkeys

System Architecture

Session Lifecycle & Protocol Flow

Monorepo Structure

Subsystem Responsibilities

Self-Hosting & Local Development

Prerequisites

1. Clone & Install

2. Configure & Run the Relay Server

3. Configure & Run the Web Interface

4. Build & Link the CLI Locally

Security Model

Production Deployment

Frontend (Vercel)

Relay Server (Docker / VPS / Render)

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Instant Execution (`npx`)