Browser Use Documentation: Run AI Agents on Hosted Chromium

# Browser Use Documentation: Run AI Agents on Hosted Chromium

Browser use documentation often stops at local setup: install Playwright, launch Chromium, write a script. That works for a demo, but production AI agents need more—persistent sessions, clean network profiles, and the ability to run 24/7 without babysitting a local Chrome process. This guide covers how to connect your browser-use workflows to hosted Chromium sessions via CDP, Playwright, and Puppeteer, and what to look for when evaluating a remote browser runtime.

Why Browser Use Documentation Needs a Hosted Runtime

The term "browser use" covers two distinct workloads. The first is a single agent completing a task—filling a form, scraping a page, or testing a flow. The second is a fleet of agents running continuously, each with its own session, profile, and network identity. Most documentation addresses the first workload with local scripts. The second requires infrastructure.

Local browser automation breaks down in production for concrete reasons:

• Session persistence: When a local script crashes, the browser session dies with it. Cookies, local storage, and login state are lost.
• Resource contention: Each Chromium instance consumes significant CPU and memory. Running multiple agents on one machine degrades performance.
• Network reputation: Datacenter IPs from cloud VMs trigger bot detection. Residential or ISP-proxied IPs are often necessary for protected sites.
• Observability: Debugging a headless browser you can't see is painful. Live viewing and session recording are not optional extras; they are debugging tools.

Remote Browser addresses these by providing hosted Chromium sessions accessible over CDP. You write code against a standard browser automation protocol, and the runtime handles the infrastructure.

What Is CDP and Why It Matters for Browser Use

The Chrome DevTools Protocol (CDP) is the wire protocol that allows external tools to inspect and control Chromium. Playwright and Puppeteer both use CDP under the hood. When you connect to a remote browser over CDP, you are not launching a browser process locally—you are attaching to an existing one running elsewhere.

This distinction is critical for browser-use documentation. Local launch commands like chromium.launch() or puppeteer.launch() give you a fresh browser instance. Connecting over CDP gives you access to a browser that may already have profiles, extensions, and network settings applied.

Here is a minimal TypeScript example using Playwright to connect to a Remote Browser session over CDP:

import { chromium } from 'playwright';

// The CDP URL is provided by your Remote Browser session.
// It looks like: wss://connect.remote-browser.dev?token=YOUR_TOKEN
const cdpUrl = process.env.REMOTE_BROWSER_CDP_URL;

if (!cdpUrl) {
  throw new Error('REMOTE_BROWSER_CDP_URL environment variable is required');
}

// Connect to the existing hosted Chromium session.
const browser = await chromium.connectOverCDP(cdpUrl);

// The default context contains the session's persistent profile.
const context = browser.contexts()[0];
const page = await context.newPage();

await page.goto('https://example.com');
console.log('Page title:', await page.title());

// Your code drives the browser. The session stays alive after disconnect.
await browser.close();

The key detail: browser.close() disconnects your client but does not terminate the hosted browser session. This is different from local Playwright, where closing the browser kills the process. In a hosted runtime, the session persists until you explicitly end it or it times out. This enables long-running agent workflows that survive client crashes.

Connecting Playwright to a Remote Browser

Playwright's connectOverCDP method is the standard way to attach to an existing Chromium instance. The official Playwright documentation for connectOverCDP describes the method signature and options.

When you connect to Remote Browser, you get a browser instance with one or more contexts already created. The default context is where your persistent profile lives. Any cookies, localStorage, or IndexedDB data you write there persists across connections.

Playwright Code Example with Session Controls

import { chromium } from 'playwright';

async function runAgentTask() {
  const browser = await chromium.connectOverCDP(process.env.REMOTE_BROWSER_CDP_URL!);
  
  try {
    const context = browser.contexts()[0];
    const page = await context.newPage();
    
    // Navigate and interact with the page.
    await page.goto('https://news.ycombinator.com');
    await page.waitForSelector('.titleline');
    
    const headlines = await page.$$eval('.titleline a', links => 
      links.slice(0, 5).map(a => a.textContent)
    );
    
    console.log('Top headlines:', headlines);
  } finally {
    // Disconnect from the session. The hosted browser remains available.
    await browser.close();
  }
}

runAgentTask().catch(console.error);

Browserbase vs Playwright: What the Comparison Misses

A common search is "browserbase vs playwright." This comparison is misleading because Playwright is a client library and Browserbase is a hosted browser service. They operate at different layers of the stack. A more useful comparison is between hosted browser runtimes—Browserbase, Remote Browser, and self-hosted Playwright infrastructure.

The real question is not "browserbase vs playwright" but whether you want to manage browser infrastructure yourself. If you are running a handful of scripts, self-hosted Playwright is fine. If you are running AI agents that need persistent state, clean network profiles, and the ability to scale, a hosted runtime saves significant engineering effort.

Agent-Browser Install: CLI Tools for Browser Automation

The open-source ecosystem has produced several CLI tools for browser automation. The agent-browser package from Vercel Labs is one example—a browser automation CLI designed for AI agents. The agent-browser GitHub repository provides a command-line interface for driving browser sessions.

The typical agent-browser install flow sets up the CLI locally. However, the CLI still needs a browser to control. You have two options:

1. Local Chromium: The CLI launches a local browser instance. Simple but inherits all the production limitations discussed above.
2. Remote browser over CDP: The CLI connects to a hosted Chromium session. This gives you persistent profiles, proxy support, and the ability to run from any environment.

When evaluating browser-use documentation for CLI tools, check whether they support connecting to an existing CDP endpoint. Tools that only support local launches are fine for development but will not serve production workloads.

Hermes Browser Extension and Browser Hermes GitHub

The "hermes browser extension" and "browser hermes github" searches point to a different category: browser extensions that provide AI assistant capabilities. These tools embed an AI assistant directly into the browser UI, allowing users to delegate tasks to an agent that operates within their current session.

These extensions are useful for interactive use cases—a user asking an assistant to fill out a form or summarize a page. However, they are not designed for programmatic browser-use workflows. An extension operates within a user's browser profile, tied to their machine and network. It cannot scale to multiple concurrent sessions or run unattended.

For production browser use, you need a runtime that separates the browser from the user's machine. Hosted Chromium sessions provide this separation. Your code connects over CDP, drives the browser, and disconnects—while the session continues running in the cloud.

Key Features to Look for in Browser Use Documentation

When evaluating a hosted browser runtime, focus on these production criteria:

Session Persistence and Profiles

Your agent will need to log into sites, maintain cookies, and preserve state across runs. Look for documentation that explains how profiles work. A good runtime treats profiles as first-class objects: you create a profile, associate it with a session, and reuse it across multiple connections.

Remote Browser provides persistent profiles that survive session termination. This means you can run an agent, disconnect, and reconnect later with the same login state intact.

Live Debugging and Session Recording

Headless browser failures are notoriously hard to debug. You see an error message but not the page state that caused it. Live viewing solves this: you watch the browser session in real time, see what the agent sees, and intervene if necessary.

Session recording goes one step further. It captures the full browser session for post-hoc analysis. When an agent fails, you replay the session to understand exactly what happened.

Network Controls and Proxy Configuration

Sites increasingly block traffic from datacenter IPs. If your agents interact with protected sites—social media, e-commerce, or sites with bot detection—you need control over the network egress IP.

Remote Browser allows configurable browser settings per session, including proxy configuration. This lets you route traffic through residential or ISP proxies when needed. The documentation should explain how to set these options when creating a session.

Usage Controls and Cost Management

Browser automation costs money, whether you pay for cloud VMs or a hosted service. Look for runtimes that provide usage controls: session timeouts, concurrent session limits, and clear metering.

Remote Browser meters by browser-hour. You pay for the time a browser session is active, not for idle time between connections. This aligns cost with actual usage.

Practical Browser Use Workflow

Here is a production workflow that combines the concepts above:

1. Create a session with a persistent profile: Use the Remote Browser API to create a session. Specify the profile ID, proxy settings, and any browser configuration.
2. Connect over CDP: Use Playwright's connectOverCDP or Puppeteer's connect method to attach to the session.
3. Run your agent logic: Navigate, extract data, fill forms, or execute whatever task your agent performs.
4. Disconnect gracefully: Close the client connection. The session remains alive for a configurable timeout.
5. Reconnect when needed: For long-running tasks, reconnect to the same session. The profile persists, so login state and cookies remain intact.
6. Monitor via live viewer: Watch the session in real time or review recordings after the fact.

This workflow works for a single agent or a fleet. Each agent gets its own session, profile, and network configuration. The runtime handles browser lifecycle, resource allocation, and cleanup.

Security Considerations for Browser Use

Browser use documentation should address security. When you give an AI agent browser access, you are granting it the ability to act on the web. Consider these practices:

• Least privilege: Grant the agent access only to the sites and actions it needs. Do not run agents with administrative credentials to unrelated services.
• Session isolation: Use separate profiles for different tasks. A profile used for scraping should not contain credentials for your production systems.
• Network egress control: Route agent traffic through proxies that match the target site's expectations. This reduces the likelihood of blocks.
• Audit logging: Record browser sessions for post-hoc review. If an agent takes an unexpected action, you need to know what happened.

Remote Browser supports session isolation and provides live viewing and recording capabilities. The Remote Browser documentation covers these features in detail.

Browser Use Documentation: From Local to Production

The progression from local browser automation to production browser use follows a predictable path:

1. Local scripts: You write Playwright or Puppeteer scripts that launch a local browser. This works for development and testing.
2. CI integration: You run browser tests in CI. You need a browser that works in a containerized environment.
3. AI agent workloads: Your agents need to run continuously, maintain state, and interact with protected sites. Local browsers no longer suffice.
4. Hosted runtime: You move to a hosted browser service that provides persistent sessions, network controls, and observability.

Each step introduces new requirements. The documentation for each stage should be clear about the trade-offs. Local browsers are free and simple but do not scale. Hosted runtimes cost money but remove infrastructure burden.

For a deeper comparison of local versus hosted approaches, see our post on remote browsers for AI agents.

Conclusion

Browser use documentation should answer two questions: how to write code that drives a browser, and how to run that code reliably in production. The first question is well-covered by Playwright and Puppeteer docs. The second is where most documentation falls short.

Hosted Chromium sessions solve the production problem. They provide persistent profiles, configurable network settings, live debugging, and usage controls. Your code connects over standard protocols—CDP, Playwright, Puppeteer—so you do not need to learn a proprietary API.

The practical path forward: start with local browser automation to validate your agent logic. When you need persistence, scale, or network controls, move to a hosted runtime. The code changes are minimal—swap a local launch for a CDP connection—but the operational difference is substantial.

For implementation details, check the Remote Browser API documentation or review pricing to understand the cost model. If you are evaluating alternatives, our comparison of remote browser online options and the remote web browser runtime may help. For specific connection patterns, see the guide on remote control browser workflows.