Agent-Browser Claude: Run Claude Browser Agents on Hosted Chromium

# Agent-Browser Claude: Run Claude Browser Agents on Hosted Chromium

Claude can write code, reason about tasks, and call tools—but when it needs to actually *use* the web, it needs a browser it can control. The agent-browser Claude pattern solves this by pairing Anthropic's models with a hosted Chromium runtime that speaks the Chrome DevTools Protocol (CDP). Instead of running a local Chrome instance that dies with your laptop, you connect Claude to a remote browser that stays alive, keeps its state, and scales across workers.

This guide explains how to connect Claude to a hosted browser, why the agent-browser Claude architecture matters for production workloads, and how to avoid the common failure modes that plague local browser setups.

Why Claude Needs a Dedicated Browser Runtime

Claude's tool use feature lets it call functions, read files, and execute code. When you give Claude a browser automation tool, it can navigate pages, click elements, fill forms, and extract data. But the quality of that interaction depends entirely on the browser runtime underneath.

Local browser setups fail in predictable ways:

• Session loss: When your machine sleeps, the network drops, or the process crashes, the browser session dies. Claude loses its cookies, localStorage, and login state.
• Resource contention: A single Chrome instance can consume 500MB–1GB of RAM. Running multiple parallel agents on one machine causes memory pressure and slowdowns.
• Scaling limits: You can't horizontally scale a browser that lives on your laptop. Cloud workers need to connect to a browser that exists independently of any single process.
• Debugging blind spots: When Claude makes a mistake, you need to see what happened. Local headless browsers give you logs but not visual context.

The agent-browser Claude pattern solves these problems by moving the browser into the cloud. Claude connects over CDP to a hosted Chromium instance that runs in a datacenter, persists across connections, and exposes a live viewer for debugging.

What Is Agent-Browser Claude?

Agent-browser Claude refers to the integration pattern where Claude (either Claude Code, the API, or a Claude-powered agent framework) drives a remote browser through the CDP protocol. The "agent-browser" part comes from the tooling ecosystem—like the agent-browser CLI from Vercel Labs—that gives AI agents a clean interface for browser control.

The architecture looks like this:

Claude (API or Code)
    │
    ▼
Agent-Browser Tool Layer (CLI or SDK)
    │
    ▼
CDP Connection (WebSocket)
    │
    ▼
Hosted Chromium Instance (Remote Browser)

The key insight is that Claude doesn't need to know *where* the browser runs. It just needs a stable CDP endpoint. Remote Browser provides that endpoint as a managed service, so you don't have to run your own browser infrastructure.

How to Connect Claude to Hosted Chromium

Connecting Claude to a hosted browser requires three pieces: a CDP endpoint, an authentication mechanism, and a tool layer that translates Claude's actions into browser commands.

Step 1: Create a Browser Session

With Remote Browser, you create a session through the API or dashboard. Each session is an isolated Chromium instance with its own profile, cookies, and storage.

// Create a browser session via the Remote Browser API
const response = await fetch('https://api.remote-browser.dev/v1/sessions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.REMOTE_BROWSER_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    // Optional: use a persistent profile to keep login state
    profileId: 'my-production-profile',
    // Optional: configure proxy settings for IP diversity
    proxy: {
      country: 'us'
    }
  })
});

const session = await response.json();
// session.cdpUrl contains the WebSocket endpoint for CDP
console.log(`Connect to: ${session.cdpUrl}`);

Step 2: Connect via Playwright's connectOverCDP

Playwright's connectOverCDP method is the standard way to attach to an existing Chrome instance. It works with any browser that exposes a CDP endpoint—including hosted Chromium.

import { chromium } from 'playwright';

// Connect to the hosted Chromium instance via CDP
const browser = await chromium.connectOverCDP(
  'wss://remote-browser.dev/cdp/session_abc123'
);

// Get the default context (includes existing cookies and storage)
const context = browser.contexts()[0];
const page = await context.newPage();

// Now Claude can drive this page
await page.goto('https://example.com');
await page.click('button[type="submit"]');
const result = await page.textContent('.result');

console.log(result);
await browser.close();

Step 3: Give Claude the Tool

Once you have a working browser connection, wrap it as a tool that Claude can call. The tool should accept natural language instructions and translate them into browser actions.

// Tool definition for Claude
const browserTool = {
  name: 'browser_action',
  description: 'Perform a browser action on the current page. Actions include: navigate, click, type, extract, screenshot.',
  input_schema: {
    type: 'object',
    properties: {
      action: { type: 'string', enum: ['navigate', 'click', 'type', 'extract', 'screenshot'] },
      selector: { type: 'string', description: 'CSS selector for click/type actions' },
      text: { type: 'string', description: 'Text to type or extract' },
      url: { type: 'string', description: 'URL for navigate action' }
    },
    required: ['action']
  }
};

// Claude API call with the browser tool
const response = await fetch('https://api.anthropic.com/v1/messages', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.ANTHROPIC_API_KEY,
    'anthropic-version': '2023-06-01',
    'content-type': 'application/json'
  },
  body: JSON.stringify({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 4096,
    tools: [browserTool],
    messages: [
      {
        role: 'user',
        content: 'Go to the pricing page and extract the monthly cost for the Pro plan.'
      }
    ]
  })
});

CDP vs. Playwright Driver: Which Connection Method?

When connecting Claude to a browser, you have two main options: raw CDP or the Playwright driver protocol. Both work with hosted Chromium, but they have different trade-offs.

For agent-browser Claude workloads, CDP is usually the right choice. The reason is session persistence. When Claude needs to log into a service, maintain a shopping cart, or navigate a multi-step workflow, it needs the browser state to survive between tool calls. connectOverCDP attaches to an existing browser with its full state intact.

Playwright's driver protocol creates fresh contexts by default. You can use persistent profiles, but the connection model is designed for test isolation rather than long-running agent sessions.

The official Playwright documentation on connectOverCDP confirms that this method is Chromium-only and designed for connecting to existing browser instances. That's exactly the agent-browser Claude use case.

Keeping Browser Sessions Alive Across Cloud Workers

One of the most common questions about agent-browser Claude is how to keep sessions alive when the underlying worker dies. If you're running Claude on a serverless function or a container that scales to zero, you can't hold a WebSocket connection open indefinitely.

The solution is to decouple the browser session from the worker lifecycle. Remote Browser runs each Chromium instance as a standalone process. Your worker connects, issues commands, and disconnects—but the browser keeps running.

Here's the pattern:

1. Create a session with a persistent profile ID.
2. Store the session ID in your database or queue.
3. Reconnect from any worker using the session ID.
4. The browser state persists because the profile lives on the Remote Browser side.

// Worker A: Start a task and save the session
const session = await createBrowserSession({ profileId: 'user-123' });
await db.save({ taskId: 'task-456', sessionId: session.id });

// Worker B: Pick up the task later and reconnect
const task = await db.get('task-456');
const browser = await chromium.connectOverCDP(task.sessionId);
const page = browser.contexts()[0].pages()[0];
// The page is exactly where Worker A left it

This pattern works across serverless functions, container restarts, and even different cloud providers. The browser session is infrastructure, not a process tied to a specific worker.

Scaling Playwright Browser Workloads Reliably

When you move from a single Claude session to a production workload with multiple concurrent agents, the browser infrastructure becomes the bottleneck. Here's what you need to scale reliably:

Session Isolation

Each agent should get its own browser session. Shared browsers cause cross-talk: one agent's cookies leak into another's requests, and concurrent navigation on the same page produces race conditions. Remote Browser isolates each session, so you can run dozens of agents without interference.

Resource Limits

A single Chromium tab can use 200–400MB of RAM. If you're running 20 concurrent agents, that's 4–8GB just for browser processes. Hosted Chromium handles this by allocating dedicated resources per session and reclaiming them when sessions end.

Connection Management

WebSocket connections are fragile. They drop on network hiccups, idle timeouts, and server restarts. Your agent code needs to handle reconnection gracefully. The CDP endpoint stays valid even if the WebSocket drops—you just reconnect.

Proxy Configuration

Some sites block datacenter IP ranges. If your agents need to access geo-restricted content or avoid rate limiting, you need configurable proxy settings. Remote Browser lets you specify proxy parameters at session creation, so each agent can have an appropriate IP.

Debugging Claude's Browser Actions

When Claude makes a mistake—clicking the wrong element, filling the wrong form, or getting blocked by a CAPTCHA—you need to see what happened. Text logs only tell you what Claude *intended* to do, not what the browser actually rendered.

Remote Browser includes a live viewer for each session. You can watch Claude's actions in real time or replay them after the fact. This is invaluable for:

• Debugging failed tasks: See exactly where the browser was when Claude got stuck.
• Verifying successful actions: Confirm that the form was filled correctly and the submission went through.
• Building trust: Show stakeholders that the agent is doing what you expect.

The live viewer also helps with prompt engineering. When you see Claude repeatedly failing at a specific step, you can adjust your instructions or add validation logic to the tool layer.

Production Criteria for Agent-Browser Claude

Before you put Claude browser agents into production, evaluate your setup against these criteria:

If you're building anything beyond a demo, the hosted approach wins on every operational axis.

Common Pitfalls and How to Avoid Them

Pitfall 1: Treating the Browser as Stateless

Claude's tool calls are stateless—each one is a separate API request. But the browser is stateful. If you create a new browser session for every tool call, Claude loses its login state and has to start over.

Fix: Use a persistent profile and reuse the same session across tool calls. Store the session ID and reconnect rather than creating fresh sessions.

Pitfall 2: Ignoring the Chromium Sandbox

Playwright's chromiumSandbox defaults to false in many configurations, which means the browser runs without OS-level sandboxing. This is fine for local development but risky in production. Hosted Chromium handles sandboxing on the server side, so you don't need to worry about it.

Pitfall 3: Not Handling CAPTCHAs and Bot Detection

Claude will encounter CAPTCHAs, login walls, and bot detection. A hosted browser with configurable settings can help, but you also need logic in your agent to handle these cases—either by delegating to a human or by using appropriate proxy configurations.

Pitfall 4: Overloading the Context Window

Claude has a limited context window. If you extract every piece of text from every page, you'll run out of tokens quickly. Be selective about what you extract and summarize aggressively.

Getting Started with Agent-Browser Claude

The fastest way to test the agent-browser Claude pattern is to create a Remote Browser session and connect to it with Playwright. Here's a minimal example:

import { chromium } from 'playwright';

// 1. Create a session (via API or dashboard)
// 2. Get the CDP URL
const cdpUrl = 'wss://remote-browser.dev/cdp/session_demo123';

// 3. Connect and verify
const browser = await chromium.connectOverCDP(cdpUrl);
const context = browser.contexts()[0];
const page = await context.newPage();

await page.goto('https://news.ycombinator.com');
console.log(await page.title());

await browser.close();

Once you verify the connection works, wrap it in a tool for Claude and start testing real tasks. Start with simple workflows—form filling, data extraction, multi-page navigation—and gradually increase complexity.

For production deployments, review the Remote Browser documentation for API details, session management, and configuration options. Check the pricing page for current session costs and limits.

Beyond Claude: Other Agent Frameworks

The agent-browser pattern isn't limited to Claude. The same CDP-based connection works with any AI agent that needs browser access. Frameworks like browser-use, Puppeteer agents, and custom LangChain tools can all connect to the same hosted Chromium sessions.

The key architectural insight is consistent: separate the browser from the agent. When the browser is a managed service rather than a local process, you get persistence, scalability, and observability that local setups can't match.

For a deeper look at how hosted browsers fit into AI agent architectures, see our guide on remote browsers for AI agents. If you're evaluating the operational differences between local and hosted setups, the remote browser online guide covers the practical trade-offs.

Summary

The agent-browser Claude pattern pairs Anthropic's language models with a hosted Chromium runtime that speaks CDP. This architecture gives you:

• Persistent sessions that survive worker restarts and network drops
• Scalable concurrency without local resource constraints
• Live debugging through session viewers and replay
• Portable profiles that work across cloud providers
• Production-ready infrastructure without managing Chrome yourself

The implementation is straightforward: create a session, connect via connectOverCDP, and wrap the browser as a tool for Claude. The hard part—keeping browsers alive, isolated, and debuggable at scale—is handled by the hosted runtime.

Start with a simple proof of concept, measure the failure modes, and iterate. The browser is no longer the bottleneck in AI web automation—it's just another API call.