VibeTunnel

VibeTunnel is a macOS application that bridges terminal applications to the web, enabling remote control of terminal tools from anywhere. It creates secure tunnels between local terminal sessions and web browsers, making it possible to access and control command-line applications like Claude Code remotely.

Architecture Overview

VibeTunnel employs a multi-layered architecture designed for flexibility, security, and ease of use:

┌─────────────────────────────────────────────────────────┐
│                   Web Browser (Client)                   │
│  ┌─────────────────────────────────────────────────┐   │
│  │  TypeScript/JavaScript Frontend                  │   │
│  │  - Asciinema Player for Terminal Rendering      │   │
│  │  - WebSocket for Real-time Updates              │   │
│  │  - Tailwind CSS for UI                          │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                            ↕ HTTPS/WebSocket
┌─────────────────────────────────────────────────────────┐
│                    HTTP Server Layer                     │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Dual Implementation:                            │   │
│  │  1. Hummingbird Server (Swift)                  │   │
│  │  2. Rust Server (tty-fwd binary)                │   │
│  │  - REST APIs for session management              │   │
│  │  - WebSocket streaming for terminal I/O         │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                            ↕
┌─────────────────────────────────────────────────────────┐
│                 macOS Application (Swift)                │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Core Components:                                │   │
│  │  - ServerManager: Orchestrates server lifecycle  │   │
│  │  - SessionMonitor: Tracks active sessions       │   │
│  │  - TTYForwardManager: Handles TTY forwarding    │   │
│  │  - TerminalManager: Terminal operations         │   │
│  │  - NgrokService: Optional tunnel exposure       │   │
│  └─────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────┐   │
│  │  UI Layer (SwiftUI):                            │   │
│  │  - MenuBarView: System menu bar integration     │   │
│  │  - SettingsView: Configuration interface        │   │
│  │  - ServerConsoleView: Diagnostics & logs        │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Core Components

1. Native macOS Application

The main application is built with Swift and SwiftUI, providing:

• Menu Bar Integration: Lives in the system menu bar with optional dock mode
• Server Lifecycle Management: Controls starting, stopping, and switching between server implementations
• System Integration: Launch at login, single instance enforcement, application mover
• Auto-Updates: Sparkle framework integration for seamless updates

Key files:

• VibeTunnel/VibeTunnelApp.swift: Main application entry point
• VibeTunnel/Services/ServerManager.swift: Orchestrates server operations
• VibeTunnel/Models/TunnelSession.swift: Core session model

2. HTTP Server Layer

VibeTunnel offers two server implementations that can be switched at runtime:

Hummingbird Server (Swift)

• Built-in Swift implementation using the Hummingbird framework
• Native integration with the macOS app
• RESTful APIs for session management
• File: VibeTunnel/Services/HummingbirdServer.swift

Rust Server (tty-fwd)

• External binary written in Rust for high-performance TTY forwarding
• Spawns and manages terminal processes
• Records sessions in asciinema format
• WebSocket streaming for real-time terminal I/O
• Source: rust/tty-fwd/ directory

Both servers expose similar APIs:

• POST /sessions: Create new terminal session
• GET /sessions: List active sessions
• GET /sessions/:id: Get session details
• POST /sessions/:id/send: Send input to terminal
• GET /sessions/:id/output: Stream terminal output
• DELETE /sessions/:id: Terminate session

3. Web Frontend

A modern web interface for terminal interaction:

• Terminal Rendering: Uses asciinema player for accurate terminal display
• Real-time Updates: WebSocket connections for live terminal output
• Responsive Design: Tailwind CSS for mobile-friendly interface
• Session Management: Create, list, and control multiple terminal sessions

Key files:

• web/: Frontend source code
• VibeTunnel/Resources/WebRoot/: Bundled static assets

Session Management Flow

1. Session Creation:

   Client → POST /sessions → Server spawns terminal process → Returns session ID
   

2. Command Execution:

   Client → POST /sessions/:id/send → Server writes to PTY → Process executes
   

3. Output Streaming:

   Process → PTY output → Server captures → WebSocket/HTTP stream → Client renders
   

4. Session Termination:

   Client → DELETE /sessions/:id → Server kills process → Cleanup resources
   

Key Features

Security & Tunneling

• Ngrok Integration: Optional secure tunnel exposure for remote access
• Keychain Storage: Secure storage of authentication tokens
• Code Signing: Full support for macOS code signing and notarization

Terminal Capabilities

• Full TTY Support: Proper handling of terminal control sequences
• Process Management: Spawn, monitor, and control terminal processes
• Session Recording: Asciinema format recording for playback
• Multiple Sessions: Concurrent terminal session support

Developer Experience

• Hot Reload: Development server with live updates
• Comprehensive Logging: Detailed logs for debugging
• Error Handling: Robust error handling throughout the stack
• Swift 6 Concurrency: Modern async/await patterns

Technology Stack

macOS Application

• Language: Swift 6.0
• UI Framework: SwiftUI
• Minimum OS: macOS 14.0 (Sonoma)
• Architecture: Universal Binary (Intel + Apple Silicon)

Dependencies

• Hummingbird: HTTP server framework
• Sparkle: Auto-update framework
• Swift Log: Structured logging
• Swift HTTP Types: Type-safe HTTP handling

Build Tools

• Xcode: Main IDE and build system
• Swift Package Manager: Dependency management
• Cargo: Rust toolchain for tty-fwd
• npm: Frontend build tooling

Installation

Prerequisites

• macOS 14.0 or later
• Xcode 15.0 or later (for development)
• Rust toolchain (for building tty-fwd)
• Node.js and npm (for frontend development)

Building from Source

1. Clone the repository:

   git clone https://github.com/amantus-ai/vibetunnel.git
   cd vibetunnel
   

2. Build the Rust server:

   cd rust/tty-fwd
   cargo build --release
   cd ../..
   

3. Build the web frontend:

   cd web
   npm install
   npm run build
   cd ..
   

4. Open in Xcode and build:

   open VibeTunnel.xcodeproj
   

Usage

Using the vt Command

VibeTunnel includes a command-line wrapper vt that forwards terminal application output through the tunnel. This allows remote monitoring and control of your terminal sessions. The command can be installed from the VibeTunnel settings or it can be found in VibeTunnel.app/Contents/MacOS/Resources/vt to symlink onto your PATH.

Basic Usage

# Run any command with VibeTunnel monitoring
vt [command] [args...]

# Examples
vt top                    # Monitor top command
vt python script.py       # Run Python script with output forwarding
vt npm test              # Run tests with VibeTunnel visibility

Claude Integration

vt --claude              # Auto-locate and run Claude
vt --claude --help       # Run Claude with --help option
vt --claude-yolo         # Run Claude with --dangerously-skip-permissions

Shell Sessions

vt --shell               # Launch current shell
vt -i                    # Launch current shell (short form)

Advanced Options

vt -S ls -la            # Execute without shell wrapper (no alias resolution)
vt --no-shell-wrap cmd   # Same as -S
vt --help               # Show detailed help

The vt wrapper automatically uses shell resolution to handle aliases, functions, and built-ins, making it work seamlessly with your existing terminal setup.

Getting Started

1. Launch VibeTunnel: The app appears in your menu bar
2. Start Server: Click the menu bar icon and select "Start Server"
3. Access Web UI: Navigate to http://localhost:4020 (default port)
4. Create Session: Use the web interface to create new terminal sessions
5. Remote Access: Enable ngrok integration for secure remote access

Development

Project Structure

vibetunnel/
├── VibeTunnel/              # macOS app source
│   ├── Services/            # Core services (servers, managers)
│   ├── Models/              # Data models
│   ├── Views/               # SwiftUI views
│   └── Resources/           # Assets and bundled files
├── rust/tty-fwd/           # Rust TTY forwarding server
├── web/                    # TypeScript/JavaScript frontend
├── scripts/                # Build and utility scripts
└── Tests/                  # Unit and integration tests

Key Design Patterns

1. Protocol-Oriented Design: ServerProtocol allows swapping server implementations
2. Actor Pattern: Swift actors for thread-safe state management
3. Dependency Injection: Services are injected for testability
4. MVVM Architecture: Clear separation of views and business logic

Testing

# Run Swift tests
swift test

# Run Rust tests
cd rust/tty-fwd && cargo test

# Run frontend tests
cd web && npm test

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

VibeTunnel is open source software licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

• Built with Hummingbird HTTP server framework
• Terminal rendering powered by asciinema player
• Auto-updates via Sparkle

---

VibeTunnel - Bridging terminals to the web, one session at a time.