Playwright connectOverCDP Example: Connect to Remote Chrome

# Playwright connectOverCDP Example: Drive Remote Chrome Instances

If you've ever needed to attach Playwright to an already-running Chrome browser, connectOverCDP is the API you're looking for. This Playwright connectOverCDP example shows you how to connect to a remote Chromium instance, why you'd want to do it, and where the approach breaks down in production.

The core idea is simple: instead of launching a fresh browser, Playwright connects to an existing one over the Chrome DevTools Protocol (CDP). That means you can inspect a live session, take over a browser that's already logged in, or run automation against a browser hosted on another machine.

What Is connectOverCDP and When Should You Use It?

browserType.connectOverCDP() is a Playwright method that attaches to a running Chromium-based browser via CDP. It returns a Browser object that behaves like one you'd get from launch(), but the underlying process is external.

Here's the canonical Playwright connectOverCDP example from the official docs:

import { chromium } from 'playwright';

// Connect to an existing Chrome instance running with --remote-debugging-port=9222
const browser = await chromium.connectOverCDP('http://localhost:9222');
const defaultContext = browser.contexts()[0];
const page = defaultContext.pages()[0];

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

// Don't close the browser — you only own the connection
await browser.close();

The official Playwright documentation for connectOverCDP notes that this method is Chromium-only. Firefox and WebKit don't support it.

When connectOverCDP Makes Sense

• Debugging a live browser: You're watching a browser session and want to execute commands against it.
• Reusing an authenticated session: A browser is already logged into a service; you attach and perform actions without re-authenticating.
• Connecting to a browser on another host: The browser runs on a remote machine or container, and you connect over the network.

When It Gets Complicated

• Scaling: Each browser instance needs a debugging port, and managing dozens of them across machines becomes infrastructure work.
• Session persistence: If the browser crashes or the machine restarts, your session is gone.
• Security: Exposing a debugging port publicly is a security risk. You need authentication, network isolation, or a proxy.

How Remote Browser Solves the connectOverCDP Problem

Remote Browser is a hosted browser runtime that gives you the same CDP access without the infrastructure burden. Instead of running Chrome yourself and exposing a debugging port, you get a CDP endpoint to a managed Chromium session.

The connection pattern is nearly identical. Here's how you'd connect to a Remote Browser session:

import { chromium } from 'playwright';

// Connect to a Remote Browser session via its CDP endpoint
const browser = await chromium.connectOverCDP('wss://remote-browser.dev/cdp/session_abc123');

// Access the default context and page
const context = browser.contexts()[0];
const page = context.pages()[0];

// Navigate and interact
await page.goto('https://example.com');
await page.fill('#search', 'playwright connectovercdp example');
await page.click('button[type="submit"]');

// Take a screenshot or extract data
await page.screenshot({ path: 'result.png' });

// Close the connection — the remote session stays alive if configured
await browser.close();

The key difference: you're not managing the browser process, the debugging port, or the network security. Remote Browser handles that.

Playwright connectOverCDP Example: Local vs. Remote Comparison

Common Use Cases for connectOverCDP

1. Keeping Browser Sessions Alive Across Cloud Workers

A common problem in browser automation is session persistence. You run a task on one worker, and when it finishes, the browser closes. The next worker starts fresh — no cookies, no localStorage, no logged-in state.

With connectOverCDP, you can keep a browser running and have multiple workers connect to it. But this only works if the browser itself is hosted somewhere stable. If you're running on serverless infrastructure, you can't rely on a local browser surviving between invocations.

Remote Browser solves this by hosting the browser session independently. Your workers connect via CDP, do their work, and disconnect. The session stays alive, retaining cookies, profiles, and state. This is covered in more depth in our guide on remote browser data and session persistence.

2. Giving AI Agents Browser Access in Production

AI agents often need to browse the web to complete tasks — checking a website, filling a form, or extracting data. The challenge is giving them a reliable browser environment that doesn't break.

A Playwright connectOverCDP example is the foundation: the agent connects to a browser, navigates, and acts. But in production, you need more:

• Session isolation: Each agent task should run in a clean or dedicated session.
• Observability: You need to see what the agent is doing, ideally in real time.
• Resource management: Browsers consume memory and CPU; you need limits and cleanup.

Remote Browser provides these as part of the runtime. Agents connect via CDP, and you get a live viewer, session controls, and usage tracking. For a deeper look, see our article on remote browsers for AI agents.

3. Scaling Playwright Browser Workloads Reliably

When you scale Playwright tests or automation, you hit a wall: each browser instance needs CPU, memory, and a debugging port. Running 50 browsers on one machine is impractical. Running them across machines requires orchestration.

connectOverCDP helps you connect to browsers running elsewhere, but you still need to provision and manage those browsers. That's the hard part.

A hosted browser runtime removes the provisioning problem. You request a session, get a CDP endpoint, and run your Playwright code. The infrastructure — browser version, resource allocation, network — is handled for you. This is the difference between running a few local browsers and running production workloads.

Production Considerations for connectOverCDP

If you're building on connectOverCDP, here's what matters beyond the basic example:

Authentication and Security

Exposing a CDP endpoint without authentication is dangerous. Anyone who can reach the port can control the browser. In production:

• Use WebSocket endpoints with authentication tokens.
• Never expose debugging ports to the public internet.
• Use network isolation or VPNs for self-hosted setups.

Remote Browser handles this by providing authenticated WebSocket endpoints. You don't need to manage firewall rules or tokens.

Session Lifecycle Management

When you connect to a browser via CDP, you need to decide what happens when your script ends. Closing the browser kills the session. Not closing it leaks resources.

In a hosted environment, you want explicit control:

• Disconnect without closing: Your script ends, but the browser stays alive for the next connection.
• Close and clean up: The session terminates, freeing resources.
• Idle timeout: The browser shuts down after a period of inactivity.

Remote Browser gives you these options through its API and dashboard.

Browser Version Consistency

Local Chrome updates can break your automation. If you're running tests against Chrome 120 locally but your production browser is Chrome 126, you might see flaky behavior.

Hosted browsers let you pin versions or use a consistent managed version. This reduces the "works on my machine" problem.

Beyond Playwright: Selenium and Puppeteer

While this article focuses on a Playwright connectOverCDP example, the same CDP endpoint works with other tools:

• Puppeteer: puppeteer.connect({ browserWSEndpoint })
• Selenium: Selenium 4 supports CDP via driver.getCdpConnection() or through the WebDriver BiDi protocol.

If you're standardizing on CDP, you're not locked into one library. Remote Browser sessions are accessible via any CDP-compatible client.

When Not to Use connectOverCDP

connectOverCDP isn't always the right choice. Consider alternatives:

• Short-lived, stateless tasks: If you don't need to reuse a session, launch() is simpler and faster.
• Firefox or WebKit: connectOverCDP is Chromium-only. For cross-browser testing, use Playwright's normal launch or connect methods.
• High-frequency, low-latency operations: Connecting over CDP adds overhead. If you're doing thousands of quick operations, a persistent browser with launch() might be better.

Getting Started with Remote Browser

If you're building automation that needs persistent, scalable browser sessions, try Remote Browser:

1. Create a session via the API or dashboard.
2. Get the CDP endpoint (a wss:// URL).
3. Connect using chromium.connectOverCDP() in Playwright, or any CDP client.
4. Run your automation and disconnect when done.

The session stays alive, ready for the next connection. You can also use the live viewer to watch what's happening in real time.

For implementation details, check the documentation. For pricing and limits, see the pricing page.

Summary

The Playwright connectOverCDP example is straightforward: connect to a running Chromium browser via CDP and control it with Playwright's API. It's useful for debugging, session reuse, and remote browser control.

But in production, you need more than a connection method. You need session persistence, security, scaling, and observability. That's where a hosted browser runtime like Remote Browser fits.

Instead of managing Chrome instances and debugging ports, you get a CDP endpoint to a managed browser. Your Playwright code stays the same — you just point it at a different URL.

If you're building AI agents, browser automation, or web scraping at scale, Remote Browser gives you the runtime layer that makes connectOverCDP production-ready.