This page is about agent-browser, the command line browser tool from vercel-labs, not about the hosted product that a proxy seller markets under the same name. The open source one takes a proxy in a single flag, and it does something most browser tools do not: it answers the proxy login itself. Three things about it surprise people, and one of them is written in its own documentation. We read every setting on this page in release v0.38.1, published on 16 September 2026.
Why would agent-browser need a proxy?
agent-browser runs Chrome on your machine, so sites see your address. On a server that address belongs to a hosting network. We tested what that changes on 19 September 2026: thirteen sites, twice from our server and twice through a residential line. A residential IP 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, so read it as what the address alone does. The table per site is on our OpenClaw page.
Where does agent-browser read the proxy?
The first of these that exists wins, and it is used for every scheme, because Chrome takes one proxy for the whole browser:
| Where | Setting |
|---|---|
| Command line | --proxy <url> and --proxy-bypass <hosts> |
| Own variables | AGENT_BROWSER_PROXY, AGENT_BROWSER_PROXY_BYPASS |
| Config file | "proxy", "proxyBypass" |
| Standard variables | HTTP_PROXY, http_proxy, HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxy |
| Bypass fallback | NO_PROXY, no_proxy |
agent-browser --proxy "http://USERNAME:PASSWORD@GATEWAY_HOST:GATEWAY_PORT" open https://api.ipify.org
agent-browser get text body
Note that HTTP_PROXY is read before HTTPS_PROXY. Setting the two to different addresses does not split the traffic; the first one carries everything. Chrome keeps localhost and link-local addresses off the proxy by itself, so a bypass list is only needed for other hosts inside your network.
What happens to the login
Chrome ignores a login written into its proxy flag. The project hit that too, and its fix says so plainly: "Chrome's --proxy-server flag doesn't support credentials in the URL." So the CLI splits the URL at the last @, gives Chrome the bare address, and keeps the username and password in the daemon. When the proxy answers with a challenge, the daemon replies over the DevTools protocol with those credentials.
Two details matter here.
- Every tab in 0.38.1. A stored proxy login turns on automatic attachment, so tabs opened later are covered. In 0.26.0, the version the Hermes Agent pins, the handler sat on the tab that existed at launch, and a new tab got it only when a domain filter was set.
- It answers every challenge, not only the proxy's. The handler never checks whether the challenge came from the proxy or from the site. A page that asks for Basic authentication receives your proxy username and password. With no proxy login set, no handler runs at all, and such a page waits until the command times out. Both halves are open on the tracker.
Three traps
A trailing slash stops the launch. The address reaches Chrome exactly as written, and Chrome refuses http://proxy:8080/ with net::ERR_NO_SUPPORTED_PROXIES. Shell variables pick up that slash easily. The report is open since May 2026, and the pull request that trimmed it was closed unmerged, so 0.38.1 still passes the value through.
A SOCKS5 login cannot work. Both the documentation page and the proxy skill show ALL_PROXY="socks5://user:pass@host:1080". Chromium's own documentation is blunt: "No authentication methods are supported for SOCKSv5 in Chrome". The login is stripped from the address, and a SOCKS handshake raises no challenge for the daemon to answer. Use an HTTP address with a login, or a SOCKS5 address whose plan allows your IP.
An attached browser keeps its own connection. With --cdp or --auto-connect the browser is already running, so the flag cannot change how it reaches the web. Nothing warns you. The related --ca-cert flag does refuse those modes with an error.
Which proxy type fits agent-browser?
Residential, for the sites that refuse a hosting address. An agent usually works through one site across several steps, so a sticky line fits that run and keeps the same identity from the first click to the last. Short one-off reads suit a rotating line.
HProxy residential gateways fit both. Allow your server's address on a Residential Premium plan, up to 150 per plan, and the proxy needs no login at all: --proxy then carries no password, and none lands in a shell history or a process list. An allowed address takes no country or city targeting. For a country, use a generated line, whose username carries the targeting. Rotating ports change the address, a sticky port holds one, and a sticky address can still change early if its device leaves the network, so let the agent 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
net::ERR_NO_SUPPORTED_PROXIES. Remove the trailing slash from the address.- The browser restarts on the next command. That is by design: the proxy, the bypass list and the login are part of the launch fingerprint, so changing any of them relaunches Chrome inside the running daemon.
- A page hangs until the command times out. The site is asking for a login and no handler is installed, because no proxy login is set.
- A site received your proxy password. The same handler answers site challenges. Keep a proxy login out of runs against sites that use Basic authentication, or allow your IP instead so no login exists.
- 407 Proxy Authentication Required. The password is wrong, or the line belongs to another plan. Our 407 guide walks through it.
- Certificate errors through a company proxy. A proxy that opens TLS needs its authority trusted with
--ca-cert, which works only with a locally launched Chrome on Linux. - Your traffic bill includes a browser download.
agent-browser installfetches Chrome through the standard variables. Install first, or keep that host off the proxy. - The site still refuses. A proxy changes the address, not the browser. A script check refuses a plain visitor whatever the address.
What this page does not cover
We read agent-browser v0.38.1's Rust source, its documentation and its changelog, plus Chromium's proxy documentation, and we did not run agent-browser. The blocking test used plain requests from one server address and one residential line, on one day. We did not test whether the Lightpanda engine can answer a proxy login; we only found that the login is never passed to it. agent-browser ships several releases a month, so we will read these settings again by 19 October 2026.
Where to go from here
Proxies for Hermes Agent covers an agent that drives this tool, and which of its own paths the proxy reaches. Proxies for Playwright MCP covers the other common browser tool for agents, which handles a login very differently. HTTP vs SOCKS5 explains the two proxy types behind the SOCKS5 limit above.
Sources
- The proxy flags and their order (cli/src/flags.rs), the URL parser and the launch command (cli/src/main.rs), the Chrome launch flags (cli/src/native/cdp/chrome.rs), the login handler and the launch fingerprint (cli/src/native/actions.rs), the Lightpanda arguments, the installer's HTTP client, the README, the changelog and the proxy documentation page. vercel-labs/agent-browser, release v0.38.1, 16 September 2026, with v0.26.0 for the comparison.
- Issues 1349, 1769, 1962 and 1662, and pull requests 1000 and 996. agent-browser issue tracker, 2026.
- SOCKSv5 authentication and the implicit bypass rules. The Chromium Authors, net/docs/proxy.md, read 19 September 2026.
- The automatic system proxy (src/async_impl/client.rs). reqwest 0.12.28, the version line agent-browser pins.
- 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.
