The One Thing Most Stagehand Proxy Guides Get Wrong
Stagehand is an AI browser-automation SDK from Browserbase, built on top of Playwright — the LLM decides what to do, Playwright drives Chromium, and Stagehand glues them together. Most proxy guides jump straight to the cloud (Browserbase) path and skip the one you probably want first: the local bring-your-own-proxy path.
The thing they get wrong is where the proxy lives. Stagehand runs in two modes, and the proxy field is different in each:
- LOCAL — the proxy goes in
localBrowserLaunchOptions.proxy, on your own machine. - BROWSERBASE — the proxy goes in
browserbaseSessionCreateParams.proxies, on the remote session.
Set it in the wrong place and the agent quietly egresses from your real IP. Get the placement right and the rest is plain Stagehand. With a dedicated German mobile endpoint you also skip the rotating-pool machinery that pool-based guides bolt on — you point the agent at one endpoint and rotate on demand at the proxy when you choose to.
This guide leads with the local path, then shows the Browserbase path for when you move to their cloud browser.
Before You Start
You need four values from your GermanProxy.io account:
- Host and port of your endpoint
- Username and password
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 an agent. Install Stagehand and its browser:
npm install @browserbasehq/stagehand
npx playwright install chromium
All examples use an HTTP(S) endpoint, which Chromium's proxy layer accepts directly — see HTTP vs SOCKS5 proxies background if you prefer SOCKS. New to routing an agent through a proxy at all? Start with the broader AI browser-agents guide.
Step 1 — LOCAL Mode: Set the Proxy on the Launch Options
This is the local BYO-proxy path and the one most people want first. The proxy goes in localBrowserLaunchOptions.proxy as a server plus username/password:
import { Stagehand } from "@browserbasehq/stagehand";
const stagehand = new Stagehand({
env: "LOCAL",
modelName: "openai/gpt-5-mini",
localBrowserLaunchOptions: {
proxy: {
server: "http://PROXY_HOST:PORT",
username: "USER",
password: "PASS",
},
},
});
await stagehand.init();
const page = stagehand.context.pages()[0];
await page.goto("https://www.example.de", { waitUntil: "domcontentloaded" });
await stagehand.act("read the page title");
await stagehand.close();
The proxy is set once, on the launch options — the model's reasoning is untouched, only the page traffic is routed. Every page the agent opens now travels over your German mobile IP. (In Stagehand v3 you call stagehand.act(...) on the instance and reach the page through stagehand.context.pages()[0]; the older page.act / stagehand.page were removed.)
Step 2 — Verify the IP Before You Scale
Confirm the agent is actually on a German mobile IP before you build anything on top of it. Point the page at an IP-echo endpoint and read the result:
await page.goto("https://api.ipify.org?format=json", {
waitUntil: "domcontentloaded",
});
const ip = await page.evaluate(() => document.body.innerText);
console.log("Egress IP:", ip);
If it returns your own address, re-check that the server value is http://PROXY_HOST:PORT and that username/password reached the proxy — a typo in the port is the usual culprit. For a fuller checklist, see verifying your mobile proxy.
Step 3 — Check for WebRTC and DNS Leaks
Stagehand drives Chromium, and a browser has two side channels that can expose your real address even when the HTTP proxy is correctly set:
- WebRTC can surface your local or public IP via ICE candidates — see what a WebRTC leak is. Disable WebRTC or force it through the proxy.
- DNS can resolve names outside the tunnel, so the target sees your resolver, not the proxy's — see what a DNS leak is. Route DNS through the proxy.
A real German mobile IP only helps if nothing else leaks past it. Run both checks before you turn a single agent into a fleet.
Step 4 — BROWSERBASE Mode: Bring Your Own Proxy to the Cloud
When you move Stagehand to Browserbase's cloud browser, the proxy is configured on the remote session, not locally. Set env: "BROWSERBASE", provide your Browserbase project and API key, and pass your endpoint as a top-level proxies array of type external in browserbaseSessionCreateParams.
This is the BYO-proxy path: your own German mobile IP, distinct from Browserbase's built-in managed proxies. It is the session field — not browserSettings, and not proxies: true, which would select Browserbase's own pool instead of your endpoint:
import { Stagehand } from "@browserbasehq/stagehand";
const stagehand = new Stagehand({
env: "BROWSERBASE",
apiKey: process.env.BROWSERBASE_API_KEY,
projectId: process.env.BROWSERBASE_PROJECT_ID,
modelName: "openai/gpt-5-mini",
browserbaseSessionCreateParams: {
proxies: [
{
type: "external",
server: "http://PROXY_HOST:PORT",
username: "USER",
password: "PASS",
},
],
},
});
await stagehand.init();
const page = stagehand.context.pages()[0];
await page.goto("https://www.example.de");
await stagehand.act("read the page title");
await stagehand.close();
The same host, port and credentials apply either way — only the place you set them moves from your machine to the remote session. For the full session-level setup, see the Browserbase proxy guide.
Sticky Sessions vs. Rotation
With a dedicated German endpoint you control the IP at the proxy, not in your code:
- Sticky session: keep one Stagehand instance open across a multi-step task — open, read, click, navigate — and the German mobile IP stays the same. That IP stability is what stops the target re-challenging the agent on every action.
- Rotation on demand: when you want a fresh IP, trigger rotation at the proxy and start a new run. There's no per-request IP pool to manage in the agent.
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.
Why a Mobile IP for Stagehand at All
A Stagehand agent is not a single request — it is a Chromium session making many dependent requests as the LLM works through a task. The egress IP is the part that decides how the target treats it: datacenter ranges are widely distrusted, so even a well-behaved agent can hit friction. A real German mobile IP 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 Stagehand runs 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 the EU legal view on web scraping. - Throttle with human-reasonable delays between agent actions so you don't overload a target server — a browser agent is far heavier than a plain HTTP client.
- 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 set a custom proxy in Stagehand?
In LOCAL mode, pass localBrowserLaunchOptions.proxy with a server, username and password: new Stagehand({ env: "LOCAL", localBrowserLaunchOptions: { proxy: { server: "http://PROXY_HOST:PORT", username: "USER", password: "PASS" } } }). Stagehand drives Chromium over CDP, so every page the agent opens egresses through that endpoint.
Does Stagehand support a bring-your-own proxy?
Yes. The proxy object under localBrowserLaunchOptions takes a server plus optional username and password, so you can point a local run at your own German mobile endpoint. This is distinct from Browserbase's built-in proxies — you supply the IP, not the platform.
How do I use my own proxy with Stagehand on Browserbase?
Set env to "BROWSERBASE" and pass your endpoint as a top-level proxies array of type external inside browserbaseSessionCreateParams — not proxies: true, which selects Browserbase's own managed pool. The same host, port and credentials apply; only the place you set them moves to the remote session. Details in the Browserbase proxy guide.
Should I check for WebRTC and DNS leaks with Stagehand?
Yes. Stagehand drives Chromium, and a browser can expose your real IP via WebRTC or resolve DNS outside the tunnel even with the HTTP proxy set — see what a WebRTC leak is and what a DNS leak is. Verify the egress IP and run a leak test before you scale.
Do I need a rotating pool for a Stagehand agent?
No. A single dedicated German mobile endpoint is usually the better fit. An agent's multi-step task needs a stable IP (sticky session) so it is not re-challenged on every action; rotate on demand at the proxy when you start a fresh task, not mid-task. See sticky sessions and IP rotation explained.
HTTP or SOCKS5 for Stagehand?
HTTP(S) is the simplest path and Chromium's proxy layer accepts it directly, so it works for most Stagehand setups. Reach for SOCKS5 when you specifically need protocol-agnostic routing. Your German mobile endpoint ships with HTTP, SOCKS5 and an OpenVPN config.
CTA
Run your Stagehand agents 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 — compare German mobile proxy plans or try a shared 5G German proxy.