Recommended Free Tools
puppeteer.connect() attaches Puppeteer to a browser that is already running and returns a Browser object. Use browserWSEndpoint when you have the browser’s DevTools WebSocket URL, or browserURL when you have its debugging HTTP address. Unlike launch(), connect() does not start the browser process.
This guide follows the Puppeteer 25.12.0 API reference, checked October 3, 2026. Defaults and experimental options can change; confirm the reference for your installed version.
How to connect Puppeteer to an existing browser
In Node.js, import Puppeteer, supply a connection target, and await the returned Browser. The following example uses a WebSocket endpoint stored in an environment variable so the endpoint is not hard-coded into the script.
-
Start or obtain access to a browser that exposes a DevTools connection. Use the browser host and endpoint supplied by your deployment or browser provider.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows 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 reinstallSpecial offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.#1 Best Overall
Search+ For Google- google search
- google map
- google plus
- youtube music
- youtube
-
Set
PUPPETEER_WS_ENDPOINTto the complete WebSocket URL, such asws://HOST:PORT/devtools/browser/<id>. Use the actual endpoint, not the illustrative host or ID. -
Run this script with Puppeteer installed in the Node.js project:
import puppeteer from 'puppeteer'; const browserWSEndpoint = process.env.PUPPETEER_WS_ENDPOINT; if (!browserWSEndpoint) { throw new Error('Set PUPPETEER_WS_ENDPOINT to the browser WebSocket URL'); } const browser = await puppeteer.connect({ browserWSEndpoint }); try { const page = await browser.newPage(); await page.goto('https://example.com', { waitUntil: 'domcontentloaded' }); console.log(await page.title()); } finally { await browser.disconnect(); }disconnect()ends Puppeteer’s connection without asking it to close the browser process. That distinction matters when the browser is managed separately or shared. Use the appropriate browser-management mechanism if you intend to shut down the process.
The official PuppeteerNode.connect() reference describes the method as attaching Puppeteer to an existing browser instance. It resolves to a Browser.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteUse a debugging HTTP address instead
If your provider gives you the browser’s debugging HTTP address rather than a WebSocket URL, pass it as browserURL:
const browser = await puppeteer.connect({ browserURL: 'http://HOST:PORT' });Replace the example with the exact debugging address documented by the browser host. The API reference lists both target options; the endpoint format and discovery method are described in the Browser.wsEndpoint() reference.
Rank #2
- Google search engine.
Where to get browserWSEndpoint
Ask the browser provider or inspect its debugging endpoint
A connected browser’s browser.wsEndpoint() returns its WebSocket endpoint. The documented shape is ws://HOST:PORT/devtools/browser/<id>. If you can access the browser’s debugging HTTP endpoint, request http://HOST:PORT/json/version and read the webSocketDebuggerUrl field from the response. Use the host, port, scheme, and full path as provided; a page-level WebSocket URL is not interchangeable with the browser-level endpoint.
For remote browsers, the debugging address may be private, authenticated, or exposed through a provider-specific proxy. Follow that provider’s instructions for network access and authentication rather than assuming a local Chrome port is reachable from your Node process.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Connect or launch: which method should you use?
| Question | connect() |
launch() |
|---|---|---|
| What happens? | Attaches to an already-running browser and returns a Browser. |
Starts a browser process under Puppeteer’s control. |
| What must you provide? | A connection target such as browserWSEndpoint or browserURL. |
Launch configuration; launch-specific options extend the shared connection options. |
| Typical fit | A hosted, remote, shared, or separately managed browser. | A browser process that your script should start and manage. |
The current LaunchOptions reference says launch options extend ConnectOptions with launch-specific settings. A connection option such as defaultViewport can therefore matter in both workflows, but only connect() attaches to an existing instance.
ConnectOptions that matter most
The options below reflect Puppeteer’s 25.12.0 reference. An option described as experimental, deprecated, or runtime-specific should not be treated as a stable cross-browser setting.
Connection target: browserWSEndpoint, browserURL, transport, and channel
-
browserWSEndpoint: use the browser’s DevTools WebSocket URL when it is available. It is the direct choice for a known WebSocket endpoint. -
browserURL: use the browser’s debugging HTTP address when that is what your environment provides. Consult the deployment documentation for the exact address.Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.Rank #3
Search+ for Google- Voice search enabled
- Clean and simple to use
- Max speed and compatibility for your Kindle device
-
transport: a lower-levelConnectionTransportoption for custom connection arrangements. It is not the ordinary starting point; the API reference does not prescribe a generic implementation for custom transports. -
channel: experimental and limited by the reference to Chrome in Node.js. It looks for an open WebSocket at the well-known user-data location for a Chrome release channel; it is not a substitute for a provider’s remote endpoint.
Viewport, timing, and target selection
-
defaultViewportdefaults to{ width: 800, height: 600 }. Set it tonullif Puppeteer should not apply that default viewport to each page. -
protocolTimeoutdefaults to180000milliseconds for an individual protocol call. Increase it only when a specific call legitimately needs more time; a longer timeout can also make a stalled operation take longer to fail.Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
slowMoadds the specified delay in milliseconds to Puppeteer operations, which can help when debugging behavior step by step. -
targetFilteris a callback that determines which browser targets Puppeteer connects to. Use it only when you understand which targets your workflow needs.Rank #4
Google Drive- Get access to files anywhere through secure cloud storage and file backup for your photos, videos, files and more with Google Drive.
Protocol selection and capabilities
The current reference documents CDP as the default protocol for Chrome launch and browser connections, and WebDriver BiDi as the default for Firefox launch. The capabilities option applies only when using protocol: 'webDriverBiDi' with Puppeteer.connect(). Check the browser and Puppeteer support for the protocol you select instead of assuming CDP-only features work under BiDi or vice versa.
Headers and WebSocket options
headers is deprecated. In Node.js, pass WebSocket connection headers through wsOptions.headers instead:
const browser = await puppeteer.connect({
browserWSEndpoint: process.env.PUPPETEER_WS_ENDPOINT,
wsOptions: {
headers: {
Authorization: `Bearer ${process.env.BROWSER_TOKEN}`,
},
},
});Do not put secrets directly in source code or logs. If the browser host expects credentials in a different form, use its documented connection method. The API reference specifies that wsOptions is Node.js-only; WebSocket keep-alive settings are ignored in browser builds because those builds lack the ping-frame API. If both deprecated headers and wsOptions.headers are supplied, wsOptions.headers takes precedence.
Experimental network controls and event settings
-
allowlistis experimental, Chrome-only, and requires Chrome 149 or newer. It matches URLs with the standardURLPatternAPI; requests outside configured patterns fail. Puppeteer warns that this is an additional guardrail, not full network isolation. -
blocklistis experimental and Chrome-only. It cannot be used together withallowlist. -
networkEnabledis experimental. Disabling network event monitoring can break features that depend onHTTPRequestandHTTPResponseevents.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 →Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
issuesEnabledis experimental and controls whether issue-event monitoring is enabled by default.
Other behavior options
-
acceptInsecureCertscontrols whether HTTPS errors are ignored during navigation; the documented default isfalse. -
handleDevToolsAsPagecontrols whether DevTools windows are treated as Puppeteer pages; the documented default isfalse.
Common connection problems and fixes
| Symptom | Likely cause | What to check |
|---|---|---|
| Connection fails immediately | The endpoint is mistyped, stale, inaccessible, or not a browser-level DevTools endpoint. | Confirm the full WebSocket URL or debugging HTTP address with the browser host. For a reachable debugging endpoint, inspect /json/version and its webSocketDebuggerUrl. |
| Local connection works but remote connection fails | The Node process cannot reach the remote host or the provider requires a proxy, authentication, or a specific network route. | Check the provider’s endpoint and access requirements, firewall or network policy, and any required Node.js WebSocket headers. |
| Authentication or upgrade is rejected | Credentials may be missing, malformed, or passed through the deprecated option. | For Node.js WebSocket headers, use wsOptions.headers and verify the credential format expected by the browser host. |
| Navigation or protocol calls time out | The browser or page is slow, unreachable, or waiting on work that does not finish within the per-call timeout. | Check browser health and network access first; then consider whether protocolTimeout is appropriate for the affected call. |
| Page dimensions differ from the browser window | Puppeteer applies its default viewport to pages. | Set an explicit defaultViewport, or use null to avoid applying the default viewport. |
| Features stop working after network monitoring is disabled | A feature may rely on request or response events. | Keep networkEnabled enabled when the workflow needs HTTPRequest or HTTPResponse events. |
| A browser option appears ignored | The option may be experimental, browser-specific, Node-only, or unsupported by the selected protocol. | Compare the option’s scope in the 25.12.0 reference with your browser, runtime, and protocol. |
Performance, reliability, and cost considerations
connect() reuses a browser process instead of starting one, which can fit environments that already manage browser lifecycle. It does not by itself guarantee a faster or more reliable workflow: connection latency, browser capacity, page load behavior, endpoint stability, and provider limits remain environment-dependent. The API reference does not establish general performance or cost figures.
For a shared browser, be deliberate about which targets your script can see and what state it changes. Disconnect when the work is complete, and follow the owner’s lifecycle rules so your script does not close or disrupt a browser used by another task.
Or skip the browser setup:
If your goal is a website screenshot rather than browser automation, ScreenshotNeo provides a screenshot API and MCP server. One GET request returns an image or PDF; see the API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes cookie/consent banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and responses include X-Page-Verdict and X-Billed headers. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. Sign up for the free plan.
Frequently asked questions
What is the difference between browserWSEndpoint and browserURL?
browserWSEndpoint takes the browser’s DevTools WebSocket URL; browserURL takes its debugging HTTP address. Choose the one your browser environment exposes.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Can I use Puppeteer connect in a browser build?
Some connection options are runtime-specific. In particular, the reference limits wsOptions to Node.js and says keep-alive settings are ignored in browser builds.
Does connect close the browser when I am done?
Use browser.disconnect() to detach Puppeteer while leaving the independently managed browser running. Browser process shutdown is a separate lifecycle decision.
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.
