Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsTo use Puppeteer with a cloud browser, keep Puppeteer in your application and connect it to a remote Chromium instance with puppeteer.connect() instead of starting a local browser with puppeteer.launch(). For Browserless, install puppeteer-core, use a secure wss:// endpoint, and pass your token in the connection URL. Your page-level code—navigation, selectors, waits, evaluation, PDFs, and screenshots—can generally stay the same, according to Browserless documentation.
What changes when Puppeteer runs in the cloud?
Puppeteer remains the automation client: your Node.js code still creates pages and controls them through the Puppeteer API. The browser process, however, runs on a managed provider or on infrastructure your organization hosts. Your application connects to that browser over a WebSocket.
The main code change is the browser connection. Local automation commonly starts a browser with puppeteer.launch(). With a remote browser, use puppeteer.connect({ browserWSEndpoint }) instead. Browserless describes this as running existing automation code by changing the connection URL. That generally preserves page-level operations, but it does not make the remote browser share your application machine’s filesystem, environment, or network location.
Install the remote-browser client
When a provider supplies Chromium, install puppeteer-core rather than the full puppeteer package. Browserless explains that the full package downloads a Chromium binary during installation, which is unnecessary when your code will connect to a browser elsewhere. The packages expose the same Puppeteer API for connect().
Recommended Free Tools
#1 Best Overall
npm install puppeteer-coreSet the Browserless token as an environment variable instead of writing it into source code. In a local shell, for example:
export BROWSERLESS_TOKEN='your-token'In a deployed application, configure the equivalent variable through your hosting platform’s secret manager. The example below uses Browserless’s documented US West endpoint. Choose the endpoint provided for your account and intended region.
Connect Puppeteer to Browserless
This ES module example connects, opens a page, navigates to a site, prints its title, and closes the remote session even if navigation or evaluation fails.
import puppeteer from "puppeteer-core";
const TOKEN = process.env.BROWSERLESS_TOKEN;
if (!TOKEN) {
throw new Error("Set BROWSERLESS_TOKEN before running this script");
}
const browser = await puppeteer.connect({
browserWSEndpoint: `wss://production-sfo.browserless.io?token=${TOKEN}`,
});
try {
const page = await browser.newPage();
await page.goto("https://example.com", { waitUntil: "networkidle2" });
console.log(await page.title());
} finally {
await browser.close();
}Save it as capture.mjs and run node capture.mjs after setting the environment variable. The endpoint must use wss:// for the secure WebSocket connection; the token is passed as a query parameter. Keep that URL private because it contains a credential.
Use the right close behavior
For a normal completed job, call browser.close() in a finally block. Browserless documents that this ends the remote session, rather than merely stopping a local process. If cleanup is omitted, a session may remain open until it times out and may continue to incur charges under the provider’s billing model. Do not close the shared browser after every page if one job deliberately uses several pages; close it when that job is finished.
Move the right work to the remote browser
Pages, navigation, and rendering
Once connected, use Puppeteer’s page methods as you would in local automation: open pages, navigate, wait for selectors, evaluate page scripts, generate PDFs, or take screenshots. A remote browser can take longer to respond because browser commands cross a network connection. Choose waits based on what the page needs rather than assuming that a local timing will be reliable remotely. For example, use a selector wait when a particular element signals readiness; use networkidle2 only when the page’s network behavior makes that condition appropriate.
Cloud execution does not remove site-side variability. A target can load slowly, require authentication, block automated traffic, or render differently for the remote browser. Make navigation and readiness logic tolerant of timeouts, and decide explicitly whether a failed page should be retried, recorded as an error, or treated as an expected result.
Downloads, uploads, and local files
A path such as /tmp/report.pdf refers to the machine running your application, not automatically to the cloud browser’s filesystem. Likewise, an input file available locally is not automatically visible to a remote Chromium process. Browserless notes that file movement requires the provider’s transfer APIs or an explicit data channel. Design file transfer as a separate part of the workflow instead of assuming local paths work unchanged.
Browser environment and reproducibility
The remote browser has its own viewport, user agent, timezone, and locale. Those values may differ from a developer’s laptop and can affect responsive layouts, date formatting, language selection, and site behavior. When repeatability matters, set the relevant browser or page settings explicitly and record them alongside the result. Also account for the browser version supplied by the service or selected for a self-hosted deployment; a browser update can affect rendering or automation behavior.
Choose managed or self-hosted infrastructure
| Approach | Best fit | What you operate |
|---|---|---|
| Managed browser service | Run existing Puppeteer jobs remotely with less infrastructure work. | Your application, token handling, job logic, and provider-specific limits. The provider supplies the browser and regional endpoints. |
| Self-hosted Docker or private fleet | Organizations that need infrastructure control, private networking, custom capacity, or their own queue and timeout policies. | Browser deployment, authentication, scaling, concurrency and queue settings, timeouts, browser image updates, and operational monitoring. |
| REST or BrowserQL task API | One-off screenshots, PDFs, scraping, or content extraction when a persistent Puppeteer client is not required. | The request workflow and API integration, rather than a full Puppeteer-controlled browser session. |
Browserless documents a Chromium Docker image and controls for WebSocket access, token authentication, concurrency, queues, timeouts, proxy arguments, and versioned image tags. These options provide operational control, but also make browser capacity and service health your responsibility. A managed service reduces that infrastructure burden while making you dependent on its endpoint, account limits, and session behavior.
Before selecting an approach, compare the amount of browser-level control your code needs, who will maintain the browser fleet, where the browser should run, how many sessions can run at once, whether login state must persist, how files move, and the total cost for the expected session duration. Do not estimate cost from request count alone: a session that remains connected can consume time or capacity even when it is not actively navigating.
Plan for latency and parallel jobs
Put the browser near the target when possible
Browserless lists regional fleets including US West, London, and Amsterdam, and recommends choosing a region near the target sites. The important path for page loading is from the browser to the website; the developer-to-control connection is not the only relevant network distance. A browser close to your application may still be far from the websites it visits. For workflows that touch several regions, measure the behavior that matters to your task instead of assuming one region is best for every destination.
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 →Use one session per independent job
For separate jobs running in parallel, create separate puppeteer.connect() sessions. Within a single job, reuse one connected browser object to create multiple pages when that suits the workflow. This avoids treating every page in one task as an unrelated remote session while keeping independent tasks isolated.
Parallelism must fit the provider’s concurrency allowance or, for a self-hosted fleet, the capacity and queue settings you configured. If work is submitted faster than available sessions can run, queue it deliberately or limit concurrency in the application. A queue does not increase browser capacity; it makes overload more controlled and predictable.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Keep login state between runs
By default, do not assume that a new cloud-browser connection starts with the cookies or web storage from a previous run. Browserless Authenticated Profiles can capture cookies, localStorage, and IndexedDB from a login session. A later Puppeteer connection can pass a profile=<name> parameter so the browser starts with that saved state.
For login flows protected by a CAPTCHA or two-factor authentication, Browserless documentation also describes handing a live session to a human before saving the profile. This can help with a legitimate account setup, but it does not mean automation should attempt to bypass a site’s access controls. Treat a saved profile as a credential: restrict who can use it, keep it out of source control and logs, and follow the account owner’s security rules.
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 reinstallSecure the connection and your deployment
- Protect tokens: inject them from an environment variable or secret manager, do not commit them, and avoid logging the complete WebSocket URL.
- Authenticate self-hosted endpoints: Browserless’s Docker documentation warns that leaving
TOKENunset leaves endpoints unauthenticated, including code-execution routes. - Keep the transport secure: use the provider’s
wss://endpoint, not an unencrypted WebSocket URL. - Limit access: expose only the network paths required by the application and configure a token when the deployment supports it.
- Separate user data: do not reuse login profiles or cookies across unrelated users or jobs unless that sharing is intentional and authorized.
Troubleshoot common connection and run failures
| Symptom | Likely cause | What to check or change |
|---|---|---|
| WebSocket connection fails immediately | Wrong endpoint, missing token, malformed URL, or blocked network connection. | Check the account’s exact endpoint, confirm the token is set, retain the wss:// scheme, and verify that the application can make outbound WebSocket connections. |
| Authentication or authorization is rejected | The token may be absent, invalid, expired, or for a different service or account. | Read the response/error details without printing the secret; replace the configured token with the current account credential and verify the endpoint. |
| Script hangs or runs longer than expected | A page wait condition may never occur, or the remote session may not be cleaned up. | Use a readiness condition tied to the page, handle navigation timeouts, and put browser.close() in finally. Review provider timeout settings if you self-host. |
| Parallel work is delayed or rejected | The account’s concurrency limit or self-hosted queue capacity has been reached. | Reduce application concurrency, queue jobs, or configure capacity consistent with your workload and service limits. |
| A downloaded or uploaded file is missing | The code assumes the application and remote browser share a filesystem. | Use the provider’s file-transfer mechanism or an explicit data channel, and verify which side owns each path. |
| Page layout or content differs from local runs | Viewport, user agent, timezone, locale, browser version, or network location differs. | Set relevant environment values explicitly and compare the target behavior from the remote browser’s region. |
| A later run appears logged out | The session did not load the required cookies or stored browser data. | Use an authenticated profile where appropriate, confirm the profile name is passed, and verify that its login state remains valid. |
Or skip the browser setup
If the job is to get a screenshot or PDF rather than control a full Puppeteer session, ScreenshotNeo offers a direct screenshot API. One GET request returns an image or PDF; use it when browser setup and page-level interaction are unnecessary. It is not a drop-in replacement for arbitrary Puppeteer logic.
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 banners, popups, and chat widgets are removed before the shot; 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. Sign up for free.
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.
