Why Human Browser

Real web work for AI agents needs four things at once: a browser whose fingerprint reads as a normal Chromium build, a clean residential connection, observable human-in-the-loop fallback when a challenge needs a real person, and an agent loop that translates plain-English goals into clicks and text. Plain Playwright on a datacenter IP gives you one. Existing scraping stacks bundle two. We ship all four behind one endpoint.

Human Browser is a cloud Chromium purpose-built for legitimate, user-authorized web tasks — research, monitoring, form-fill on services you own, gathering public data — driven by an AI agent and observed by you in real time:

• Real Chromium fingerprint (Patchright + Camoufox engine layer) — runs like a normal Chrome build, not like a headless test harness
• Residential connection pool (60+ countries, sticky session per profile) — bandwidth metered, no separate proxy contract to sign
• Live viewer + human takeover — every session emits a viewer URL the user can open to watch live and click take over whenever a login, 2FA, or judgment call appears
• 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
• Captcha handling — when a site presents a CAPTCHA challenge, the human-in-the-loop takeover lets a real person complete it via the viewer URL ($0.005/solve assisted, included)

You bring a goal. We bring the rest.

60-second start

npm install @virixlabs/humanbrowser

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 →

MCP server (Claude Desktop, Cursor, Cline)

Human Browser exposes three MCP tools — humanbrowser_run, humanbrowser_status, humanbrowser_viewer_url — so Claude / Cursor / Cline can drive a real cloud browser from inside their chat. Two ways to connect:

Remote (recommended, zero install). Point your client at our hosted MCP endpoint. Same hb_live_* Bearer token as the A2A endpoint — one credential, two protocols.

{
  "mcpServers": {
    "humanbrowser": {
      "url": "https://agent.humanbrowser.cloud/mcp",
      "headers": { "Authorization": "Bearer hb_live_..." }
    }
  }
}

For Claude Desktop, wrap with mcp-remote until native HTTP transport ships:

{
  "mcpServers": {
    "humanbrowser": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://agent.humanbrowser.cloud/mcp", "--header", "Authorization: Bearer hb_live_..."]
    }
  }
}

Local stdio (no remote dependency). Run the MCP server in-process via npx:

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

Both modes call the same cloud backend and bill the same hb_live_* token. Pick remote for the lowest-friction setup, stdio if you want full local control over the MCP process.

HB_TOKEN vs HUMANBROWSER_API_TOKEN — as of 5.0.2 HB_TOKEN is the canonical env name. The longer HUMANBROWSER_API_TOKEN is still accepted as a fallback so existing setups don't break. Pick whichever fits your stack. Run npx @virixlabs/humanbrowser doctor to verify which one the SDK picked up + ping the agent endpoint.

Verify your setup

HB_TOKEN=hb_live_... npx @virixlabs/humanbrowser doctor

Prints which env var resolved, masks the token, and pings /.well-known/agent-card.json — no billed calls. Useful as a first check before wiring the SDK into a real workflow.

What runOnCloud returns (the shape that surprised our testers)

{
  text:       'final natural-language answer from the agent',
  viewerUrl:  'https://humanbrowser.cloud/a/s_<id>?k=<key>',  // live, watchable
  state:      'completed' | 'input-required' | 'failed' | 'canceled',
  taskId:     '<id>',
  artifacts:  [ { name, parts: [...] } ],
  metadata:   { profile, viewer_url, ... }
}

This is an A2A task result, not a Playwright DOM snapshot. If you need raw page state (HTML, screenshots, the rendered DOM tree), look in artifacts — the server attaches them on completion. If you're porting a Playwright pipeline and expected a page handle, you want the local launchHuman() path instead.

A2A 1.0

Human Browser is a fully spec-compliant A2A 1.0 agent. Any A2A-aware client can point at it and call message/send:

• Agent Card: 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 for the full protocol)

Cloud or self-host

| | Cloud (humanbrowser.cloud) | Self-host (this repo) | |---|---|---| | Engine layer | 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 engineering + ops are real work to maintain.

Self-host quick start

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 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 fingerprint 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 — remote agent.humanbrowser.cloud/mcp + stdio 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 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 — click "Cite this repository" in the sidebar.

@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 — stdio + remote HTTP (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)
• ⏳ Engine benchmark (virixlabs/stealth-benchmark) — open reproducible matrix of 6 Chromium-engine configs × 12 challenging-site environments (June 2026)

Maintainer

Built and maintained by Virix Labs. Talk to us:

• Telegram: @virixlabs
• Email: [email protected]
• Cloud: 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 engineering + ops are real work.