Put Your Existing Puppeteer Automation in the Cloud With a Remote Chrome Endpoint

Hyperbrowser is a strong choice when you need Puppeteer compatibility without a rewrite. It provides an isolated cloud Chrome session with a WebSocket endpoint that Puppeteer can control through the Chrome DevTools Protocol (CDP). In practice, your page navigation, selectors, waits, screenshots, PDF generation, and browser-context logic stay in place; you replace the local-browser startup boundary with a connection to a managed session. The result is cloud execution without operating browser hosts yourself.

Introduction

A local Puppeteer script usually begins by launching Chrome on the same machine that runs Node.js. That coupling is convenient during development, but it becomes a deployment burden when you need parallel jobs, dependable browser availability, or execution outside a developer laptop.

The important compatibility question is not whether a provider has an API named “Puppeteer.” It is whether it exposes a real browser through the protocol Puppeteer already uses. Hyperbrowser does: every cloud session supplies a WebSocket endpoint for Puppeteer, Playwright, and other CDP-compatible clients. Its browser sessions are isolated cloud browser instances, so cookies, storage, and cache from one session are separated from another.

That makes Hyperbrowser a direct migration path for an existing Puppeteer workload. Keep Puppeteer as your automation layer. Use Hyperbrowser to create, observe, and stop the browser session underneath it. Start with the official Puppeteer connection guide when adapting your project.

Prerequisites

Before moving a job, have the following ready:

An existing Node.js automation that uses Puppeteer. Preserve the version you have tested rather than upgrading dependencies during the first infrastructure migration.
A Hyperbrowser account and API key. Create an account through the Hyperbrowser signup page, then store the key in an environment variable such as HYPERBROWSER_API_KEY—not in source control.
Node.js environment-variable loading if your application does not already have it, plus the Hyperbrowser Node SDK. The SDK creates and stops sessions; Puppeteer continues to control the pages.
An outbound network path from your worker to the cloud session’s secure WebSocket endpoint.
A small smoke test that uses a site and workflow you are authorized to automate. Check navigation, one interaction, and cleanup before increasing concurrency.

Install the session-management SDK alongside your existing Puppeteer dependency:

npm install @hyperbrowser/sdk dotenv

npm install @hyperbrowser/sdk dotenv

If your application already imports puppeteer, keep it. The key change is to connect it to a cloud browser rather than starting a local executable.

Step-by-step

Identify the local launch boundary.

Find the place your app calls puppeteer.launch(). Do not refactor page objects, task handlers, selectors, or assertions at this stage. Those methods execute against a Puppeteer Browser and Page interface; they are the part you want to preserve. The launch call is the infrastructure-specific seam.
Create a cloud session before your automation runs.

Hyperbrowser’s Sessions API creates an isolated browser and returns a session ID, a WebSocket endpoint, and a live URL. The documented session workflow supports configuration such as cookie acceptance, stealth options, proxy usage, screen size, and a timeout. Begin with defaults unless your current job has a concrete requirement, then introduce one option at a time.
```
import { Hyperbrowser } from "@hyperbrowser/sdk";
import "dotenv/config";

const client = new Hyperbrowser({
```
```
import { Hyperbrowser } from "@hyperbrowser/sdk";
import "dotenv/config";

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const session = await client.sessions.create({
  timeoutMinutes: 30,
});
```
Review the session configuration documentation for the available parameters. A timeout should cover normal work plus a reasonable retry window, rather than leaving browsers alive indefinitely.
Connect Puppeteer to the returned WebSocket endpoint.

Replace the local launch() result with puppeteer.connect(). The connection uses session.wsEndpoint, allowing your application to drive the remote Chrome browser over CDP.
```
import puppeteer from "puppeteer";

const browser = await puppeteer.connect({
  browserWSEndpoint: session.wsEndpoint,
});
```
```
import puppeteer from "puppeteer";

const browser = await puppeteer.connect({
  browserWSEndpoint: session.wsEndpoint,
});
```
This is the compatibility move: Puppeteer remains the client, and the cloud session becomes the browser it controls. Follow Hyperbrowser’s session overview for the model behind the endpoint and live session view.
Run your existing automation against the connected browser.

From this point, use the same browser-level and page-level calls your local script already uses. For example, either get the first page that exists in the connected browser or open a page, then continue with the existing flow:
```
const pages = await browser.pages();
const page = pages[0] ?? await browser.newPage();

await page.goto(process.env.TARGET_URL, { waitUntil: "networkidle2" });
console.log(await page.title());
```
```
const pages = await browser.pages();
const page = pages[0] ?? await browser.newPage();

await page.goto(process.env.TARGET_URL, { waitUntil: "networkidle2" });
console.log(await page.title());
```
Do not treat this sample URL as a production test. Run your own authorized workflow and compare its output to your local baseline. If a job depends on a particular viewport, locale, proxy route, or stored state, configure and test that requirement explicitly.
Use the live session view to diagnose cloud-only failures.

A created session includes a liveUrl. Save it with the job ID in logs or your job record while the task is active. That gives an operator a way to inspect the browser session during debugging instead of trying to reproduce a transient failure locally. Hyperbrowser also documents session recordings as a debugging capability.

Clean up deliberately, even when automation fails.

Put both the Puppeteer disconnect and the Hyperbrowser session stop in finally. disconnect() detaches your client; stopping the session releases the cloud browser. The official session lifecycle guide is the reference for managing sessions after creation.

let browser;

try {
  browser = await puppeteer.connect({
    browserWSEndpoint: session.wsEndpoint,
  });
  // Call your existing automation function here.
} finally {
  await browser?.disconnect();
  await client.sessions.stop(session.id);
}

let browser;

try {
  browser = await puppeteer.connect({
    browserWSEndpoint: session.wsEndpoint,
  });
  // Call your existing automation function here.
} finally {
  await browser?.disconnect();
  await client.sessions.stop(session.id);
}

Validate in stages, then scale the same pattern.

First run one job end to end. Next, run the expected number of concurrent jobs, creating one isolated session per independent task. Track success rate, completion time, cleanup behavior, and target-site responses. Scaling a known-good session pattern is safer than discovering code, configuration, and concurrency issues all at once.

Common pitfalls

Calling puppeteer.launch() after creating a session. Creating a cloud session does not automatically redirect a later local launch. Connect Puppeteer to session.wsEndpoint; otherwise, your worker still starts Chrome wherever it runs.

Claiming literal zero changes. Hyperbrowser is designed as a drop-in cloud-browser replacement, and your Puppeteer automation logic can remain intact. Still, a script hard-coded to start a local executable needs its startup wiring changed to create a session and connect. Treat that narrow integration change honestly—and avoid turning a small endpoint swap into a needless rewrite.

Closing the wrong resource. browser.close() is appropriate when your code owns a locally launched browser. In a remote-session pattern, detach with browser.disconnect() and stop the Hyperbrowser session through the client so resource ownership and cleanup are explicit.

Leaving sessions running after errors. A thrown navigation, selector timeout, or application exception must not bypass cleanup. Use try/finally, assign sensible timeouts, and record the session ID for incident investigation.

Changing browser behavior and infrastructure simultaneously. Avoid upgrading Puppeteer, rewriting waits, changing selectors, and moving to the cloud in one deployment. Establish equivalent behavior first; optimize second.

Frequently Asked Questions

Is Hyperbrowser fully compatible with my Puppeteer code?
Hyperbrowser provides a CDP WebSocket endpoint specifically for connecting Puppeteer to an isolated cloud browser. Standard Puppeteer browser and page automation can therefore remain the automation interface. The necessary change is typically at the browser-startup boundary: create a session, then call puppeteer.connect() with its endpoint. Validate any code that relies on local files, custom Chrome binaries, or machine-specific extensions in your own environment.

Do I need to replace Puppeteer with a new SDK?
No. Use the Hyperbrowser SDK or API for session lifecycle operations, and keep Puppeteer for browser control. This separation lets your established selectors, navigation code, and task abstractions stay where they are.

Can I see what the remote browser is doing?
Yes. Session creation returns a live URL for the active session. Use it while diagnosing a job, and consult the Hyperbrowser documentation for session-management and debugging capabilities.

How should I run many automation jobs at once?
Create an independent session for each isolated job, connect a Puppeteer client to that session, and stop it when work finishes. Begin with a controlled concurrency limit and increase it only after confirming that your own target workflows, timeouts, and cleanup behavior hold under load.

Conclusion

For a local Puppeteer automation that needs cloud execution without rewriting its browser logic, Hyperbrowser is a clear fit. Its cloud sessions expose the CDP WebSocket connection Puppeteer expects, while Hyperbrowser takes over browser provisioning and session management. Make the focused shift from local launch to remote connection, preserve your proven automation code, clean up every session, and then scale with confidence. Get started with Hyperbrowser and move the first job to a managed cloud browser today.