Proxies for Stagehand: what each environment accepts

Stagehand here means the browser automation library from browserbase, the one that takes natural language actions and drives a real Chrome. It runs in two environments, and they treat proxies differently enough that one of them refuses what the project's own documentation shows. We read every setting on this page in version 4.1.0, which npm published on 9 September 2026 as the current release.

Watch the version. The repository's release list leads with the 3.7 tags, so it is easy to read documentation for one line while running the other.

Why would Stagehand need a proxy?

An agent run reaches the same sites a scraper does, from whatever address the machine has. We tested what the address alone changes on 19 September 2026: thirteen sites, twice from our server in a hosting network and twice through a residential line. A residential address changed the answer at four of them: Zillow, Instagram, Reddit and DuckDuckGo. Indeed, Glassdoor, Amazon and Booking refused both. That test sent plain requests rather than a browser. The table per site is on our OpenClaw page.

What the local browser accepts

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "LOCAL",
  localBrowserLaunchOptions: {
    proxy: { server: "http://GATEWAY_HOST:GATEWAY_PORT" },
  },
});

await stagehand.init();

Chrome keeps localhost and link-local addresses off the proxy by itself, so the bypass list is only for other hosts inside your network.

The error, and why it is there

Put a login into the local options and version 4.1.0 stops with a sentence that leaves no doubt: Authenticated local browser proxies are not supported yet. The check runs before Chrome is launched.

The reason is old and familiar: Chrome ignores a login written into its proxy flag, so a tool has to answer the proxy's challenge over the DevTools protocol instead. Stagehand does not do that yet. Two contributors have offered the same fix, one since December 2025 and one since June 2026, and both pull requests are still open. One of them describes the older behaviour plainly: the options accepted a username and password, only the server was forwarded, and authenticated proxies failed silently.

So a version that throws is an improvement. You still need a proxy that recognises your machine by its address.

The hosted session

The other environment creates a session through the vendor's API, and Stagehand passes your session parameters straight through:

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  browserbaseSessionCreateParams: {
    projectId: process.env.BROWSERBASE_PROJECT_ID,
    proxies: [
      {
        type: "external",
        server: "http://GATEWAY_HOST:GATEWAY_PORT",
        username: "USERNAME",
        password: "PASSWORD",
      },
    ],
  },
});

That entry type is where your own proxy goes, with its login. proxies: true uses the vendor's own network instead, and each entry may carry a domain pattern, so only matching sites take the proxy and everything else goes direct. That last detail is worth using on a line billed per gigabyte.

Which proxy type fits Stagehand?

Residential, for the sites that refuse a hosting address. An agent usually works one site across several steps, so a sticky line keeps the same identity from the first click to the last. Many short visits suit a rotating line.

For the local environment the shape matters more than the type: the line has to work without a login. On an HProxy Residential Premium plan you can allow your machine's address, up to 150 per plan, and the proxy then needs no username at all. That is exactly what proxy.server can use. An allowed address takes no country or city targeting, rotates on the rotating ports and holds one address per sticky port. For the hosted session, generate a line instead: its username carries the country and goes into the external entry. A sticky address can still change early if its device leaves the network, so let the run retry. The residential proxies page lists the plans, and the plan API generates lines and manages allowed addresses from code.

What breaks when the proxy is on

• Authenticated local browser proxies are not supported yet. Remove the username and password, and allow your address instead.
• The documented example fails. The configuration page shows a local proxy block with a login, which is the one shape the code rejects.
• On an older version, nothing happens at all. The 3.x line accepted the same fields and forwarded only the server.
• 407 Proxy Authentication Required in the hosted session. The password is wrong, or the line belongs to another plan. Our 407 guide walks through it.
• Traffic climbs faster than expected. Every asset the page loads goes through the proxy. In the hosted session a domain pattern narrows that.
• The site still refuses. A proxy changes the address, not the browser or the way the agent behaves.

What this page does not cover

We read Stagehand 4.1.0 and the vendor session types as text, and we did not run either environment. Our blocking test used plain requests from one server address and one residential line, on one day. We say nothing about the vendor's own proxy network, which we have not measured. Stagehand ships several versions a month, and the two pull requests above would change its main answer, so we will read these settings again by 19 October 2026.

Where to go from here

Proxies for browser-use covers an agent that answers the proxy login itself, which is the thing Stagehand's local mode is missing. Proxies for agent-browser covers another local browser tool and how it handles the same problem. Sticky vs rotating sessions explains the choice above.

Sources

• The local browser launcher (packages/sdk-ts/src/browser/localBrowser.ts), the hosted session factory (browserbaseSession.ts) and the browser configuration page shipped with the release. browserbase/stagehand, version 4.1.0, 9 September 2026.
• Session creation parameters, including the external proxy entry. browserbase/sdk-node, v2.20.0, 9 September 2026.
• Pull requests 1484 and 2208 (both open) and issue 356. Stagehand issue tracker, 2025 to 2026.
• Credentials in the proxy flag, SOCKSv5 authentication and the implicit bypass rules. The Chromium Authors, net/docs/proxy.md, read 19 September 2026.
• Plans, IP whitelist and sticky sessions; errors; the proxy API. HProxy documentation, hproxy.com/docs, 19 September 2026.
• Our own test of 19 September 2026: plain GET requests to 13 sites and 3 controls, two runs from our server and two through a residential line of our own house plan. Raw output is kept in the research folder of our OpenClaw page.