WooTTY

Flawless browser terminal for real operators.

WooTTY is a clean-slate browser terminal designed for one non-negotiable outcome: a terminal experience that stays reliable under real pressure (resize storms, reconnects, long output, and unstable networks).

Why WooTTY

• Terminal-first UI: maximum viewport, compact status bar, floating controls.
• Reconnect-safe sessions: resume by sessionId, replay buffered output.
• Tab-safe defaults: each browser tab starts its own live session unless the operator explicitly resumes one.
• Explicit multi-session actions: Resume for controllable sessions, Watch for sessions already controlled elsewhere (read-only).
• Resize fidelity: client and PTY stay in sync during rapid window changes.
• Operational defaults: high scrollback, keyboard-first controls, low-friction deployment.
• Modern stack: Go 1.26+, Node 24+, React 19 + compiler, xterm.js.

Table of Contents

• Quick Start
• Run with Docker
• Run from Source
• Operator Controls
• Configuration
• Architecture
• Testing and Quality
• Contributing
• Security

Quick Start

Run with Docker

Stable image from GitHub Container Registry:

docker run --rm -it -p 8080:8080 ghcr.io/icoretech/wootty:latest

Then open http://127.0.0.1:8080.

Pin by version:

docker run --rm -it -p 8080:8080 ghcr.io/icoretech/wootty:v0.2.0

Run a custom command:

docker run --rm -it -p 8080:8080 \
  -e WOOTTY_COMMAND=/bin/bash \
  -e WOOTTY_COMMAND_ARGS="-l" \
  ghcr.io/icoretech/wootty:latest

Run from Source

pnpm install
pnpm dev

• Web: http://localhost:5173
• Server: http://127.0.0.1:8080

Production-like local run:

pnpm build
cd apps/server
go run ./cmd/woottyd run --port 8080 bash

Run with Docker

Build locally:

docker build -t wootty:dev .
docker run --rm -it -p 8080:8080 wootty:dev

The container serves:

• backend API/websocket on /api/*
• web UI from apps/web/dist

Operator Controls

Keyboard shortcuts:

• Ctrl/Cmd+Shift+R: reconnect
• Ctrl/Cmd+Shift+K: clear viewport
• Ctrl/Cmd+Shift+=: increase font size
• Ctrl/Cmd+Shift+-: decrease font size
• Ctrl/Cmd+Shift+0: reset font size
• Ctrl/Cmd+Shift+F: fullscreen
• Ctrl/Cmd+Shift+B: toggle controls

Status bar metrics:

• connection status and latency
• session id
• reconnect count
• buffered/dropped input size (humanized units)
• output size (humanized units)

Session controls:

• click the Session badge in the status bar to open the session menu.
• New session: start a fresh session in the current tab.
• Resume last: reattach the last session id seen in this browser.
• session menu separates Live sessions (running on server) from Recent session ids (browser memory only).
• sessions already controlled in another tab/operator are shown as Watch (read-only attach).
• resumable sessions are shown as Resume (full control attach).
• recent ids that are not running are shown as unavailable.
• tabs do not implicitly steal active sessions from each other.
• terminal font starts at minimum (11px) by default and can be changed from controls/shortcuts.

Configuration

Variable	Default	Description
WOOTTY_HOST	0.0.0.0	Bind address
WOOTTY_PORT	8080	HTTP/WebSocket port
WOOTTY_RECONNECT_GRACE_MS	0	Legacy detached-session cleanup timeout in ms (used only when WOOTTY_DETACHED_TTL_MS=0)
WOOTTY_DETACHED_TTL_MS	86400000	Hard TTL for running detached sessions (24h). 0 disables this TTL
WOOTTY_HISTORY_BYTES	5242880	Buffered output bytes for replay
WOOTTY_COMMAND	$SHELL or bash	Executed command
WOOTTY_COMMAND_ARGS	empty	Space-separated command args
WOOTTY_CWD	current directory	Process working directory
WOOTTY_STATIC_DIR	auto-detected	Directory with built web assets
WOOTTY_FAKE_PTY	0	Set to 1 for deterministic fake PTY mode

CLI equivalents are available for key timing controls: --reconnect-grace-ms and --detached-ttl-ms.

Session Retention Model

• Session metadata and PTY state are in-memory only.
• If a terminal process exits, the session is removed immediately.
• If a terminal process is still running but no client is attached, the session is retained for WOOTTY_DETACHED_TTL_MS.
• If WOOTTY_DETACHED_TTL_MS=0, cleanup falls back to WOOTTY_RECONNECT_GRACE_MS behavior.
• Server restart clears all sessions because there is no persistent session store.

Recommended for long-running jobs with occasional reconnects:

WOOTTY_RECONNECT_GRACE_MS=0
WOOTTY_DETACHED_TTL_MS=259200000  # 72h

Example in Compose:

environment:
  WOOTTY_RECONNECT_GRACE_MS: "0"
  WOOTTY_DETACHED_TTL_MS: "259200000"

Architecture

flowchart LR
  B["Browser UI (React + xterm)"] -- "WebSocket (/api/terminal)" --> S["WooTTY Server (Go)"]
  B -- "HTTP (/api/sessions)" --> S
  S -- "PTY attach/input/resize" --> P["Shell Process (creack/pty)"]
  P -- "output stream" --> S
  S -- "output + status events" --> B
  S -- "session history buffer" --> H["In-memory replay buffer"]

Loading

Testing and Quality

Standard quality gates:

pnpm lint
pnpm test
pnpm build
pnpm test:e2e

Cross-browser browser matrix (Chromium + Firefox + WebKit):

pnpm test:e2e:cross

Notes:

• pnpm lint applies Biome fixes and then runs typecheck.
• CI enforces zero formatting drift (git diff --exit-code).

Contributing

Read CONTRIBUTING.md before opening a PR.

Security

Report vulnerabilities through SECURITY.md.