To attach Puppeteer to a browser that is already running, call puppeteer.connect() with its complete debugger WebSocket URL in browserWSEndpoint. In Node.js, put WebSocket connection headers under wsOptions.headers; use options such as protocolTimeout to configure Puppeteer’s protocol behavior, not the WebSocket handshake. When finished, call browser.disconnect() to detach without shutting down the browser, or browser.close() to close it.
What Puppeteer’s connection options control
connect() attaches Puppeteer to an existing browser and resolves to a Browser instance; it does not launch a browser. The options are defined by Puppeteer’s ConnectOptions reference (version 25.12.0).
- Identify the browser: provide an endpoint or other locator for the existing browser. When you have its full debugger WebSocket URL, use
browserWSEndpoint. - Configure the connection and Puppeteer session: use
wsOptionsfor Node.js WebSocket settings such as headers. Other connection options govern protocol behavior, target selection, and page defaults. - Choose how to finish: disconnect the Puppeteer client to leave the browser running, or close the browser when it should shut down.
Connect with a WebSocket endpoint
Supply the complete browser debugger WebSocket URL as browserWSEndpoint. This example assumes you have already obtained a valid endpoint for the browser you intend to control:
const browser = await puppeteer.connect({
browserWSEndpoint: 'ws://127.0.0.1:9222/devtools/browser/your-id',
});
const page = await browser.newPage();
await page.goto('https://example.com');
// Detach Puppeteer while leaving the browser running.
browser.disconnect();Replace the example path with the actual endpoint; it is not a literal path to copy. The documentation’s browser-management guide demonstrates connecting with browserWSEndpoint and creating a page: Browser management.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problems#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
Find Chrome’s debugger WebSocket URL
For a browser started by Puppeteer, call browser.wsEndpoint() to get the URL typically passed to connect(). The API reference also documents discovering Chrome’s webSocketDebuggerUrl at http://HOST:PORT/json/version; the documented endpoint form is ws://HOST:PORT/devtools/browser/<id>. See Browser.wsEndpoint().
const endpoint = browser.wsEndpoint();
// Save endpoint before disconnecting if you plan to reconnect.
browser.disconnect();
const reconnected = await puppeteer.connect({
browserWSEndpoint: endpoint,
});Make sure the URL is the browser-level debugger endpoint, not a page target’s WebSocket URL. If the endpoint is stale, unreachable, or belongs to a different browser, the connection cannot attach to the intended browser.
browserURL or browserWSEndpoint?
The 25.12.0 generated options table lists both browserURL and browserWSEndpoint, but does not describe their semantics. Use browserWSEndpoint when you already have the full debugger WebSocket URL. Do not infer a URL path, discovery behavior, or precedence rule for browserURL from that table alone; consult documentation specific to your Puppeteer version and setup before choosing it.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
Pass WebSocket headers in Node.js
For Node.js, current WebSocket configuration belongs in wsOptions. Add authentication headers there only when the browser endpoint’s operator specifies that header and credential format:
Recommended Free Tools
const browser = await puppeteer.connect({
browserWSEndpoint: endpoint,
wsOptions: {
headers: {
Authorization: `Bearer ${token}`,
},
},
});This shows the option shape, not a universal authentication scheme. Remote-browser services can specify different endpoint and authentication conventions; follow the instructions for the service you use. The top-level headers option is deprecated; if both it and wsOptions.headers are supplied, wsOptions.headers takes precedence. wsOptions is Node-only. The reference also notes that browser builds have no ping-frame API, so keep-alive options are ignored there. See ConnectOptions.
Choose protocol and session behavior
These options affect Puppeteer’s connection or behavior after attachment; they do not replace the browser endpoint.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
| Option | What it controls | Important qualification |
|---|---|---|
protocol |
Selects the protocol Puppeteer uses. | The documented runtime default for a browser connection is CDP. Chrome launch defaults to CDP; Firefox launch defaults to WebDriver BiDi. These launch defaults do not establish the protocol of every remote browser. |
capabilities |
Capabilities for a WebDriver BiDi connection. | Documented for protocol: "webDriverBiDi" with Puppeteer.connect(). |
protocolTimeout |
Timeout, in milliseconds, for individual CDP calls. | Documented default: 180_000 ms. This is not documented as the WebSocket handshake timeout. |
defaultViewport |
Viewport applied to each page. | Documented default: {width: 800, height: 600}. |
targetFilter |
Callback that decides which targets Puppeteer connects to. | Use it to control target selection, not to discover or authenticate the browser endpoint. |
slowMo |
Delay, in milliseconds, between Puppeteer operations. | Useful for debugging; it deliberately slows automation. |
networkEnabled |
Controls network event monitoring. | Experimental. Setting it to false disables monitoring and breaks features that rely on network events, including HTTPRequest and HTTPResponse. |
allowlist / blocklist |
Experimental URLPattern-based controls for navigation and requests. | Documented as Chrome-only for Chrome 149 or later. Existing targets that violate the rules may be detached, and disallowed requests fail. Puppeteer warns these controls are not complete network sandboxing; use container- or OS-level sandboxing when that stronger boundary is required. |
channel |
Looks for an open Chrome WebSocket in a known user-data directory and connects to its active port. | Experimental; the reference limits it to Chrome in Node.js. It is not a general remote-provider endpoint convention. |
Browser build, Node.js, and transport boundaries
Puppeteer’s browser build can connect over WebSockets to an existing browser, but it cannot launch or download browsers because those operations require Node.js APIs. Its guide uses the browser-specific puppeteer-core entry point and browserWSEndpoint: Running Puppeteer in the browser.
A Chrome pipe is a launch-time transport option in LaunchOptions, not an endpoint to pass to connect() for an already-running browser. See LaunchOptions.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Disconnect from the browser or shut it down
Use browser.disconnect() when the automation client should detach but the browser and its pages should remain alive. Puppeteer’s Browser management guide states: “Unlike browser.close(), browser.disconnect() does not shut down the browser or close any pages.”
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
Use browser.close() when Puppeteer should gracefully close the browser. If you need to reconnect later, save browser.wsEndpoint() before disconnecting, then pass it back as browserWSEndpoint.
Troubleshoot connection failures
- Connection is refused or times out: verify that the browser is still running, the host and port are reachable from the Node.js process, and the endpoint belongs to that browser. A debugger URL discovered at
/json/versionis one documented way to obtain Chrome’s WebSocket URL. - Authentication or upgrade failure: check the remote service’s current endpoint and credential instructions. In Node.js, place required WebSocket headers in
wsOptions.headers; Puppeteer’s generic API reference does not define a universal provider token scheme. - Connected to the wrong target or no expected pages appear: confirm that you supplied the browser-level endpoint and review whether a
targetFilteris excluding targets. - An operation times out after connecting:
protocolTimeoutgoverns individual CDP calls, not the initial WebSocket handshake. Diagnose the specific slow or stalled protocol operation before changing it. - Network request/response events are missing: check whether experimental
networkEnabledwas set tofalse; that disables network monitoring and dependent request/response features. - Keep-alive configuration has no effect in a browser build: the browser build lacks the ping-frame API noted in the reference, and WebSocket keep-alive options are ignored there.
Or skip the browser setup
If your goal is to get a website screenshot rather than attach Puppeteer to a browser, ScreenshotNeo provides a screenshot API and MCP server. A single GET request returns an image or PDF, without setting up a browser endpoint yourself. For API options and response details, see the ScreenshotNeo documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. See ScreenshotNeo.
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 & 11Sign up for ScreenshotNeo’s free plan and get 1,000 screenshots a month with no card.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Frequently Asked Questions
Can a web page use Puppeteer to connect to a remote browser?
Yes. Puppeteer’s browser build can connect over WebSockets to an existing browser, but it cannot launch or download browsers. The browser guide shows the browser-specific puppeteer-core entry point.
Does Puppeteer’s generic API specify cloud-browser authentication headers?
No. It documents where Node.js WebSocket headers go, but not provider-specific endpoint formats or credentials. Use the current instructions from the browser service you connect to.
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.
Free tools Windows power users keep installed
One-click scans. No signup required.
