Skip to main content

​
Architecture Overview

​
System Design

VibeTunnel consists of three main components working together: 
┌─────────────────────────────────────────────────────┐
│              macOS Menu Bar Application              │
│                   (Swift/SwiftUI)                    │
│  ┌──────────────────────────────────────────────┐  │
│  │ ServerManager: Lifecycle & process control    │  │
│  │ SessionMonitor: Active session tracking       │  │
│  │ TTYForwardManager: Terminal forwarding        │  │
│  └──────────────────────────────────────────────┘  │
└────────────────────┬────────────────────────────────┘
                     │ Spawns & Manages
┌────────────────────▼────────────────────────────────┐
│             Node.js/Bun Server Process              │
│                  (TypeScript)                       │
│  ┌──────────────────────────────────────────────┐  │
│  │ HTTP Server: REST API endpoints               │  │
│  │ WebSocket Server: Real-time terminal I/O      │  │
│  │ PTY Manager: Native terminal processes        │  │
│  │ Session Manager: Lifecycle & state            │  │
│  └──────────────────────────────────────────────┘  │
└────────────────────┬────────────────────────────────┘
                     │ HTTP/WebSocket
┌────────────────────▼────────────────────────────────┐
│                  Client Applications                 │
├──────────────────────────────────────────────────────┤
│  Web Browser         │        iOS App               │
│  (Lit/TypeScript)    │    (Swift/SwiftUI)          │
└──────────────────────────────────────────────────────┘

​
Component Responsibilities

​
macOS Application

ComponentFilePurpose
ServerManagermac/VibeTunnel/ServerManager.swiftServer lifecycle, port management
SessionMonitormac/VibeTunnel/SessionMonitor.swiftTrack active sessions
TTYForwardManagermac/VibeTunnel/TTYForwardManager.swiftCLI integration
MenuBarUImac/VibeTunnel/MenuBarView.swiftUser interface

​
Server Process

ComponentFilePurpose
HTTP Serverweb/src/server/server.tsREST API, WebSocket upgrade
PTY Managerweb/src/server/pty/pty-manager.tsTerminal process spawning
Session Managerweb/src/server/pty/session-manager.tsSession state & cleanup
WsV3Hubweb/src/server/services/ws-v3-hub.ts/ws v3 framing + multiplex
CastOutputHubweb/src/server/services/cast-output-hub.tsCast tail → STDOUT frames

​
Web Frontend

ComponentFilePurpose
App Shellweb/src/client/app.tsMain application container
Terminal Viewweb/src/client/components/terminal.tsghostty-web integration
Session Listweb/src/client/components/session-list.tsActive sessions UI
WebSocket Clientweb/src/client/services/terminal-socket-client.ts/ws v3 transport

​
Data Flow

​
Session Creation

User → vt command → TTYForwardManager → HTTP POST /api/sessions
→ Server creates PTY → Returns session ID → Opens browser
→ WebSocket connection established → Terminal ready

​
Terminal I/O

User types → v3 `INPUT_*` frame → Server PTY write
PTY output → Cast tail → v3 `STDOUT` frames
Server-side Ghostty → v1 VT snapshots → v3 `SNAPSHOT_VT` frames
Client render: ghostty-web (interactive) + VT snapshots (previews)

​
Session Cleanup

Terminal exit → PTY close → Session manager cleanup
→ WebSocket close → Client notification → UI update

​
Communication Protocols

​
HTTP REST API

  • Session CRUD operations
  • Authentication endpoints
  • Health checks
  • See API Reference

​
WebSocket Protocol

  • Terminal transport: /ws WebSocket v3 framing (multiplexed sessions)
  • Details: docs/websocket.md

​
Inter-Process Communication

  • Mac app spawns Bun server as child process
  • Environment variables for configuration
  • File-based PID tracking
  • Signal handling for graceful shutdown

​
Security Architecture

​
Authentication Flow

Client → Password (optional) → Server validates
→ JWT token generated → Token in Authorization header
→ Server validates on each request

​
Network Security

  • Localhost-only by default
  • Optional LAN exposure with authentication
  • Tailscale/ngrok integration for remote access
  • WSS/HTTPS in production

​
Process Isolation

  • Each session runs in separate PTY process
  • User permissions inherited from server
  • No privilege escalation
  • Resource limits per session

​
Performance Optimizations

​
Buffer Aggregation

  • Batch terminal output every 16ms
  • Reduce WebSocket message frequency
  • Binary protocol reduces payload size

​
Connection Management

  • WebSocket connection pooling
  • Automatic reconnection with backoff
  • Ping/pong for keep-alive

​
Resource Management

  • Lazy loading of terminal sessions
  • Automatic cleanup of idle sessions
  • Memory-mapped session recordings

​
Platform Integration

​
macOS Features

  • Menu bar application
  • Sparkle auto-updates
  • Code signing & notarization
  • Launch at login

​
iOS Features

  • Native Swift UI
  • Background session support
  • Push notifications
  • Handoff support

​
Web Standards

  • Progressive Web App capable
  • Service Worker for offline
  • WebAssembly for performance
  • Responsive design

​
Build & Deployment

​
Build Pipeline

1. TypeScript compilation → JavaScript bundle
2. Bun standalone executable generation
3. Swift compilation → macOS app
4. Embed server in app bundle
5. Code sign & notarize
6. DMG creation with Sparkle

​
Configuration

  • Runtime: Environment variables
  • Build-time: xcconfig files
  • User preferences: macOS defaults system
  • Server config: JSON files

​
Monitoring & Debugging

​
Logging

  • Unified logging to macOS Console
  • Structured JSON logs from server
  • Session-specific log filtering
  • See ./scripts/vtlog.sh

​
Metrics

  • Session count & duration
  • Message throughput
  • Error rates
  • Resource usage

​
See Also