vibetunnel/web/spec.md

VibeTunnel Codebase Map

A comprehensive navigation guide for the VibeTunnel web terminal system.

Project Overview

VibeTunnel is a web-based terminal multiplexer with distributed architecture support. It provides:

• PTY-based terminal sessions via node-pty
• Real-time terminal streaming via SSE (asciinema cast files)
• Binary-optimized buffer synchronization (current viewport via WebSocket)
• Distributed HQ/remote server architecture
• Web UI with full terminal emulation

Directory Structure

web/
├── src/
│   ├── server/           # Node.js Express server
│   │   ├── middleware/   # Auth and other middleware
│   │   ├── pty/         # PTY management
│   │   ├── routes/      # API endpoints
│   │   ├── services/    # Core services
│   │   ├── server.ts    # Server loader
│   │   └── fwd.ts       # CLI forwarding tool
│   ├── client/           # Lit-based web UI
│   │   ├── assets/      # Static files (fonts, icons, html)
│   │   ├── components/  # UI components
│   │   ├── services/    # Client services
│   │   └── utils/       # Client utilities
│   ├── test/            # Test files
│   └── index.ts         # Main entry point
├── scripts/             # Build scripts
└── public/              # Built static assets (generated)

Server Architecture (src/server/)

Core Components

Entry Points

• index.ts (1-25): Main entry point, chooses between server and forward modes
• server/server.ts (1-4): Simple loader for modular server
• server/index.ts (1-49): Server initialization, cleanup intervals, graceful shutdown
• server/app.ts (198-404): Express app factory, CLI parsing, mode configuration

Server Modes

1. Normal Mode: Standalone terminal server
2. HQ Mode (--hq): Central server managing remotes
3. Remote Mode (--hq-url): Registers with HQ server

Authentication (middleware/auth.ts)

• Basic Auth: Username/password (46-55)
• Bearer Token: HQ↔Remote communication (28-44)
• Health endpoint bypass (14-16)

Session Management

PTY Manager (pty/pty-manager.ts)

• createSession() (72-167): Spawns PTY processes
• sendInput() (265-315): Handles keyboard input
• killSession() (453-537): SIGTERM→SIGKILL escalation
• resizeSession() (394-447): Terminal dimension changes
• Control pipe support for external sessions (320-349)

Session Manager (pty/session-manager.ts)

• Session persistence in ~/.vibetunnel/control/
• listSessions() (155-224): Filesystem-based discovery
• updateZombieSessions() (231-257): Dead process cleanup

Terminal Manager (services/terminal-manager.ts)

• Headless xterm.js for server-side state (40-69)
• getBufferSnapshot() (255-323): Captures terminal buffer
• encodeSnapshot() (328-555): Binary protocol encoding
• Debounced buffer notifications (627-642)

API Routes (routes/)

Sessions (sessions.ts)

• GET /api/sessions (40-120): List with HQ aggregation
• POST /api/sessions (123-199): Create local/remote
• DELETE /api/sessions/:id (270-323): Kill session
• GET /api/sessions/:id/stream (517-627): SSE streaming of asciinema cast files
• POST /api/sessions/:id/input (630-695): Send input
• POST /api/sessions/:id/resize (698-767): Resize terminal
• GET /api/sessions/:id/buffer (455-514): Binary snapshot of current terminal view

Remotes (remotes.ts) - HQ Mode Only

• GET /api/remotes (15-27): List registered servers
• POST /api/remotes/register (30-52): Remote registration
• DELETE /api/remotes/:id (55-69): Unregister remote

Binary Buffer Protocol

Note: "Buffer" refers to the current terminal display state (visible viewport) without scrollback history - just what's currently shown at the bottom of the terminal. This is used for rendering terminal previews in the session list.

Format (terminal-manager.ts:361-555)

Header (32 bytes):
- Magic: 0x5654 "VT" (2 bytes)
- Version: 0x01 (1 byte)
- Flags: reserved (1 byte)
- Dimensions: cols, rows (8 bytes)
- Cursor: X, Y, viewport (12 bytes)
- Reserved (4 bytes)

Rows: 0xFE=empty, 0xFD=content
Cells: Variable-length with type byte

SSE Streaming and Asciinema Files

File Writing (pty/asciinema-writer.ts)

• AsciinemaWriter (separate file) writes cast files to ~/.vibetunnel/control/[sessionId]/stream-out
• Used by PtyManager when creating sessions
• Records in asciinema v2 format with custom extensions:
  • Standard: [timestamp, "o", output] for terminal output
  • Standard: [timestamp, "i", input] for user input
  • Standard: [timestamp, "r", "colsxrows"] for resize events
  • Custom: ["exit", exitCode, sessionId] when process terminates

SSE Streaming (routes/sessions.ts:517-627)

• Streams asciinema cast files from disk in real-time
• StreamWatcher monitors file changes and broadcasts to clients
• Replays existing content first (timestamps zeroed)
• Watches for new content and streams incrementally
• Closes connections on exit event

Client Playback (client/utils/cast-converter.ts)

• Parses asciinema v2 format
• Handles custom exit event to dispatch session-exit
• Supports batch loading and real-time streaming

WebSocket (services/buffer-aggregator.ts)

• Client connections (31-68)
• Message handling (69-127)
• Local session buffers (131-195)
• Remote session proxy (200-232)
• Binary message format (136-164)

HQ Mode Components

Remote Registry (services/remote-registry.ts)

• Health checks every 15s (118-146)
• Session ownership tracking (82-96)
• Bearer token authentication

HQ Client (services/hq-client.ts)

• Registration with HQ (29-58)
• Unregister on shutdown (60-72)

Client Architecture (src/client/)

Core Components

Entry Points

• app-entry.ts - Main application entry point
• test-terminals-entry.ts - Test terminals entry point
• styles.css - Global styles

Main Components

• app.ts - Lit-based SPA (15-331)
  • URL-based routing ?session=<id>
  • Global keyboard handlers
  • Error/success message handling (74-90)

Terminal Components

• terminal.ts - Custom DOM terminal renderer (634-701)
  • Virtual scrolling (537-555)
  • Touch/momentum support
  • URL highlighting integration
  • Copy/paste handling
• session-view.ts - Full-screen terminal view (12-1331)
  • SSE streaming (275-333)
  • Mobile input overlays
  • Resize synchronization
• vibe-terminal-buffer.ts - Terminal buffer display component

UI Components

• app-header.ts - Application header
• session-list.ts - Active sessions list view
• session-card.ts - Individual session card
• session-create-form.ts - New session creation form
• file-browser.ts - File browser component
• vibe-logo.ts - Application logo
• terminal-icon.ts - Terminal icon
• copy-icon.ts - Copy icon

Services

Buffer Subscription (services/buffer-subscription-service.ts)

• WebSocket client (30-87)
• Binary protocol decoder (163-208)
• Auto-reconnection with backoff

Utils

Cast Converter (utils/cast-converter.ts)

• Asciinema v2 parser (31-82)
• SSE stream handler (294-427)
• Batch loading (221-283)

Terminal Renderer (utils/terminal-renderer.ts)

• Binary buffer decoder (279-424)
• HTML generation
• Style mapping

Additional Utilities

• url-highlighter.ts - URL detection and highlighting
• xterm-colors.ts - Terminal color definitions
• terminal-preferences.ts - Terminal preference management

Forward Tool (src/server/fwd.ts)

Purpose

CLI tool that spawns PTY sessions integrated with VibeTunnel infrastructure.

Key Features

• Interactive terminal forwarding (295-312)
• Monitor-only mode (--monitor-only)
• Control pipe handling (140-287)
• Session persistence (439-446)

Usage

npx tsx src/fwd.ts <command> [args...]
npx tsx src/fwd.ts --monitor-only <command>

Integration Points

• Uses same PtyManager as server (63)
• Creates sessions in control directory
• Supports resize/kill via control pipe

Key Files Quick Reference

Server Core

• src/index.ts: Main entry point
• src/server/server.ts: Server loader
• src/server/app.ts: App configuration, CLI parsing
• src/server/middleware/auth.ts: Authentication logic
• src/server/routes/sessions.ts: Session API endpoints
• src/server/pty/pty-manager.ts: PTY process management
• src/server/pty/asciinema-writer.ts: Cast file writer
• src/server/services/terminal-manager.ts: Terminal state & binary protocol
• src/server/services/buffer-aggregator.ts: WebSocket buffer distribution
• src/server/services/stream-watcher.ts: SSE file streaming
• src/server/fwd.ts: CLI forwarding tool

Client Core

• src/client/app-entry.ts: Application entry point
• src/client/app.ts: Main SPA component
• src/client/components/terminal.ts: Terminal renderer
• src/client/components/session-view.ts: Session viewer
• src/client/components/session-list.ts: Session list view
• src/client/services/buffer-subscription-service.ts: WebSocket client
• src/client/utils/cast-converter.ts: Asciinema parser
• src/client/assets/: Static files (fonts, icons, HTML)

Configuration

• Environment: PORT, VIBETUNNEL_USERNAME, VIBETUNNEL_PASSWORD
• CLI: --port, --username, --password, --hq, --hq-url, --name

Protocols

• REST API: Session CRUD, terminal I/O
• SSE: Real-time streaming of asciinema cast files from disk
• WebSocket: Binary buffer updates (current terminal viewport)
• Control pipes: External session control

Development Notes

Build System

• npm run dev: Auto-rebuilds TypeScript
• ESBuild: Fast bundling
• Vitest: Testing framework
• Assets: Copied from src/client/assets/ to public/ during build

Testing

• Unit tests: npm test
• E2E tests: npm run test:e2e
• Integration: npm run test:integration

Key Dependencies

• node-pty: Cross-platform PTY
• @xterm/headless: Terminal emulation
• Lit: Web components
• Express: HTTP server
• TailwindCSS: Styling