platonai/dsh-browser4

🤖 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:

```yaml

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

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