Hyperbrowser Proxy Setup: Sessions on German Mobile IPs

The One Thing Most Hyperbrowser Proxy Guides Get Wrong

Hyperbrowser is a managed cloud browser for AI apps and agents — you create a remote Chromium session over its API, then drive it with Playwright or Puppeteer over CDP. Most proxy guides stop at its managed proxies (useProxy: true) and never show the setup people actually search for: attaching your own proxy so the session egresses through an IP you control.

That is the thing they get wrong. There are two different proxy concepts on a Hyperbrowser session:

useProxy: true (no proxyServer) — routes through Hyperbrowser's own managed proxy pool. You don't pick the IP.
useProxy: true + proxyServer — routes through a proxy you supply. You pick the IP.

This guide is the second one: a custom proxy, using your German mobile endpoint. You get a real German mobile IP on a managed cloud browser, without running the browser yourself — and without the rotating-pool machinery, because a dedicated endpoint rotates on demand at the proxy, not per request in code. Note that custom proxies are a Hyperbrowser Enterprise-plan feature, so confirm your plan before you wire this up.

Before You Start

You need four values from your GermanProxy.io account:

Host and port of your endpoint
Username and password

You'll also need a Hyperbrowser API key, plus the SDK and a driver (Playwright here):

npm install @hyperbrowser/sdk playwright-core

The examples use PROXY_HOST, PORT, USER and PASS as placeholders — replace them with your own. A single dedicated endpoint is enough; you do not need a rotating pool for a session. All examples use the HTTP endpoint, which is the simplest credentialed path. New to routing an agent through a proxy at all? Start with the broader AI browser-agents guide.

Step 1 — Create a Session With Your Custom Proxy

Create the session with useProxy: true and the three proxyServer* fields carrying your German mobile endpoint. This is the custom-proxy path — with proxyServer set, Hyperbrowser routes through your IP instead of its own managed pool. proxyServer must include the scheme (http://):

import { Hyperbrowser } from "@hyperbrowser/sdk";

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

const session = await client.sessions.create({
  useProxy: true,
  proxyServer: "http://PROXY_HOST:PORT",
  proxyServerUsername: "USER",
  proxyServerPassword: "PASS",
});

console.log("Session:", session.id);

Hyperbrowser supports HTTP, HTTPS, SOCKS5 and SOCKS5h — put the scheme on proxyServer and the credentials in proxyServerUsername / proxyServerPassword. Custom proxy values must be set at create time; you can't add them later through the session-update route.

Step 2 — Connect Over CDP and Drive the Session

The session comes back with a wsEndpoint. Connect Playwright to it over CDP, and everything the browser does on that session egresses through your German mobile endpoint:

import { chromium } from "playwright-core";

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

await page.goto("https://www.example.de", { waitUntil: "domcontentloaded" });
console.log("Title:", await page.title());

await browser.close();

No launch args, no page.authenticate — the proxy was set on the session at create time, so the connection just inherits it. Prefer Puppeteer? puppeteer.connect({ browserWSEndpoint: session.wsEndpoint }) attaches the same way; see the Puppeteer proxy guide for that driver's quirks.

Step 3 — Verify the IP Before You Scale

Confirm the session is actually on a German mobile IP before you build anything on top of it. Point the same page at an IP-echo endpoint:

await page.goto("https://api.ipify.org?format=json", {
  waitUntil: "domcontentloaded",
});
console.log("Egress IP:", await page.evaluate(() => document.body.innerText));

If it returns a datacenter address or your own, re-check the proxyServer, proxyServerUsername and proxyServerPassword — a session created with useProxy: true but no proxyServer runs on Hyperbrowser's managed IP, not yours. For a fuller checklist, see checking your proxy configuration.

Step 4 — Check for WebRTC and DNS Leaks

A cloud browser routes HTTP through your proxy, but Chromium has two side channels that can expose the underlying address:

WebRTC can surface an IP via ICE candidates outside the proxy tunnel — see what a WebRTC leak is.
DNS can resolve names outside the tunnel, so the target sees a different resolver — see what a DNS leak is.

A real German mobile IP only helps if nothing else leaks past it. Verify both before you turn a single session into a fleet.

Sticky Sessions vs. Rotation

With a dedicated German endpoint you control the IP at the proxy, not in your code:

Sticky session: one Hyperbrowser session on your endpoint keeps the same German mobile IP across a multi-step task — that IP stability is what stops the target re-challenging the browser on every action.
Rotation on demand: when you want a fresh IP, trigger rotation at the proxy and open a new session. There's no per-request IP pool to manage.

This is why a dedicated endpoint keeps the code small: no rotation list, no health-checking, no retry-on-dead-IP loop. See sticky sessions and IP rotation explained and dedicated vs shared mobile proxy.

Note the data budget: a cloud browser loads full pages with images and scripts, and a single session rendering rich pages can move several hundred MB an hour. A GermanProxy.io endpoint comes with a fair-use allowance of 20 GB/day, so size your concurrency to that rather than assuming headroom that isn't promised. We do not advertise "unlimited" traffic, because fair-use limits apply in practice and honesty is the point.

Why a Mobile IP for Hyperbrowser at All

A Hyperbrowser session is a Chromium instance making many dependent requests as an agent works through a task, and the egress IP decides how the target treats it. Datacenter ranges — including many cloud-browser IPs — are widely distrusted, so even a well-behaved agent can hit friction. Attaching a real German mobile IP as your own proxy rides on carrier-grade NAT (CGNAT), the same shared-IP space thousands of ordinary phone users sit behind, which is why it tends to carry higher IP reputation on German platforms.

For the trade-offs against other IP types, see mobile vs residential vs datacenter proxy and what is a mobile proxy.

Scrape Responsibly

A mobile proxy improves reliability for authorized automation — it is not a tool to defeat access controls, anti-bot systems, or platform rules, and we don't position it as an "undetectable" agent. Keep your Hyperbrowser sessions clean and defensible:

Respect each site's terms and its robots.txt; collect only public data you're permitted to use. Web scraping for public data is generally lawful in the EU, but context matters — see is web scraping legal in the EU.
Throttle with human-reasonable delays between agent actions so you don't overload a target server.
Collect only what you need, and handle any personal data in line with the GDPR.
Be honest about who you are — don't impersonate a service or misuse a target's security mechanisms.

[!IMPORTANT]
GermanProxy.io is an EU-based provider with a full imprint, clear acceptable-use rules, and a real abuse-reporting process. The service is IT routing — a host, port and credentials — not hardware you operate, and not framed as anonymity. Whether mobile proxies are lawful to use: are mobile proxies legal.

FAQ

How do I add a custom proxy to a Hyperbrowser session?

Pass useProxy: true plus proxyServer, proxyServerUsername and proxyServerPassword to client.sessions.create. The proxyServer must include a scheme, e.g. "http://PROXY_HOST:PORT". The session then egresses through your German mobile endpoint. Custom proxy is an Enterprise-plan feature.

What's the difference between a custom proxy and Hyperbrowser's managed proxies?

useProxy: true with no proxyServer selects Hyperbrowser's own managed proxy pool. Adding proxyServer plus credentials routes the session through a proxy you supply — your German mobile endpoint — so you control the outbound IP.

How do I connect to a Hyperbrowser session that uses my proxy?

After client.sessions.create returns, connect Playwright or Puppeteer over CDP to session.wsEndpoint with connectOverCDP. Everything the browser does on that session then egresses through the custom proxy you configured at create time.

Which proxy schemes does Hyperbrowser accept for a custom proxy?

Hyperbrowser supports HTTP, HTTPS, SOCKS5 and SOCKS5h. proxyServer must start with the scheme. Your GermanProxy.io endpoint gives you HTTP/SOCKS5 (plus OpenVPN), so the HTTP endpoint with proxyServerUsername and proxyServerPassword is the simplest credentialed path. Background: SOCKS5 vs HTTP proxy.

Should I check for WebRTC and DNS leaks on Hyperbrowser?

Yes. A cloud browser can still expose the underlying address through WebRTC or resolve DNS outside the tunnel — see what a WebRTC leak is and what a DNS leak is. Have the session open an IP-echo page to confirm a German mobile IP, then run a leak test before you rely on the setup.

Do I need a rotating pool for Hyperbrowser sessions?

No. A single dedicated German mobile endpoint is usually the better fit. A stateful, multi-step session needs a stable IP (sticky session) so it is not re-challenged on every action; rotate on demand at the proxy between tasks, not mid-task. See sticky sessions and IP rotation explained.

Related guides

CTA

Run your Hyperbrowser sessions on real German mobile IPs. Get a German mobile proxy — HTTP/SOCKS5/OpenVPN, sticky sessions, on-demand rotation, fair-use 20 GB/day, from a transparent EU provider. Browse the plans to get started. New to the topic? Start with the AI-agents use case or what is a mobile proxy.

Get a German mobile proxy: Real 4G/5G IPs from Germany, fair-use 20 GB/day — browse German mobile proxy plans or get a dedicated proxy on the Blue network.