Chrome CDP Remote Control#

Use when: automating browser tasks programmatically — navigate pages, capture screenshots, run searches, execute JavaScript — without a full Playwright/Puppeteer dependency.

---

Setup: Launch Chrome with CDP enabled#

Linux#

bash

google-chrome \
  --remote-debugging-port=9222 \
  --remote-allow-origins=* \
  --user-data-dir=~/.config/chrome-cdp

macOS#

bash

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --remote-allow-origins=* \
  --user-data-dir="$HOME/.config/chrome-cdp"

Note: Use a dedicated --user-data-dir (e.g. ~/.config/chrome-cdp) — Chrome 126+ blocks CDP on the default profile by design. Log in with your Google account once to enable sync.

Note: On macOS, omit --user-data-dir only if you don't need sync — it gives you your real profile with extensions and custom shortcuts.

Verify CDP is running#

bash

curl http://localhost:9222/json/version

Should return browser version and a webSocketDebuggerUrl.

Kill and relaunch#

bash

pkill -f 'chrome.*remote-debugging-port=9222'
sleep 2
# relaunch with flags above

---

Setup: Remote machine via SSH tunnel (recommended)#

Forward the remote machine's CDP port to localhost:

bash

ssh -L 9223:localhost:9222 user@remote-host -N &

Then use PORT = 9223 in your scripts. Works great over Tailscale.

---

macOS: Raycast Script Command#

Save as ~/.config/raycast/scripts/chrome-cdp.sh and chmod +x:

bash

#!/bin/bash
# @raycast.schemaVersion 1
# @raycast.title Chrome CDP
# @raycast.mode silent
# @raycast.icon 🌐
# @raycast.description Launch Chrome with CDP enabled

pkill -f "Google Chrome.*remote-debugging-port" 2>/dev/null
sleep 1

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --remote-allow-origins=* \
  --user-data-dir="$HOME/.config/chrome-cdp" &

echo "Chrome CDP started on port 9222"

---

Python: WebSocket control pattern#

Install dependency (once):

bash

pip install websocket-client

python

import json, urllib.request, websocket, time, base64

PORT = 9222  # use 9223 if connecting via SSH tunnel

def send_recv(ws, method, params, msg_id):
    """Send a CDP command and wait for its response, draining intermediate events."""
    ws.send(json.dumps({"id": msg_id, "method": method, "params": params}))
    for _ in range(30):
        msg = json.loads(ws.recv())
        if msg.get("id") == msg_id:
            return msg
    return None

# Open a new tab
req = urllib.request.Request(f"http://localhost:{PORT}/json/new", method="PUT")
tab = json.loads(urllib.request.urlopen(req).read())

# Connect via WebSocket — origin header is required
ws = websocket.WebSocket()
ws.connect(tab["webSocketDebuggerUrl"], origin=f"http://localhost:{PORT}")
ws.settimeout(15)

msg_id = 1
send_recv(ws, "Page.enable", {}, msg_id); msg_id += 1

# Navigate to a URL
send_recv(ws, "Page.navigate", {"url": "https://example.com"}, msg_id); msg_id += 1
time.sleep(5)  # wait for page load

# Take a screenshot
# Use fromSurface + scale=2 on Retina/HiDPI displays (e.g. MacBook Pro)
result = send_recv(ws, "Page.captureScreenshot", {
    "format": "jpeg",
    "quality": 70,
    "fromSurface": True,
    "scale": 2  # remove on non-Retina displays
}, msg_id); msg_id += 1

img = base64.b64decode(result["result"]["data"])
with open("/tmp/cdp_screenshot.jpg", "wb") as f:
    f.write(img)

ws.close()
print("Screenshot saved.")

---

Custom search engine shortcuts (bangs)#

If Chrome is launched with a real user profile, custom search engine shortcuts are available.

Configure in Chrome → Settings → Search engine → Manage search engines.

Example — add Perplexity as !ppx:

• Shortcut: !ppx
• URL: https://www.perplexity.ai/search?q=%s

Trigger via address bar: type !ppx then Tab, then your query.

When controlling via CDP from a different machine, use the full URL directly:

text

https://www.perplexity.ai/search?q=YOUR+QUERY
https://www.google.com/search?q=YOUR+QUERY

---

CDP patterns#

• Never connect to ws://localhost:9222/devtools/browser directly — always fetch http://localhost:9222/json/list and use webSocketDebuggerUrl from the target tab
• Runtime.enable and Page.enable must be called before any Runtime.evaluate or Page.navigate
• Network.responseReceived doesn't include body — call Network.getResponseBody with requestId after response completes
• Block URLs before navigate: call Network.setBlockedURLs before Page.navigate, not after

---

Pitfalls#

• --remote-allow-origins=* is required — omitting it causes 403 Forbidden on WebSocket handshake
• Chrome 126+ blocks CDP on the default profile — always use a dedicated --user-data-dir
• Always filter ws.recv() by message ID — CDP sends intermediate events between your command and its response
• SSH tunnel holds the port after Chrome dies — kill the tunnel before relaunching ( kill %1 or pkill ssh)
• macOS: omit --user-data-dir only if you want your real profile with bangs/extensions (and don't mind Chrome not starting if already open)
• Chromium-based alternatives (Helium, Brave, etc.) support CDP but may behave inconsistently — Chrome is most reliable