atomk-hermes-skills/skills/misc/remote-browser-vnc/SKILL.md

name, description

name	description
remote-browser-vnc	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)

sudo apt-get install -y x11vnc novnc websockify

2. Start Xvfb (virtual framebuffer)

Xvfb :99 -screen 0 1920x1080x24

3. Launch Chromium on the virtual display

/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

x11vnc -display :99 -nopw -forever -shared -rfbport 5999

Run in background mode.

5. Start noVNC websockify proxy

websockify --web /usr/share/novnc 6080 localhost:5999

Run in background mode.

6. Verify ports are listening

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

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.