vnc

name	vnc
description	Use start-vnc to run a virtual desktop with noVNC — share your screen over the internet so the user can watch browser activity in real time.

VNC Screen Sharing

start-vnc runs a virtual desktop (Xvfb + Fluxbox + x11vnc + noVNC) that the user can view in their browser. Use it when the user wants to see what a browser or GUI app is doing in real time.

Quick Reference

# Start the virtual desktop (default 1280x800)
start-vnc

# Start with custom resolution
start-vnc 1920x1080

# Check if running
start-vnc

# Stop everything
start-vnc --stop

Sharing with the User

After starting VNC, expose it so the user can view from any device:

# Share over internet
wormhole http 6080

# Tell the user to open: <wormhole-url>/vnc.html

The user opens the URL in their browser and sees a live desktop — like screen sharing.

Running a Browser on the Virtual Desktop

Apps must target display :99 to appear on the virtual desktop:

# Launch Chromium
DISPLAY=:99 chromium --no-sandbox http://localhost:3000 &

# Launch Chromium with specific window size
DISPLAY=:99 chromium --no-sandbox --window-size=1280,800 http://localhost:3000 &

# Launch Firefox (if installed)
DISPLAY=:99 firefox http://localhost:3000 &

# Open xterm for debugging
DISPLAY=:99 xterm &

Full Workflow: Let User Watch App Development

# 1. Start the dev server
cd /workspace/my-app
npm run dev &

# 2. Start the virtual desktop
start-vnc

# 3. Open the app in a browser on the virtual desktop
DISPLAY=:99 chromium --no-sandbox http://localhost:3000 &

# 4. Share with the user
wormhole http 6080
# → Give the user the URL + /vnc.html

Now the user sees the app live in their browser. Any changes (hot reload, navigation, interactions) are visible in real time.

Full Workflow: Let User Watch Playwright Tests

# 1. Start VNC
start-vnc

# 2. Run Playwright tests with headed browser on the virtual display
DISPLAY=:99 npx playwright test --headed

# 3. User watches tests run via noVNC

Ports

Service	Port	Protocol
noVNC (web viewer)	6080	HTTP
VNC server	5900	VNC

Tips

• The virtual display is :99 — always use DISPLAY=:99 when launching GUI apps
• noVNC runs on port 6080 — tunnel with wormhole http 6080 for internet access
• No password is set — access is gated by SSH/firewall, not VNC auth
• Fluxbox is the window manager — right-click the desktop for a menu
• Resolution can be changed by stopping and restarting: start-vnc --stop && start-vnc 1920x1080
• xterm is available for quick terminal access on the virtual desktop
• Multiple GUI apps can run simultaneously on the same virtual display