Playwright Firefox connect_over_cdp Supported Docs: A Practical Guide

# Playwright Firefox connect_over_cdp Supported Docs: A Practical Guide

If you've searched for "Playwright Firefox connect_over_cdp supported docs," you've likely hit a wall. The Playwright documentation is clear that connectOverCDP is primarily designed for Chromium-based browsers. But what does that mean for Firefox? Can you use it at all? And if so, how?

This guide answers those questions directly. We'll cover what the official docs say, what actually works in practice, and how to connect to remote Firefox instances when you need to. We'll also show you how hosted browser runtimes like Remote Browser handle this limitation.

The Short Answer: What the Docs Say

The Playwright documentation for browserType.connectOverCDP states that the method is only supported for Chromium-based browsers. The official docs explicitly note that Firefox and WebKit do not support the connectOverCDP method.

This is a hard limitation, not a configuration issue. Firefox does not expose the Chrome DevTools Protocol (CDP) in the same way Chromium does. Instead, Firefox uses the Remote Debugging Protocol (RDP), which is a different wire protocol.

Why Firefox Doesn't Support connectOverCDP

The core issue is protocol mismatch. CDP is a Chrome-specific protocol. While it has become the de facto standard for browser automation, Firefox never adopted it. Instead, Firefox uses its own Remote Debugging Protocol.

Playwright's architecture reflects this. The connectOverCDP method speaks CDP natively. Since Firefox doesn't speak CDP, the method simply cannot work with Firefox.

What About WebDriver BiDi?

Playwright is gradually moving toward WebDriver BiDi as a cross-browser protocol. WebDriver BiDi is a W3C standard that aims to unify browser automation across vendors. Firefox has implemented WebDriver BiDi, and Playwright can connect to Firefox using this protocol.

However, connectOverCDP is not the method for this. If you need to connect to a remote Firefox instance, you have two options:

1. Use Playwright's Firefox launcher with browserType.launch() and connect via the Playwright server protocol (not CDP).
2. Use Selenium with the GeckoDriver, which speaks the WebDriver protocol.

What Actually Works: Connecting to Firefox

If you need to automate Firefox remotely, here's what works today.

Option 1: Playwright's Native Firefox Support

Playwright has first-class support for launching Firefox locally. You can use browserType.launch() with the Firefox channel, and Playwright handles the connection internally.

import { firefox } from 'playwright';

const browser = await firefox.launch({
  headless: true
});

const page = await browser.newPage();
await page.goto('https://example.com');
await browser.close();

This works because Playwright launches Firefox as a subprocess and communicates with it using its internal protocol. The limitation only appears when you try to connect to an *already-running* Firefox instance.

Option 2: Selenium with GeckoDriver

If you need to connect to an already-running Firefox instance, Selenium is the more practical choice. Selenium's WebDriver protocol works with Firefox through GeckoDriver.

from selenium import webdriver
from selenium.webdriver.firefox.options import Options

options = Options()
options.add_argument("-headless")
driver = webdriver.Firefox(options=options)
driver.get("https://example.com")
driver.quit()

Option 3: Use Chromium Instead

This is the pragmatic answer for most teams. If your workflow depends on connectOverCDP, switching to Chromium removes the limitation entirely. Chromium supports CDP natively, and Playwright's connectOverCDP works reliably with it.

The Production Reality: Remote Browser Sessions

The connectOverCDP limitation becomes more acute in production. When you run browser automation at scale—especially for AI agents—you rarely run browsers on the same machine as your code. You need remote browser sessions.

This is where the protocol question matters. If you're building an AI agent that needs to control a browser, you have two paths:

1. Use Chromium and CDP: This gives you connectOverCDP support, a mature protocol, and broad tooling compatibility.
2. Use Firefox and WebDriver BiDi: This is more standards-compliant but has fewer tools and less mature support.

For most production workloads, Chromium and CDP win. That's why hosted browser runtimes like Remote Browser focus on Chromium.

How Remote Browser Handles This

Remote Browser provides hosted Chromium sessions that you can connect to via CDP. This means you get the full power of connectOverCDP without managing browser infrastructure yourself.

import { chromium } from 'playwright';

// Connect to a Remote Browser session
const browser = await chromium.connectOverCDP(
  'wss://remote-browser.dev/cdp/your-session-id'
);

const pages = browser.contexts()[0].pages();
const page = pages[0] || await browser.contexts()[0].newPage();

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

await browser.close();

This approach gives you:

• Persistent sessions: Keep browser sessions alive across multiple cloud workers.
• Live debugging: Watch your AI agent work in real-time through a live viewer.
• Profile persistence: Maintain cookies, local storage, and login states across sessions.
• Proxy support: Route traffic through different IPs when needed.

When You Actually Need Firefox

There are legitimate reasons to use Firefox in production:

• Testing Firefox-specific behavior: If your product must work in Firefox, you need to test it.
• Compliance requirements: Some industries require testing in multiple browsers.
• User-agent diversity: For web scraping, you may want Firefox's user-agent string.

For these cases, we recommend a hybrid approach:

1. Use Playwright's Firefox launcher for local and CI testing.
2. Use Selenium Grid for remote Firefox sessions.
3. Use Chromium with `connectOverCDP` for your primary production workload.

How to Keep Browser Sessions Alive Across Cloud Workers

A common question from teams building AI agents is: "How do I keep browser sessions alive across multiple cloud workers?"

The answer depends on your architecture. If you're using connectOverCDP, the browser runs in a separate process or machine. Your workers connect to it, perform actions, and disconnect. The browser stays alive between connections.

The Wrong Way: Local Browser Per Worker

If each worker launches its own browser, you lose state between requests. Cookies, sessions, and login states disappear when the worker finishes.

// This loses state between workers
async function handleRequest() {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  // ... do work ...
  await browser.close(); // State is gone
}

The Right Way: Persistent Remote Browser

With a remote browser, the browser instance persists. Workers connect, do work, and disconnect. The browser state remains intact.

// This maintains state across workers
async function handleRequest(sessionId: string) {
  const browser = await chromium.connectOverCDP(
    `wss://remote-browser.dev/cdp/${sessionId}`
  );
  const context = browser.contexts()[0];
  const page = context.pages()[0] || await context.newPage();
  // ... do work ...
  await browser.close(); // Browser stays alive
}

Scaling Playwright Browser Workloads Reliably

When you scale browser automation, you hit several problems:

1. Resource exhaustion: Each browser instance consumes significant CPU and memory.
2. Session management: Keeping track of many browser sessions is complex.
3. Network isolation: Browsers need stable network connections.
4. Failure recovery: Browsers crash, and you need to handle it gracefully.

Resource Usage: Headless vs. Headed

Headless browsers use fewer resources, but they're not free. A single headless Chromium instance typically uses 200-400 MB of RAM. Running 100 concurrent sessions means 20-40 GB of RAM just for browsers.

Multi-Session Management

Managing multiple browser sessions requires careful orchestration. You need to:

• Track which sessions are active.
• Handle browser crashes and restarts.
• Manage connection timeouts.
• Clean up idle sessions.

A hosted runtime handles this for you. Remote Browser manages the browser lifecycle, so you focus on your automation logic.

How to Give Your AI Agent Browser Access in Production

If you're building an AI agent that needs browser access, you need to solve several problems:

1. Browser lifecycle: Who launches and manages the browser?
2. Session persistence: How do you maintain state across agent steps?
3. Observation: How does the agent see the browser state?
4. Action execution: How does the agent interact with the page?

The Browser Agent Architecture

A production browser agent typically works like this:

1. Agent receives a task (e.g., "Book a flight").
2. Agent connects to a browser session via CDP.
3. Agent observes the page (screenshot, DOM snapshot, or accessibility tree).
4. Agent decides on an action (click, type, navigate).
5. Agent executes the action via Playwright or Puppeteer.
6. Agent observes the result and repeats.

// Minimal browser agent loop
async function runAgent(task: string, sessionId: string) {
  const browser = await chromium.connectOverCDP(
    `wss://remote-browser.dev/cdp/${sessionId}`
  );
  const page = browser.contexts()[0].pages()[0];

  while (!taskComplete) {
    // Observe
    const screenshot = await page.screenshot();
    const dom = await page.content();

    // Decide (send to LLM)
    const action = await llm.decide({
      task,
      screenshot,
      dom: truncate(dom, 50000)
    });

    // Execute
    if (action.type === 'click') {
      await page.click(action.selector);
    } else if (action.type === 'type') {
      await page.fill(action.selector, action.text);
    }

    // Check completion
    taskComplete = await llm.checkCompletion(task, await page.content());
  }
}

The Playwright connectOverCDP Documentation Gap

The Playwright docs for connectOverCDP are sparse. The method signature is simple, but the practical details are missing:

• How to handle connection timeouts.
• How to manage multiple contexts.
• How to deal with browser crashes.
• How to secure your CDP endpoint.

Connection Timeouts

When you connect to a remote browser, network latency matters. Playwright's default timeout is 30 seconds, but you may need to adjust this for remote connections.

const browser = await chromium.connectOverCDP(
  'wss://remote-browser.dev/cdp/session-id',
  { timeout: 60000 } // 60 seconds
);

Multiple Contexts

A single browser can have multiple contexts (essentially separate browser profiles). This is useful for isolating sessions.

const browser = await chromium.connectOverCDP('wss://...');
const context1 = browser.contexts()[0];
const context2 = await browser.newContext(); // May not work over CDP

Note: Creating new contexts over CDP has limitations. The browser.newContext() method may not work as expected when connected via CDP. You're often limited to the contexts that already exist in the browser.

Selenium and Playwright: A Comparison for Remote Browsers

If you're evaluating Selenium vs. Playwright for remote browser automation, here's a practical comparison:

For new projects, Playwright is generally the better choice. Its auto-waiting and multi-tab handling make it more reliable for complex automation. The Firefox limitation is a real consideration, but for most workloads, Chromium is sufficient.

What Is a Browser Agent, Really?

A browser agent is software that uses a browser to accomplish tasks autonomously. Unlike traditional browser automation (which follows pre-scripted steps), a browser agent uses AI to make decisions about what to do next.

Browser agents typically use:

1. Computer vision to understand page layouts.
2. LLMs to reason about content and decide on actions.
3. Browser automation tools (Playwright, Puppeteer) to execute actions.

The browser is the agent's "hands and eyes." It provides the agent with:

• Observation: Screenshots, DOM snapshots, accessibility trees.
• Action: Clicking, typing, navigating, form submission.
• State: Cookies, sessions, local storage.

Why Browser Agents Need a Dedicated Runtime

Browser agents have different requirements than traditional test automation:

• Long-running sessions: Agents may work for minutes or hours on a single task.
• State persistence: Agents need to maintain login states and cookies.
• Human oversight: Humans may need to intervene or monitor agent progress.
• Scalability: You may run multiple agents concurrently.

A hosted browser runtime addresses these needs. Remote Browser provides persistent sessions, live viewing, and API-based access that fits agent workflows.

The Chromium Sandbox Default: What You Need to Know

If you're running Playwright in production, you'll encounter the Chromium sandbox issue. The Playwright docs mention chromiumSandbox: false as a launch option. This is relevant when running in containers or as root.

const browser = await chromium.launch({
  chromiumSandbox: false // Required in many container environments
});

The sandbox provides an extra layer of security between the browser and your system. Disabling it is sometimes necessary in containerized environments, but it increases risk.

In a hosted browser runtime, this is handled for you. The browser runs in an isolated environment with appropriate security measures.

Making the Right Choice for Your Workload

Here's our practical recommendation:

Choose Chromium with connectOverCDP when:

• You need to connect to already-running browser instances.
• You're building AI agents that need persistent sessions.
• You want the broadest tooling compatibility.
• You need network interception and advanced debugging.

Choose Firefox with Playwright's native launcher when:

• You must test Firefox-specific behavior.
• You're running local or CI tests.
• You don't need to connect to existing browser instances.

Choose a hosted browser runtime when:

• You want to avoid managing browser infrastructure.
• You need persistent sessions across multiple workers.
• You want live debugging and session monitoring.
• You need to scale browser workloads without capacity planning.

Conclusion

The Playwright connectOverCDP method is Chromium-only. Firefox does not support it because Firefox doesn't speak CDP. This is a protocol limitation, not a Playwright bug.

For production workloads, especially AI browser agents, Chromium with connectOverCDP is the pragmatic choice. It gives you a mature protocol, broad tooling support, and the ability to connect to persistent remote browser sessions.

If you need Firefox support, use Playwright's native launcher for local testing and Selenium for remote Firefox sessions. But for most production automation, Chromium is the right answer.

Remote Browser provides hosted Chromium sessions with full CDP support. You get persistent sessions, live debugging, and API-based access without managing browser infrastructure. Explore the documentation to see how it works, or check pricing for current plans.

For more context on how hosted browsers fit into AI agent workflows, read our guides on remote browsers for AI agents and remote browser online. You can also learn about remote web browsers and remote control browsers for broader automation patterns.

For the authoritative reference on Playwright's CDP support, see the official Playwright documentation on connectOverCDP.