VibeTunnel: Running Claude Code on iPhone

This runbook covers setting up VibeTunnel to access Claude Code from your iPhone via Tailscale.

Prerequisites

• Apple Silicon Mac (M1+) with macOS 14.0+

• Homebrew installed

• Tailscale account

• iPhone with Tailscale app installed

Quick Reference

Item	Value
Dashboard URL (IP)	http://<tailscale-ip>:4020
Dashboard URL (Serve)	https://<hostname>.<tailnet>.ts.net/
Username	Your Mac username
Password	Your Mac login password
Start session	vt claude
Check status	vt status

---

Step-by-Step Setup

Step 1: Install VibeTunnel

brew install --cask vibetunnel

Verify installation:

which vt

Step 2: Install Tailscale (if not installed)

brew install --cask tailscale

Step 3: Configure Tailscale on Mac

1. Log out of any stale session:

   tailscale logout

2. Log in:

   tailscale login

   This opens a browser for authentication.

3. Verify connection and get your Tailscale IP:

   tailscale status

   Note the IP address (e.g., 100.x.x.x).

Step 4: Start VibeTunnel

1. Launch the VibeTunnel app:

   open -a VibeTunnel

2. Verify the server is running:

   vt status

   Expected output:

   VibeTunnel Server Status:
     Running: Yes
     Port: 4020
     URL: http://localhost:4020

Step 5: Start Claude Code Session

vt claude

This starts Claude Code with VibeTunnel monitoring, making it visible in the dashboard.

Step 6: Configure iPhone

1. Install Tailscale from the App Store

2. Log in with the same Tailscale account as your Mac

3. Enable the VPN connection when prompted

4. Open Safari and navigate to:

   http://<your-tailscale-ip>:4020

   Example: http://100.x.x.x:4020

Step 7: Authenticate

When prompted for credentials:

• Username: Your Mac username (e.g., michi)

• Password: Your Mac login password

---

Common Issues and Solutions

Issue 1: Tailscale Login Fails - "Device already exists"

Error:

Authorization failed
device with nodekey:xxxx already exists; please log out explicitly and try logging in again.

Solution:

tailscale logout
tailscale login

---

Issue 2: VibeTunnel Server Not Running

Symptom:

vt status
# Output: Running: No

Solution:

1. Kill any existing VibeTunnel processes:

   killall VibeTunnel

2. Relaunch the app:

   open /Applications/VibeTunnel.app

3. Wait a few seconds and check status:

   sleep 3 && vt status

---

Issue 3: Menu Bar Icon Not Visible

Symptom: VibeTunnel app is running but no menu bar icon appears.

Solution:

1. The app may be running without the GUI component. Check processes:

   ps aux | grep -i vibetunnel | grep -v grep

2. Kill and restart:

   killall VibeTunnel
   open -a VibeTunnel

3. Wait for the server to start (may take a few seconds).

---

Issue 4: Cannot Connect from iPhone

Symptom: Safari shows "cannot connect to server"

Checklist:

1. Verify Tailscale is connected on both devices:

   • Mac: tailscale status

   • iPhone: Check Tailscale app shows "Connected"

2. Verify both devices use the same Tailscale account

3. Verify VibeTunnel is running:

   vt status

4. Test local access first:

   curl http://localhost:4020

5. Verify the correct IP:

   tailscale status | grep $(hostname)

---

Issue 5: "Invalid Username or Password"

Symptom: Login page rejects credentials.

Solution:

VibeTunnel uses your Mac system credentials, not Tailscale or Google account.

• Username: Your Mac username (run whoami to check)

• Password: Your Mac login password (the one used to unlock your Mac)

To find your username:

whoami

---

Issue 6: Dashboard Loads but No Sessions Visible

Symptom: Dashboard is accessible but shows no terminal sessions.

Solution:

Sessions must be started with the vt wrapper:

# Start Claude Code with VibeTunnel
vt claude

# Start any command with VibeTunnel
vt <command>

# Start an interactive shell
vt -i

---

Issue 7: Session Disconnects or Freezes

Solution:

1. Check if the Mac went to sleep (disable sleep during long sessions)

2. Verify Tailscale connection is still active:

   tailscale status

3. Restart the session:

   vt claude

---

Issue 8: Login Fails After VibeTunnel Restart

Symptom: Mac username/password no longer works after restarting VibeTunnel.

Cause: VibeTunnel may have restarted with --enable-tailscale-serve mode, which uses different authentication.

Diagnosis:

ps aux | grep vibetunnel | grep -v grep

Look for --enable-tailscale-serve or --bind 127.0.0.1 in the output.

Solution - Use Tailscale Serve:

1. Set up Tailscale Serve:

   tailscale serve reset
   tailscale serve --bg 4020

2. Access via Tailscale hostname (no password needed):

   https://<hostname>.<tailnet>.ts.net/

3. Find your hostname:

   tailscale status | head -1

---

Issue 9: Claude Code Running but 0 Active Sessions

Symptom: Claude Code is running in terminal, but VibeTunnel dashboard shows 0 sessions.

Cause: Claude Code was started with claude instead of vt claude.

Diagnosis:

# Check if sessions are wrapped with vt
ps aux | grep "vibetunnel fwd" | grep -v grep

If no output, sessions aren't being tracked by VibeTunnel.

Solution:

1. Exit your current Claude Code sessions (/exit or Ctrl+C)

2. Restart with the vt wrapper:

   cd ~/code/your-project
   vt claude

Important: Always use vt claude instead of just claude when you want remote access.

---

Issue 10: Tailscale Serve Conflicts

Symptom:

foreground listener already exists for port 443

Solution:

tailscale serve reset
tailscale serve --bg 4020

---

Debugging Commands

Quick commands to diagnose issues:

# Check all components at once
echo "=== VibeTunnel ===" && vt status && \
echo "=== Tailscale ===" && tailscale status && \
echo "=== Active Sessions ===" && ps aux | grep "vibetunnel fwd" | grep -v grep

# Check VibeTunnel server settings
ps aux | grep vibetunnel | grep -v grep | head -1

# Test dashboard is responding
curl -s -o /dev/null -w "HTTP Status: %{http_code}\n" http://localhost:4020

# Check Tailscale Serve status
tailscale serve status

# View VibeTunnel bind address and auth mode
ps aux | grep vibetunnel | grep -o -E '\-\-bind [^ ]+|--enable-tailscale-serve'

---

Managing Multiple Sessions

Running Multiple Claude Code Sessions

Start multiple sessions from different terminal windows on your Mac:

# Terminal 1
vt claude

# Terminal 2 (new terminal window)
vt claude

Naming Sessions for Easy Identification

From within an active vt session, rename it:

vt title "Project A"

Switching Sessions on iPhone

1. Open the VibeTunnel dashboard in Safari

2. You'll see a list of all active sessions with their names and status

3. Tap on any session to switch to it

4. Sessions show activity status (active/idle) to help identify which is which

Keyboard Shortcuts (iPad with keyboard)

Shortcut	Action
Cmd + 1	Switch to session 1
Cmd + 2	Switch to session 2
Cmd + 3-9	Switch to sessions 3-9

Tips for Multiple Sessions

• Name your sessions with vt title to easily identify them

• Sessions persist even if you close the browser - just reconnect to the dashboard

• Each session runs independently - you can have different projects in each

Issue: All Sessions Show Same Name

Symptom: Running Claude Code from different directories but all sessions show the same name (e.g., all show ~/.claude).

Cause: VibeTunnel uses the command name (claude) as the default title, not the working directory.

Solution: Rename each session from within it:

# From within the session (in Claude Code, use /run)
vt title "project-name"

# Or from the Mac terminal running that session
vt title "kuma-blog"

After renaming, refresh the iPhone dashboard to see the updated names.

---

Useful Commands

Command	Description
vt status	Check server status and follow mode
vt claude	Start Claude Code with monitoring
vt -i	Start interactive shell
vt <command>	Run any command with monitoring
vt title "Name"	Rename current session
tailscale status	Check Tailscale connection
tailscale ip	Show your Tailscale IP
tailscale serve --bg 4020	Enable Tailscale Serve for VibeTunnel
tailscale serve status	Check Tailscale Serve configuration
tailscale serve reset	Reset Tailscale Serve settings

---

Architecture Overview

Option A: Direct Tailscale IP Access

┌─────────────────┐     Tailscale      ┌─────────────────┐
│     iPhone      │◄──────────────────►│       Mac       │
│                 │   (100.x.x.x)      │                 │
│  Safari Browser │                    │  VibeTunnel     │
│                 │                    │  (port 4020)    │
└─────────────────┘                    │       │         │
    http://100.x.x.x:4020              │       ▼         │
    + Mac username/password            │  Claude Code    │
                                       │  (via vt)       │
                                       └─────────────────┘

Option B: Tailscale Serve (Recommended)

┌─────────────────┐     Tailscale      ┌─────────────────┐
│     iPhone      │◄──────────────────►│       Mac       │
│                 │     Serve          │                 │
│  Safari Browser │   (HTTPS proxy)    │  VibeTunnel     │
│                 │                    │  (port 4020)    │
└─────────────────┘                    │       │         │
    https://hostname.tailnet.ts.net    │       ▼         │
    + Auto-authenticated               │  Claude Code    │
                                       │  (via vt)       │
                                       └─────────────────┘

---

References

• VibeTunnel GitHub: https://github.com/amantus-ai/vibetunnel

• VibeTunnel Docs: https://docs.vibetunnel.sh

• Tailscale: https://tailscale.com

---

Last updated: 2026-01-03