Use Puppeteer’s connect() method with the running browser’s DevTools WebSocket URL. Find that URL in the browser’s webSocketDebuggerUrl field at http://HOST:PORT/json/version, then pass it as browserWSEndpoint. This attaches Puppeteer to the existing browser instead of launching a new one.
What you need before connecting
The browser must already be running and expose a debugging endpoint that the Node.js process running Puppeteer can reach. The browser and Puppeteer do not have to run on the same machine, but the host, port, and WebSocket endpoint must be reachable from the Puppeteer process.
As an Amazon Associate I earn from qualifying purchases.
Puppeteer’s documented endpoint format is ws://HOST:PORT/devtools/browser/<id>. Get the actual value from the running browser rather than guessing the ID or constructing the URL yourself. The endpoint may be different for each browser instance.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Find the browser’s WebSocket endpoint
- Identify the host and port where the browser’s debugging endpoint is available.
- Request
http://HOST:PORT/json/versionfrom the machine running Puppeteer, substituting the browser’s actual host and port. - Read the
webSocketDebuggerUrlvalue in the response. Use that complete URL in the Puppeteer connection options.
Puppeteer documents this discovery method in its browser management guide and specifies the endpoint format in the Browser.wsEndpoint() reference. The documentation explains how to discover the endpoint, but does not provide a universal browser launch command for every operating system or managed browser service; configure the browser according to the environment you use.
#1 Best Overall
Connect from Node.js
Install Puppeteer in the Node.js project that will connect, then use the browser’s exact WebSocket URL. Replace the example value with the URL returned by /json/version.
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.connect({
browserWSEndpoint: 'ws://127.0.0.1:9222/devtools/browser/REPLACE_WITH_ACTUAL_ID',
});
try {
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
} finally {
// Detach Puppeteer; leave the existing browser running.
browser.disconnect();
}
})();The code uses the CommonJS form of importing Puppeteer. In an ES module, use import puppeteer from 'puppeteer'; and keep the same connect() call. The official API describes connect(options) as attaching to an existing browser and resolving to a Browser object. See Puppeteer’s connect API.
Work with existing pages instead of opening another
browser.newPage() creates a new page in the connected browser. To inspect pages that are already open, use browser.pages():
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Rank #2
- Used Book in Good Condition
const pages = await browser.pages();
console.log(`Open pages: ${pages.length}`);
for (const page of pages) {
console.log(await page.url());
}Choose how Puppeteer should detach or close
| Call | Effect | Use it when |
|---|---|---|
browser.disconnect() |
Detaches Puppeteer while leaving the browser process and its pages running. | The browser is shared, persistent, or managed separately from the script. |
browser.close() |
Closes the browser. | Your script owns the browser lifecycle and intends to shut it down. |
Do not substitute close() for disconnect() if another process or user needs the attached browser to remain open. Puppeteer’s browser management guide describes the distinction.
Other connection options and compatibility
browserURL
The ConnectOptions reference lists browserURL as well as browserWSEndpoint. The explicit documented connection example uses browserWSEndpoint, so use that route when you have retrieved the WebSocket URL. The reference excerpt does not establish enough detail to prescribe a universal browserURL format or usage case.
Protocol behavior
The protocol is determined at runtime and defaults to CDP when connecting to a browser. WebDriver BiDi is an explicit configuration case using protocol: "webDriverBiDi"; do not assume it is the default. See the ConnectOptions reference.
Rank #3
Experimental channel option
The same reference marks channel experimental for connect(). It looks for an open WebSocket in the channel’s well-known default user data directory and works only for Chrome in Node.js. Treat it as a special case, not as a replacement for discovering and supplying the debugger WebSocket endpoint.
Browser-page runtime
A browser-compatible Puppeteer build can connect through WebSockets to an existing browser when running in a browser page, but it cannot launch or download browsers there because those actions depend on Node.js APIs. The official browser management guide uses the browser-specific puppeteer-core entry point for this environment.
Version and deployment differences
The official API reference showed Puppeteer 25.12.0 when checked on October 3, 2026. API details, including experimental options, can change. The documented API and endpoint shape do not establish compatibility with every Chrome, Chromium, or remote-browser deployment. Confirm that your particular browser exposes the expected protocol and that its endpoint is reachable from your Puppeteer process.
Keep separate tasks’ browser storage isolated
If separate tasks must not share cookies or local storage, use separate browser contexts. Puppeteer’s browser management guide states that cookies and local storage are not shared between contexts. This is different from opening multiple pages in the same context, where those pages share that context’s browser state.
Troubleshooting connection failures
- Connection fails or times out: Check that the browser is still running, the host and port are correct, and the Puppeteer process can reach them. Request
http://HOST:PORT/json/versionfrom the same environment as Puppeteer and confirm it returns the expectedwebSocketDebuggerUrl. - The WebSocket handshake fails: Use the complete
webSocketDebuggerUrlreturned by the browser. Do not omit the/devtools/browser/<id>portion or guess the browser ID. - Endpoint works locally but not remotely: The endpoint may not be reachable across the network from the Puppeteer host. Configure network access for the browser service and verify reachability from the client environment; a URL that works only on the browser machine is not sufficient for a remote Puppeteer process.
- Connection succeeds but an expected page is missing:
browser.newPage()opens a new page; usebrowser.pages()to enumerate pages already open in the connected browser. - The browser disappears after cleanup: Check whether the code called
browser.close(). Callbrowser.disconnect()when Puppeteer should detach without terminating the browser. - Behavior differs between environments: Verify the browser’s protocol and Puppeteer version. CDP is the default documented protocol; BiDi requires explicit configuration, and the
channelconnection option is experimental with stated Chrome and Node.js restrictions.
Or skip the browser setup
If your goal is simply to capture a website rather than automate an existing browser session, ScreenshotNeo provides a website screenshot API. A single GET request returns an image or PDF. For example, using cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo documentation for API options. Cookie and consent banners are accepted before capture, and known consent platforms, newsletter popups, and chat widgets are removed; each of those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. ScreenshotNeo also has an MCP server with take_screenshot, get_page_info, and capture_pdf tools for AI agents. The Free plan includes 1,000 screenshots a month without a card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Frequently Asked Questions
Does Puppeteer launch a new browser when I use connect()?
No. connect() attaches to a browser that is already running; use Puppeteer’s launch workflow when you want Puppeteer to start one.
Can I connect to a browser on another machine?
Yes, provided the debugger endpoint is reachable from the machine running Puppeteer and you use the endpoint that browser instance exposes.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Which protocol does connect() use by default?
CDP is the documented default when connecting to a browser; WebDriver BiDi requires explicit protocol configuration.
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.
