🤖 Browser4

Project: github.com/platonai/Browser4 · Website: browser4.io

English | 简体中文 | 中国镜像

Table of Contents

• 🤖 Browser4
  • 🌟 Introduction
    • ✨ Key Capabilities
  • 📦 Installation
    • Install DeepSeek Harness (DSH)
    • Install the Browser4 plugin (recommended)
    • Start DSH
    • Use Browser4 in DSH
    • Install browser4-cli (Optional)
    • Install-free usage (optional)
  • 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
  • 💡 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
  • 🧪 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 — Enable AI agents to browse, interact, and automate real-world websites.
• 🧠 ML-Powered Extraction — Learn page structures and extract structured data without LLM token costs.
• ⚡ High-Performance Runtime — Coroutine-safe architecture supporting 100k–200k complex page visits per machine per day.
• 🧬 Hybrid Intelligence — Combine LLM, ML, X-SQL, and selectors for robust extraction and experience reuse.
• 📦 Enterprise-Scale Automation — Large-scale web access, CDP-native control, batch jobs, stateful sessions, plugins, extensions, and more.

📦 Installation

1. Install DeepSeek Harness (DSH)

First check whether DSH is already installed:

dsh --version

If the command prints a version number, DSH is ready — go to the next step. If the command is not found, install it by OS:

macOS

Install Node.js 20 or later, then install DSH:

brew install node
npm install -g @deepseek-ai/dsh

Windows

Install Node.js LTS in PowerShell:

winget install OpenJS.NodeJS.LTS

Reopen PowerShell after installation, then install DSH:

npm install -g @deepseek-ai/dsh

Run dsh --version again to confirm DSH works.

2. Install the Browser4 plugin (recommended)

Install dsh-browser4 as a DSH plugin bundle — from the npm registry or straight from GitHub:

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

Installing the package runs its installer script (scripts/install-browser4.mjs), which:

1. Installs browser4-cli following the browser4-cli SKILL installation process (npm install -g browser4-cli → browser4-cli install, falling back to the platform bootstrap script when npm is unavailable).
2. Unpacks the SKILL files with browser4-cli skills unpack into ~/.dsh/skills and ~/.agents/skills (honouring $DSH_HOME / $DSH_AGENTS_HOME), so every DSH profile and preset discovers the browser4-cli, browser4-experience, browser4-plugin, and scent-miner skills.

The bundle also registers a skill-provider layer (cordis.patch.yml) that serves the same skills directly from the installed package's skills/ directory.

The unpacked skills are the version embedded in your local browser4-cli binary. browser4-cli skills unpack reads the skill files compiled into the CLI itself, not the copies shipped in this npm package. This is intentional: the agent's instructions always match the exact command set, options, and behaviour of the CLI actually installed on the machine — no network fetch, no version drift. After upgrading browser4-cli, just run browser4-cli skills unpack again to refresh.

A shorter alias works too: dsh plugin --profile web add b4@github:platonai/dsh-browser4.

pnpm ≥ 10 blocks dependency build scripts by default. If add fails with a build-permission error, copy the exact package key pnpm prints into the profile's pnpm-workspace.yaml (under $DSH_HOME/profiles/web/) and re-run the command:

allowBuilds:
  dsh-browser4: true

Installing from a local checkout (dsh plugin --profile web add ./dsh-browser4) links the package without running lifecycle scripts — run the installer once manually afterwards:

node scripts/install-browser4.mjs

3. Start DSH

dsh web

4. Use Browser4 in DSH

Once DSH starts, the bundle automatically loads the Skill Provider. The model loads the instructions via skill({ name: "browser4-cli" }) or the /browser4-cli command — no extra setup needed.

After that, just describe your task to the agent in natural language. The agent drives the browser through browser4-cli commands (via the Bash tool), for example:

Open https://browser4.io, find the installation guide,
and save a full-page screenshot to the current directory.

Typical flow the agent performs under the hood:

browser4-cli open --headless https://browser4.io   # open a session (backend starts on first run, ~10s)
browser4-cli snapshot -i --boxes                   # inspect the page and get element refs
browser4-cli click e15                             # interact using refs
browser4-cli screenshot --full-page --filename page.png

Install browser4-cli (Optional)

The plugin installer already installs browser4-cli, so doing this manually is optional. Only do it if you want to use browser4-cli outside DSH, or your AI agent is asked 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:

Windows (PowerShell):

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

Linux / macOS (bash):

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

Install-free usage (optional)

No plugin install needed. Start DSH, then ask the agent to read the SKILL and install it:

Read https://browser4.io/SKILL.md and install browser4-cli (if not installed), then run `browser4-cli skills unpack` into ~/.dsh/skills and ~/.agents/skills, for browser automation

The agent follows the SKILL.md Installation section to install browser4-cli and unpacks the same skill files into the DSH skill roots — the same result as the plugin installer.

Quick Start

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

Read https://browser4.io/SKILL.md and install browser4-cli (if not installed) for browser automation to perform the following task:

1. go to amazon.com
2. search for pens to draw on whiteboards
3. compare the first 4 ones
4. write the result to a markdown file

🧭 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.

Typical interactive flow:

browser4-cli goto 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

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
├─ 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 -- eval "..." -i 3600
└─ Just a few URLs in a shell script?
   → 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.

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)
│  java -jar scent-miner.jar 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+. See web-miner for install instructions.

💡 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 browser session (headless by default; add --headed to see the window)
browser4-cli open https://browser4.io

# Or explicitly open a visible browser:
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 a static DOM snapshot for repeated extraction
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.png
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

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

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.

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 stored raw DOM snapshot and is the center of Browser4's structured extraction workflow.

Important rules:

• use snapshot when you need refs and interaction
• use htmlsnapshot when you need repeated DOM extraction
• 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

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

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

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

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 17+ (21+ recommended), 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.

🎬 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

📦 Modules Overview

🧪 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: ./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.

📜 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.