5 min read
Also: CDP, DevTools Protocol, Chrome remote debugging protocol, remote-debugging-port, Chrome remote debugging, chrome devtools protocol
Chrome DevTools Protocol (CDP)
Quick answer
The Chrome DevTools Protocol (CDP) is the JSON-over-WebSocket interface Chrome exposes for inspecting and controlling the browser; DevTools, Puppeteer and Playwright all use it. To connect, start Chrome with --remote-debugging-port=9222 and a separate --user-data-dir, then attach with puppeteer.connect() or Playwright's connectOverCDP(); if the connection drops, see Protocol error: Target closed.
The Chrome DevTools Protocol (CDP) is the JSON-over-WebSocket interface Chrome exposes for inspecting and controlling the browser. Chrome DevTools, Puppeteer, Playwright and many hosted browser services use it to navigate, click, intercept network traffic and capture pages.
Last verified
What people do with Chrome DevTools Protocol (CDP)
- Fix "Protocol error: Target closed"
The CDP target went away mid-command: crashes, closed tabs and launch problems.
- Fix "Session closed. Most likely the page has been closed"
Why a CDP session ends under Puppeteer and how to keep it alive.
- Fix "Target page, context or browser has been closed"
The Playwright version of a lost CDP target.
- Fix "Execution context was destroyed"
A navigation replaced the page while a CDP evaluation was running.
- Run Chrome headless over CDP
Headless flags, chrome-headless-shell and remote debugging.
- Drive CDP from Node.js with Puppeteer
Google's CDP client library and how it launches or attaches to Chrome.
- Pretty-print /json/version and CDP responses
Paste raw CDP JSON to read it.
Key facts
| Defined by | Google's Chrome DevTools team |
|---|---|
| Transport | JSON messages over WebSocket (or a pipe), usually via --remote-debugging-port |
| Supported browsers | Chrome, Chromium and Chromium-based browsers such as Edge, Brave and Opera |
| Documented versions | Stable (1.3) and tip-of-tree (latest Chromium, includes experimental methods) |
| Used by | Chrome DevTools, Puppeteer, Playwright (Chromium), Selenium 4 CDP APIs, ChromeDriver internally |
| Notable change | Chrome 136 stopped honoring remote debugging switches on the default user data directory |
What is the Chrome DevTools Protocol?
The Chrome DevTools Protocol, usually shortened to CDP, is the low-level interface Chrome exposes for inspecting and controlling the browser. Chrome's own DevTools panel uses it: when you open DevTools and watch the Network tab fill up, the panel is receiving CDP events. Automation libraries use the same protocol to drive the browser from code.
CDP is defined and maintained by Google's Chrome DevTools team and documented at chromedevtools.github.io/devtools-protocol. It works in Chrome, Chromium and Chromium-based browsers such as Microsoft Edge, Brave and Opera. It is not a W3C standard: Google changes it as Chrome evolves.
How CDP works
A browser started with remote debugging enabled, typically --remote-debugging-port=9222, listens for connections. A client opens a WebSocket to that port and exchanges JSON messages:
id, a method and params, for example {"id": 1, "method": "Page.navigate", "params": {"url": "https://example.com"}}. The browser replies with a result carrying the same id.Network.requestWillBeSent or Page.loadEventFired, once the client has enabled that domain.The protocol is grouped into domains, each covering one area of the browser: Page (navigation, screenshots, PDFs), Runtime (evaluating JavaScript), DOM, Network (requests, responses, cookies, headers), Input (mouse and keyboard events), Emulation (device, viewport, geolocation, time zone), Fetch (intercepting and modifying requests), Target (tabs, iframes, workers) and others.
The HTTP endpoint on the same port also lists open targets at /json and browser details, including the WebSocket URL to connect to, at /json/version.
The documentation has two views: a stable protocol version (1.3) with a smaller set of methods, and tip-of-tree, which reflects the latest Chromium and includes experimental methods that can change or disappear between releases.
Who uses CDP
connectOverCDP.What CDP makes possible
Because it sits below the page, CDP can do things a script inside the page cannot: intercept and rewrite network requests, read every response body, set cookies for any domain, emulate a phone or a different time zone, throttle the network, capture full-page screenshots, collect performance traces and code coverage, and dispatch trusted mouse and keyboard events that the page sees as real input.
Common problems
`connect ECONNREFUSED 127.0.0.1:9222`. Nothing is listening. Chrome was not started with the debugging flag, or another Chrome instance already owned the profile and the flag was ignored.
Remote debugging ignored on your normal profile. Since Chrome 136, Chrome no longer honors --remote-debugging-port when it uses the default user data directory, a change made to stop infostealer malware from reading real profiles. Start Chrome with a separate --user-data-dir.
Experimental methods breaking after an update. Code written against tip-of-tree methods can fail when Chrome updates. Stick to the stable domains where you can, or pin the browser version, for example with Chrome for Testing.
Exposing the port. Anyone who can reach a debugging port has full control of that browser, including its cookies and logged-in sessions. Bind it to localhost and never expose it to the internet.
Detection. Anti-bot scripts look for side effects of a CDP client being attached. A well-known example is the Runtime.enable command, which most libraries send on every page and which leaves traces a page can observe. Patched builds such as patchright change how the library uses CDP to avoid those leaks. See headless Chrome for the other common signals.
CDP and WebDriver BiDi
CDP is Chrome-specific. WebDriver BiDi is the W3C effort to give every browser a similar two-way protocol. Firefox deprecated its partial CDP support in Firefox 129 in favor of BiDi, and Puppeteer now drives Firefox over BiDi. For Chrome automation, CDP remains what most tools use underneath.
CDP and Autonoly
Autonoly's cloud browser is Chromium controlled by Playwright with patchright, so CDP is the protocol underneath every click and extraction the agent performs. You never touch it directly: you describe the task, the agent works in a headed browser you can watch in the live view, and a successful run can be saved as a workflow.
Why It Matters
CDP is the layer most Chrome automation actually runs on. Knowing it helps you debug connection errors, attach tools to an existing browser, intercept network traffic, and understand why some automation is detectable.
How Autonoly Solves It
Autonoly's browser is Chromium driven by Playwright with patchright, which uses CDP under the hood with fewer detectable side effects than stock Playwright. You never manage ports or WebSockets: the agent works from a plain-English task in a headed browser you can watch and take over.
Learn moreExamples
Attaching Playwright to an already running Chrome with connectOverCDP to reuse a logged-in session in a separate test profile
Using the Network and Fetch domains to block images and ads during a scrape and read API responses directly
Emulating an iPhone viewport and a different time zone through the Emulation domain to test a localized checkout page
Frequently Asked Questions
What is CDP used for?
It is used to inspect and control Chromium-based browsers from outside the page: navigating, running JavaScript, intercepting network requests, emulating devices, taking screenshots and profiling performance. Chrome DevTools uses it, and so do automation libraries such as Puppeteer and Playwright.
How do I connect to Chrome with CDP?
Start Chrome with --remote-debugging-port=9222 and a separate --user-data-dir, open http://localhost:9222/json/version to get the WebSocket URL, then connect with a library such as Puppeteer's connect or Playwright's connectOverCDP, or with a raw WebSocket client.
Why is --remote-debugging-port not working?
Since Chrome 136, the flag is ignored when Chrome runs on its default user data directory, as a protection against malware. Pass --user-data-dir with a different folder. Also check that no other Chrome instance is already using that profile.
Is CDP a standard?
No. CDP is defined by Google and changes with Chrome; experimental methods can change between releases. The W3C standard effort for a similar bidirectional protocol across browsers is WebDriver BiDi, which Firefox and Puppeteer have adopted.
Does Firefox support the Chrome DevTools Protocol?
Not anymore in any practical sense. Firefox had partial CDP support for Puppeteer, deprecated it in Firefox 129 and moved to WebDriver BiDi. Puppeteer now automates Firefox through BiDi.
Is exposing a CDP port dangerous?
Yes. Anyone who can connect to the port controls the browser completely, including cookies and logged-in sessions. Keep it bound to localhost or behind authenticated infrastructure, and never open it to the internet.
Further reading
Related terms, automations and guides
Where this concept shows up in practice.
Stop reading about automation.
Start automating.
Describe what you need in plain English. Autonoly's AI agent builds and runs the automation for you — no code required.