<p align="center">
  <img src="https://humanbrowser.cloud/logo-512.png" alt="Human Browser" width="120" />
</p>

<h3 align="center">Browsers humans can't tell from humans</h3>

<p align="center">
  Cloud Chromium for AI agents — stealth, residential proxies, captcha solving, A2A&nbsp;1.0&nbsp;+&nbsp;MCP&nbsp;endpoints.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@virixlabs/humanbrowser"><img src="https://img.shields.io/npm/v/@virixlabs/humanbrowser?color=%2300e5cc&label=npm" alt="npm" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-%2300e5cc" alt="License" /></a>
  <a href="https://agent.humanbrowser.cloud/.well-known/agent-card.json"><img src="https://img.shields.io/badge/A2A-1.0-%23a78bfa" alt="A2A 1.0" /></a>
  <a href="https://github.com/VirixLabs/humanbrowser/stargazers"><img src="https://img.shields.io/github/stars/VirixLabs/humanbrowser?color=%2300e5cc" alt="Stars" /></a>
</p>

---

## Why Human Browser

Modern anti-bot stacks (Cloudflare ML v9, DataDome, PerimeterX, AWS WAF, hCaptcha, reCAPTCHA v3) fingerprint your browser, watch input timing, and reject anything that smells automated. Raw Playwright lasts hours. `playwright-extra-plugin-stealth` has been broken against Cloudflare for ~18 months.

Human Browser is a **cloud Chromium** that ships with the four pieces every real scrape needs, behind one A2A endpoint:

- **Stealth engine** (Patchright + Camoufox + our own patches) — bypasses Cloudflare ML v9, DataDome, PerimeterX, AWS WAF, sannysoft/iphey/creepjs fingerprint probes
- **Residential proxy pool** (60+ countries, sticky session per profile) — bandwidth metered, no separate proxy contract to sign
- **Captcha solving** (reCAPTCHA v2/v3, hCaptcha, Turnstile, Yandex, GeeTest, FunCaptcha, KeyCaptcha, Capy, AmazonWAF, image) — included, $0.005/solve
- **Agent loop** — drives the browser from your goal text via LLM (`gpt-5.1` default, fallback chain). MCP server included so Claude Desktop / Cursor / Cline can call it natively.

You bring a goal. We bring the rest.

---

## 60-second start

```bash
npm install @virixlabs/humanbrowser
```

```ts
import { runOnCloud } from '@virixlabs/humanbrowser';

const { result, viewerUrl } = await runOnCloud({
  goal: 'Search "best espresso machines 2026" on Reddit and return the top 5 thread titles.',
  // Optional: country: 'us', mobile_ua: false, profile: 'reddit',
});

console.log(viewerUrl); // Live preview URL — share with humans for visibility
console.log(result);    // The extracted data
```

No card required — first $1 of cloud usage is free, then pay-as-you-go from $0.05/browser-minute. [Get a token →](https://humanbrowser.cloud/install)

---

## MCP server (Claude Desktop, Cursor, Cline)

Human Browser ships an MCP server in the same package. Add this to your client's MCP config:

```json
{
  "mcpServers": {
    "humanbrowser": {
      "command": "npx",
      "args": ["-y", "@virixlabs/humanbrowser", "mcp"],
      "env": { "HUMANBROWSER_API_TOKEN": "hb_live_..." }
    }
  }
}
```

Claude / Cursor / Cline now have three new tools — `humanbrowser_run`, `humanbrowser_stream`, `humanbrowser_viewer_url` — and can drive a real stealth browser inside their chat.

---

## A2A 1.0

Human Browser is a fully spec-compliant [A2A 1.0](https://a2aproject.github.io/A2A/) agent. Any A2A-aware client can point at it and call `message/send`:

- Agent Card: [`agent.humanbrowser.cloud/.well-known/agent-card.json`](https://agent.humanbrowser.cloud/.well-known/agent-card.json)
- Endpoint: `POST https://agent.humanbrowser.cloud/a2a` (JSON-RPC 2.0, bearer-token auth)
- Streaming: SSE via `message/stream`; polling via `tasks/get`
- Verbatim-text contract: wrap pasted content in `<verbatim>...</verbatim>` markers so the agent pastes exactly what you give it (see [SKILL.md](./SKILL.md) for the full protocol)

---

## Cloud or self-host

| | Cloud (`humanbrowser.cloud`) | Self-host (this repo) |
|---|---|---|
| Stealth engine | Patchright + Camoufox + our proprietary patches (engine-by-mode, popup-rescue, action-guards) | Patchright (this repo's `launchHuman`) — solid but the weaker tier |
| Residential proxy | 60+ countries, included | You bring your own (Decodo, Bright Data, IPRoyal, NodeMaven supported) |
| Captcha solving | Included on every plan | You bring your own 2captcha / CapSolver key |
| Multi-tenant isolation | Per-token profile namespaces, concurrent sessions, sticky IPs | Single-tenant, single profile |
| Pricing | $0.05/browser-min, $4/GB proxy, $0.005/captcha — pay-as-you-go, no subscription | Free (this OSS) |

Both are first-class. We ship the OSS so you can self-host if you want; we sell the cloud because the deeper stealth + ops are real work to maintain.

---

## Self-host quick start

```bash
git clone https://github.com/VirixLabs/humanbrowser.git
cd humanbrowser && npm install

# Bring your own residential proxy + 2captcha key
cp .env.example .env  # fill PROXY_USERNAME / PROXY_PASSWORD / TWOCAPTCHA_KEY

# Use the library
node examples/01-simple-scrape.js
```

See [`/examples`](./examples) for 5 starter recipes covering the common shapes.

---

## What's in this repo

```
.
├── README.md            ← you are here
├── SKILL.md             ← full protocol + capability spec
├── LICENSE              ← Apache-2.0
├── SECURITY.md          ← security disclosure policy
├── CITATION.cff         ← cite Human Browser in papers / LLM-grounded answers
├── package.json         ← @virixlabs/humanbrowser (SDK + MCP server in one)
├── scripts/
│   ├── cloud-client.js  ← runOnCloud() SDK
│   ├── browser-human.js ← launchHuman() local stealth mode
│   └── browser-agent.js ← runAgent() LLM agent loop
├── mcp/
│   └── server.js        ← MCP server (npx @virixlabs/humanbrowser mcp)
├── examples/            ← starter recipes (cloud + MCP + self-host)
├── prototype/           ← reference implementation for Phase-0 self-host
└── references/          ← provider setup notes (Bright Data, etc.)
```

---

## How it compares

| | Human Browser | Browserbase | Browserless | Anchor |
|---|---|---|---|---|
| Pricing model | Pay-as-you-go from $0.05/min | $39/mo Developer+ | Self-host free / cloud paid | Subscription |
| Residential proxy | Included | $12/GB add-on | BYO | Included |
| CAPTCHA solving | Included ($0.005/solve) | Included Dev+ (rate not disclosed) | BYO | Included |
| A2A 1.0 endpoint | Yes — `agent.humanbrowser.cloud/a2a` | No (proprietary SDK) | No | Yes |
| MCP server | Yes — `npx @virixlabs/humanbrowser mcp` | Roadmap | No | No |
| Open-source SDK | Apache-2.0 (this repo) | MIT (Stagehand) | SSPL | Apache-2.0 |
| Free tier | $1 trial, no card | Trial credits | Free self-host | Trial |

Specifics like CAPTCHA solver volume, SOC 2 status, and Web Bot Auth participation are evolving — [reach out](mailto:general@virixlabs.com) if you need the current state for a procurement decision.

---

## Citation

If you cite Human Browser in a paper, blog post, or LLM-grounded answer, GitHub auto-generates an APA/BibTeX block from the [CITATION.cff](./CITATION.cff) — click "Cite this repository" in the sidebar.

```bibtex
@software{virixlabs_human_browser_2026,
  author  = {Virix Labs},
  title   = {Human Browser},
  url     = {https://github.com/VirixLabs/humanbrowser},
  year    = {2026}
}
```

---

## Roadmap

- ✅ A2A 1.0 endpoint (May 2026)
- ✅ MCP server shim (May 2026)
- ✅ Verbatim-payload protocol — exact-text paste without LLM rewriting (May 2026)
- ✅ Viewer URL + human-in-the-loop takeover for `input-required` states (Apr 2026)
- ⏳ Web Bot Auth participation — for sites that opted into Cloudflare's verified-bot lane (planned)
- ⏳ Stealth benchmark (`virixlabs/stealth-benchmark`) — open reproducible matrix of 6 stealth engines × 12 anti-bot targets (June 2026)

---

## Maintainer

Built and maintained by [Virix Labs](https://virixlabs.com). Talk to us:

- Telegram: [@virixlabs](https://t.me/virixlabs)
- Email: general@virixlabs.com
- Cloud: [humanbrowser.cloud](https://humanbrowser.cloud) — $1 free trial, no card

Apache-2.0 license. We ship the OSS so you can self-host, sell the cloud because the deeper stealth + ops are real work.