cdp-tunnel

library2.10.9jsnpmunverified

cdp-tunnel is a Chrome extension and proxy server that bridges Chrome's DevTools Protocol (CDP) to WebSocket, enabling remote browser control via Playwright or Puppeteer. v2.10.9 (stable) supports multiple simultaneous clients with message isolation, auto-reconnect, and a configuration UI. The npm package provides CLI commands (setup, start, status, diagnose) and an extensible proxy. Key differentiators: acts as a Chrome extension rather than requiring a separate Browser instance, allowing you to control an existing user's browser; supports both 'create' and 'takeover' modes for flexible page management. Requires Node.js >=16.

testing devops

npm install cdp-tunnel

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CDP-TUNNEL

cdp-tunnel

testingjavascriptv2.10.9

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default export

✓ import cdpTunnel from 'cdp-tunnel'

✗ const cdpTunnel = require('cdp-tunnel')

Package does not export a main function; use CLI commands instead.

Starts the CDP Tunnel proxy server and shows how to connect with Playwright to control an existing browser.

// Install globally npm install -g cdp-tunnel # Start server and auto-load extension (recommended) cdp-tunnel setup # Or just start the proxy server cdp-tunnel start -p 9221 # Then connect Playwright/Puppeteer to http://localhost:9221 const { chromium } = require('playwright'); (async () => { const browser = await chromium.connectOverCDP('http://localhost:9221'); const context = browser.contexts()[0]; const page = await context.newPage(); await page.goto('https://example.com'); console.log(await page.title()); await browser.close(); })();

Debug

Known issues

gotchaMulti-client support requires message isolation; pages created by one client are not accessible to others.

fix

Use the 'takeover' mode if you need to share pages across clients.

affects: >=2.0.0

breakingIn version 2.x, the proxy server binding port changed from 9220 to 9221.

fix

Update your client connections to use port 9221 instead of 9220.

affects: >=2.0.0 <3.0.0

deprecatedCLI subcommand 'init' is deprecated; use 'setup' instead.

fix

Replace `cdp-tunnel init` with `cdp-tunnel setup`.

affects: >=2.8.0

gotchaThe extension must be loaded unpacked; the 'setup' command attempts to auto-load it into Chrome, but on some systems you may need to manually load it from chrome://extensions.

fix

Go to chrome://extensions, enable Developer mode, click 'Load unpacked' and select the extension directory provided by `cdp-tunnel setup`.

affects: >=1.0.0

Errors

Common errors & fixes

Error: connect ECONNREFUSED ::1:9221

Proxy server not running or wrong port

fix

Ensure `cdp-tunnel start` is running and specify the correct port: `chromium.connectOverCDP('http://localhost:9221')`.

WebSocket connection to 'ws://localhost:9221/plugin' failed

Extension not connected or WebSocket URL mismatch

fix

Open the extension's configuration page, add a connection with WebSocket URL `ws://localhost:9221/plugin`.

TypeError: browser.contexts is not a function

Using Playwright's `connectOverCDP` incorrectly or with wrong CDP endpoint

fix

Ensure you call `chromium.connectOverCDP('http://localhost:9221')` and not an invalid endpoint.

Upgrade

Version history

2.10.9latest on npm

Audit

Dependencies

wsrequiredWebSocket server for communication with extension and clients

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/dyyz1993/cdp-tunnel ↗

packagecdp-tunnel ↗

homepagehttps://github.com/dyyz1993/cdp-tunnel#readme ↗