Chrome DevTools Protocol: Two Steps, Both Required
CDP remote-controls Chrome through a two-phase connection: HTTP for the GUID, then WebSocket for commands. Both must hit the same process.
The Control Channel for Chrome
CDP is how programs remote-control Chrome. Puppeteer, Playwright, and chromedp all use it. The word “debug” in CDP is misleading. CDP is the control channel for Chrome. Chrome kept the name from its DevTools origin.
Prerequisite: IP, port, localhost.
Two-Phase Connection
CDP needs two steps. Both must reach the same Chrome process.
Step 1 is a normal HTTP request. Step 2 is a WebSocket (persistent connection). Each step is a separate TCP connection.
GUID: Each Chrome’s ID Card
abc-123 is a GUID (Globally Unique Identifier). Each Chrome process generates one at startup. One GUID opens exactly one WebSocket session. A different Chrome has a different GUID and returns 404.
/json/version Has Two Consumers
The probe discards the response body. It uses /json/version as a health check. The GUID only matters to CDP clients.
“Two steps = two separate network connections. A load balancer can send them to different pods. That breaks everything.”
References:
Related: see what happens when Chrome 128 locks DevTools to localhost, learn how the two-step design causes the GUID race, or go back to the series overview.