Browser4

🤖 Browser4

English | 简体中文 | 中国镜像

Table of Contents

• 🤖 Browser4
• 🌟 Introduction
• ✨ Key Capabilities
• Quick Start
• 🧭 Tool Selection Guide
• How to Interact with a Page
• How to Extract Data
• How to Process at Scale
• How to Turn HTML into Spreadsheets — Zero Tokens
• 📦 Installation
• 💡 CLI Guide for Humans
• Quick start
• Mental model
• Global options
• Key concepts before the command list
• Complete command reference
• Timeout environment variables
• State persistence
• 🚀 Build from Source
• Architecture
• 📦 Modules Overview
• 🧩 Programming-Agent Kernel (browser4-coding)
• 🧪 Test Fixture Server (MockSite)
• 🤝 Support & Community
• 📜 Documentation
• 🔧 Proxy Configuration
• License

🌟 Introduction

💖 Browser4 — an AI-native browser engine for autonomous agents, intelligent extraction, and large-scale web automation. 💖

✨ Key Capabilities

• 🤖 Agent Browser — AI agents and humans drive real browsers via a Rust CLI, MCP, and an agentic backend: navigate, click, fill, snapshot, batch, and loop.
• 🧬 Zero-Token Extraction — X-SQL + CSS selectors for deterministic extraction from live pages or stored HTML snapshots; WebMiner ML clustering turns HTML corpora into spreadsheet and report views with no LLM tokens.
• 🧠 Hybrid Intelligence — Combine LLM extraction, ML clustering, X-SQL, and a progressive experience store that reuses learned selectors and blockers.
• ⚡ High-Performance Runtime — Coroutine-safe, CDP-native engine designed for 100k–200k complex page visits per machine per day via swarm/crawl scale-out.
• 📦 Enterprise-Scale Automation — Swarm crawling, batch/loop jobs, stateful sessions, plugins, runtime skills, browser extension, and MCP-over-HTTP.
• 🛠️ Programming-Agent Kernel — 50+ coding.* tools (sandboxed shell/fs, scaffolding, validation, self-development) for agents building Browser4 artifacts — or Browser4 itself.

Quick Start

Paste the following instruction to your favorite AI agent like dsh, claude, codex, workbuddy or openclaw and run it:

Read https://browser4.io/SKILL.md, install or upgrade browser4-cli for browser automation, perform the following task:

1. Open the browser in headed mode (`open --headed`) so the window is visible — this is a human-facing demo
2. go to amazon.com
3. search for pens to draw on whiteboards
4. compare the first 4 ones
5. write the result to a markdown file

DeepSeek Harness integration

https://github.com/platonai/dsh-browser4

dsh plugin --profile web add dsh-browser4                  # npm registry
dsh plugin --profile web add github:platonai/dsh-browser4  # GitHub

🧭 Tool Selection Guide

Choosing the right tool for your task:

How to Interact with a Page

Use snapshot -i --boxes to see clickable/typeable elements with refs like e15, then click , fill "", type/press, select, hover/drag/scroll, and wait to drive the page. All interaction commands accept CSS selectors too. Chain multiple steps efficiently with batch.

Content embedded in `s (payment forms, editors, widgets) is reached with the built-in frame switching: frames lists the frame tree, frame "" scopes subsequent element commands into that frame (same-origin iframes fully supported), and frame main returns to the main document — no manual contentDocument` eval needed.

Typical interactive flow:

# Humans usually want to see the browser — open it headed
browser4-cli open --headed https://example.com/login
browser4-cli snapshot -i --boxes
browser4-cli fill e3 "user@example.com"
browser4-cli fill e4 "secret" --submit
browser4-cli wait --load networkidle
browser4-cli snapshot -i
# iframe-heavy page:
browser4-cli frame "#pay-frame"
browser4-cli fill "#card-number" "4111 1111 1111 1111"
browser4-cli frame main

How to Extract Data

Need to extract data from a page?
├─ Interactive page (click, fill, scroll first)? → snapshot + refs, then extract
├─ Static page, one field? → htmlsnapshot get text "<selector>"
├─ Static page, all matches of one field? → htmlsnapshot get all text "<selector>"
├─ Static page, multiple correlated fields (title+price+url per item)?
│  → htmlsnapshot query --sql @query.sql
├─ Live JS / complex DOM logic? → eval --json
├─ Several outputs from one page (text + links + images + a table)?
│  → scrape --formats "markdown,links,images"   # one capture for all of them
├─ A screenshot or a PDF as a *file* on this machine?
│  → scrape --formats "screenshot,pdf" --output ./out
├─ Natural language ("find the product price")? → extract (needs LLM key)
└─ High volume, many pages? → crawl or swarm with --sql

How to Process at Scale

Need to process multiple pages?
├─ Single list page (search results)? → htmlsnapshot query with DOM_LOAD_AND_SELECT
├─ List of known URLs (in a file)? → crawl --seed-file urls.txt --depth 0 --sql @query.sql
├─ Crawl from a start URL (follow links)? → crawl <url> --out-link-selector "..." --depth N
├─ Need parallel execution (high throughput)? → swarm create → swarm query --seed-file ...
├─ Repeated monitoring (check every hour)? → loop -i 3600 -- eval "..."
└─ Just a few URLs in a shell script?
   → browser4-cli open --headed "https://first-url"   # humans: open once, visibly
   → for url in ...; do browser4-cli goto "$url"; ... done

How to Turn HTML into Spreadsheets — Zero Tokens

WebMiner runs ML clustering on downloaded HTML files to produce structured spreadsheets and interactive reports — no LLM tokens, everything runs locally. webminer is a first-class Browser4 CLI citizen: browser4-cli webminer install + browser4-cli webminer all runs the whole pipeline without PowerShell.

Have HTML files and want structured data — without tokens?
├─ < 20 pages? → browser4-cli crawl --seed-file urls.txt --depth 0 --sql @query.sql
├─ < 1,000 pages (small to medium)? → WebMiner Free (SMILE ML engine)
│  browser4-cli webminer install
│  browser4-cli webminer all ./pages/
│  → Interactive HTML report + Excel spreadsheets — local, zero cost
├─ > 1,000 pages (production scale)? → WebMiner Commercial (Apache Spark ML)
│  Same encode → cluster → views pipeline, distributed across machines
└─ Need to acquire pages first?
   ├─ Single pages: browser4-cli htmlsnapshot export
   ├─ Bulk download: browser4-cli crawl --seed-file urls.txt --depth 0
   └─ High throughput: browser4-cli swarm create → swarm query --seed-file ...
       Then feed the HTML directory to WebMiner

Pipeline: encode (HTML → feature vectors → CSV) → cluster (KMeans, auto-detected K) → views (HTML report + Excel). Free tier uses the SMILE ML library for single-machine clustering (< 1,000 pages). Requires JDK 17+ (auto-detected). See web-miner and browser4-cli help webminer for usage.

📦 Installation

Manually installation is optional since your AI agent is smart enough to install it after reading the SKILL.

Install browser4-cli globally using npm (requires Node.js):

npm install -g browser4-cli
browser4-cli install

Or bootstrap the native binary directly with a single command. The scripts also install the Browser4 backend (runtime bundle) afterwards — running browser4-cli install on a fresh machine, or browser4-cli upgrade when a backend is already present (pass --skip-backend to skip this step):

Windows (PowerShell):

irm https://browser4.oss-cn-beijing.aliyuncs.com/scripts/install-browser4-cli.ps1 | iex

Linux / macOS (bash):

curl -fsSL https://browser4.oss-cn-beijing.aliyuncs.com/scripts/install-browser4-cli.sh | bash

💡 CLI Guide for Humans

browser4-cli is a human-usable browser automation shell, not just an agent backend. You can drive a real browser, inspect state, extract structured data, run X-SQL, orchestrate crawl/swarm jobs, manage server plugins and skills, and hand long-running work to built-in AI features.

If you want the embedded agent-facing instructions, see skills/browser4-cli/SKILL.md. This section is the human reference.

Quick start

# Open a visible browser session (humans usually want to see the window;
# agents should prefer the default headless mode — see SKILL.md)
browser4-cli open --headed https://browser4.io

# Inspect the page and get element refs
browser4-cli snapshot --boxes

# Interact using a ref from the snapshot
browser4-cli click e15
browser4-cli fill e16 "Browser4" --submit

# Extract data from the live page
browser4-cli get text "h1"

# Capture the page into the store, then extract from that copy
browser4-cli htmlsnapshot
browser4-cli htmlsnapshot get text "#main-content"
browser4-cli htmlsnapshot query --sql @query.sql

# Save output
browser4-cli screenshot --full-page --filename page.jpg
browser4-cli pdf --filename page.pdf

Mental model

1. Session-oriented: commands work against the current browser session; use -s for isolated named sessions.
2. Two page views: snapshot is for interactive work with element refs like e15; htmlsnapshot is for DOM/X-SQL extraction with CSS selectors.
3. Interactive vs static extraction: use click, fill, type, press, wait when the page must be manipulated first; use htmlsnapshot query when you need structured extraction from the DOM.
4. Synchronous vs async jobs: agent, swarm, crawl, and async chat-style commands return task IDs you poll later.

Global options

These flags can appear before any command.

Flag · Meaning -h, --help [command\ · category] · Show top-level help, category help, or detailed command help --help-json · Emit the machine-readable command reference -v, --version · Print the CLI version -s, --session · Use a named session instead of the default session. A global flag: place it before the command (browser4-cli -s job-42 snapshot) — after the command it is rejected as a positional argument --server · Override the Browser4 server URL --timeout · Override the HTTP timeout for the current command --proxy · Proxy used for runtime downloads/install operations --json · Emit machine-readable JSON only --pretty · Pretty-print JSON output -q, --quiet · Suppress normal human-readable output -tip, --show-tip · Show a relevant tip on stderr after commands

Key concepts before the command list

Element refs vs CSS selectors

• snapshot returns accessibility-tree refs such as e5, e12, e42
• most interaction commands accept either a snapshot ref or a CSS selector
• htmlsnapshot commands use CSS selectors, not accessibility refs

snapshot vs htmlsnapshot

Tool · Best for · Input model · Output model snapshot · clicking, typing, finding interactive elements · live accessibility tree · refs like e15 htmlsnapshot · DOM inspection, CSS extraction, X-SQL · a fresh snapshot of the active page (every command captures the tab first, then reads; --expires reads the stored snapshot instead) · CSS selectors and query results

LLM configuration

AI-powered commands such as extract, summarize, chat, agent run, and X-SQL llm_* functions require an LLM provider key.

Provider · Environment variables DeepSeek · DEEPSEEK_API_KEY OpenRouter · OPENROUTER_API_KEY, OPENROUTER_MODEL_NAME, OPENROUTER_BASE_URL Volcengine · VOLCENGINE_API_KEY, VOLCENGINE_MODEL_NAME, VOLCENGINE_BASE_URL OpenAI-compatible · OPENAI_API_KEY, OPENAI_MODEL_NAME, OPENAI_BASE_URL Aliyun Qwen · OPENAI_API_KEY, OPENAI_MODEL_NAME, OPENAI_BASE_URL

export DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

Configure one provider. When several provider keys are present, the first one in the

built-in detection order wins — openai comes after the dedicated providers such as

deepseek, so a leftover DEEPSEEK_API_KEY silently wins over OPENAI_*.

browser4-cli doctor prints the key that won (Selected key) and the model the backend

will request (Active model). See LLM configuration.

Complete command reference

Session lifecycle and server administration

Command · Description open [url] · Open a browser session or reconnect to an existing one. Headless by default. Supports --headed (visible window), --headless, --profile , --profile-mode , --interact-level . Note: SYSTEM_DEFAULT is deprecated and unsupported on Chrome ≥ 143 — use attach + state-save/state-load to reuse system browser state (see browser-state-import.md). attach · Attach to an existing browser via CDP or the Browser4 extension. Supports --cdp and remote endpoint options. A channel name resolves candidates from the browser's DevToolsActivePort, --remote-debugging-port and listening ports, and binds the first endpoint that can host a page — over /json, or over the browser-level WebSocket that Chrome's built-in chrome://inspect/#remote-debugging toggle publishes (attach --cdp ws://127.0.0.1:/devtools/browser/ also works). After a successful attach the CLI prints the browser that actually connected (Connected browser: … / Attached to … at …) and shows a ⚠ warning when it conflicts with the requested channel (e.g. requested msedge but Chrome connected) — verify it before driving the session. close · Close the active browser session. list · List browser sessions with their status and next-open behavior. The Connection column prefers the backend-reported actual browser and annotates channel conflicts (e.g. requested msedge · actual Google Chrome). Supports --all, which adds a Workspace column and includes the sessions persisted by every other checkout (* marks the workspace you are running in; foreign rows read Unknown / - / Refresh because this backend cannot verify them). session-default · Make a named session become the default unnamed session. close-all · Close all sessions without stopping the backend. kill-all · Force-stop the backend and Browser4-managed browser processes. stop · Gracefully stop the Browser4 server. status · Show server version, port, health, and the web status panel URL (http://:18182/status). When a session is active it also prints a current-session block: Name / Session ID / Status / Display / Connection / Next open. doctor · Run diagnostics: build info, LLM status (including the configuration file it reads, the winning provider key and the active model), stale daemon cleanup, optional repair. Supports --verbose and --fix; --fix also writes a commented LLM config template. doctor log [name] · List, view, tail, or grep backend log files. Supports --tail, grep-style flags, and doctor log grep . doctor metrics [filter] · List, filter, or grep backend metrics. Supports doctor metrics grep . doctor status [--section ] [--verbose] · Print the aggregated status panel report in the terminal: summary layer by default, full detail with --verbose, one report with --section (health, build, runtime, llm, sessions, pulsar-sessions, swarm, url-pool, browsers, drivers, privacy, plugins, skills, metrics, logs), machine-readable JSON with --json. delete-data · Delete session data. install · Install the Browser4 runtime bundle. Supports --tag and --force. upgrade · Upgrade the CLI/runtime bundle. Supports --tag and --force. uninstall · Remove global installs and runtime data. Supports -y, --yes, and --dry-run.

browser4-cli open --headed https://example.com
browser4-cli attach --cdp chrome
browser4-cli doctor --verbose
browser4-cli doctor log server.log --tail
browser4-cli doctor metrics grep request
browser4-cli doctor status --section skills --verbose

Web status panel: open http://127.0.0.1:18182/status in a browser for a live dashboard (health, version, JVM/runtime, LLM config, sessions, Pulsar sessions — SDK identity, context and main-loop state, swarm — swarm session plus task summary, URL pool — queued/real-time/delay counts per priority cache, browsers & open tabs — per-session browser/driver binding and tab counts, with on-demand live tab details via GET /api/system/tabs — driver pools, plugins: load/enable state and SDK compatibility, skills: registered skills with origin (classpath/filesystem/programmatic), metrics, log files; auto-refreshes, set ?refresh= to change the interval). The panel is backed by the aggregated GET /api/system/status endpoint; the individual endpoints (/api/system/health, /api/system/build, /api/doctor/llm-status, /api/doctor/metrics, /api/doctor/log-files, /api/plugins, /api/skills) remain available. browser4-cli plugin-list also reports load/enable state and SDK version for every installed plugin; the same reports can be read from the terminal with browser4-cli doctor status.

Page screenshots: open http://127.0.0.1:18182/pages.html for a grid of every open page across sessions. The active tab of each session is captured automatically (click a screenshot to re-capture it); inactive tabs show a placeholder that captures on click. Swarm sessions only show placeholders. Screenshots load asynchronously — the backend captures in the background (202 Accepted with Retry-After while capturing, cached image/png when ready), so the panel never blocks on a capture. Backed by GET /api/pages and GET /api/pages/{sessionId}/{guid}/screenshot.png (?refresh=1 forces a new capture).

Navigation

Command · Description goto · Navigate to a URL; auto-opens/reconnects a session if needed. go-back · Go back in browser history. go-forward · Go forward in browser history. reload · Reload the current page.

Core interaction

All interaction commands accept a snapshot ref such as e15 or a CSS selector unless noted otherwise. Most of them also support --no-snapshot to skip the automatic post-action accessibility snapshot.

Command · Description click [button] · Click an element. Supports --modifiers, --follow, --auto-dismiss-dialogs. dblclick [button] · Double-click an element. Supports --modifiers, --follow, --auto-dismiss-dialogs. hover · Hover over an element. fill · Clear and fill text into an editable field. Supports --submit, --verify. type [ref] · Type text into the focused element or a target element. Supports --submit, --verify, --focus, --interactable-timeout, and --method auto\ · chars\ · exec (requires a target ref; auto types short text per-character and bulk-inserts long/multi-line text on textarea/contenteditable via a single execCommand('insertText'), chars forces per-character typing, exec forces the bulk insert). press [ref] · Press a key on the focused element or a target element. Supports --verify, --follow. select · Select a dropdown value. Supports --verify. check · Check a checkbox or radio button. uncheck · Uncheck a checkbox or radio button. drag · Drag and drop from one element to another. wait [target] · Wait for a selector/ref, duration, text, URL pattern, page-load state, or JavaScript expression. Supports --timeout, --text, --url, --load, --fn. upload [file...] · Upload one or more local files to a page file input. The target must be an ` (anything else errors); the paths must be readable by the browser process — local mode: the same machine, and empty/missing files are rejected with a hint; remote backend: paths resolve on the backend host. Supports --no-snapshot`.

wait --load accepts domcontentloaded, load, and networkidle. networkidle only proves the network went quiet — it does not mean late-rendered results exist; for result pages poll the element instead: wait "".

browser4-cli click e8 --follow
browser4-cli fill e4 "john@example.com" --submit
browser4-cli type "Browser4" e7 --verify
browser4-cli wait --text "Success"
browser4-cli wait --load networkidle

Keyboard and mouse

Command · Description keydown · Press and hold a key. keyup · Release a held key. mousemove · Move the mouse to screen/page coordinates. mousedown [button] · Press a mouse button. mouseup [button] · Release a mouse button. mousewheel · Scroll using a wheel delta. scroll · Scroll the page up, down, left, or right.

Page inspection and live extraction

Command · Description | snapshot | Capture an accessibility-tree snapshot. Supports --boxes/--no-boxes, -i/--interactive, -u/--urls, -c/--compact, --no-compact, -d/--depth, -l/--limit, -s/--selector, --raw, --stdout, -vp/--viewport, --filename. --stdout/--raw output is paginated at 2000 lines/page by default — when truncated, stdout (if piped) gets a # … output truncated: showing N of M lines … hint and