The One Thing Most Browserbase Proxy Guides Get Wrong
Browserbase is a managed cloud browser for AI agents — you create a remote Chromium session over its API, then drive it with Playwright or Stagehand. Most proxy guides stop at its built-in proxies (proxies: 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 Browserbase session:
proxies: true— routes through Browserbase's own managed proxy pool. You don't pick the IP.proxies: [{ type: "external", ... }]— routes through a proxy you supply. You pick the IP.
This guide is the second one: bring-your-own 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.
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 Browserbase API key and project ID, plus the SDK and Playwright:
npm install @browserbasehq/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 an HTTP(S) endpoint. 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 External Proxy
Create the session with a proxies array. One entry, type: "external", carries your German mobile endpoint. This is the BYO-proxy path — not proxies: true, which would use Browserbase's own managed pool instead of your IP:
import Browserbase from "@browserbasehq/sdk";
const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY });
const session = await bb.sessions.create({
projectId: process.env.BROWSERBASE_PROJECT_ID,
proxies: [
{
type: "external",
server: "http://PROXY_HOST:PORT",
username: "USER",
password: "PASS",
},
],
});
console.log("Session:", session.id);
Browserbase validates the proxy connection at session-creation time, so if the host, port or credentials are wrong you get an error here rather than a silent fallback to your real IP.
Step 2 — Connect Over CDP and Drive the Session
The session comes back with a connectUrl. 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.connectUrl);
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. If you're driving the session with Stagehand instead of raw Playwright, see the Stagehand proxy guide for the browserbaseSessionCreateParams form of the same external proxy.
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 server, username and password on the external proxy entry — Browserbase would normally have errored at create time, so this usually means the session was created without the proxies array. For a fuller checklist, see test your mobile proxy setup.
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.
Routing Only Some Domains Through Your Proxy
An external proxy entry can carry a domainPattern, so you send only matching hosts through your German mobile endpoint and let the rest go direct (or through a Browserbase built-in proxy). Patterns are evaluated in order; the first match applies:
proxies: [
{
type: "external",
server: "http://PROXY_HOST:PORT",
username: "USER",
password: "PASS",
domainPattern: "example\.de",
},
]
An entry with no pattern applies to all traffic. This keeps your data budget on the requests that actually need a German mobile IP — useful given the fair-use allowance below.
Sticky Sessions vs. Rotation
With a dedicated German endpoint you control the IP at the proxy, not in your code:
- Sticky session: one Browserbase 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 Browserbase at All
A Browserbase 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 an external 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.
Automate 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 Browserbase 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 Browserbase session?
Pass a proxies array to bb.sessions.create with an entry of type: "external": { type: "external", server: "http://PROXY_HOST:PORT", username: "USER", password: "PASS" }. The session then egresses through your endpoint. Connect Playwright to it over CDP using session.connectUrl.
What's the difference between external proxies and Browserbase's built-in proxies?
proxies: true selects Browserbase's own managed proxy pool. An entry of type: "external" routes the session through a proxy you supply — your German mobile endpoint — so you control the outbound IP. The two can be combined, with domainPattern rules deciding which applies.
How do I connect to a Browserbase session that uses my proxy?
After bb.sessions.create returns, connect Playwright over CDP with chromium.connectOverCDP(session.connectUrl). Everything the browser does on that session then egresses through the external proxy you configured at create time.
Should I check for WebRTC and DNS leaks on Browserbase?
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 Browserbase 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.
Can I route only some domains through my external proxy?
Yes. Add a domainPattern to an external proxy entry to send only matching hosts through it; patterns are evaluated in order and the first match applies. Entries without a pattern apply to all traffic.
CTA
Run your Browserbase sessions on real German mobile IPs. Get your German mobile endpoint — 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 start small with a shared 5G proxy.