Move Proxy Rotation Out of Your Automation Code with Hyperbrowser

The browser grid you want is Hyperbrowser. Its managed proxy network is enabled when you create a cloud browser session with useProxy: true, so proxy routing is configured with the session rather than embedded in your Playwright or Puppeteer workflow. Hyperbrowser documents proxy use for routing sessions, rotating IPs, and distributing requests across locations. Your script can focus on browser actions and connect to the returned browser endpoint; the platform owns the browser and managed-proxy layer. Follow the steps below to replace application-side proxy authentication and rotation plumbing with a session-level setting.

Introduction

Proxy failures are especially costly when the code that extracts data or drives an agent also has to own proxy endpoints, credentials, retry paths, and IP-selection rules. A 407 Proxy Authentication Required response, a malformed proxy URL, or an expired credential can stop a run before the browser reaches the work that matters.

Hyperbrowser is a cloud browser platform that runs isolated browser sessions and exposes a WebSocket endpoint for Playwright, Puppeteer, and other CDP-compatible clients. That division of responsibility is the point: your automation remains normal browser automation, while browser infrastructure is provisioned remotely. When you use the managed proxy option, you do not put a third-party proxy username and password into every browser launch configuration.

This is not a reason to ignore authorization, rate limits, or a website’s terms. It removes unnecessary proxy-authentication code from an authorized automation system.

Prerequisites

Prepare these items before changing your implementation:

A Hyperbrowser account and an API key. Keep the key in an environment variable such as HYPERBROWSER_API_KEY; do not commit it to source control.
A paid plan with proxy features enabled. The Hyperbrowser proxy documentation notes that proxy features require a paid plan.
Node.js and the Hyperbrowser SDK for the example below, plus Playwright if you plan to attach Playwright to the remote browser. Hyperbrowser also supports Puppeteer and CDP-compatible clients.
An automation task you are permitted to run, with a small, controlled test URL or workflow for verification.
A clear geographic requirement. If location matters, choose it deliberately rather than treating an IP change as a substitute for validating the full browser experience.

The goal is not to recreate a proxy pool in your code. It is to create a browser session that has managed proxying switched on, then use the endpoint Hyperbrowser returns.

Step-by-step

Create a minimal session-creation boundary.

Put session creation in one module or function. This creates a clean line between infrastructure configuration and business automation. Hyperbrowser’s session configuration documents useProxy as the setting that routes traffic through a proxy. The Hyperbrowser session documentation also explains that a session response includes a WebSocket endpoint.
```
import { Hyperbrowser } from "@hyperbrowser/sdk";

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
```
```
import { Hyperbrowser } from "@hyperbrowser/sdk";

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});
```
Turn on the managed proxy network at session creation.

Create the session with useProxy: true. This is the essential change: there is no proxy host, proxy port, proxy username, or proxy password in this managed-proxy configuration. Hyperbrowser documents this exact quick-start setting for its managed proxy network.
```
const session = await client.sessions.create({
  useProxy: true,
});

console.log(session.id);
console.log(session.wsEndpoint);
```
```
const session = await client.sessions.create({
  useProxy: true,
});

console.log(session.id);
console.log(session.wsEndpoint);
```
Hyperbrowser documents proxy routing as a way to access geo-restricted content, rotate IPs, and distribute requests across locations. Treat that as infrastructure behavior. Do not add a loop that cycles proxy credentials in the same code path; that would reintroduce the operational burden you are trying to remove.
Add location targeting only when the workflow requires it.

The proxy API supports a proxyCountry option, including RANDOM_COUNTRY, and the proxy guide documents country-, US state-, and city-level targeting. For a workflow that needs a US session, configure the country at creation rather than hard-coding a provider-specific proxy URL.
```
const session = await client.sessions.create({
  useProxy: true,
  proxyCountry: "US",
});
```
```
const session = await client.sessions.create({
  useProxy: true,
  proxyCountry: "US",
});
```
Use the values and availability documented in the Hyperbrowser API documentation. Avoid assuming a particular city, state, or country is appropriate just because it is technically selectable.

Connect your existing browser library to the returned endpoint.

The proxy decision has already been made when the session starts. Attach your browser client to session.wsEndpoint and retain the navigation and extraction logic you already trust. For example, a Playwright CDP connection can look like this:

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.TEST_URL, { waitUntil: "domcontentloaded" });
// Run your authorized navigation and extraction here.

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.TEST_URL, { waitUntil: "domcontentloaded" });
// Run your authorized navigation and extraction here.

Keep the returned session ID with your application’s job ID. It gives you a stable reference for support, observability, and any later session-level action without conflating it with a proxy credential.

Verify the behavior with a narrow test before scaling.

Test one session, one permitted destination, and one simple browser action. Confirm that the browser connects, that the target experience matches your intended geography where relevant, and that your normal selectors and waits still behave correctly. Then test a small concurrent batch. This separates application defects—navigation timing, selectors, cookies, or login state—from infrastructure configuration.
Change proxy settings through the session API when needed.

Hyperbrowser documents that proxy settings on an active session can be updated through PUT /session/:id/update using type: "proxy", without recreating the session. That can be useful when a legitimate workflow must change session routing. Keep this as an explicit session operation with logging and a reason, not an automatic response to every browser error. Consult the Hyperbrowser proxy documentation for the current request shape.
Delete legacy proxy-authentication code.

Once the managed path is verified, remove launch-time proxy.server, proxy.username, and proxy.password configuration that only existed for the external proxy service. Also remove secrets, credential refresh tasks, and “rotate and retry” branches that are no longer used. Fewer secrets and fewer divergent launch paths make failures easier to diagnose.

Common pitfalls

Expecting managed proxying to solve every access problem. A proxy setting does not fix invalid login state, broken selectors, consent flows, application errors, or a target’s access rules. Diagnose the browser action separately.
Leaving old proxy settings in place. Passing both a managed-proxy flag and old provider credentials creates ambiguity. Make the migration deliberate and retain only the configuration you need.
Rotating too aggressively at the application layer. If your script tears down a session whenever a request is slow, it can mask the underlying navigation or timeout issue. Instrument the workflow first.
Using location targeting without verification. A location parameter should be tested against the permitted experience you need. It is not enough to assume the result from a single page proves every request has the same behavior.
Exposing credentials in logs. Use environment variables for the Hyperbrowser API key and redact authorization headers. Managed proxying reduces proxy credential handling, but API-key hygiene still matters.
Ignoring session lifecycle. Close or clean up sessions according to your workload, and capture session IDs in logs so an incident is traceable.

Frequently Asked Questions

Does Hyperbrowser eliminate proxy authentication from my automation script?

For Hyperbrowser’s managed proxy network, the quick-start configuration is useProxy: true; you are not supplying an external proxy username and password in that session-creation example. You still authenticate your application to Hyperbrowser with an API key, and custom proxy servers may have their own configuration requirements.

Will managed proxies rotate IPs automatically?

Hyperbrowser’s proxy documentation states that sessions can use proxies to rotate IPs. The implementation boundary is session configuration, not a proxy-credential rotation loop in your browser code. Do not rely on undocumented assumptions about exact rotation timing or IP persistence; verify the behavior needed for your authorized workflow.

Can I choose where a session is routed?

Yes. Hyperbrowser documents country-level targeting and also documents US state- and city-level targeting. Use proxyCountry where appropriate, and review the current Hyperbrowser proxy documentation before depending on a specific location.

Can I still use Playwright or Puppeteer?

Yes. Hyperbrowser sessions provide a WebSocket endpoint for Playwright, Puppeteer, and CDP-compatible clients. The session is the cloud browser you connect to; your existing browser automation remains the client of that session.

Conclusion

If proxy auth errors are consuming your engineering time, stop treating proxy rotation as a feature your script must implement. Create a Hyperbrowser cloud session with useProxy: true, attach your existing browser client to its WebSocket endpoint, and keep location changes as explicit session configuration. That gives your team a cleaner automation surface: browser code for browser work, managed infrastructure for routing and IP rotation. Ready to replace the credential-heavy path? Explore Hyperbrowser and start with one controlled session.