Recommended Free Tools
Use puppeteer.connect() to attach Puppeteer to a Chrome instance that is already running and exposes a remote debugging endpoint. Pass its browser WebSocket endpoint as browserWSEndpoint, or provide a browserURL for endpoint discovery. To leave Chrome open when you finish, call browser.disconnect(); browser.close() shuts it down.
Connect to a browser Puppeteer launched earlier
If Puppeteer started the browser, save the endpoint from browser.wsEndpoint() before disconnecting. You can then attach again to that same still-running browser:
As an Amazon Associate I earn from qualifying purchases.
const puppeteer = require('puppeteer');
async function main() {
const launched = await puppeteer.launch();
const browserWSEndpoint = launched.wsEndpoint();
await launched.disconnect();
const browser = await puppeteer.connect({ browserWSEndpoint });
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.disconnect();
}
main().catch(error => {
console.error(error);
process.exitCode = 1;
});The endpoint identifies the browser-level DevTools connection, typically in the form ws://HOST:PORT/devtools/browser/<id>. Use the value returned by Puppeteer rather than constructing the URL yourself.
Connect to Chrome started outside Puppeteer
Chrome must be running with remote debugging enabled. For a local development session, start Chrome with a debugging port and, preferably, a dedicated profile. Example launch arguments on desktop systems:
#1 Best Overall
chrome --remote-debugging-port=9222 --user-data-dir=/tmp/puppeteer-profileThe executable name and command-line invocation vary by operating system and installation. Do not use a profile containing sensitive personal data unless the debugging endpoint is tightly controlled.
Discover the WebSocket endpoint
For a browser listening on port 9222, request http://127.0.0.1:9222/json/version. The returned JSON includes webSocketDebuggerUrl. Pass that complete value to browserWSEndpoint:
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
const puppeteer = require('puppeteer');
async function main() {
const response = await fetch('http://127.0.0.1:9222/json/version');
if (!response.ok) {
throw new Error(`Chrome endpoint lookup failed: HTTP ${response.status}`);
}
const info = await response.json();
if (!info.webSocketDebuggerUrl) {
throw new Error('Chrome did not return webSocketDebuggerUrl');
}
const browser = await puppeteer.connect({
browserWSEndpoint: info.webSocketDebuggerUrl,
});
const pages = await browser.pages();
const page = pages[0] || await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.disconnect();
}
main().catch(error => {
console.error(error);
process.exitCode = 1;
});This example uses the built-in fetch available in current Node.js releases. On older Node.js versions without global fetch, use a compatible HTTP client or obtain the WebSocket endpoint by another means.
Use browserURL for discovery
Puppeteer’s connection options also support browserURL. Give it the HTTP origin and debugging port, rather than a page URL:
Rank #3
const browser = await puppeteer.connect({
browserURL: 'http://127.0.0.1:9222',
});Alternatively, provide the full webSocketDebuggerUrl as browserWSEndpoint. Do not pass a page-specific target WebSocket URL where a browser endpoint is expected.
Chrome choosing a port automatically
Chrome can be started with --remote-debugging-port=0 to choose an available port. In that mode, Chrome writes the selected port and related endpoint information to a DevToolsActivePort file in the browser profile directory. Read the file from the profile Chrome actually launched with; a different profile will not identify that browser’s endpoint. See the Chrome DevTools Protocol documentation for protocol details.
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
Choose between disconnecting and closing
| Call | Effect | Use it when |
|---|---|---|
await browser.disconnect() |
Detaches this Puppeteer client; Chrome and its pages remain open. | A person or another automation step should keep using the browser. |
await browser.close() |
Closes the browser. | This automation owns the browser and should shut it down. |
The distinction is documented in the Puppeteer browser management guide. Connecting does not transfer exclusive ownership of the browser: other clients or a person may also be interacting with it.
Protect the session you attach to
An attached browser may contain signed-in accounts, cookies, and other active session data. Chrome warns that a connected agent inherits access to this data in its remote debugging guidance. Treat the debugging endpoint like a credential:
- Keep the debugging port bound to a trusted local environment where practical; do not expose it to an untrusted network.
- Use a dedicated browser profile for automation instead of a personal profile.
- Restrict which processes and users can reach the browser endpoint.
- Disconnect clients when they no longer need access, and close the browser when the session should end.
Troubleshoot connection failures
- Connection refused or timeout: Chrome may not be running, remote debugging may not be enabled, or the host and port may be wrong. Confirm the browser is listening and request
/json/versionfrom the same machine or reachable host. - Missing or invalid WebSocket endpoint: Check that you copied the complete
webSocketDebuggerUrlfrom the JSON response, or saved the exact value frombrowser.wsEndpoint(). Avoid substituting a page target URL. - Browser closes after disconnect: Check that the code calls
disconnect()rather thanclose(). Also verify that some other process or browser policy is not shutting Chrome down. - Cannot find
DevToolsActivePort: Verify Chrome used--remote-debugging-port=0and that you are checking the profile directory for that launched process. With a fixed port, query/json/versioninstead. - Unexpected login state or page: The connection attaches to the browser instance and its existing pages/profile, not a fresh isolated session. Inspect
await browser.pages()and choose or create the intended page. - Remote connection fails: Check network reachability, firewall rules, and whether the endpoint is restricted to loopback. Do not solve this by making a sensitive debugging port publicly accessible.
Or skip the browser setup
If you need an image or PDF of a page rather than control of an existing interactive Chrome session, ScreenshotNeo provides a screenshot API and MCP server. A single GET request can return a screenshot or PDF:
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 parameters and response details. ScreenshotNeo removes supported cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its MCP server lets AI agents use screenshot tools. The Free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 screenshots.
Sign up for ScreenshotNeo free: 1,000 screenshots a month, no card required.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Frequently Asked Questions
Can I attach Puppeteer to a browser I did not launch with Puppeteer?
Yes. The browser must expose a supported remote debugging endpoint; connect with its browser WebSocket endpoint or use the browser URL for discovery.
Does disconnecting Puppeteer log me out of Chrome?
No. Disconnecting detaches Puppeteer and leaves the browser session open; it does not itself close the browser or its pages.
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.
