VibeTunnel Documentation

VibeTunnel is a macOS application that provides browser-based access to Mac terminals. It consists of a native macOS application (Swift/SwiftUI) that manages a Node.js/Bun server process. This server handles terminal sessions via node-pty and communicates with clients (Web Browsers or iOS apps) using a WebSocket-based binary buffer protocol.

Key architectural components include:

• ServerManager: Manages the Bun server lifecycle and configuration.
• BunServer: The core process handling HTTP/WebSocket traffic and PTY allocation.
• SessionMonitor: Tracks active terminal sessions.
• TerminalManager: Integrates with macOS terminal applications like Terminal.app or iTerm2.
• NgrokService: Manages secure public tunnels for remote access.

VibeTunnel uses a centralized pruning logic to handle asciicast data more efficiently. The current implementation (post-commit 627309ebf) moves from a retroactive, playback-based detection model to a real-time, write-based model. This ensures that pruning sequences (like terminal clear operations) are detected once during the recording phase, allowing for immediate and precise playback without the need to re-scan large files when a client connects.

Key Benefits:

• Reduced Latency: Client connections start streaming almost instantly (1-10ms) because offsets are pre-calculated, compared to 100-500ms in the old system.
• Lower Resource Usage: Single-pass detection reduces CPU and I/O overhead, especially for large files (10MB+).
• Scalability: Moves from $O(n)$ complexity per client connection to $O(1)$ lookup, making it suitable for multiple concurrent viewers.

VibeTunnel supports four authentication modes:

• None: Localhost access only (default).
• Password: A simple shared secret.
• Token: JWT-based authentication.
• External: Integration with services like Tailscale or ngrok.

Security Settings Reference

VibeTunnel supports multiple platforms with specific requirements:

macOS

• OS Version: macOS 14.0+ (Sonoma or later)
• Hardware: Apple Silicon Mac (M1+)
• Build Requirements: Xcode 15+ and code signing for terminal permissions.
• CLI Tool: The vt CLI tool is installed to /usr/local/bin/vt on macOS.

iOS

• OS Version: iOS 17.0+
• Device: iPhone or iPad
• Connectivity: Requires network access to the VibeTunnel server.

Linux / Headless

• OS: Any Linux distribution
• Runtime: Node.js 22.12 through 24.x
• Deployment: Ideal for VPS/cloud environments via the vibetunnel npm package.

Browser

• Support: Modern browsers with WebSocket support.
• Rendering: Terminal rendering is handled via canvas/WebGL.

The repository is organized into platform-specific directories and a core web implementation:

• mac/: macOS native application built with Swift and SwiftUI.
• ios/: iOS companion application built with Swift and SwiftUI.
• web/: The core server and frontend implementation (TypeScript).
  • web/src/server/: Node.js/Bun server logic.
  • web/src/client/: Web UI built with Lit and TypeScript.
• scripts/: Build and utility scripts (e.g., logging scripts).
• docs/: Project documentation.

A session is created when the macOS App calls ServerManager.createSession(). This triggers a Unix Socket IPC message to the server, which then performs the following steps:

1. Executes POST /api/sessions.
2. Calls TerminalManager.createTerminal().
3. Spawns a PTY via PtyManager.spawn() using node-pty.
4. Creates a control directory at ~/.vibetunnel/control/[sessionId]/.
5. Starts the BufferAggregator.
6. Returns a response containing { sessionId, wsUrl } to the client.
7. The client connects via WebSocket for bidirectional terminal I/O.

VibeTunnel follows a client-server-PTY architecture designed to stream terminal sessions to a web interface.

Core Components:

• Client: Browser or Electron application.
• Web Server: Handles HTTP endpoints and WebSocket connections.
• PTY Process: Manages the pseudo-terminal lifecycle.
• Terminal Manager: Responsible for binary buffer rendering (converting ANSI to binary cells).
• Stream Watcher: Monitors ascinema files and implements clear sequence truncation to prevent massive data transfers.
• vibetunnel-fwd: An external terminal forwarding component that mirrors stdout to a terminal.

vibetunnel-fwd is a per-session native process written in Rust. It acts as a bridge between a PTY (Pseudo-Terminal) and the VibeTunnel web server. The vt wrapper launches the forwarder around a command, and the web server manages the session by watching session artifacts and sending control messages via a Unix socket.

Architecture Flow: vt $\rightarrow$ vibetunnel-fwd $\rightarrow$ PTY $\rightarrow$ child command

Note that vibetunnel-fwd supports macOS and Linux; Windows is not supported.

VibeTunnel is a cross-platform terminal sharing application composed of three primary modules. Developers can interact with or extend the project based on their target platform:

• macOS Application (mac/): A native macOS app using SwiftUI and the Bun runtime for server orchestration.
• iOS Application (ios/): A companion app for mobile terminal access, utilizing SwiftUI and WebSocket clients.
• Web Server (web/): A TypeScript-based web server (Express) that manages PTY processes and provides a web-based terminal interface.

The project uses separate build systems: Xcode for Apple platforms and Node.js/TypeScript for the web server.

VibeTunnel uses a binary framed message protocol over Unix domain sockets for all inter-process communication (IPC).

Components

• PTY Manager (Server): Creates a Unix domain socket at {session_dir}/ipc.sock, manages PTY process I/O, and tracks session state.
• Socket Client: Connects to the session's Unix socket to send stdin data and control commands, and receive errors/responses.

Socket Path

• Location: {control_dir}/{session_id}/ipc.sock
• macOS Limitation: macOS has a 104 character limit for Unix socket paths (103 usable). Keep control directories short to avoid EINVAL errors.

VibeTunnel is distributed in three primary formats:

1. macOS Application Bundle: The main VibeTunnel.app bundle. It is signed with a Developer ID Application certificate, notarized by Apple, and contains the embedded Bun server and CLI binaries.
2. DMG Distribution: A disk image (VibeTunnel-{version}.dmg) intended for user downloads. It contains the app bundle and an /Applications symlink.
3. CLI Tools Package: Command line binaries installed to /usr/local/bin. This includes the vibetunnel binary and the vt wrapper script.