BLOG
Learn and Use Remote Browsers: A Practical Guide
Learn and use remote browsers for AI agents: CDP connection, Playwright setup, session lifecycle, and production criteria that actually matter.

To learn and use a remote browser, you need three things: a hosted Chromium instance you can reach over the network, a CDP endpoint to drive it, and a client library (Playwright, Puppeteer, or Selenium) that speaks the protocol. Everything else — profiles, proxies, live viewing, session limits — is operational detail layered on top. This guide walks through the connection model, a working Playwright example, the session lifecycle decisions that break in production, and the criteria worth checking before you commit to a runtime.
If you are new to the concept, start with remote browsers for AI agents for the architectural background. This article assumes you understand why you want one and focuses on how to actually learn and use it.
What "remote browser" actually means
A remote browser is a real Chromium process running on someone else's infrastructure, exposed through the Chrome DevTools Protocol. Your code does not launch Chrome locally. Instead, it opens a WebSocket connection to a browser that already exists, then issues the same commands Playwright or Puppeteer would issue to a local instance.
That distinction matters because it changes what you own:
- You own the automation logic, the selectors, the retry policy, and the data handling.
- The runtime owns the browser binary, the OS, the network egress, the process lifecycle, and the isolation between sessions.
The protocol is the contract between those two halves. CDP is documented in the Chrome DevTools Protocol reference, and Playwright's connectOverCDP is the standard entry point for attaching to an existing browser rather than launching one.
Local Chrome vs. remote Chromium
The mental model most developers carry is "Playwright launches a browser." That is true locally. Remotely, Playwright *attaches* to a browser that was launched by the platform. The API surface is nearly identical, but the failure modes are different: connection drops, session expiry, and network latency replace "Chrome won't start on my laptop."
The connection model: CDP over WebSocket
Every hosted browser runtime exposes a WebSocket URL that looks roughly like wss://<host>/<session-id>. You pass that URL to your client library. The library negotiates the CDP session, discovers existing targets (tabs, iframes, workers), and hands you a Browser object.
Three practical consequences follow:
- You cannot assume a blank browser. A hosted session may already have a page open, or may be reused across calls if you asked for a persistent profile. Always enumerate contexts before acting.
- Connection setup is a network operation. It can fail, time out, or be rate-limited. Wrap it in retry logic with backoff, separate from your task-level retries.
- The endpoint is a secret. Treat the WebSocket URL like a credential. Do not log it, do not commit it, and rotate it per session where the platform supports it.
For a deeper treatment of the endpoint mechanics, see remote web browser.
A working Playwright example
The following TypeScript example connects to a hosted Chromium session over CDP, creates a fresh context, navigates, and extracts a value. It assumes the runtime provides a WebSocket endpoint via an environment variable — the exact provisioning call differs per provider, so check the documentation for the session-creation API.
import { chromium, Browser, BrowserContext, Page } from "playwright";
const CDP_ENDPOINT = process.env.REMOTE_BROWSER_WS;
if (!CDP_ENDPOINT) {
throw new Error("REMOTE_BROWSER_WS is not set");
}
async function runTask(): Promise<string> {
let browser: Browser | undefined;
let context: BrowserContext | undefined;
try {
// Attach to the already-running hosted Chromium instance.
browser = await chromium.connectOverCDP(CDP_ENDPOINT, {
timeout: 30_000,
});
// Create an isolated context so state does not leak between tasks.
context = await browser.newContext({
viewport: { width: 1280, height: 800 },
userAgent: undefined, // let the runtime's configured UA apply
});
const page: Page = await context.newPage();
await page.goto("https://example.com", {
waitUntil: "domcontentloaded",
timeout: 45_000,
});
const heading = await page.locator("h1").innerText();
return heading.trim();
} finally {
// Close the context, not the browser, unless you own the session.
await context?.close().catch(() => {});
await browser?.close().catch(() => {});
}
}
runTask()
.then((h) => console.log("Result:", h))
.catch((err) => {
console.error("Task failed:", err);
process.exitCode = 1;
});A few details worth internalizing:
- `connectOverCDP` returns a browser you did not launch. Calling
browser.close()may terminate the remote session or may be a no-op depending on the runtime. Confirm the semantics before relying on it for cleanup. - Contexts are your isolation boundary. Creating a new context per task is cheaper than a new browser and prevents cookie bleed between jobs.
- Timeouts belong at multiple layers. Connection timeout, navigation timeout, and task timeout are separate concerns. Set all three.
Session lifecycle: the part that breaks in production
Most tutorials stop at "it connected." Production failures cluster around lifecycle. Here is the decision tree that matters.
Ephemeral vs. persistent sessions
| Property | Ephemeral session | Persistent profile |
|---|---|---|
| State after task | Discarded | Retained (cookies, storage) |
| Best for | One-off scraping, stateless tasks | Logged-in workflows, multi-step agents |
| Isolation risk | Low | Higher — state follows the profile |
| Cleanup | Automatic on close | Explicit profile management |
| Debugging | Reproduce from scratch | Replay from saved state |
Choose ephemeral by default. Move to persistent profiles only when a workflow genuinely requires a login that cannot be re-established cheaply, and treat the profile as sensitive data.
Concurrency and quotas
Hosted runtimes meter sessions. Whether that is per browser-hour, per concurrent session, or per API call depends on the provider. Do not assume there is no cap on parallelism — check pricing for current limits and plan your worker pool around them. A common mistake is spinning up one session per task in a fan-out job and hitting a concurrency ceiling halfway through.
Failure handling
Three failure classes need distinct handling:
- Connection failures — retry with backoff, cap attempts, alert on repeated failure.
- Task failures — the browser is fine but the page did not behave. Retry the task, possibly with a fresh context.
- Session failures — the remote browser died. Discard the session, request a new one, and do not retry against the dead endpoint.
Conflating these three into a single retry loop is the most common cause of runaway costs and stuck agents.
What to evaluate before you commit
The runtime you pick determines your ceiling. These are the criteria that separate a demo-grade runtime from a production one.
Protocol and client compatibility
Does it expose a standard CDP WebSocket endpoint? If yes, Playwright, Puppeteer, and Selenium can all connect, and you are not locked into a proprietary SDK. If the runtime only offers a custom HTTP API, you lose the entire ecosystem of CDP tooling.
Observability
Can you watch a session live? A live viewer is not a luxury — it is the fastest way to debug a stuck agent. Look for the ability to attach to a running session without disrupting it. See remote control browser for how live control fits into debugging workflows.
Network configuration
Proxies, geolocation, and configurable browser settings matter for tasks that hit region-locked content or need consistent egress IPs. Be precise about what you need: "configurable browser settings" is a real capability; claims about altering browser identity signals require evidence. Ask providers exactly what they configure and how they document it.
Isolation guarantees
Each session should be isolated at the process or container level. Shared browser instances across tenants are a security problem, not just a performance one.
Usage controls
You need visibility into how many sessions you are running, how long they last, and what they cost. Metering that you cannot inspect is metering you cannot control.
Common mistakes when learning to use remote browsers
- Launching instead of connecting. If your code calls
chromium.launch()against a remote runtime, you are doing it wrong. UseconnectOverCDP. - Ignoring context isolation. Reusing a single context across unrelated tasks leaks cookies and storage between jobs.
- Hardcoding the endpoint. Endpoints rotate. Read them from the session-creation response at runtime.
- Skipping the live viewer. Debugging blind costs more time than any other mistake on this list.
- Assuming local performance. Round-trip latency to the hosted browser affects every CDP command. Batch operations where possible.
A realistic adoption path
If you are moving from local Playwright to a hosted runtime, sequence it like this:
- Prove the connection. Get
connectOverCDPworking against a single session with a trivial navigation. No task logic yet. - Port one workflow. Take your simplest existing script and run it against the remote browser unchanged except for the connection step.
- Add lifecycle handling. Introduce explicit session creation, context isolation, and the three-tier retry model.
- Instrument. Add logging around connection time, task duration, and session teardown. Watch the live viewer during the first week.
- Scale the worker pool. Only after a single workflow is stable should you fan out, and only up to the concurrency your plan allows.
This order matters because each step isolates a different failure class. Skipping to step five is how teams end up debugging concurrency bugs and connection bugs simultaneously.
Where remote browsers fit — and where they don't
Remote browsers are the right choice when you need real Chromium behavior, network isolation, or scale beyond what a single machine can host. They are the wrong choice when your task is a simple HTTP fetch — a plain HTTP client is faster, cheaper, and easier to reason about.
For AI agents specifically, the value is in the runtime guarantees: a browser that survives your process, a session you can inspect, and isolation between concurrent tasks. That is the layer this platform provides. To go deeper on the agent-specific architecture, read remote browsers for AI agents, and for the online-access angle see remote browser online.
The fastest way to learn and use a remote browser is to connect to one and break it deliberately. Start with the documentation, provision a session, and run the example above against a page you control. The protocol will teach you the rest.