Documentation

Installation

webmux requires Node.js 20+ and runs on Linux and macOS. The Rust terminal sidecar (webmux-term) is included as a pre-built binary.

From npm

npm install -g webmux

From source

git clone https://github.com/alphatechlab/webmux.git
cd webmux
npm install
npm run build

# Build the Rust sidecar (requires Rust toolchain)
cd webmux-term
cargo build --release
cd ..

npm start

System requirements

• Node.js 20 or later
• Linux or macOS (WSL supported on Windows)
• A modern browser (Chrome, Firefox, Safari)

Usage

Starting the server

Run webmux start to launch the server on port 3030. Open your browser to http://localhost:3030 to access the terminal UI.

# Start with default settings
webmux start

# Start on a custom port
PORT=8080 webmux start

# Start with debug logging
WEBMUX_DEBUG=1 webmux start

Sessions

Sessions are named workspaces that contain screens, panes, and state. Create a new session from the session picker, or navigate to /project/<name> directly.

Sessions persist across server restarts. Terminal daemon processes run independently and survive reboots. When you reconnect, your scrollback, cursor position, and running processes are all intact.

Split screens

Split the current pane horizontally or vertically to create multi-pane layouts. Each screen holds an independent split tree. Navigate between screens using keyboard shortcuts or the screen bar.

Keyboard shortcuts

webmux uses a prefix-key system similar to tmux. The default prefix is configurable.

• Prefix + % — Split horizontally
• Prefix + " — Split vertically
• Prefix + Arrow — Navigate between panes
• Prefix + c — Create new screen
• Prefix + n/p — Next / previous screen

Pro Setup

Pro unlocks remote access via an encrypted tunnel. After upgrading, activate Pro from the Settings panel in the webmux UI.

Activation

• Open Settings in the webmux UI
• Enter your Pro license key
• Choose your tunnel username (e.g., farid)
• The tunnel connects automatically on server start

Accessing remotely

Once activated, your terminal is available at https://<user>.webmux.app from any browser. The connection is end-to-end encrypted.

Remote Access

The Pro tunnel creates a secure connection between your browser and your machine. Here is how data flows:

• Browser — connects to <user>.webmux.app
• CDN — serves static assets, terminates TLS
• Relay — routes encrypted WebSocket frames (zero-knowledge)
• Tunnel — Rust binary on your machine, maintains persistent connection to relay
• Node — your local webmux server, handles terminal sessions

The relay never decrypts your data. It only sees opaque encrypted bytes and routes them by username.

Configuration

User-specific settings live in config.cjs in the webmux directory. Copy config.example.cjs to get started.

module.exports = {
  terminal: {
    fontSize: 20,
    fontFamily: 'Menlo, monospace',
    scrollback: 10000,
    cursorBlink: false,
    theme: {
      background: '#15191F',
      foreground: '#e0e0e0',
      cursor: '#e0e0e0',
    },
  },
  debug: false,
};

Options

• terminal.fontSize — Font size in pixels (default: 20)
• terminal.fontFamily — Font stack (default: Menlo, monospace)
• terminal.scrollback — Scrollback buffer lines (default: 10000)
• terminal.theme — Color theme object (background, foreground, cursor, selection)
• debug — Enable verbose logging (default: false)

API

webmux includes a Model Context Protocol (MCP) server that allows AI agents to interact with terminal sessions programmatically.

Available tools include creating and destroying sessions, reading terminal content, sending input, waiting for output, splitting panes, and interacting with embedded browsers via CDP.

For full API documentation, see the MCP Server section in the GitHub README.