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?
• Installation Options
• Quick Start
• Features
• Architecture
• Remote Access Options
• Git Follow Mode
• Terminal Title Management
• Authentication
• npm Package
• Building from Source
• Development
• Poltergeist Integration
• Documentation
• macOS Permissions
• Contributing
• Support VibeTunnel
• Credits
• 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:

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 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).

1. Download & Install

Option 1: Direct Download

Download VibeTunnel and drag it to your Applications folder.

Option 2: Homebrew

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

# 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.

4. Open Your Dashboard

Visit 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 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, Direct Download, or a CLI/daemon package such as nix-darwin
2. Install Tailscale on your remote device:
   • iOS: Download from App Store
   • Android: Download from Google Play
   • Other platforms: All Downloads
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
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:

   "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 automatically handled.

Option 2: ngrok

ngrok creates secure tunnels to your localhost, making VibeTunnel accessible via a public URL. Perfect for quick sharing or temporary access.

How it works: ngrok establishes a secure tunnel from a public endpoint to your local VibeTunnel server, handling SSL/TLS encryption and providing a unique URL for access.

Setup Guide:

1. Create a free ngrok account: Sign up for ngrok
2. Copy your auth token from the ngrok dashboard
3. Add the token in VibeTunnel settings (Settings → Remote Access → ngrok)
4. Enable ngrok tunneling in VibeTunnel
5. Share the generated https://[random].ngrok-free.app URL

Benefits:

• Public HTTPS URL with SSL certificate
• No firewall configuration needed
• Built-in request inspection and replay
• Custom domains available (paid plans)

Note: Free ngrok URLs change each time you restart the tunnel. You can claim one free static domain per user, or upgrade to a paid plan for multiple domains.

Option 3: Local Network

1. Configure authentication (see Authentication section)
2. Switch to "Network" mode
3. Access via http://[your-mac-ip]:4020

Option 4: Cloudflare Quick Tunnel

1. Install cloudflared
2. Run cloudflared tunnel --url http://localhost:4020
3. Access via the generated *.trycloudflare.com URL

Option 5: Pinggy

1. Install the Pinggy CLI: npm install -g pinggy
2. Open VibeTunnel Settings → Remote → Pinggy Integration
3. Optionally save a Pinggy access token for a persistent subdomain or custom domain
4. Enable the tunnel and open the displayed public HTTPS URL

Free tunnels use a new URL after reconnecting. A persistent subdoma