---
name: remote-browser-vnc
description: Set up a remote desktop browser via VNC/noVNC for user to log in to sites with CAPTCHA or 2FA that block automation.
---

# Remote Browser via VNC for Interactive Login

When a website has CAPTCHA, email verification, or other interactive login barriers that prevent headless automation, set up a VNC-accessible browser on the server for the user to log in manually, then resume automation afterward.

## Setup Steps

### 1. Install dependencies (requires root/sudo)
```bash
sudo apt-get install -y x11vnc novnc websockify
```

### 2. Start Xvfb (virtual framebuffer)
```bash
Xvfb :99 -screen 0 1920x1080x24
```

### 3. Launch Chromium on the virtual display
```bash
/home/ubuntu/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
  --no-sandbox --disable-gpu --window-size=1920,1080 \
  --disable-setuid-sandbox --disable-dev-shm-usage
```
Run this in background mode: `terminal(background=true)`

### 4. Start x11vnc to share the display
```bash
x11vnc -display :99 -nopw -forever -shared -rfbport 5999
```
Run in background mode.

### 5. Start noVNC websockify proxy
```bash
websockify --web /usr/share/novnc 6080 localhost:5999
```
Run in background mode.

### 6. Verify ports are listening
```bash
ss -tlnp | grep -E '5999|6080'
```
Should show both ports listening.

### 7. User connects
Tell user to visit in their browser:
```
http://<server-ip>:6080/vnc.html
```
Then click Connect (no password needed).

### 8. Resume automation after login
After user confirms login is complete, use Playwright with `chromium.connectOverCDP()` or continue using the same browser instance to automate post-login tasks.

## Port Summary
| Service | Port | Purpose |
|---------|------|---------|
| Xvfb | :99 | Virtual X11 display |
| x11vnc | 5999 | VNC server |
| noVNC | 6080 | Web-accessible VNC client |

## Cleanup
```bash
killall -9 chrome Xvfb x11vnc websockify 2>/dev/null
```

## Pitfalls
- **No root access**: `apt-get install` requires sudo. If not available, use Playwright's `chromium.launch({ headless: false })` with `chromium.connectOverCDP()` approach instead.
- **Firewall**: Port 6080 must be accessible from user's machine. Check cloud security groups.
- **Chromium path**: May vary by Playwright version. Check `/home/ubuntu/.cache/ms-playwright/` for the actual chromium directory.
- **Server IP**: Use the SSH connection IP or check cloud console. `curl ip.sb` may be blocked.
- **Browser won't start without display**: Must start Xvfb BEFORE launching Chromium, and set `DISPLAY=:99`.
- **x11vnc can't connect**: If x11vnc says "unable to open display", Xvfb isn't running. Check with `ps aux | grep Xvfb`.