WebBrowserBot Documentation

Updated July 2026
WebBrowserBot is a free, open-source browser automation tool built on Playwright. It drives real browser sessions through a simple line-delimited JSON protocol, types and clicks like a human, randomizes its fingerprint per profile, supports optional residential proxies, and streams every session into a live viewer where you can watch, redirect, or take manual control. The GitHub release is launching soon, and this documentation covers everything the tool does.

In This Guide

  1. What WebBrowserBot Is
  2. How It Is Put Together
  3. Feature Highlights
  4. Documentation Pages
  5. Related Guides

What WebBrowserBot Is

WebBrowserBot sits between your automation code and a real browser. Instead of writing Playwright scripts directly, you send small JSON commands like goto, click, type, and read to a local socket, and the bot executes them inside a live browser session. Any program that can open a TCP connection and write a line of JSON can drive a browser with it, which makes it a natural fit for AI agents, cron jobs, and scripts in any language.

Every session runs under a named profile that holds a stable, realistic browser fingerprint along with saved cookies and storage. Sessions type character by character with human-like delays, move the mouse to element centers with natural offsets before clicking, and can run with or without a proxy provider. The result is automation that behaves like a person using a normal desktop browser.

How It Is Put Together

The tool is a small set of Python modules with a clear division of labor:

  • The engine owns Playwright, sessions, profiles, and the command vocabulary. It is implemented once and exposed through both a synchronous and an asynchronous entry point.
  • The transport layer accepts commands as line-delimited JSON, either over a localhost TCP socket or over stdin, one request per line, one response per line.
  • The viewer server is an async process that owns the sessions, keeps the command socket open for your automation, serves a single-page viewer UI over HTTP, and streams live frames to each viewer over WebSocket. Sessions opened through its command socket appear in the UI automatically.

By default the viewer server listens on two localhost-only ports: the viewer UI and WebSocket on port 8770, and the command socket for automation on port 8771. Neither port is exposed to the internet directly. When you want remote access to the viewer, you front it with your web server over TLS, which is covered in the live viewer guide.

Feature Highlights

  • Simple protocol. One JSON object in, one JSON envelope back: {success, session_id, data, error}. Around 40 commands cover sessions, navigation, interaction, reading, tabs, frames, and timing.
  • Stealth fingerprint profiles. Each profile gets a consistent viewport, user agent, GPU identity, and timezone, and keeps its cookies and storage between runs.
  • Human-like input. Character-by-character typing with natural delays, mouse movement with small offsets, and scrolling that reads like a person.
  • Live viewer with manual takeover. Watch any session in the browser, and click Take Control to drive it by hand while your automation politely waits.
  • Optional proxies. Run proxyless by default, or attach a proxy provider per session with sticky IP rotation handled for you.
  • Multi-tab and frame support. Open, switch, and close tabs, list frames, and click inside iframes.
  • Screenshots and page reading. Full-page screenshots, trimmed or raw HTML, and visible-text extraction for JS-rendered pages.

Documentation Pages

The documentation is organized into four guides. If you are new, read them in order.

Getting Started Command Reference Live Viewer and Manual Takeover Profiles and Proxies

WebBrowserBot builds on ideas covered across this site. These guides explain the background concepts:

Playwright: The Complete Automation Guide Browser Fingerprinting Explained How to Avoid Getting Blocked Browser Automation Guide Web Scraping Proxies