WebTMUX

WebTMUX is a small, password-protected web terminal for persistent tmux sessions. It uses Express for the HTTP API, Socket.IO for live terminal traffic, node-pty for the pseudoterminal bridge, and xterm.js in the browser.

Features

• Browser-based terminal connected to real tmux sessions.
• Password login required before any terminal socket can connect.
• Session listing, creation, reconnection, and logout.
• Persistent shell state through tmux new-session -A.
• Docker image with Node.js and tmux included.
• Basic hardening with Helmet, session cookies, and login rate limiting.

Requirements

• Node.js 20 or newer.
• tmux available in PATH when running directly on the host.
• A strong WEBTMUX_PASSWORD.

This application exposes shell access through a browser. Do not run it on a public network without HTTPS, a strong password, and firewall rules that match your threat model.

Local Development

npm install
WEBTMUX_PASSWORD=change-me npm start

Open http://127.0.0.1:3000 and sign in with the password from WEBTMUX_PASSWORD.

Optional environment variables:

Variable	Default	Purpose
PORT	3000	HTTP port.
HOST	0.0.0.0	HTTP bind address.
WEBTMUX_PASSWORD	required	Login password.
WEBTMUX_SESSION_SECRET	generated at boot	Cookie signing secret. Set this in production.
WEBTMUX_DEFAULT_SESSION	webtmux	Session used when none exists yet.
WEBTMUX_SECURE_COOKIES	false	Set to true when serving over HTTPS.

Docker

docker compose up --build

Edit docker-compose.yml first and replace both WEBTMUX_PASSWORD and WEBTMUX_SESSION_SECRET.

API

• POST /api/login with { "password": "..." }.
• POST /api/logout.
• GET /api/me.
• GET /api/sessions.
• POST /api/sessions with { "name": "dev" }.
• DELETE /api/sessions/:name.

Socket.IO events:

• Client sends terminal:start with { sessionName, cols, rows }.
• Client sends terminal:data for keystrokes.
• Client sends terminal:resize with { cols, rows }.
• Server emits terminal:data, terminal:ready, terminal:error, and terminal:exit.

Release Plan

The current implementation is an MVP suitable for a v0.1.0 tag. Good next steps are HTTPS/reverse-proxy documentation, clipboard controls, attach-only mode, and automated tests for auth/session behavior.