🤖 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 <ref>, fill <ref> "<text>", 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 <iframe>s (payment forms, editors, widgets) is reached with the built-in frame switching: frames lists the frame tree, frame "<iframe selector>" 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 <html-dir> 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 <name> 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.

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

LLM configuration

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

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

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=<ms> 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

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.

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 "<result-selector>".

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

Page inspection and live extraction

get modes:

browser4-cli snapshot -i --boxes
browser4-cli snapshot grep -C 2 "button"
browser4-cli eval "document.title"
browser4-cli eval --file script.js --await
browser4-cli console warn
browser4-cli cdp Runtime.evaluate --json '{"expression":"document.title"}'

HTML snapshot and X-SQL extraction

htmlsnapshot captures a raw DOM snapshot of the page the active tab is showing and is the center of Browser4's structured extraction workflow. Every htmlsnapshot command works on a fresh snapshot of the active page: it captures the tab first (serializing the document the tab already shows, without navigating) and then operates on that snapshot — capture returns the metadata, while the reads consume it, so a read already sees the live document (form results, SPA updates, eval mutations). A read can also be told to serve the stored snapshot instead: --expires <dur> (default 0s, the live page) serves the stored copy of the active page while it is younger than the window — htmlsnapshot get text ".price" --expires 1d reads the previous snapshot version and never touches the tab. A command aimed at another URL (readability <url>, query --url <url>) reads that URL's stored copy, or an independent read-only load when the store has nothing — a URL the tab does not show is never captured, so the tab's document is never filed under it.

Important rules:

• use snapshot when you need refs and interaction
• use htmlsnapshot when you need repeated DOM extraction — every command captures the tab first, so simply rerunning it sees the page as it is now
• use --expires <dur> on a read when you want the snapshot already in the store (--expires 1d) instead of the live page (--expires 0s, the default) — the stored copy is left untouched and the tab is not serialized
• htmlsnapshot query --sql @query.sql is the recommended way to avoid shell quoting issues
• for correlated list extraction, prefer htmlsnapshot query over repeated get all
• for one-step article extraction (no selectors needed), use htmlsnapshot readability

browser4-cli htmlsnapshot
browser4-cli htmlsnapshot get text "#productTitle"
browser4-cli htmlsnapshot get all text ".result-title" --offset 10 --limit 5
browser4-cli htmlsnapshot inspect ".s-result-item" --depth 6 --max 20
browser4-cli htmlsnapshot export --file page.html --clean
browser4-cli htmlsnapshot query --sql @query.sql
browser4-cli htmlsnapshot readability --text-only --all

For deep X-SQL usage, see skills/browser4-cli/references/htmlsnapshot.md and skills/browser4-cli/references/x-sql-dom-load-select.md.

Screenshots and PDF

Tabs

Browser storage and local page data

AI extraction, chat, and autonomous agent tasks

These commands require an LLM key.

browser4-cli extract "product name, price, rating"
browser4-cli extract "contacts" --schema @schema.json
browser4-cli summarize --selector "#reviews"
browser4-cli agent run "Go to amazon.com, compare the first 3 keyboards, write a summary"
browser4-cli agent status agent-task-1

Batch and loop automation

Batch-compatible commands:

goto  go-back  go-forward  reload  press  type  keydown  keyup
click  dblclick  hover  fill  select  check  uncheck  drag
mousemove  mousedown  mouseup  mousewheel  scroll  wait
get  eval  snapshot  screenshot  pdf  dialog-accept  dialog-dismiss
resize  tab-list  tab-new  tab-close  tab-select

browser4-cli batch --bail "goto https://example.com" "snapshot" "screenshot"
browser4-cli loop "load https://example.com and extract the title" -i 300 -n 10
browser4-cli loop --shell "curl -s https://api.example.com/health" -i 60
browser4-cli loop --list

Network inspection, HAR recording & request routing

Inspect what the page actually loaded (XHR/fetch calls, status codes, headers, response bodies), record a HAR 1.2 archive importable by Chrome DevTools, and route (mock/abort) matching requests. See skills/browser4-cli/references/network.md for the full guide.

browser4-cli network requests --filter api --status 2xx
browser4-cli network har start --content text
browser4-cli network har stop ./capture.har
browser4-cli network route "**/api/users" --body '{"users":[]}' --content-type application/json

Swarm and crawl for scale

The co prefix is accepted as an alias for swarm.

browser4-cli swarm create --max-open-tabs 12 --display-mode HEADLESS
browser4-cli swarm query --seed-file urls.txt --sql @query.sql --refresh
browser4-cli crawl "https://example.com" --depth 2 --out-link-selector "a[href]"
browser4-cli crawl list
browser4-cli crawl resume <task-id>    # continue an interrupted crawl

Bundled skill files vs installed runtime skills

Browser4 has two different "skill" surfaces:

1. skills ... manages bundled, embedded skill documents that ship with the CLI.
2. skill-* manages installed runtime skills exposed by the backend.

Bundled CLI skills

Installed runtime skills

Progressive experience memory

These commands operate on Browser4's learned experience store.

Plugins

Plugins are server-side JARs that extend Browser4.

Advanced and currently hidden commands

These commands exist in the CLI but are intentionally kept out of the default public help.

Timeout environment variables

export BROWSER4_CLI_INPUT_TIMEOUT_SECS=180
export BROWSER4_CLI_NAVIGATION_TIMEOUT_SECS=300

State persistence

CLI state lives under ~/.browser4 unless overridden.

• default session: ~/.browser4/cli-state.json
• named sessions: ~/.browser4/sessions/<name>.json
• loops: ~/.browser4/loops/<name>.json

The runtime bundle is stored separately in a platform-conventional application-data directory, so clearing session state does not force a re-download of Browser4 itself.

🚀 Build from Source

Prerequisites: Git, JDK 25+ (Eclipse Temurin), Chrome/Chromium, and PowerShell 7 (Linux/macOS only). For the full prerequisites table, platform-specific tools, and Chrome auto-detection paths, see Build from Source.

1. Clone the repository

   git clone https://github.com/platonai/Browser4.git
   cd Browser4
   

2. Configure your LLM API key

   Edit application.properties and add your API key, or set environment variables. See LLM Configuration for supported providers and variable names.

3. Build the project

   ./mvnw -DskipTests
   

4. Build and run the CLI (from source)

   # Build the Rust CLI (requires Rust toolchain)
   cd cli/browser4-cli && cargo build --release
   
   # Or run directly without installing:
   cargo run --manifest-path cli/browser4-cli/Cargo.toml -- --help
   
   # Add --quiet to suppress Cargo build-status output:
   cargo run --quiet --manifest-path cli/browser4-cli/Cargo.toml -- <command>
   
   # Or install globally:
   cd cli/browser4-cli && cargo install --path .
   

   On Windows, prefix the command with chcp 65001 >nul && for proper UTF-8 output. See Build from Source for full platform-specific instructions.

   Dev-mode wrappers (no install needed): The repo root provides shell wrappers that auto-build from source. Use ./b4w.ps1 <command> (PowerShell), ./b4w.sh <command> (Git Bash / Linux / macOS), or ./b4w.bat <command> (CMD) — all accept the same arguments as the installed browser4-cli binary. Dev mode only ever serves the checked-out code: a local runtime bundle built from a different project version makes the command refuse to start (naming the reason, the bundle's versions and build time, and the rebuild command) rather than silently testing an outdated backend; a checkout whose sources merely look newer than the bundle jars is rebuilt before the server starts — see CLI install & upgrade.

🎬 YouTube:

📺 Bilibili: https://www.bilibili.com/video/BV1kM2rYrEFC

Architecture

browser4-cli (Rust) ──MCP over HTTP──▶ browser4-rest (Kotlin/Spring) ──▶ PulsarWebDriver (Kotlin/CDP)

• CLI (cli/browser4-cli) — native Rust binary, talks to the backend via MCP tool calls
• Backend (browser4-rest) — Spring Boot server, dispatches MCP tools to browser drivers
• Browser driver (browser4-core/browser4-browser) — wraps Chrome DevTools Protocol
• Agent tools (browser4-agentic) — maps MCP tool names to browser automation methods
• Programming kernel (browser4-coding) — dependency-light agent toolkit (sandboxed shell/filesystem, scaffolding, validation, self-development tools) — see below

📦 Modules Overview

🧩 Programming-Agent Kernel (browser4-coding)

browser4-coding is the dependency-light programming kernel that lets an AI agent create Browser4 artifacts and develop Browser4 itself. It is independent of browser4-agentic and pulsar-common (only SLF4J + Jackson + coroutines), so it can be reused by non-agent hosts. Heavy backends (LSP servers, kotlin-compiler-embeddable) are probed at runtime and never downloaded by default.

The coding domain exposes 47 tools in four groups:

Generic vs project-specific: the kernel is layered by mechanism vs data — diff, sandbox, LSP client, Kotlin analysis, Maven passthrough and the pom-graph scanner are generic and portable; the scaffolds, validators, ModuleMap, CdpTrapCheck and the governance defaults encode Browser4 conventions and are the layer to rewrite when reusing the kernel elsewhere.

• Full tool reference & workflows: skills/browser4-coding/SKILL.md
• Developing Browser4 itself: skills/browser4-dev/SKILL.md
• Four-artifact comparison examples (real vs scaffold output): docs-dev/copilot/examples/
• Evaluation summary (P1–P7): docs-dev/copilot/browser4-programming-support-eval.md

🧪 Test Fixture Server (MockSite)

Browser4 includes a lightweight MockSite server that serves static HTML pages for testing and demos. Start it from the repository root:

Windows (pwsh — PowerShell 7+): ./bin/test.ps1 mock-site -Dmock.site.port=18080 Linux/macOS: ./bin/test.sh mock-site -Dmock.site.port=18080

Key demo pages are served at http://localhost:18080/generated/. For the full page listing, environment variables, Python fallback, and Maven-based launch, see MockSite. For the test taxonomy and tagging system, see Test Taxonomy.

🤝 Support & Community

Join our community for support, feedback, and collaboration!

• GitHub Discussions: Engage with developers and users.
• Issue Tracker: Report bugs or request features.
• Social Media: Follow us for updates and news.

We welcome contributions! See CONTRIBUTING.md for details.

Contact Us

• 💬 WeChat: galaxyeye
• 🌐 Weibo: galaxyeye
• 📧 Email: galaxyeye@live.cn, ivincent.zhang@gmail.com
• 🐦 Twitter: galaxyeye8

📜 Documentation

Comprehensive documentation is available in the docs/ directory and on our GitHub Pages site.

🔧 Proxy Configuration - Unblock Website Access

export PROXY_ROTATION_URL=https://your-proxy-provider.com/rotation-endpoint

License

Apache 2.0 License. See LICENSE for details.

Links

• omdsh-dev/dsh-data-agent - DSH Data Agent · Analyze data through conversation
• ccch1mneyyy/dsh-TUI - DSH TUI · Text-based User Interface