BLOG
Automation Chrome: Running Real Chromium for Agents
Automation Chrome means driving real Chromium from code or agents. Learn the runtime options, CDP wiring, and production criteria that hold up.

Automation Chrome is the practice of driving a real Chromium browser programmatically — launching it, navigating pages, clicking, typing, reading the DOM, and capturing state — from a script or an AI agent. The hard part is rarely the automation code. It is where that Chrome instance runs, how it is isolated, how sessions persist, and how you observe what happened when a task fails at 2 a.m. This guide covers the runtime choices, the CDP wiring that connects your code to a browser, and the production criteria that separate a demo from a system you can leave running.
If you are evaluating hosted runtimes specifically, the remote browser for AI agents overview is a useful companion. This article focuses on the mechanics of automation Chrome itself.
What "automation Chrome" actually means
The phrase covers a few overlapping things, and conflating them causes bad architecture decisions:
- Driving Chrome with a library. Playwright, Puppeteer, and Selenium all speak to Chromium through the Chrome DevTools Protocol (CDP) or a WebDriver bridge. Your code issues commands; the browser executes them.
- Driving Chrome with an agent. An LLM-backed agent decides what to click or type based on page state, then issues the same underlying commands. The browser does not know or care whether a human-written script or a model produced the action.
- Running Chrome somewhere other than your laptop. This is the runtime question: local headless Chrome, a container you operate, or a hosted browser API that hands you a CDP endpoint.
All three share one requirement: a real Chromium process with a real network stack, real cookies, and real JavaScript execution. Anything that fakes the browser — a DOM parser, an HTTP client with a headless shim — will fail on the sites that matter, because modern web apps render client-side and gate behavior on browser APIs.
Local Chrome vs. self-hosted vs. hosted runtime
The first decision is where the browser lives. Each option trades control against operational burden.
| Dimension | Local Chrome | Self-hosted Chromium | Hosted browser runtime |
|---|---|---|---|
| Setup time | Minutes | Days to weeks | Minutes (API call) |
| Isolation between jobs | Manual (profiles, ports) | You build it | Per-session by default |
| Scaling | Limited by your machine | You manage orchestration | Provisioned via API |
| Browser version control | Manual updates | You pin and patch | Provider-managed |
| Live debugging | DevTools on your machine | You expose and secure it | Built-in viewer |
| Persistent logins | Local profile dirs | Custom storage | Managed profiles |
| Cost model | Your hardware | Infra + engineering time | Metered per browser-hour |
| Failure recovery | Manual restart | Custom health checks | Session lifecycle API |
Local Chrome is fine for development. It stops being fine when you need ten concurrent sessions, when a crashed browser silently wedges a queue, or when you cannot reproduce a failure because the session is gone. Self-hosting solves isolation and scale but moves the burden onto you: container images, Chromium version pinning, zombie process reaping, proxy configuration, and a debugging surface you have to secure yourself.
A hosted runtime is the pragmatic middle. You get a CDP endpoint per session and keep full control of the automation code. The trade-off is that you depend on the provider for browser version, network egress, and uptime — so evaluate those explicitly rather than assuming them.
How CDP connects your code to Chrome
The Chrome DevTools Protocol is the wire format. Every modern automation library ultimately speaks it. When you connect over CDP, you get a WebSocket endpoint and a browser-level session; from there you can create pages, attach to targets, and listen to network and console events.
The practical detail that trips people up: connectOverCDP attaches to an *existing* browser rather than launching one. That means lifecycle is your responsibility — you create the session through the provider's API, connect, do the work, then explicitly close the session so it stops billing and frees capacity.
Here is a minimal TypeScript example using Playwright against a hosted Chromium endpoint:
import { chromium, Browser, Page } from 'playwright';
interface SessionInfo {
cdpUrl: string;
sessionId: string;
}
// Your runtime provider returns a CDP WebSocket URL for a new session.
async function createSession(): Promise<SessionInfo> {
const res = await fetch(`${process.env.BROWSER_API}/sessions`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BROWSER_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ region: 'us-east', profile: 'checkout-agent' }),
});
if (!res.ok) throw new Error(`session create failed: ${res.status}`);
return res.json();
}
async function runTask(url: string): Promise<string> {
const session = await createSession();
let browser: Browser | undefined;
try {
browser = await chromium.connectOverCDP(session.cdpUrl);
// connectOverCDP reuses the existing context; grab the first page.
const context = browser.contexts()[0] ?? (await browser.newContext());
const page: Page = context.pages()[0] ?? (await context.newPage());
await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
await page.getByRole('button', { name: /accept cookies/i }).click({ timeout: 5_000 }).catch(() => {});
await page.waitForLoadState('networkidle');
const title = await page.title();
return title;
} finally {
// Closing the CDP connection does not always terminate the remote session.
await browser?.close().catch(() => {});
await fetch(`${process.env.BROWSER_API}/sessions/${session.sessionId}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${process.env.BROWSER_API_KEY}` },
}).catch(() => {});
}
}Two things to note. First, connectOverCDP is Chromium-only — it will not attach to Firefox or WebKit, which matters if your test matrix spans engines. Second, the finally block is not optional: leaked sessions are the most common cause of runaway browser-hour spend. For the protocol-level details, the Chrome DevTools Protocol documentation is the authoritative reference.
Production criteria for automation Chrome
Once the wiring works, the questions shift from "can it drive a page" to "can it run unattended." These are the criteria worth scoring any runtime against.
Session isolation
Every job should get its own browser context at minimum, and ideally its own browser process. Shared contexts leak cookies, localStorage, and service workers between tasks — which is both a correctness bug and a security problem when different tenants are involved. Verify that the runtime isolates at the process level, not just the tab level.
Persistent profiles
Many real workflows need a logged-in state that survives across sessions: a dashboard you authenticate once, a checkout flow with saved payment methods. Profile persistence lets you reuse cookies and storage without replaying a login every run. Check how profiles are scoped (per user, per tenant), how they are versioned, and whether you can reset them deterministically.
Network controls
Proxy configuration and configurable browser settings matter for geo-specific content, rate-limit avoidance, and staging environments behind IP allowlists. Be precise about what you need: a static egress IP, a residential pool, or per-session proxy assignment. Confirm in the provider's documentation exactly which network controls are supported before you build around them.
Observability
When an agent fails, you need the session recording, the console log, the network waterfall, and ideally a live view during execution. A live viewer is not a luxury — it is the fastest way to distinguish "the site changed" from "the agent made a bad decision." Look for session replay and a way to attach to a running session for interactive debugging.
Lifecycle and cost control
Sessions must be creatable, inspectable, and terminable through an API. Idle timeouts, maximum session duration, and concurrency limits should be explicit. Pricing is typically metered per browser-hour; see /pricing for current rates and limits rather than relying on secondhand figures.
Version and compatibility
Your automation code targets a specific Chromium version's behavior. Confirm how the runtime handles browser updates, whether you can pin a version, and whether Playwright, Puppeteer, and Selenium clients all connect cleanly. CDP compatibility is generally good, but minor protocol changes do break things.
Where agents change the requirements
A deterministic Playwright script and an LLM agent use the same browser, but they stress it differently.
Agents issue more actions per task, many of them exploratory. They read page state frequently, which means more DOM snapshots and more round-trips. They recover from errors by trying alternatives, so a single task may navigate many pages. And they are harder to debug because the failure is often a reasoning error, not an exception.
That pushes three requirements to the front:
- Low-latency CDP. Every extra 50 ms per action compounds across long action sequences. Co-locate your agent process with the browser region where possible.
- Stable page state reads. Agents need reliable accessibility trees or DOM snapshots. A runtime that throttles or truncates these will degrade task success.
- Session replay as a first-class feature. You cannot step through an agent's reasoning after the fact the way you step through a stack trace. The recording is the debugging artifact.
For a deeper treatment of how hosted Chromium affects agent task success, see the companion piece on accurate web agents in the blog index.
Common failure modes and how to avoid them
Leaked sessions. The finally block above exists because of this. Instrument session creation and deletion counts; a growing gap means you are paying for browsers nobody is using.
Assuming `connectOverCDP` launches a browser. It does not. If you need a fresh browser, create the session first, then connect. Mixing the two mental models produces confusing "target closed" errors.
Ignoring `waitUntil` semantics. networkidle is unreliable on pages with long-polling or analytics beacons. Prefer explicit element waits (getByRole, waitForSelector) over network heuristics.
Sharing one context across concurrent tasks. This is the isolation bug in disguise. It usually surfaces as flaky auth failures that are impossible to reproduce locally.
Hardcoding selectors against a moving target. Agents handle this better than scripts, but neither survives a redesign without a fallback strategy. Prefer role-based and text-based locators over brittle CSS paths.
Skipping the live viewer until something breaks. Attach early during development. Watching a session execute reveals timing assumptions you did not know you had.
Choosing a runtime: a short checklist
Before committing, run a small proof against your actual workload:
- Create a session via API and confirm you receive a CDP endpoint.
- Connect with Playwright and Puppeteer; verify both work against the same session type.
- Run a login flow, close the session, reopen with the same profile, and confirm the session persists.
- Kill a session mid-task and confirm it terminates cleanly without orphaned billing.
- Run ten concurrent sessions and watch for cross-contamination.
- Open the live viewer during a run and confirm you can inspect network and console.
If all six pass, the runtime is a candidate. If any fail, you have found the operational work you would otherwise inherit.
Bottom line
Automation Chrome is not a library choice — it is a runtime decision. The automation code is the easy part; isolation, persistence, observability, and lifecycle management are what determine whether your agents run reliably in production. Start local to develop, but design for a remote CDP endpoint from day one, because that is the interface that lets you swap runtimes without rewriting your automation layer. For setup specifics and connection patterns, the /documentation covers session creation, CDP endpoints, and profile management in detail.