Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vibetunnel.sh/llms.txt

Use this file to discover all available pages before exploring further.

​
VibeTunnel Architecture Deep Dive

​
🏗️ High-Level Architecture

VibeTunnel is a sophisticated terminal multiplexer ecosystem with native macOS/iOS apps and a powerful web interface. Here’s the complete architectural breakdown: 
┌─────────────────────────────────────────────────────────────────────────┐
│                           USER INTERFACES                                │
├─────────────────┬──────────────────────┬─────────────────────────────────┤
│   macOS Menu    │   iOS App            │    Web Browser                  │
│   Bar App        │   (SwiftUI)          │    (TypeScript/LitElement)     │
│                 │                       │                                 │
│  ┌───────────┐  │  ┌──────────────┐   │  ┌──────────────────────────┐   │
│  │ServerMgr │  │  │SessionService│   │  │  xterm.js Terminal       │   │
│  │TTYFwd    │  │  │BufferWS      │   │  │  Session Management UI   │   │
│  │Monitor   │  │  │APIClient     │   │  │  File Browser           │   │
│  └─────┬─────┘  │  └──────┬───────┘   │  └──────────┬───────────────┘   │
└────────┼────────┴─────────┼───────────┴─────────────┼─────────────────┘
         │                  │                          │
         │ Spawns &         │ REST/WS                 │ HTTP/WS
         │ Manages          │                          │
         ▼                  └──────────┬───────────────┘
┌─────────────────────────────────────▼──────────────────────────────────┐
│                    NODE.JS/BUN SERVER (Port 4020)                       │
│                                                                         │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │                     EXPRESS APP + MIDDLEWARE                      │  │
│  │  Auth (JWT/SSH) │ CORS │ Compression │ Static Files │ Logging   │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                                                                         │
│  ┌─────────────────┐  ┌──────────────────┐  ┌────────────────────┐   │
│  │  PTY Manager    │  │ Terminal Manager │  │ Buffer Aggregator  │   │
│  │  - Spawn PTY    │  │ - Session Logic   │  │ - Binary Protocol  │   │
│  │  - Process I/O  │  │ - Lifecycle Mgmt  │  │ - Snapshot/Delta   │   │
│  └─────────────────┘  └──────────────────┘  └────────────────────┘   │
│                                                                         │
│  ┌─────────────────┐  ┌──────────────────┐  ┌────────────────────┐   │
│  │ Session Monitor │  │  Stream Watcher  │  │ Activity Monitor   │   │
│  │ - Cleanup       │  │  - Log Tailing   │  │ - Idle Detection   │   │
│  │ - Zombie detect │  │  - File Watch    │  │ - Resource Track   │   │
│  └─────────────────┘  └──────────────────┘  └────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                         System Resources
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                          SYSTEM LAYER                                   │
│  ┌──────────────┐  ┌─────────────────┐  ┌─────────────────────────┐   │
│  │ PTY Processes│  │ File System     │  │ Unix Sockets           │   │
│  │ (bash/zsh)   │  │ (~/.vibetunnel) │  │ (IPC Communication)    │   │
│  └──────────────┘  └─────────────────┘  └─────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘

​
🎯 Core Components Breakdown

​
1. macOS Application (Swift/SwiftUI)

The native macOS app serves as the system orchestrator: 
mac/VibeTunnel/
├── Core/
│   ├── Services/
│   │   ├── ServerManager.swift      # Central orchestrator
│   │   ├── BunServer.swift          # Bun runtime integration
│   │   ├── SessionMonitor.swift     # Session tracking
│   │   ├── TTYForwardManager.swift  # Terminal forwarding
│   │   ├── UnixSocketConnection.swift # IPC communication
│   │   └── TailscaleServeService.swift # Remote access
│   ├── Models/
│   │   ├── TunnelSession.swift      # Session data model
│   │   └── AppConstants.swift       # Configuration
│   └── Protocols/
│       └── VibeTunnelServer.swift   # Server interface
└── Presentation/
    ├── Views/                       # SwiftUI views
    └── Components/                  # UI components
Key Responsibilities:
  • Process Management: Spawns and monitors the Bun/Node.js server
  • Log Aggregation: Captures all logs from server and frontend
  • System Integration: Menu bar UI, notifications, keychain
  • Remote Access: Tailscale/Ngrok tunnel management

​
2. Web Server (Node.js/Bun)

The TypeScript server handles all terminal operations: 
web/src/server/
├── server.ts                 # Main server entry (912 lines)
├── pty/
│   ├── pty-manager.ts       # Native PTY management
│   ├── session-manager.ts   # Session lifecycle
│   └── types.ts            # TypeScript definitions
├── services/
│   ├── terminal-manager.ts  # High-level terminal ops
│   ├── buffer-aggregator.ts # Binary buffer protocol
│   ├── auth-service.ts     # SSH key authentication
│   ├── activity-monitor.ts # Resource tracking
│   └── hq-client.ts        # Multi-server mode
├── routes/
│   ├── sessions.ts         # Session REST API
│   ├── websocket-input.ts  # WebSocket handlers
│   ├── auth.ts            # Authentication endpoints
│   └── control.ts         # Unix socket control
└── middleware/
    └── auth.ts            # JWT validation
Key Features:
  • Session Management: Full PTY lifecycle (create/resize/kill)
  • Binary Buffer Protocol: Optimized terminal streaming
  • Authentication: JWT + SSH keys + PAM
  • Distributed Mode: HQ server for multi-machine setups

​
3. iOS Application (Swift/SwiftUI)

Mobile terminal client with full feature parity: 
ios/VibeTunnel/
├── Services/
│   ├── BufferWebSocketClient.swift  # Binary protocol client
│   ├── SessionService.swift         # Session management
│   ├── ConnectionManager.swift      # Server connections
│   └── BonjourDiscoveryService.swift # Local discovery
├── Views/
│   ├── Terminal/
│   │   ├── TerminalView.swift      # Main terminal UI
│   │   ├── XtermWebView.swift      # xterm.js wrapper
│   │   └── TerminalHostingView.swift # UIKit bridge
│   └── Sessions/
│       └── SessionListView.swift    # Session browser
└── Models/
    ├── TerminalSnapshot.swift       # Buffer state
    └── Session.swift                # Session model

​
4. Web Frontend (TypeScript/LitElement)

Browser-based terminal interface: 
web/src/client/
├── app.ts                   # Main LitElement app
├── components/
│   ├── terminal.ts         # xterm.js wrapper
│   ├── session-list.ts     # Session management
│   └── file-browser.ts     # File navigation
└── services/
    ├── websocket.ts        # WebSocket client
    └── api-client.ts       # REST client

​
📡 Communication Protocols

​
1. Binary Buffer Protocol (0xBF Magic Byte)

Optimized terminal streaming protocol: 
// Message Format
[Magic Byte: 0xBF] [Type: 1 byte] [Length: 4 bytes] [Payload: N bytes]

// Types:
0x01: Full buffer snapshot
0x02: Delta update
0x03: Cursor position
0x04: Terminal resize
Flow: 
Terminal Output → BufferAggregator → Binary Encode → WebSocket → Client Decode → xterm.js

​
2. REST API Endpoints

POST   /api/sessions              # Create session
GET    /api/sessions              # List sessions
DELETE /api/sessions/:id          # Kill session
POST   /api/sessions/:id/resize   # Resize terminal
WS     /api/sessions/:id/ws       # Terminal I/O stream
GET    /api/auth/challenge        # SSH key challenge
POST   /api/auth/ssh-key          # SSH key verify

​
3. Unix Socket IPC

Mac app ↔ Server communication: 
// Control Protocol
{
  "type": "session.create",
  "payload": {
    "cols": 80,
    "rows": 24,
    "cwd": "/Users/chris"
  }
}

​
🔄 Key Data Flows

​
Session Creation Flow

User Request
    │
    ▼
[macOS App] ServerManager.createSession()
    │
    ├─→ [IPC] Unix Socket Message
    │
    ▼
[Server] POST /api/sessions
    │
    ├─→ TerminalManager.createTerminal()
    ├─→ PtyManager.spawn() → node-pty
    ├─→ Create ~/.vibetunnel/control/[sessionId]/
    ├─→ Start BufferAggregator
    │
    ▼
[Response] { sessionId, wsUrl }
    │
    ▼
[Client] Connect WebSocket
    │
    ▼
[Bidirectional Terminal I/O]

​
Log Aggregation Pipeline

┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Frontend   │────▶│   Server     │────▶│   Mac App    │────▶│  macOS Log   │
│  console.log │HTTP │ [CLIENT:*]   │Pipe │ ServerOutput │     │  Unified     │
└──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘
                         
[component] msg → POST /api/logs → [CLIENT:component] → Logger category → vtlog

​
🔐 Security Architecture

​
Authentication Layers

┌─────────────────────────────────────────────────────┐
│                  Client Request                      │
└────────────────────────┬────────────────────────────┘
                         ▼
┌─────────────────────────────────────────────────────┐
│              Authentication Middleware               │
├─────────────────────────────────────────────────────┤
│  1. Local Bypass (localhost + token)                │
│  2. JWT Token (from previous auth)                  │
│  3. SSH Key Challenge/Response                      │
│  4. Password (PAM or env var)                       │
│  5. Bearer Token (HQ mode)                          │
└─────────────────────────────────────────────────────┘
                         │
                    Authenticated
                         ▼
┌─────────────────────────────────────────────────────┐
│                  Protected Routes                    │
└─────────────────────────────────────────────────────┘

​
🚀 Advanced Features

​
1. Distributed Mode (HQ)

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Machine A   │────▶│  HQ Server   │◀────│  Machine B   │
│  (Remote)    │     │  (Central)   │     │  (Remote)    │
└──────────────┘     └──────────────┘     └──────────────┘
     
Registration → Session Discovery → Proxied Access

​
2. Remote Access (Tailscale/Ngrok)

Internet → Tailscale Funnel/Ngrok → localhost:4020 → VibeTunnel
            ├─ HTTPS termination
            ├─ Authentication
            └─ Traffic routing

​
3. Activity Monitoring

// Idle detection and resource management
ActivityMonitor → Session idle > 5min → Mark inactive
                → System resources → Auto-cleanup
                → WebSocket ping/pong → Connection health

​
📁 File System Structure

~/.vibetunnel/
├── control/                      # Session control files
│   └── [sessionId]/
│       ├── session.json         # Metadata
│       ├── stdout              # Output log
│       ├── stdin               # Input log
│       ├── activity.json       # Activity status
│       └── ipc.sock           # Unix socket
├── logs/                        # Application logs
├── keys/                        # VAPID keys
└── config/                      # Server config

​
🎨 Technology Stack

  • macOS/iOS: Swift 6, SwiftUI, Combine, os.log
  • Server: Node.js/Bun, TypeScript, Express, node-pty
  • Frontend: TypeScript, LitElement, xterm.js, Web Components
  • Protocols: WebSocket, Unix Sockets, REST, Binary Buffer
  • Security: JWT, Ed25519 SSH keys, PAM, Keychain
  • Build: Xcode, Swift Package Manager, pnpm, esbuild

​
🔧 Key Implementation Details

​
Server Lifecycle

  1. Startup: Mac app spawns Bun process with embedded server
  2. Health Check: Polls /health endpoint until ready
  3. Operation: Handles sessions, forwards logs to Mac app
  4. Shutdown: Graceful termination on SIGTERM

​
Session Persistence

  • Sessions survive server restarts via control directory
  • Reconnection supported through session ID
  • Automatic cleanup of orphaned sessions

​
Performance Optimizations

  • Binary Protocol: 10x smaller than JSON for terminal data
  • Buffer Aggregation: Batches updates to reduce WebSocket messages
  • Delta Updates: Only sends changes, not full buffer
  • Lazy Loading: Sessions load on-demand

​
Development vs Production

  • Development: Hot reload, verbose logging, dev server mode
  • Production: Embedded server, optimized builds, minimal logging
  • No Backwards Compatibility: Everything ships together as one unit