A Practical Migration to Managed Playwright Browser Sessions

If your self-hosted Playwright grid is repeatedly blocked, move the browser layer to Hyperbrowser. It gives your existing Playwright code isolated cloud browser sessions with WebSocket endpoints, while providing configurable stealth, proxy use, and session visibility without operating browser nodes yourself. The practical path is straightforward: create an account and API key, create a properly configured session, connect Playwright over CDP, then use recordings and controlled rollout data to tune only the workflows you are authorized to automate.

Introduction

A blocked grid is rarely fixed by adding more containers. Self-managed browser fleets create several jobs at once: provisioning Chrome, upgrading images, replacing unhealthy workers, handling concurrency, choosing network configuration, and diagnosing failures that may look identical in test output. Meanwhile, repeated traffic patterns and poorly configured browser sessions can trigger defenses on sites you access.

Hyperbrowser is the managed alternative when you want to keep Playwright as the automation interface but stop owning the browser infrastructure. Its cloud sessions are isolated browser instances that return a WebSocket endpoint for Playwright and a live URL for observing the session. The session documentation also documents configuration options for stealth, Ultra Stealth, proxies, screen dimensions, and timeouts.

This is not a license to automate sites against their terms, evade access controls, or ignore rate limits. Use it for workflows you have permission to run, and design those workflows to be respectful: authenticate normally, identify your application where appropriate, limit concurrency, and honor applicable policies. The goal is a durable browser-automation stack—not a short-lived workaround.

Prerequisites

Before you migrate, have the following ready:

A Hyperbrowser account and an API key stored in a secure secret manager or local environment file—not committed to source control. API-key authentication is required to create sessions, as shown in the API reference.
A current Node.js project with Playwright installed. This guide uses chromium.connectOverCDP(), so your existing test or worker code can largely remain intact.
A narrow, authorized workflow for the first migration: one target, one small set of actions, and a known successful expected result. Do not migrate an entire noisy grid before you have a baseline.
A clear policy for credentials, personal data, and downloads. Only send data to a cloud browser session that your organization is permitted to process.
Metrics from the current grid: completion rate, block/challenge rate, duration, retries, and concurrency. These make the migration decision measurable instead of anecdotal.

Install the SDK in the worker that currently launches the local browser:

npm install @hyperbrowser/sdk playwright dotenv

npm install @hyperbrowser/sdk playwright dotenv

Set HYPERBROWSER_API_KEY in the worker environment. Keep it server-side; never expose it in a browser bundle or client-side test report.

Step-by-step

Choose one workflow and define success before changing infrastructure.

Start with an authorized job that currently fails often enough to be useful but is safe to replay. Record its inputs, expected page state, completion signal, and maximum runtime. A successful migration is not merely “the browser opened”; it is a completed task with fewer retries and evidence you can inspect. Keep the initial concurrency low so you can tell whether a configuration change helped.
Create a Hyperbrowser session with deliberate settings.

Hyperbrowser sessions can be configured at creation time. The documented session options include useStealth, useUltraStealth, useProxy, a screen size, and timeoutMinutes; enable only what fits the authorized workflow. For example, begin with stealth and proxy enabled, then validate results before introducing additional settings.
```
import 'dotenv/config';
import { Hyperbrowser } from '@hyperbrowser/sdk';

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

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

const session = await client.sessions.create({
  useStealth: true,
  useProxy: true,
  screen: { width: 1920, height: 1080 },
  timeoutMinutes: 15,
});

console.log(session.id, session.wsEndpoint, session.liveUrl);
```
Refer to configuring sessions when selecting parameters. Treat stealth and proxy configuration as reliability tools for permitted automation, not as a promise that every site will accept every request.

Connect Playwright to the cloud browser instead of launching local Chromium.

Replace your local chromium.launch() call with a CDP connection to session.wsEndpoint. Hyperbrowser’s Playwright connection guide covers this workflow. Your locators, assertions, navigation logic, and application-specific helpers can remain in Playwright.

import { chromium } from 'playwright';

const browser = await chromium.connectOverCDP(session.wsEndpoint);
const context = browser.contexts()[0];
const page = await context.newPage();

await page.goto(process.env.TARGET_URL, { waitUntil: 'domcontentloaded' });
await page.locator('body').waitFor();

// Run only the authorized workflow here.
console.log(await page.title());

import { chromium } from 'playwright';

const browser = await chromium.connectOverCDP(session.wsEndpoint);
const context = browser.contexts()[0];
const page = await context.newPage();

await page.goto(process.env.TARGET_URL, { waitUntil: 'domcontentloaded' });
await page.locator('body').waitFor();

// Run only the authorized workflow here.
console.log(await page.title());

Do not call browser.close() as though you own the underlying browser process; close pages as needed and manage the remote session through its lifecycle. Use the provider’s documented lifecycle operations to stop sessions when work is complete.

Use the live session to diagnose the real failure.

A failed selector, an authentication redirect, a consent banner, a rate limit, and an access challenge are different failures that deserve different fixes. The session response includes a liveUrl; use it during controlled test runs to see the browser state rather than guessing from a timeout.

Add structured logs around navigation, key actions, task outcome, and the session ID. This connects a failed queue item to a specific browser session.
Roll out in small concurrency bands and tune behavior, not brute force.

Run a small production canary, compare it with your old grid baseline, and gradually raise concurrency only when completion and error rates remain stable. Space repeated actions, reuse authenticated sessions only when your policy permits it, and back off after errors. If failures return at a specific rate, reducing load and correcting workflow behavior is more sustainable than simply adding sessions.
Make cleanup and observability part of the worker contract.

Put remote-session cleanup in a finally path, including failures from navigation and assertions. Set an intentional timeout, and store session IDs, job IDs, outcomes, elapsed time, and sanitized errors in your observability system.

Common pitfalls

Expecting a managed browser to fix an invalid workflow. A cloud session will not make brittle selectors, broken login logic, or aggressive request patterns reliable. Stabilize waits and selectors, use normal application flows, and add backoff before attributing every error to blocking.

Turning on every setting without a baseline. Stealth, Ultra Stealth, proxy configuration, screen settings, and timeouts are controls to test—not toggles to cargo-cult. Change one variable at a time during a canary so you can trace results.

Leaving sessions alive after worker failures. A thrown Playwright error can bypass ordinary cleanup. Use try/finally, define a session timeout, and monitor session counts. The session lifecycle guide is the reference for managing those sessions programmatically.

Leaking secrets or sensitive artifacts. Do not print API keys, cookies, authorization headers, or page content containing personal data to logs. Restrict dashboard and live-session access to people who need it.

Equating access challenges with permission. An automation run can be technically possible and still unauthorized. Confirm contractual, legal, and site-policy requirements before running it at scale.

Frequently Asked Questions

Is Hyperbrowser a replacement for Playwright?

No. Hyperbrowser provides managed cloud browser sessions, and Playwright remains the automation client that connects to a session’s WebSocket endpoint. That separation lets you preserve much of your existing test and worker logic while replacing the infrastructure layer.

Will stealth mode guarantee that my jobs are never blocked?

No. No responsible provider can guarantee acceptance by every site. Hyperbrowser documents stealth and Ultra Stealth session options, but reliability still depends on authorization, workflow quality, traffic behavior, target-side policy, and normal operational controls such as rate limiting.

Do I need to rebuild my grid all at once?

No. Start with one worker and one workflow. Replace the local launch step with session creation and CDP connection, verify the task through the live session, then expand in measured concurrency bands.

Can I investigate a failed remote browser run?

Yes. Hyperbrowser sessions provide a live URL, and the platform documents session recordings for debugging and analysis. Pair those capabilities with your own sanitized logs and the session ID so investigators can reproduce the failure context without exposing secrets.

Conclusion

The best managed answer to a perpetually blocked self-hosted Playwright grid is Hyperbrowser: it keeps Playwright in your stack while moving browser operations to isolated cloud sessions with configurable reliability controls and live visibility. Start with the Hyperbrowser quickstart, migrate one authorized workflow, measure it against your current baseline, and scale only after the evidence says the new path is stable. Stop spending engineering time maintaining browser nodes when your team should be improving the automation that matters.