To connect Puppeteer to a browser that is already running, call puppeteer.connect() with the browser’s WebSocket debugger endpoint or its browser URL. The call returns a Puppeteer Browser instance you can use to open pages and work with the browser. Use browser.disconnect() to detach without shutting down the external browser; use browser.close() when you intend to close the browser itself.
Connect to an existing browser
Install Puppeteer in your Node.js project if it is not already installed, then make the browser endpoint available to your process. This example uses an environment variable so the endpoint need not be embedded in source code:
import puppeteer from 'puppeteer';
const endpoint = process.env.BROWSER_WS_ENDPOINT;
if (!endpoint) {
throw new Error('Set BROWSER_WS_ENDPOINT to the browser WebSocket endpoint');
}
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 connection options and returned browser behavior are documented in the Puppeteer connect() API and ConnectOptions reference. The environment-variable name is your choice; Puppeteer does not require this particular setup.
Find the browser endpoint
The browser must already be running and reachable from the Node.js process. The host or browser launch environment may print a WebSocket endpoint. Puppeteer documents the general endpoint shape as ws://HOST:PORT/devtools/browser/<id>; use the actual value supplied by your browser environment, not that illustrative pattern as a literal address.
#1 Best Overall
If the browser exposes the Chrome DevTools Protocol HTTP endpoint, request http://HOST:PORT/json/version from the appropriate host and port. Its webSocketDebuggerUrl field can provide the socket URL for browserWSEndpoint. The endpoint’s scheme, hostname, port, and any authentication requirements depend on the host. See Puppeteer’s browser management guide and Browser.wsEndpoint() reference.
Choose the right connection option
browserWSEndpoint: use this when you have the browser’s DevTools WebSocket endpoint.browserURL: use this when the browser host provides a browser URL that Puppeteer can use to discover the endpoint.wsOptions: use this to configure Node.js WebSocket connection details, including headers where required by the host. The current reference marks the olderheadersoption as deprecated in favor ofwsOptions.headers.
Match the option and authentication method to what the browser host actually provides. Treat endpoint URLs and credentials as secrets: do not commit them to source control or print them in logs. Check the current ConnectOptions documentation for the exact options supported by your installed Puppeteer version.
Rank #2
Use the connected browser
puppeteer.connect() resolves to a Browser object, so you can use Puppeteer’s browser and page APIs against the attached instance. For example, the code above creates a page, navigates to a URL, and reads its title. Your Node.js process must be able to reach the browser endpoint, and the browser must accept the connection.
A connection attaches to an existing browser; it does not launch a replacement browser. Browser availability, authentication, and access to existing pages or contexts depend on how the host exposes that instance. The connect() API describes the method as attaching Puppeteer to an existing browser instance.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #3
Detach or shut down the browser
browser.disconnect()detaches Puppeteer. It does not close the browser or its pages. Choose it when the browser is externally managed or another process is expected to keep using it.browser.close()gracefully closes the browser. Choose it only when your application owns the browser lifecycle and is meant to shut it down.
Do not substitute close() for disconnect() when attaching to a shared or externally managed browser. The lifecycle distinction is covered in Puppeteer’s browser management guide.
Check browser compatibility
Puppeteer’s supported-browser mapping is tied to Puppeteer releases, so check the row for the version installed in your project rather than relying on a version number from an old example. At the time of the cited compatibility documentation, its row for Puppeteer 25.12.0 listed Chrome for Testing 154.0.8037.57 and Firefox 156.0.1; those identifiers are release-specific, not evergreen requirements. The documentation also says Puppeteer has downloaded and worked with Chrome for Testing since v20.0.0, and its Firefox support moved to stable Firefox starting with v23.0.0. Consult the current Puppeteer supported browsers table for your release.
Rank #4
Security considerations for remote browsers
A WebSocket endpoint grants access to a browser’s DevTools interface, so protect it as you would a credential. Restrict network exposure and use the authentication and connection controls provided by the host. Puppeteer’s current options reference includes an experimental, Chrome-only allowlist for Chrome 149 or newer. It limits browser network requests matching configured URL patterns while Puppeteer remains attached, but Puppeteer explicitly cautions that it is not complete network sandboxing. For full isolation, use operating-system or container-level controls in addition to Puppeteer’s guardrails. See the ConnectOptions reference.
Troubleshoot connection failures
- Missing or malformed endpoint: Confirm the environment variable is set and contains the actual endpoint supplied by the browser host. If using CDP discovery, inspect the host’s
/json/versionresponse and copy itswebSocketDebuggerUrlvalue. - Connection refused or timeout: Check that the browser is running, the Node.js process can reach the host and port, and any network rules allow the connection. A local address inside one container or machine may not identify the browser from another.
- Authentication or WebSocket handshake error: Verify the host’s required authentication mechanism and configure supported Node.js WebSocket options through
wsOptions. Avoid exposing credentials in logs. - Protocol or browser incompatibility: Check the compatibility row for the installed Puppeteer release and the browser version provided by the host in the supported browsers table.
- Browser unexpectedly exits: Check whether your code calls
browser.close()or whether the external host is stopping its browser. Usedisconnect()when your process should only detach.
Or skip the browser setup
If your goal is a website screenshot rather than attaching Puppeteer to a browser you manage, ScreenshotNeo offers a screenshot API and MCP server. One GET request can return a PNG, JPEG, WebP, or PDF. For example, with cURL:
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Quick Recap
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 API documentation for request options. Cookie and consent banners, newsletter popups, and chat widgets are removed before capture by default, and each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers identify the page verdict and billing status. Its MCP server lets AI agents use screenshot tools, and the free plan includes 1,000 screenshots per month with no card required; paid plans start at $5 for 3,000 screenshots. Sign up for ScreenshotNeo’s free plan.
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.
