​
Quickstart Guide

​
Installation

​
Download & Install

  1. Download VibeTunnel.dmg from Releases
  2. Open DMG and drag VibeTunnel to Applications
  3. Launch VibeTunnel from Applications
  4. Grant accessibility permissions when prompted

​
First Terminal

# Open a terminal session in your browser
vt

# Named session
vt --name "Project Build"

# Custom command
vt --command "htop"
The browser opens automatically at http://localhost:4020

​
Essential Commands

CommandPurpose
vtStart new terminal session
vt listShow active sessions
vt kill <id>Terminate session
vt logsView server logs
vt --helpShow all options

​
Configuration

​
Settings Location

~/Library/Preferences/com.steipete.VibeTunnel.plist

​
Key Settings

SettingDefaultOptions
Port4020Any available port
AuthenticationNonePassword, Token
NetworkLocalhostLAN, Tailscale
Auto-startDisabledEnable at login

​
Enable LAN Access

  1. Click VibeTunnel menu bar icon
  2. Select Preferences
  3. Toggle “Allow LAN Connections”
  4. Set password for security

​
Development Mode

​
Using Development Server

# Enable in VibeTunnel settings
Settings → Debug → Use Development Server

# Or run manually
cd web
pnpm install
pnpm dev
Benefits:
  • Hot reload for web changes
  • No Mac app rebuild needed
  • Faster iteration

​
Common Workflows

​
Monitor AI Agents

# Start Claude Code in VibeTunnel
vt --name "Claude Code"
claude

# Access from another device
http://your-mac-ip:4020

​
Remote Development

# With Tailscale
vt --tailscale

# With ngrok
vt --ngrok

​
Multiple Sessions

# Start multiple named sessions
vt --name "Frontend" --command "cd ~/frontend && npm run dev"
vt --name "Backend" --command "cd ~/backend && npm start"
vt --name "Database" --command "docker-compose up"

​
Keyboard Shortcuts

​
Terminal

ShortcutAction
Cmd+CCopy selection
Cmd+VPaste
Cmd+KClear terminal
Cmd+TNew session
Cmd+WClose session

​
Web Interface

ShortcutAction
Ctrl+Shift+CCopy
Ctrl+Shift+VPaste
Alt+1-9Switch tabs
Ctrl+Alt+TNew terminal

​
Troubleshooting Quick Fixes

​
Server Won’t Start

# Check if port is in use
lsof -i :4020

# Kill existing process
killall node

# Restart VibeTunnel
osascript -e 'quit app "VibeTunnel"'
open -a VibeTunnel

​
Can’t Connect

# Check server status
curl http://localhost:4020/api/health

# View logs
./scripts/vtlog.sh -e

​
Permission Issues

  1. System Preferences → Security & Privacy
  2. Privacy → Accessibility
  3. Add VibeTunnel.app
  4. Restart VibeTunnel

​
Next Steps

​
Quick Tips

  1. Auto-start: Enable “Launch at Login” in preferences
  2. Custom port: Set VT_PORT=8080 environment variable
  3. Debug mode: Hold Option while clicking menu bar icon
  4. Force quit session: vt kill --force <id>
  5. Export recordings: Sessions saved in ~/.vibetunnel/recordings/