> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibetunnel.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# TESTING EXTERNAL DEVICES

# 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

```bash theme={null}
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**

```bash theme={null}
# 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

```bash theme={null}
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:**

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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](../README.md) - General setup and usage
* [CONTRIBUTING.md](CONTRIBUTING.md) - Development workflow
* [spec.md](spec.md) - Technical specification
* [architecture.md](architecture.md) - System architecture