Use puppeteer.connect() to attach Node.js Puppeteer to a browser that is already running. Pass the browser’s WebSocket debugger endpoint as browserWSEndpoint, or use its HTTP browser URL with browserURL. The call returns a Puppeteer Browser you can use to open pages; use browser.disconnect() to detach without shutting down the external browser.
What you need before connecting
The browser must already be running and reachable from the Node.js process, and it must expose an endpoint compatible with Puppeteer. Obtain that endpoint from the browser host or process; do not assume that a sample host, port, or URL applies to your setup. Keep endpoint credentials private and avoid logging them.
As an Amazon Associate I earn from qualifying purchases.
- Install Puppeteer in your Node.js project and check the official supported-browsers table for the row matching your installed Puppeteer version. Compatibility is release-specific.
- Get either the browser’s WebSocket debugger URL or the HTTP browser URL, plus any authentication details required by the host.
- Decide whether your code should only detach when finished or shut down the browser it connected to.
Puppeteer documents connect() as attaching Puppeteer to an existing browser instance. See the connect() API and browser management guide.
Free tools Windows power users keep installed
One-click scans. No signup required.
Find the browser endpoint
Use the WebSocket debugger endpoint
If the browser host provides a WebSocket debugger URL, pass it as browserWSEndpoint. Puppeteer’s documented endpoint format is ws://HOST:PORT/devtools/browser/<id>; the actual scheme, host, port, path, and any access controls depend on the environment. A browser’s Browser.wsEndpoint() method returns this kind of URL when called from the process managing that browser; it is not a way to discover an unrelated browser. See the wsEndpoint() reference.
#1 Best Overall
Discover it through the CDP HTTP endpoint
When the host exposes the Chrome DevTools Protocol HTTP endpoint, request http://HOST:PORT/json/version and read the webSocketDebuggerUrl value in the response. Substitute the real host, port, and scheme supplied by the browser environment. Treat the returned URL as sensitive if it grants access to the browser.
Connect, use the browser, and detach
This ES module example reads the WebSocket endpoint from an environment variable, attaches to the running browser, opens a page, and detaches in a finally block. Install Puppeteer with npm install puppeteer and set BROWSER_WS_ENDPOINT to the actual endpoint before running it.
Rank #2
import puppeteer from 'puppeteer';
const endpoint = process.env.BROWSER_WS_ENDPOINT;
if (!endpoint) {
throw new Error('Set BROWSER_WS_ENDPOINT to the browser WebSocket debugger URL');
}
const browser = await puppeteer.connect({
browserWSEndpoint: endpoint,
});
try {
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
} finally {
browser.disconnect();
}The environment-variable convention is an example, not a Puppeteer requirement. The available connection fields and WebSocket options are documented in the ConnectOptions reference.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallChoose the connection option
| Option | Supply | Use it when |
|---|---|---|
browserWSEndpoint |
The browser’s WebSocket debugger URL | You have the direct WebSocket endpoint, for example the value returned by /json/version. |
browserURL |
The browser’s HTTP URL | The host provides a browser HTTP endpoint and you want Puppeteer to connect using that URL. |
wsOptions |
Node.js WebSocket configuration | The connection needs WebSocket-specific configuration such as headers. The current API documents wsOptions.headers; the older headers option is deprecated. |
Use the option and authentication mechanism the browser host actually supplies. Puppeteer currently defaults to the CDP protocol when connecting to a browser, according to its ConnectOptions documentation.
Rank #3
Detach or shut down the browser
browser.disconnect()disconnects Puppeteer but leaves the browser and its pages running. Use it when the browser is externally managed, shared, or expected to continue serving another process.browser.close()gracefully shuts down the browser. Use it only when your code owns the browser lifecycle and closing it is intended.
These methods are not interchangeable: closing a shared browser can disrupt its other users. Puppeteer’s browser management guide describes the lifecycle distinction.
Security and compatibility considerations
Treat endpoints and credentials as secrets
A debugger endpoint can provide control over browser activity. Do not expose it in public logs, source control, or an untrusted network. Follow the hosting environment’s authentication and network-access controls; simply attaching Puppeteer does not create a security boundary.
Rank #4
Match the browser to your Puppeteer release
Consult the supported-browsers table for your installed version rather than copying a version number from an example or an older guide. The table is release-specific. Puppeteer documents that, starting with v20.0.0, it downloads and works with Chrome for Testing; its Firefox support moved to stable Firefox starting with v23.0.0. Those details do not guarantee that every arbitrary externally hosted browser build is compatible.
Do not treat the experimental allowlist as full isolation
The current ConnectOptions API documents an experimental, Chrome-only allowlist feature requiring Chrome 149 or newer. It limits browser network requests matching configured URL patterns while Puppeteer remains attached, but Puppeteer explicitly describes it as an additional guardrail, not complete network sandboxing. Use operating-system or container-level controls when full network isolation is required.
Troubleshooting connection failures
- Invalid or missing endpoint: Confirm that the environment variable is set and contains the complete URL, including the correct scheme and path. If using CDP discovery, inspect the actual
webSocketDebuggerUrlin/json/version. - Connection refused or timeout: Check that the browser is running, the endpoint is reachable from the Node.js machine or container, and the host and port are accessible. A browser reachable on one machine is not automatically reachable from another.
- Authentication or handshake failure: Verify the host’s required credentials and WebSocket headers. Where needed, configure Node.js WebSocket details using
wsOptions; do not put secrets in logs. - Browser or protocol incompatibility: Check the official support table for the installed Puppeteer release and the browser version exposed by the host. Do not assume a version mapping from a different Puppeteer release applies.
- Browser unexpectedly stays open: That is the expected result of
disconnect(). Callclose()only if you intend to shut down the browser. - Shared browser unexpectedly closes: Replace
browser.close()withbrowser.disconnect()when your process should release its Puppeteer connection without ending the browser session.
Or skip the browser setup
If the goal is a screenshot rather than browser automation, ScreenshotNeo provides a website screenshot API and MCP server. One GET request can return a PNG, JPEG, WebP, or PDF; its API options include full-page capture, CSS-selector element capture, viewport and device settings, and custom CSS or JavaScript. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpScreenshotNeo accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses include X-Page-Verdict and X-Billed headers. Its MCP server offers take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 screenshots.
Sign up for ScreenshotNeo free: 1,000 screenshots a month, no card required.
Recommended Free Tools
Frequently Asked Questions
Can I connect Puppeteer to a browser started by another process?
Yes. If it is reachable and exposes a Puppeteer-compatible endpoint, pass its WebSocket debugger URL or browser HTTP URL to `puppeteer.connect()`.
Does `browser.disconnect()` close pages in the external browser?
No. It detaches Puppeteer and leaves the browser and its pages running.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
