DEV Community: RemoteBrowser

Puppeteer BrowserWSEndpoint Tutorial: Connect to Remote Chromium

RemoteBrowser — Mon, 21 Sep 2026 03:58:55 +0000

Puppeteer BrowserWSEndpoint Tutorial: Connect to Remote Chromium

This Puppeteer browserWSEndpoint tutorial shows you how to connect Puppeteer to a remote Chromium instance instead of launching a local browser. The short version: get a WebSocket debugger URL from your browser provider, pass it to puppeteer.connect({ browserWSEndpoint }), and drive the remote session exactly as you would a local one. The rest of this guide covers what that URL actually is, how to wire it up in TypeScript, and the production details that break naive implementations.

If you already know you want hosted sessions rather than local Chrome, start with Remote Browser for AI agents for the runtime model, then come back here for the Puppeteer specifics.

What browserWSEndpoint Actually Is

browserWSEndpoint is a WebSocket URL that speaks the Chrome DevTools Protocol (CDP). When you launch Chrome with --remote-debugging-port=9222, Chrome exposes an HTTP endpoint at http://localhost:9222/json/version. That response contains a webSocketDebuggerUrl field. That value is your browserWSEndpoint.

Puppeteer's connect() method opens a WebSocket to that URL and speaks CDP over it. Every page.goto(), page.click(), and page.evaluate() call becomes a CDP command on that socket. The browser process can be running anywhere — your laptop, a container, or a managed host — as long as the WebSocket is reachable and the transport is secure.

Two things matter for correctness:

The endpoint is browser-level, not page-level. You connect once, then call browser.newPage() or browser.pages() to get targets.
The endpoint is a credential. Anyone with the URL can drive the browser. Treat it like a password: never log it, never commit it, always use wss:// in production.

The Chrome DevTools Protocol documentation is the authoritative reference for the commands Puppeteer sends underneath.

Getting a browserWSEndpoint from a Hosted Runtime

With a local Chrome you construct the endpoint yourself. With a hosted runtime you request a session and the provider returns a connection URL. The shape is consistent across providers:

wss://<host>/cdp/<session-id>?token=<short-lived-token>

Remote Browser issues a per-session WebSocket URL that you pass straight into Puppeteer. Sessions are isolated, so two concurrent agents never share a browser process, profile, or cookie jar. You can also attach a live viewer to watch the session in real time while your agent runs — useful when a task fails and you need to see why rather than guess from logs.

The practical difference from local Chrome is that you no longer manage the browser binary, the display server, the container image, or the process lifecycle. You manage a URL and a session budget. Current session limits and metering are on the pricing page.

Minimal TypeScript Example

Install Puppeteer and the types:

npm install puppeteer-core
npm install -D typescript @types/node

Use puppeteer-core rather than puppeteer when connecting to a remote browser. The full puppeteer package downloads a bundled Chromium you will never launch, which adds a large amount of disk usage to your image for no benefit.

import puppeteer, { Browser, Page } from "puppeteer-core";

interface SessionInfo {
  browserWSEndpoint: string;
  sessionId: string;
}

async function createSession(): Promise<SessionInfo> {
  const res = await fetch("https://api.remote-browser.dev/v1/sessions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.REMOTE_BROWSER_API_KEY}`,
    },
    body: JSON.stringify({
      // Configurable browser settings: region, viewport, proxy, profile.
      profile: "checkout-agent",
    }),
  });

  if (!res.ok) {
    throw new Error(`Session create failed: ${res.status} ${await res.text()}`);
  }

  return (await res.json()) as SessionInfo;
}

async function run(): Promise<void> {
  const session = await createSession();

  const browser: Browser = await puppeteer.connect({
    browserWSEndpoint: session.browserWSEndpoint,
    // Keep the session alive if the socket drops briefly.
    protocolTimeout: 180_000,
  });

  try {
    const page: Page = await browser.newPage();
    await page.setViewport({ width: 1280, height: 800 });

    await page.goto("https://example.com", {
      waitUntil: "domcontentloaded",
      timeout: 30_000,
    });

    const title = await page.title();
    console.log("title:", title);

    await page.screenshot({ path: "example.png" });
  } finally {
    // Disconnect without killing the remote browser.
    browser.disconnect();
  }
}

run().catch((err) => {
  console.error(err);
  process.exit(1);
});

Two details in that snippet are easy to get wrong.

browser.disconnect() versus browser.close(). disconnect() closes the WebSocket and leaves the remote browser running. close() sends a CDP command that terminates the browser process. In a hosted runtime you usually want disconnect() and then an explicit session-termination call, so cleanup is idempotent and you do not accidentally kill a session another worker is still using.

protocolTimeout. The default is generous but finite. Long-running agent tasks that sit idle between CDP calls can trip it. Raise it deliberately rather than disabling timeouts entirely.

Connecting to an Existing Local Chrome

The same API works against a local browser, which is useful for debugging. Start Chrome with remote debugging enabled:

chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

Then fetch the endpoint and connect:

const versionRes = await fetch("http://localhost:9222/json/version");
const { webSocketDebuggerUrl } = await versionRes.json();

const browser = await puppeteer.connect({
  browserWSEndpoint: webSocketDebuggerUrl,
});

This is the fastest way to confirm your Puppeteer code is correct before you introduce network latency and auth tokens. If it works locally and fails remotely, the problem is almost always the endpoint URL, the token, or a firewall — not your page logic.

Local Chrome vs Hosted Remote Browser

Dimension	Local Chrome	Hosted remote browser
Setup	Install binary, manage versions	Request a session, get a URL
Scaling	One process per machine, manual	Sessions provisioned per request
Isolation	Shared profile unless you configure it	Isolated per session
Proxies	Manual config, your own IPs	Configurable per session
Debugging	Local DevTools	Live viewer plus CDP
Persistence	Local disk, lost on rebuild	Persistent profiles across sessions
Cost model	Compute you already pay for	Metered per browser-hour
Failure mode	Process crash kills the run	Session ends, reconnect or re-provision

The trade-off is not "remote is always better." If you run a handful of tests on a laptop, local Chrome is simpler and free. The calculus changes when you need concurrency, consistent IPs, or sessions that survive a deploy. That is the point where managing Chrome becomes a second job.

Production Criteria Before You Commit

Before you move a Puppeteer workload to a hosted runtime, check these against your requirements.

Reconnect semantics. What happens when the WebSocket drops mid-task? A good runtime lets you reconnect to the same session by ID rather than losing state. Test this by killing the socket deliberately.
Profile persistence. If your agent logs in, does the session keep cookies and local storage across runs? Persistent profiles matter for anything behind auth.
Proxy and network controls. Per-session proxy configuration, including residential IPs where needed, is often the difference between a task succeeding and getting blocked.
Isolation guarantees. Confirm that sessions do not share a browser process or profile. Shared state between agents is a correctness bug, not a performance optimization.
Observability. A live viewer plus structured session logs turns a 40-minute debugging session into a 4-minute one.
Metering transparency. Know how browser-hours are counted and whether idle time bills. See pricing for the current model.

If you are evaluating this for an agent stack rather than a test suite, the remote browser guide covers the runtime layer in more depth.

Common Failure Modes

Error: Failed to launch the browser process — you called puppeteer.launch() instead of puppeteer.connect(). Check your import and call site.

WebSocket connection closed abnormally — usually a token expiry or a proxy stripping the Upgrade header. Verify the token lifetime and that nothing between your worker and the runtime terminates long-lived connections.

Target closed mid-task — the remote browser was reaped, often because the session hit a time limit or the worker that created it exited. Decouple session lifetime from worker lifetime.

Hangs with no error — a CDP command was sent but the response never arrived. This is frequently a protocolTimeout that is too low combined with a slow page. Log the last command issued before the hang.

Works locally, fails in CI — the CI runner cannot reach the WebSocket host, or the token is not injected. Print the host portion of the endpoint (never the token) to confirm.

Where This Fits in an Agent Stack

Puppeteer over browserWSEndpoint is the lowest-level way to drive a remote browser. It gives you full CDP access and no abstraction. That is an advantage when you need precise control over network interception, request blocking, or performance tracing, and a disadvantage when you would rather describe a task in natural language.

Most production agent stacks end up with both: a high-level agent loop for task planning, and a Puppeteer or Playwright layer for the deterministic steps — login, checkout, file upload — where you want exact control. The remote runtime is shared between them, which means one place to configure proxies, profiles, and isolation.

If you are coming from Playwright rather than Puppeteer, the connection model is nearly identical; the remote control browser guide maps the concepts across both libraries.

Practical Checklist

Use puppeteer-core, not puppeteer, when connecting remotely.
Request a session, take the browserWSEndpoint, and pass it to connect().
Set protocolTimeout based on your longest expected idle gap.
Call disconnect() in a finally block; terminate the session explicitly.
Never log or commit the endpoint URL — it is a credential.
Test reconnect behavior before you rely on it.
Verify isolation and profile persistence against your actual workload.
Check current session limits and metering on pricing.

The API surface is small. The operational details are where remote Puppeteer succeeds or fails, and they are worth getting right before you scale past a single worker. For the full connection reference, see the documentation.

Puppeteer Install Browser: Local vs Remote CDP Setup

RemoteBrowser — Mon, 21 Sep 2026 03:58:55 +0000

Puppeteer Install Browser: Local vs Remote CDP Setup

When you run npm install puppeteer, the package downloads a pinned Chrome build into a local cache directory. That is the default "puppeteer install browser" step, and it works fine on a laptop. It becomes a problem the moment you deploy to a container, a CI runner, or a fleet of agent workers: the download is large, the cache path differs per OS, and the browser binary has to match the Puppeteer version that launched it. This guide covers what the install actually does, how to control it, and when to stop installing Chrome locally and connect Puppeteer to a hosted Chromium session over CDP instead.

What `puppeteer install browser` actually does

Puppeteer ships two packages. puppeteer runs a postinstall script that fetches a browser; puppeteer-core does not. That single distinction drives most install decisions.

When you install the full puppeteer package, the install script:

Reads the browser version pinned to that Puppeteer release.
Downloads the matching Chrome for Testing build (or Chrome Headless Shell, depending on config).
Extracts it into a cache directory — ~/.cache/puppeteer on Linux, ~/Library/Caches/puppeteer on macOS, %USERPROFILE%\.cache\puppeteer on Windows.
Records the revision so puppeteer.launch() can find the binary without you passing an executable path.

The cache is keyed by browser and revision, so upgrading Puppeteer can trigger a second download rather than reusing the first. On a build machine with no persistent cache, every clean install pays that cost again.

Environment variables that control the install

You can steer the install without touching code:

PUPPETEER_SKIP_DOWNLOAD=true — skip the browser download entirely. Use this when you only need puppeteer-core behavior or you plan to connect to a remote browser.
PUPPETEER_CACHE_DIR=/path — relocate the cache, useful for Docker layers and CI caching.
PUPPETEER_DOWNLOAD_BASE_URL — point at an internal mirror if your network blocks the default CDN.
PUPPETEER_EXECUTABLE_PATH — at runtime, force Puppeteer to use a specific Chrome binary instead of the cached one.

If you install puppeteer-core, none of this applies. You get the API surface with no bundled browser, and you must supply a browser yourself — either a system Chrome via executablePath, or a remote endpoint via browserWSEndpoint or browserURL.

Local install vs remote connect

The install question is really a deployment question. Here is the trade-off in concrete terms.

Dimension	Local `puppeteer` install	`puppeteer-core` + remote CDP
Browser binary	Downloaded per install, cached on disk	None; browser runs elsewhere
Image size	+300–500 MB typical	Package only, tens of MB
Version coupling	Puppeteer pins the Chrome revision	You control the remote browser version
Cold start	Download + extract on first run	Connect handshake, typically sub-second
Scaling	One browser per process/container	Many sessions against hosted Chromium
Session persistence	Tied to the process lifetime	Profiles can outlive the worker
Debugging	Local DevTools	Live viewer or CDP over the wire
Best fit	Local dev, one-off scripts	CI, serverless, agent fleets

The pattern that holds up in production: use the full puppeteer package locally so you get a working browser with zero configuration, and use puppeteer-core in deployed code where the browser is a remote resource. That keeps your dependency tree honest — your production code never silently depends on a downloaded binary that may not exist in the runtime.

Connecting Puppeteer to a remote browser

Puppeteer connects to a remote Chromium in two ways. puppeteer.connect({ browserWSEndpoint }) uses the WebSocket endpoint that Chrome exposes when started with --remote-debugging-port. puppeteer.connect({ browserURL }) hits the HTTP endpoint and resolves the WebSocket URL for you. Both speak the Chrome DevTools Protocol, so anything you can do with a local browser you can do against a hosted one.

The endpoint is the only thing that changes. Your page logic — selectors, waits, evaluation — stays identical.

import puppeteer, { Browser, Page } from "puppeteer-core";

// The WebSocket endpoint comes from your browser provider.
// It looks like: wss://<host>/cdp/<session-id>
const browserWSEndpoint = process.env.BROWSER_WS_ENDPOINT!;

async function runTask(): Promise<void> {
  let browser: Browser | undefined;

  try {
    browser = await puppeteer.connect({
      browserWSEndpoint,
      defaultViewport: { width: 1280, height: 800 },
      // Keep the session alive if the socket blips.
      protocolTimeout: 120_000,
    });

    const page: Page = await browser.newPage();

    // Route through the remote browser's network stack.
    await page.goto("https://example.com", {
      waitUntil: "networkidle2",
      timeout: 45_000,
    });

    const title = await page.title();
    const links = await page.$$eval("a", (anchors) =>
      anchors.map((a) => (a as HTMLAnchorElement).href).slice(0, 10)
    );

    console.log({ title, links });
  } catch (err) {
    // Surface the CDP error rather than swallowing it.
    console.error("Remote browser task failed:", err);
    throw err;
  } finally {
    // Disconnect, do not close — the remote session may be reused.
    if (browser) await browser.disconnect();
  }
}

runTask();

Two details matter here. First, browser.disconnect() instead of browser.close(). Closing a remote browser tears down a session you may not own; disconnecting releases your client while leaving the session intact for reuse or inspection. Second, protocolTimeout guards against a stalled CDP call hanging your worker indefinitely — worth setting explicitly rather than relying on defaults.

If you are wiring this into a Playwright-based stack instead, the same endpoint works through chromium.connectOverCDP(). The Playwright CDP guide documents the connection semantics, and the protocol underneath is identical.

Production criteria for the remote path

Connecting is easy. Running it reliably is the part that needs decisions.

Session lifecycle. Decide up front whether a session is per-task or long-lived. Per-task sessions are simpler to reason about and isolate failures. Long-lived sessions preserve login state and cookies but need explicit cleanup. Remote Browser exposes persistent profiles for the second case, so a worker can reconnect to a session that already holds an authenticated state.

Endpoint stability. A WebSocket endpoint that changes on every reconnect forces you to re-fetch it from an API before each task. Prefer a provider that gives you a stable connection URL per session, or an API call that returns the current endpoint for a session ID.

Isolation. If two agents share a browser, they share cookies, storage, and possibly a page context. Session isolation at the browser level is the safe default; sharing a browser across tenants is not.

Observability. When a remote task fails, you need to see what the browser saw. A live viewer that streams the session is far more useful than a stack trace alone. Pair it with CDP-level logging so you can correlate agent actions with page state.

Cost model. Remote browsers are usually metered by session time. Understand whether you pay for idle sessions, how disconnects are billed, and whether there is a minimum increment. Current rates are on the /pricing page rather than baked into this post, since they change.

Network posture. If your targets are geo-restricted or rate-limited, the browser's egress IP matters as much as the browser itself. Configurable proxy settings at the session level let you route traffic without changing your Puppeteer code.

Common failure modes

Most "remote browser not working" reports trace back to a handful of causes.

Wrong endpoint scheme. browserWSEndpoint needs ws:// or wss://. Passing an http:// URL to it fails immediately. Use browserURL for HTTP endpoints.
Session already closed. Reconnecting to an expired session returns a connection error. Fetch a fresh endpoint rather than retrying a dead one.
Version skew. A very old puppeteer-core against a very new Chromium can hit unsupported CDP methods. Keep the client reasonably current.
Missing --remote-debugging-address. If you self-host Chrome and it only binds to localhost, remote clients cannot reach it. Hosted providers handle this for you.
Timeouts on heavy pages. Default navigation timeouts are short. Set waitUntil and timeout explicitly for pages with client-side rendering.

For a broader look at how hosted sessions fit into agent architectures, see Remote Browser for AI Agents.

When to keep the local install

The remote path is not universally better. Keep the local puppeteer install when:

You are developing and iterating on selectors, where a local browser and DevTools are faster to inspect.
You need to test against a specific Chrome build that you control end to end.
Your workload is a single script on a machine that already has Chrome.
You are debugging a CDP interaction and want zero network variables.

Switch to puppeteer-core plus a remote endpoint when you deploy, when you need more concurrent sessions than one machine can hold, when you want sessions to survive worker restarts, or when you need a live view of what an agent is doing. The remote browser overview covers the runtime model in more depth, and the /documentation has the connection specifics for each supported client.

A practical migration path

If you have a working local Puppeteer script and want to move it to a hosted browser without a rewrite:

Swap the dependency from puppeteer to puppeteer-core.
Replace puppeteer.launch({ ... }) with puppeteer.connect({ browserWSEndpoint }).
Move any launch flags you relied on — viewport, user agent, proxy — into the session configuration on the provider side.
Replace browser.close() with browser.disconnect() unless you genuinely want to end the session.
Add a retry wrapper that fetches a fresh endpoint on connection failure.

That is the whole change. The page automation code — the part you actually spent time on — does not move.

The install step is a deployment detail, not an architectural one. Treat it that way: install locally for development, connect remotely for production, and keep the browser binary out of your deployed artifact.

Puppeteer Browsers Npm: Install, Connect, and Run Remotely

RemoteBrowser — Sun, 20 Sep 2026 03:27:46 +0000

Puppeteer Browsers Npm: Install, Connect, and Run Remotely

If you have run npm install puppeteer recently, you already know the surprise: the package pulls a Chromium build into your node_modules or cache directory, and that download is often the slowest, most fragile part of your CI pipeline. The puppeteer browsers CLI exists to manage exactly that — installing, listing, and pinning browser binaries. This guide covers what the puppeteer browsers npm workflow actually does, where it breaks in production, and how to connect Puppeteer to a hosted Chromium runtime so you stop shipping browser binaries with your app.

What `puppeteer browsers` Actually Manages

Puppeteer ships two related things: the Node library and a browser binary. Since Puppeteer v19+, browser management moved into a dedicated CLI and a set of npm packages under the @puppeteer/browsers namespace. The command surface looks like this:

npx puppeteer browsers install chrome
npx puppeteer browsers install chrome@stable
npx puppeteer browsers install chrome-headless-shell@121.0.6167.85
npx puppeteer browsers list
npx puppeteer browsers uninstall chrome

Each command resolves a browser "build ID" (a version string like 121.0.6167.85 or a channel like stable, beta, canary, dev), downloads the matching archive from Google's Chrome for Testing endpoints, and unpacks it into a cache directory. On Linux that is typically ~/.cache/puppeteer; on macOS it is ~/Library/Caches/puppeteer. The path is configurable via PUPPETEER_CACHE_DIR.

The key detail for production: the browser is not part of your application artifact. It is a side-loaded binary that must exist on the machine that runs puppeteer.launch(). That distinction drives most of the operational pain.

Version pinning and the `puppeteer` vs `puppeteer-core` split

puppeteer — installs a browser on npm install (unless PUPPETEER_SKIP_DOWNLOAD is set) and exposes the full API.
puppeteer-core — no browser download, no install hooks. You supply an executable path or a CDP endpoint.

For containerized workloads, puppeteer-core is almost always the right dependency. It keeps your image small and removes a network-dependent step from npm ci. You then either bake a browser into the image or — more usefully — connect to a browser that already exists somewhere else.

Where the Local Install Model Breaks Down

The puppeteer browsers npm flow is fine for a laptop. It gets awkward at scale for predictable reasons:

Cold-start cost. A fresh npm ci in CI pulls a ~150–200 MB archive per job. Multiply by parallel runners and you are paying for bandwidth and wall-clock time on every build.
Version drift. If you do not pin the build ID, chrome@stable resolves to whatever is current that day. A Chrome release can change rendering, network behavior, or CDP surface between your test runs.
Missing system libraries. Chrome needs a long list of shared libraries (libnss3, libatk, libgbm, and friends). Minimal base images do not have them, and the failure mode is a cryptic launch error rather than a clear dependency message.
Architecture mismatch. chrome-headless-shell and full Chrome have different build matrices. Cross-compiling or running on ARM runners means verifying the right artifact exists.
Sandbox and privilege issues. Running Chrome as root in a container requires --no-sandbox or a properly configured user namespace. Both have security implications you should decide on deliberately, not by copy-pasting a flag.

None of these are fatal. They are the tax you pay for owning the browser lifecycle. The question is whether that ownership buys you anything.

The Alternative: Connect Instead of Install

Puppeteer's connect() method attaches to an existing browser over the Chrome DevTools Protocol. If a browser is already running somewhere reachable, you skip installation entirely:

import puppeteer from 'puppeteer-core';

// A hosted runtime exposes a CDP WebSocket endpoint.
// Treat this URL as a secret — it grants full control of the session.
const browser = await puppeteer.connect({
  browserWSEndpoint: process.env.BROWSER_WS_ENDPOINT!,
  defaultViewport: { width: 1280, height: 800 },
});

const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle2' });

const title = await page.title();
const links = await page.$$eval('a', (nodes) =>
  nodes.slice(0, 10).map((n) => (n as HTMLAnchorElement).href),
);

console.log({ title, links });

// Close the page, but do not kill the remote browser unless you own it.
await page.close();
browser.disconnect();

Two things matter here. First, browser.disconnect() detaches your client without terminating the remote process — the opposite of browser.close(). Second, the browserWSEndpoint is a credential. Anyone with that URL can drive the session, read cookies, and navigate. Store it in a secret manager, not in a checked-in .env.

The same pattern works with Playwright's connectOverCDP, which is documented in the Playwright CDP guide. If you are evaluating both libraries, the connection model is nearly identical; the difference is in the higher-level API.

Local Install vs Hosted Runtime: A Comparison

Dimension	`puppeteer browsers` local install	Hosted Chromium via CDP
Setup step	Download + unpack per machine	Paste a WebSocket URL
Image size	+150–200 MB per browser	No browser in your artifact
Version control	You pin build IDs manually	Runtime owns the build
System deps	You install `libnss3`, `libgbm`, etc.	Handled by the runtime
Cold start	Seconds to minutes on first run	Connection handshake
Session persistence	You manage profile dirs	Persistent profiles available
Debugging	Local DevTools or screenshots	Live viewer + CDP
Scaling model	One browser per container	Sessions provisioned per request
Best fit	Local dev, offline work	CI, agents, multi-tenant automation

The honest read: local installs win when you need a specific patched build, work offline, or want zero external dependencies. Hosted runtimes win when browser lifecycle is not your product.

Production Criteria Before You Switch

Before moving Puppeteer workloads to a remote runtime, check these against your requirements:

CDP compatibility. Confirm the runtime exposes a standard CDP endpoint. Puppeteer's connect() expects a WebSocket URL; some providers only offer REST wrappers.
Session isolation. Each task should get its own browser context or process. Shared state across tenants is a correctness and security problem.
Profile persistence. If your workflow logs in once and reuses cookies, you need persistent profiles with a defined retention policy.
Proxy and network controls. Egress IP, geolocation, and header behavior should be configurable per session, not global.
Observability. A live viewer or session recording turns "the agent failed" into "the agent clicked the wrong element at step 6."
Usage accounting. Browser time is the unit that scales. Know how sessions are metered before you commit to a volume.

Remote Browser exposes hosted Chromium sessions with CDP access, Playwright/Puppeteer/Selenium compatibility, persistent profiles, configurable browser settings, session isolation, and a live viewer. Current limits and metering are on the /pricing page — check there rather than assuming a number.

Wiring It Into an Existing Puppeteer Codebase

The migration is usually smaller than teams expect. The main changes:

Swap puppeteer for puppeteer-core in package.json.
Replace puppeteer.launch({ ... }) with puppeteer.connect({ browserWSEndpoint }).
Remove PUPPETEER_CACHE_DIR, browser install steps, and the associated Docker layers.
Move launch options that no longer apply (like executablePath) into runtime configuration.
Keep --no-sandbox-style flags out of your code; the runtime owns process configuration.

If you use puppeteer.launch() with a browserURL instead of a WebSocket, note that browserURL points at the HTTP debugging endpoint (usually port 9222), while browserWSEndpoint is the WebSocket. Mixing them up produces a connection error that looks like a network problem but is actually a protocol mismatch.

For a broader look at how hosted sessions fit into agent workflows, see /blog/remote-browser-for-ai-agents. If you are comparing connection styles across libraries, /blog/remote-control-browser covers the control-plane side.

Common Failure Modes and How to Read Them

Could not find browser revision — you are on puppeteer (not puppeteer-core) and the install step was skipped or the cache was cleared. Either run npx puppeteer browsers install or switch to puppeteer-core with an explicit endpoint.

Target closed immediately after connect — the remote session expired or was reclaimed. Check session TTL and whether your client is holding the connection open during long idle periods.

Protocol error (Page.navigate): Session closed — often a proxy or network policy killing the connection mid-navigation. Verify egress rules and timeouts.

Timeouts on page.goto with networkidle0 — a common Puppeteer footgun. Pages with long-polling or analytics beacons may never reach idle. Prefer domcontentloaded plus an explicit selector wait.

Stale cookies across runs — you are reusing a persistent profile when you meant a fresh context, or vice versa. Decide per workload and make it explicit in code.

When to Keep the Local Install

There are legitimate reasons to stay with puppeteer browsers npm installs:

You need a specific Chrome build that a hosted runtime does not offer.
Your workload runs in an air-gapped environment.
You are testing browser-version-specific behavior and need to switch builds frequently.
Your volume is low enough that CI download time is not a real cost.

The decision is not ideological. It is a question of whether browser lifecycle management is core to your product or incidental overhead. For most agent and automation workloads, it is the latter — which is why connecting to a hosted runtime tends to win once you have more than a handful of concurrent sessions.

Getting Started

The fastest path is to keep your existing Puppeteer code and change one function call. Install puppeteer-core, point connect() at a CDP endpoint, and delete the browser download from your build. The /documentation covers session creation, endpoint formats, and profile handling. If you want to see the runtime in action before committing, /blog/remote-browser-online walks through a browser session without any local Chrome install.

The puppeteer browsers npm tooling is genuinely useful — it solved a real problem when Puppeteer stopped bundling browsers into the main package. But it solves a problem you only have if you own the browser. Once you stop owning it, the CLI becomes a local development convenience rather than a production dependency.

Puppeteer BrowserWSEndpoint Example: Connect to Remote Chromium

RemoteBrowser — Sun, 20 Sep 2026 03:27:43 +0000

Puppeteer BrowserWSEndpoint Example: Connect to Remote Chromium

If you are searching for a Puppeteer browserWSEndpoint example, you probably already have a WebSocket URL and want to know exactly how to hand it to Puppeteer so your script drives a browser that is not running on your machine. The short answer: pass the endpoint to puppeteer.connect() instead of puppeteer.launch(), then call browser.newPage() as usual. Everything after that — pages, selectors, network interception — behaves the same as a local launch, because browserWSEndpoint is just the Chrome DevTools Protocol (CDP) WebSocket address of a running browser.

This post gives you a working example, explains what the endpoint actually is, and covers the production details that trip people up: version matching, session lifetime, reconnection, and when a WebSocket endpoint is the wrong abstraction.

What `browserWSEndpoint` actually is

When Chromium starts with remote debugging enabled, it opens a WebSocket server and prints a line like:

DevTools listening on ws://127.0.0.1:9222/devtools/browser/6f3c...

That URL is the browser-level CDP endpoint. It is not a page, not a tab, and not a session — it is the control channel for the whole browser process. Puppeteer's browserWSEndpoint option is simply the string it uses to open that channel.

Two things follow from this:

The endpoint is transport, not state. Connecting to it does not create a browser; it attaches to one that already exists. If the process dies, your endpoint is dead too.
The endpoint is version-sensitive. CDP is a moving protocol. Puppeteer ships with a pinned Chromium and a matching protocol definition. Connecting a Puppeteer version to a Chromium build several major versions away is the single most common source of "it connected but nothing works" bugs.

For a hosted runtime, the endpoint is issued per session. You request a session, receive a ws:// or wss:// URL, connect, do your work, and release the session. That lifecycle is the part worth designing around.

A minimal Puppeteer browserWSEndpoint example

Here is the smallest useful version. It assumes you already have an endpoint string from your browser provider or from a locally launched Chrome with --remote-debugging-port.

import puppeteer, { Browser, Page } from 'puppeteer-core';

const endpoint = process.env.BROWSER_WS_ENDPOINT;
if (!endpoint) throw new Error('BROWSER_WS_ENDPOINT is not set');

async function main() {
  const browser: Browser = await puppeteer.connect({
    browserWSEndpoint: endpoint,
    // Keep the remote browser alive when the client disconnects.
    // Set false if you want the session torn down with the socket.
    defaultViewport: { width: 1280, height: 800 },
  });

  const page: Page = await browser.newPage();
  await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });

  const title = await page.title();
  console.log('title:', title);

  // Disconnect, do not close. close() would kill the remote browser.
  await browser.disconnect();
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

Three details in that snippet matter more than they look:

puppeteer-core, not puppeteer. If you are connecting to a browser you did not download, you do not need the bundled Chromium. puppeteer-core skips the ~150 MB download and avoids version drift between the bundled binary and the remote one.
browser.disconnect() vs browser.close(). disconnect() drops the WebSocket and leaves the browser running. close() sends a protocol command that shuts the browser down. On a metered hosted runtime, calling close() when you meant disconnect() will end your session — which is sometimes what you want, and sometimes a bug that kills a long-running agent mid-task.
defaultViewport is a client-side hint. It sets the viewport Puppeteer applies to new pages. It does not resize the remote browser window. If your provider exposes viewport configuration, set it there too.

Connecting with Playwright over CDP instead

Puppeteer is not the only client for a CDP endpoint. Playwright's connectOverCDP accepts the same WebSocket URL, which is useful if your test suite is already Playwright-based but your runtime is a hosted Chromium session.

import { chromium, Browser, Page } from 'playwright';

const endpoint = process.env.BROWSER_WS_ENDPOINT!;

async function run(): Promise<void> {
  const browser: Browser = await chromium.connectOverCDP(endpoint, {
    timeout: 30_000,
  });

  // Reuse the existing context if the session already has one.
  const context = browser.contexts()[0] ?? (await browser.newContext());
  const page: Page = await context.newPage();

  await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
  console.log(await page.title());

  await browser.close(); // For connectOverCDP this disconnects the client.
}

run();

The trade-off is real. Playwright over CDP gives you Playwright's locators, auto-waiting, and tracing, but it does not give you Playwright's browser patching — the instrumentation Playwright normally injects at launch. Some features behave differently when attached to an externally managed browser. If your workflow depends on Playwright-specific internals, test them against the remote endpoint before committing. The Playwright CDP documentation is the authoritative reference for what connectOverCDP does and does not support.

Puppeteer vs Playwright over a WebSocket endpoint

Concern	Puppeteer `connect()`	Playwright `connectOverCDP()`
Protocol	CDP only	CDP only (for Chromium)
Browser patching	None	None when attaching
Auto-waiting	Manual / `waitForSelector`	Built into locators
Tracing	Not built in	Available, with caveats
Version coupling	Tight to Chromium build	Tolerant but not immune
Best fit	Chrome-centric scripts, existing Puppeteer code	Test suites, teams already on Playwright

Neither is "better." If you have a working Puppeteer codebase, puppeteer.connect() is a two-line change. If you are starting fresh and want tracing and resilient locators, Playwright is the more ergonomic client — just verify the features you rely on actually work over CDP.

Production criteria for a remote endpoint

A browserWSEndpoint example gets you connected. Keeping it connected under load is a different problem. These are the criteria that matter when you move from a laptop to a deployed agent.

Session lifetime and idle timeouts. Hosted sessions are usually metered and expire. Know your idle timeout and whether the clock resets on activity. An agent that pauses for a model call longer than the idle window will come back to a dead socket.

Reconnection semantics. WebSockets drop. Plan for it: catch the disconnect, request a new session, and decide whether you need to restore state (cookies, storage, open tabs) or can restart the task. Persistent profiles help here — if the runtime supports them, session state survives across connections.

Version pinning. Ask what Chromium build the runtime serves and whether you can pin it. If your Puppeteer version expects CDP methods the remote build does not implement, you get silent failures. Pin both sides.

Proxy and network configuration. Many production workflows need specific egress IPs, geolocation, or header handling. Check whether the runtime exposes proxy configuration per session and whether it is configurable at the session level or only globally.

Observability. When a remote task fails, you need to see what the browser saw. A live viewer or session recording turns a 40-minute debugging session into a 40-second one. This is the difference between a hosted browser you can operate and one you can only hope works.

Isolation. Sessions should not share cookies, storage, or process state unless you explicitly want them to. Verify this rather than assuming it.

For a broader look at how these criteria map onto agent workloads, see Remote Browser for AI Agents.

Common failure modes

"Protocol error (Target.setAutoAttach): Target closed." Usually the session expired or the browser crashed. Check session lifetime before debugging your script.

Connection succeeds, newPage() hangs. Often a version mismatch or a session that is already at its page limit. Log the browser version from browser.version() and compare it to your Puppeteer's expected Chromium.

Works locally, fails remotely. Local Chrome and hosted Chromium differ in flags, extensions, and sometimes headless mode. Anything that depends on a specific launch flag needs to be configured on the runtime side, not passed to connect() — connect() has no launch options.

Endpoint works once, then 401s. Many providers issue single-use or short-lived endpoints. Request a fresh endpoint per connection rather than caching the string.

When a WebSocket endpoint is the wrong tool

browserWSEndpoint is the right abstraction when you want to drive a browser with code you already have. It is the wrong abstraction when:

You want a managed task API that takes a natural-language goal and returns a result. That is an agent runtime, not a CDP endpoint.
You need the browser to outlive your process by hours or days without a client attached. Look for session persistence rather than a socket.
You are running thousands of short tasks and want the runtime to handle pooling. Managing your own connection pool over raw WebSockets is possible but rarely worth it.

If you are still deciding between a raw endpoint and a higher-level API, Remote Browser Online walks through the options.

Getting an endpoint and running the example

The example above works against any CDP-compatible endpoint. To run it against a hosted Chromium session:

Create a session through the API and read the WebSocket URL from the response.
Export it as BROWSER_WS_ENDPOINT.
Run the script with puppeteer-core installed.
Release the session when the task finishes — do not rely on the socket closing to clean up.

The documentation covers session creation, endpoint formats, and the connection lifecycle in detail. Current session limits and metering are on the pricing page.

One practical note: treat the endpoint as a credential. It grants full control of the browser, including any authenticated sessions inside it. Do not log it, do not commit it, and rotate it per session where the provider supports it.

Summary

A Puppeteer browserWSEndpoint example is short — puppeteer.connect({ browserWSEndpoint }) and you are driving a remote browser. The engineering is in everything around it: matching Puppeteer to the remote Chromium version, distinguishing disconnect() from close(), handling session expiry, and choosing a runtime that gives you the observability and isolation you need. Get those right and the endpoint becomes an implementation detail. Get them wrong and you will spend your time debugging sockets instead of shipping the task.

Puppeteer Remote Browser Chrome: Connect and Run in the Cloud

RemoteBrowser — Sat, 19 Sep 2026 03:50:05 +0000

Puppeteer Remote Browser Chrome

Running Puppeteer against a remote browser Chrome instance means your Node process no longer launches a local binary. Instead, it connects to a Chromium process running elsewhere over the Chrome DevTools Protocol (CDP). This is the pattern behind most production browser automation today: the script stays small, the browser becomes infrastructure, and you stop shipping a large Chrome download with every deploy. This guide covers how puppeteer.connect() works with a browserWSEndpoint, how to get that endpoint, how browser versions and launch args behave when the browser is remote, and what to check before you put it in production.

If you already know you want a hosted runtime, you can skip ahead to Remote Browser for AI agents for the architectural picture. The rest of this post is the Puppeteer-specific mechanics.

What "remote browser Chrome" actually means in Puppeteer

Puppeteer has two entry points:

puppeteer.launch() — spawns a local Chromium/Chrome process and connects to it over a local pipe or WebSocket.
puppeteer.connect() — attaches to an already running browser via a WebSocket URL.

A remote browser is just the second case where the WebSocket URL points at a machine that isn't yours. The browser could be a container in your own cluster, a VM you manage, or a hosted service. Puppeteer doesn't care about the topology; it only cares that the endpoint speaks CDP.

That distinction matters because almost every operational difference between "local Puppeteer" and "remote Puppeteer" comes from the fact that you no longer control the process lifecycle. You don't call browser.close() to kill a machine you don't own — you disconnect. You don't pass args to a process that's already running — those were set at launch time by whoever runs the browser. Understanding that split is the whole game.

Getting a browserWSEndpoint

The browserWSEndpoint is a ws:// or wss:// URL that Puppeteer uses to open a CDP session. There are three common ways to obtain one.

1. From a local launch. If you launch Chrome yourself with --remote-debugging-port=9222, you can read the endpoint from http://localhost:9222/json/version:

curl -s http://localhost:9222/json/version | jq -r '.webSocketDebuggerUrl'

This is useful for development, but it's not a remote browser — it's your own machine with an extra step.

2. From a self-hosted container. You run Chromium in Docker with a debugging port exposed, then construct the endpoint from the host and port. You own patching, scaling, session cleanup, and outbound network configuration.

3. From a hosted runtime. You request a session and the provider returns a ready-to-use browserWSEndpoint (often alongside a CDP URL and a live viewer link). This is the model Remote Browser uses: you get a connection string, paste it into puppeteer.connect(), and the browser is already running with the settings you requested. See Remote Browser online for how session provisioning works end to end.

The important property is that all three produce the same kind of URL. Your Puppeteer code doesn't change between them, which is why migrating from local to remote is usually a config change rather than a rewrite.

Connecting Puppeteer to a remote browser

Here is the minimal TypeScript pattern. It uses Playwright's CDP entry point because it handles reconnection and typed sessions well, but the same endpoint works with puppeteer.connect() directly.

import { chromium } from "playwright";

type SessionInfo = {
  browserWSEndpoint: string;
  cdpUrl: string;
};

async function runTask(session: SessionInfo) {
  // Connect over CDP to the remote Chromium instance.
  const browser = await chromium.connectOverCDP(session.cdpUrl, {
    timeout: 30_000,
  });

  // A remote session usually starts with one existing context.
  const context = browser.contexts()[0] ?? (await browser.newContext());
  const page = await context.newPage();

  try {
    await page.goto("https://example.com", { waitUntil: "domcontentloaded" });
    const title = await page.title();
    console.log("title:", title);

    // Do work here: fill forms, extract data, run assertions.
  } finally {
    // Disconnect, do not kill the remote browser unless you own it.
    await page.close();
    await browser.close();
  }
}

Two details are easy to get wrong.

First, browser.close() on a CDP connection disconnects the client. Whether it also terminates the remote browser depends on the provider and the session semantics. With a hosted runtime, you typically want to disconnect and let the session expire or be explicitly stopped through the API. Check your provider's docs — for Remote Browser, session lifecycle is covered in the documentation.

Second, if you're using Puppeteer directly rather than Playwright, the call is:

import puppeteer from "puppeteer";

const browser = await puppeteer.connect({
  browserWSEndpoint: session.browserWSEndpoint,
  defaultViewport: null,
});

defaultViewport: null matters when the remote browser already has a viewport configured. Forcing a viewport from the client can fight with the server-side setting and produce inconsistent screenshots.

Puppeteer browser versions and the install problem

Locally, puppeteer downloads a pinned Chrome build into a cache directory. That's what puppeteer browsers install chrome does — it fetches a specific revision and records it. The puppeteer browsers command family (also exposed through the puppeteer npm package) manages that cache: list, install, and remove browser builds.

This is convenient until it isn't. The problems are predictable:

Image size. Every CI runner and container needs the browser binary. That adds significant size to each image.
Version drift. Your package.json pins a Puppeteer version, which pins a Chrome revision. When you upgrade Puppeteer, you may silently change the browser your tests run against.
Platform mismatch. The Chrome build that works on your laptop may not match the architecture or libc of your production container.
Cold starts. Downloading and unpacking Chrome on every fresh worker adds latency you can't easily hide.

A remote browser inverts this. The browser version is a property of the server, not your client. You choose a version when you request a session, and your Puppeteer client just connects. There's no puppeteer browsers install chrome step in your build, no cache to warm, and no binary in your image.

The trade-off is that you now depend on the provider's version catalog. If you need a very specific Chrome build for a compatibility test, confirm it's available before you commit. For most automation and agent workloads, "a recent stable Chromium" is fine, and the operational savings dominate.

Concern	Local Puppeteer	Remote browser Chrome
Browser binary	Downloaded per machine/image	Runs server-side
Version control	Pinned by Puppeteer release	Selected per session
Launch args	You pass them to `launch()`	Set by the runtime at launch
Scaling	You manage processes and memory	Provider manages capacity
Session cleanup	`browser.close()` kills the process	Disconnect; session ends via API
Proxy / network	Your infra	Configurable per session
Debugging	Local DevTools	Live viewer + CDP

Puppeteer browser args when the browser is remote

puppeteer.launch({ args: [...] }) is one of the most-used Puppeteer APIs, and it's the one that changes most when you go remote. Those args are passed to the Chrome process at startup. If the process is already running on someone else's machine, you can't inject new args from the client.

In practice this means:

Flags you can still influence from the client are limited to CDP-level behavior — things like viewport, emulation, and network interception, which are set through the protocol rather than process flags.
Flags that must be set at launch — sandbox settings, headless mode, GPU flags, proxy configuration, and similar — have to be exposed by the runtime as session options.

So the question to ask any remote browser provider is: which launch args can I configure per session? A runtime that only gives you a fixed browser is fine for simple scraping but painful when you need a specific proxy, a particular user agent at the process level, or a non-default headless mode.

Remote Browser exposes configurable browser settings per session, including proxy and network options, rather than a fixed binary. If you need a specific combination, verify it against the documentation before designing around it.

Production criteria for a remote Puppeteer setup

Once the connection works, the interesting questions are operational. Here's a checklist that separates a demo from something you'd run on a schedule.

Session isolation. Each task should get its own browser context or its own browser, so cookies and storage from one job don't leak into another. Shared browsers with shared profiles are a common source of flaky, hard-to-reproduce bugs.

Persistent profiles when you need them. Some workflows — logged-in dashboards, multi-step flows — need state to survive across sessions. Others need a clean slate every time. A good runtime lets you choose, rather than forcing one model.

Reconnection behavior. WebSocket connections drop. Your client should handle a closed CDP socket by reconnecting or failing fast, not by hanging. Set explicit timeouts on connectOverCDP and on navigation.

Observability. When a remote task fails, you want to see what the browser saw. A live viewer and session recordings turn "it failed" into "here's the frame where the selector didn't match." See Remote control browser for how live session control fits into debugging.

Cost model. Remote browsers are usually billed by session time. That means idle sessions cost money, and a task that hangs on a waitForSelector with no timeout is a billing bug as much as a logic bug. Always set timeouts. Current rates are on the pricing page.

Network egress. If your automation pulls large payloads, egress can matter as much as browser time. Know what's metered.

When local Puppeteer is still the right call

Remote isn't automatically better. Local Puppeteer is the right choice when:

You're developing and iterating on selectors, where the feedback loop of a local browser is faster.
You need a browser build that isn't available remotely.
Your workload is small, infrequent, and runs on a machine that already has Chrome.
You're debugging a CDP-level issue and want full control of the process.

The migration path that works well is to keep local Puppeteer for development and point the same code at a remote endpoint in CI and production. Because the only difference is the connection URL, you can gate it on an environment variable:

const endpoint = process.env.BROWSER_WS_ENDPOINT;

const browser = endpoint
  ? await puppeteer.connect({ browserWSEndpoint: endpoint })
  : await puppeteer.launch({ headless: true });

That single branch lets you develop locally and run remotely without maintaining two code paths.

Where this fits for AI agents

Puppeteer remote browser setups are increasingly the substrate for AI browser agents rather than hand-written scripts. The reason is the same as above: agents need browsers that start fast, isolate cleanly, and can be observed when they go wrong. An agent that runs a hundred steps and fails at step ninety is only debuggable if you can replay the session.

If that's your use case, the Puppeteer mechanics in this post still apply — the agent framework ultimately drives a CDP connection — but the runtime requirements are stricter. Persistent profiles, proxy configuration, and live viewing move from "nice to have" to "required." Remote web browser covers the runtime side of that in more depth.

The practical takeaway: learn puppeteer.connect() and browserWSEndpoint once, and you can point your automation at a local Chrome, a container you run, or a hosted runtime without changing the code that does the actual work. The browser becomes a connection string, and everything above it stays portable.

For the CDP details underneath, the Chrome DevTools Protocol documentation is the authoritative reference, and Playwright's connectOverCDP behavior is documented in the Playwright docs.

Puppeteer Remote Browser Download: What You Install vs Connect

RemoteBrowser — Sat, 19 Sep 2026 03:50:04 +0000

Puppeteer Remote Browser Download: What You Install vs Connect

If you searched for a "puppeteer remote browser download," you probably want one of two things: the Chrome binary that Puppeteer needs locally, or a way to run Puppeteer against a browser that isn't on your machine. Those are different problems, and the commands people copy from each other often solve the wrong one. This guide separates them: what puppeteer browsers install chrome downloads, what browserWSEndpoint actually points at, and how to connect Puppeteer to a hosted Chromium session when local downloads stop being practical.

The two meanings of "Puppeteer remote browser download"

Puppeteer has always shipped with a browser download step. Historically, npm install puppeteer pulled a pinned Chrome build into a cache directory. Since Puppeteer v19+, that behavior is more explicit: you can install Puppeteer as a library and manage browser binaries separately with the @puppeteer/browsers CLI.

That gives you two distinct workflows:

Local binary management. You download Chrome/Chromium to disk and launch it as a child process. Puppeteer talks to it over a local pipe or WebSocket.
Remote connection. You skip the download entirely and connect to a browser already running somewhere else — a container, a VM, or a hosted runtime — using puppeteer.connect() with a WebSocket endpoint.

The phrase "remote browser download" blurs these. A remote browser isn't something you download; it's something you connect to. What you download is the client — the Puppeteer library and, optionally, a local Chrome for development.

What `puppeteer browsers install chrome` actually does

The modern CLI is @puppeteer/browsers. It's a standalone package that manages browser binaries independently of the Puppeteer library version.

# Install the CLI
npm install @puppeteer/browsers

# Download a specific Chrome build into a cache dir
npx @puppeteer/browsers install chrome@stable

# Or pin an exact version
npx @puppeteer/browsers install chrome@121.0.6167.85

# List what's already cached
npx @puppeteer/browsers list

Key behaviors worth knowing:

Binaries land in a cache directory, not node_modules. On Linux that's typically ~/.cache/puppeteer; on macOS it's under ~/Library/Caches/puppeteer. This matters for Docker images and CI runners, where the cache path is often ephemeral.
chrome and chromium are different channels. chrome is the branded Google build; chromium is the open-source build. They have different version cadences and slightly different feature sets.
chrome-headless-shell is a separate download. If you only need headless automation, this is a smaller binary than full Chrome. Puppeteer can use it, but some features (extensions, certain rendering paths) differ.
Version pinning is explicit. chrome@stable tracks the stable channel; an exact version string locks you to a build. Reproducible CI usually wants the exact version.

If you're using the full puppeteer package rather than puppeteer-core, the install script handles this for you. puppeteer-core never downloads a browser — it expects you to supply one, either locally or via a connection URL.

Why the download step causes problems in production

The download is fine on a laptop. In production it creates friction:

Image size. A full Chrome build adds a large amount of disk to a container image.
Cold-start latency. Downloading on first boot adds seconds to every fresh instance.
Version drift. Different services pin different Chrome versions, and a shared cache can serve the wrong one.
Missing system libraries. Chrome needs a set of shared libraries (libnss3, libatk, libgbm, and friends). Minimal base images don't have them, and the failure mode is a cryptic launch error.
Sandbox requirements. Chrome's sandbox needs specific kernel capabilities. Many container runtimes require --no-sandbox, which weakens isolation.

None of these are fatal, but together they're why teams eventually ask whether they need to download a browser at all.

Connecting instead of downloading: `browserWSEndpoint`

Puppeteer's remote story is puppeteer.connect(). You give it a WebSocket URL, and it attaches to an already-running browser over the Chrome DevTools Protocol (CDP).

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.connect({
  browserWSEndpoint: 'wss://your-endpoint.example/devtools/browser/<id>',
  defaultViewport: null,
});

const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle2' });
const title = await page.title();
console.log(title);

// Disconnect without killing the remote browser
await browser.disconnect();

Three details that trip people up:

disconnect() vs close(). disconnect() detaches your client and leaves the browser running. close() sends a command that shuts the browser down. For a hosted session you usually want disconnect().
puppeteer-core is the right package here. The full puppeteer package bundles a download step you don't need when connecting remotely.
The endpoint is a capability. Anyone with the WebSocket URL can drive that browser. Treat it like a credential — don't log it, don't commit it, and rotate it per session where the runtime supports it.

The browserWSEndpoint you get from a hosted runtime is typically per-session and short-lived. That's a feature: it means a leaked URL has a bounded blast radius.

Puppeteer vs Playwright for remote connections

Both libraries speak CDP, but their remote ergonomics differ. If you're choosing a client for a hosted runtime, this table is the practical summary.

Concern	Puppeteer	Playwright
Remote connect API	`puppeteer.connect({ browserWSEndpoint })`	`chromium.connectOverCDP(endpoint)`
Package for remote-only use	`puppeteer-core`	`playwright-core`
Browser download on install	Yes, with full `puppeteer`	Yes, with full `playwright`
Multi-browser support	Chrome/Chromium/Firefox (limited)	Chromium, Firefox, WebKit
Auto-waiting	Manual (`waitForSelector`, etc.)	Built into locators
CDP session access	`page.target().createCDPSession()`	`context.newCDPSession(page)`
Best fit	Chrome-centric automation, existing Puppeteer code	Cross-browser testing, newer agent code

Neither is wrong. If you have a working Puppeteer codebase, puppeteer.connect() is a two-line change. If you're starting fresh and want cross-browser coverage, Playwright's connectOverCDP is the equivalent path — see the Playwright CDP documentation for the exact semantics, including the Chromium-only constraint.

A TypeScript example: Playwright over CDP to a hosted session

Most teams that outgrow local downloads end up on Playwright for new code, because the auto-waiting behavior reduces flaky selectors. Here's a typed example that connects to a hosted Chromium session over CDP, creates a context, and cleans up properly.

import { chromium, type Browser, type BrowserContext } from 'playwright-core';

interface SessionInfo {
  cdpUrl: string;
  sessionId: string;
}

async function runTask(session: SessionInfo): Promise<string> {
  let browser: Browser | undefined;
  let context: BrowserContext | undefined;

  try {
    // connectOverCDP attaches to an existing browser; it does not launch one.
    browser = await chromium.connectOverCDP(session.cdpUrl, {
      timeout: 30_000,
    });

    // A hosted session usually exposes one default context.
    context = browser.contexts()[0] ?? (await browser.newContext());

    const page = await context.newPage();
    await page.goto('https://example.com', {
      waitUntil: 'domcontentloaded',
      timeout: 45_000,
    });

    // Locators auto-wait; no manual sleep needed.
    const heading = await page.locator('h1').first().innerText();
    return heading;
  } finally {
    // Close the page/context you created, then detach.
    await context?.close().catch(() => {});
    await browser?.close().catch(() => {});
  }
}

const session: SessionInfo = {
  cdpUrl: process.env.REMOTE_BROWSER_CDP_URL!,
  sessionId: process.env.REMOTE_BROWSER_SESSION_ID!,
};

runTask(session)
  .then((h) => console.log('heading:', h))
  .catch((err) => {
    console.error('task failed:', err);
    process.exitCode = 1;
  });

Notes on the code:

connectOverCDP is Chromium-only. It won't attach to Firefox or WebKit. If you need those, you need a different transport.
browser.close() on a CDP connection closes the connection and, depending on the runtime, may terminate the remote browser. If you want to preserve session state, detach instead and let the runtime reap the session on its own schedule.
Timeouts are explicit. Remote connections add network latency that local pipes don't have. Default timeouts that work locally often need to be raised.
playwright-core avoids the browser download. Same reasoning as puppeteer-core.

Browser args and version pinning on remote sessions

puppeteer browser args and puppeteer browser version are common follow-up searches, and they behave differently when the browser isn't yours.

Locally, you pass args at launch:

const browser = await puppeteer.launch({
  args: ['--no-sandbox', '--disable-dev-shm-usage', '--window-size=1280,800'],
});

Remotely, you can't pass launch args — the browser is already running. Instead, the runtime exposes configurable browser settings: viewport, locale, timezone, user agent, proxy configuration, and similar session-level options. If you need a specific Chrome version, you select it when creating the session rather than pinning it in your client code.

This is a real trade-off. You lose fine-grained control over the process, and you gain consistency: every session starts from the same known configuration, and you're not debugging why one container has a different libgbm version than another.

For a deeper look at how session configuration and profiles work on a hosted runtime, see Remote Browser for AI agents.

When to download, when to connect

A decision table, since this is the actual question behind the search.

Situation	Download locally	Connect to remote
Local development and debugging	✅	Optional
One-off scripts on your laptop	✅	Overkill
CI with a stable base image	✅ (cached)	✅
Serverless / short-lived functions	❌	✅
Horizontal scale beyond a few instances	❌	✅
Sessions that must survive worker restarts	❌	✅
Need for persistent profiles across runs	❌	✅
Strict reproducibility across environments	❌	✅
Air-gapped or offline environments	✅	❌

The pattern: local downloads are fine when the environment is stable and the browser's lifetime matches the process's lifetime. Remote connections win when the browser needs to outlive the worker, or when you're running enough instances that per-instance browser management becomes a maintenance burden.

Production criteria for a remote browser runtime

If you're evaluating hosted Chromium for Puppeteer or Playwright, these are the things that actually matter in production — not the marketing bullets.

CDP compatibility. Does it expose a standard browserWSEndpoint that puppeteer.connect() and chromium.connectOverCDP() accept without patched clients? If you need a custom SDK, that's a lock-in signal.
Session isolation. Are sessions isolated from each other at the process or container level? Shared browser processes leak state between tenants.
Persistent profiles. Can a session retain cookies and local storage across runs? This is essential for authenticated workflows and impossible with ephemeral local Chrome.
Live viewer. Can you watch a session in real time when something fails? Debugging a headless remote browser without a viewer is painful.
Proxy and network controls. Per-session proxy configuration, and clarity about which egress IPs you'll see.
Usage controls. Per-session time limits, concurrency caps, and a way to see what you're spending. Check /pricing for current rates rather than trusting a blog post.
Observability. Session logs, CDP event access, and the ability to attach a debugger mid-session.

For a broader comparison of hosted versus self-managed browser infrastructure, Remote Browser online covers the operational trade-offs.

Migrating an existing Puppeteer script

The migration is smaller than it looks. The typical diff:

- const browser = await puppeteer.launch({
-   headless: 'new',
-   args: ['--no-sandbox'],
- });
+ const browser = await puppeteer.connect({
+   browserWSEndpoint: process.env.REMOTE_BROWSER_WS_ENDPOINT,
+   defaultViewport: null,
+ });

Then:

Swap puppeteer for puppeteer-core in package.json to drop the download step.
Remove --no-sandbox and other launch args. They're the runtime's concern now.
Move viewport and user-agent settings from launch options to session creation or page.setViewport().
Replace browser.close() with browser.disconnect() if you want the session to persist.
Raise timeouts. Network hops add latency; 30s defaults may be too tight.
Handle reconnection. Remote sessions can drop. Wrap your task in retry logic that creates a fresh session rather than assuming the old endpoint is still valid.

Step 6 is the one people skip, and it's the one that causes production incidents.

Where Remote Browser fits

Remote Browser provides hosted Chromium sessions with CDP access, so puppeteer.connect() and chromium.connectOverCDP() work without a custom client. Sessions support persistent profiles, configurable browser settings including proxy configuration, a live viewer for debugging, and per-session usage controls.

The practical upshot for the "download" question: you install puppeteer-core or playwright-core, you never download a browser binary, and you connect to a session that's already running. That removes the image-size, cold-start, and version-drift problems described earlier — at the cost of a network hop and a dependency on the runtime's availability.

Start with the documentation for connection details and session lifecycle, and check /pricing for current usage rates. If you're still deciding between local and remote, Remote web browser walks through the runtime model in more depth.

Summary

puppeteer browsers install chrome downloads a Chrome binary to a local cache. It does not give you a remote browser.
A remote browser is something you connect to via puppeteer.connect({ browserWSEndpoint }) or chromium.connectOverCDP().
Use puppeteer-core / playwright-core when connecting remotely — they skip the download entirely.
Launch args don't apply to remote sessions; session-level configuration replaces them.
Download locally for development and stable CI; connect remotely for serverless, horizontal scale, persistent profiles, and sessions that outlive workers.
The migration is a handful of lines plus retry logic. The retry logic is the part that matters.

Playwright Chrome Recorder: Record, Export, and Run Remotely

RemoteBrowser — Fri, 18 Sep 2026 03:28:24 +0000

Playwright Chrome Recorder: Record, Export, and Run Remotely

The Playwright Chrome Recorder is a browser extension that captures clicks, typing, and navigation in a real Chrome tab and exports them as a Playwright test script. It is the fastest way to get a working selector for a stubborn element, and a reasonable way to bootstrap a test you will later harden. It is not a test generator you can ship unedited, and it does not run anything for you — it produces code you still have to execute somewhere.

That last point matters more than it used to. Once a recording exists, the question shifts from "how do I capture this flow" to "where does this script actually run." Locally, you are managing Chrome versions, driver binaries, and a machine that has to stay awake. On a hosted runtime, you connect over CDP and the browser lives somewhere else. This guide covers the recorder itself, what its output is worth, and how to point the resulting script at a remote Chromium session.

What the Playwright Chrome Recorder Actually Does

The recorder ships as a Chrome extension. You open it against the tab you want to capture, hit record, and interact with the page normally. Each action becomes a line in a generated script. When you stop, you can copy the output as a Playwright test, a Puppeteer script, or a set of raw actions.

The extension is maintained alongside Playwright, so the generated code tracks current API conventions rather than the older page.$eval style you see in stale tutorials. Selectors are the interesting part: the recorder prefers role-based and text-based locators (getByRole, getByLabel, getByText) over brittle CSS paths, which is a meaningful improvement over naive recording tools that emit div > div:nth-child(3) > span.

What it captures:

Clicks and taps on interactive elements, with a best-effort accessible-name selector.
Text input, including per-field values as you type them.
Navigation, including form submissions that trigger page loads.
Assertions, if you manually add them through the recorder UI — visibility, text content, and value checks.

What it does not capture: network interception, multi-tab or multi-context flows, file uploads in every case, iframe interactions reliably, and anything involving authentication state you set up outside the recorded tab. It also records what you did, not what you meant. If you clicked a button twice because the first click was slow, you get two clicks.

Reading the Generated Script Critically

A recorded script is a draft. Treat the output as a starting point and expect to edit it before it goes into CI.

Selectors degrade. The recorder picks the best locator it can find at record time. If the page had a stable data-testid, great. If it fell back to visible text, that text is now a coupling point — a copy change breaks your test. Review every locator and replace text-based ones with stable attributes where the application exposes them.

Timing is implicit. Recorded scripts rely on Playwright's auto-waiting, which handles most cases but not all. Flows with debounced search, optimistic UI updates, or animations that settle late will need explicit expect(...).toBeVisible() assertions rather than a bare click.

State is missing. The recording starts from whatever state your browser was in. If you were logged in, the script assumes you are logged in. There is no storageState setup, no fixture, no teardown. You have to add that.

Values are hardcoded. Credentials, search terms, and IDs get baked in as literals. Parameterize them before the script touches a shared environment.

A practical workflow: record the flow, extract the selectors you could not figure out by hand, then rewrite the script around your own fixtures and page objects. The recorder's real value is selector discovery, not test authoring.

From Recording to Execution: Where the Script Runs

Here is where most teams hit friction. A recorded script is a Playwright script, and Playwright scripts need a browser. Three options, with real trade-offs:

Approach	Setup cost	Isolation	Scaling	Best for
Local Chrome + `playwright install`	Low initially, recurring per machine	None — shares your desktop session	Manual, one machine	Debugging, one-off selector capture
Self-hosted Playwright in containers	High — image builds, driver pinning, orchestration	Per container	Requires scheduler and capacity planning	Teams with existing infra and ops headcount
Hosted Chromium over CDP	Low — one connection string	Per session	Handled by the provider	CI, agents, parallel test runs

The local path is fine for recording. It stops being fine when the script needs to run on a schedule, in CI, or from a machine that is not your laptop. The self-hosted path works but the maintenance is real: Chromium updates break driver compatibility, container images drift, and you end up owning a browser fleet.

The hosted path replaces all of that with a WebSocket endpoint. You call chromium.connectOverCDP(endpoint) instead of chromium.launch(), and the rest of your script is unchanged. Remote Browser exposes exactly this — hosted Chromium sessions with CDP access, Playwright/Puppeteer/Selenium compatibility, persistent profiles, and a live viewer for debugging. You can see the connection model in the documentation.

Connecting a Recorded Script to Remote Chromium

The migration from local to remote is a two-line change. Here is a TypeScript example that takes a recorded flow and runs it against a hosted session:

import { chromium, Browser, Page } from 'playwright';

const CDP_ENDPOINT = process.env.REMOTE_BROWSER_WS!;

async function runRecordedFlow(): Promise<void> {
  // connectOverCDP attaches to an existing browser instead of launching one.
  const browser: Browser = await chromium.connectOverCDP(CDP_ENDPOINT);

  // A remote session may already have a context; reuse it if so.
  const context = browser.contexts()[0] ?? (await browser.newContext());
  const page: Page = context.pages()[0] ?? (await context.newPage());

  try {
    await page.goto('https://example.com/login');

    // Locators below are what the recorder would emit, hardened by hand.
    await page.getByLabel('Email').fill(process.env.TEST_EMAIL!);
    await page.getByLabel('Password').fill(process.env.TEST_PASSWORD!);
    await page.getByRole('button', { name: 'Sign in' }).click();

    // Replace implicit waits with explicit assertions.
    await page.getByRole('heading', { name: 'Dashboard' }).waitFor();

    await page.getByRole('link', { name: 'Reports' }).click();
    await page.getByRole('button', { name: 'Export CSV' }).click();

    const download = await page.waitForEvent('download');
    console.log('Saved to:', await download.path());
  } finally {
    // Close the connection, not the remote browser, unless you own its lifecycle.
    await browser.close();
  }
}

runRecordedFlow().catch((err) => {
  console.error(err);
  process.exit(1);
});

Three details worth noting. First, connectOverCDP is Chromium-only — it will not attach to Firefox or WebKit, so if your recorded flow needs cross-browser coverage you will run the local-launch path for those engines. Second, browser.contexts()[0] may already exist on a remote session; creating a second context is fine but changes your isolation semantics. Third, closing the browser object closes the CDP connection. Whether that tears down the remote session depends on the provider's lifecycle rules, so check before you rely on it.

If you are still deciding between attaching to an existing browser and launching a fresh one, the trade-offs are covered in Playwright attach to existing browser.

Production Criteria for Recorded Flows

A recording that works once is not a test. Before a recorded flow runs unattended, it needs to survive these conditions:

Authentication. Recorded flows assume a logged-in state. Move login into a setup step that writes storageState, then reuse it across tests. On a hosted runtime, persistent profiles let you keep that state across sessions without re-authenticating every run.

Parallelism. Recorded scripts often share a single browser context, which serializes them. Give each test its own context or session so runs do not collide on cookies or local storage. Session isolation is a runtime property, not something you can patch in the script.

Flakiness. The most common cause is a selector that matched something incidental at record time. The second most common is a missing wait. Both are fixable by editing the script, not by adding retries — retries hide the problem and inflate your runtime bill.

Observability. When a recorded flow fails in CI, you need the trace, the screenshot, and ideally a live view of the session. Playwright's trace viewer covers the first two. For the third, a live viewer attached to the remote session lets you watch the run as it happens rather than reconstructing it afterward.

Cost control. Browser time is metered on hosted runtimes. A recorded flow with generous waitForTimeout calls burns session minutes doing nothing. Replace fixed sleeps with event-based waits and your bill drops accordingly. Current rates are on the pricing page.

Recorder vs. Hand-Written vs. Agent-Driven

The recorder is one of three ways to produce a browser script, and it is not always the right one.

Use the recorder when you are reverse-engineering a complex UI, the selectors are non-obvious, or you need a quick smoke test for a flow you already understand.

Write by hand when the flow has branching logic, data-driven steps, or assertions that depend on computed values. Recorded scripts do not express conditionals well, and retrofitting them is more work than starting clean.

Use an agent when the flow is exploratory or changes frequently — the agent reads the page and decides what to click, so selector drift does not break it the way it breaks a recorded script. Agents still need a browser to run in, and the runtime requirements are similar: CDP access, session isolation, and a way to observe what happened. That overlap is why the same hosted runtime serves both recorded tests and agent workloads; see Remote Browser for AI agents.

A hybrid works well in practice: record once to discover selectors, hand-write the production test around them, and let an agent handle the flows that are too volatile to script.

Practical Setup Notes

A few things that save time when you wire the recorder into a real workflow:

Pin the extension version in your team's browser profile so everyone generates code against the same Playwright release.
Record against a staging environment, not production, so your captured values are not real customer data.
Strip credentials immediately. The recorder captures what you type. If you typed a real password, it is in the output.
Keep recordings out of version control until they are rewritten. A raw recording in a PR invites review comments about selectors that will not survive the first edit.
Test the remote connection before the flow. A connectOverCDP call that fails on a bad endpoint looks like a test failure if you do not separate the two.

For the connection layer specifically, the Playwright CDP documentation is the authoritative reference on connectOverCDP behavior, including the Chromium-only constraint and how contexts are exposed on an attached browser.

Where This Leaves You

The Playwright Chrome Recorder solves a narrow, real problem: turning a manual interaction into a locator you can trust. It does not solve execution, isolation, or maintenance, and treating it as a test-generation tool leads to brittle suites.

The productive pattern is to use the recorder for what it is good at — selector discovery — and invest your effort in the runtime and the test structure around it. If your scripts need to run on a schedule, in parallel, or from a machine that is not your laptop, a hosted Chromium session removes the browser-management work without changing your Playwright code. Start with the documentation to see the connection model, and check pricing before you plan capacity.

Playwright connectOverCDP GitHub: Connect to Remote Chrome

RemoteBrowser — Fri, 18 Sep 2026 03:28:23 +0000

Playwright connectOverCDP GitHub: Connect to Remote Chrome

If you searched for playwright connectovercdp github, you probably want one of two things: a working code example, or a repo that shows how to attach Playwright to a Chrome instance that is already running somewhere else. The short answer is that browserType.connectOverCDP() takes a WebSocket debugger URL and returns a Browser object you drive exactly like a locally launched one. The longer answer is that most GitHub examples stop at localhost:9222, and that is not the part that breaks in production.

This guide covers the API contract, what real GitHub examples get right and wrong, and how to point connectOverCDP at a hosted Chromium session so you are not maintaining Chrome, drivers, and profiles on every worker.

What connectOverCDP actually does

connectOverCDP is a method on BrowserType in Playwright. It opens a connection to a browser over the Chrome DevTools Protocol and returns a Browser instance. From that point on, the Playwright API is the same: browser.contexts(), context.newPage(), page.click(), and so on.

The important distinction is that you are not launching a browser. You are attaching to one that already exists. That means:

You do not control the browser binary version through Playwright's install step.
You do not get a fresh profile unless the remote side gives you one.
You inherit whatever contexts and pages are already open.
Lifecycle is shared — closing the connection is not the same as killing the browser.

This is why connectOverCDP is the right primitive for remote and hosted browsers, and why it behaves differently from chromium.launch() in ways that matter once you leave your laptop.

The API shape

const browser = await chromium.connectOverCDP(endpointURL, options);

endpointURL is either an HTTP URL (Playwright will discover the WebSocket URL from /json/version) or a ws:// / wss:// debugger URL directly. options accepts things like headers, timeout, and slowMo.

A minimal working example against a remote endpoint:

import { chromium, Browser, BrowserContext, Page } from 'playwright';

async function runTask(cdpEndpoint: string) {
  const browser: Browser = await chromium.connectOverCDP(cdpEndpoint, {
    timeout: 30_000,
  });

  // A hosted session usually hands you one context already.
  const context: BrowserContext =
    browser.contexts()[0] ?? (await browser.newContext());

  const page: Page = context.pages()[0] ?? (await context.newPage());

  await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
  const title = await page.title();
  console.log('title:', title);

  // Detach. Do not assume this kills the remote browser.
  await browser.close();
}

runTask(process.env.CDP_ENDPOINT!);

Two details worth internalizing. First, browser.contexts()[0] — a remote session often arrives with a context already created, and calling newContext() blindly can leave you with an orphaned blank context. Second, browser.close() on a CDP connection disconnects; whether the remote browser shuts down depends on the provider. Check that behavior before you build cleanup logic around it.

What GitHub examples get right and wrong

Searching GitHub for connectOverCDP returns a lot of near-identical snippets. They are useful as a starting point and misleading as a production reference. Here is the pattern you will see most often:

const browser = await chromium.connectOverCDP('http://localhost:9222');

That works if you launched Chrome with --remote-debugging-port=9222 on the same machine. It tells you nothing about authentication, TLS, session lifetime, or what happens when the endpoint is behind a load balancer.

Concern	Typical GitHub snippet	Production requirement
Endpoint	`http://localhost:9222`	`wss://` URL with auth, from a session API
Chrome binary	Assumed installed	Managed by the runtime, versioned
Profile	Default user profile	Isolated per session, optionally persistent
Auth	None	Token or signed URL in headers
Lifecycle	`browser.close()`	Explicit session teardown via API
Concurrency	One browser	Pooled sessions, per-session isolation
Failure mode	Crash	Reconnect, retry, or new session
Observability	`console.log`	Live viewer, session logs, traces

The gap is not the Playwright call. The gap is everything around it. If you are evaluating a GitHub repo as a template, check whether it handles the right column at all. Most do not, because the authors were demonstrating the API, not operating it.

The `--remote-debugging-port` trap

A common GitHub pattern is to shell out to Chrome with --remote-debugging-port=9222 and then connect. This works locally and fails in almost every hosted environment for three reasons:

Binding. Chrome binds the debug port to 127.0.0.1 by default. Exposing it requires --remote-debugging-address=0.0.0.0, which is a security decision, not a convenience flag.
No auth. The DevTools Protocol has no built-in authentication. Anyone who can reach the port can drive the browser. On a public network that is a full compromise.
Version drift. The Chrome you install on a worker is not the Chrome the next worker installs. CDP surface area changes between versions.

Hosted runtimes solve this by giving you a wss:// endpoint with a token, a pinned Chromium build, and a session that is destroyed on teardown. That is the model to look for when you graduate from a GitHub snippet.

Wiring connectOverCDP to a hosted runtime

The practical flow with a hosted Chromium runtime is: create a session over HTTP, receive a CDP endpoint, connect Playwright to it, run your task, then release the session. The Playwright code does not change — only where the endpoint comes from.

import { chromium } from 'playwright';

type Session = {
  id: string;
  cdpUrl: string; // wss://... provided by the runtime
};

async function createSession(): Promise<Session> {
  const res = await fetch('https://api.remote-browser.dev/v1/sessions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.REMOTE_BROWSER_TOKEN}`,
    },
    body: JSON.stringify({
      // configurable browser settings, not hardcoded fingerprints
      profile: { persistent: true, name: 'checkout-agent' },
      viewport: { width: 1440, height: 900 },
    }),
  });
  if (!res.ok) throw new Error(`session create failed: ${res.status}`);
  return (await res.json()) as Session;
}

async function releaseSession(id: string) {
  await fetch(`https://api.remote-browser.dev/v1/sessions/${id}`, {
    method: 'DELETE',
    headers: { Authorization: `Bearer ${process.env.REMOTE_BROWSER_TOKEN}` },
  });
}

async function main() {
  const session = await createSession();
  const browser = await chromium.connectOverCDP(session.cdpUrl, {
    timeout: 30_000,
  });

  try {
    const context = browser.contexts()[0] ?? (await browser.newContext());
    const page = context.pages()[0] ?? (await context.newPage());
    await page.goto('https://example.com');
    // ... your task
  } finally {
    await browser.close();
    await releaseSession(session.id);
  }
}

main();

The endpoint shape and session API differ by provider. What matters is that the endpoint is authenticated, the session has a defined lifetime, and teardown is explicit. You can read more about the runtime model in Remote Browser for AI agents.

Why persistent profiles matter here

With connectOverCDP, the profile is whatever the remote browser already has. If you want cookies, localStorage, and logged-in state to survive across sessions, the runtime has to persist them. If you want a clean slate every time, it has to isolate them. Either way, that is a runtime decision, not a Playwright one — connectOverCDP gives you no profile control beyond what the endpoint exposes.

For agents that log in once and then run many tasks, persistent profiles cut a large amount of redundant work. For agents that must not leak state between tenants, isolation is the requirement. Both are configuration, not code.

Production criteria for a CDP endpoint

Once you move past GitHub snippets, evaluate the endpoint against these criteria:

Transport. wss:// with TLS, not plain ws://. The DevTools Protocol is fully privileged.
Auth. A token or signed URL per session. Rotate it. Do not share one endpoint across tenants.
Isolation. One browser process per session, or at minimum one context per tenant with no shared storage.
Version pinning. A known Chromium build so CDP behavior is stable across deploys.
Lifecycle. A session ID you can query and destroy. browser.close() alone is not enough.
Observability. A live viewer or session recording so you can debug a failed run without reproducing it.
Network controls. Proxy configuration and browser settings you can set per session, since IP reputation affects success rates on protected sites.
Reconnect semantics. What happens if the WebSocket drops mid-task. A good runtime lets you reconnect to the same session.

If a provider cannot answer these, you are back to running Chrome on your own workers — which is fine, but then you own the --remote-debugging-port problem described above.

Common failure modes and how to debug them

connectOverCDP times out. Usually the endpoint is reachable but the WebSocket upgrade is blocked by a proxy or firewall. Test with curl -i <http-endpoint>/json/version first; if that returns JSON, the HTTP side is fine and the issue is the upgrade path.

Connection succeeds but browser.contexts() is empty. The remote browser has no context yet. Call newContext(). Do not assume a context exists.

Pages close unexpectedly. Something else is driving the same browser. With CDP, multiple clients can attach. If your runtime allows it, avoid sharing a session across processes.

Navigation hangs. Check whether the remote browser has network access to the target. A hosted session may have different egress rules than your local machine.

browser.close() does not stop billing. It should not — closing a CDP connection is a detach. Release the session through the provider's API. See pricing for how sessions are metered.

Version mismatch errors on newer CDP methods. The remote Chromium is older than your Playwright version expects. Pin both, or use a runtime that tracks recent Chromium releases.

When to use connectOverCDP vs launch

Use chromium.launch() when the browser runs on the same machine as your code and you control the environment. Use connectOverCDP when the browser runs somewhere else — a container, a VM, or a hosted runtime.

The trade-off is control versus operational cost. launch() gives you full control over flags, binary, and profile, at the cost of installing and maintaining Chrome everywhere your code runs. connectOverCDP gives you a stable endpoint and offloads that maintenance, at the cost of depending on the endpoint's behavior and lifecycle.

For AI agents and long-running automation, the second model usually wins because the hard part is not the Playwright call — it is keeping browsers alive, isolated, and debuggable across many concurrent tasks. That is the problem a hosted runtime solves. You can see the broader picture in Remote Browser online and remote control browser.

Practical checklist

Before you ship a connectOverCDP integration:

Confirm the endpoint is wss:// and authenticated.
Handle the case where browser.contexts() is empty.
Treat browser.close() as a detach, not a teardown.
Release sessions explicitly through the provider API.
Pin your Playwright version and know the remote Chromium version.
Add a reconnect path for dropped WebSockets.
Log the session ID with every task so failures are traceable.
Test against the actual target sites, not just example.com.

The Playwright API is the easy part. The runtime is where reliability is won or lost. For the API reference, see the Playwright CDP documentation and the Chrome DevTools Protocol spec. For the runtime side, start with the documentation.

Playwright MCP Connect to Existing Browser: A Practical Guide

RemoteBrowser — Thu, 17 Sep 2026 03:35:19 +0000

Playwright MCP Connect to Existing Browser: A Practical Guide

If you want Playwright MCP to connect to an existing browser instead of launching its own, the answer is CDP. The Playwright MCP server drives a browser over the Chrome DevTools Protocol, and browserType.connectOverCDP() is the entry point that lets it attach to a Chrome or Chromium instance that is already running — locally, on another host, or inside a hosted runtime. This guide covers how the connection actually works, what breaks in practice, and how to point MCP at a remote Chromium session you don't have to babysit.

What "connect to an existing browser" means for Playwright MCP

Playwright MCP is a Model Context Protocol server that exposes browser actions — navigate, click, type, snapshot — as tools an LLM can call. By default it launches its own Chromium process. That default is fine for a laptop demo and wrong for almost everything else: the browser dies when the process exits, the profile is throwaway, and you can't see what the agent is doing.

Connecting to an existing browser changes the ownership model. Instead of MCP spawning Chromium, you give it a WebSocket endpoint that a running browser is already listening on. MCP attaches, takes over the page context, and drives it. The browser keeps running whether or not MCP is alive.

There are two ways to get that endpoint:

Launch Chrome yourself with --remote-debugging-port. You control the flags, the profile directory, and the lifecycle.
Use a hosted runtime that exposes a CDP endpoint. You get a URL, paste it into your config, and the runtime handles process management, isolation, and cleanup.

The second option is what most production agent stacks converge on, because the first one means you're now operating Chrome fleets.

How the CDP handshake works

When Playwright calls connectOverCDP(), it opens a WebSocket to the browser's DevTools endpoint, typically ws://host:port/devtools/browser/<id>. Over that socket it speaks the Chrome DevTools Protocol — the same protocol Chrome DevTools itself uses. Playwright then wraps the connection in its normal Browser object, so browser.contexts(), page.goto(), and locators all work as usual.

Two details matter and are easy to get wrong:

connectOverCDP is Chromium-only. Firefox and WebKit do not implement the CDP surface Playwright needs here. If your MCP config points at a Firefox endpoint, the connection will fail or behave unpredictably. Use Chromium.
You attach to existing contexts, not new ones. With connectOverCDP, browser.newContext() is not available in the way it is for a launched browser. You work with browser.contexts()[0] or create pages on the default context. Code that assumes a fresh context per task will need adjusting.

The official Playwright reference for this method is browserType.connectOverCDP() in the Playwright API docs.

Minimal TypeScript example

Here is the shape of a connection you can adapt for an MCP server or a standalone script. It assumes you already have a CDP WebSocket URL.

import { chromium, Browser, BrowserContext, Page } from 'playwright';

const CDP_ENDPOINT = process.env.CDP_WS_ENDPOINT!; // ws://.../devtools/browser/<id>

async function attach(): Promise<{ browser: Browser; context: BrowserContext; page: Page }> {
  const browser = await chromium.connectOverCDP(CDP_ENDPOINT, {
    timeout: 30_000,
  });

  // connectOverCDP attaches to existing contexts; do not call newContext().
  const context = browser.contexts()[0];
  if (!context) {
    throw new Error('No browser context available on the CDP endpoint');
  }

  const page = context.pages()[0] ?? (await context.newPage());

  // Confirm the connection is live before handing it to an agent.
  await page.goto('about:blank');
  return { browser, context, page };
}

async function main() {
  const { browser, page } = await attach();
  await page.goto('https://example.com');
  console.log(await page.title());

  // Close the Playwright connection, not the remote browser.
  await browser.close();
}

main().catch((err) => {
  console.error('CDP attach failed:', err);
  process.exit(1);
});

The important line is browser.close(). Over CDP, that closes the Playwright connection. Whether the underlying browser process terminates depends on how it was started — a hosted runtime typically keeps the session alive until you explicitly release it, which is what you want when a second tool or a human viewer needs to stay attached.

Configuring Playwright MCP to use an existing browser

Playwright MCP accepts a CDP endpoint through its configuration. The exact flag name depends on your MCP client and server version, but the pattern is consistent: you supply a WebSocket URL instead of letting the server launch Chromium. A typical config block looks like this:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--cdp-endpoint",
        "wss://your-runtime.example/devtools/browser/abc123"
      ]
    }
  }
}

Check the current flag against your installed server version before you commit it to a repo — MCP server options have moved around, and a stale flag fails silently in some clients. If you're running against a hosted runtime, the endpoint is usually handed to you per session, so the config is generated at runtime rather than hardcoded.

Local Chrome vs hosted Chromium for MCP

The decision is not really about Playwright. It's about who owns the browser process.

Criterion	Local Chrome + `--remote-debugging-port`	Hosted Chromium runtime
Setup	Manual flags, profile dir, port management	Paste a CDP URL
Lifecycle	Dies with your shell or machine	Survives client restarts
Isolation	Shared profile, shared cookies	Session-scoped, isolated
Concurrency	One browser, one port, contention	Multiple sessions, separate endpoints
Observability	DevTools on localhost only	Live viewer, remote access
Proxies / network	Your machine's IP	Configurable per session
Scaling	You operate the fleet	Runtime operates the fleet
Debugging	Attach DevTools locally	Attach DevTools or use the viewer

Local Chrome is the right call when you're debugging a selector or reproducing a bug on your own machine. It stops being the right call the moment the agent needs to run unattended, run more than one session at a time, or run from a machine that isn't yours.

Common failure modes

Most "Playwright MCP won't connect" reports trace back to a small set of causes.

The endpoint is an HTTP URL, not a WebSocket URL. connectOverCDP wants ws:// or wss://. An http://host:9222 value will fail. Fetch http://host:9222/json/version and read the webSocketDebuggerUrl field if you need to discover it.

Chrome wasn't started with remote debugging enabled. Without --remote-debugging-port, there is no endpoint to connect to. If you're launching Chrome yourself, that flag is mandatory. If you're using a hosted runtime, the endpoint is created for you.

The browser is bound to localhost. A CDP port on 127.0.0.1 is unreachable from another container or host. Hosted runtimes solve this by exposing a routable endpoint; self-hosted setups need --remote-debugging-address=0.0.0.0 plus network controls, which is a security decision, not just a config tweak.

The connection drops mid-session. CDP WebSockets are long-lived and fragile across networks. Production code should treat a dropped connection as recoverable: reconnect, re-resolve the page, and continue. Don't assume the socket outlives the task.

You called newContext(). As noted above, connectOverCDP attaches to existing contexts. Code ported from a launch() flow will throw here.

Version skew. Playwright's CDP client tracks a specific protocol surface. A browser far ahead of your Playwright version can expose methods Playwright doesn't expect. Pin both sides.

Why hosted Chromium fits MCP better than local Chrome

MCP servers are usually spawned by a client — an IDE, a chat app, an agent framework — and that client restarts constantly. If the browser is a child process of the MCP server, every restart destroys the session: cookies gone, login gone, half-finished task gone.

Decoupling the browser from the MCP process fixes this. The runtime holds the Chromium session; MCP holds a connection to it. Restart the client, reconnect to the same endpoint, and the page is still where you left it. That's the same architectural argument behind remote browsers for AI agents, and it applies whether your agent is a coding assistant or a scheduled scraper.

The other practical win is the live viewer. When an agent is driving a browser over CDP, you can't see anything unless you attach DevTools. A hosted runtime that exposes a viewer lets you watch the session in a browser tab while the agent works — which turns "the agent did something weird" from a log-reading exercise into a thirty-second observation. This is the same reason remote control of a browser matters for debugging agent runs.

Production criteria before you commit

If you're choosing between self-hosted Chrome and a hosted runtime for MCP, evaluate against these:

Session persistence. Does the browser survive an MCP client restart? If not, you'll rebuild auth state constantly.
Isolation. Can two concurrent agents share a browser without leaking cookies or storage between them? They shouldn't.
Endpoint stability. Is the CDP URL stable for the life of a session, or does it rotate in ways your reconnect logic must handle?
Network controls. Can you route traffic through a specific proxy per session? Many sites behave differently by IP, and this is a per-session concern, not a global one.
Observability. Can a human watch the session without SSH access to the host?
Cleanup guarantees. When a task ends or crashes, does the session get released? Orphaned Chromium processes are the default failure mode of self-hosted setups.
Cost model. Browser time is metered differently across providers. Check current pricing rather than assuming a per-task or per-hour model.

None of these are Playwright problems. They're runtime problems, and they're the reason the "connect to an existing browser" pattern exists in the first place.

A reasonable default

For local development, launch Chrome with --remote-debugging-port=9222, point Playwright MCP at the discovered WebSocket URL, and iterate. You get fast feedback and full DevTools.

For anything that runs unattended, move the browser off your machine. Start a hosted Chromium session, take the CDP endpoint it returns, and configure MCP to attach. Keep the reconnect logic, keep the browser.close() semantics straight, and treat the session as a resource with a lifecycle rather than a process your script happens to own.

The connection mechanics are the same in both cases — a WebSocket, a protocol, a Browser object. What changes is who's responsible when the browser dies at 3 a.m. That's the part worth getting right before you ship.

Puppeteer In Browser: Run Puppeteer Against Hosted Chromium

RemoteBrowser — Thu, 17 Sep 2026 03:35:18 +0000

Puppeteer In Browser: Run Puppeteer Against Hosted Chromium

Running Puppeteer in browser environments usually means one of two things: you want Puppeteer to drive a browser that isn't on your machine, or you want to run Puppeteer itself somewhere other than your laptop. Both cases come down to the same mechanism — the Chrome DevTools Protocol (CDP). Puppeteer talks to Chrome over a WebSocket, and that WebSocket doesn't have to point at localhost. Point it at a hosted Chromium session and your script runs unchanged.

This guide covers what "Puppeteer in browser" actually means in practice, how puppeteer.connect() differs from puppeteer.launch(), what breaks when you move to remote Chrome, and how to structure a production setup on a hosted runtime like Remote Browser.

What "Puppeteer in browser" actually means

Puppeteer is a Node library that controls Chrome or Chromium. It has two entry points:

puppeteer.launch() — spawns a local Chrome process and connects to it.
puppeteer.connect({ browserWSEndpoint }) — attaches to a Chrome instance that is already running, anywhere reachable over the network.

The second form is what makes Puppeteer usable in browser-adjacent contexts: serverless functions, containers without a bundled Chrome, CI runners, and agent runtimes that need a browser they don't own. You're not embedding Puppeteer inside a browser tab — you're running Puppeteer as a client and pointing it at a browser that lives elsewhere.

That distinction matters because a lot of confusion comes from conflating three separate problems:

No local Chrome. You don't want to run puppeteer browsers install chrome on every worker.
No persistent state. You need cookies, logins, and localStorage to survive across runs.
No isolation. You need each job to get its own browser context so sessions don't bleed into each other.

A hosted Chromium runtime addresses all three. Puppeteer stays your client library; the browser becomes infrastructure.

connect() vs launch(): the trade-off

If you've only ever used puppeteer.launch(), the mental model shift is small but the operational consequences are large.

Concern	`puppeteer.launch()` (local)	`puppeteer.connect()` (remote)
Chrome binary	Installed per machine/container	Managed by the runtime
Startup cost	Process spawn + cold start per run	Attach to a warm session
Session persistence	Manual userDataDir management	Profile handled by the runtime
Scaling	Bound by host CPU/RAM	Bound by your session quota
Debugging	Local DevTools	Live viewer + CDP
Version drift	You pin and patch Chrome	Runtime pins the build
Network egress	Your IP	Configurable proxy settings

The trade-off is control versus operational burden. Local launch() gives you total control over flags, extensions, and the exact Chrome build — and you pay for it with install scripts, container images, and a Chrome version you have to keep patched. Remote connect() gives up some of that control in exchange for not managing any of it.

For a single developer running one script, local launch is fine. For anything that runs on a schedule, across multiple workers, or inside an agent loop, the install-and-patch cycle becomes the dominant cost.

Connecting Puppeteer to hosted Chromium

The connection flow is the same whether you're pointing at a local Chrome started with --remote-debugging-port or a hosted session. You need a WebSocket debugger URL, and you pass it to connect().

import puppeteer, { Browser, Page } from 'puppeteer-core';

// The runtime returns a CDP WebSocket endpoint for the session.
// Treat this like a credential — it grants full control of the browser.
const browserWSEndpoint = process.env.REMOTE_BROWSER_WS_ENDPOINT!;

async function runTask(): Promise<void> {
  let browser: Browser | undefined;

  try {
    browser = await puppeteer.connect({
      browserWSEndpoint,
      // Reuse the session's existing tab instead of opening a new one.
      defaultViewport: null,
    });

    const pages = await browser.pages();
    const page: Page = pages[0] ?? (await browser.newPage());

    await page.goto('https://example.com', {
      waitUntil: 'domcontentloaded',
      timeout: 30_000,
    });

    const title = await page.title();
    console.log('title:', title);

    // Create an isolated context for a second job on the same browser.
    const context = await browser.createBrowserContext();
    const isolated = await context.newPage();
    await isolated.goto('https://example.com/account');
    await context.close();
  } finally {
    // Disconnect, do not close — the runtime owns the browser lifecycle.
    await browser?.disconnect();
  }
}

runTask().catch((err) => {
  console.error(err);
  process.exit(1);
});

Three details in that snippet are worth calling out.

Use puppeteer-core, not puppeteer. The full puppeteer package downloads a Chrome build on install. Since you're connecting to a remote browser, you don't need it. puppeteer-core is the client-only package and skips the download entirely — which is exactly the puppeteer browsers install chrome step you're trying to avoid.

Call disconnect(), not close(). browser.close() terminates the Chrome process. On a hosted runtime, that's the runtime's job. Disconnecting releases your client connection and lets the session be reclaimed according to the runtime's policy.

Use createBrowserContext() for isolation. Multiple pages in the same context share cookies and storage. If you're running concurrent jobs, give each one its own context so a login in one task can't leak into another.

What breaks when you go remote

Moving from local to remote Chrome surfaces a handful of failure modes that don't exist locally. Knowing them ahead of time saves a lot of debugging.

Version mismatch between Puppeteer and Chrome. Puppeteer's protocol bindings are generated against a specific Chrome version. A hosted runtime pins its own Chromium build. If the two drift far enough apart, some CDP domains behave unexpectedly. Pin your puppeteer-core version and check the runtime's Chromium version rather than assuming latest works.

--no-sandbox and launch flags. Flags like --no-sandbox, --disable-dev-shm-usage, and --window-size are passed at launch. When you connect(), you can't pass them — the browser is already running. If you need specific launch arguments, they have to be configured on the runtime side, not in your Puppeteer code. This is the single most common source of "it worked locally" bugs.

Timeouts on goto. Remote navigation includes network latency between your client and the browser, plus the browser's own page load. Set explicit timeouts rather than relying on defaults, and prefer domcontentloaded over networkidle0 for pages with long-polling or analytics beacons that never fully settle.

File downloads. page.waitForEvent('download') works, but the file lands on the remote filesystem. You need a way to retrieve it — either a runtime-provided download API or a shared object store. Don't assume the path is local.

Stale sessions. If your process crashes without disconnecting, the session may linger until the runtime's idle timeout reclaims it. Wrap your work in try/finally and always disconnect.

When to use Puppeteer vs Playwright vs raw CDP

Puppeteer isn't the only client for a hosted Chromium session, and it isn't always the right one.

Client	Best for	Notes
Puppeteer	Chrome-only automation, existing Puppeteer codebases	Mature, Chrome-focused, `puppeteer-core` avoids downloads
Playwright	Cross-browser, richer auto-waiting, test runners	`connectOverCDP` for Chromium; broader API surface
Raw CDP	Fine-grained control, custom protocols, non-Node languages	No abstraction — you manage sessions and targets yourself

If your codebase is already Puppeteer, there's no reason to rewrite it just to go remote. If you're starting fresh and need Firefox or WebKit, Playwright is the better fit — see Playwright connectOverCDP for the equivalent attach flow. And if you're building an agent that needs to inspect network traffic or manipulate the protocol directly, raw CDP over a WebSocket is the lowest-level option.

For agent workloads specifically, the client library is usually the least interesting decision. What matters is whether the runtime gives you persistent profiles, session isolation, and a way to observe what the agent is doing. That's covered in more depth in Remote Browser for AI agents.

Production criteria for a hosted Puppeteer runtime

If you're evaluating runtimes to point Puppeteer at, these are the questions that actually determine whether it works in production.

Does it expose a CDP WebSocket endpoint? This is non-negotiable for Puppeteer. Some services only offer a REST API or a proprietary SDK. If there's no browserWSEndpoint, puppeteer.connect() isn't an option.

How are sessions isolated? Separate browser processes are stronger than separate contexts, which are stronger than separate tabs. Ask which one you get, because it determines whether a crash in one job can take down another.

What happens to state between sessions? Persistent profiles let you keep logins and cookies across runs. Ephemeral sessions start clean every time. Both are valid — but you need to know which you're getting, because it changes how you handle authentication.

Can you observe a running session? A live viewer that streams the browser's screen is the difference between debugging in minutes and debugging in hours. Without it, a failed selector is just a stack trace.

What's the network egress story? Proxies, IP reputation, and geographic location all affect whether a site serves you a real page or a challenge. The runtime should let you configure this rather than forcing a single shared egress.

How is usage metered? Browser time, network traffic, and session count are the usual axes. Check pricing for the current model rather than assuming a flat rate.

Remote Browser exposes CDP endpoints for hosted Chromium sessions, so Puppeteer, Playwright, and Selenium clients all attach the same way. Sessions support persistent profiles, configurable browser settings, and a live viewer for debugging. The documentation covers the connection flow end to end.

A practical migration path

If you have a working local Puppeteer script and want to move it to a hosted runtime, the sequence is short.

Swap puppeteer for puppeteer-core. Remove the bundled Chrome download. Your code doesn't change.
Replace launch() with connect(). Pass the runtime's WebSocket endpoint. Move any launch flags you were using into runtime configuration.
Add explicit timeouts. Remote navigation has more latency than local. Set timeout on goto, waitForSelector, and waitForFunction.
Wrap in try/finally with disconnect(). Never leave a session dangling on a crash path.
Add context isolation for concurrent jobs. One createBrowserContext() per job if you're running in parallel.
Verify downloads and file paths. Anything that touched the local filesystem needs a remote-aware replacement.

Most scripts migrate in an afternoon. The parts that take longer are the ones that depended on local Chrome flags or local filesystem access — those need a runtime-side equivalent, not a code change.

Where this fits

Puppeteer in browser contexts is really a question about where Chrome lives. Once you accept that the browser can be remote and Puppeteer is just a CDP client, the architecture simplifies: your code stays portable, your workers stay thin, and the browser becomes a managed resource with its own lifecycle, profiles, and observability.

That's the same shift that makes agent workloads tractable. An AI agent driving a browser needs the same things a test suite does — isolation, persistence, and a way to see what happened — plus a runtime that can hold a session open across many steps. If you want to see what that looks like without managing Chrome yourself, start with Remote Browser online or connect a session directly from the documentation.

Playwright Chrome Extension: What It Is and What to Use Instead

RemoteBrowser — Wed, 16 Sep 2026 03:50:47 +0000

Playwright Chrome Extension: What It Is and What to Use Instead

If you searched for a "Playwright Chrome Extension," you're probably trying to do one of two things: drive your existing Chrome browser with Playwright, or find a browser extension that adds Playwright-style control to Chrome. There is no official Playwright Chrome Extension on the Chrome Web Store. Playwright is a Node/Python/.NET/Java library that launches or connects to browsers over the Chrome DevTools Protocol (CDP) — it does not ship as a browser add-on. What you actually want is one of three things: connectOverCDP to an existing Chrome instance, a remote browser runtime you connect to over CDP, or a third-party extension that wraps CDP for you. This guide covers all three, with the trade-offs that matter in production.

Why there's no official Playwright Chrome Extension

Playwright's architecture is deliberately outside the browser. It speaks CDP (for Chromium) and its own protocol (for Firefox and WebKit) from a driver process. That design gives it capabilities a browser extension can't match: multi-context isolation, network interception at the protocol layer, tracing, and deterministic waits. A Chrome extension runs inside a single browser profile, is subject to extension permission limits, and cannot spawn isolated contexts.

So when people say "Playwright Chrome Extension," they usually mean one of:

Connect Playwright to my running Chrome — via chromium.connectOverCDP() against a Chrome launched with --remote-debugging-port.
A remote browser I can drive with Playwright — a hosted Chromium session exposing a CDP endpoint.
A Chrome extension that automates the browser — e.g. recorder-style tools, which are a different category entirely.

If you want the conceptual background on why agents and test harnesses need a dedicated runtime rather than a local browser, see Remote Browser for AI Agents.

Option 1: Connect Playwright to your existing Chrome via CDP

This is the closest thing to a "Playwright Chrome Extension" workflow. You launch Chrome with a debugging port, then attach Playwright to it. Your existing cookies, extensions, and logged-in sessions stay intact.

Launch Chrome with a debugging port

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-playwright-profile

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-playwright-profile

The --user-data-dir flag matters. Without it, Chrome may refuse to open the debugging port if another Chrome instance is already running with the default profile.

Attach with connectOverCDP

import { chromium, Browser, BrowserContext, Page } from 'playwright';

async function attachToChrome(): Promise<void> {
  // connectOverCDP attaches to an already-running Chromium/Chrome.
  // It does NOT launch a new browser.
  const browser: Browser = await chromium.connectOverCDP(
    'http://127.0.0.1:9222'
  );

  // Existing contexts are exposed; there is no default context to create.
  const contexts: BrowserContext[] = browser.contexts();
  const context: BrowserContext = contexts[0] ?? (await browser.newContext());

  const pages: Page[] = context.pages();
  const page: Page = pages[0] ?? (await context.newPage());

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

  // Do NOT call browser.close() — that would kill the user's Chrome.
  // Instead, disconnect the Playwright client:
  await browser.close();
}

attachToChrome().catch((err) => {
  console.error('CDP attach failed:', err);
  process.exit(1);
});

Two things trip people up here. First, connectOverCDP is Chromium-only — it does not work with Firefox or WebKit. Second, browser.close() on a CDP-attached browser closes the underlying browser, not just the connection. If you're attaching to a user's Chrome, you want to disconnect without killing it. The Playwright docs on BrowserType.connectOverCDP cover the exact semantics.

When this approach breaks down

CI and containers — there's no "existing Chrome" to attach to unless you launch one first, at which point you've just reimplemented launch().
Concurrency — one Chrome instance with one profile is not a multi-tenant runtime. Parallel jobs need isolated contexts or separate browsers.
State drift — a long-lived local Chrome accumulates cookies, extensions, and memory. Tests become non-reproducible.
Remote access — exposing port 9222 to the network is a security problem. CDP has no authentication by default.

Option 2: A remote browser runtime you connect to over CDP

This is where most production teams land. Instead of managing Chrome on every worker, you connect Playwright to a hosted Chromium session that already exposes a CDP endpoint. The connection code is nearly identical to Option 1 — only the URL changes.

import { chromium } from 'playwright';

const wsEndpoint = process.env.REMOTE_BROWSER_CDP_URL!; // e.g. wss://.../cdp

const browser = await chromium.connectOverCDP(wsEndpoint);
const context = await browser.newContext({
  // Configurable browser settings are applied server-side:
  // viewport, locale, timezone, proxy, and session isolation.
  viewport: { width: 1280, height: 800 },
});
const page = await context.newPage();
await page.goto('https://example.com');
await page.screenshot({ path: 'shot.png' });
await browser.close(); // closes the remote session, not a local browser

The practical differences from local Chrome:

Concern	Local Chrome + CDP	Hosted Chromium runtime
Setup	Install Chrome, manage flags, profiles	Paste a CDP URL
Isolation	One profile per instance	Session-isolated contexts
Concurrency	Manual process management	Sessions provisioned per job
Proxies	Per-launch flags	Configurable per session
Live debugging	Local DevTools only	Live viewer + CDP
Persistence	Local profile dir	Persistent profiles across sessions
Cost model	Your infra + ops time	Metered per browser-hour (see pricing)

If you're weighing self-hosting against a managed runtime, the trade-offs are covered in Remote Browser Online. The short version: self-hosting is cheaper at low volume and much more expensive once you factor in ops, proxy management, and session cleanup.

Option 3: Third-party Chrome extensions that wrap CDP

There are Chrome extensions that expose a CDP-like control surface, and there are extensions that record and replay browser actions. These are not Playwright. They typically:

Run inside a single profile with extension permissions.
Cannot create isolated browser contexts.
Cannot intercept network at the protocol layer the way Playwright can.
Break when Chrome updates its extension APIs.

If your goal is a quick recorder for a manual workflow, an extension is fine. If your goal is reproducible automation, tests, or agent workloads, you want Playwright (or Puppeteer) talking to a real browser over CDP. The same logic applies to Puppeteer — see how Puppeteer connects to existing browsers for the parallel workflow.

Playwright launch options that matter in production

Whether you launch locally or connect remotely, the launchOptions you pass shape reliability. The ones that matter most:

args — Chromium flags like --disable-dev-shm-usage (containers), --no-sandbox (only when you understand the security trade-off), --disable-gpu (headless servers).
headless — headless is faster and more stable in CI; headed is useful for debugging via a live viewer.
proxy — route traffic through a specific proxy. In a hosted runtime this is usually configured per session rather than per launch.
channel — chrome, msedge, or bundled Chromium. Bundled Chromium is the most reproducible.
timeout — how long to wait for the browser to start. Remote sessions may need a higher value.

A common production pattern is to keep launch options minimal and push environment-specific settings (proxy, viewport, locale) into the session configuration on the runtime side. That keeps your test code portable between local and hosted execution.

Choosing between the three approaches

Use this as a decision rule:

Attaching to your own Chrome — good for debugging a logged-in session, scraping behind an auth wall you already cleared, or one-off scripts. Bad for CI, concurrency, and anything you need to reproduce.
Hosted Chromium over CDP — good for CI, agent workloads, parallel jobs, and anything that needs isolation, proxies, or persistent profiles. This is the default for production.
Chrome extensions — good for manual recording and personal productivity. Not a substitute for a driver library.

The mistake to avoid is treating a local Chrome attach as a production runtime. It works until you need a second concurrent job, a clean profile, or a machine that isn't your laptop.

What to look for in a hosted runtime

If you go the hosted route, evaluate on these criteria rather than marketing claims:

CDP compatibility — does connectOverCDP work unmodified, or do you need a custom SDK?
Session isolation — are contexts truly isolated per job, or shared?
Persistent profiles — can you keep cookies and storage across sessions when you need to?
Proxy and network controls — per-session proxy configuration, not global.
Live debugging — a viewer or CDP access so you can see what the agent saw.
Usage controls — clear metering so you can predict cost. Check /pricing for current rates.
Playwright/Puppeteer/Selenium support — you shouldn't have to rewrite your driver code.

Remote Browser exposes hosted Chromium sessions with CDP access, Playwright/Puppeteer/Selenium compatibility, a live viewer, persistent profiles, configurable browser settings, and session isolation. The connection pattern is the connectOverCDP example above — no proprietary driver required. Full API details are in the /documentation.

A note on "Playwright MCP Chrome Extension"

A related search is "Playwright MCP Chrome extension." MCP (Model Context Protocol) servers for browser control are a separate layer — they expose browser actions as tools to an LLM, and they typically sit on top of Playwright or CDP. They are not Chrome extensions either. If you're building an agent that needs browser tools, the runtime underneath the MCP server is what determines reliability: isolation, proxies, and session lifecycle. A local Chrome attach will not scale to concurrent agent tasks; a hosted runtime will. See Remote Web Browser for how that runtime layer fits into an agent stack.

Summary

There is no official Playwright Chrome Extension. The real options are:

chromium.connectOverCDP() to attach to a local Chrome you launched with --remote-debugging-port.
chromium.connectOverCDP() to a hosted Chromium session for production, CI, and agent workloads.
A third-party extension if you only need manual recording.

For anything beyond a one-off script, the hosted runtime path gives you isolation, proxies, persistent profiles, and live debugging without managing Chrome on every worker. Start with the /documentation to see the CDP connection flow, and check /pricing for current usage rates.

Playwright MCP Chrome Extension: What It Is and What to Use

RemoteBrowser — Wed, 16 Sep 2026 03:50:46 +0000

Playwright MCP Chrome Extension: What It Is and What to Use

If you searched for a "Playwright MCP Chrome extension," you are probably trying to give an AI agent control of a real browser. The naming is confusing, because there is no official Playwright-branded Chrome extension that does this. What exists is the Playwright MCP server — a Model Context Protocol server that exposes Playwright browser actions as tools an LLM can call — plus a set of ways to attach that server to Chrome, including a real Chrome extension that bridges your own logged-in browser session.

This post separates the three things people conflate: the MCP server, the Chrome extension bridge, and the underlying browser connection (CDP or a launched Chromium). Then it covers where each breaks down in production and how to move to a hosted runtime when you need sessions that survive past your laptop.

The short answer

Playwright MCP is a server that lets an LLM drive a browser through Playwright. It is not a Chrome extension.
The Chrome extension in this stack is a bridge. It lets the MCP server talk to a Chrome instance you already have open, using your existing profile and logins.
The connection underneath is either a launched Chromium process or a CDP endpoint. That distinction determines whether your automation is reproducible or tied to one machine.

If you only need an agent to click around a site you are already logged into, the extension bridge is convenient. If you need agents that run on a schedule, in CI, or across many concurrent tasks, the extension is the wrong layer — you want a remote browser with a CDP endpoint.

What the Playwright MCP server actually does

MCP (Model Context Protocol) is a standard for exposing tools to LLM clients. A Playwright MCP server wraps Playwright's API — navigate, click, type, snapshot the accessibility tree, take screenshots — and publishes them as callable tools. The LLM client (Claude Desktop, an IDE agent, a custom harness) decides which tool to call; the server executes it against a browser.

Two design choices matter:

Accessibility-tree snapshots vs. screenshots. Most Playwright MCP implementations return a structured accessibility snapshot rather than pixels. That is cheaper for the model and more deterministic than vision-based clicking, but it means the agent sees the DOM's semantic structure, not the rendered page. Canvas apps, heavily styled widgets, and anything behind a shadow DOM boundary can be invisible to it.

Session lifetime. The server holds a browser context for the duration of the conversation. When the client disconnects, that context typically dies. There is no built-in persistence unless you configure a user data directory or connect to an external browser.

That last point is where the Chrome extension enters.

The Chrome extension bridge: what it solves

A plain Playwright MCP server launches its own Chromium. That browser has no cookies, no logins, no extensions, and a fresh fingerprint. For a lot of real tasks — checking an internal dashboard, operating a SaaS tool you pay for, testing a page behind auth — that is a blocker.

The extension bridge solves it by inverting the connection. Instead of the server launching a browser, the server connects to a browser you already have open. The extension runs inside that browser and relays CDP-level commands between the MCP server and the live tab.

What you get:

Your existing cookies, sessions, and logged-in state
Your real profile, including installed extensions
The ability to watch the agent work in a tab you can see
No separate browser download or install step

What you give up:

Reproducibility. The browser state is whatever you happened to have open.
Isolation. The agent shares a profile with your personal browsing.
Concurrency. One extension, one browser, effectively one agent at a time.
Headless operation. The browser has to be running, which usually means a desktop session.

For interactive, human-in-the-loop work, that trade is fine. For anything that runs unattended, it is not.

How the pieces connect: CDP is the common denominator

Whether you launch Chromium, attach to a running Chrome, or connect to a cloud browser, the wire protocol is the same: the Chrome DevTools Protocol. Playwright's connectOverCDP is the entry point.

import { chromium, Browser, BrowserContext, Page } from 'playwright';

type RemoteTarget = {
  cdpUrl: string;      // e.g. wss://<host>/cdp or http://127.0.0.1:9222
  sessionId?: string;  // provider-specific session handle
};

async function attach(target: RemoteTarget): Promise<{
  browser: Browser;
  context: BrowserContext;
  page: Page;
}> {
  const browser = await chromium.connectOverCDP(target.cdpUrl, {
    timeout: 30_000,
  });

  // A remote browser usually exposes one persistent context.
  // Reuse it so cookies and storage survive across calls.
  const context = browser.contexts()[0] ?? (await browser.newContext());

  const page = context.pages()[0] ?? (await context.newPage());

  // Fail fast if the endpoint is stale rather than hanging on the first action.
  await page.goto('about:blank', { waitUntil: 'domcontentloaded' });

  return { browser, context, page };
}

// Usage against a hosted endpoint:
// const { browser, page } = await attach({ cdpUrl: process.env.CDP_URL! });
// await page.goto('https://example.com');
// await browser.close(); // closes the client connection, not the remote session

Three details in that snippet are worth calling out, because they are where most connectOverCDP implementations go wrong:

connectOverCDP is Chromium-only. It does not work against Firefox or WebKit. If your test matrix includes those engines, you need a different connection strategy — Playwright's own browser server, not CDP.
browser.close() semantics differ. On a CDP connection, closing the browser object disconnects the client. Whether the remote session terminates depends on the provider. Read the docs for your endpoint before assuming cleanup happened.
Context reuse is not automatic. browser.contexts()[0] is a convention, not a guarantee. Some providers return an empty array until you create a context. Handle both branches.

If you are comparing this to a locally launched browser, the relevant Playwright launch flags are in the browser launch options guide — --remote-debugging-port, --user-data-dir, and --headless are the ones that matter for attach-style workflows.

Comparison: extension bridge vs. launched Chromium vs. hosted runtime

Dimension	Chrome extension bridge	Local launched Chromium	Hosted remote browser
Auth state	Your live profile	Fresh, or a seeded profile dir	Persistent profile per session
Isolation	None — shares your profile	Process-level	Session-level, per agent
Concurrency	~1 agent	Limited by local RAM/CPU	Scales with the provider
Headless / CI	No (needs a desktop browser)	Yes	Yes
Reproducibility	Low	Medium	High (pinned image, fixed config)
Debugging	Watch the tab live	Trace files, video	Live viewer + traces
Setup cost	Install extension, run server	`npx playwright install`	Paste a CDP URL
Best for	Interactive, logged-in tasks	Local dev, unit tests	Agents, CI, scheduled jobs

The extension column is not "worse" — it is optimized for a different job. The mistake is using it for the job in the last row.

Where the extension approach breaks in production

Four failure modes show up repeatedly once you move past a demo:

Session death on disconnect. The MCP client closes, the browser context goes with it. Any multi-step task that spans a client restart loses its place. Persistent profiles fix this, but a local Chrome profile is not designed for programmatic lifecycle management.

No concurrency. One extension, one browser. Ten parallel agent tasks need ten browsers, which means ten desktop sessions. That does not fit on a CI runner.

State drift. Because the browser is your real one, its state changes underneath the agent — you close a tab, log out of a site, install an extension. The agent's assumptions go stale silently.

No resource controls. A runaway agent loop on a local browser consumes your machine. There is no per-session CPU, memory, or time budget to enforce.

None of these are fatal for interactive use. All of them are fatal for unattended workloads.

The production path: hosted Chromium with a CDP endpoint

The pattern that scales is the same one the extension uses — connect to an existing browser over CDP — except the browser is not on your desk. It is a hosted Chromium session with:

A CDP endpoint you connect to with connectOverCDP
A persistent profile so logins survive across sessions
Session isolation so concurrent agents do not share cookies
A live viewer for debugging without screen-sharing your desktop
Configurable browser settings, including proxy routing, applied at session creation
Usage controls so a stuck agent cannot burn budget indefinitely

The migration from an extension-based setup is mostly deleting code. You stop managing a local Chrome process and a bridge; you pass a CDP URL to the same Playwright client you already wrote.

// Before: local Chrome + extension bridge
// const browser = await chromium.connectOverCDP('http://127.0.0.1:9222');

// After: hosted session, same client API
const browser = await chromium.connectOverCDP(process.env.CDP_URL!);
const context = browser.contexts()[0];
const page = context.pages()[0] ?? (await context.newPage());

await page.goto('https://app.example.com/dashboard');
await page.getByRole('button', { name: 'Export' }).click();

Everything downstream — locators, assertions, retries — is unchanged. That is the point of CDP as an interface: the browser's location is an implementation detail.

For a fuller treatment of the runtime model, see Remote Browser for AI agents and the remote web browser overview. If you are specifically wiring an agent harness rather than a test suite, remote control browser covers the control-plane side.

Choosing between them

Use the extension bridge when:

The task requires a login you cannot or should not script
A human is watching and may need to intervene
You are prototyping and want to see the agent's actions in a real tab
The workload is one-off and interactive

Use a hosted remote browser when:

The workload runs unattended, on a schedule, or in CI
You need more than one agent running at once
Sessions must survive client restarts
You need per-session resource limits and audit trails
You want the same code path in dev and production

A reasonable migration is to prototype with the extension, then move to a CDP endpoint once the task definition stabilizes. The Playwright code barely changes; what changes is who owns the browser lifecycle.

Practical setup notes

A few things that save time regardless of which path you pick:

Pin your Playwright version. CDP compatibility drifts between Playwright releases and Chrome versions. A version bump in CI that silently changes attach behavior is a bad afternoon.
Set an explicit connect timeout. The default can hang for a long time on a dead endpoint. Thirty seconds is generous.
Health-check before the first real action. A goto('about:blank') costs nothing and fails fast on a stale session.
Log the session ID. When something goes wrong at 3 a.m., the session handle is the first thing you will want.
Do not assume browser.close() kills the remote session. Verify against your provider's docs, and use an explicit session-terminate call if one exists.

Current session limits, concurrency, and pricing for hosted sessions are on the pricing page. The documentation covers CDP connection details, profile persistence, and the live viewer.

Bottom line

There is no Playwright MCP Chrome extension in the sense most people mean. There is an MCP server, and there is an extension that bridges it to your own browser. That combination is genuinely useful for interactive, logged-in work — and genuinely wrong for anything that needs to run unattended, concurrently, or reproducibly.

The underlying connection is CDP either way. Once you internalize that, the decision stops being about extensions and starts being about where the browser lives. For production agent workloads, that answer is usually a hosted session with a persistent profile and a CDP URL you can paste into the Playwright client you already have.

DEV Community: RemoteBrowser

Puppeteer BrowserWSEndpoint Tutorial: Connect to Remote Chromium

Puppeteer BrowserWSEndpoint Tutorial: Connect to Remote Chromium

What browserWSEndpoint Actually Is

Getting a browserWSEndpoint from a Hosted Runtime

Minimal TypeScript Example

Connecting to an Existing Local Chrome

Local Chrome vs Hosted Remote Browser

Production Criteria Before You Commit

Common Failure Modes

Where This Fits in an Agent Stack

Practical Checklist

Puppeteer Install Browser: Local vs Remote CDP Setup

Puppeteer Install Browser: Local vs Remote CDP Setup

What puppeteer install browser actually does

Environment variables that control the install

Local install vs remote connect

Connecting Puppeteer to a remote browser

Production criteria for the remote path

Common failure modes

When to keep the local install

A practical migration path

Puppeteer Browsers Npm: Install, Connect, and Run Remotely

Puppeteer Browsers Npm: Install, Connect, and Run Remotely

What puppeteer browsers Actually Manages

Version pinning and the puppeteer vs puppeteer-core split

Where the Local Install Model Breaks Down

The Alternative: Connect Instead of Install

Local Install vs Hosted Runtime: A Comparison

Production Criteria Before You Switch

Wiring It Into an Existing Puppeteer Codebase

Common Failure Modes and How to Read Them

When to Keep the Local Install

Getting Started

Puppeteer BrowserWSEndpoint Example: Connect to Remote Chromium

Puppeteer BrowserWSEndpoint Example: Connect to Remote Chromium

What browserWSEndpoint actually is

A minimal Puppeteer browserWSEndpoint example

Connecting with Playwright over CDP instead

Puppeteer vs Playwright over a WebSocket endpoint

Production criteria for a remote endpoint

Common failure modes

When a WebSocket endpoint is the wrong tool

Getting an endpoint and running the example

Summary

Puppeteer Remote Browser Chrome: Connect and Run in the Cloud

Puppeteer Remote Browser Chrome

What "remote browser Chrome" actually means in Puppeteer

Getting a browserWSEndpoint

Connecting Puppeteer to a remote browser

Puppeteer browser versions and the install problem

Puppeteer browser args when the browser is remote

Production criteria for a remote Puppeteer setup

When local Puppeteer is still the right call

Where this fits for AI agents

Puppeteer Remote Browser Download: What You Install vs Connect

Puppeteer Remote Browser Download: What You Install vs Connect

The two meanings of "Puppeteer remote browser download"

What puppeteer browsers install chrome actually does

Why the download step causes problems in production

Connecting instead of downloading: browserWSEndpoint

Puppeteer vs Playwright for remote connections

A TypeScript example: Playwright over CDP to a hosted session

Browser args and version pinning on remote sessions

When to download, when to connect

Production criteria for a remote browser runtime

Migrating an existing Puppeteer script

Where Remote Browser fits

Summary

Playwright Chrome Recorder: Record, Export, and Run Remotely

Playwright Chrome Recorder: Record, Export, and Run Remotely

What the Playwright Chrome Recorder Actually Does

Reading the Generated Script Critically

From Recording to Execution: Where the Script Runs

Connecting a Recorded Script to Remote Chromium

Production Criteria for Recorded Flows

Recorder vs. Hand-Written vs. Agent-Driven

Practical Setup Notes

Where This Leaves You

Playwright connectOverCDP GitHub: Connect to Remote Chrome

What `puppeteer install browser` actually does

What `puppeteer browsers` Actually Manages

Version pinning and the `puppeteer` vs `puppeteer-core` split

What `browserWSEndpoint` actually is

What `puppeteer browsers install chrome` actually does

Connecting instead of downloading: `browserWSEndpoint`

The `--remote-debugging-port` trap