BLOG
Playwright Chrome: Run Real Chrome Locally or Remotely
Playwright Chrome setup, channels, and CDP wiring explained, plus when to move from local Chrome to a hosted Chromium runtime.

"Playwright Chrome" usually means one of two things: launching a Chrome build through Playwright's chromium browser type, or attaching Playwright to a Chrome instance that is already running somewhere else. The first is a local install problem. The second is a runtime architecture decision, and it is the one that matters once automation moves past your laptop.
This guide covers both. It explains how Playwright selects a Chrome binary, how channels and connectOverCDP differ, and what to check before you point Playwright at a hosted Chromium session instead of a local browser.
What "Playwright Chrome" Actually Refers To
Playwright ships its own Chromium builds. When you write chromium.launch(), you are not launching the Chrome installed on your machine — you are launching the Chromium revision Playwright downloaded for its version. That distinction causes a lot of confusion, so it is worth stating plainly:
- `chromium.launch()` uses Playwright's bundled Chromium. Version is pinned to your Playwright release.
- `channel: "chrome"` tells Playwright to launch the stable Google Chrome installed on the system instead.
- `channel: "chrome-beta"`, `"chrome-dev"`, `"chrome-canary"` target other installed Chrome channels.
- `chromium.connectOverCDP(endpoint)` attaches to a browser that is already running, wherever it runs.
The first three are local concerns. The fourth is how Playwright talks to remote browsers, including hosted Chromium sessions. If your goal is to run automation in the cloud, connectOverCDP is the function you will actually use — see the Playwright CDP guide for the broader connection model.
Local Chrome vs Playwright's Bundled Chromium
The choice between bundled Chromium and a system Chrome channel is a real trade-off, not a formality.
| Aspect | Bundled Chromium (chromium.launch()) | System Chrome (channel: "chrome") |
|---|---|---|
| Version control | Pinned to Playwright release | Whatever is installed on the host |
| Install step | npx playwright install chromium | Manual Chrome install |
| Reproducibility | High — same build everywhere | Low — drifts with host updates |
| Codec/media support | Limited (open-source build) | Full Chrome build |
| Enterprise policy | Not applied | Host policies apply |
| Typical use | CI, tests, agents | Debugging against real Chrome behavior |
For test suites and agent workloads, the bundled Chromium is usually the right default because it is reproducible. Reach for channel: "chrome" when you specifically need to reproduce behavior that depends on the branded Chrome build — DRM, certain media codecs, or enterprise-managed settings.
You can also point Playwright at a specific executable with executablePath, but that bypasses Playwright's version compatibility checks. Treat it as a last resort.
Launching Chrome Through Playwright
A minimal local launch with the Chrome channel looks like this:
import { chromium } from "playwright";
const browser = await chromium.launch({
channel: "chrome",
headless: true,
});
const context = await browser.newContext();
const page = await context.newPage();
await page.goto("https://example.com");
await browser.close();Two things to note. First, channel: "chrome" fails if Chrome is not installed on the host — Playwright does not download it for you. Second, headless: true on modern Chrome uses the new headless mode, which behaves closer to headed Chrome than the legacy headless shell. If you are debugging rendering or layout issues, run headed first.
Launch options matter more than most people expect. Flags like --disable-dev-shm-usage, proxy configuration, and viewport defaults all affect stability under load. The launch options guide covers the flags that actually change behavior in production.
Connecting Playwright to a Remote Chrome Over CDP
connectOverCDP is the bridge between Playwright and any Chrome or Chromium instance that exposes a DevTools endpoint. That includes a local Chrome started with --remote-debugging-port, a container running Chromium, or a hosted browser session from a provider like Remote Browser.
import { chromium } from "playwright";
// The endpoint comes from your browser provider's session API.
const browser = await chromium.connectOverCDP(process.env.CDP_ENDPOINT!);
// Reuse the existing context rather than creating a new one.
const context = browser.contexts()[0] ?? (await browser.newContext());
const page = context.pages()[0] ?? (await context.newPage());
await page.goto("https://example.com");
await page.click("text=Sign in");
// Do not call browser.close() on a shared remote session unless you
// intend to tear it down. Disconnect instead.
await browser.close();A few details that trip people up:
- `connectOverCDP` returns a `Browser`, but you do not own its lifecycle the way you do with `launch()`. Closing it may terminate the remote session depending on the provider. Check the provider's semantics.
- Contexts already exist on a remote browser. Calling
newContext()on a connected browser creates an additional context; it does not replace the default one. Reusebrowser.contexts()[0]when you want the session's existing profile and cookies. - CDP is Chromium-only.
connectOverCDPdoes not work with Firefox or WebKit. If you need cross-browser coverage, that is a separate architecture question. - The endpoint is a WebSocket URL. It looks like
wss://.../devtools/browser/<id>. Treat it as a secret — anyone with it can drive the browser.
The official Playwright `connectOverCDP` documentation is the authoritative reference for the method's options, including headers and timeouts.
When Local Chrome Stops Being Enough
Local Chrome works well until it doesn't. The failure modes are predictable:
- Concurrency. Each browser instance consumes memory and CPU. Ten parallel agents on one machine is a capacity planning problem, not a code problem.
- Environment drift. Chrome auto-updates on developer machines. A test that passes locally can fail in CI because the Chrome versions differ.
- Session persistence. Cookies, logins, and local storage live on the host. Moving a workflow between machines means re-authenticating.
- Network identity. Geo-routing, per-session IPs, and proxy configuration are hard to manage on a laptop.
- Observability. Watching a headless browser on a remote CI runner is awkward without a live viewer.
A hosted Chromium runtime addresses these by moving the browser off your machine. Remote Browser provides hosted Chromium sessions with CDP access, Playwright/Puppeteer/Selenium compatibility, a live viewer, persistent profiles, and configurable browser settings including proxy options. The session lifecycle is managed through an API rather than a local process.
For a deeper look at the runtime model, see Remote Browser for AI agents.
Production Criteria for a Remote Chrome Runtime
If you are evaluating hosted browsers for Playwright workloads, these are the criteria that separate a workable runtime from a demo:
- CDP compatibility. The endpoint must accept standard
connectOverCDPconnections without a proprietary wrapper. If you have to rewrite your Playwright code, it is not a drop-in. - Session isolation. Each session should have its own browser process, profile, and network identity. Shared state between sessions causes cross-contamination in agent workloads.
- Persistent profiles. The ability to save and reuse a profile across sessions is what makes logged-in workflows viable. Without it, every run starts from scratch.
- Live viewer. Being able to watch a session in real time is not a luxury — it is how you debug agent failures that only reproduce in production.
- Configurable browser settings. Proxy configuration, user agent, viewport, and locale should be settable per session. Be precise about what a provider actually offers; "stealth" claims vary widely and are not all backed by the same mechanisms.
- Usage controls. You need visibility into session duration and concurrency so you can forecast cost. See /pricing for current rates and limits.
- Lifecycle semantics. Does closing the Playwright connection terminate the session, or does it just disconnect? Know this before you ship.
None of these are exotic. They are the baseline for running browser automation as infrastructure rather than as a script on a laptop.
Playwright Chrome in CI and Agent Workloads
The two dominant use cases for Playwright Chrome are test suites and AI agents, and they have different requirements.
Test suites want reproducibility. Pin the Playwright version, use the bundled Chromium by default, and only use channel: "chrome" when you need branded Chrome behavior. Run against a remote runtime when you need parallelism beyond what a single CI runner provides, or when tests depend on network conditions you cannot reproduce locally.
AI agents want session persistence and isolation. An agent that logs into a site, navigates a multi-step workflow, and returns structured output needs a browser that survives across steps and does not leak state into the next task. That is a runtime problem, not a Playwright problem. Playwright is the control layer; the hosted browser is the execution environment.
In both cases, the integration point is the same: a CDP endpoint and connectOverCDP. The rest is operational.
Common Mistakes
- Calling `browser.close()` on a shared session. If the session is meant to persist, disconnect rather than close. Check your provider's behavior.
- Ignoring `browser.contexts()`. On a connected browser, the default context already exists. Creating a new one silently changes which profile you are using.
- Assuming `connectOverCDP` works with Firefox. It does not. CDP is a Chromium protocol.
- Hardcoding the endpoint. Session endpoints are ephemeral. Fetch them from the provider's API at runtime.
- Skipping the live viewer during development. Watching the session is the fastest way to understand why an agent stalled.
- Treating stealth as a checkbox. Configurable browser settings are not the same as guaranteed evasion. Test against your actual targets.
Getting Started
The shortest path from local Playwright to a hosted runtime is:
- Install Playwright and confirm your local Chrome setup works with
channel: "chrome". - Create a hosted Chromium session through the Remote Browser API.
- Connect with
chromium.connectOverCDP(endpoint). - Reuse the existing context and page rather than creating new ones.
- Add a live viewer check to your debugging loop.
The documentation covers session creation, CDP endpoints, and profile management in detail. If you are comparing local and remote setups more broadly, Remote browser online walks through the trade-offs without assuming you have already decided.
Playwright Chrome is not complicated once you separate the two questions: which Chrome binary you are running, and where it runs. The first is a launch option. The second is a runtime decision — and for anything beyond a single machine, it is the one that determines whether your automation holds up.