How to Connect Playwright or Puppeteer to a Hyperbrowser Cloud Chrome Session

Hyperbrowser hosts Chrome sessions in the cloud and exposes them through an API, so you connect Playwright or Puppeteer the same way you would connect to any remote browser: create a session, get its connection endpoint, and point your existing automation library at it instead of launching a local browser. This works for teams that already have Playwright or Puppeteer scripts and want managed browsers, saved logins between runs, and live session inspection without changing their automation code.

What Hyperbrowser provides for the connection

Hyperbrowser describes itself as a gateway for AI agents to the internet, offering cloud Chrome sessions, isolated sandboxes, and web data APIs. The relevant capabilities for this task:

The site also cites 100M+ sessions run and 1,000+ concurrent isolated browsers, which matters if you plan to scale parallel runs.

Prerequisites

• A Hyperbrowser account and API key. The pricing page lists a free tier: $0 to start with 5,000 credits included.
• A working Playwright or Puppeteer script that currently launches a local browser.
• Node.js or Python, depending on which SDK you use.

General connection pattern

The exact method names come from the Hyperbrowser SDK documentation; the site shows SDK usage in its examples (for instance, client.sandboxes.create(...) and client.web.fetch(...)). The connection flow follows the standard remote-browser pattern:

1. Create a session through the Hyperbrowser API or SDK. The response includes a connection endpoint (typically a WebSocket URL) for that session.
2. Replace the local launch call in your script with a connect call that uses that endpoint. In Playwright this is chromium.connectOverCDP(...) or chromium.connect(...); in Puppeteer it is puppeteer.connect({ browserWSEndpoint: ... }).
3. Run your existing automation against the returned browser object. Your page interactions, selectors, and assertions stay the same.
4. Close the session when done so the browser is released.

Expected result: your script runs against a cloud-hosted Chrome instance, and you can watch the session live from the Hyperbrowser dashboard.

Playwright sketch

// Pseudocode: confirm exact SDK method names in Hyperbrowser docs
const session = await hyperbrowser.sessions.create(); // returns a connection URL
const browser = await chromium.connectOverCDP(session.wsEndpoint);
const page = await browser.newPage();
await page.goto("https://example.com");
// ...your existing automation...
await browser.close();

Puppeteer sketch

const session = await hyperbrowser.sessions.create();
const browser = await puppeteer.connect({ browserWSEndpoint: session.wsEndpoint });
const page = await browser.newPage();
await page.goto("https://example.com");
await browser.close();

Treat the method names above as placeholders. The site confirms Playwright and Puppeteer connectivity but does not publish the exact session-creation signature in the material available here, so check the SDK reference before running.

Persisting logins between runs

By default, a new session starts clean. To keep cookies and logins, use saved browser profiles: create or attach a profile to the session so state carries over to later runs. This is the main reason to use a managed browser instead of a fresh local instance for recurring tasks like checking a dashboard behind a login.

Practical pattern:

• First run: log in manually or via script, then let the profile save.
• Later runs: attach the same profile and skip the login step.
• Keep separate profiles per account or environment to avoid state collisions.

Debugging a run

Two features help when a script fails in the cloud but worked locally:

• Live inspection: watch the session in real time to see what the page actually shows.
• Session recordings: replay a finished run to find the step where it diverged.

For flaky selectors or timing issues, replay is usually faster than adding logging and re-running.

Common snags

• Connecting instead of launching: if your script still calls chromium.launch() or puppeteer.launch(), it runs locally and never touches Hyperbrowser. Swap in the connect call.
• Closing too early: closing the browser object ends the session; make sure all async work finishes first.
• Assuming state persists: without a saved profile, each session starts fresh, so logins won't carry over.
• Endpoint format: Playwright's CDP connect and Puppeteer's WebSocket connect expect different endpoint styles; use the one your library documents.

When this setup fits

Choose the cloud-session approach when you need parallel isolated browsers, persistent logins, or replayable debugging for agent-driven automation. If you only run a single short script occasionally on your own machine, a local browser is simpler and avoids the session-management step.