vibetunnel

# VibeTunnel - Turn any browser into your terminal; command agents from the road (vt.sh)

Turn any browser into your Mac terminal.
VibeTunnel proxies your terminals right into the browser, so you can vibe-code anywhere.

Documentation • Releases • Discord • Twitter

## Table of Contents - [Why VibeTunnel?](#why-vibetunnel) - [Installation Options](#installation-options) - [Quick Start](#quick-start) - [Features](#features) - [Architecture](#architecture) - [Remote Access Options](#remote-access-options) - [Git Follow Mode](#git-follow-mode) - [Terminal Title Management](#terminal-title-management) - [Authentication](#authentication) - [npm Package](#npm-package) - [Building from Source](#building-from-source) - [Development](#development) - [Poltergeist Integration](#poltergeist-integration) - [Documentation](#documentation) - [macOS Permissions](#macos-permissions) - [Contributing](#contributing) - [Support VibeTunnel](#support-vibetunnel) - [Credits](#credits) - [License](#license) ## Why VibeTunnel? Ever wanted to check on your AI agents while you're away? Need to monitor that long-running build from your phone? Want to share a terminal session with a colleague without complex SSH setups? VibeTunnel makes it happen with zero friction. ## Installation Options ### macOS App (Recommended for Mac users) The native macOS app provides the best experience with menu bar integration and automatic updates. ### npm Package (Linux & Headless Systems) For Linux servers, Docker containers, or headless macOS systems, install via npm: ```bash npm install -g vibetunnel ``` This gives you the full VibeTunnel server with web UI, just without the macOS menu bar app. See the [npm Package section](#npm-package) for detailed usage. ## Quick Start ### Requirements **macOS App**: Requires an Apple Silicon Mac (M1+). Intel Macs are not supported for the native app. **npm Package**: Works on Node.js 22.12 through 24.x, including Intel Macs and Linux. Windows is not yet supported ([#252](https://github.com/amantus-ai/vibetunnel/issues/252)). ### 1. Download & Install #### Option 1: Direct Download [Download VibeTunnel](https://github.com/amantus-ai/vibetunnel/releases/latest) and drag it to your Applications folder. #### Option 2: Homebrew ```bash brew install --cask vibetunnel ``` ### 2. Launch VibeTunnel VibeTunnel lives in your menu bar. Click the icon to start the server. ### 3. Use the `vt` Command The `vt` command is a smart wrapper that forwards your terminal sessions through VibeTunnel: **How it works**: - `vt` is a bash script that internally calls `vibetunnel fwd` to forward terminal output - It provides additional features like shell alias resolution and session title management - Available from both the Mac app and npm package installations **Installation sources**: - **macOS App**: Installs the `vt` wrapper script at `/usr/local/bin/vt` during installation - **npm Package**: Installs `vt` globally, with intelligent Mac app detection **Smart detection**: When you run `vt` from the npm package, it: 1. Checks if the Mac app is installed at `/Applications/VibeTunnel.app` 2. If found, forwards to the Mac app's `vt` for the best experience 3. If not found, uses the npm-installed `vibetunnel fwd` 4. This ensures `vt` always uses the best available implementation ```bash # Run any command in the browser vt pnpm run dev vt npm test vt python script.py # Use your shell aliases vt gs # Your 'git status' alias works! vt claude-danger # Custom aliases are resolved # Open an interactive shell vt --shell # or vt -i # Git follow mode vt follow # Follow current branch vt follow main # Switch to main and follow vt unfollow # Stop following # For more examples and options, see "The vt Forwarding Command" section below ``` ### Git Repository Scanning on First Session When opening a new session for the first time, VibeTunnel's working directory scanner will look for Git repositories. By default, this scans your home directory, which may trigger macOS permission prompts for accessing protected folders (like Desktop, Documents, Downloads, iCloud Drive, or external volumes). To avoid these prompts: - **Option 1**: Navigate to your actual projects directory before opening a session - **Option 2**: Accept the one-time permission prompts (they won't appear again) This only happens on the first session when the scanner discovers your Git repositories. For more details about macOS privacy-protected folders, see [this explanation](https://eclecticlight.co/2025/02/24/gaining-access-to-privacy-protected-folders/). ### 4. Open Your Dashboard Visit [http://localhost:4020](http://localhost:4020) to see all your terminal sessions. ## Features - ** Browser-Based Access** - Control your Mac terminal from any device with a web browser - ** Zero Configuration** - No SSH keys, no port forwarding, no complexity - ** AI Agent Friendly** - Perfect for monitoring Claude Code, ChatGPT, or any terminal-based AI tools - ** Session Activity Indicators** - Real-time activity tracking shows which sessions are active or idle - ** Git Follow Mode** - Terminal automatically follows your IDE's branch switching - **⌨️ Smart Keyboard Handling** - Intelligent shortcut routing with toggleable capture modes. When capture is active, use Cmd+1...9/0 (Mac) or Ctrl+1...9/0 (Linux) to quickly switch between sessions - ** Secure by Design** - Multiple authentication modes, localhost-only mode, or secure tunneling via Tailscale/ngrok - ** Mobile Ready** - Native iOS app and responsive web interface for phones and tablets - ** Session Recording** - All sessions recorded in asciinema format for later playback - **⚡ High Performance** - Optimized Node.js server with minimal resource usage - ** Apple Silicon Native** - Optimized for Apple Silicon (M1+) Macs with ARM64-only binaries - ** Shell Alias Support** - Your custom aliases and shell functions work automatically > **Note**: The iOS app is still work in progress and not recommended for production use yet. ## Architecture VibeTunnel consists of three main components: 1. **macOS Menu Bar App** - Native Swift application that manages the server lifecycle 2. **Node.js Server** - High-performance TypeScript server handling terminal sessions 3. **Web Frontend** - Modern web interface using Lit components and ghostty-web The server runs as a standalone Node.js executable with embedded modules, providing excellent performance and minimal resource usage. ## Remote Access Options ### Option 1: Tailscale (Recommended) [Tailscale](https://tailscale.com) creates a secure peer-to-peer VPN network between your devices. It's the most secure option as traffic stays within your private network without exposing VibeTunnel to the public internet. **How it works**: Tailscale creates an encrypted WireGuard tunnel between your devices, allowing them to communicate as if they were on the same local network, regardless of their physical location. #### Basic Setup 1. Install Tailscale on your Mac: [Download from Mac App Store](https://apps.apple.com/us/app/tailscale/id1475387142), [Direct Download](https://tailscale.com/download/macos), or a CLI/daemon package such as nix-darwin 2. Install Tailscale on your remote device: - **iOS**: [Download from App Store](https://apps.apple.com/us/app/tailscale/id1470499037) - **Android**: [Download from Google Play](https://play.google.com/store/apps/details?id=com.tailscale.ipn) - **Other platforms**: [All Downloads](https://tailscale.com/download) 3. Sign in to both devices with the same account 4. If using VibeTunnel's Tailscale Serve integration, ensure Tailscale Serve is enabled in your [tailnet settings](https://login.tailscale.com/f/serve) 5. Find your Mac's Tailscale hostname in the menu bar app or with `tailscale status` (e.g., `my-mac.tailnet-name.ts.net`) 6. Access VibeTunnel at `http://[your-tailscale-hostname]:4020` VibeTunnel detects standard CLI locations and nix-darwin system/user profiles, and falls back to `tailscale status --json` when the macOS app API is unavailable. #### Enhanced Tailscale Features VibeTunnel now supports advanced Tailscale integration with **Private** and **Public** access modes: ##### Private Mode (Default) - **What it does**: Provides secure HTTPS access within your Tailscale network only - **Access URL**: `https://[your-machine-name].[tailnet-name].ts.net` - **Security**: Traffic stays within your private tailnet - **Best for**: Personal use, accessing your terminals from your own devices ##### Public Mode (Tailscale Funnel) - **What it does**: Exposes VibeTunnel to the public internet via Tailscale Funnel - **Access URL**: Same as Private mode but accessible from anywhere - **Security**: Still uses HTTPS encryption, but accessible without Tailscale login - **Best for**: Sharing terminal sessions with colleagues, temporary public access - **Requirements**: Funnel must be enabled on your tailnet (see configuration below) #### Configuring Tailscale Funnel To use Public mode, you need to enable Funnel on your tailnet: 1. **Enable Funnel for your tailnet** by adding this ACL policy in the [Tailscale Admin Console](https://login.tailscale.com/admin/acls): ```json "nodeAttrs": [ { "target": ["autogroup:member"], // All members of your tailnet "attr": ["funnel"], }, ], ``` 2. **Switch between modes** in VibeTunnel: - Open VibeTunnel Settings → Remote Access - Toggle between "Private (Tailnet Only)" and "Public (Internet)" - The UI will show the transition status and confirm when the mode is active #### HTTPS Support Both Private and Public modes automatically provide **HTTPS access**: - Tailscale Serve creates an HTTPS proxy to VibeTunnel's local server - SSL certificates are managed automatically by Tailscale - No manual certificate configuration needed - WebSocket connections work seamlessly over HTTPS/WSS **Benefits**: - **End-to-end encrypted** traffic - **Automatic HTTPS** with valid certificates - **Works behind NAT** and firewalls - **Zero configuration** after initial setup - **Flexible access control** - choose between private tailnet or public internet access - **No port forwarding** required #### Troubleshooting **"Tailscale Serve unavailable - using fallback mode"**: This is normal if you don't have Tailscale admin permissions. VibeTunnel will work perfectly using direct HTTP access at `http://[your-tailscale-hostname]:4020`. **"Applying mode configuration..."**: When switching between Private and Public modes, it may take a few seconds for Tailscale to reconfigure. This is normal. **"Funnel requires admin permissions"**: You need to be a tailnet admin to enable Funnel. Contact your tailnet admin or create your own tailnet if needed. **WebSocket connections fail**: Make sure you're using the HTTPS URL when accessing VibeTunnel through Tailscale Serve. The WebSocket authentication tokens are au