Use puppeteer.connect() when a browser is already running and you want Puppeteer to control it. Provide its DevTools WebSocket endpoint with browserWSEndpoint, or its debugging HTTP address with browserURL. The method resolves to a Browser object; unlike launch(), it does not start the browser process. This guide reflects the Puppeteer 25.12.0 API reference checked October 3, 2026.
How do I connect Puppeteer to an existing browser?
Start with a browser that exposes a remote debugging endpoint, then pass the endpoint to puppeteer.connect(). In Node.js, the basic pattern is:
As an Amazon Associate I earn from qualifying purchases.
import puppeteer from 'puppeteer';
const browser = await puppeteer.connect({
browserWSEndpoint: 'ws://HOST:PORT/devtools/browser/ID',
});
try {
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
} finally {
await browser.disconnect();
}Replace the example endpoint with the WebSocket URL for the browser you intend to control. The Puppeteer API describes connect() as attaching to an existing browser instance and returning a promise for a Browser. See the PuppeteerNode.connect() reference.
disconnect() closes Puppeteer’s connection; it does not terminate the browser process. Use it when your script should release the connection but leave the existing browser running.
#1 Best Overall
Where do I get browserWSEndpoint?
Read it from a browser Puppeteer launched
If you launched the browser with Puppeteer elsewhere in your application, call browser.wsEndpoint() on that Browser object and provide the returned string to another Puppeteer connection. The documented URL shape is ws://HOST:PORT/devtools/browser/<id>.
Discover it from the debugging HTTP address
For a browser exposing remote debugging at HOST:PORT, request http://HOST:PORT/json/version and read the webSocketDebuggerUrl value. Use that WebSocket URL as browserWSEndpoint. The browser’s deployment or hosting documentation is the place to find the correct host, port, and any access requirements; do not assume a local address for a remote browser.
See the official Browser.wsEndpoint() reference for the endpoint format and discovery address.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Use browserURL when you have the debugging HTTP address
browserURL is the alternative when you have the browser’s debugging HTTP address rather than its WebSocket URL. The exact address depends on how the browser is deployed, so use the provider’s stated debugging address. Choose one connection target that matches what you have rather than guessing or constructing an endpoint ID.
Connect or launch: which should you use?
| Choice | What it does | Use it when |
|---|---|---|
puppeteer.connect(options) |
Attaches Puppeteer to an existing browser and resolves to a Browser. |
A browser process is already running and you have its connection endpoint. |
puppeteer.launch(options) |
Starts a browser process under Puppeteer’s control. | Your program should create and manage the browser process. |
LaunchOptions extends the shared connection options and adds launch-specific settings. That shared inheritance does not make connect() launch a browser: the decision is whether the browser already exists. See the LaunchOptions reference.
Which ConnectOptions settings matter?
The following defaults and caveats are from Puppeteer’s version 25.12.0 ConnectOptions reference. Some options are experimental or restricted to particular runtimes, so check the current API reference if you use a later version.
Rank #3
| Option | Behavior and when to change it |
|---|---|
browserWSEndpoint |
Connect using the browser’s DevTools WebSocket URL. |
browserURL |
Connect using the browser’s debugging HTTP address. |
defaultViewport |
Defaults to {width: 800, height: 600}. Set it to null to avoid Puppeteer applying that default viewport to each page. |
protocolTimeout |
Defaults to 180,000 milliseconds for an individual protocol call. Increase it if a specific protocol operation needs longer; a larger timeout also means waiting longer before that operation fails. |
slowMo |
Delays Puppeteer operations by the specified number of milliseconds. Useful for observing behavior while debugging, not as a general performance setting. |
targetFilter |
A callback that decides which browser targets Puppeteer connects to. |
protocol |
The documented default is CDP for Chrome launch and browser connections; Firefox launch defaults to WebDriver BiDi. Choose a protocol supported by the browser and operation you need. |
capabilities |
Only applicable with protocol: 'webDriverBiDi' and Puppeteer.connect(). |
headers |
Deprecated. In Node.js, use wsOptions.headers instead. If both are supplied, wsOptions.headers takes precedence. |
wsOptions |
Node.js-only WebSocket connection options. Keep-alive options are ignored in browser builds because the browser build lacks the ping-frame API. |
transport |
Lower-level custom ConnectionTransport option for specialized connection arrangements; not the usual endpoint-based setup. |
channel |
Experimental Node.js/Chrome option that looks for an open WebSocket at the well-known user-data location for a Chrome release channel. |
acceptInsecureCerts |
Controls whether HTTPS errors are ignored during navigation; defaults to false. |
handleDevToolsAsPage |
Controls whether DevTools windows are treated as Puppeteer pages; defaults to false. |
networkEnabled |
Experimental. Disabling network event monitoring can break features that depend on HTTPRequest and HTTPResponse events. |
issuesEnabled |
Experimental setting that disables issue-event monitoring by default when configured to do so. |
Default viewport: 800 by 600, or opt out
Unless you specify otherwise, the connection options use an 800-by-600 default viewport. Set defaultViewport: null if Puppeteer should not apply that default to each page. This is distinct from choosing a particular viewport size for a page; set a viewport explicitly when your workflow needs a known screen size.
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 →Protocol choice and capabilities
CDP is the documented default for browser connections. WebDriver BiDi capabilities are not a generic addition to every connection: the reference limits capabilities to a BiDi connection made through Puppeteer.connect(). Browser and protocol support differ, so do not infer Firefox connection behavior from the Firefox launch default.
Experimental network controls are not a sandbox
The experimental allowlist and blocklist are Chrome-only and mutually exclusive. The allowlist requires Chrome 149 or newer and matches URLs with the standard URLPattern API; requests outside its patterns fail. Puppeteer cautions that these controls are an additional guardrail, not complete network isolation. Use separate network-level controls when you need a security boundary.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
How do I pass headers to Puppeteer connect?
For Node.js, put WebSocket handshake headers under wsOptions.headers:
const browser = await puppeteer.connect({
browserWSEndpoint: 'wss://HOST/your-browser-endpoint',
wsOptions: {
headers: {
Authorization: 'Bearer YOUR_TOKEN',
},
},
});headers at the top level is deprecated. If both that field and wsOptions.headers are present, the nested value wins. The WebSocket options are Node.js-only; do not rely on them in browser builds. Keep credentials out of source control and use the authentication format required by the browser host.
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 matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Or skip the browser setup
If your goal is a screenshot rather than controlling a browser session, ScreenshotNeo offers a one-request screenshot API and an MCP server. For example, the following cURL request saves a WebP screenshot:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for API options. ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and the Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Learn about ScreenshotNeo or sign up for 1,000 free screenshots a month, with no card.
Troubleshooting Puppeteer connections
Connection fails or times out
- Check the endpoint: confirm the host and port are reachable from the Node.js process, and use the exact
webSocketDebuggerUrlwhen connecting by WebSocket. - Check endpoint freshness: a browser WebSocket URL can include an instance-specific ID. Retrieve the current value from the running browser rather than reusing an old endpoint.
- Check access requirements: a remote host may require authentication headers or a provider-specific connection URL. Put WebSocket headers in
wsOptions.headersin Node.js. - Separate connection timeouts from protocol timeouts:
protocolTimeoutapplies to individual protocol calls; changing it does not fix an unreachable host or invalid endpoint.
Pages use an unexpected size
Check whether defaultViewport is set. It defaults to 800 by 600; use null to avoid applying the default, or explicitly set the viewport required by your task.
Network-dependent features stop working
If you set experimental networkEnabled to disable network event monitoring, features relying on HTTPRequest or HTTPResponse events may break. Re-enable network monitoring before debugging those behaviors.
Recommended Free Tools
Headers appear to be ignored
Move them from the deprecated top-level headers option to wsOptions.headers, and confirm the code runs in Node.js rather than a browser build.
A URL fails under an allowlist
Allowlist rules are matched as URL patterns, and requests outside the patterns fail. Verify that every required destination matches the configured patterns and that the connected browser is Chrome 149 or newer. Do not treat the allowlist as complete network isolation.
FAQ
Can Puppeteer connect to a browser on another machine?
Yes, if that browser exposes an endpoint reachable from the Puppeteer process and the connection details meet the host’s access requirements. Use the provider’s exact endpoint and secure it appropriately.
Does calling disconnect close the browser?
No. It disconnects Puppeteer from the browser; it does not close the existing browser process.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →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.
