SuperBrowser

The browser your agent won't get blocked on.

Quick start · Examples · What it does · Config

Give your agent a real browser. SuperBrowser handles the parts that break LLMs in the wild — captchas, Cloudflare, autocomplete dropdowns, "let me Google that" drift — so your prompt can stay focused on the task.

from runagent_superbrowser import SuperBrowser

sb = SuperBrowser()

# One call. The agent decides whether a lightweight fetch or a full browser
# session is the right tool — you just say what you want, no "please click…".
res = sb.run("find me a black summer dress under $80 on zara.com, size M, ships to Dhaka")
print(res.text)

Run it — SDK, Docker, or npm

Three ways to run the same thing locally. Two moving parts: the engine (the TypeScript stealth-browser server on :3100) and the SDK (the Python brain that drives it). Pick the setup that fits you.

1. Host engine + Python SDK — `npm run dev`

Run the engine on your host, drive it with the SDK in-process. This is examples/03_browser_mode.py.

npm install && npm run build            # once
npm run dev                             # TS engine on :3100 (watch mode)
python examples/03_browser_mode.py      # the SDK, in another shell

Or let the SDK start and stop the engine for you (what example 03 does — no second shell):

from runagent_superbrowser import SuperBrowser

with SuperBrowser(auto_start_server=True, server_cmd=["npm", "run", "dev"]) as sb:
    print(sb.run("book a 4-star Sylhet hotel Sun–Thu", url="https://gozayaan.com", mode="browser").text)

2. Docker all-in-one — `docker compose`

One container runs the engine and the orchestrator, exposed on :8450 — no Node/Python/venv on the host, no RunAgent key. This is examples/07_local_docker.py (or 06).

cp deploy/.env.example deploy/.env      # set the brain (below) + a provider key
docker compose up -d --build            # agent server on :8450 (‑‑build after any Dockerfile change)
python examples/07_local_docker.py      # the SDK talks to the container

sb = SuperBrowser(remote=False, local_agent_url="http://localhost:8450")
print(sb.run("what's the top story on Hacker News?").text)

To make Docker's brain identical to your host, hand the container your nanobot config verbatim — it reproduces the model and its loop tuning — and leave LLM_MODEL unset (setting both would override the delivered model):

echo "NANOBOT_CONFIG_JSON_B64=$(base64 -w0 ~/.nanobot/config.json)" >> deploy/.env

3. uv — no manual venv, reproducible from the lockfile

uv builds an isolated env from uv.lock and runs either path above. runagent (needed only for the Docker/local-agent SDK) pins an old websockets; a [tool.uv] override reconciles it, so uv sync just works.

uv sync                                 # base SDK → in-process / npm-dev mode (example 03)
uv sync --extra remote                  # + runagent → Docker / local-agent mode (examples 06, 07)
uv run patchright install chromium      # host browser mode needs the stealth Chromium (skip for Docker-only)

uv run python examples/03_browser_mode.py
uv run python examples/07_local_docker.py

Or deploy to serverless

Callable from every RunAgent SDK (Python / TS / Go / Rust / Dart / C#), with on-demand micro-VMs and per-user persistent sessions:

runagent init my-browser --from-template superbrowser/default   # or: cd deploy
cp .env.example .env     # set LLM_MODEL + OPENAI_API_KEY (or ANTHROPIC_API_KEY)
runagent deploy .        # prints an agent_id

Then RunAgentClient(agent_id, "run", local=False, persistent_memory=True).run(task="…"). See deploy/README.md and docs/sdk.md.

Python SDK

pip install runagent-superbrowser gives you a one-object SDK. Terse goals in, structured results out — the heavy prompting (routing rules, anti-fabrication, the browser tool ladder) ships inside the package, so you don't hand-write "please click… please type…".

from runagent_superbrowser import SuperBrowser

sb = SuperBrowser()
res = sb.run("what's the top story on Hacker News right now?")
print(res.text)        # the answer
print(res.success)     # did it work?

Pick how it browses — or let it decide

mode is the intelligence switch:

`mode`	What runs	Needs the engine?
`"auto"` (default)	the agent decides: lightweight fetch/search or a real browser	only if it picks the browser
`"fetch"`	read-only: HTTP / stealth fetch / search. Fast, no captcha risk	no
`"browser"`	a real headless browser — clicks, forms, logins, bookings	yes

sb.run("average price of used iPhone 16 Pro on mercari.com", mode="fetch")
sb.run("book a 4-star Sylhet hotel, Sun–Thu, 2 adults", url="https://gozayaan.com", mode="browser")

In auto mode the result tells you which way it leaned, and why:

res = sb.run("cheapest DAC→BKK flight Apr 30, return May 5")
print(res.classification)   # {'approach': 'browser', 'reason': '…', 'confidence': 0.88}

Typed results

Pass a pydantic model (or list[Model], or a JSON Schema dict) and get parsed data back in res.data — best-effort, never raises:

from pydantic import BaseModel
from runagent_superbrowser import SuperBrowser

class Hotel(BaseModel):
    name: str
    price_usd: float

res = SuperBrowser().run(
    "list 4–5 star hotels in Sylhet with nightly prices",
    url="https://gozayaan.com", mode="browser",
    output_schema=list[Hotel],
)
for h in res.data or []:    # list[Hotel]; None if the model didn't return clean JSON
    print(h.name, h.price_usd)

The browser engine

Browser mode needs the TS engine on :3100. Start it yourself (superbrowser http), or let the SDK start and stop it for you:

with SuperBrowser(auto_start_server=True) as sb:   # spawns the engine, tears it down on exit
    res = sb.run("…", mode="browser")

Async + CLI

res = await SuperBrowser().arun("…", mode="fetch")

superbrowser-run "what's trending on github this week" --mode fetch
superbrowser-run "book the cheapest DAC→BKK flight" --mode browser --auto-start-server

Model + API keys come from ~/.nanobot/config.json (nanobot onboard); vision and server knobs from env / .env. Override per-instance with SuperBrowser(model=…, vision=…, server_url=…, workspace_root=…). Full guide: docs/sdk.md.

The low-level register_all_tools(bot) / raw /session HTTP API are still there for advanced use — see Examples.

Drive it from a chat app

Plug SuperBrowser into WhatsApp, Telegram, Discord, Slack (also DingTalk, Lark, QQ — the SDKs are already vendored). Type a task in chat, the agent runs it in the cloud, and when it hits a captcha your phone buzzes with a live-view link — tap, swipe, the session resumes on the same cookies.

You (WhatsApp):  "book me a Khulna hotel under $40/night, check-in Apr 23"

  SuperBrowser:  Searching gozayaan.com...
                 Filtering 4-star, under $40...
                 [hit a captcha] → tap here: https://browser.runagent.cloud/v/abc
                                ↑ you tap once, swipe slider, done

  SuperBrowser:  Found 3 hotels. Top pick: Hotel Castle Salam,
                 $34/night, 4.2★. Want me to book?

You (WhatsApp):  "yes, my card on file"

Wire it up in one env var:

HANDOFF_WEBHOOK_URL=https://your-bot.example.com/webhooks/handoff

The webhook receives {viewUrl, captchaType, pageTitle, screenshot, caption} — forward that to whichever messenger SDK you're using. WebSocket events (awaiting_human, captcha_active, captcha_done) push updates with snapshot replay so late subscribers see the same state. Cookies persist per task, so the human only solves once per site.

What it does

Runs through captchas. Cloudflare, Akamai, DataDome, PerimeterX, Kasada. Auto-pass on warm profiles, Turnstile token solvers, vision-based slider / jigsaw / rotation solvers, or hand off to a human via a live-view URL.
Doesn't get fingerprinted. Per-domain persistent Chrome profiles. First visit takes the hit, every visit after looks like a returning user.
Picks the cheapest engine that works. httpx for plain pages, Puppeteer for SPAs, curl_cffi for TLS-blocked APIs, undetected Chromium for the hard targets, Wayback as a fallback. One tool call, the router does the rest.
Stops LLM failure patterns at the tool layer. No more "khulnakhulna, bangladesh" from a missed autocomplete. No more "let me check Google" mid-task. No more re-typing into a closed dropdown.
Keeps your reasoning model cheap. A dedicated tiny vision model labels screenshots into [V1], [V2] boxes. Your expensive LLM never sees raw pixels.
Hands off to a human when stuck. Live-view URL fires through a webhook to WhatsApp / Slack / Telegram. User taps once, session resumes on the same cookies.

Install

Run it locally. Datacenter IPs (Hetzner, AWS, DigitalOcean…) get blocked by a lot of sites. On your own machine — macOS, Windows, or Ubuntu — you look like a normal visitor. The one-liner below gets you there on any of them.

Fastest — one-command bootstrap

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/runagent-dev/runagent-superbrowser/main/scripts/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/runagent-dev/runagent-superbrowser/main/scripts/install.ps1 | iex

It clones the repo, installs Google Chrome (+ Xvfb and the headless system libs on Linux), sets up a Python venv and the patchright Chromium, builds the TS engine, and writes a .env. The only things it won't silently install are the Node 20+ / Python 3.11+ runtimes — it detects them and prints the right command for your OS so it never clobbers nvm/pyenv. Pass --check to dry-run, --yes for non-interactive (-Check / -Yes on PowerShell).

Then:

superbrowser-doctor     # verify Chrome, build, env, server
superbrowser            # start the engine on :3100  (alias: npm start)

From packages

The two halves publish separately — the browser engine to npm, the agent bridge to PyPI:

# TS browser engine (HTTP + MCP server):
npm install -g runagent-superbrowser

# Python agent bridge (nanobot tools, captcha solving, Tier-3):
pip install runagent-superbrowser
patchright install chromium          # download the stealth Chromium (pip can't)
playwright install-deps chromium     # Linux only: the apt libs Chromium needs
superbrowser-doctor                  # check Chrome, build, env

puppeteer-core does not bundle a browser — you need real Google Chrome on the machine. The bootstrap installer handles it; if you set things up by hand on a fresh Ubuntu/Debian VM, Chrome isn't in the default apt repos, so apt install google-chrome-stable fails until you add Google's repo first:

# add Google's signing key + apt source, then install Chrome
wget -q -O - https://dl.google.com/linux/linux_signing_key.pub \
  | sudo gpg --dearmor -o /usr/share/keyrings/google-chrome.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/google-chrome.gpg] https://dl.google.com/linux/chrome/deb/ stable main" \
  | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt update && sudo apt install -y google-chrome-stable

Then point PUPPETEER_EXECUTABLE_PATH at the binary:

OS	Typical Chrome path
Ubuntu/Debian	`/usr/bin/google-chrome-stable`
macOS	`/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`
Windows	`C:\Program Files\Google\Chrome\Application\chrome.exe`

Or Docker (all-in-one agent server)

One container runs the stealth browser engine and the agent orchestrator on :8450 — no Node/Python/venv on the host, no RunAgent key. The run recipe is above:

cp deploy/.env.example deploy/.env      # set the brain + a provider key
docker compose up -d --build            # ready when :8450/api/v1/health is healthy

The image bakes Node, real Google Chrome, patchright's stealth Chromium (+ Xvfb for headful Tier-3), and the Python bridge. Compose gives it shm_size: 2gb (Chrome renderer memory) and persists ~/.superbrowser (cookies/profiles) and ~/.nanobot (orchestrator state) in named volumes across restarts. See docs/sdk.md → Local agent server (Docker) for the full picture (in-process vs local-agent vs remote).

Per-OS notes

	Install Chrome	Headless	Extra
Ubuntu / Debian	add Google's apt repo, then `apt install google-chrome-stable` (snippet above)	`HEADLESS=true` works; headful Tier-3 needs Xvfb	`apt install xvfb` + the lib list (the installer does this)
macOS	`brew install --cask google-chrome`	headful, no Xvfb	—
Windows	`winget install Google.Chrome`	headful (`HEADLESS=false`)	no Xvfb/apt needed

From source (contributors)

git clone https://github.com/runagent-dev/runagent-superbrowser.git
cd runagent-superbrowser
npm install && npm run build            # TS engine
cp .env.example .env                    # then edit the keys you care about
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt         # Python bridge (pinned dev lockfile)
patchright install chromium
playwright install-deps chromium        # Linux only
npm start                               # engine on :3100 — no API key needed

Prefer uv? Skip the venv + pip install -r steps — uv sync builds the env from uv.lock and uv run runs anything in it:

uv sync --all-extras                    # base + puzzles + remote (runagent) + dev
uv run patchright install chromium
uv run pytest nanobot/superbrowser_bridge/tests   # the offline suite

See CONTRIBUTING.md for the dev + release workflow.

Examples

Screenshot anything.

curl -X POST http://localhost:3100/screenshot \
  -d '{"url": "https://example.com"}' \
  -H "Content-Type: application/json" --output shot.jpg

Drive a session from any language.

import httpx
r = httpx.post("http://localhost:3100/session/create", json={"url": "https://news.ycombinator.com"})
sid = r.json()["sessionId"]
httpx.post(f"http://localhost:3100/session/{sid}/click", json={"index": 1})

Write a Puppeteer script on the live page.

httpx.post(f"http://localhost:3100/session/{sid}/script", json={
    "code": "await page.type('#q', 'agents'); await page.click('#search'); return page.title();"
})

Let the autonomous agent do it.

curl -X POST http://localhost:3100/task \
  -d '{"task": "find trending Python repos this week on GitHub"}' \
  -H "Content-Type: application/json"

Tasks that actually work:

await bot.run("book a 3-day stay in Khulna on gozayaan.com, check-in April 23, 1 adult, under $40/night")
await bot.run("find the cheapest flight DAC → SIN on March 5, one-way, list top 3 airlines")
await bot.run("get the IRA contribution limit for someone 45yo earning $120k from the Chase calculator")
await bot.run("compare the iPhone 16 Pro on amazon.com vs. apple.com — price, ship date, return policy")
await bot.run("download the latest 10-K filing for NVDA from the SEC EDGAR site")

When SuperBrowser hits a captcha it can't auto-solve, your phone buzzes with a link. Tap, swipe, done.

Configuration

LLM brain — one `.env`, every mode

The agent's brain needs a model + provider key. Either run nanobot onboard once, or put it in .env — the SDK bridges .env into nanobot's config for you, and the same keys work locally, in Docker, and on serverless:

LLM_MODEL=gpt-4o
OPENAI_API_KEY=sk-...        # or ANTHROPIC_API_KEY, or the LLM_PROVIDER/LLM_API_KEY contract

Precedence is "onboard wins, .env bootstraps": a .env only (re)writes nanobot's config when you set an explicit LLM_* var or haven't onboarded yet, so a stray exported key never clobbers a deliberate nanobot onboard. Details: docs/sdk.md → Configuration & .env.

Engine knobs

Zero config required. The knobs that matter most:

Variable	What it does
`T3_PERSIST_PROFILE=1`	Persistent per-domain Chrome profiles. Turn this on. First visit solves the captcha, every visit after looks like a returning user.
`HANDOFF_WEBHOOK_URL`	Fires when a human is needed. Point it at your WhatsApp / Slack / Telegram bridge.
`CAPTCHA_API_KEY` + `CAPTCHA_PROVIDER`	2captcha / anticaptcha / nopecha for Turnstile auto-solve.
`VISION_API_KEY` + `VISION_MODEL`	Cheap dedicated vision model. Keeps image tokens off your reasoning LLM bill.
`PROXY_POOL` + `PROXY_POOL_RESIDENTIAL`	Datacenter + residential pools. Hardened domains auto-promote to residential.
`TOKEN`	Bearer auth. Set this for anything not on localhost.
`SUPERBROWSER_TASK_ID`	Scope key for the cookie jar. Pass a stable ID for warm starts.

Full reference: .env.example. Deep dive on Tier-3 stealth + persistent profiles: STEALTH.md.

Where this is going

RunAgent Cloud — a managed serverless deployment with per-user persistent profiles surviving cold starts, controlled via chat apps. The pieces are already here; the cloud substrate is what's next.

License

MIT.

Navigation Menu

Uh oh!

SuperBrowser

Run it — SDK, Docker, or npm

1. Host engine + Python SDK — `npm run dev`

2. Docker all-in-one — `docker compose`

3. uv — no manual venv, reproducible from the lockfile

Or deploy to serverless

Python SDK

Pick how it browses — or let it decide

Typed results

The browser engine

Async + CLI

Drive it from a chat app

What it does

Install

Fastest — one-command bootstrap

From packages

Or Docker (all-in-one agent server)

Per-OS notes

From source (contributors)

Examples

Configuration

LLM brain — one `.env`, every mode

Engine knobs

Where this is going

License

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

SuperBrowser

Run it — SDK, Docker, or npm

1. Host engine + Python SDK — npm run dev

2. Docker all-in-one — docker compose

3. uv — no manual venv, reproducible from the lockfile

Or deploy to serverless

Python SDK

Pick how it browses — or let it decide

Typed results

The browser engine

Async + CLI

Drive it from a chat app

What it does

Install

Fastest — one-command bootstrap

From packages

Or Docker (all-in-one agent server)

Per-OS notes

From source (contributors)

Examples

Configuration

LLM brain — one .env, every mode

Engine knobs

Where this is going

License

1. Host engine + Python SDK — `npm run dev`

2. Docker all-in-one — `docker compose`

LLM brain — one `.env`, every mode