Headless & Headful Modes
Headless mode
Section titled “Headless mode”The default. The browser runs without a GUI, using less resources.
ws://localhost:9222/connect?headless=true&os=windowsHeadful mode
Section titled “Headful mode”Run a visible browser inside the container via Xvnc. Watch sessions live through the built-in noVNC viewer.
ws://localhost:9222/connect?headless=false&os=windowsView at http://localhost:6080/vnc.html.
VNC (noVNC viewer)
Section titled “VNC (noVNC viewer)”When STEALTH_BROWSER_NOVNC=true (the default), each browser gets its own noVNC port in the range 6080–6119. This allows you to view multiple sessions simultaneously.
Local mode
Section titled “Local mode”Open http://localhost:6080 in your browser.
Cloud mode
Section titled “Cloud mode”Pass vnc=True to connect_url() and use the returned VNC URL:
ws_url = client.connect_url(os="windows", vnc=True)print(f"Watch live: {client.last_vnc_url}")const wsUrl = await client.connectUrl({ os: 'windows', vnc: true });console.log(`Watch live: ${client.vncUrl}`);When to use each
Section titled “When to use each”| Mode | Use case |
|---|---|
| Headless | Production scraping, CI/CD, performance-sensitive |
| Headful + VNC | Debugging, demos, visual verification, development |