# Browserless Documentation
> Guides, references, and examples for Browserless
---
# Vercel Agent Browser Integration
URL: https://docs.browserless.io/ai-integrations/agent-browser
# Vercel Agent Browser Integration
[Agent Browser](https://github.com/vercel-labs/agent-browser) is a headless browser automation CLI for AI agents, built with a fast Rust CLI and Node.js fallback. By connecting agent-browser to Browserless, you get cloud-hosted browsers without managing Chrome infrastructure yourself, complete with stealth mode, residential proxies, and enterprise-grade reliability.
- Node.js 18 or later
- agent-browser installed globally or as a project dependency
- Browserless API token (available in your [account dashboard](https://browserless.io/account/))
## Step-by-Step Setup
Go to your Browserless account dashboard and copy your API token.
Then set your environment variable:
**.env file:**
```text
BROWSERLESS_API_KEY=your-api-token
```
**Command line:**
```bash
export BROWSERLESS_API_KEY="your-api-token"
```
**Global (recommended):**
```bash
npm install -g agent-browser
```
**npx (no install):**
```bash
npx agent-browser open https://example.com
```
**Project dependency:**
```bash
npm install agent-browser
```
Use the -p browserless flag to route all browser commands through Browserless:
```bash
export BROWSERLESS_API_KEY="your-api-token"
agent-browser -p browserless open https://example.com
```
Or use environment variables for CI/scripts:
```bash
export AGENT_BROWSER_PROVIDER=browserless
export BROWSERLESS_API_KEY="your-api-token"
agent-browser open https://example.com
```
When enabled, agent-browser connects to a Browserless cloud session instead of launching a local browser. All commands work identically.
Use agent-browser's CLI commands with the Browserless-powered browser:
```bash
# Navigate and take a snapshot
agent-browser -p browserless open https://www.browserless.io
agent-browser snapshot
# Interact using refs from the snapshot
agent-browser click @e2
agent-browser fill @e3 "test@example.com"
# Get text content and screenshots
agent-browser get text @e1
agent-browser screenshot page.png
# Clean up
agent-browser close
```
## Optional Configuration
Configure Browserless behavior via environment variables:
| Variable | Description | Default |
|---|---|---|
| `BROWSERLESS_API_URL` | Base API URL (for custom regions or self-hosted) | `https://production-sfo.browserless.io` |
| `BROWSERLESS_BROWSER_TYPE` | Type of browser to use (chromium or chrome) | `chromium` |
| `BROWSERLESS_TTL` | Session TTL in milliseconds | `300000` |
| `BROWSERLESS_STEALTH` | Enable stealth mode (`true` / `false`) | `true` |
### Regional endpoints
Pick the region closest to you for lower latency:
| Region | `BROWSERLESS_API_URL` value |
|---|---|
| US West (San Francisco) | `https://production-sfo.browserless.io` |
| Europe (London) | `https://production-lon.browserless.io` |
| Europe (Amsterdam) | `https://production-ams.browserless.io` |
## Usage with AI Agents
agent-browser is designed for AI coding assistants and autonomous agents. Add it to your agent's instructions:
```text
Use agent-browser to browse the web. Run agent-browser --help for all commands.
Core workflow:
1. agent-browser -p browserless open
2. agent-browser snapshot -i (get interactive elements with refs @e1, @e2)
3. agent-browser click @e1 / fill @e2 "text" (interact using refs)
4. Re-snapshot after page changes
```
For richer context in AI coding assistants (Claude Code, Cursor, Codex, etc.):
```bash
npx skills add vercel-labs/agent-browser
```
## Why use Browserless with agent-browser
- **Stealth mode**: bypass bot detection with stealth enabled by default
- **Residential proxies**: route traffic through real residential IPs to avoid blocks
- **Global regions**: choose from US West (San Francisco), Europe (London), or Europe (Amsterdam) endpoints for lower latency
- **No infrastructure**: skip managing Chrome installations, updates, or scaling
- **Parallel sessions**: run multiple browser sessions simultaneously
- **Enterprise reliability**: 99.9% uptime SLA with automatic failover
## Resources
- [Agent Browser Documentation](https://agent-browser.dev)
- [Agent Browser GitHub Repository](https://github.com/vercel-labs/agent-browser)
- [Browserless Connection Options](/overview/connection-urls)
- [Stealth Mode](/baas/bot-detection/stealth)
- [Proxy Configuration](/baas/bot-detection/proxies)
## FAQ & Troubleshooting
How do I connect agent-browser to Browserless?
Pass the `-p browserless` flag (or set `AGENT_BROWSER_PROVIDER=browserless`) along with your `BROWSERLESS_API_KEY` environment variable, as shown in step 3 above. agent-browser then routes all commands through a Browserless cloud session instead of a local browser.
agent-browser is still getting blocked by bot detection
Stealth mode is enabled by default (`BROWSERLESS_STEALTH=true`). If a site still blocks you, add a [residential proxy](/baas/bot-detection/proxies) to your Browserless connection.
## Next steps
all supported AI frameworks and tools
---
# AgentKit Integration
URL: https://docs.browserless.io/ai-integrations/agentkit
# AgentKit Integration
[AgentKit](https://agentkit.inngest.com/) is a TypeScript framework by Inngest for building fault-tolerant AI agents with tools, state, and multi-agent networks. By connecting AgentKit to Browserless, your agents can browse the web with stealth capabilities, CAPTCHA solving, and residential proxies without managing browser infrastructure.
- Node.js 18 or higher
- Browserless API token (available in your [account dashboard](https://browserless.io/account/))
- An LLM API key (Anthropic, OpenAI, etc.), required for the agent to reason and call tools
## Step-by-Step Setup
Go to your Browserless account dashboard and copy your API token.
Then set your environment variables:
**.env file:**
```text
BROWSERLESS_API_KEY=your-browserless-token
ANTHROPIC_API_KEY=your-anthropic-key
```
**Command line:**
```bash
export BROWSERLESS_API_KEY=your-browserless-token
export ANTHROPIC_API_KEY=your-anthropic-key
```
AgentKit requires inngest as a peer dependency. Install both alongside Playwright and Zod:
**npm:**
```bash
npm install @inngest/agent-kit inngest playwright-core zod
```
**yarn:**
```bash
yarn add @inngest/agent-kit inngest playwright-core zod
```
**pnpm:**
```bash
pnpm add @inngest/agent-kit inngest playwright-core zod
```
Create a file called index.ts. Start by defining a tool that connects to Browserless using Playwright's connectOverCDP method:
```typescript
import { createTool } from "@inngest/agent-kit";
import { z } from "zod";
import { chromium } from "playwright-core";
const scrapeHackerNews = createTool({
name: "scrape_hackernews",
description: "Get the top stories from Hacker News",
parameters: z.object({
limit: z.number().describe("Number of stories to fetch").default(5),
}),
handler: async ({ limit }, { step }) => {
const scrape = async () => {
const browser = await chromium.connectOverCDP(
`wss://production-sfo.browserless.io?token=${process.env.BROWSERLESS_API_KEY}`
);
try {
const page = await browser.newPage();
await page.goto("https://news.ycombinator.com");
const stories = await page.evaluate((limit) => {
const items = document.querySelectorAll(".athing");
return Array.from(items)
.slice(0, limit)
.map((item) => {
const titleEl = item.querySelector(".titleline > a");
const subtext = item.nextElementSibling;
const scoreEl = subtext?.querySelector(".score");
return {
title: titleEl?.textContent,
url: titleEl?.getAttribute("href"),
points: scoreEl?.textContent || "0 points",
};
});
}, limit);
return stories;
} finally {
await browser.close();
}
};
return await step?.run("scrape-hn", scrape) ?? await scrape();
},
});
```
When running inside an Inngest function, step.run() ensures the operation only executes once, even if the agent retries. The ?? await scrape() fallback lets the same tool work in standalone mode without Inngest.
Add the agent and network definitions to the same file. Pass the tool directly to the agent's tools array:
```typescript
import {
anthropic,
createAgent,
createNetwork,
} from "@inngest/agent-kit";
const newsAgent = createAgent({
name: "hackernews_agent",
description: "Fetches and summarizes Hacker News stories",
system: "You fetch top stories from Hacker News and provide summaries.",
tools: [scrapeHackerNews],
});
const network = createNetwork({
name: "news_network",
agents: [newsAgent],
maxIter: 3,
defaultModel: anthropic({
model: "claude-sonnet-4-20250514",
defaultParameters: {
max_tokens: 4096,
},
}),
});
```
Add the following to the same file to run the network with a prompt:
```typescript
const result = await network.run(
"Get the top 5 stories from Hacker News and summarize them"
);
console.log(result);
```
Run the script:
```bash
npx tsx ./index.ts
```
You should see the agent fetch and summarize the top Hacker News stories.
## How It Works
1. **Connection**: Playwright connects to Browserless via WebSocket using `connectOverCDP`
2. **Tool execution**: The agent calls your tool, which runs browser operations through Browserless
3. **Cleanup**: The browser closes in a `finally` block to prevent session leaks
## Advanced Configuration
### Stealth mode
For sites with bot detection, use a [stealth route](/baas/bot-detection/stealth):
```typescript
const browser = await chromium.connectOverCDP(
`wss://production-sfo.browserless.io/stealth?token=${process.env.BROWSERLESS_API_KEY}`
);
```
### Residential proxies
Route traffic through residential IPs for geo-targeting and rate-limit avoidance:
```typescript
const browser = await chromium.connectOverCDP(
`wss://production-sfo.browserless.io?token=${process.env.BROWSERLESS_API_KEY}&proxy=residential&proxyCountry=us`
);
```
### Regional endpoints
Pick the region closest to your users or target sites:
| Region | Endpoint |
|---|---|
| US West (San Francisco) | `wss://production-sfo.browserless.io` |
| Europe (London) | `wss://production-lon.browserless.io` |
| Europe (Amsterdam) | `wss://production-ams.browserless.io` |
## Resources
- [AgentKit documentation](https://agentkit.inngest.com/)
- [Browserless connection options](/overview/connection-urls)
- [Stealth routes](/baas/bot-detection/stealth)
- [Proxy configuration](/baas/bot-detection/proxies)
## FAQ & Troubleshooting
How does an AgentKit tool connect to Browserless?
Use Playwright's `connectOverCDP` method inside your tool's `handler`, pointing at your Browserless WebSocket URL with your token, as shown in step 3 above.
My tool's browsing gets blocked by bot detection
Switch to the [stealth route](/baas/bot-detection/stealth) (`wss://production-sfo.browserless.io/stealth?token=...`) and add a residential proxy, as shown in [Advanced Configuration](#advanced-configuration) above.
Why does the tool call browser.close() in a finally block?
Browserless sessions consume units for as long as they're open. Closing in `finally` guarantees cleanup even if the tool throws, preventing leaked sessions from running until they time out.
## Next steps
all supported AI frameworks and tools
---
# Anthropic SDK
URL: https://docs.browserless.io/ai-integrations/anthropic
# Anthropic SDK
Anthropic exposes two paths for putting Claude behind a Browserless-powered agent loop:
- **Direct integration** with the [Messages API MCP connector](https://docs.claude.com/en/docs/agents-and-tools/mcp-connector). One `messages.create` call, MCP server as a single `mcp_servers` entry. Lightest possible shape.
- **Managed integration** with [Managed Agents (beta)](https://docs.claude.com/en/docs/agents-and-tools/managed-agents/overview). A persistent `Environment`, a named `Agent`, and `Session` + `events` streams. Better when you need long-lived sessions or server-stored history.
Both routes call the same hosted MCP server, though the Messages API uses `/mcp` while Managed Agents requires the legacy `/sse` endpoint. This page builds the same example using both integration paths: a `GET /hn` endpoint that returns the top 10 Hacker News stories as JSON.
- Browserless API token (available in your [account dashboard](https://browserless.io/account/))
- An [Anthropic API key](https://console.anthropic.com/settings/keys)
- Node.js 20.6 or later (for the built-in `--env-file` flag)
## Setting environment variables
**.env file:**
```bash
ANTHROPIC_API_KEY=your-anthropic-key
BROWSERLESS_API_KEY=your-browserless-token
PORT=3000
```
**Command line:**
```bash
export ANTHROPIC_API_KEY=your-anthropic-key
export BROWSERLESS_API_KEY=your-browserless-token
export PORT=3000
```
## Direct integration: Messages API MCP connector
The Messages API accepts hosted MCP servers via the `mcp_servers` parameter (beta). Anthropic's API server makes the MCP calls on Claude's behalf and returns the final answer in one request.
### Install
```bash
npm init -y
npm install @anthropic-ai/sdk express
```
### `server.js`
```js
const PORT = process.env.PORT ?? 3000;
const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY || "";
const BROWSERLESS_API_KEY = process.env.BROWSERLESS_API_KEY || "";
const INSTRUCTIONS =
"You are a news scraper. Use the browserless tools to load the Hacker News front page and return the top 10 stories as a JSON array. Each item must have the shape { rank, title, url, points }. Reply with ONLY the JSON array — no markdown fences, no commentary.";
const app = express();
const client = new Anthropic({ apiKey: ANTHROPIC_API_KEY });
app.get("/hn", async (_req, res) => {
const message = await client.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
system: INSTRUCTIONS,
mcp_servers: [
{
type: "url",
name: "browserless",
url: "https://mcp.browserless.io/mcp",
authorization_token: BROWSERLESS_API_KEY,
},
],
messages: [
{
role: "user",
content: "Fetch the top 10 stories from https://news.ycombinator.com",
},
],
betas: ["mcp-client-2025-04-04"],
});
const text = message.content
.filter((block) => block.type === "text")
.map((block) => block.text)
.join("");
res.type("application/json").send(text);
});
app.listen(PORT, () => {
console.log(`Listening on http://localhost:${PORT}`);
});
```
Add `"type": "module"` to your `package.json` so the `import` statements work.
### Run it
```bash
node --env-file=.env server.js
```
```bash
curl http://localhost:3000/hn
# → [
# { "rank": 1, "title": "Show HN: …", "url": "https://…", "points": 412 },
# …
# ]
```
### How it works
1. Express receives `GET /hn`.
2. The server calls `client.beta.messages.create` with the `mcp_servers` array pointing at `https://mcp.browserless.io/mcp`, authenticated via `authorization_token`.
3. Anthropic's API fetches the MCP tool list, Claude picks the right Browserless tool (typically [`browserless_smartscraper`](/mcp/rest-api-tools#browserless_smartscraper)), and Anthropic executes the call server-side against `https://news.ycombinator.com`.
4. The scraped page comes back to Claude, which extracts the top 10 stories into the JSON shape requested by `system`.
5. The model's final response is returned as content blocks. We concatenate the `text` blocks and pipe them straight to the HTTP response.
### Multi-turn state
The Messages API is stateless — to maintain a conversation, append the assistant turn back into `messages` and send the next user turn:
```js
const turns = [
{ role: "user", content: "Fetch the top 10 stories from https://news.ycombinator.com" },
];
const first = await client.beta.messages.create({ /* …, messages: turns */ });
turns.push({ role: "assistant", content: first.content });
turns.push({ role: "user", content: "Now sort them by points." });
const second = await client.beta.messages.create({ /* …, messages: turns */ });
```
Persist `turns` in your own store (Redis, Postgres) keyed by user or session. Unlike OpenAI's `previous_response_id`, Anthropic does not retain conversation state server-side on this path — you own it.
## Managed integration: Managed Agents
[Managed Agents](https://docs.claude.com/en/docs/agents-and-tools/managed-agents/overview) move the entire agent — system prompt, tools, and MCP server bindings — onto Anthropic's infrastructure. You bootstrap a named `Agent` once, then open `Session`s against it and stream events. Server-side state and a richer event stream are the payoff.
Reach for this when you need long-lived sessions across many turns, server-stored history, or a centrally-versioned agent definition.
### Bootstrap (run once)
This script creates the Environment and the Agent. Save the resulting IDs into `.env`.
```js
// bootstrap-agent.js
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const BROWSERLESS_API_KEY = process.env.BROWSERLESS_API_KEY;
const MCP_URL = `https://mcp.browserless.io/sse?token=${BROWSERLESS_API_KEY}`;
const MA_BETA = "managed-agents-2026-04-01";
const INSTRUCTIONS =
"You are a news scraper. Use the browserless tools to load the Hacker News front page and return the top 10 stories as a JSON array. Each item must have the shape { rank, title, url, points }. Reply with ONLY the JSON array — no markdown fences, no commentary.";
const environment = await client.beta.environments.create({
name: "browserless-hn-env",
config: { type: "cloud", networking: { type: "unrestricted" } },
}, { betas: [MA_BETA] });
const agent = await client.beta.agents.create({
name: "browserless-hn",
model: "claude-opus-4-7",
system: INSTRUCTIONS,
mcp_servers: [{ name: "browserless", type: "url", url: MCP_URL }],
tools: [
{
type: "mcp_toolset",
mcp_server_name: "browserless",
default_config: {
enabled: true,
permission_policy: { type: "always_allow" },
},
},
],
}, { betas: [MA_BETA] });
console.log(`MANAGED_AGENTS_ENVIRONMENT_ID=${environment.id}`);
console.log(`MANAGED_AGENTS_AGENT_ID=${agent.id}`);
console.log(`MANAGED_AGENTS_AGENT_VERSION=1`);
```
Run once and paste the output into your `.env`:
```bash
node --env-file=.env bootstrap-agent.js
```
> **The Browserless token is baked into the Agent's MCP URL**
> The agent definition stores the token as part of `mcp_servers[0].url`. To rotate the token, create a new agent version via `client.beta.agents.update(...)` with the new URL. For production deployments where the token must never appear in any stored config, Anthropic's [Vault credentials](https://docs.claude.com/en/docs/agents-and-tools/managed-agents/credentials) are the right tool — but get this recipe working first.
### `server.js`
The per-request handler opens a session against the bootstrapped agent, sends a user-message event, and consumes the event stream until the agent stops.
```js
const PORT = process.env.PORT ?? 3000;
const MA_BETA = "managed-agents-2026-04-01";
const app = express();
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
app.get("/hn", async (_req, res) => {
const session = await client.beta.sessions.create({
agent: {
type: "agent",
id: process.env.MANAGED_AGENTS_AGENT_ID,
version: Number(process.env.MANAGED_AGENTS_AGENT_VERSION),
},
environment_id: process.env.MANAGED_AGENTS_ENVIRONMENT_ID,
betas: [MA_BETA],
});
// Open the stream BEFORE sending the message — avoids a race per MA docs.
const events = await client.beta.sessions.events.stream(session.id, { betas: [MA_BETA] });
await client.beta.sessions.events.send(session.id, {
events: [{
type: "user.message",
content: [{ type: "text", text: "Fetch the top 10 stories from https://news.ycombinator.com" }],
}],
betas: [MA_BETA],
});
let finalText = "";
for await (const event of events) {
if (event.type === "agent.message") {
for (const block of event.content) {
if (block.type === "text") finalText += block.text;
}
}
if (event.type === "session.status_idle") break;
if (event.type === "session.status_terminated") {
res.status(500).type("text/plain").send("session terminated");
return;
}
}
res.type("application/json").send(finalText);
});
app.listen(PORT, () => {
console.log(`Listening on http://localhost:${PORT}`);
});
```
### What you get over the Messages API path
- **Server-side session state.** Conversation history, tool-call history, and intermediate state live on Anthropic's side. You only hold `session.id`.
- **Versioned agents.** The system prompt, tools, and MCP server bindings are part of a named `Agent` you can roll back or A/B by `version`.
- **Richer event stream.** You see tool calls, results, and partial deltas as discrete events instead of one final blob.
Trade-off: more moving pieces, a bootstrap step, and the MA-specific `/sse` workaround called out below.
## Stealth, CAPTCHAs, and regional endpoints
Both paths route through the same Browserless infrastructure, so [stealth mode](/baas/bot-detection/stealth), [automatic CAPTCHA solving](/baas/bot-detection/captchas), and [residential proxies](/baas/bot-detection/proxies) all apply.
The Messages API `mcp_servers` entry and the Managed Agents `mcp_servers` entry both accept the regional pin via URL query parameter, since neither lets you set arbitrary headers on the MCP request:
```bash
https://mcp.browserless.io/mcp?browserlessUrl=https://production-lon.browserless.io
```
For Managed Agents, swap `/mcp` for `/sse` (see [FAQ & Troubleshooting](#faq--troubleshooting) below). See the [MCP setup page](/mcp/browserless-mcp-server/setup) for the full list of configuration options.
## Resources
- [Anthropic Messages API — MCP connector](https://docs.claude.com/en/docs/agents-and-tools/mcp-connector)
- [Anthropic Managed Agents overview](https://docs.claude.com/en/docs/agents-and-tools/managed-agents/overview)
- [Claude Agent SDK page](/ai-integrations/claude-agent-sdk) – a third option using Playwright over CDP instead of the hosted MCP server
- [Browserless MCP setup](/mcp/browserless-mcp-server/setup)
- [REST API tools](/mcp/rest-api-tools)
- [Browser agent](/mcp/browser-agent)
- [Connection URLs](/overview/connection-urls)
## FAQ & Troubleshooting
Messages API: "Unknown parameter: mcp_servers" or 400
The MCP connector is still in beta. Use `client.beta.messages.create` (not `client.messages.create`) and include `betas: ["mcp-client-2025-04-04"]` on the request. Without that opt-in, the parameter is rejected.
Managed Agents: MCP init fails with "SSE data line is not valid JSON"
Managed Agents' MCP client does not currently complete the Streamable HTTP handshake at `https://mcp.browserless.io/mcp`. Use the legacy SSE endpoint instead (`https://mcp.browserless.io/sse`). This is the opposite of the Messages API path, which must use `/mcp`. If you copy snippets between the two integrations, double-check the URL.
Empty response text
Both paths return content blocks rather than a single string field. For the Messages API, filter `message.content` for `block.type === "text"`. For Managed Agents, accumulate text from `agent.message` events (each carries a `content` array of `{ text }` blocks) and stop the loop on `session.status_idle` or `session.status_terminated`.
max_tokens truncates the JSON
`max_tokens` caps the model's final output on the Messages API. If you ask for 10 stories with rich fields and hit a truncated array, raise it. 4096 is usually plenty for this recipe; Managed Agents handles this via the agent definition rather than per-request.
mcp_servers "disappear" between calls (Messages API)
The Messages API does not persist MCP server configuration server-side. Re-send the full `mcp_servers` array on every `messages.create` call, even in a multi-turn conversation. The Managed Agents path stores the binding on the `Agent` resource, so you set it once at bootstrap.
## Next steps
use BrowserQL for advanced browser automation
---
# Browser Use Integration
URL: https://docs.browserless.io/ai-integrations/browser-use/python
# Browser Use Integration
[Browser Use](https://github.com/browser-use/browser-use) is a Python library that allows AI agents to control a browser. By integrating Browserless with Browser Use, you can give your AI applications web browsing capabilities without managing browser infrastructure.
- Python 3.11+
- Browserless API token (available in your [account dashboard](https://browserless.io/account/))
- An LLM provider API key (OpenAI used in this guide; get your key from [OpenAI's API keys page](https://platform.openai.com/api-keys))
### Tooling
- **Virtual environment**: `python -m venv` is the recommended, built-in way to create a virtual environment (no additional installation required).
- **Optional tools**:
- [uv](https://github.com/astral-sh/uv) - Fast Python package installer and resolver
- [conda](https://docs.conda.io/en/latest/miniconda.html) - Package and environment manager
## Step-by-Step Setup
You'll need three environment variables:
Note: While other LLM providers can be used, this guide uses OpenAI for the examples.
See the Environment Variables + .env file section below for detailed setup instructions.
Set up a Python virtual environment to manage your dependencies. The built-in venv module is recommended as it requires no additional installs:
**venv (recommended):**
**macOS/Linux:**
```bash
# Verify Python version (should be 3.11+)
python3 --version
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate
```
**Windows (CMD):**
```cmd
# Verify Python version (should be 3.11+)
py --version
# Create virtual environment
py -m venv .venv
.venv\Scripts\activate
```
**Optional: Using uv:**
If you have uv installed, you can use it as an alternative:
```bash
python -m venv .venv
source .venv/bin/activate # On Windows (CMD): .venv\Scripts\activate
```
After activation, install dependencies with uv pip install (see step 3).
**Optional: Using conda:**
If you have conda installed, you can use it as an alternative:
```bash
conda create -n browserless-env python=3.11
conda activate browserless-env
```
Note: The default path is venv + pip. uv and conda are optional alternatives.
Make sure your virtual environment is activated, then install the required packages:
**pip (default):**
**macOS/Linux:**
```bash
# Make sure your virtual environment is activated
source .venv/bin/activate
# Install required packages
pip install "browser-use>=0.12.0" python-dotenv openai
```
**Windows:**
```cmd
# Make sure your virtual environment is activated
.venv\Scripts\activate
# Install required packages
pip install "browser-use>=0.12.0" python-dotenv openai
```
**Optional: Using uv:**
If you're using uv (see step 2), install with:
```bash
# Make sure your virtual environment is activated
source .venv/bin/activate # macOS/Linux
# or
.venv\Scripts\activate # Windows CMD
# Install required packages
uv pip install browser-use python-dotenv openai
```
Note: The quickstart uses uv pip install, not uv add or uv init.
Create a .env file in your project directory with the following variables:
```env
BROWSERLESS_TOKEN=your_browserless_token_here
OPENAI_API_KEY=your_openai_key_here
BROWSERLESS_WS_URL=wss://production-sfo.browserless.io
```
Note: This guide uses BROWSERLESS_TOKEN to match the repository standard. Other scripts in this repository also use BROWSERLESS_TOKEN for consistency.
Important: Do not commit .env to version control. Add .env to your .gitignore file.
If you prefer to set environment variables directly (without a .env file):
**macOS/Linux:**
```bash
export BROWSERLESS_TOKEN=your_browserless_token_here
export OPENAI_API_KEY=your_openai_key_here
export BROWSERLESS_WS_URL=wss://production-sfo.browserless.io
```
**Windows (PowerShell):**
```powershell
$env:BROWSERLESS_TOKEN="your_browserless_token_here"
$env:OPENAI_API_KEY="your_openai_key_here"
$env:BROWSERLESS_WS_URL="wss://production-sfo.browserless.io"
```
**Windows (CMD):**
```cmd
set BROWSERLESS_TOKEN=your_browserless_token_here
set OPENAI_API_KEY=your_openai_key_here
set BROWSERLESS_WS_URL=wss://production-sfo.browserless.io
```
Note: The examples in this guide use python-dotenv to automatically load the .env file.
Create a new file named main.py with the following complete code:
```python
from browser_use import Agent, BrowserSession
from browser_use.llm import ChatOpenAI
from dotenv import load_dotenv
import os
import asyncio
# Load environment variables from .env file
load_dotenv()
async def main():
# Validate required environment variables
browserless_token = os.getenv('BROWSERLESS_TOKEN')
openai_key = os.getenv('OPENAI_API_KEY')
browserless_ws_url = os.getenv('BROWSERLESS_WS_URL', 'wss://production-sfo.browserless.io')
if not browserless_token:
raise RuntimeError("BROWSERLESS_TOKEN environment variable is required. Get your token from https://browserless.io/account/")
if not openai_key:
raise RuntimeError("OPENAI_API_KEY environment variable is required. Get your key from https://platform.openai.com/api-keys")
# Create browser session using BROWSERLESS_WS_URL
browser_session = BrowserSession(
cdp_url=f"{browserless_ws_url}?token={browserless_token}"
)
# Setup LLM
llm = ChatOpenAI(model="gpt-4o-mini", api_key=openai_key)
# Create and run agent with a simple task
agent = Agent(
task="Go to https://example.com and tell me the main heading on the page",
llm=llm,
browser_session=browser_session
)
result = await agent.run()
print(result)
if __name__ == "__main__":
asyncio.run(main())
```
Make sure your virtual environment is activated, then run your application:
**macOS/Linux:**
```bash
# Make sure your virtual environment is activated
source .venv/bin/activate
# Run your application
python main.py
```
**Windows:**
```cmd
# Make sure your virtual environment is activated
.venv\Scripts\activate
# Run your application
python main.py
```
You should see output indicating that the browser is initialized and the agent is running.
## How It Works
1. **Connection Setup**: Browser Use connects to Browserless using the WebSocket endpoint with your API token
2. **Agent Configuration**: The AI agent is configured with a task and a language model
3. **Automation**: The agent uses the browser to navigate and interact with websites
4. **LLM Integration**: The agent uses an LLM (like GPT-4o) to interpret web content and make decisions
## Complete Example with Cloud Browser
Here's a complete example that demonstrates the modern `BrowserSession` approach with proper environment variable handling:
```python
"""Simple browser-use + Browserless connection example"""
from browser_use import Agent
from browser_use.browser import BrowserSession
from browser_use.llm import ChatOpenAI
from dotenv import load_dotenv
# Load environment variables from .env file
load_dotenv()
async def main():
# Validate required environment variables
browserless_token = os.getenv('BROWSERLESS_TOKEN')
openai_key = os.getenv('OPENAI_API_KEY')
browserless_ws_url = os.getenv('BROWSERLESS_WS_URL', 'wss://production-sfo.browserless.io')
if not browserless_token:
raise RuntimeError("BROWSERLESS_TOKEN environment variable is required. Get your token from https://browserless.io/account/")
if not openai_key:
raise RuntimeError("OPENAI_API_KEY environment variable is required. Get your key from https://platform.openai.com/api-keys")
# Setup LLM
llm = ChatOpenAI(model="gpt-4o-mini", api_key=openai_key)
# Setup browser session using BROWSERLESS_WS_URL
url = f"{browserless_ws_url}?token={browserless_token}"
browser_session = BrowserSession(cdp_url=url)
print("🌐 Using cloud browser")
# Create and run agent
agent = Agent(
task="Go to https://example.com and tell me the main heading",
llm=llm,
browser_session=browser_session
)
result = await agent.run(max_steps=5)
print(f"✅ Done! Result: {type(result).__name__}")
if __name__ == "__main__":
asyncio.run(main())
```
## Advanced / Bot-Protected Sites
For sites with bot protection (like eBay), you may need additional configuration:
```python
from browser_use import Agent, BrowserSession
from browser_use.llm import ChatOpenAI
from dotenv import load_dotenv
load_dotenv()
async def main():
browserless_token = os.getenv('BROWSERLESS_TOKEN')
openai_key = os.getenv('OPENAI_API_KEY')
browserless_ws_url = os.getenv('BROWSERLESS_WS_URL', 'wss://production-sfo.browserless.io')
if not browserless_token:
raise RuntimeError("BROWSERLESS_TOKEN environment variable is required")
if not openai_key:
raise RuntimeError("OPENAI_API_KEY environment variable is required")
# Use stealth mode and residential proxy for bot-protected sites
browser_session = BrowserSession(
cdp_url=f"{browserless_ws_url}/chromium/stealth?token={browserless_token}&proxy=residential"
)
llm = ChatOpenAI(model="gpt-4o-mini", api_key=openai_key)
agent = Agent(
task="Find me the top cheapest trainer on ebay.co.uk",
llm=llm,
browser_session=browser_session
)
result = await agent.run()
print(result)
if __name__ == "__main__":
asyncio.run(main())
```
## Additional Configuration Options
### Using Different Browserless Regions
You can connect to different Browserless regions for better performance by setting `BROWSERLESS_WS_URL` in your `.env` file:
```env
# US West Coast (default)
BROWSERLESS_WS_URL=wss://production-sfo.browserless.io
# Europe (London)
BROWSERLESS_WS_URL=wss://production-lon.browserless.io
```
### Proxy Support
You can enable a residential proxy for improved website compatibility:
```python
browserless_ws_url = os.getenv('BROWSERLESS_WS_URL', 'wss://production-sfo.browserless.io')
browserless_token = os.getenv('BROWSERLESS_TOKEN')
browser_session = BrowserSession(
cdp_url=f"{browserless_ws_url}?token={browserless_token}&proxy=residential"
)
```
### Stealth Mode and Proxy Support
Enable stealth mode and residential proxies for better website compatibility. Stealth mode uses the `/chromium/stealth` path:
```python
browserless_ws_url = os.getenv('BROWSERLESS_WS_URL', 'wss://production-sfo.browserless.io')
browserless_token = os.getenv('BROWSERLESS_TOKEN')
browser_session = BrowserSession(
cdp_url=f"{browserless_ws_url}/chromium/stealth?token={browserless_token}&proxy=residential"
)
```
### Automatic CAPTCHA Solving
> **Requires browser-use 0.12.0+**
> The automatic CAPTCHA pause/resume feature requires **browser-use version 0.12.0 or later**, which includes the CaptchaWatchdog. Earlier versions don't have this. Upgrade with `pip install browser-use>=0.12.0`.
Enable automatic CAPTCHA solving so the agent pauses while CAPTCHAs are solved and resumes when done. This requires `solveCaptchas=true` to enable the captcha engine and `integrations=browseruse` to bridge the events to browser-use's watchdog:
```python
browserless_ws_url = os.getenv('BROWSERLESS_WS_URL', 'wss://production-sfo.browserless.io')
browserless_token = os.getenv('BROWSERLESS_TOKEN')
browser_session = BrowserSession(
cdp_url=f"{browserless_ws_url}/chromium?token={browserless_token}&solveCaptchas=true&integrations=browseruse"
)
```
When the agent navigates to a page with a CAPTCHA (reCAPTCHA, Cloudflare Turnstile, etc.), Browserless automatically detects and solves it. The agent pauses during solving and resumes once the CAPTCHA is resolved.
### Stealth + Proxy + CAPTCHA Solving
Combine all features for maximum compatibility with bot-protected sites:
```python
browserless_ws_url = os.getenv('BROWSERLESS_WS_URL', 'wss://production-sfo.browserless.io')
browserless_token = os.getenv('BROWSERLESS_TOKEN')
# Stealth mode + residential proxy + auto CAPTCHA solving
browser_session = BrowserSession(
cdp_url=(
f"{browserless_ws_url}/chromium/stealth?token={browserless_token}"
f"&proxy=residential&proxyCountry=US"
f"&solveCaptchas=true&integrations=browseruse"
)
)
llm = ChatOpenAI(model="gpt-4o-mini", api_key=os.getenv('OPENAI_API_KEY'))
agent = Agent(
task="Navigate to a protected site and extract data",
llm=llm,
browser_session=browser_session
)
result = await agent.run()
```
**Available query parameters:**
| Parameter | Description | Example |
|-----------|-------------|---------|
| `token` | Your API token (required) | `token=your_token` |
| `solveCaptchas` | Enable automatic CAPTCHA solving | `solveCaptchas=true` |
| `integrations` | Enable browser-use event bridge for CAPTCHA pause/resume | `integrations=browseruse` |
| `proxy` | Enable residential proxy | `proxy=residential` |
| `proxyCountry` | Proxy country (two-letter code) | `proxyCountry=US` |
| `proxyCity` | Proxy city | `proxyCity=New+York` |
| `proxyState` | Proxy state/region | `proxyState=CA` |
| `stealth` | Enable stealth mode (use `/chromium/stealth` path instead) | Path-based |
**Available stealth routes:**
| Route | Description |
|-------|-------------|
| `/chromium` | Standard Chromium (default) |
| `/chromium/stealth` | Chromium with anti-detection |
| `/chrome/stealth` | Chrome with anti-detection |
### Custom Browser Configuration
Configure browser settings using BrowserProfile:
```python
from browser_use.browser import BrowserProfile
browserless_ws_url = os.getenv('BROWSERLESS_WS_URL', 'wss://production-sfo.browserless.io')
browserless_token = os.getenv('BROWSERLESS_TOKEN')
browser_session = BrowserSession(
cdp_url=f"{browserless_ws_url}?token={browserless_token}",
browser_profile=BrowserProfile(
user_agent="Custom User Agent",
viewport_size={"width": 1920, "height": 1080},
headless=True,
)
)
```
## FAQ & Troubleshooting
Missing environment variables (BROWSERLESS_TOKEN or OPENAI_API_KEY)
Ensure your `.env` file contains both variables and is in the same directory as your script. Call `load_dotenv()` at the top of your script before accessing them. If using `uv`, run `uv pip install python-dotenv`.
.env file not being loaded
Install `python-dotenv` (`pip install python-dotenv`) and call `load_dotenv()` before accessing environment variables. Verify the `.env` file is in the same directory as your script.
uv add fails or does not work as expected
The quickstart uses `uv pip install` instead of `uv add`. The `uv add` command requires a project initialized with `uv init`. Use `uv pip install browser-use python-dotenv` after activating your virtual environment.
Windows ExecutionPolicy error when activating the virtual environment
Run PowerShell as Administrator and execute `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`. Alternatively, use Command Prompt (CMD) or activate with `.venv\Scripts\activate.bat`.
Connection timeout or failed to connect
Verify `BROWSERLESS_WS_URL` is set correctly (default: `wss://production-sfo.browserless.io`). Check that your `BROWSERLESS_TOKEN` is valid and active. Try a different region endpoint if you are experiencing latency, and ensure your network allows WebSocket connections.
## Next steps
all supported AI frameworks and tools
---
# Claude Agent SDK
URL: https://docs.browserless.io/ai-integrations/claude-agent-sdk
# Claude Agent SDK
The [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) lets you build autonomous AI agents powered by Claude. Unlike simple chat completions, agents execute tools autonomously, persist across multiple turns, and use MCP servers to extend capabilities. By connecting to Browserless, your agents can browse bot-protected websites with stealth mode, automatic CAPTCHA solving, and residential proxies. All without local browser infrastructure.
- Browserless API token (available in your [account dashboard](https://browserless.io/account/))
- An [Anthropic API key](https://platform.claude.com/settings/keys)
- Node.js 18 or later (TypeScript)
## Setup
Go to your Browserless account dashboard and copy your API token. You will also need an Anthropic API key.
Set both as environment variables:
**.env file:**
```text
BROWSERLESS_API_KEY=your-browserless-token
ANTHROPIC_API_KEY=your-anthropic-key
```
**Command line:**
```bash
export BROWSERLESS_API_KEY=your-browserless-token
export ANTHROPIC_API_KEY=your-anthropic-key
```
Install the Claude Agent SDK alongside Playwright and Zod:
```bash
npm install @anthropic-ai/claude-agent-sdk playwright-core zod
```
The key change is connecting Playwright to Browserless via CDP instead of launching a local browser:
```typescript
import { chromium } from "playwright-core";
// Browserless connection with stealth + CAPTCHA solving
const BROWSERLESS_URL = `wss://production-sfo.browserless.io/stealth?token=${process.env.BROWSERLESS_API_KEY}&solveCaptchas=true&timeout=300000`;
// Connect via CDP (instead of chromium.launch())
const browser = await chromium.connectOverCDP(BROWSERLESS_URL);
const context = browser.contexts()[0] || await browser.newContext();
const page = context.pages()[0] || await context.newPage();
```
Claude doesn't know Browserless handles CAPTCHAs automatically. Add these rules to your system prompt:
```typescript
systemPrompt: `You have access to a Browserless cloud browser via the execute_playwright MCP tool.
The browser has stealth mode and automatic CAPTCHA solving enabled at the infrastructure level.
IMPORTANT RULES:
1. ALWAYS use execute_playwright for web interactions. Do NOT use WebFetch or other tools.
2. The 'page' and 'browser' objects are ALREADY CONNECTED. Do NOT call connectOverCDP yourself.
3. If you encounter a CAPTCHA or challenge page, wait 15-30 seconds and check again — it will be solved automatically.
4. Return data from your code using: return yourData;
5. ALWAYS use a long timeout on page.goto() to allow time for CAPTCHA solving.
6. Complete ALL your work in a SINGLE execute_playwright call. Do NOT make multiple separate calls.`
```
Run your script with a command and pass a prompt as the argument:
```bash
npx tsx your-agent.ts "Go to https://news.ycombinator.com and get the top 5 story titles"
```
## Connection URL anatomy
The Browserless WebSocket URL controls which features are active for the session:
```bash
wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN&solveCaptchas=true&timeout=300000&proxy=residential&blockAds=true
```
| Segment | Purpose |
|---------|---------|
| `production-sfo.browserless.io` | Regional endpoint (US West). See [Connection URLs](/overview/connection-urls) for all regions |
| `/stealth` | [Stealth route](/baas/bot-detection/stealth): hides automation signals, spoofs fingerprints |
| `token=` | Your Browserless API token |
| `solveCaptchas=true` | Automatically detects and [solves CAPTCHAs](/baas/bot-detection/captchas) (reCAPTCHA, Cloudflare Turnstile, DataDome, and more) |
| `timeout=300000` | Session timeout in ms (5 minutes). Allows time for CAPTCHA solving |
| `proxy=residential` | Route through [residential IPs](/baas/bot-detection/proxies) for better IP reputation |
| `blockAds=true` | Block ads and trackers for cleaner page loads |
> **Cloud browser without stealth or CAPTCHA solving**
> If you don't need anti-detection or automatic CAPTCHA solving and just want Browserless as managed cloud browser infrastructure, use the standard route and omit `solveCaptchas`:
>
> ```bash
> wss://production-sfo.browserless.io?token=YOUR_API_TOKEN
> ```
>
> You still get a fully managed, remote browser, just without the stealth fingerprinting and CAPTCHA solving layers.
## How stealth mode works
The [`/stealth`](/baas/bot-detection/stealth) route automatically applies anti-detection techniques before your agent interacts with any page:
- Hides `navigator.webdriver` and other automation signals
- Spoofs browser fingerprints (canvas, WebGL, fonts)
- Randomizes user-agent strings
- Mimics human-like behavior patterns
No code changes needed. The protections are applied at the browser level, transparently to Playwright and the Claude Agent SDK.
## How automatic CAPTCHA solving works
With `solveCaptchas=true` in your connection URL, Browserless monitors every page for CAPTCHA challenges and solves them in the background:
1. **Detects** CAPTCHAs by monitoring network requests for known patterns (reCAPTCHA, Cloudflare Turnstile, DataDome, and more)
2. **Solves** them programmatically using Browserless's solving engine
3. **Continues** once solved. Your agent sees the unblocked page
Solving typically takes 15 to 60 seconds depending on complexity. The system prompt should instruct your agent to wait and retry if it encounters a challenge page.
> **Note**
> Each successful CAPTCHA solve costs 10 units; attempts that don't clear aren't charged. Using `/stealth` and residential proxies reduces how often CAPTCHAs appear in the first place.
## Example use cases
The integration works well for tasks that would normally trigger bot detection:
Scrape bot-protected review sites:
```text
"Go to https://www.g2.com/products/browserless-io/reviews and get the reviews"
```
Extract product data from e-commerce:
```text
"Navigate to https://www.amazon.com/dp/B09V3KXJPB and get the product title and price"
```
Research news sites:
```text
"Go to https://news.ycombinator.com and get the top 5 story titles"
```
Multi-step workflows:
```text
"Search Google for 'best headless browser 2026', click the first result, and summarize the page"
```
## Resources
- [Claude Agent SDK documentation](https://platform.claude.com/docs/en/agent-sdk/overview)
- [Stealth routes](/baas/bot-detection/stealth)
- [CAPTCHA solving](/baas/bot-detection/captchas)
- [Proxy configuration](/baas/bot-detection/proxies)
- [Connection URLs](/overview/connection-urls)
## FAQ & Troubleshooting
Claude tries to solve CAPTCHAs manually
Add clear instructions to your system prompt that CAPTCHAs solve automatically and to wait 15 to 30 seconds. See the system prompt guidance step in [Setup](#setup) above.
Connection timeout on page.goto()
Use a long timeout: `page.goto(url, { timeout: 120000, waitUntil: 'domcontentloaded' })`. The default 30-second timeout isn't enough when CAPTCHA solving is happening.
"Target page, context or browser has been closed"
This means the Browserless session expired. Increase the session timeout in the URL (`&timeout=300000` for 5 minutes), instruct Claude to complete all work in a single tool call, or rely on the code's automatic reconnect on the next tool call.
Site still blocks the browser
Layer your defenses: use the [`/stealth`](/baas/bot-detection/stealth) route for anti-detection, add `proxy=residential` for [IP reputation](/baas/bot-detection/proxies), and add `solveCaptchas=true` for [CAPTCHA challenges](/baas/bot-detection/captchas).
"WebSocket connection failed"
Check that your `BROWSERLESS_API_KEY` is set correctly, you have available units in your Browserless account, and the regional endpoint is accessible from your network.
## Next steps
use BrowserQL for advanced browser automation
---
# Claude Code + Playwright MCP
URL: https://docs.browserless.io/ai-integrations/claude-code-playwright-mcp
# Claude Code + Playwright MCP
Claude Code connects to a Browserless cloud browser over CDP using Microsoft's official [Playwright MCP](https://github.com/microsoft/playwright-mcp) server, giving your AI agent managed infrastructure with anti-detection, residential proxies, and automatic CAPTCHA solving. No local browser required.
- A Browserless API token (available in your [account dashboard](https://browserless.io/account/))
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed (`npm install -g @anthropic-ai/claude-code`)
- Node.js 18 or later (required by the Playwright MCP server)
## Setup
Register the Playwright MCP server and point it at your Browserless endpoint:
```bash
claude mcp add playwright-browserless \
-- npx -y @playwright/mcp@latest \
--cdp-endpoint "wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN&solveCaptchas=true"
```
That single command does three things:
1. Registers Microsoft's official `@playwright/mcp` server with Claude Code
2. Routes all browser traffic through Browserless's [`/stealth`](/baas/bot-detection/stealth) endpoint (anti-detection enabled)
3. Turns on [automatic CAPTCHA solving](/baas/bot-detection/captchas) at the infrastructure level
Start Claude Code and verify:
```bash
claude
```
Then try:
```text
Use playwright to navigate to https://www.google.com and take a snapshot
```
> **Tip**
> Say "playwright" explicitly in your first message. Claude Code sometimes defaults to running Playwright through bash commands if you don't mention it by name.
## Connection URL anatomy
The CDP endpoint URL controls which Browserless features are active for the session:
```bash
wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN&solveCaptchas=true
```
| Segment | Purpose |
|---------|---------|
| `production-sfo.browserless.io` | Regional endpoint (SFO). Also available: `production-lon` for EU, `production-ams` for Amsterdam |
| `/stealth` | [Stealth route](/baas/bot-detection/stealth) — hides automation signals, spoofs fingerprints, reduces bot detection |
| `token=` | Your Browserless API token |
| `solveCaptchas=true` | Automatically detects and [solves CAPTCHAs](/baas/bot-detection/captchas) in real time |
### Route options
| Route | Use case |
|-------|----------|
| `/stealth` | Best for most AI agent workflows. Anti-detection enabled by default |
| `/` | Standard route. Use when stealth is not needed |
> **Cloud browser without stealth or CAPTCHA solving**
> If you don't need anti-detection or automatic CAPTCHA solving and just want Browserless as managed cloud browser infrastructure, use the standard route and omit `solveCaptchas`:
>
> ```bash
> claude mcp add playwright-browserless \
> -- npx -y @playwright/mcp@latest \
> --cdp-endpoint "wss://production-sfo.browserless.io?token=YOUR_API_TOKEN"
> ```
>
> You still get a fully managed, remote browser, just without the stealth fingerprinting and CAPTCHA solving layers.
### Useful query parameters
| Parameter | Example | Description |
|-----------|---------|-------------|
| `solveCaptchas` | `true` | Auto-solve CAPTCHAs without any code changes |
| `timeout` | `300000` | Session timeout in ms (default 30 s, increase for long-running tasks) |
| `proxy` | `residential` | Route traffic through [residential proxies](/baas/bot-detection/proxies) for additional anti-detection |
| `blockAds` | `true` | Block ads and trackers for cleaner page loads |
Combine them as needed:
```bash
claude mcp add playwright-browserless \
-- npx -y @playwright/mcp@latest \
--cdp-endpoint "wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN&solveCaptchas=true&timeout=300000&proxy=residential"
```
## How stealth mode works
The [`/stealth`](/baas/bot-detection/stealth) route automatically applies anti-detection techniques before your agent interacts with any page:
- Hides `navigator.webdriver` and other automation signals
- Spoofs browser fingerprints (canvas, WebGL, fonts)
- Randomizes user-agent strings
- Mimics human-like browser behavior patterns
No code or configuration changes needed. The stealth protections are applied at the browser level, transparently to Playwright and Claude Code.
When stealth alone isn't enough (some sites still trigger challenges), `solveCaptchas=true` provides the second layer of defense.
## How automatic CAPTCHA solving works
With `solveCaptchas=true` in your connection URL, Browserless monitors every page for CAPTCHA challenges and solves them in the background. This happens entirely at the infrastructure layer. Playwright and Claude Code don't need to do anything.
The system:
1. **Detects** CAPTCHAs by monitoring network requests for known CAPTCHA service patterns (reCAPTCHA, Cloudflare Turnstile, etc.)
2. **Solves** them programmatically using Browserless's solving engine
3. **Fires CDP events** (`Browserless.captchaFound`, `Browserless.captchaAutoSolved`) for monitoring
Since solving can take a few seconds to a minute, you'll want to give Claude Code guidance on how to handle this. See [System prompt for Claude Code](#system-prompt-for-claude-code) below.
> **Note**
> Each successful CAPTCHA solve costs 10 units; attempts that don't clear aren't charged. Using `/stealth` and residential proxies reduces how often CAPTCHAs appear in the first place.
## System prompt for Claude Code
Claude Code doesn't inherently know that Browserless is handling CAPTCHAs and stealth in the background. Without guidance, it may try to interact with CAPTCHA elements directly or give up when it sees a challenge page.
Add this to your Claude Code system prompt (via `CLAUDE.md` in your project root, or passed via `--system-prompt`):
```markdown
## Browser automation context
You are connected to a Browserless cloud browser via Playwright MCP. The browser
has stealth anti-detection and automatic CAPTCHA solving enabled at the
infrastructure level. Important behavior guidelines:
### CAPTCHA handling
- **Do NOT attempt to click, solve, or interact with CAPTCHA elements yourself.**
CAPTCHAs (reCAPTCHA, Cloudflare Turnstile, etc.) are solved
automatically by the browser infrastructure.
- If you detect a CAPTCHA or challenge page, **wait 15-30 seconds**, then take a
new snapshot to check if the page has updated.
- If the CAPTCHA is still present after 60 seconds, report it to the user rather
than attempting to interact with it.
### Bot detection and blocking
- The browser is already running in stealth mode with anti-detection protections.
You do not need to take any special steps to avoid detection.
- If a site blocks you or shows a "bot detected" page, wait 10 seconds and retry
once. If still blocked, report it to the user.
### Session management
- The browser session has a timeout configured by the connection URL. For
long-running tasks, be mindful of the session duration.
- Each `browser_navigate` call reuses the same browser context. Cookies and
session state persist across navigations within the same session.
### Best practices
- Use `browser_snapshot` (accessibility tree) as your primary observation method.
It's faster and more token-efficient than screenshots.
- Use `browser_take_screenshot` only when you need to verify visual layout or
see something the accessibility tree doesn't capture.
- When filling forms, use `browser_type` for text inputs and `browser_click`
for buttons and checkboxes.
```
### Why this matters
Without this prompt, Claude Code will:
- See a CAPTCHA element in the accessibility snapshot and try to click it
- Report "I'm unable to proceed because there's a CAPTCHA" before auto-solve finishes
- Attempt its own "stealth" workarounds (modifying user-agent, etc.) that conflict with Browserless's stealth
With this prompt, Claude Code knows to wait and let the infrastructure handle it.
## Example use cases
### Web research with anti-detection
```text
Navigate to https://www.g2.com/products/browserless/reviews and extract
the 5 most recent reviews. Get the reviewer name, rating, and summary
for each.
```
Claude Code will navigate via the stealth Browserless browser, handle any Cloudflare challenges automatically, and extract the data from the accessibility tree.
### Form submission through CAPTCHA-protected pages
```text
Go to https://example.com/contact, fill in the form with:
- Name: Test User
- Email: test@example.com
- Message: "I'd like to learn more about your enterprise plan"
Then submit the form.
```
If the form has a reCAPTCHA, Browserless solves it transparently before (or during) form submission.
### Multi-step authenticated workflow
```text
1. Navigate to https://app.example.com/login
2. Wait for me to log in manually
3. Once I confirm, navigate to the settings page and take a screenshot
```
Since Browserless maintains a persistent browser context, cookies and auth state carry through the entire session.
## Configuration options
### Per-project setup
Scope the MCP registration to a project so teammates get the same config:
```bash
claude mcp add --scope project playwright-browserless \
-- npx -y @playwright/mcp@latest \
--cdp-endpoint "wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN&solveCaptchas=true"
```
This writes to `.mcp.json` in the project directory, which you can commit to version control (with token managed via environment variable).
### Using environment variables for the token
Avoid committing tokens by using an environment variable:
```bash
claude mcp add playwright-browserless \
-- npx -y @playwright/mcp@latest \
--cdp-endpoint "wss://production-sfo.browserless.io/stealth?token=${BROWSERLESS_TOKEN}&solveCaptchas=true"
```
### Increasing the session timeout
For tasks that take more than 30 seconds (the default), increase the timeout:
```bash
claude mcp add playwright-browserless \
-- npx -y @playwright/mcp@latest \
--cdp-endpoint "wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN&solveCaptchas=true&timeout=300000"
```
`timeout=300000` gives you 5 minutes. Adjust as needed for your workflow.
### Adding residential proxies
For sites with aggressive geo-based blocking or IP reputation checks:
```bash
claude mcp add playwright-browserless \
-- npx -y @playwright/mcp@latest \
--cdp-endpoint "wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN&solveCaptchas=true&proxy=residential"
```
See [Proxy configuration](/baas/bot-detection/proxies) for more options including country targeting and sticky sessions.
## Available Playwright MCP tools
Once connected, Claude Code has access to these browser automation tools:
| Tool | Description |
|------|-------------|
| `browser_navigate` | Navigate to a URL |
| `browser_snapshot` | Capture the accessibility tree (primary observation method) |
| `browser_click` | Click an element by reference |
| `browser_type` | Type text into a form field |
| `browser_take_screenshot` | Capture a PNG screenshot |
| `browser_go_back` / `browser_go_forward` | Browser history navigation |
| `browser_wait` | Wait for a specified duration |
| `browser_press_key` | Press a keyboard key |
| `browser_select_option` | Select from a dropdown |
| `browser_hover` | Hover over an element |
| `browser_drag` | Drag and drop |
| `browser_resize` | Resize the browser viewport |
| `browser_tab_*` | Tab management (new, select, close, list) |
| `browser_file_upload` | Upload files to file inputs |
| `browser_pdf_save` | Save page as PDF |
All of these tools execute against your Browserless cloud browser with stealth and CAPTCHA solving active.
## FAQ & Troubleshooting
Claude Code tries to solve CAPTCHAs manually
Add the [system prompt](#system-prompt-for-claude-code) above to your `CLAUDE.md`. Without it, Claude sees CAPTCHA elements in the accessibility tree and tries to interact with them.
"Connection timeout" errors
The Playwright MCP server defaults to a 30-second CDP connection timeout. If Browserless is slow to provision a browser, add `--cdp-timeout 60000`:
```bash
claude mcp add playwright-browserless \
-- npx -y @playwright/mcp@latest \
--cdp-endpoint "wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN&solveCaptchas=true" \
--cdp-timeout 60000
```
Claude Code uses bash Playwright instead of MCP
Say "use Playwright MCP" explicitly in your first message. Claude Code defaults to writing and running Playwright scripts via bash if it doesn't know MCP is available. After the first interaction, it remembers.
CAPTCHA solving takes too long
Solving can take up to 60 seconds for complex challenges. If you're hitting timeouts, increase the session timeout (`timeout=300000`), add [residential proxies](/baas/bot-detection/proxies) (`proxy=residential`) to reduce CAPTCHA frequency, and use the `/stealth` route (not `/`) to prevent most CAPTCHAs from appearing.
Site still detects the browser as a bot
Layer your defenses. Start with the [`/stealth`](/baas/bot-detection/stealth) route (included in [Setup](#setup)), add `proxy=residential` for IP reputation, and if still blocked, try the [Site Unblocking](/baas/bot-detection/unblocking) API for the most aggressive anti-detection.
## Next steps
use BrowserQL for advanced browser automation
---
# Claude Code Plugin
URL: https://docs.browserless.io/ai-integrations/claude-code-plugin
# Claude Code Plugin
The Browserless plugin for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) gives Claude direct access to the Browserless REST APIs. It can scrape webpages, take screenshots, generate PDFs, search the web, map site structures, and run custom browser automation, all from natural language.
- A Browserless API token (available in your [account dashboard](https://browserless.io/account/))
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
## Installation
Install the plugin in Claude Code:
Clone the repo and point Claude Code at the plugin directory:
```bash
git clone https://github.com/browserless/claude-plugin.git
cd claude-plugin
claude --plugin-dir .
```
## Authentication
Run the auth skill inside Claude Code:
```text
/browserless:auth
```
This prompts you for your token and preferred API region (SFO, LON, or a custom URL for private deployments), then saves the credentials to `~/.browserless/.env`.
Alternatively, set the environment variable directly:
```bash
# On Windows:
# set BROWSERLESS_TOKEN=your-token-here
```
### Auth Management
| Command | Description |
|---------|-------------|
| `/browserless:auth` | Interactive setup — set token and region |
| `/browserless:auth status` | Check if authentication is configured |
| `/browserless:auth clear` | Remove saved credentials |
| `/browserless:auth region` | Change API region without re-entering token |
Credentials are stored in `~/.browserless/.env`, but the `BROWSERLESS_TOKEN` environment variable takes precedence if set.
## API Regions
| Region | URL |
|--------|-----|
| SFO (US West, default) | `https://production-sfo.browserless.io` |
| LON (Europe) | `https://production-lon.browserless.io` |
| AMS (Amsterdam) | `https://production-ams.browserless.io` |
| Custom | Any self-hosted or custom Browserless URL |
## Skills
Once authenticated, all skills are available as slash commands:
```text
/browserless:smart-scrape https://example.com
/browserless:screenshot https://example.com
/browserless:pdf https://example.com
/browserless:search what is browserless
/browserless:map https://example.com
/browserless:function click the login button on https://example.com
```
| Skill | Command | Description | Example Prompt |
|-------|---------|-------------|----------------|
| **Smart Scrape** | `/browserless:smart-scrape` | Scrape webpages with cascading strategies (HTTP fetch, proxy, headless browser, captcha solving). Returns markdown, HTML, screenshots, PDFs, or links. | `summarize the main content of https://news.ycombinator.com` |
| **Screenshot** | `/browserless:screenshot` | Capture screenshots of webpages. Supports full-page, element-specific, viewport sizing, image formats (PNG/JPEG/WebP), and proxy/geo-targeting. | `take a screenshot of https://inet-ip.info/ using a French proxy, wait 5 seconds before taking it` |
| **PDF** | `/browserless:pdf` | Generate PDFs from webpages or HTML. Supports paper formats, margins, headers/footers, landscape, background graphics, and tagged/accessible PDFs. | `save https://en.wikipedia.org/wiki/Headless_browser as a landscape A4 PDF` |
| **Search** | `/browserless:search` | Search the web and optionally scrape result pages. Supports web, news, and image sources with time-based filtering and content categories. | `find recent AI news en español from the last week` |
| **Map** | `/browserless:map` | Discover and list all URLs on a website. Crawls sitemaps, pages, and subdomains with relevance-based search filtering. | `save a list of all URLs on https://browserless.io in json format` |
| **Function** | `/browserless:function` | Execute custom Puppeteer JavaScript in a cloud browser. Run arbitrary automation scripts, interact with page elements, fill forms, and return structured data. | `go to https://news.ycombinator.com and return the top 10 story titles as JSON` |
## API Reference
Each skill maps to a Browserless REST API endpoint. Full API documentation is available in the [REST APIs guide](/rest-apis/intro).
| Skill | Endpoint |
|-------|----------|
| Smart Scrape | `POST /smart-scrape` |
| Screenshot | `POST /screenshot` |
| PDF | `POST /pdf` |
| Search | `POST /search` |
| Map | `POST /map` |
| Function | `POST /function` |
## FAQ & Troubleshooting
How do I set or change my API token and region?
Run `/browserless:auth` inside Claude Code for interactive setup, or `/browserless:auth region` to change the region without re-entering your token. Credentials are stored in `~/.browserless/.env`, unless the `BROWSERLESS_TOKEN` environment variable is set, which takes precedence.
Which skill should I use to scrape a page?
Use `/browserless:smart-scrape` for most scraping tasks. It cascades through HTTP fetch, proxy, headless browser, and CAPTCHA solving strategies automatically, returning markdown, HTML, screenshots, PDFs, or links.
How do I run custom automation beyond the built-in skills?
Use `/browserless:function` to execute custom Puppeteer JavaScript in a cloud browser, for example clicking elements, filling forms, or returning structured data that the other skills don't cover.
## Next steps
use BrowserQL for advanced browser automation
---
# Anthropic Computer Use Integration
URL: https://docs.browserless.io/ai-integrations/computer-use/anthropic-computer-use
# Anthropic Computer Use Integration
[Anthropic Computer Use](https://docs.anthropic.com/en/docs/agents-and-tools/computer-use) enables Claude to interact with browsers like a human. It takes screenshots, moves the cursor, clicks elements, and types text. By connecting Computer Use to Browserless, you get cloud-hosted browser infrastructure without managing local browsers, enabling scalable AI-powered browser automation with stealth mode, residential proxies, and enterprise-grade reliability.
- Node.js 18+ (for TypeScript) or Python 3.9+ (for Python)
- Browserless API token (available in your [account dashboard](https://browserless.io/account/))
- Anthropic API key (from your [Anthropic Settings](https://platform.claude.com/settings/keys))
## How it works
This integration uses a **screenshot + action loop** with Playwright CDP:
1. **Connect** — Playwright connects to Browserless via CDP WebSocket
2. **Screenshot** — Capture the browser screen as an image
3. **Send to Claude** — Claude analyzes the screenshot using the Computer Use API
4. **Execute action** — Claude requests an action (click, type, scroll) and you execute it via Playwright
5. **Repeat** — Take a new screenshot and continue until the task is complete
Anthropic calls this the "agent loop": Claude responds with a tool use request, and your application responds with the results. You implement the loop that coordinates between Claude and the browser.
## Step-by-Step Setup
Go to your Browserless account dashboard and copy your API token.
Then set your environment variables:
**.env file:**
```text
BROWSERLESS_API_KEY=your-browserless-token
ANTHROPIC_API_KEY=your-anthropic-key
```
**Command line:**
```bash
export BROWSERLESS_API_KEY="your-browserless-token"
export ANTHROPIC_API_KEY="your-anthropic-key"
```
**TypeScript:**
```bash
npm install playwright-core @anthropic-ai/sdk dotenv typescript ts-node @types/node
```
**Python:**
```bash
pip install playwright anthropic python-dotenv
```
Computer Use requires you to implement the agent loop yourself. Below is a complete working example that navigates to Hacker News and identifies the top post.
When using the Anthropic API directly, you must use the correct combination of model, tool version, and beta flag. Check the Anthropic Models Documentation and Computer Use Documentation for the latest values.
Current working values (as of this writing):
Model: claude-sonnet-4-6
Beta: computer-use-2025-11-24
Tool type: computer_20251124
**TypeScript:**
```typescript
dotenv.config();
const BROWSERLESS_URL = `wss://production-sfo.browserless.io?token=${process.env.BROWSERLESS_API_KEY}`;
const DISPLAY_WIDTH = 1024;
const DISPLAY_HEIGHT = 768;
async function captureScreenshot(page: Page): Promise {
const screenshot = await page.screenshot({ type: "png" });
return screenshot.toString("base64");
}
async function executeComputerAction(
page: Page,
action: string,
params: Record
): Promise {
const coordinate = params.coordinate as [number, number] | undefined;
switch (action) {
case "screenshot":
return "Screenshot captured";
case "left_click":
if (coordinate) {
await page.mouse.click(coordinate[0], coordinate[1]);
return `Clicked at (${coordinate[0]}, ${coordinate[1]})`;
}
return "Missing coordinate for left_click";
case "type":
await page.keyboard.type(params.text as string);
return `Typed: "${params.text}"`;
case "key":
await page.keyboard.press(params.text as string);
return `Pressed key: ${params.text}`;
case "scroll": {
const direction = params.scroll_direction as string;
const amount = (params.scroll_amount as number) ?? 3;
const scrollCoord = coordinate ?? [DISPLAY_WIDTH / 2, DISPLAY_HEIGHT / 2];
await page.mouse.move(scrollCoord[0], scrollCoord[1]);
const deltaX = direction === "left" ? -amount * 100 : direction === "right" ? amount * 100 : 0;
const deltaY = direction === "down" ? amount * 100 : direction === "up" ? -amount * 100 : 0;
await page.mouse.wheel(deltaX, deltaY);
return `Scrolled ${direction} by ${amount}`;
}
default:
return `Unknown action: ${action}`;
}
}
async function runComputerUseLoop(
client: Anthropic,
page: Page,
task: string
): Promise {
const initialScreenshot = await captureScreenshot(page);
const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
{
role: "user",
content: [
{
type: "image",
source: {
type: "base64",
media_type: "image/png",
data: initialScreenshot,
},
},
{ type: "text", text: task },
],
},
];
const tools: Anthropic.Beta.Messages.BetaToolUnion[] = [
{
type: "computer_20251124",
name: "computer",
display_width_px: DISPLAY_WIDTH,
display_height_px: DISPLAY_HEIGHT,
},
];
const MAX_ITERATIONS = 10;
for (let i = 0; i < MAX_ITERATIONS; i++) {
const response = await client.beta.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 4096,
tools,
messages,
betas: ["computer-use-2025-11-24"],
});
const assistantContent: Anthropic.Beta.Messages.BetaContentBlock[] = [];
const toolResults: Anthropic.Beta.Messages.BetaToolResultBlockParam[] = [];
for (const block of response.content) {
assistantContent.push(block);
if (block.type === "tool_use") {
const input = block.input as Record;
const action = input.action as string;
if (action === "screenshot") {
const screenshot = await captureScreenshot(page);
toolResults.push({
type: "tool_result",
tool_use_id: block.id,
content: [
{
type: "image",
source: {
type: "base64",
media_type: "image/png",
data: screenshot,
},
},
],
});
} else {
const result = await executeComputerAction(page, action, input);
toolResults.push({
type: "tool_result",
tool_use_id: block.id,
content: result,
});
}
}
}
messages.push({ role: "assistant", content: assistantContent });
if (toolResults.length === 0) {
return response.content
.filter(
(b): b is Anthropic.Beta.Messages.BetaTextBlock => b.type === "text"
)
.map((b) => b.text)
.join("\n");
}
messages.push({ role: "user", content: toolResults });
}
return "Max iterations reached";
}
async function main() {
const browser = await chromium.connectOverCDP(BROWSERLESS_URL);
const page = await browser.newPage();
await page.setViewportSize({ width: DISPLAY_WIDTH, height: DISPLAY_HEIGHT });
await page.goto("https://news.ycombinator.com", { waitUntil: "networkidle" });
const client = new Anthropic();
const result = await runComputerUseLoop(
client,
page,
"What is the title of the top post on this page? Take a screenshot first to see the page."
);
console.log("Result:", result);
await browser.close();
}
main();
```
**Python:**
```python
from dotenv import load_dotenv
from playwright.async_api import async_playwright
load_dotenv()
BROWSERLESS_URL = f"wss://production-sfo.browserless.io?token={os.environ['BROWSERLESS_API_KEY']}"
DISPLAY_WIDTH = 1024
DISPLAY_HEIGHT = 768
async def capture_screenshot(page) -> str:
screenshot = await page.screenshot(type="png")
return base64.b64encode(screenshot).decode()
async def execute_computer_action(page, action: str, params: dict) -> str:
if action == "screenshot":
return "Screenshot captured"
elif action == "left_click":
x, y = params["coordinate"]
await page.mouse.click(x, y)
return f"Clicked at ({x}, {y})"
elif action == "type":
await page.keyboard.type(params["text"])
return f'Typed: "{params["text"]}"'
elif action == "key":
await page.keyboard.press(params["text"])
return f'Pressed key: {params["text"]}'
elif action == "scroll":
direction = params.get("scroll_direction", "down")
amount = params.get("scroll_amount", 3)
coord = params.get("coordinate", [DISPLAY_WIDTH // 2, DISPLAY_HEIGHT // 2])
await page.mouse.move(coord[0], coord[1])
delta_x = -amount * 100 if direction == "left" else amount * 100 if direction == "right" else 0
delta_y = amount * 100 if direction == "down" else -amount * 100 if direction == "up" else 0
await page.mouse.wheel(delta_x, delta_y)
return f"Scrolled {direction} by {amount}"
return f"Unknown action: {action}"
async def run_computer_use_loop(client, page, task: str) -> str:
initial_screenshot = await capture_screenshot(page)
messages = [
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": initial_screenshot,
},
},
{"type": "text", "text": task},
],
}
]
tools = [
{
"type": "computer_20251124",
"name": "computer",
"display_width_px": DISPLAY_WIDTH,
"display_height_px": DISPLAY_HEIGHT,
}
]
max_iterations = 10
for _ in range(max_iterations):
response = await client.beta.messages.create(
model="claude-sonnet-4-6",
max_tokens=4096,
tools=tools,
messages=messages,
betas=["computer-use-2025-11-24"],
)
assistant_content = []
tool_results = []
for block in response.content:
assistant_content.append(block)
if block.type == "tool_use":
action = block.input.get("action")
if action == "screenshot":
screenshot = await capture_screenshot(page)
tool_results.append(
{
"type": "tool_result",
"tool_use_id": block.id,
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": screenshot,
},
}
],
}
)
else:
result = await execute_computer_action(page, action, block.input)
tool_results.append(
{
"type": "tool_result",
"tool_use_id": block.id,
"content": result,
}
)
messages.append({"role": "assistant", "content": assistant_content})
if not tool_results:
return "\n".join(b.text for b in response.content if b.type == "text")
messages.append({"role": "user", "content": tool_results})
return "Max iterations reached"
async def main():
async with async_playwright() as p:
browser = await p.chromium.connect_over_cdp(BROWSERLESS_URL)
page = await browser.new_page()
await page.set_viewport_size({"width": DISPLAY_WIDTH, "height": DISPLAY_HEIGHT})
await page.goto("https://news.ycombinator.com", wait_until="networkidle")
client = anthropic.AsyncAnthropic()
result = await run_computer_use_loop(
client,
page,
"What is the title of the top post on this page? Take a screenshot first to see the page.",
)
print("Result:", result)
await browser.close()
asyncio.run(main())
```
## Available actions
Claude can request these actions through the Computer Use tool:
| Action | Description |
|--------|-------------|
| `screenshot` | Capture current screen state |
| `left_click` | Click at coordinates `[x, y]` |
| `right_click` | Right-click at coordinates |
| `double_click` | Double-click at coordinates |
| `type` | Type a text string |
| `key` | Press a key or combo via `text` param (e.g., `Enter`, `ctrl+s`) |
| `mouse_move` | Move cursor to coordinates |
| `scroll` | Scroll at coordinates with `scroll_direction` and `scroll_amount` |
## Advanced Configuration
### Stealth mode
For sites with bot detection, use the [stealth route](/baas/bot-detection/stealth):
**TypeScript:**
```typescript
const browser = await chromium.connectOverCDP(
`wss://production-sfo.browserless.io/stealth?token=${process.env.BROWSERLESS_API_KEY}`
);
```
**Python:**
```python
browser = await p.chromium.connect_over_cdp(
f"wss://production-sfo.browserless.io/stealth?token={os.environ['BROWSERLESS_API_KEY']}"
)
```
### Residential proxies
Route traffic through residential IPs for geo-targeting and rate-limit avoidance:
**TypeScript:**
```typescript
const browser = await chromium.connectOverCDP(
`wss://production-sfo.browserless.io?token=${process.env.BROWSERLESS_API_KEY}&proxy=residential&proxyCountry=us`
);
```
**Python:**
```python
browser = await p.chromium.connect_over_cdp(
f"wss://production-sfo.browserless.io?token={os.environ['BROWSERLESS_API_KEY']}&proxy=residential&proxyCountry=us"
)
```
### Regional endpoints
Pick the region closest to you for lower latency:
| Region | Endpoint |
|--------|----------|
| US West (San Francisco) | `wss://production-sfo.browserless.io` |
| Europe (London) | `wss://production-lon.browserless.io` |
| Europe (Amsterdam) | `wss://production-ams.browserless.io` |
## Why use Browserless with Anthropic Computer Use
- **Stealth mode**: bypass bot detection by adding `/stealth` to the endpoint URL
- **Residential proxies**: route traffic through real residential IPs to avoid blocks
- **Global regions**: choose from US West (San Francisco), Europe (London), or Europe (Amsterdam) endpoints for lower latency
- **No infrastructure**: skip managing Chrome installations, updates, or scaling
- **Parallel sessions**: run multiple browser sessions simultaneously
- **Enterprise reliability**: 99.9% uptime SLA with automatic failover
## Resources
- [Anthropic Computer Use Documentation](https://docs.anthropic.com/en/docs/agents-and-tools/computer-use)
- [Anthropic Models Documentation](https://docs.anthropic.com/en/docs/about-claude/models)
- [Computer Use Reference Implementation](https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo)
- [Browserless Connection Options](/overview/connection-urls)
- [Stealth Mode](/baas/bot-detection/stealth)
- [Proxy Configuration](/baas/bot-detection/proxies)
## FAQ & Troubleshooting
Which model, beta flag, and tool version should I use?
Anthropic updates these together, and mismatched combinations return an error. Check the [Anthropic Models Documentation](https://docs.anthropic.com/en/docs/about-claude/models) and [Computer Use Documentation](https://docs.anthropic.com/en/docs/agents-and-tools/computer-use) for current values before hardcoding them, since they change as new tool versions ship.
Claude's clicks land in the wrong place
The `display_width_px` and `display_height_px` values passed to the `computer` tool must match the actual Playwright viewport size (`page.setViewportSize`/`page.set_viewport_size`). A mismatch scales Claude's coordinates against the wrong dimensions, so clicks and scrolls land off-target.
The loop stops with "Max iterations reached"
`MAX_ITERATIONS` caps how many screenshot-action rounds the loop runs before giving up. Raise the constant for tasks that need more steps, or break the task into smaller prompts so each run completes within the cap.
A site blocks the browser mid-task
Add the [`/stealth`](/baas/bot-detection/stealth) route and [residential proxies](/baas/bot-detection/proxies) to the CDP connection URL. See [Advanced Configuration](#advanced-configuration) above for both examples.
## Next steps
use BrowserQL for advanced browser automation
---
# Gemini Computer Use Integration
URL: https://docs.browserless.io/ai-integrations/computer-use/gemini-computer-use
# Gemini Computer Use Integration
Google's [Gemini Computer Use](https://ai.google.dev/gemini-api/docs/computer-use) model looks at a screenshot of the page and returns UI actions (click, type, scroll) that Playwright executes in a Browserless cloud browser. This enables form filling, web research, and multi-step automation without managing browser infrastructure yourself, backed by Browserless stealth mode and residential proxies.
Unlike OpenAI CUA and Anthropic Computer Use, which return absolute pixel coordinates, Gemini returns coordinates on a normalized 0–1000 grid. You must scale them to your actual viewport (pixel_x = x / 1000 * viewport_width) before passing them to Playwright. Feeding Gemini's raw coordinates directly into page.mouse.click() makes every click land in the top-left corner of the page — forms get mis-filled and submit/CAPTCHA elements are missed. This is the single most common mistake when porting an OpenAI/Anthropic loop to Gemini. See Denormalize coordinates.
- Browserless API token (available in your [account dashboard](https://browserless.io/account/))
- Gemini API key (get it from [Google AI Studio](https://aistudio.google.com/apikey))
- Python 3.10+ and the [`google-genai`](https://pypi.org/project/google-genai/) SDK (`2.7.0`+)
## How it works
Gemini Computer Use runs an agentic **screenshot + action loop**:
1. **Send a request** — call `generate_content` with the `computer_use` tool, the task prompt, and a screenshot of the current page
2. **Receive an action** — the model responds with a `function_call` (e.g. `click`, `type`) whose `x`/`y` are on a normalized 0–1000 grid, plus an `intent` explaining the step
3. **Execute the action** — denormalize the coordinates to viewport pixels and run the action via Playwright
4. **Return the new state** — capture a fresh screenshot and send it back in a `function_response`, then repeat until the model stops emitting actions
gemini-3.5-flash is Google's recommended Computer Use model and uses the streamlined action set below (click, type, ...). The legacy gemini-2.5-computer-use-preview-10-2025 uses a different set (click_at, type_text_at, ...). Both return normalized 0–1000 coordinates. Check the Gemini Computer Use docs for the latest model IDs.
## Step-by-Step Setup
In this guide you'll build an example that navigates to Hacker News and reports the title of the top post. We use [stealth mode](/baas/bot-detection/stealth) to avoid bot detection. The example follows Google's official [Computer Use reference implementation](https://github.com/google-gemini/computer-use-preview), adapted to connect to Browserless over CDP.
Grab your Browserless token from your account dashboard and your Gemini key from Google AI Studio.
**.env file:**
```text
BROWSERLESS_API_KEY=your-browserless-token
GEMINI_API_KEY=your-gemini-key
```
**Command line:**
```bash
export BROWSERLESS_API_KEY=your-browserless-token
export GEMINI_API_KEY=your-gemini-key
```
```bash
pip install google-genai playwright
playwright install chromium
```
Gemini Computer Use is Python-first during preview; this guide uses the google-genai Python SDK. A Node.js SDK (@google/genai) exposes the same computerUse tool if you prefer TypeScript — the Browserless connection and coordinate-denormalization steps are identical.
Connect Playwright to Browserless over CDP using the stealth route (recommended for avoiding bot detection). Set a fixed viewport and reuse those exact dimensions when you denormalize coordinates.
```python
import os
from playwright.sync_api import sync_playwright
SCREEN_WIDTH = 1440
SCREEN_HEIGHT = 900
BROWSERLESS_URL = (
"wss://production-sfo.browserless.io/chromium/stealth"
f"?token={os.environ['BROWSERLESS_API_KEY']}"
)
playwright = sync_playwright().start()
browser = playwright.chromium.connect_over_cdp(BROWSERLESS_URL, timeout=60000)
context = browser.new_context(
viewport={"width": SCREEN_WIDTH, "height": SCREEN_HEIGHT}
)
page = context.new_page()
page.goto("https://news.ycombinator.com", wait_until="load")
```
Gemini's x/y are on a 0–1000 grid. Scale them to the viewport you configured above. This is the step that's missing when a ported OpenAI/Anthropic loop "clicks in the wrong place".
```python
def denormalize_x(x: int) -> int:
return int(x / 1000 * SCREEN_WIDTH)
def denormalize_y(y: int) -> int:
return int(y / 1000 * SCREEN_HEIGHT)
```
Translate each function_call into a Playwright action, denormalizing every coordinate first. This covers the gemini-3.5-flash action set; the legacy gemini-2.5-* names are noted in Supported actions.
```python
KEY_MAP = {
"control": "ControlOrMeta",
"cmd": "Meta",
"command": "Meta",
"enter": "Enter",
"return": "Enter",
"tab": "Tab",
"escape": "Escape",
"backspace": "Backspace",
"delete": "Delete",
"up": "ArrowUp",
"down": "ArrowDown",
"left": "ArrowLeft",
"right": "ArrowRight",
}
def press_keys(keys: list[str]) -> None:
mapped = [KEY_MAP.get(k.lower(), k) for k in keys]
for key in mapped[:-1]:
page.keyboard.down(key)
page.keyboard.press(mapped[-1])
for key in reversed(mapped[:-1]):
page.keyboard.up(key)
def execute_action(call) -> None:
name = call.name
args = dict(call.args or {})
if name in ("open_web_browser", "take_screenshot"):
pass
elif name == "wait":
page.wait_for_timeout(int(args.get("seconds", 1)) * 1000)
elif name == "navigate":
page.goto(args["url"], wait_until="load")
elif name == "go_back":
page.go_back()
elif name == "go_forward":
page.go_forward()
elif name in ("click", "double_click", "right_click", "middle_click", "move"):
x, y = denormalize_x(args["x"]), denormalize_y(args["y"])
if name == "click":
page.mouse.click(x, y)
elif name == "double_click":
page.mouse.dblclick(x, y)
elif name == "right_click":
page.mouse.click(x, y, button="right")
elif name == "middle_click":
page.mouse.click(x, y, button="middle")
else:
page.mouse.move(x, y)
elif name == "type":
page.keyboard.type(args["text"])
if args.get("press_enter"):
page.keyboard.press("Enter")
elif name == "scroll":
x, y = denormalize_x(args["x"]), denormalize_y(args["y"])
direction = args["direction"]
raw = args.get("magnitude", args.get("magnitude_in_pixels", 800))
step = denormalize_y(raw) if direction in ("up", "down") else denormalize_x(raw)
dx = -step if direction == "left" else step if direction == "right" else 0
dy = -step if direction == "up" else step if direction == "down" else 0
page.mouse.move(x, y)
page.mouse.wheel(dx, dy)
elif name in ("hotkey", "key_combination"):
keys = args["keys"]
press_keys(keys if isinstance(keys, list) else str(keys).split("+"))
elif name == "press_key":
press_keys([args["key"]])
elif name == "drag_and_drop":
x, y = denormalize_x(args["x"]), denormalize_y(args["y"])
dx, dy = denormalize_x(args["destination_x"]), denormalize_y(args["destination_y"])
page.mouse.move(x, y)
page.mouse.down()
page.mouse.move(dx, dy)
page.mouse.up()
else:
raise ValueError(f"Unsupported action: {name}")
page.wait_for_load_state()
```
Send the task plus the initial screenshot, execute each returned action, and send a fresh screenshot back in a function_response. The loop ends when the model stops emitting function calls.
This example uses client.models.generate_content with a client-side contents history, matching Google's official Computer Use reference implementation. Google also offers a newer Interactions API (client.interactions.create) that manages conversation state server-side via previous_interaction_id and is recommended for new development generally; generate_content remains fully supported. The Browserless connection and the 0–1000 coordinate denormalization below are identical either way.
```python
from google import genai
from google.genai import types
def capture(page) -> bytes:
page.wait_for_load_state()
return page.screenshot(type="png")
client = genai.Client() # reads GEMINI_API_KEY from the environment
config = types.GenerateContentConfig(
tools=[
types.Tool(
computer_use=types.ComputerUse(
environment=types.Environment.ENVIRONMENT_BROWSER,
)
)
],
thinking_config=types.ThinkingConfig(include_thoughts=True),
)
contents = [
types.Content(
role="user",
parts=[
types.Part(text="What is the title of the top post on this page?"),
types.Part.from_bytes(data=capture(page), mime_type="image/png"),
],
)
]
for _ in range(30): # cap iterations so the loop can't run forever
response = client.models.generate_content(
model="gemini-3.5-flash",
contents=contents,
config=config,
)
candidate = response.candidates[0]
contents.append(candidate.content)
parts = candidate.content.parts or []
function_calls = [part.function_call for part in parts if part.function_call]
if not function_calls:
print("Done:", " ".join(part.text for part in parts if part.text))
break
function_responses = []
for call in function_calls:
# A `safety_decision` of "require_confirmation" means you should
# confirm before executing — see the Safety section below.
execute_action(call)
function_responses.append(
types.FunctionResponse(
name=call.name,
response={"url": page.url},
parts=[
types.FunctionResponsePart(
inline_data=types.FunctionResponseBlob(
mime_type="image/png", data=capture(page)
)
)
],
)
)
contents.append(
types.Content(
role="user",
parts=[types.Part(function_response=fr) for fr in function_responses],
)
)
browser.close()
playwright.stop()
```
## Supported actions
Gemini `3.5-flash` (recommended) returns these browser actions. Every coordinate is on the 0–1000 grid and must be denormalized before use.
| Action | Properties | Description |
|---|---|---|
| `click` / `double_click` / `right_click` / `middle_click` | `x`, `y` | Click at coordinates |
| `move` | `x`, `y` | Move the cursor |
| `type` | `text`, `press_enter` | Type text, optionally pressing Enter |
| `press_key` / `key_down` / `key_up` | `key` | Press / hold / release a key |
| `hotkey` | `keys[]` | Press a key combination |
| `scroll` | `x`, `y`, `direction`, `magnitude` | Scroll at a position |
| `navigate` | `url` | Go directly to a URL |
| `go_back` / `go_forward` | – | Browser history navigation |
| `drag_and_drop` | `x`, `y`, `destination_x`, `destination_y` | Drag from one point to another |
| `wait` | `seconds` | Pause for the page to settle |
| `open_web_browser` / `take_screenshot` | – | No-ops in this loop (state is captured each turn) |
The legacy gemini-2.5-computer-use-preview-10-2025 model uses click_at, hover_at, type_text_at, scroll_document, scroll_at, wait_5_seconds, key_combination, search, navigate, go_back, go_forward, and drag_and_drop. The coordinate handling is identical.
## Safety confirmations
For sensitive actions (e.g. clicking a CAPTCHA checkbox or completing a purchase), Gemini may attach a `safety_decision` to the function call with `decision: "require_confirmation"`. In production you should pause and require explicit approval before executing those actions, then acknowledge the decision when returning the `function_response`. See Google's [safety guidance](https://ai.google.dev/gemini-api/docs/computer-use) for details.
## Advanced configuration
### Residential proxies
reCAPTCHA v3 and similar defenses score requests largely on IP reputation. If your automation completes the form but the site rejects the submission, route traffic through residential IPs:
```python
BROWSERLESS_URL = (
"wss://production-sfo.browserless.io/chromium/stealth"
f"?token={os.environ['BROWSERLESS_API_KEY']}&proxy=residential&proxyCountry=us"
)
```
See [Proxy configuration](/baas/bot-detection/proxies) for country and session options.
### Without stealth mode
If you don't need anti-detection and just want a managed cloud browser:
```python
BROWSERLESS_URL = (
f"wss://production-sfo.browserless.io?token={os.environ['BROWSERLESS_API_KEY']}"
)
```
### Regional endpoints
Connect to the closest region for lower latency. See [Connection URLs](/overview/connection-urls) for all available endpoints.
## When to use Computer Use vs. the MCP browser agent
Computer Use drives the browser from **screenshots and pixel coordinates**, so its reliability depends on the model clicking the right spot. For structured, multi-step flows (logins, form filling), the [Browserless MCP server](/mcp/browserless-mcp-server/setup)'s `browserless_agent` tool is often more robust: it drives the browser from **accessibility/DOM snapshots and element references** rather than coordinates, so it doesn't depend on pixel-accurate clicks and works the same across models. If you're seeing coordinate-related flakiness with Computer Use, consider the MCP agent for the structured parts of your workflow.
## Why use Browserless with Gemini Computer Use
- **Stealth mode**: bypass bot detection by adding `/stealth` to the endpoint URL
- **Residential proxies**: route traffic through real residential IPs to improve IP reputation for score-based defenses like reCAPTCHA v3
- **Global regions**: choose US West, London, or Amsterdam endpoints for lower latency
- **No infrastructure**: skip managing Chrome installations, updates, or scaling
- **Parallel sessions**: run multiple browser sessions simultaneously
## Resources
- [Gemini Computer Use Documentation](https://ai.google.dev/gemini-api/docs/computer-use)
- [Gemini Computer Use Reference Implementation](https://github.com/google-gemini/computer-use-preview)
- [Browserless Connection Options](/overview/connection-urls)
- [Stealth Mode](/baas/bot-detection/stealth)
- [Proxy Configuration](/baas/bot-detection/proxies)
## FAQ & Troubleshooting
The model's clicks land in the wrong place (usually the top-left)
You're passing Gemini's raw 0–1000 coordinates straight to Playwright. Denormalize every `x`/`y` to your viewport first (`x / 1000 * viewport_width`), and make sure the width/height you scale against match the viewport you set with `new_context(viewport=...)`. See [Denormalize coordinates](#step-by-step-setup).
The automation fills the form but the site rejects the submission
This is usually not a coordinate issue — score-based defenses like reCAPTCHA v3 rely heavily on IP reputation. Add [residential proxies](/baas/bot-detection/proxies) to the CDP URL and keep the `/stealth` route. See [Advanced configuration](#advanced-configuration).
The model returns key names Playwright doesn't recognize
The `KEY_MAP` in the [action handler](#step-by-step-setup) covers common mismatches (`control` → `ControlOrMeta`, `cmd` → `Meta`, etc.). Add new ones as needed — the Playwright [keyboard API docs](https://playwright.dev/docs/api/class-keyboard) list all valid key names.
The loop never stops
The `range(30)` cap bounds how many screenshot-action rounds run before giving up. Raise it for longer tasks, or break the task into smaller prompts so each run completes within the cap.
A site blocks the browser mid-task
Add [residential proxies](/baas/bot-detection/proxies) to the CDP connection URL and confirm you're still using the `/stealth` route from [Connect to Browserless](#step-by-step-setup).
## Next steps
use BrowserQL for advanced browser automation
---
# Hermes Agent
URL: https://docs.browserless.io/ai-integrations/hermes-agent
# Hermes Agent
[Hermes Agent](https://github.com/NousResearch/hermes-agent) is NousResearch's open-source AI agent. This guide configures Browserless as its browser: managed cloud sessions with stealth, automatic CAPTCHA solving, residential proxies, and cascading scrape strategies, through one MCP server and one API token.
- A Browserless API token from your [account dashboard](https://browserless.io/account/)
- [Hermes Agent](https://github.com/NousResearch/hermes-agent) installed with MCP support (included in the standard install script)
## Why Browserless as Hermes's browser
Most automation targets use bot detection, login walls, or CAPTCHAs. Browserless handles these by default, so one configuration works on protected sites and permissive ones alike:
- `browserless_smartscraper` runs cascading strategies on every request: direct fetch, then proxy, then headless browser, then CAPTCHA solving, until the content returns.
- `browserless_agent` can preserve cookies and page state through logins, multi-step forms, and pagination. In v1.33.0+, [multi-call sessions require first-call opt-in](/mcp/browser-agent#session-lifetime): set `keepSessionAlive: true`, then echo the returned `sessionId` on later calls.
- The browsers run on Browserless's cloud rather than the machine running Hermes. A single API token covers stealth, residential proxies, and CAPTCHA solving; there are no separate provider accounts to set up.
- The same server exposes nine tools covering scraping, search, crawling, exports, Lighthouse audits, and file downloads.
Hermes's built-in browser tools work for public, permissive pages. We recommend Browserless for automation workloads because the unblocking, proxying, and solving are built into every request instead of configured per site.
## Step 1: Add the server to your config
Hermes configures MCP servers in `~/.hermes/config.yaml`. The Browserless server is remote, so it needs only a URL and your token. Put the token in `~/.hermes/.env` so it stays out of the config file:
```bash
# Add to ~/.hermes/.env
BROWSERLESS_API_TOKEN=YOUR_API_TOKEN_HERE
```
Then reference it from the config. Hermes expands `${VAR}` in server entries from `.env` or the process environment:
```yaml
mcp_servers:
browserless:
url: "https://mcp.browserless.io/mcp"
headers:
Authorization: "Bearer ${BROWSERLESS_API_TOKEN}"
```
The hosted server speaks the Streamable HTTP transport, which is what Hermes uses for URL-based servers. No local process, Node, or Docker is required.
## Step 2: Verify the tools loaded
Start Hermes from the terminal and ask it what it can do:
```bash
hermes chat
```
```text
Tell me which MCP-backed tools are available right now.
```
The reply should list the Browserless tools. Hermes prefixes MCP tools with the server name, so they appear as `mcp__browserless__browserless_agent`, `mcp__browserless__browserless_smartscraper`, and so on. If you edited the config while Hermes was running, reload it with `/reload-mcp`. See the full tool list in the [MCP server reference](/mcp/browserless-mcp-server/setup#tools).
## Step 3: Try it on a real task
Give Hermes a task its built-in browser tends to get blocked on:
```text
Use the Browserless tools to scrape https://www.browserless.io/pricing
and list each plan with its unit allowance, then tell me which strategy
the scraper used.
```
```text
Use the Browserless agent to open https://docs.browserless.io, navigate
to the BaaS quickstart, and summarize the setup steps.
```
## Optional: Limit which tools load
The server exposes nine tools. If you want a smaller surface, use Hermes's tool filtering to whitelist just the ones you need:
```yaml
mcp_servers:
browserless:
url: "https://mcp.browserless.io/mcp"
headers:
Authorization: "Bearer ${BROWSERLESS_API_TOKEN}"
tools:
include: [browserless_agent, browserless_smartscraper]
```
`browserless_agent` plus `browserless_smartscraper` covers most workflows: one stateful browser for interaction, one stateless scraper for content.
## FAQ & Troubleshooting
Can I point Hermes's /browser connect at a Browserless CDP endpoint instead?
No. `/browser connect` is built for local Chromium-family browsers: its readiness probe requests `/json/version` without preserving the URL's query string, so an authenticated endpoint like `wss://production-sfo.browserless.io?token=...` fails the check. Use the MCP route on this page, which authenticates properly and exposes richer tools than raw CDP.
Hermes doesn't list any Browserless tools
Run `/reload-mcp` if you changed `config.yaml` during a session, and check the Hermes logs for a connection error. The usual causes are a URL typo (the endpoint must be exactly `https://mcp.browserless.io/mcp`), an expired token, or `BROWSERLESS_API_TOKEN` not being set in `~/.hermes/.env` — Hermes leaves an unset `${VAR}` as its literal placeholder text, so the server receives a header of `Bearer ${BROWSERLESS_API_TOKEN}` and rejects it.
What do MCP sessions cost?
Each tool call opens a browser session that consumes units based on session time, plus proxy traffic and CAPTCHA solving if used. See [unit consumption](/overview/unit-consumption#mcp-session-cost) for the breakdown.
## Next steps
the eight stateless tools for scraping, search, and exports
---
# LangChain Integration
URL: https://docs.browserless.io/ai-integrations/langchain
# LangChain Integration
[LangChain](https://www.langchain.com/) is a framework for developing applications powered by language models. By integrating Browserless with LangChain, you can give your AI applications web scraping and content processing capabilities without managing browser infrastructure.
- Python 3.8 or higher
- Browserless API token (available in your [account dashboard](https://browserless.io/account/))
> **Note**
> This guide focuses on `BrowserlessLoader`, which is useful for scraping and document ingestion. If you need full browser control or multi-step automation, start with [BrowserQL](/browserql/start) or one of the [agent-focused guides](/ai-integrations/start#agent-frameworks).
## Step-by-Step Setup
Go to your Browserless account dashboard and copy your API token.
Then set the BROWSERLESS_API_TOKEN environment variable in your .env file:
**.env file:**
```text
BROWSERLESS_API_TOKEN=your-token-here
```
**Command line:**
```bash
export BROWSERLESS_API_TOKEN=your-token-here
```
Set up a Python virtual environment to manage your dependencies:
**venv:**
```bash
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
```
**conda:**
```bash
conda create -n langchain-env python=3.8
conda activate langchain-env
```
Install LangChain and other required packages:
**pip:**
```bash
pip install langchain-community python-dotenv
```
**Poetry:**
```bash
poetry add langchain-community python-dotenv
```
Create a file named scraper.py with the following complete code:
```python
from dotenv import load_dotenv
import os
from langchain_community.document_loaders import BrowserlessLoader
def main():
# Load environment variables
load_dotenv()
# Initialize the loader with your API token
loader = BrowserlessLoader(
api_token=os.getenv("BROWSERLESS_API_TOKEN"),
urls=["https://example.com"],
text_content=True # Get text content instead of raw HTML
)
# Load and process the documents
documents = loader.load()
# Print the results
for doc in documents:
print(f"Source: {doc.metadata.get('source')}")
print(f"Content: {doc.page_content[:200]}...")
if __name__ == "__main__":
main()
```
Run your application with the following command:
```bash
python scraper.py
```
You should see output showing the scraped content from the example website.
## How It Works
**1. Connection Setup**: BrowserlessLoader connects to Browserless using your API token
**2. Content Loading**: The loader fetches and processes web content
**3. Document Creation**: Content is converted into LangChain Documents
**4. Processing**: Documents can be further processed with LangChain's tools
## Advanced Configuration
### Multiple URLs
Process multiple websites in a single operation:
```python
loader = BrowserlessLoader(
api_token=api_token,
urls=[
"https://example1.com",
"https://example2.com",
"https://example3.com"
]
)
```
### Raw HTML Mode
Get raw HTML content instead of text:
```python
loader = BrowserlessLoader(
api_token=api_token,
urls=["https://example.com"],
text_content=False
)
```
## Performance Optimization
1. **Batch Processing**
- Process multiple URLs in batches
- Implement proper error handling
- Use async/await for better performance
2. **Resource Management**
- Monitor memory usage
- Implement proper cleanup
- Handle timeouts appropriately
## Security Best Practices
1. **API Token Management**
- Never commit tokens to version control
- Use environment variables
- Rotate tokens regularly
2. **Input Validation**
- Validate URLs before processing
- Implement rate limiting
- Handle sensitive data appropriately
## Common Use Cases
### News Aggregation
```python
def aggregate_news(api_token, news_sites):
loader = BrowserlessLoader(
api_token=api_token,
urls=news_sites,
text_content=True
)
documents = loader.load()
# Process and analyze the news content
for doc in documents:
print(f"Source: {doc.metadata.get('source')}")
print(f"Content: {doc.page_content[:200]}...")
```
### Content Analysis
```python
from langchain.text_splitter import RecursiveCharacterTextSplitter
def analyze_content(api_token, url):
# Load content
loader = BrowserlessLoader(
api_token=api_token,
urls=[url],
text_content=True
)
documents = loader.load()
# Split content into chunks
text_splitter = RecursiveCharacterTextSplitter(
chunk_size=1000,
chunk_overlap=200
)
chunks = text_splitter.split_documents(documents)
# Process chunks
for chunk in chunks:
print(f"Chunk: {chunk.page_content[:100]}...")
```
For more advanced usage scenarios, please refer to:
- [LangChain Documentation](https://www.langchain.com/docs)
- [Browserless BaaS Documentation](/baas/start)
- [Integrating with other LLM providers](/ai-integrations/start)
## FAQ & Troubleshooting
How does BrowserlessLoader authenticate with Browserless?
Pass your token directly via the `api_token` parameter, or set it as the `BROWSERLESS_API_TOKEN` environment variable and load it with `os.getenv("BROWSERLESS_API_TOKEN")` as shown in the setup steps above.
Should I use BrowserlessLoader or BrowserQL?
Use `BrowserlessLoader` for straightforward scraping and document ingestion into LangChain. If the target site has aggressive bot detection, or you need multi-step interaction (clicking, filling forms) before extracting content, use [BrowserQL](/browserql/start) instead.
The loaded content is missing text I can see in the browser
Set `text_content=False` to get raw HTML instead of extracted text, which preserves structure that text extraction can drop. See [Raw HTML Mode](#raw-html-mode) above.
## Next steps
all supported AI frameworks and tools
---
# Browserless templates for Make.com
URL: https://docs.browserless.io/ai-integrations/make
# Using Browserless with Make.com
Make.com (formerly Integromat) is a visual automation platform that connects different services and automates tasks. This guide shows you how to use Browserless with Make.com to automate browser-based tasks.
- A Browserless account with an API token
- A Make.com account (free or paid)
## Getting Started
Create a free account on [Make.com](https://www.make.com) to get started with automation workflows.
Once logged in, go to the Scenarios section where you can create and manage your automation workflows.
Click on "Create a new scenario" to start building your automation workflow with Browserless.
Search for and add the HTTP module to your scenario. This will allow you to make requests to Browserless APIs.
Choose the "Make a Request" action from the HTTP module options.
Configure your HTTP request with the Browserless endpoint and your API token. See the examples below for specific endpoint configurations.
For the templates below, remember to replace `YOUR_API_TOKEN_HERE` with your actual Browserless API token.
## Available Endpoints
### Screenshot
The `/screenshot` endpoint allows you to capture screenshots of web pages. This is useful for:
- Visual monitoring of websites
- Creating thumbnails
- Documenting web content
[Learn more about the Screenshot API](/rest-apis/screenshot-api)
#### HTTP Module Configuration
1. Add an **HTTP** module and select the **Make a Request** action
2. Set **URL** to `https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE`
3. Set **Method** to `POST`
4. Set **Body type** to `Raw`
5. Set **Content type** to `application/json`
6. Add this JSON to the **Request content**:
```json
{
"url": "https://www.example.com"
}
```
### PDF Generation
The `/pdf` endpoint generates PDF documents from web pages. This is useful for:
- Creating printable versions of web content
- Archiving web pages
- Generating reports
[Learn more about the PDF API](/rest-apis/pdf-api)
#### HTTP Module Configuration
1. Add an **HTTP** module and select the **Make a Request** action
2. Set **URL** to `https://production-sfo.browserless.io/pdf?token=YOUR_API_TOKEN_HERE`
3. Set **Method** to `POST`
4. Set **Body type** to `Raw`
5. Set **Content type** to `application/json`
6. Add this JSON to the **Request content**:
```json
{
"url": "https://www.example.com"
}
```
### Content Extraction
The `/content` endpoint extracts the HTML content from web pages. This is useful for:
- Web scraping
- Content analysis
- Data extraction
[Learn more about the Content API](/rest-apis/content)
#### HTTP Module Configuration
1. Add an **HTTP** module and select the **Make a Request** action
2. Set **URL** to `https://production-sfo.browserless.io/content?token=YOUR_API_TOKEN_HERE`
3. Set **Method** to `POST`
4. Set **Body type** to `Raw`
5. Set **Content type** to `application/json`
6. Add this JSON to the **Request content**:
```json
{
"url": "https://www.example.com"
}
```
### Unblock
The `/unblock` endpoint helps bypass common anti-bot measures. This is useful for:
- Accessing protected content
- Handling CAPTCHAs
- Managing cookies and sessions
[Learn more about the Unblock API](/rest-apis/unblock)
#### HTTP Module Configuration
1. Add an **HTTP** module and select the **Make a Request** action
2. Set **URL** to `https://production-sfo.browserless.io/unblock?token=YOUR_API_TOKEN_HERE`
3. Set **Method** to `POST`
4. Set **Body type** to `Raw`
5. Set **Content type** to `application/json`
6. Add this JSON to the **Request content**:
```json
{
"url": "https://www.example.com",
"cookies": true,
"browserWSEndpoint": true,
"content": true,
"screenshot": true
}
```
### Browser Query Language (BQL)
The `/chrome/bql` endpoint allows you to execute complex browser automation tasks using GraphQL. This is useful for:
- Complex form filling
- Multi-step workflows
- Custom browser automation
[Learn more about BQL](/browserql/start)
#### HTTP Module Configuration
1. Add an **HTTP** module and select the **Make a Request** action
2. Set **URL** to `https://production-sfo.browserless.io/chrome/bql?token=YOUR_API_TOKEN_HERE`
3. Set **Method** to `POST`
4. Set **Body type** to `Raw`
5. Set **Content type** to `application/json`
6. Add this JSON to the **Request content**:
```json
{
"query": "mutation FormExample {\n goto(url: \"https://www.browserless.io/practice-form\") {\n status\n }\n select(selector:\"#Contact-Subject\",value:\"support\"){ time } \n typeEmail: type(text: \"john@email.com\", selector: \"#Email\") {\n time\n }\n typeMessage: type(\n selector: \"#Message\"\n text: \"Hello world!\"\n ) {\n time\n }\n solve(\n type: cloudflare\n ){\n solved\n }\n waitForTimeout(time:3000){time}\n screenshot{\n base64\n }\n}",
"variables": {},
"operationName": "FormExample"
}
```
### Function
The `/function` endpoint allows you to execute custom JavaScript code in a browser context. This is useful for:
- Custom browser automation
- Complex data extraction
- Multi-step workflows
[Learn more about the Function API](/rest-apis/function)
#### HTTP Module Configuration
1. Add an **HTTP** module and select the **Make a Request** action
2. Set **URL** to `https://production-sfo.browserless.io/function?token=YOUR_API_TOKEN_HERE`
3. Set **Method** to `POST`
4. Set **Body type** to `Raw`
5. Set **Content type** to `application/javascript`
6. Add this JavaScript to the **Request content**:
```javascript
await page.goto("https://example.com/");
const url = await page.content();
const buffer = await page.pdf({ format: "A4" });
const base64PDF = buffer.toString('base64');
const screenshot = await page.screenshot({ encoding: "base64" });
return {
data: {
url,
screenshot,
base64PDF
},
type: "application/json",
};
}
```
## FAQ & Troubleshooting
The HTTP module returns 401 Unauthorized
Check that `token=YOUR_API_TOKEN_HERE` is on the request URL, not just in the body. A missing or expired token is the most common cause.
The screenshot or PDF response looks corrupted in Make
Make's HTTP module doesn't render binary responses inline. Add `"encoding": "base64"` to the request body (for endpoints that support it) so Browserless returns JSON with a base64 string you can pass to a downstream module instead of a raw binary buffer.
The request times out on slow-loading pages
Increase the module's timeout setting, and consider adding `waitUntil` or `bestAttempt` parameters to the Browserless endpoint so it doesn't wait indefinitely on pages that never fully settle.
## Next steps
explore every Browserless REST endpoint
---
# OpenClaw Integration
URL: https://docs.browserless.io/ai-integrations/open-claw
# OpenClaw Integration
[OpenClaw](https://openclaw.ai/) is an open-source personal AI assistant that runs locally and can autonomously browse the web, fill out forms, scrape data, and interact with online services. By connecting OpenClaw to Browserless, you offload browser execution to the cloud – gaining stealth, residential proxies, CAPTCHA solving, and scalable sessions without running a local browser.
- [OpenClaw](https://openclaw.ai/) installed and running (`openclaw onboard` completed)
- Browserless API token (available in your [account dashboard](https://browserless.io/account/))
## Step-by-Step Setup
Go to your Browserless account dashboard and copy your API token. You will add it to your OpenClaw configuration in the next step.
:::tip
Store your token in an environment variable instead of hardcoding it in config files:
```bash
export BROWSERLESS_API_TOKEN="your-token-here"
```
:::
OpenClaw uses browser profiles defined in ~/.openclaw/openclaw.json. Add a browserless profile that points to a Browserless regional endpoint via its CDP URL.
Open your config file and add the following:
```json5
// ~/.openclaw/openclaw.json
{
browser: {
enabled: true,
defaultProfile: "browserless",
remoteCdpTimeoutMs: 2000,
remoteCdpHandshakeTimeoutMs: 4000,
profiles: {
browserless: {
cdpUrl: "wss://production-sfo.browserless.io?token=YOUR_API_TOKEN",
color: "#FF4500"
}
}
}
}
```
Replace YOUR_API_TOKEN with your actual Browserless token, or use an environment variable reference if your setup supports it.
Choose a regional endpoint
Pick the region closest to you for lower latency:
| Region | CDP URL |
|---|---|
| US West | `wss://production-sfo.browserless.io?token=YOUR_API_TOKEN` |
| Europe UK | `wss://production-lon.browserless.io?token=YOUR_API_TOKEN` |
| Europe Amsterdam | `wss://production-ams.browserless.io?token=YOUR_API_TOKEN` |
Confirm that OpenClaw can reach the Browserless endpoint:
```bash
openclaw browser status
```
You should see the browserless profile listed as reachable. If the profile shows as unreachable, double-check your API token and network connectivity.
You can also start a quick browser session and take a screenshot to validate:
```bash
openclaw browser start
openclaw browser screenshot
```
Once connected, OpenClaw's AI can use Browserless just like a local browser. Ask it to perform tasks in natural language through your preferred chat interface (WhatsApp, Discord, Slack, etc.):
- "Go to example.com and take a screenshot"
- "Fill out the contact form on browserless.io/practice-form"
- "Scrape the pricing table from that page"
OpenClaw will route all browser actions through Browserless automatically.
Using the CLI directly
You can also drive the browser with OpenClaw's CLI commands:
```bash
# Navigate to a page
openclaw browser navigate "https://example.com"
# Take a snapshot (returns element references for interaction)
openclaw browser snapshot --efficient
# Click an element by reference
openclaw browser click @e1
# Take a full-page screenshot
openclaw browser screenshot --full-page
```
:::note
Always take a new snapshot after every action – element references (`@e1`, `@e2`, etc.) become stale when the DOM changes.
:::
## Why use Browserless with OpenClaw?
OpenClaw's built-in managed browser works well for local tasks, but cloud and headless deployments (servers, Docker, CI) have no display. Browserless solves this and adds a host of other features:
- **Stealth and anti-bot resilience** – bypass bot detection that trips up standard Chromium
- **CAPTCHA and Cloudflare solving** – automatically handle verification challenges
- **Residential proxies** – rotate IPs to avoid rate limits and geo-restrictions
- **No local browser required** – ideal for headless servers, Docker, and cloud VMs
- **Regional endpoints** – choose US West, UK, or Amsterdam for lower latency
## Keeping a local profile alongside Browserless
You can define multiple profiles and switch between them. This is useful for local development (managed browser) and production (Browserless):
```json5
// ~/.openclaw/openclaw.json
{
browser: {
enabled: true,
defaultProfile: "browserless",
profiles: {
local: {
cdpPort: 18800,
color: "#0066CC"
},
browserless: {
cdpUrl: "wss://production-sfo.browserless.io?token=YOUR_API_TOKEN",
color: "#FF4500"
}
}
}
}
```
Switch profiles on any command with the `?profile=` parameter, or change `defaultProfile` in your config.
## Additional resources
- [OpenClaw Documentation](https://docs.openclaw.ai/)
- [OpenClaw Browser Tool Reference](https://docs.openclaw.ai/tools/browser)
- [Browserless Connection URLs](/overview/connection-urls)
- [Browserless REST APIs](/rest-apis/screenshot-api)
- [BrowserQL](/browserql/start)
## FAQ & Troubleshooting
How do I connect OpenClaw to Browserless?
Add a `browserless` profile to `~/.openclaw/openclaw.json` with a `cdpUrl` pointing at your Browserless WebSocket endpoint and token, then set it as `defaultProfile`, as shown in step 2 above.
openclaw browser status shows the Browserless profile as unreachable
Verify your API token is correct and active in the [Browserless dashboard](https://browserless.io/account/). If it still fails, increase `remoteCdpTimeoutMs` and `remoteCdpHandshakeTimeoutMs` in your config, and check that outbound HTTPS traffic on port 443 is allowed by your firewall.
I'm getting 501 errors on snapshot, PDF, or AI snapshot features
These advanced OpenClaw browser features require Playwright. Install it with `npm install playwright`.
I'm hitting rate limit or plan errors
Browserless returns HTTP 429 when concurrency or request limits are exceeded. Check your usage in the [Browserless dashboard](https://browserless.io/account/) and consider upgrading your plan.
## Next steps
all supported AI frameworks and tools
---
# OpenAI SDK
URL: https://docs.browserless.io/ai-integrations/openai
# OpenAI SDK
OpenAI exposes two paths for putting GPT behind a Browserless-powered agent loop:
- **Direct integration** with the [Responses API](https://platform.openai.com/docs/api-reference/responses). One `responses.create` call, MCP server as a `tool`. Lightest possible shape.
- **Managed integration** with the [OpenAI Agents SDK](https://openai.github.io/openai-agents-js/). An `Agent` class, a `run()` helper, built-in tracing and handoffs. Better when you outgrow a single prompt.
Both routes call the same hosted MCP server at `https://mcp.browserless.io/mcp`. This page builds the same example using both integration paths: a `GET /hn` endpoint that returns the top 10 Hacker News stories as JSON.
- Browserless API token (available in your [account dashboard](https://browserless.io/account/))
- An [OpenAI API key](https://platform.openai.com/api-keys)
- Node.js 20.6 or later (for the built-in `--env-file` flag)
## Setting environment variables
**.env file:**
```bash
OPENAI_API_KEY=your-openai-key
BROWSERLESS_API_KEY=your-browserless-token
PORT=3000
```
**Command line:**
```bash
export OPENAI_API_KEY=your-openai-key
export BROWSERLESS_API_KEY=your-browserless-token
export PORT=3000
```
## Direct integration: Responses API
The Responses API runs the tool-calling loop server-side and accepts the hosted MCP server as a single `tool` entry. No SDK, no state machine — one request, one response.
### Install
```bash
npm init -y
npm install openai express
```
### `server.js`
```js
const PORT = process.env.PORT ?? 3000;
const OPENAI_API_KEY = process.env.OPENAI_API_KEY || "";
const BROWSERLESS_API_KEY = process.env.BROWSERLESS_API_KEY || "";
const INSTRUCTIONS =
"You are a news scraper. Use the browserless tools to load the Hacker News front page and return the top 10 stories as a JSON array. Each item must have the shape { rank, title, url, points }. Reply with ONLY the JSON array — no markdown fences, no commentary.";
const app = express();
const client = new OpenAI({ apiKey: OPENAI_API_KEY });
app.get("/hn", async (_req, res) => {
const response = await client.responses.create({
model: "gpt-5.5",
instructions: INSTRUCTIONS,
tools: [
{
type: "mcp",
server_label: "browserless",
server_url: "https://mcp.browserless.io/mcp",
headers: {
Authorization: `Bearer ${BROWSERLESS_API_KEY}`,
},
require_approval: "never",
},
],
input: "Fetch the top 10 stories from https://news.ycombinator.com",
});
res.type("application/json").send(response.output_text);
});
app.listen(PORT, () => {
console.log(`Listening on http://localhost:${PORT}`);
});
```
Add `"type": "module"` to your `package.json` so the `import` statements work.
### Run it
```bash
node --env-file=.env server.js
```
```bash
curl http://localhost:3000/hn
# → [
# { "rank": 1, "title": "Show HN: …", "url": "https://…", "points": 412 },
# …
# ]
```
### How it works
1. Express receives `GET /hn`.
2. The server calls `responses.create` with the `mcp` tool pointing at `https://mcp.browserless.io/mcp`.
3. OpenAI fetches the MCP tool list, the model picks the right Browserless tool (typically [`browserless_smartscraper`](/mcp/rest-api-tools#browserless_smartscraper)), and OpenAI executes the call server-side against `https://news.ycombinator.com`.
4. The scraped page comes back to the model, which extracts the top 10 stories into the JSON shape requested by `instructions`.
5. `response.output_text` is piped straight to the HTTP response — one-shot, no persistence.
### Multi-turn state
For a chat-style endpoint, persist the response ID per session and pass it on the next call:
```js
const response = await client.responses.create({
model: "gpt-5.5",
previous_response_id: lastResponseId, // from the previous turn
tools: [/* same mcp tool block — must be re-sent every call */],
input: userMessage,
});
lastResponseId = response.id;
```
OpenAI persists the conversation server-side under that ID, so you only store the string.
## Managed integration: Agents SDK
The [OpenAI Agents SDK](https://openai.github.io/openai-agents-js/) wraps the Responses API in an `Agent` abstraction with built-in tracing, handoffs to other agents, and richer multi-turn ergonomics. The MCP tool config moves from a raw `tools[]` entry to the `hostedMcpTool` helper.
Reach for this when you want a longer-running agent process, multi-agent orchestration, or just structured tracing of every tool call.
### Install
```bash
npm install @openai/agents express
```
### `server.js`
```js
const PORT = process.env.PORT ?? 3000;
const OPENAI_API_KEY = process.env.OPENAI_API_KEY || "";
const BROWSERLESS_API_KEY = process.env.BROWSERLESS_API_KEY || "";
const INSTRUCTIONS =
"You are a news scraper. Use the browserless tools to load the Hacker News front page and return the top 10 stories as a JSON array. Each item must have the shape { rank, title, url, points }. Reply with ONLY the JSON array — no markdown fences, no commentary.";
setDefaultOpenAIKey(OPENAI_API_KEY);
setTracingExportApiKey(OPENAI_API_KEY);
const app = express();
const agent = new Agent({
name: "HN Scraper",
model: "gpt-5.5",
instructions: INSTRUCTIONS,
tools: [
hostedMcpTool({
serverLabel: "browserless",
serverUrl: "https://mcp.browserless.io/mcp",
headers: {
Authorization: `Bearer ${BROWSERLESS_API_KEY}`,
},
requireApproval: "never",
}),
],
});
app.get("/hn", async (_req, res) => {
const result = await run(
agent,
"Fetch the top 10 stories from https://news.ycombinator.com",
);
res.type("application/json").send(result.finalOutput ?? "[]");
});
app.listen(PORT, () => {
console.log(`Listening on http://localhost:${PORT}`);
});
```
### Run it
```bash
node --env-file=.env server.js
curl http://localhost:3000/hn
```
### What you get over the raw Responses path
- **Tracing.** Every tool call, retry, and handoff is exported to OpenAI's traces dashboard out of the box.
- **Handoffs.** Define multiple `Agent` instances and let the model route between them (e.g. one for scraping, one for summarization).
- **Session helpers.** Pass `previousResponseId` or accumulate input arrays without managing the wire format yourself.
- **Guardrails.** Built-in input/output validation hooks for production use.
Trade-off: another dependency, and an extra abstraction between you and the underlying Responses API.
## Stealth, CAPTCHAs, and regional endpoints
Both paths route through the same hosted MCP server, so [stealth mode](/baas/bot-detection/stealth), [automatic CAPTCHA solving](/baas/bot-detection/captchas), and [residential proxies](/baas/bot-detection/proxies) all apply.
To pin to a regional endpoint, add the `x-browserless-api-url` header alongside the bearer:
```js
headers: {
Authorization: `Bearer ${BROWSERLESS_API_KEY}`,
"x-browserless-api-url": "https://production-lon.browserless.io",
},
```
See the [MCP setup page](/mcp/browserless-mcp-server/setup) for the full list of configuration options.
## Resources
- [OpenAI Responses API — MCP tool guide](https://platform.openai.com/docs/guides/tools-remote-mcp)
- [OpenAI Agents SDK (JS) documentation](https://openai.github.io/openai-agents-js/)
- [Browserless MCP setup](/mcp/browserless-mcp-server/setup)
- [REST API tools](/mcp/rest-api-tools)
- [Browser agent](/mcp/browser-agent)
- [Connection URLs](/overview/connection-urls)
## FAQ & Troubleshooting
The request hangs forever
The default value for `require_approval` (Responses API) / `requireApproval` (Agents SDK) is `"always"`, which makes the API return `mcp_approval_request` items and wait for you to approve each tool call. Set it to `"never"` on the MCP tool config so the loop runs to completion.
"Unknown tool type: mcp"
The `mcp` tool type requires a current model. Use `gpt-5.5` (or later); older completion-only models reject the entry.
Tools "disappear" between calls (Responses API)
OpenAI does not persist tool configuration server-side on the raw Responses API. Re-send the full `tools[]` array on every `responses.create` call, even when using `previous_response_id`. The Agents SDK handles this for you because tools are bound to the `Agent` instance.
401 from the MCP server
The bearer is sent fresh on every call and never stored. Double-check that `BROWSERLESS_API_KEY` is loaded into the process and that the `Authorization: Bearer …` header is on the MCP tool config, not on the outer request.
Use /mcp, not /sse
The Browserless MCP endpoint is `https://mcp.browserless.io/mcp` (Streamable HTTP). The legacy `/sse` path will not work with either the Responses API's MCP client or the Agents SDK's `hostedMcpTool`.
## Next steps
use BrowserQL for advanced browser automation
---
# opencode
URL: https://docs.browserless.io/ai-integrations/opencode
# opencode
[opencode](https://opencode.ai) is an open-source terminal coding agent with no built-in browser. This guide adds one through MCP: managed cloud sessions with stealth, automatic CAPTCHA solving, and residential proxies, configured with one entry in `opencode.json` and one API token.
- A Browserless API token from your [account dashboard](https://browserless.io/account/)
- [opencode](https://opencode.ai/docs/) installed
- Node.js, only if you use the [Playwright MCP alternative](#alternative-playwright-mcp-over-a-cdp-endpoint)
## Why Browserless as opencode's browser
opencode's built-in tools are `bash`, `edit`, `write`, `read`, `grep`, `glob`, `lsp`, `apply_patch`, `skill`, `todowrite`, `webfetch`, `websearch`, and `question`. None of them drive a browser. `webfetch` retrieves a URL and hands back its content, which is enough for reading documentation, but it can't log in, click through a multi-step flow, wait on a JavaScript-rendered view, or get past bot detection. The [feature request for a built-in browser tool](https://github.com/anomalyco/opencode/issues/27541) was closed as not planned, so there's no first-party path coming.
That changes what "remote browser" means here. In an agent that ships its own browser tool, a hosted provider is a swap; in opencode it's the whole capability. Adding the Browserless MCP server gives opencode fourteen tools that cover the gap:
- `browserless_agent` can preserve cookies and page state through logins, multi-step forms, and pagination. In v1.33.0+, [multi-call sessions require first-call opt-in](/mcp/browser-agent#session-lifetime): set `keepSessionAlive: true`, then echo the returned `sessionId` on later calls.
- `browserless_smartscraper` runs cascading strategies on every request: direct fetch, then proxy, then headless browser, then CAPTCHA solving, until the content returns.
- The browsers run on Browserless's cloud, not the machine running opencode. One API token covers stealth, residential proxies, and CAPTCHA solving, with no separate provider accounts.
- The remaining tools cover search, crawling, site mapping, exports, Lighthouse audits, and account usage. See the [full tool list](/mcp/browserless-mcp-server/setup#tools).
## Step 1: Add the server to `opencode.json`
The Browserless MCP server is remote, so it needs only a URL and your token. Keep the token in your environment rather than the config file:
```bash
```
Then add the server to `opencode.json` in your project root, or to `~/.config/opencode/opencode.json` to make it available everywhere:
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"browserless": {
"type": "remote",
"url": "https://mcp.browserless.io/mcp",
"headers": {
"Authorization": "Bearer {env:BROWSERLESS_API_TOKEN}"
}
}
}
}
```
Use `{env:VAR}`, not `$VAR` or `${VAR}`. opencode does its own substitution on config values and doesn't expand shell syntax inside JSON strings, so a `${...}` placeholder reaches Browserless verbatim as the Bearer value and gets rejected.
The hosted server speaks Streamable HTTP, which is what opencode uses for `"type": "remote"`. There's no local process, Node, or Docker involved.
### Optional: sign in with OAuth instead of a token
opencode enables OAuth on remote MCP servers by default, and the hosted Browserless server supports it. Drop the `headers` block and authenticate interactively:
```bash
opencode mcp auth browserless
```
opencode runs the OAuth flow with PKCE, registers a client dynamically, and stores the credentials outside your project config. Prefer this if `opencode.json` is committed to version control, since nothing token-shaped ends up in the repo.
## Step 2: Verify the tools loaded
Check that opencode connected to the server. `opencode mcp list` prints every configured server with its connection status, so `browserless` should be listed and connected:
```bash
opencode mcp list
```
Then start a session and ask what it can reach:
```text
Which MCP tools do you have available right now?
```
opencode namespaces MCP tools as `_`, so with the server keyed `browserless` they appear as `browserless_browserless_agent`, `browserless_browserless_smartscraper`, and so on. The doubled prefix is expected: opencode prepends the server key to tool names that already start with `browserless_`. If it bothers you, key the server as something shorter, like `bl`, and the tools read `bl_browserless_agent`.
If the list is empty, restart opencode. Config changes aren't picked up mid-session.
## Step 3: Try it on a real task
Give opencode something `webfetch` can't do, so the difference is visible:
```text
Use the Browserless smartscraper to scrape https://www.browserless.io/pricing
and list each plan with its unit allowance, then tell me which strategy
the scraper needed.
```
```text
Use the Browserless agent to open https://docs.browserless.io, navigate to
the BrowserQL quickstart, and summarize the setup steps.
```
The second prompt is the one worth watching. With `keepSessionAlive: true` on the first call and `sessionId` echoed thereafter, `browserless_agent` holds the session open, so opencode can read the page and decide where to click next without losing state.
### Optional: tell opencode what the infrastructure handles
Browserless solves CAPTCHAs in the background, which can take a few seconds. Without context, an agent sees the challenge in the page and either tries to click it or reports that it's blocked. Add this to `AGENTS.md` in your project root, or `~/.config/opencode/AGENTS.md` for every project:
```md
## Browser automation
Browser tools run on Browserless cloud infrastructure with stealth and
automatic CAPTCHA solving enabled.
- Don't click or try to solve CAPTCHA elements. They're solved for you.
- If you see a CAPTCHA or challenge page, wait 15-30 seconds and look again.
Report it only if it's still there after 60 seconds.
- Don't add your own anti-detection workarounds. They conflict with stealth.
```
## Alternative: Playwright MCP over a CDP endpoint
If you want Playwright's `browser_*` tool semantics instead, register Microsoft's [Playwright MCP](https://github.com/microsoft/playwright-mcp) as a local server and point it at a Browserless CDP endpoint:
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"playwright-browserless": {
"type": "local",
"command": [
"npx",
"-y",
"@playwright/mcp@latest",
"--cdp-endpoint",
"wss://production-sfo.browserless.io/stealth?token={env:BROWSERLESS_API_TOKEN}&solveCaptchas=true"
]
}
}
}
```
This runs `@playwright/mcp` on your machine, but the browser it drives is still a Browserless cloud session. The endpoint URL is what turns the features on:
| Segment | Purpose |
|---------|---------|
| `production-sfo.browserless.io` | Regional endpoint. Also `production-lon` and `production-ams` for the EU |
| `/stealth` | [Stealth route](/baas/bot-detection/stealth). Hides automation signals and spoofs fingerprints |
| `token=` | Your Browserless API token |
| `solveCaptchas=true` | [Solves CAPTCHAs](/baas/bot-detection/captchas) in real time, at the infrastructure layer |
Add `&timeout=300000` for tasks that run longer than the 30-second default, and `&proxy=residential` for sites with IP reputation checks. The [Claude Code + Playwright MCP](/ai-integrations/claude-code-playwright-mcp) page covers the full parameter set, the tool list, and the CAPTCHA-handling system prompt. Everything on it applies here; only the registration step differs.
We recommend the hosted MCP server over this route for most work. Playwright MCP gives you primitives (navigate, click, type), while `browserless_agent` and `browserless_smartscraper` handle unblocking and retries per request instead of per script.
## FAQ & Troubleshooting
opencode doesn't list any Browserless tools
Run `opencode mcp list` to see whether the server connected. If it's missing entirely, `opencode.json` failed to parse. Check it with `cat opencode.json | jq .`. If it's listed but not connected, the usual causes are a URL typo (the endpoint must be exactly `https://mcp.browserless.io/mcp`) or a bad token. If the server connected before you edited the config, restart opencode; config changes don't apply to a running session.
The server rejects the token, or returns 401
Check the substitution syntax first. opencode expands `{env:BROWSERLESS_API_TOKEN}` but leaves `$BROWSERLESS_API_TOKEN` and `${BROWSERLESS_API_TOKEN}` untouched, so the shell-style forms arrive at the server as literal text. An unset variable is a quieter version of the same failure: `{env:...}` resolves to an empty string, and the server sees `Authorization: Bearer` with nothing after it. Confirm the variable is exported in the shell you launch opencode from with `echo $BROWSERLESS_API_TOKEN`.
Can I point an opencode CDP browser plugin at Browserless instead?
Not without changes to the plugin. The community CDP plugins take a `browser_url` per tool call, which looks like it should accept a Browserless endpoint, but they're built around a locally launched Chrome. [`opencode-chrome-devtools`](https://github.com/different-ai/opencode-browser) discovers tabs by requesting `/json/list`, which Browserless doesn't expose because it provisions a browser per connection rather than keeping a list of open tabs. It then rebuilds each WebSocket URL from the host and path alone, dropping the `?token=` query string that authenticates the session. Use the MCP route on this page, or [Playwright MCP](#alternative-playwright-mcp-over-a-cdp-endpoint), which passes the full endpoint URL through to the browser.
Isn't opencode web the browser feature?
No. `opencode web` starts a headless opencode server with a web interface, so you drive opencode *from* a browser. It doesn't give opencode a browser to drive. The two get conflated in search results for "opencode browser", so it's worth being explicit about which one you're after.
Long-running tasks time out
Browserless sessions default to 30 seconds. Add `timeout` to the connection URL on the Playwright MCP route (`&timeout=300000` for five minutes). On the hosted MCP server, break the work into several `browserless_agent` calls rather than one long one. Set `keepSessionAlive: true` on the first call and echo `sessionId` on later calls to preserve page state; see [session lifetime](/mcp/browser-agent#session-lifetime).
What do MCP sessions cost?
Each tool call opens a browser session that consumes units based on session time, plus proxy traffic and CAPTCHA solving if used. See [unit consumption](/overview/unit-consumption#mcp-session-cost) for the breakdown.
## Next steps
the full CDP endpoint reference for the alternative route
---
# Stagehand Integration
URL: https://docs.browserless.io/ai-integrations/stagehand
# Stagehand Integration
[Stagehand](https://github.com/browserbase/stagehand) is an open-source AI browser automation framework that lets you control web browsers using natural language and code. By connecting Stagehand to Browserless, you get reliable cloud-hosted browsers without managing Chrome infrastructure yourself, complete with stealth mode, residential proxies, and enterprise-grade reliability.
- Node.js 18 or later
- Browserless API token (available in your [account dashboard](https://browserless.io/account/))
- An LLM API key (Anthropic, OpenAI, etc.)
## Step-by-Step Setup
Go to your Browserless account dashboard and copy your API token.
Then set your environment variables:
**.env file:**
```text
BROWSERLESS_API_KEY=your-browserless-token
ANTHROPIC_API_KEY=your-anthropic-key
```
**Command line:**
```bash
export BROWSERLESS_API_KEY=your-browserless-token
export ANTHROPIC_API_KEY=your-anthropic-key
```
**npm:**
```bash
npm install @browserbasehq/stagehand zod
```
**pnpm:**
```bash
pnpm add @browserbasehq/stagehand zod
```
Pass the Browserless WebSocket URL directly to Stagehand's cdpUrl config:
```javascript
import { Stagehand } from "@browserbasehq/stagehand";
const stagehand = new Stagehand({
env: "LOCAL",
localBrowserLaunchOptions: {
cdpUrl: `wss://production-sfo.browserless.io?token=${process.env.BROWSERLESS_API_KEY}`,
},
model: "anthropic/claude-sonnet-4-5",
});
await stagehand.init();
```
Use Stagehand's page methods with the Browserless-powered browser:
```javascript
import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod";
const stagehand = new Stagehand({
env: "LOCAL",
localBrowserLaunchOptions: {
cdpUrl: `wss://production-sfo.browserless.io?token=${process.env.BROWSERLESS_API_KEY}`,
},
model: "anthropic/claude-sonnet-4-5",
});
await stagehand.init();
const page = stagehand.context.pages()[0];
// Navigate to Browserless
await page.goto("https://www.browserless.io");
// act() - Click on Documentation
await stagehand.act("click on the Docs link in the navigation");
// extract() - Get documentation sections
const docs = await stagehand.extract(
"extract the main documentation categories or sections",
z.object({
sections: z.array(z.object({
title: z.string(),
description: z.string().optional(),
})),
})
);
console.log("Documentation sections:", docs.sections);
// Clean up when done
await stagehand.close();
```
## Why use Browserless with Stagehand
- **Stealth mode**: bypass bot detection by adding `/stealth` to the endpoint URL
- **Residential proxies**: route traffic through real residential IPs to avoid blocks
- **Global regions**: choose from US West (San Francisco), Europe (London), or Europe (Amsterdam) endpoints for lower latency
- **No infrastructure**: skip managing Chrome installations, updates, or scaling
- **Parallel sessions**: run multiple browser sessions simultaneously
- **Enterprise reliability**: 99.9% uptime SLA with automatic failover
## Resources
- [Stagehand Documentation](https://docs.stagehand.dev)
- [Browserless Connection Options](/overview/connection-urls)
- [Stealth Mode](/baas/bot-detection/stealth)
- [Proxy Configuration](/baas/bot-detection/proxies)
- [Stagehand GitHub Repository](https://github.com/browserbase/stagehand)
## FAQ & Troubleshooting
How do I connect Stagehand to Browserless?
Set `localBrowserLaunchOptions.cdpUrl` to your Browserless WebSocket URL (`wss://production-sfo.browserless.io?token=YOUR_TOKEN`) when creating the `Stagehand` instance, as shown in step 3 above.
Which LLM models can I use with Stagehand?
Stagehand accepts any model string in `provider/model` format, such as `anthropic/claude-sonnet-4-5` or `openai/gpt-4o`. Set the matching API key as an environment variable (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.) for whichever provider you use.
Stagehand's act() or extract() can't find the right element
Use the `/stealth` endpoint instead of the default one in your `cdpUrl` if the site is blocking automated browsers. See [stealth mode](/baas/bot-detection/stealth) for configuration details. If the page loads dynamic content, make sure you `await` navigation and any async rendering before calling `act()` or `extract()`.
## Next steps
all supported AI frameworks and tools
---
# AI & Agent Integrations Overview
URL: https://docs.browserless.io/ai-integrations/start
# AI & Agent Integrations
Browserless gives your AI a managed, stealth-enabled browser to plan, act, and observe the web. Pick the integration that fits your stack.
## Agentic Browsing
### MCP (Model Context Protocol)
Connect MCP-compatible clients directly to Browserless over the Model Context Protocol (MCP).
- [MCP Overview](/mcp/overview) – Compare the two Browserless MCP servers and pick the right one
- [Browserless MCP Server](/mcp/browserless-mcp-server/setup) – Full browser automation: scrape, screenshot, PDF, crawl, and run custom code from any MCP client
- [Browserless Docs MCP](/mcp/browserless-docs-mcp) – Query Browserless documentation directly from your IDE or AI tool
### Agent Frameworks
Use Browserless as the browser your agent controls.
- [Browser Use](/ai-integrations/browser-use/python) – Agentic browsing in Python
- [Stagehand](/ai-integrations/stagehand) – Natural language and code browser automation
- [LangChain](/ai-integrations/langchain) – Browserless loaders inside chains and agents
- [AgentKit](/ai-integrations/agentkit) – Fault-tolerant AI agents with Browserless browser tools via Inngest
- [Agent Browser](/ai-integrations/agent-browser) – Headless browser automation CLI for AI agents
- [OpenClaw](/ai-integrations/open-claw) – Local AI assistant with cloud-powered browser execution
### AI SDKs & APIs
Build agents and tool-calling flows with Browserless as a browser tool.
- [Vercel AI SDK](/ai-integrations/vercel-ai-sdk) – Browser tools for Next.js AI handlers
- [Claude Agent SDK](/ai-integrations/claude-agent-sdk) – Autonomous Claude agents with stealth browsing and CAPTCHA solving
- [OpenAI SDK](/ai-integrations/openai) – Browserless tools via the OpenAI Responses API MCP connector
- [Anthropic SDK](/ai-integrations/anthropic) – Browserless tools via the Anthropic Messages API MCP connector
### AI Tools & Interfaces
Extend AI tools and IDEs with a cloud browser.
- [Claude Code Plugin](/ai-integrations/claude-code-plugin) – Browserless MCP server installed as a Claude Code plugin
- [Hermes Agent](/ai-integrations/hermes-agent) – Browserless as the browser for NousResearch's open-source agent via MCP
- [opencode](/ai-integrations/opencode) – A browser for the terminal coding agent that ships without one
- [Claude Code + Playwright MCP](/ai-integrations/claude-code-playwright-mcp) – Control a stealth browser from Claude Code via Playwright MCP
- [Anthropic Computer Use](/ai-integrations/computer-use/anthropic-computer-use) – Claude's screenshot-and-action loop backed by Browserless cloud browsers
- [OpenAI Computer Use](/ai-integrations/computer-use/openai-cua) – OpenAI CUA screenshot-driven automation on Browserless
- [Gemini Computer Use](/ai-integrations/computer-use/gemini-computer-use) – Google Gemini's screenshot-and-action loop on Browserless, with 0–1000 coordinate denormalization
## Workflow & Automation
Call Browserless as a reliable API step inside no-code and low-code tools.
- [n8n](/ai-integrations/n8n) – Drag-and-drop workflows with Browserless REST and BQL
- [Make.com](/ai-integrations/make) – No-code automation calling Browserless
- [Zapier](/ai-integrations/zapier) – Trigger Browserless actions from Zapier apps
## FAQ & Troubleshooting
How do I connect my agent to Browserless?
It depends on the integration type. CDP-based agent frameworks (like Browser Use or Stagehand) connect using a Browserless WebSocket URL (`wss://production-sfo.browserless.io/chromium?token=YOUR_TOKEN`) as the browser endpoint. MCP clients connect to a Browserless MCP server URL with your token instead, and AI SDKs and no-code tools call Browserless's REST or function APIs as a tool. See the section above that matches your tool for the exact connection details.
My agent is getting blocked by bot detection
Use the [Browserless Agent](/mcp/browser-agent) instead of a plain Puppeteer/Playwright connection – it runs on Browserless's managed, stealth-enabled browser infrastructure with residential proxies built in, so most bot detection is handled without extra configuration.
## Next steps
use BrowserQL for advanced browser automation
---
# Browserless templates for Zapier
URL: https://docs.browserless.io/ai-integrations/zapier
# Using Browserless with Zapier
Use Zapier to orchestrate Browserless through our [REST APIs](/rest-apis/intro). This will allow you to trigger real Chrome sessions to take screenshots, generate PDFs, fetch HTML, run BQL flows, or execute custom functions, then pass results to apps like Google Drive, Slack, or Gmail.
There are two ways to use Browserless with Zapier:
- **Browserless Zapier Integration**: our custom app with built‑in actions like Screenshot, PDF, Content, Stats, Scrape, and BQL. No paid Zapier account required.
- **Webhooks by Zapier**: call Browserless REST/BQL endpoints directly with Webhooks by Zapier which requires a paid Zapier account.
- A Browserless API token from your [account dashboard](https://browserless.io/account/)
## Browserless Zapier Integration
Connect your Browserless account and use the prebuilt actions, then fill in the required fields.
### Connect Browserless
1. In Zapier, create a Zap and add the Browserless app as an action.
2. Click “Connect a new account”.
3. Enter:
- Account Name: any label to recognize your account
- API token: your Browserless API token from the dashboard
4. Zapier will verify the token by calling the Browserless version endpoint.
### Built-in REST APIs
- Screenshot: capture a screenshot from a URL.
- PDF: generate a PDF from a URL.
- Content: fetch rendered HTML/content from a URL.
- Scrape: scrape data from a URL.
- Stats: retrieve account stats.
- BQL: run multi‑step BrowserQL flows.
Each action exposes “Quick Options” (URL, `waitUntil`, flags) and an “Advanced - Raw JSON” input that overrides quick options if you define the full JSON body.
## Webhooks by Zapier
Use Webhooks by Zapier to run our REST APIs as you would with any HTTP Request and implement our REST APIs directly.
> **Warning**
> Webhooks by Zapier requires a paid Zapier account.
For the templates below, remember to replace `YOUR_API_TOKEN_HERE` with your actual Browserless API token.
### Example workflow: Daily Visual Check
**Trigger** — Schedule by Zapier: run every hour
**Action** — Webhooks by Zapier (POST):
- **URL**: `https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE&headless=false&stealth=true&--window-size=1440,1000&--lang=en-US`
- **Payload (JSON)**:
```json
{
"url": "https://www.ebay.com/sch/i.html?_nkw=nintendo+switch",
"options": {
"fullPage": true,
"type": "png",
"viewport": { "width": 1440, "height": 1000 }
}
}
```
**Optional** — Gmail (Send Email): attach the file taken from Browserless.
### Implementing REST APIs
You can implement all our REST APIs using Webhooks by Zapier as documented below.
Zapier has an AI Beta "Copilot", you can copy paste the below information and it'll configure the webhook for you.
#### Screenshot
**Use Webhooks by Zapier → POST** to `/screenshot` for visual monitoring, thumbnails, and documentation images.
**Zapier Webhook POST Configuration**
1. Add **Webhooks by Zapier** to your Zap
2. Choose **POST** as the event
3. Set **URL** to `https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE`
4. Set **Payload Type** to `JSON`
5. Add these data fields:
- `url`: `https://www.example.com`
[Learn more about the Screenshot API](/rest-apis/screenshot-api)
#### PDF Generation
**Use Webhooks by Zapier → POST** to `/pdf` for printable reports and archival documents.
**Zapier Webhook POST Configuration**
1. Add **Webhooks by Zapier** to your Zap
2. Choose **POST** as the event
3. Set **URL** to `https://production-sfo.browserless.io/pdf?token=YOUR_API_TOKEN_HERE`
4. Set **Payload Type** to `JSON`
5. Add these data fields:
- `url`: `https://www.example.com`
[Learn more about the PDF API](/rest-apis/pdf-api)
#### Content Extraction
**Use Webhooks by Zapier → POST** to `/content` for rendered HTML analysis and web scraping.
**Zapier Webhook POST Configuration**
1. Add **Webhooks by Zapier** to your Zap
2. Choose **POST** as the event
3. Set **URL** to `https://production-sfo.browserless.io/content?token=YOUR_API_TOKEN_HERE`
4. Set **Payload Type** to `JSON`
5. Add these data fields:
- `url`: `https://www.example.com`
[Learn more about the Content API](/rest-apis/content)
#### Unblock
**Use Webhooks by Zapier → POST** to `/unblock` for bypassing anti-bot measures and accessing protected content.
**Zapier Webhook POST Configuration**
1. Add **Webhooks by Zapier** to your Zap
2. Choose **POST** as the event
3. Set **URL** to `https://production-sfo.browserless.io/unblock?token=YOUR_API_TOKEN_HERE`
4. Set **Payload Type** to `JSON`
5. Add these data fields:
- `url`: `https://www.example.com`
- `cookies`: `true`
- `browserWSEndpoint`: `true`
- `content`: `true`
- `screenshot`: `true`
[Learn more about the Unblock API](/rest-apis/unblock)
#### Browser Query Language (BQL)
**Use Webhooks by Zapier → POST** to `/chrome/bql` for multi-step BrowserQL automation workflows.
**Zapier Webhook POST Configuration**
1. Add **Webhooks by Zapier** to your Zap
2. Choose **POST** as the event
3. Set **URL** to `https://production-sfo.browserless.io/chrome/bql?token=YOUR_API_TOKEN_HERE`
4. Set **Payload Type** to `JSON`
5. Add these data fields:
- `query`: `mutation FormExample {\n goto(url: \"https://www.browserless.io/practice-form\") {\n status\n }\n select(selector:\"#Contact-Subject\",value:\"support\"){ time } \n typeEmail: type(text: \"john@email.com\", selector: \"#Email\") {\n time\n }\n typeMessage: type(\n selector: \"#Message\"\n text: \"Hello world!\"\n ) {\n time\n }\n solve(\n type: cloudflare\n ){\n solved\n }\n waitForTimeout(time:3000){time}\n screenshot{\n base64\n }\n}`
- `variables`: `{}`
- `operationName`: `FormExample`
[Learn more about BQL](/browserql/start)
#### Function
**Use Webhooks by Zapier → POST** to `/function` for custom JavaScript execution in a real browser context.
**Zapier Webhook POST Configuration**
1. Add **Webhooks by Zapier** to your Zap
2. Choose **POST** as the event
3. Set **URL** to `https://production-sfo.browserless.io/function?token=YOUR_API_TOKEN_HERE`
4. Set **Payload Type** to `Raw`
5. Set **Content Type** to `application/javascript`
6. Add this JavaScript to the **Data** field:
```javascript
await page.goto("https://example.com/");
const url = await page.content();
const buffer = await page.pdf({ format: "A4" });
const base64PDF = buffer.toString('base64');
const screenshot = await page.screenshot({ encoding: "base64" });
return {
data: {
url,
screenshot,
base64PDF
},
type: "application/json",
};
}
```
[Learn more about the Function API](/rest-apis/function)
## FAQ & Troubleshooting
Do I need a paid Zapier account?
No, not for the [Browserless Zapier Integration](#browserless-zapier-integration) app with its built-in actions (Screenshot, PDF, Content, Stats, Scrape, BQL). A paid plan is only required for [Webhooks by Zapier](#webhooks-by-zapier), which calls the REST/BQL endpoints directly.
The webhook returns 401 Unauthorized
Check that `token=YOUR_API_TOKEN_HERE` is on the request URL. If you're using the Browserless Zapier Integration app instead, re-connect your account and re-enter the token; Zapier verifies it against the version endpoint on save.
The screenshot or PDF response isn't usable in later Zap steps
Binary buffers don't pass cleanly between Zap steps. Add `"encoding": "base64"` to the request body (as shown in the Screenshot API) so Browserless returns a base64 string you can attach directly to an email or file-upload step.
## Next steps
explore every Browserless REST endpoint
---
# API Reference Overview
URL: https://docs.browserless.io/api-reference
# API Reference Overview
Full specifications for every Browserless endpoint. Use these references to look up exact parameters, types, and response shapes.
## FAQ & Troubleshooting
How do I authenticate API requests?
Pass your API token as a `?token=` query parameter in the request URL. Some endpoints also accept it in the `Authorization` header.
Where can I test API endpoints?
Use the [API playground](/rest-apis/api-playground) to test endpoints interactively with your token.
## Next steps
test endpoints interactively
---
# CDP Extensions
URL: https://docs.browserless.io/api-reference/cdp-extensions
# CDP Extensions
Browserless-specific Chrome DevTools Protocol methods you call via `cdp.send()` on a page's CDP session in Puppeteer or Playwright. They extend standard CDP with live URLs, captcha solving, session reconnect, recording, file transfer, and page identification. Several also emit CDP events (listen with `cdp.on()`).
- A Browserless API token from your [account dashboard](https://browserless.io/account/)
- An existing WebSocket connection to Browserless via Puppeteer or Playwright
- Familiarity with creating a CDP session (`page.createCDPSession()` in Puppeteer, `page.context().newCDPSession(page)` in Playwright)
Captcha solving, reconnect, and recording are each gated on their own feature flag / query param and return an `error` in the result when unavailable.
## Usage
```javascript
const browser = await puppeteer.connect({ browserWSEndpoint: '...' });
const [page] = await browser.pages();
const cdp = await page.createCDPSession();
// Command: get a live URL for debugging
const { liveURL } = await cdp.send('Browserless.liveURL', { quality: 70 });
// Event: react to an auto-detected captcha
cdp.on('Browserless.captchaFound', ({ type, status }) => {});
```
## Commands
### Browserless.liveURL
Mints a temporary URL that opens a live, interactive view of the current page in any browser. For debugging, QA, or human-in-the-loop workflows. The Live URL `timeout` sets the URL's validity and post-disconnect keep-alive window. The browser and viewer still end at the existing [session deadline](/baas/best-practices#session-duration-limits); minting a Live URL never resets or extends that deadline. If `timeout` is longer than the time the session has left, the URL is minted for the remaining time instead, and a session with no time left returns `error: "The browser session has expired."`. Each Live URL accepts up to five concurrent viewers (a sixth connection receives HTTP `429`). It binds to the page whose CDP session sends it. For one link per tab, see [Multi-Tab Workflows](/baas/advanced-configurations/hybrid-automation-configurations#multi-tab-workflows).
Call via CDP: `cdp.send('Browserless.liveURL', { quality: 70 })`
Returns: `{ error, liveURLId, liveURL, timeout }` (`error` is `null` on success; `timeout` is the lifetime actually applied, in ms).
| Parameter | Type | Default | Description |
|---|---|---|---|
| `quality` | `number` | `70` | Stream image quality (1-100). |
| `type` | `string` | `"jpeg"` | Stream frame image format. |
| `timeout` | `number` | `30000` | How long (ms) the minted URL stays valid, capped to the session's remaining time. |
| `interactable` | `boolean` | `true` | Allow the viewer to click/type into the page. |
| `resizable` | `boolean` | `true` | Allow the viewer to resize the viewport. |
| `showBrowserInterface` | `boolean` | `false` | Show browser chrome around the page. |
| `compressed` | `boolean` | `true` | Compress the stream. |
| `emulateComponents` | `boolean` | `true` | Emulate UI components in the stream. |
### Browserless.closeLiveURL
Closes a live URL opened with `liveURL`, freeing server resources. Called automatically when the session ends.
Call via CDP: `cdp.send('Browserless.closeLiveURL', { liveURLId })`
Returns: `{ error, liveURLId }`.
| Parameter | Type | Description |
|---|---|---|
| `liveURLId` | `string` | Required. The `liveURLId` returned by `liveURL`. |
### Browserless.solveCaptcha
Detects a CAPTCHA on the current page and attempts to solve it via a third-party solving service (reCAPTCHA v2/v3, Cloudflare Turnstile, and more). Requires captcha solving to be available for the session.
Call via CDP: `cdp.send('Browserless.solveCaptcha')`
Returns: `{ ok, captchaFound, solveAttempted, solved, token?, message?, error? }`.
### Browserless.reconnect
Returns a WebSocket URL for reconnecting to this browser session after disconnecting. The browser stays alive server-side for `timeout` ms. Requires reconnect to be enabled; on hosted Cloud plans a `timeout` above the plan's [maximum session duration](/baas/session-management/standard-sessions#reconnection-timeout-limits) returns an `error` instead of being silently clamped. The browser still terminates at its original session deadline even if the TTL has time left.
Call via CDP: `cdp.send('Browserless.reconnect', { timeout: 60000 })`
Returns: `{ auth, error, browserWSEndpoint }` (`browserWSEndpoint` is `null` on error).
| Parameter | Type | Description |
|---|---|---|
| `timeout` | `number` | How long (ms) to keep the browser alive after disconnect. Defaults to the deployment's configured connection timeout. |
| `auth` | `string` | Optional auth token echoed back and required on the reconnect handshake. |
### Browserless.pageId
Returns Browserless's stable identifier for the current page target, useful for routing and correlating a page across reconnects.
Call via CDP: `cdp.send('Browserless.pageId')`
Returns: `{ pageId: '...' }`.
### Browserless.startRecording
Starts server-side video recording of the page. Requires connecting with `?record=true`. Refused after a credential has been filled on the session (the recording could capture the secret).
Call via CDP: `cdp.send('Browserless.startRecording', { width, height })`
Returns: `{ recording, error? }`.
| Parameter | Type | Description |
|---|---|---|
| `width` | `number` | Optional recording width. |
| `height` | `number` | Optional recording height. |
### Browserless.stopRecording
Stops the recording started with `startRecording` and returns the video. Requires `?record=true`.
Call via CDP: `cdp.send('Browserless.stopRecording', { encoding: 'base64' })`
Returns the encoded recording, or `{ error }`.
| Parameter | Type | Description |
|---|---|---|
| `encoding` | `string` | `"binary"` or `"base64"`. |
### Browserless.stopSessionRecording
Stops rrweb session-replay capture, then processes and uploads the events. Requires connecting with `?replay=true`.
Call via CDP: `cdp.send('Browserless.stopSessionRecording')`
Returns: `{ error }` (`null` on success).
### Browserless.uploadFile
Uploads one or more files into a file `` on the page, matched by selector. Total decoded size is capped per request.
Call via CDP: `cdp.send('Browserless.uploadFile', { selector, files })`
Returns: `{ ok, error? }`.
| Parameter | Type | Description |
|---|---|---|
| `selector` | `string` | Required. CSS selector for the file input. |
| `files` | `array` | Required. Objects of `{ name, content, mimeType? }` where `content` is base64 and `mimeType` is inferred from `name` if omitted. |
### Browserless.setDownloadEnabled
Toggles streaming of completed downloads back to the client as `Browserless.fileDownloaded` events. Off by default, so download bytes never flow unless you opt in.
Call via CDP: `cdp.send('Browserless.setDownloadEnabled', { enabled: true })`
Returns: `{ ok, enabled }`.
| Parameter | Type | Description |
|---|---|---|
| `enabled` | `boolean` | Whether to emit `fileDownloaded` events. |
## Events
Subscribe with `cdp.on('', handler)`.
### Browserless.heartbeat
Periodic keep-alive emitted on each attached session at the server's heartbeat interval. No params.
### Browserless.captchaFound
Emitted when a CAPTCHA is auto-detected on a page.
Params: `{ type, status }` — `status` is `"solving"` when auto-solve is on, otherwise `"found"`.
### Browserless.captchaAutoSolved
Emitted after an auto-solve attempt completes (only when auto-solving is enabled).
Params: the solve result `{ found, solved, token, time, error? }`.
### Browserless.fileDownloaded
Emitted when a download completes, if enabled via `setDownloadEnabled`. Mirrored to every attached session.
Params: `{ filename, mimeType, size, data }` (`data` base64), or `{ filename, mimeType, size, error: 'FileTooLarge', maxBytes }` when the file exceeds the transfer limit.
### Browserless.liveComplete
Emitted at most once per mint created with `Browserless.liveURL`, including links nobody opens. Params: `{ liveURLId: string, reason: LiveURLCompleteReason }`.
| Reason | Meaning |
| --- | --- |
| `timeout` | The link's lifetime expired. |
| `closed` | The link was explicitly closed, replaced by a new mint on the same page, or lost its anchor page without a replacement. |
| `viewerDisconnected` | The last viewer disconnected and stayed gone for two seconds, including credential-protection teardown. |
| `userDone` | Reserved for a future viewer “Done” action; not currently produced. |
| `userFailed` | Reserved for a future viewer “Couldn't finish” action; not currently produced. |
Every reason consumes that mint's one completion. After an ordinary `viewerDisconnected`, the URL remains reopenable until expiry while the browser session is available, but later visits or expiry produce no further completion. Reconnecting within the two-second grace period, such as during a viewer reload, cancels the pending disconnect completion. **Credential-protection teardown is an exception:** after a stored credential is filled, new viewers are blocked for that session, so reopening cannot cancel or re-arm completion. Completion does not prove the human task succeeded; verify the page state before continuing.
Delivery requires a CDP session attached to the page; earlier events are not replayed. Browser shutdown records closure internally but does not send this event. `Browserless.reconnect` IDs and links minted through BQL or HTTP do not produce this CDP event. Existing zero-argument listeners continue to work unchanged.
When re-minting on the same page, **register the new listener after the mint response, then share the URL**. Re-minting reuses the ID and emits `closed` for the superseded mint; a listener armed before the response can catch that old completion. See [handling completion reasons](/baas/monitor-sessions/hybrid-automation#handle-completion-reasons).
### Browserless.liveViewerConnected
Emitted each time a viewer WebSocket attaches to a live URL, including additional viewers and reconnects. Both `/live/*` and `/chromium/live/*` viewer routes emit this event.
Params: `{ liveURLId: string }`, identifying the live URL returned by `Browserless.liveURL`. The event is delivered to attached CDP sessions for that URL's page, not other pages. It signals attachment, not that the viewer has finished interacting or received a frame.
Register the listener before sharing the URL; earlier attachments are not replayed:
```js
const cdp = await page.createCDPSession();
cdp.on('Browserless.liveViewerConnected', ({ liveURLId }) => {
console.log('Viewer connected:', liveURLId);
});
const { liveURL } = await cdp.send('Browserless.liveURL');
// Share liveURL with the viewer.
```
## FAQ & Troubleshooting
Why does liveURL or reconnect return an error instead of a URL?
The commands have different requirements. For `liveURL`, an error means invalid authentication, a runtime failure, or an invalid timeout — a `timeout` that isn't a whole number of milliseconds above 0, or that exceeds your plan's [maximum session duration](/baas/best-practices#session-duration-limits), is rejected when the URL is minted. `reconnect` has its own reconnect ceiling, and recording requires `?record=true` and a plan that includes recording. When a command is unavailable, it returns `error` instead of the expected field (`liveURL`, `browserWSEndpoint`, and so on).
Why isn't my cdp.on() handler firing?
CDP extension events are scoped to the session that triggered them, so `cdp.on()` has to be attached to the same `CDPSession` you called `cdp.send()` on, before the triggering action happens. A handler attached after the event already fired, or attached to a different page's CDP session, never receives it.
Why does Browserless.startRecording fail after I've already filled in a login form?
Recording is refused once a credential has been filled on the session, since the recording could capture the secret. Start recording before any authentication step, or use a separate session for the recorded portion of the flow.
## Next steps
BrowserQL schema, OpenAPI spec, and the CLI
---
# Advanced Hybrid Automation Configurations
URL: https://docs.browserless.io/baas/advanced-configurations/hybrid-automation-configurations
This page is the comprehensive reference for all `Browserless.liveURL` options and advanced patterns. It covers bandwidth tuning, viewport control, recording integration, CAPTCHA fallback handling, multi-stage workflows, and error recovery.
If you are new to hybrid automation, start with the [Hybrid Automation](/baas/monitor-sessions/hybrid-automation) guide.
- A Browserless API token from your [account dashboard](https://browserless.io/account/)
- Puppeteer or Playwright installed locally
> **Session limits**
> The `timeout` values in this guide have to fit within your plan's [maximum session duration](/baas/best-practices#session-duration-limits), and a LiveURL created partway through a session can't extend the browser's existing deadline.
## Bandwidth and Quality Optimization
Fine-tune live sessions for different network conditions and device capabilities.
**Puppeteer:**
```js
const { liveURL } = await cdp.send('Browserless.liveURL', {
quality: 30, // Optimized for mobile/slow connections
type: 'jpeg', // Better compression than PNG
timeout: 300000, // 5 minutes for complex workflows
});
```
**Playwright:**
```js
const { liveURL } = await cdpSession.send('Browserless.liveURL', {
quality: 30, // Optimized for mobile/slow connections
type: 'jpeg', // Better compression than PNG
timeout: 300000, // 5 minutes for complex workflows
});
```
## Advanced Viewport Control
Control viewport behavior and browser UI visibility for live sessions.
By default, the live URL viewport resizes to match the end user's screen. Set `resizable: false` to lock the browser at its current viewport dimensions. The live URL client preserves the aspect ratio.
**Puppeteer:**
```js
const { liveURL } = await cdp.send('Browserless.liveURL', {
resizable: false, // Maintain fixed viewport
interactable: true, // Allow user interaction
showBrowserInterface: false, // Hide browser tabs and UI
});
```
**Playwright:**
```js
const { liveURL } = await cdpSession.send('Browserless.liveURL', {
resizable: false, // Maintain fixed viewport
interactable: true, // Allow user interaction
showBrowserInterface: false, // Hide browser tabs and UI
});
```
## Multi-Tab Workflows
`Browserless.liveURL` binds to the page whose CDP session sends it, so one CDP session per tab gives you one independent link per tab.
Open both tabs before sharing either link. These recipes keep each tab's `liveURLId` so you can close its link with `Browserless.closeLiveURL` later.
Open both links and keep the original tabs open until both viewers finish. These minimal examples wait for each tab's `Browserless.liveComplete` event. An unopened link or a detached tab listener can leave that wait pending, even after the browser disconnects. In production, add an application timeout and disconnect handling. The five-minute browser session timeout doesn't settle the application promises.
**Puppeteer:**
```js
import puppeteer from 'puppeteer-core';
const browser = await puppeteer.connect({
browserWSEndpoint: 'wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE&timeout=300000',
});
try {
const tab1 = await browser.newPage();
await tab1.goto('https://example.com');
const tab2 = await browser.newPage();
await tab2.goto('https://browserless.io');
const liveViews = await Promise.all([tab1, tab2].map(async (page) => {
const cdp = await page.createCDPSession();
const complete = new Promise((resolve) => cdp.once('Browserless.liveComplete', resolve));
const { error, liveURL, liveURLId } = await cdp.send('Browserless.liveURL', {
timeout: 300000,
});
if (error) throw new Error(error);
return { cdp, liveURL, liveURLId, complete };
}));
liveViews.forEach(({ liveURL }, index) => console.log(`Tab ${index + 1}:`, liveURL));
await Promise.all(liveViews.map(({ complete }) => complete));
} finally {
await browser.close();
}
```
**Playwright:**
```js
import { chromium } from 'playwright-core';
const browser = await chromium.connectOverCDP(
'wss://production-sfo.browserless.io/chromium/stealth?token=YOUR_API_TOKEN_HERE&timeout=300000'
);
try {
const [context] = browser.contexts();
const tab1 = await context.newPage();
await tab1.goto('https://example.com');
const tab2 = await context.newPage();
await tab2.goto('https://browserless.io');
const liveViews = await Promise.all([tab1, tab2].map(async (page) => {
const cdp = await context.newCDPSession(page);
const complete = new Promise((resolve) => cdp.once('Browserless.liveComplete', resolve));
const { error, liveURL, liveURLId } = await cdp.send('Browserless.liveURL', {
timeout: 300000,
});
if (error) throw new Error(error);
return { cdp, liveURL, liveURLId, complete };
}));
liveViews.forEach(({ liveURL }, index) => console.log(`Tab ${index + 1}:`, liveURL));
await Promise.all(liveViews.map(({ complete }) => complete));
} finally {
await browser.close();
}
```
**How per-tab links behave**
- Minting again for the **same tab** returns the **same link** (same `liveURLId`) with the new options and timeout, and disconnects anyone currently watching it. Minting for a **different tab** returns a separate link, and the two coexist.
- With `showBrowserInterface` off, a link switches to **any new tab** opened after the viewer connected, anywhere in the browser, including other browser contexts. Every open link switches, not only the one whose tab opened a popup. Open all the tabs you want to stream **before sharing** the links. A mode that pins a link to its tab is planned.
- Closing a tab **doesn't end** its link. The link moves to another tab it can see, and ends only when none are left. Call `Browserless.closeLiveURL` with that tab's `liveURLId` before closing the tab if you don't want this.
- Filling a stored credential closes all links for the browser. See [Viewer behavior and limits](/baas/monitor-sessions/embedding-live-url#viewer-behavior-and-limits).
If you'd rather hand out a single link that shows every tab, set `showBrowserInterface: true`. The viewer shows live tab titles and favicons, lets users switch and close tabs, provides back and forward controls, and adds a draggable page scrollbar. This option injects UI overlay code into the page, which may increase CAPTCHA challenge likelihood on some sites.
**Puppeteer:**
```js
const { liveURL } = await cdp.send('Browserless.liveURL', {
showBrowserInterface: true, // Show all tabs and browser UI
quality: 50,
timeout: 300000, // 5 minutes for complex workflows
});
```
**Playwright:**
```js
const { liveURL } = await cdpSession.send('Browserless.liveURL', {
showBrowserInterface: true, // Show all tabs and browser UI
quality: 50,
timeout: 300000, // 5 minutes for complex workflows
});
```
## Mobile Viewers
LiveURL links work when the end user opens them on a phone or tablet, but support is limited to single-touch interaction:
- **Touch input**: A single-finger tap maps to a mouse click, and a single-finger drag maps to mouse scroll. Multi-touch gestures (including pinch-to-zoom and two-finger pan) are not forwarded to the remote browser.
- **Virtual keyboard**: When the LiveURL is opened on a device identified as mobile by its user agent, Browserless automatically injects an on-screen keyboard into the remote page so end users can type.
- **Remote viewport**: With the default `resizable: true`, the remote browser's viewport is set to the end user's device width and height, which can cause target sites to render their mobile layout. Use `resizable: false` to keep the viewport you set in your automation script; the stream will be letterboxed to fit the device while preserving aspect ratio.
- **Local zoom**: The LiveURL page does not disable the browser's native pinch-zoom, so end users can zoom the LiveURL page itself, but this only scales the local canvas — it does not zoom the remote page.
- **Bandwidth**: Lower `quality` (for example `quality: 30`) and keep `type: 'jpeg'` to reduce data usage on cellular connections.
## Clipboard Support
The viewer supports copy and paste in both directions. Ctrl-based shortcuts work on Windows and Linux, and Command-based shortcuts work on macOS. When you [embed the Live URL](/baas/monitor-sessions/embedding-live-url), add `allow="clipboard-read; clipboard-write"` to the iframe so the browser can grant clipboard access.
Depending on the end user's browser and operating system configuration, clipboard access may require explicit user permission or interaction before it can be used within the LiveURL session.
## Read-Only Monitoring Sessions
Create view-only sessions for compliance monitoring or training by setting `interactable: false`. The viewer sees the browser but cannot click, type, or interact. Browserless enforces this on the server by dropping viewer input before it reaches the remote browser; client-side CSS isn't a security boundary. See [View-only embedding](/baas/monitor-sessions/embedding-live-url#view-only-embedding).
**Puppeteer:**
```js
const { liveURL } = await cdp.send('Browserless.liveURL', {
interactable: false, // View-only mode
quality: 80, // Higher quality for monitoring
timeout: 1800000, // 30 minutes for extended monitoring
});
// Share with compliance team or supervisors
console.log('Monitoring URL (read-only):', liveURL);
```
**Playwright:**
```js
const { liveURL } = await cdpSession.send('Browserless.liveURL', {
interactable: false, // View-only mode
quality: 80, // Higher quality for monitoring
timeout: 1800000, // 30 minutes for extended monitoring
});
// Share with compliance team or supervisors
console.log('Monitoring URL (read-only):', liveURL);
```
## Session Recording Integration
Combine screen recording with live sessions to capture an audit trail. Set `record=true` as a query parameter when connecting to the browser endpoint. See [Screen Recording](/baas/monitor-sessions/screen-recording) for full details.
**Puppeteer:**
```js
// Start recording before creating live session
await cdp.send('Browserless.startRecording');
const { liveURL } = await cdp.send('Browserless.liveURL', {
timeout: 300000
});
// Wait for session completion
await new Promise(resolve => cdp.on('Browserless.liveComplete', resolve));
// Save recording (see recording docs for details)
const recording = await cdp.send('Browserless.stopRecording');
fs.writeFileSync('audit-trail.webm', Buffer.from(recording.value, 'binary'));
```
**Playwright:**
```js
// Start recording before creating live session
await cdpSession.send('Browserless.startRecording');
const { liveURL } = await cdpSession.send('Browserless.liveURL', {
timeout: 300000
});
// Wait for session completion
await new Promise(resolve => cdpSession.on('Browserless.liveComplete', resolve));
// Save recording (see recording docs for details)
const recording = await cdpSession.send('Browserless.stopRecording');
fs.writeFileSync('audit-trail.webm', Buffer.from(recording.value, 'binary'));
```
## CAPTCHA Handling with Hybrid Fallback
Try automated CAPTCHA solving first, then fall back to a live URL for human intervention if the solver fails. Listen for the `Browserless.captchaFound` event to trigger this flow. For full CAPTCHA solver documentation, see [CAPTCHA Solving](/baas/bot-detection/captchas).
**Puppeteer:**
```js
// Set up CAPTCHA detection before navigation
cdp.on('Browserless.captchaFound', async () => {
console.log('CAPTCHA detected, attempting automatic solve');
const { solved } = await cdp.send('Browserless.solveCaptcha');
if (!solved) {
// Fall back to human intervention
const { liveURL } = await cdp.send('Browserless.liveURL', {
timeout: 120000 // 2 minutes for CAPTCHA solving
});
console.log('Manual CAPTCHA solving needed:', liveURL);
}
});
```
**Playwright:**
```js
// Set up CAPTCHA detection before navigation
cdpSession.on('Browserless.captchaFound', async () => {
console.log('CAPTCHA detected, attempting automatic solve');
const { solved } = await cdpSession.send('Browserless.solveCaptcha');
if (!solved) {
// Fall back to human intervention
const { liveURL } = await cdpSession.send('Browserless.liveURL', {
timeout: 120000 // 2 minutes for CAPTCHA solving
});
console.log('Manual CAPTCHA solving needed:', liveURL);
}
});
```
## Multi-Stage Workflows
Chain multiple hybrid sessions for complex business processes. Each stage alternates between automated steps and human handoffs.
`Browserless.liveComplete` means the link completed, not that the person finished the task: timeout, cancellation, or replacement can also trigger it. Verify each stage's expected page state before advancing. Viewer-driven completion waits about two seconds after the last viewer disconnects, allowing a quick reload without completing the link.
**Puppeteer:**
```js
const multiStageWorkflow = async () => {
const browser = await puppeteer.connect({
browserWSEndpoint: 'wss://production-sfo.browserless.io?token=YOUR_TOKEN'
});
try {
const page = await browser.newPage();
const cdp = await page.createCDPSession();
await page.goto('https://practice.expandtesting.com/inputs');
await page.waitForSelector('input[name="input-number"]');
// Stage 1: User fills the number input via liveURL
let { liveURL } = await cdp.send('Browserless.liveURL', {
timeout: 180000 // 3 minutes for number entry
});
console.log('Stage 1 - Enter a number:', liveURL);
await new Promise(resolve => cdp.on('Browserless.liveComplete', resolve));
const numberEntered = await page.$eval(
'input[name="input-number"]',
input => input.value !== '' && input.checkValidity()
);
if (!numberEntered) {
throw new Error('Stage 1 ended without a valid number');
}
// Stage 2: Automated filling of text and password fields
await page.type('input[name="input-text"]', 'Automated text entry');
await page.type('input[name="input-password"]', 'SecurePass123');
console.log('Stage 2 - Automated text and password fields completed');
// Stage 3: User fills the date input via liveURL
({ liveURL } = await cdp.send('Browserless.liveURL', {
timeout: 300000 // 5 minutes for date selection
}));
console.log('Stage 3 - Select a date:', liveURL);
await new Promise(resolve => cdp.on('Browserless.liveComplete', resolve));
const dateEntered = await page.$eval(
'input[name="input-date"]',
input => input.value !== '' && input.checkValidity()
);
if (!dateEntered) {
throw new Error('Stage 3 ended without a valid date');
}
console.log('Multi-stage workflow completed successfully');
} finally {
await browser.close();
}
};
```
**Playwright:**
```js
const multiStageWorkflow = async () => {
const browser = await playwright.chromium.connectOverCDP(
'wss://production-sfo.browserless.io?token=YOUR_TOKEN'
);
try {
const context = browser.contexts()[0];
const page = await context.newPage();
const cdpSession = await context.newCDPSession(page);
await page.goto('https://practice.expandtesting.com/inputs');
await page.waitForSelector('input[name="input-number"]');
// Stage 1: User fills the number input via liveURL
let { liveURL } = await cdpSession.send('Browserless.liveURL', {
timeout: 180000 // 3 minutes for number entry
});
console.log('Stage 1 - Enter a number:', liveURL);
await new Promise(resolve => cdpSession.on('Browserless.liveComplete', resolve));
const numberEntered = await page.$eval(
'input[name="input-number"]',
input => input.value !== '' && input.checkValidity()
);
if (!numberEntered) {
throw new Error('Stage 1 ended without a valid number');
}
// Stage 2: Automated filling of text and password fields
await page.fill('input[name="input-text"]', 'Automated text entry');
await page.fill('input[name="input-password"]', 'SecurePass123');
console.log('Stage 2 - Automated text and password fields completed');
// Stage 3: User fills the date input via liveURL
({ liveURL } = await cdpSession.send('Browserless.liveURL', {
timeout: 300000 // 5 minutes for date selection
}));
console.log('Stage 3 - Select a date:', liveURL);
await new Promise(resolve => cdpSession.on('Browserless.liveComplete', resolve));
const dateEntered = await page.$eval(
'input[name="input-date"]',
input => input.value !== '' && input.checkValidity()
);
if (!dateEntered) {
throw new Error('Stage 3 ended without a valid date');
}
console.log('Multi-stage workflow completed successfully');
} finally {
await browser.close();
}
};
```
## Error Recovery and Resilience
Implement retry logic for production hybrid automation. This helper retries on transient failures but exits immediately on permanent errors like invalid tokens or rate limits.
```js
const createResilientLiveSession = async (cdp, options = {}) => {
const { timeout = 300000, quality = 50, maxRetries = 2 } = options;
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
const { liveURL, liveURLId } = await cdp.send('Browserless.liveURL', {
timeout,
quality,
type: 'jpeg'
});
console.log(`Live session created on attempt ${attempt}`);
return { liveURL, liveURLId };
} catch (error) {
console.log(`Live session attempt ${attempt} failed:`, error.message);
// Don't retry on permanent errors
if (error.message.includes('Invalid token') ||
error.message.includes('Rate limit exceeded')) {
throw error;
}
if (attempt === maxRetries) {
throw new Error(`Failed to create live session after ${maxRetries} attempts: ${error.message}`);
}
// Brief wait before retry
await new Promise(resolve => setTimeout(resolve, 1000));
}
}
};
(async () => {
let browser = null;
try {
const BROWSERLESS_TOKEN = 'YOUR_API_TOKEN_HERE';
browser = await puppeteer.connect({
browserWSEndpoint: `wss://production-sfo.browserless.io?token=${BROWSERLESS_TOKEN}`,
});
const page = await browser.newPage();
await page.goto('https://practicetestautomation.com/practice-test-login/');
const cdp = await page.createCDPSession();
const { liveURL, liveURLId } = await createResilientLiveSession(cdp, {
timeout: 300000,
quality: 50,
maxRetries: 3
});
console.log('Live URL created:', liveURL);
console.log('Live URL ID:', liveURLId);
await new Promise((resolve) => {
cdp.on('Browserless.liveComplete', resolve);
});
console.log('Live session completed');
} catch (error) {
console.error('Error:', error);
} finally {
if (browser) {
await browser.close();
}
}
})();
```
## FAQ & Troubleshooting
Why am I getting a 403 Forbidden error?
Your API token is missing or expired. Pass it as a `?token=` query parameter in the WebSocket or HTTP URL. Verify the token in your [account dashboard](https://browserless.io/account/).
My script works locally but fails on Browserless
Local browser settings may differ from the Browserless environment. Use `launch` parameters to match your local setup (viewport, user agent, timezone). See [launch parameters](/baas/launch-options) for the full list.
## Next steps
Configure residential and third-party proxy services for geographic targeting
---
# Playwright Configurations
URL: https://docs.browserless.io/baas/advanced-configurations/playwright-customizations
This page covers advanced Playwright configurations for users already familiar with basic Playwright connections to Browserless. If you haven't set up your basic connection yet, start with our [Quickstart guide](/baas/quick-start).
- A Browserless API token from your [account dashboard](https://browserless.io/account/)
- Playwright installed locally
Here are some advanced configurations you can explore:
### Advanced Connection Methods
#### Understanding Connection Types
The basic guide covers connectOverCDP as the recommended method. For detailed comparison of connection methods and when to use each, see our [Browser Versions documentation](/baas/versions#playwrights-versioning).
#### Multi-Browser Support
For Firefox and WebKit automation, you must use the connect method since CDP is Chrome-only. Complete examples and browser-specific configurations are available in our [Browser Versions guide](/baas/versions#playwrights-versioning).
### Performance Optimization
#### Package Optimization
Switch to playwright-core for production deployments to reduce bundle size:
```bash
npm install playwright-core
```
#### Error Handling and Retry Logic
Implement error handling and retry logic for production environments:
```js
async function withRetry(operation, maxRetries = 3) {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
return await operation();
} catch (error) {
if (attempt === maxRetries) throw error;
console.log(`Attempt ${attempt} failed, retrying...`);
await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
}
}
}
```
### Advanced Session Management
#### Timeout Configuration
For custom session timeouts and launch parameters, see our comprehensive [Launch parameters documentation](/baas/launch-options).
#### Browser Context Configuration
Advanced context options for stealth, geolocation, and viewport settings:
```js
const context = await browser.newContext({
extraHTTPHeaders: {
'User-Agent': 'Custom User Agent String'
},
viewport: { width: 1920, height: 1080 },
deviceScaleFactor: 1,
geolocation: { longitude: -122.4194, latitude: 37.7749 },
permissions: ['geolocation']
});
```
> **Note**
> Advanced browser context options (stealth, geolocation, viewport, etc.) are only available when using `connectOverCDP`. These options are not supported with the standard `connect` method.
### Integration with Browserless Features
#### Stealth Mode Integration
For comprehensive bot detection bypass, see our [Stealth documentation](/baas/bot-detection/stealth). Basic stealth integration:
```js
const TOKEN = "YOUR_API_TOKEN_HERE";
const browser = await chromium.connectOverCDP(
`wss://production-sfo.browserless.io/chromium/stealth?token=${TOKEN}`
);
```
#### Proxy Configuration
For built-in residential proxies and advanced proxy setups, see our [Proxies documentation](/baas/bot-detection/proxies). Context-level proxy configuration for third-party providers:
```js
const context = await browser.newContext({
proxy: {
server: "http://proxy-provider.com:8080",
username: "username",
password: "password"
}
});
```
#### PuppeteerSharp Proxy Considerations
When using PuppeteerSharp with the `--proxy-server` flag in the WebSocket connection URL, calling `CreateBrowserContextAsync()` creates a new incognito context that does not inherit the proxy settings from the initial browser connection. As a result, requests will default to the Browserless IP instead of routing through your configured proxy.
To ensure the page correctly uses the proxy configured in the WebSocket connection URL, avoid creating a separate browser context. Instead of:
```csharp
var browserContext = await browser.CreateBrowserContextAsync();
var page = await browserContext.NewPageAsync();
```
Use this approach:
```csharp
var page = await browser.NewPageAsync();
```
This ensures the page inherits the proxy configuration from the WebSocket connection URL.
### Version Compatibility
Ensure your Playwright version matches Browserless supported versions. Check the [versions compatibility page](/baas/versions) for current supported versions.
## connect vs connectOverCDP
Playwright offers two ways to connect to Browserless. Each method uses a different protocol and unlocks a different feature set.
| Method | Playwright API | Browserless Path | Protocol |
|---|---|---|---|
| Playwright native | `playwright.chromium.connect({ wsEndpoint })` | `/chromium/playwright`, `/firefox/playwright`, `/webkit/playwright` | Playwright's own browser server protocol |
| CDP mode | `playwright.chromium.connectOverCDP(url)` | `/chromium`, `/chrome`, `/` | Chrome DevTools Protocol |
### Playwright Native (connect)
Connect with `playwright.chromium.connect()` and a `/playwright` path. This mode uses Playwright's native protocol.
```javascript
const browser = await chromium.connect(
"wss://production-sfo.browserless.io/chromium/playwright?token=YOUR_API_TOKEN_HERE"
);
const page = await browser.newPage();
await page.goto("https://example.com");
await browser.close();
```
### CDP Mode (connectOverCDP)
Connect with `playwright.chromium.connectOverCDP()` and a CDP path. This mode bridges Playwright over the Chrome DevTools Protocol.
```javascript
const browser = await chromium.connectOverCDP(
"wss://production-sfo.browserless.io/chromium?token=YOUR_API_TOKEN_HERE"
);
const context = browser.contexts()[0];
const page = await context.newPage();
await page.goto("https://example.com");
await browser.close();
```
### Feature Comparison
| Capability | Playwright Native (`connect`) | CDP Mode (`connectOverCDP`) |
|---|---|---|
| Browser extensions | Not supported | Supported (loaded in default context) |
| BQL interoperability | Not supported | Supported |
| Captcha solving | Not supported | Supported |
| `page.route()` network interception | Supported | Not supported (use CDP `Fetch` domain) |
| `APIRequestContext` | Supported | Not supported |
| Firefox / WebKit | Supported | Not supported (Chromium only) |
| Proxy via `browser.newContext()` | Supported | Not supported in default context |
| Proxy via query parameter | Supported | Supported |
| Multiple independent contexts | Supported | Limited (one default context from browser) |
| Connection overhead | Lower | Higher |
> **Default context**
> When you call `connectOverCDP`, the browser already has one context open. This is the **default context**. Access it with `browser.contexts()[0]`. Extensions, cookies, and launch-level settings live in this context. Calling `browser.newContext()` creates a separate context that does not inherit extensions or launch-level proxy configuration. Use the default context when you need access to those features.
### When to Use Each
**Use connect (Playwright native) when you need:**
- `page.route()` for request interception, mocking, or blocking
- `APIRequestContext` for HTTP requests that share browser state
- Firefox or WebKit browser engines
- Lower connection overhead for high-throughput workloads
- Multiple independent browser contexts with separate proxy configs
**Use connectOverCDP when you need:**
- Browser extensions loaded in the session
- BQL queries against the running browser
- Built-in captcha solving
- Interop with Puppeteer or other CDP-based tools in the same session
Default to CDP mode (`connectOverCDP`) for most automation tasks. It supports extensions, BQL, and captcha solving. Switch to Playwright native (`connect`) when you need `page.route()`, `APIRequestContext`, or non-Chromium browsers.
## FAQ & Troubleshooting
Why am I getting a 403 Forbidden error?
Your API token is missing or expired. Pass it as a `?token=` query parameter in the WebSocket or HTTP URL. Verify the token in your [account dashboard](https://browserless.io/account/).
My script works locally but fails on Browserless
Local browser settings may differ from the Browserless environment. Use `launch` parameters to match your local setup (viewport, user agent, timezone). See [launch parameters](/baas/launch-options) for the full list.
## Next steps
Set up residential and third-party proxies for enhanced privacy and geo-targeting
---
# Puppeteer Configurations
URL: https://docs.browserless.io/baas/advanced-configurations/puppeteer-customizations
This page covers advanced Puppeteer configurations for users who have already established basic connections to Browserless. If you haven't set up a basic Puppeteer connection yet, start with our [Quickstart](/baas/quick-start) guide.
- A Browserless API token from your [account dashboard](https://browserless.io/account/)
- Puppeteer installed locally
Here are some advanced configurations you can explore:
### Advanced Monitoring and Debugging
#### CDP Performance Monitoring
Access Chrome DevTools Protocol to collect real-time browser performance metrics through direct CDP session communication:
```js
const client = await page.target().createCDPSession();
await client.send('Performance.enable');
// Get performance metrics
const metrics = await client.send('Performance.getMetrics');
console.log('Performance metrics:', metrics);
```
#### Network Request Monitoring
Implement comprehensive network activity tracking through Puppeteer's event-driven request/response lifecycle monitoring:
```js
page.on('request', request => {
console.log('→', request.method(), request.url());
});
page.on('response', response => {
// Check if response indicates a non-success status (outside 200-299)
if (!response.ok()) {
console.log('✗', response.status(), response.url());
}
});
page.on('requestfailed', request => {
// Log network-level failures: timeouts, DNS errors, connection refused
console.log('✗ Failed:', request.url(), request.failure().errorText);
});
```
### Performance Optimization
#### Package Optimization
Switch to puppeteer-core for production deployments to reduce bundle size:
```bash
npm install puppeteer-core
```
For comprehensive performance optimization techniques including network round-trip reduction and navigation settings, see our [Best Practices guide](/baas/best-practices#reduce-network-round-trips).
### Advanced Launch Configuration
For complex Chrome flags and launch parameters using the JSON `launch` parameter approach, see the [Launch parameters documentation](/baas/launch-options#the-launch-object).
### Proxy Configuration and Cost Optimization
For comprehensive proxy configuration including residential proxies, geographic targeting, and bandwidth cost optimization, see [Proxies Documentation](/baas/bot-detection/proxies).
### Regional Optimization
For regional endpoint optimization and performance considerations, see [Best Practices](/baas/best-practices#avoid-network-latency).
## FAQ & Troubleshooting
Why am I getting a 403 Forbidden error?
Your API token is missing or expired. Pass it as a `?token=` query parameter in the WebSocket or HTTP URL. Verify the token in your [account dashboard](https://browserless.io/account/).
My script works locally but fails on Browserless
Local browser settings may differ from the Browserless environment. Use `launch` parameters to match your local setup (viewport, user agent, timezone). See [launch parameters](/baas/launch-options) for the full list.
## Next steps
full parameter reference for Chrome flags and configurations
---
# Best Practices
URL: https://docs.browserless.io/baas/best-practices
This page covers essential practices for creating reliable Puppeteer and Playwright scripts with Browserless. Follow these patterns to avoid common pitfalls, improve performance, and keep your automation code maintainable.
- A Browserless API token from your [account dashboard](https://browserless.io/account/)
- Puppeteer or Playwright installed locally
## Concurrency limits
Always close your browser sessions properly to avoid hitting concurrency limits:
**Puppeteer:**
```js
import puppeteer from "puppeteer-core";
const browser = await puppeteer.connect({
browserWSEndpoint: `wss://production-sfo.browserless.io/?token=YOUR_API_TOKEN_HERE`,
});
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
// Your automation logic here
} catch (error) {
console.error('Automation failed:', error.message);
} finally {
// Always close the browser, even on errors
if (browser.isConnected()) {
await browser.close();
}
}
```
**Playwright:**
```js
import playwright from "playwright";
const browser = await playwright.chromium.connectOverCDP(
`wss://production-sfo.browserless.io/?token=YOUR_API_TOKEN_HERE`
);
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
// Your automation logic here
} catch (error) {
console.error('Automation failed:', error.message);
} finally {
// Always close the browser, even on errors
if (browser.isConnected()) {
await browser.close();
}
}
```
### Concurrency limits by plan
| Plan | Concurrency (Monthly) | Concurrency (Yearly) |
|------|----------------------|---------------------|
| Free | 2 | 2 |
| Prototyping | 5 | 10 |
| Starter | 30 | 40 |
| Scale | 80 | 100 |
| Enterprise | Custom | Custom |
## Timeouts
### Session timeouts
Control the maximum duration of a browser session using the `timeout` parameter in your connection URL. The value is in milliseconds.
**Puppeteer:**
```js
import puppeteer from "puppeteer-core";
const browser = await puppeteer.connect({
browserWSEndpoint: `wss://production-sfo.browserless.io/?token=YOUR_API_TOKEN_HERE&timeout=300000`,
// 300000ms = 5 minutes
});
```
**Playwright:**
```python
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.connect_over_cdp(
"wss://production-sfo.browserless.io/?token=YOUR_API_TOKEN_HERE&timeout=300000"
# 300000ms = 5 minutes
)
```
### Session duration limits
Maximum session duration depends on your subscription plan:
To increase your limit, see the [pricing page](https://www.browserless.io/pricing).
## Avoid network latency
Call the nearest regional endpoint to reduce network latency and improve performance. Using a geographically closer endpoint significantly reduces connection and data transfer time. For available regional endpoints and load balancing options, see [Load Balancers](/baas/infrastructure/load-balancers#cloud-subscriptions-load-balancing).
## Reduce Network Round-trips
Every `await` call (e.g. `page.click()`, `page.textContent()`) is a separate WebSocket round-trip between your client and the remote browser. Five sequential `await` calls means five round-trips, each adding network latency. Wrapping the same operations in a single `page.evaluate()` executes them all inside the browser in one round-trip, returning the results together. The difference scales linearly with the number of operations.
**Puppeteer:**
```js
// DON'T DO - Multiple round-trips
const button = await page.$('.buy-now');
const buttonText = await button.getProperty('innerText');
const isVisible = await button.isIntersectingViewport();
await button.click();
// DO - Single round-trip
const result = await page.evaluate(() => {
const button = document.querySelector('.buy-now');
const buttonText = button.innerText;
const isVisible = button.offsetParent !== null;
button.click();
return { buttonText, isVisible, clicked: true };
});
```
**Playwright:**
```js
// DON'T DO - Multiple round-trips
const button = await page.locator('.buy-now');
const buttonText = await button.textContent();
const isVisible = await button.isVisible();
await button.click();
// DO - Single round-trip
const result = await page.evaluate(() => {
const button = document.querySelector('.buy-now');
const buttonText = button.textContent;
const isVisible = button.offsetParent !== null;
button.click();
return { buttonText, isVisible, clicked: true };
});
```
## Wait for the page to be ready
When is your page fully ready? It depends on the site. Some pages are usable after the initial DOM load, while others need async data or scripts to finish executing. Here are the signals you can wait for:
- **Load events** (`commit`, `load`, `domcontentloaded`, `networkidle`)
- **Specific selectors** to appear or become visible
- **Network requests** to complete
- **Custom events** fired by the page
### Wait Until the Page has Loaded
The `waitUntil` parameter in `page.goto()` controls when navigation is considered complete. Choose based on what your target content requires:
| Option | Availability | Fires when | Best for |
|--------|-------------|-----------|----------|
| `commit` | Playwright only | Response headers are parsed and session history is updated, before the document starts loading | Fastest possible signal; useful when you only need to confirm navigation started |
| `domcontentloaded` | Puppeteer, Playwright | Document content is loaded and parsed | Fast pages, static content, SPAs with client-side rendering |
| `load` | Puppeteer, Playwright | Page executes scripts and loads resources like stylesheets and images | Pages where visual completeness matters |
| `networkidle2` | Puppeteer only | No more than 2 network connections for at least 500ms | SPAs, pages with async data fetching |
| `networkidle` / `networkidle0` | Playwright (`networkidle`) / Puppeteer (`networkidle0`) | Zero network connections for at least 500ms | Strictest check, slowest option |
Start with `domcontentloaded` and only move to `networkidle2`/`networkidle` if your target content requires it. Using `networkidle0`/`networkidle` on busy pages can cause unnecessary timeouts. Use `commit` (Playwright only) when you need the earliest possible signal that navigation occurred.
For a deeper dive, see our [waitUntil blog post](https://www.browserless.io/blog/waituntil-option-for-puppeteer-and-playwright).
**Puppeteer:**
```js
import puppeteer from "puppeteer-core";
const browser = await puppeteer.connect({
browserWSEndpoint: `wss://production-sfo.browserless.io/?token=YOUR_API_TOKEN_HERE`,
});
const page = await browser.newPage();
// Fast navigation - use when you only need DOM content
await page.goto('https://example.com', {
waitUntil: 'domcontentloaded',
timeout: 30000
});
// Use networkidle2 only when you need all resources loaded
await page.goto('https://example.com', {
waitUntil: 'networkidle2',
timeout: 60000
});
```
**Playwright:**
```python
from playwright.async_api import async_playwright
async with async_playwright() as p:
browser = await p.chromium.connect_over_cdp(
"wss://production-sfo.browserless.io/?token=YOUR_API_TOKEN_HERE"
)
page = await browser.new_page()
# Fast navigation - use when you only need DOM content
await page.goto('https://example.com',
wait_until='domcontentloaded',
timeout=30000)
# Use networkidle only when you need all resources loaded
await page.goto('https://example.com',
wait_until='networkidle',
timeout=60000)
```
### Wait for Specific Selectors
Waiting for specific selectors is one of the most reliable ways to ensure your target content is ready. This approach works well for dynamic content that loads asynchronously.
**Puppeteer:**
```js
// Wait for a specific element to appear
await page.waitForSelector('.dynamic-content');
// Wait for element to be visible
await page.waitForSelector('.loading-spinner', { hidden: true });
// Wait for multiple elements
await page.waitForSelector('.product-list .product-item');
```
**Playwright:**
```python
# Wait for a specific element to appear
await page.wait_for_selector('.dynamic-content')
# Wait for element to be visible
await page.wait_for_selector('.loading-spinner', state='hidden')
# Wait for multiple elements
await page.wait_for_selector('.product-list .product-item')
```
### Wait for Network Requests
Sometimes you need to wait for specific network requests to complete before proceeding. This is useful when your target data comes from API calls.
**Puppeteer:**
```js
// Wait for a specific request to complete
await page.waitForResponse(response =>
response.url().includes('/api/data') && response.status() === 200
);
// Wait for all requests to finish
await page.waitForLoadState('networkidle');
// Wait for multiple requests
await Promise.all([
page.waitForResponse(response => response.url().includes('/api/users')),
page.waitForResponse(response => response.url().includes('/api/posts'))
]);
```
**Playwright:**
```python
# Wait for a specific request to complete
async with page.expect_response(lambda response: '/api/data' in response.url and response.status == 200):
pass
# Wait for all requests to finish
await page.wait_for_load_state('networkidle')
# Wait for multiple requests
await asyncio.gather(
page.wait_for_response(lambda response: '/api/users' in response.url),
page.wait_for_response(lambda response: '/api/posts' in response.url)
)
```
### Wait for Custom Events
Many modern web applications fire custom events when specific actions complete. You can listen for these events to know exactly when your target functionality is ready.
**Puppeteer:**
```js
// Wait for a custom event
await page.evaluate(() => {
return new Promise((resolve) => {
document.addEventListener('dataLoaded', resolve, { once: true });
});
});
// Wait for multiple custom events
await Promise.all([
page.evaluate(() => new Promise(resolve =>
document.addEventListener('userDataReady', resolve, { once: true })
)),
page.evaluate(() => new Promise(resolve =>
document.addEventListener('contentReady', resolve, { once: true })
))
]);
```
**Playwright:**
```python
# Wait for a custom event
await page.evaluate("""
() => new Promise((resolve) => {
document.addEventListener('dataLoaded', resolve, { once: true });
})
""")
# Wait for multiple custom events
await asyncio.gather(
page.evaluate("""
() => new Promise(resolve =>
document.addEventListener('userDataReady', resolve, { once: true })
)
"""),
page.evaluate("""
() => new Promise(resolve =>
document.addEventListener('contentReady', resolve, { once: true })
)
""")
)
```
## HTTP error codes
| Code | Cause | How to resolve |
|------|-------|----------------|
| **400** Bad Request | Malformed JSON, invalid fields, negative or out-of-range timeout, or colliding request arguments | Validate your payload structure and check for conflicting parameters |
| **401** Unauthorized | Missing or invalid API token, or endpoint not supported by your plan | Check that your token is correct and that your plan supports the endpoint |
| **403** Forbidden | Wrong regional endpoint or insufficient permissions. The deprecated `chrome.browserless.io` endpoint returns 403. Use `production-sfo.browserless.io` instead. | Verify you're using the correct regional endpoint for your account |
| **404** Not Found | Endpoint does not exist | Check your endpoint URL |
| **408** Request Timeout | Timeout set too low, waiting for a selector or event that never appears, or session exceeded plan limit | Increase timeout, verify your selectors exist, check session duration limits above |
| **429** Too Many Requests | Exceeding your plan's concurrency limit, usually from unclosed sessions accumulating | Close browser sessions in `finally` blocks; upgrade your plan if needed |
Failed requests appear as "Rejected" sessions in your [account dashboard](https://browserless.io/account/). To check the HTTP status code of a site navigated to by a REST API, look for the `x-response-code` and `x-response-status` response headers.
## Getting Help
If you continue to experience issues after implementing these best practices:
1. Check your [account dashboard](https://browserless.io/account/) for usage metrics
2. Contact [Browserless support](https://www.browserless.io/contact) for assistance
## FAQ & Troubleshooting
Why am I getting a 403 Forbidden error?
Your API token is missing or expired. Pass it as a `?token=` query parameter in the WebSocket or HTTP URL. Verify the token in your [account dashboard](https://browserless.io/account/).
My script works locally but fails on Browserless
Local browser settings may differ from the Browserless environment. Use `launch` parameters to match your local setup (viewport, user agent, timezone). See [launch parameters](/baas/launch-options) for the full list.
## Next steps
allowlist Browserless outbound IPs if your infrastructure restricts by IP
---
# CAPTCHA Solving
URL: https://docs.browserless.io/baas/bot-detection/captchas
Browserless detects and solves CAPTCHAs programmatically using Chrome DevTools Protocol events and commands. Use [stealth routes](/baas/bot-detection/stealth) to prevent CAPTCHAs from appearing in the first place. This page covers what to do when they still appear.
- A Browserless API token from your [account dashboard](https://browserless.io/account/)
- Puppeteer or Playwright installed locally
## How it works
The CAPTCHA system operates through Chrome DevTools Protocol (CDP) events and commands:
- **Automatic CAPTCHA solving**: Add `solveCaptchas=true` to your connection URL to monitor and solve CAPTCHAs in real-time without manual CDP commands
- **Detection**: The `Browserless.captchaFound` event fires automatically when a CAPTCHA is detected
- **Solving**: The `Browserless.solveCaptcha` command programmatically solves detected CAPTCHAs
## Automatic CAPTCHA Solving
Add `solveCaptchas=true` to your connection URL. Browserless then monitors the entire session for CAPTCHAs and solves them as they appear, including on later navigations, popups, and async-loaded forms. Listeners you attach once at the start of the session keep working across every page, so there's no need to re-attach after navigation.
You only need to wait for `Browserless.captchaAutoSolved` at points where your next action depends on a solved CAPTCHA, typically before submitting a form. The solved token is automatically injected into the page DOM, so you don't need to read or pass it yourself.
The example below starts on the 2captcha homepage (no CAPTCHA there), then clicks through to a reCAPTCHA v2 demo page. The CAPTCHA only appears after the second navigation, but because the listener was attached at the start of the session, it catches the auto-solve event without any re-attachment.
**Puppeteer:**
```js
import puppeteer from "puppeteer-core";
const TOKEN = "YOUR_API_TOKEN_HERE";
const browser = await puppeteer.connect({
browserWSEndpoint: `wss://production-sfo.browserless.io/stealth?token=${TOKEN}&proxy=residential&proxyCountry=us&solveCaptchas=true&timeout=300000`,
});
const page = await browser.newPage();
const cdp = await page.createCDPSession();
// Attach BEFORE navigation — the listener survives the whole session.
const captchaSolved = new Promise((resolve) => {
cdp.on("Browserless.captchaAutoSolved", resolve);
});
// No CAPTCHA on the homepage.
await page.goto("https://2captcha.com/", { waitUntil: "networkidle0" });
// Clicking through navigates to the reCAPTCHA v2 demo — a CAPTCHA appears here.
await page.click(
"#order-captchas > table > tbody > tr:nth-child(2) span > a:nth-child(2)"
);
// Wait for autosolve to finish before submitting.
const { solved, token, time } = await captchaSolved;
console.log({ solved, token, time });
await page.click("._actionsItem_151cx_41");
await browser.close();
```
**Playwright:**
**Javascript:**
```js
import playwright from "playwright-core";
const TOKEN = "YOUR_API_TOKEN_HERE";
const browser = await playwright.chromium.connectOverCDP(
`wss://production-sfo.browserless.io/stealth?token=${TOKEN}&proxy=residential&proxyCountry=us&solveCaptchas=true&timeout=300000`
);
// Reuse the existing context and page so Browserless CDP events are visible.
const context = browser.contexts()[0];
const page = context.pages()[0];
const cdp = await page.context().newCDPSession(page);
// Attach BEFORE navigation — the listener survives the whole session.
const captchaSolved = new Promise((resolve) => {
cdp.on("Browserless.captchaAutoSolved", resolve);
});
await page.goto("https://2captcha.com/", { waitUntil: "networkidle" });
await page.click(
"#order-captchas > table > tbody > tr:nth-child(2) span > a:nth-child(2)"
);
const result = await captchaSolved;
console.log(result);
await page.click("._actionsItem_151cx_41");
await browser.close();
```
**Python:**
```python
import asyncio
from playwright.async_api import async_playwright
TOKEN = "YOUR_API_TOKEN_HERE"
async def main():
async with async_playwright() as p:
browser = await p.chromium.connect_over_cdp(
f"wss://production-sfo.browserless.io/stealth?token={TOKEN}&proxy=residential&proxyCountry=us&solveCaptchas=true&timeout=300000"
)
# Reuse the existing context and page so Browserless CDP events are visible.
context = browser.contexts[0]
page = context.pages[0]
cdp = await page.context.new_cdp_session(page)
# Attach BEFORE navigation — the listener survives the whole session.
captcha_solved = asyncio.get_event_loop().create_future()
cdp.on(
"Browserless.captchaAutoSolved",
lambda event: captcha_solved.set_result(event) if not captcha_solved.done() else None,
)
await page.goto("https://2captcha.com/", wait_until="networkidle")
await page.click(
"#order-captchas > table > tbody > tr:nth-child(2) span > a:nth-child(2)"
)
result = await captcha_solved
print(result)
await page.click("._actionsItem_151cx_41")
await browser.close()
asyncio.run(main())
```
**Java:**
```java
import com.microsoft.playwright.*;
import com.microsoft.playwright.options.*;
import java.util.concurrent.CompletableFuture;
public class AutoCaptchaSolving {
public static void main(String[] args) throws Exception {
String TOKEN = "YOUR_API_TOKEN_HERE";
String endpoint = "wss://production-sfo.browserless.io/stealth?token=" + TOKEN
+ "&proxy=residential&proxyCountry=us&solveCaptchas=true&timeout=300000";
try (Playwright playwright = Playwright.create()) {
Browser browser = playwright.chromium().connectOverCDP(endpoint);
// Reuse the existing context and page so Browserless CDP events are visible.
BrowserContext context = browser.contexts().get(0);
Page page = context.pages().get(0);
CDPSession cdp = page.context().newCDPSession(page);
// Attach BEFORE navigation — the listener survives the whole session.
CompletableFuture captchaSolved = new CompletableFuture<>();
cdp.on("Browserless.captchaAutoSolved", event -> captchaSolved.complete(event));
page.navigate("https://2captcha.com/", new Page.NavigateOptions()
.setWaitUntil(LoadState.NETWORKIDLE));
page.click("#order-captchas > table > tbody > tr:nth-child(2) span > a:nth-child(2)");
System.out.println(captchaSolved.get());
page.click("._actionsItem_151cx_41");
browser.close();
}
}
}
```
**C#:**
```csharp
using System;
using System.Threading.Tasks;
using Microsoft.Playwright;
class Program
{
static async Task Main(string[] args)
{
var TOKEN = "YOUR_API_TOKEN_HERE";
var endpoint = $"wss://production-sfo.browserless.io/stealth?token={TOKEN}&proxy=residential&proxyCountry=us&solveCaptchas=true&timeout=300000";
var playwright = await Playwright.CreateAsync();
var browser = await playwright.Chromium.ConnectOverCDPAsync(endpoint);
// Use the first context and page so Browserless CDP events are visible.
var context = browser.Contexts[0];
var page = context.Pages[0];
var cdp = await page.Context.NewCDPSessionAsync(page);
// Attach BEFORE navigation — the listener survives the whole session.
var captchaSolved = new TaskCompletionSource