vibetunnel/docs/TESTING_EXTERNAL_DEVICES.md

Testing VibeTunnel on External Devices

This guide explains how to test VibeTunnel development changes on external devices like iPads, iPhones, and other computers.

Overview

When developing VibeTunnel's web interface, you may encounter browser-specific issues that only appear on certain devices (e.g., Safari on iPad). This guide shows you how to test your local development changes on these devices without deploying.

Quick Start: Development Server Method

This is the recommended approach for rapid iteration during development.

1. Start the Development Server

cd web
pnpm run dev --port 4021 --bind 0.0.0.0

Key parameters:

• --port 4021: Use a different port than the production server (4020)
• --bind 0.0.0.0: Bind to all network interfaces (not just localhost)

2. Find Your Mac's IP Address

Option A: System Preferences

1. Open System Preferences → Network
2. Select Wi-Fi → Advanced → TCP/IP
3. Look for "IPv4 Address"

Option B: Terminal

# For Wi-Fi connection
ipconfig getifaddr en0

# For Ethernet connection
ipconfig getifaddr en1

3. Access from External Device

Open a browser on your external device and navigate to:

http://[your-mac-ip]:4021

Example: http://192.168.1.42:4021

Production Build Method

Use this method when you need to test with the full Mac app integration.

1. Build the Web Project

cd web
pnpm run build

2. Configure VibeTunnel for Network Access

1. Open VibeTunnel from the menu bar
2. Go to Settings → Dashboard Access
3. Select "Network" mode
4. Set a dashboard password (required for network access)

3. Access from External Device

http://[your-mac-ip]:4020

Common Issues and Solutions

Cannot Connect from External Device

Check network connectivity:

• Ensure both devices are on the same Wi-Fi network
• Verify the IP address is correct
• Try pinging your Mac from the external device

Check firewall settings:

• macOS may block incoming connections
• When prompted, click "Allow" for Node.js/Bun
• Check System Preferences → Security & Privacy → Firewall

Verify server is running:

# Check if the port is listening
lsof -i :4021

Changes Not Appearing

For development server:

• Hot reload should work automatically
• Try hard refresh on the external device (Cmd+Shift+R on Safari)
• Check the terminal for build errors

For production build:

• You must rebuild after each change: pnpm run build
• Restart the VibeTunnel server after building
• Clear browser cache on the external device

Safari-Specific Issues

Enable Developer Mode on iOS/iPadOS:

1. Settings → Safari → Advanced → Web Inspector (ON)
2. Connect device to Mac via USB
3. Open Safari on Mac → Develop menu → [Your Device]
4. Select the page to inspect

Common Safari quirks:

• Different touch event handling
• Stricter security policies
• Different viewport behavior
• WebSocket connection issues

Advanced Testing Scenarios

Testing with HTTPS

Some features may require HTTPS. Use ngrok for secure tunneling:

# Install ngrok
brew install ngrok

# Create tunnel to dev server
ngrok http 4021

Testing Different Network Conditions

Use Chrome DevTools or Safari Web Inspector to simulate:

• Slow network connections
• Offline mode
• Different device viewports

Multi-Device Testing

Test on multiple devices simultaneously:

# Terminal 1: Development server
pnpm run dev --port 4021 --bind 0.0.0.0

# Terminal 2: Production server (if needed)
# VibeTunnel app handles this automatically

Security Considerations

Development only:

• Only use --bind 0.0.0.0 on trusted networks
• The dev server has no authentication
• Consider using a firewall to restrict access

Production testing:

• Always set a dashboard password
• Use Tailscale or ngrok for remote access
• Never expose unprotected servers to the internet

Debugging Tips

Console Access on Mobile

Safari on iOS/iPadOS:

1. Enable Web Inspector (see above)
2. Connect device to Mac
3. Use Safari Developer Tools

Chrome on Android:

1. Enable Developer Options
2. Connect via USB
3. Open chrome://inspect on desktop Chrome

Network Debugging

Monitor network requests:

# Watch incoming connections
sudo lsof -i -P | grep LISTEN | grep 4021

# Monitor HTTP traffic
sudo tcpdump -i en0 port 4021

Performance Profiling

Use browser developer tools to:

• Profile JavaScript performance
• Analyze rendering bottlenecks
• Check memory usage
• Monitor WebSocket traffic

Best Practices

1. Always test on real devices - Emulators don't catch all issues
2. Test on multiple browsers - Safari, Chrome, Firefox behave differently
3. Check different orientations - Portrait and landscape modes
4. Test with poor network - Not everyone has fast Wi-Fi
5. Verify touch interactions - Mouse events ≠ touch events
6. Check responsive design - Different screen sizes and resolutions

Related Documentation

• README.md - General setup and usage
• CONTRIBUTING.md - Development workflow
• spec.md - Technical specification
• architecture.md - System architecture