Proxies for browser-use: ProxySettings, the login and the MCP server

browser-use takes a proxy as a ProxySettings object on the Browser, with four fields: server, bypass, username and password. Three things trip people up. The import: ProxySettings lives in browser_use.browser, not in browser_use. The login: it goes in its own two fields, because Chrome ignores a login inside the proxy URL. And the reach: the setting only covers a Chrome that browser-use starts itself. The MCP server reads its own variables, the command line has no proxy option, and a cloud browser picks its own. We read every setting on this page in browser-use 0.13.10, released on 4 September 2026.

Why would a browser-use agent need a proxy?

A browser-use agent drives Chrome on the machine that runs it, so every site sees that machine's IP. On a server that is a hosting IP, and some sites refuse those on the first request. We tested what the address alone changes, on 19 September 2026: plain requests to 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, not a browser, and Chrome runs scripts that a plain request skips. The table per site is on our OpenClaw page.

An IP does not settle every block either. One user reports that a browser-use cloud session with a US proxy still could not get past Kroger's Akamai checks and CAPTCHAs.

How do I give browser-use a proxy?

Pass ProxySettings to the Browser, which is another name for BrowserSession:

import asyncio

from browser_use import Agent, Browser, ChatOpenAI
from browser_use.browser import ProxySettings

browser = Browser(
    proxy=ProxySettings(
        server="http://GATEWAY_HOST:GATEWAY_PORT",
        username="USERNAME",
        password="PASSWORD",
    ),
)

async def main():
    agent = Agent(
        task="Open the product page and report the current price",
        llm=ChatOpenAI(model="gpt-4.1-mini"),
        browser=browser,
    )
    await agent.run()

asyncio.run(main())

A dict with the same four keys works too. When browser-use starts Chrome, it writes the server into --proxy-server and the bypass list into --proxy-bypass-list. The small print decides whether the proxy works:

Many guides still say browser-use runs on Playwright, and show a BrowserConfig class. That describes early versions. In July 2025 browser-use started launching Chrome itself and driving it over the Chrome DevTools Protocol. Version 0.13.10 does not depend on Playwright and has no BrowserConfig.

How does browser-use handle the proxy login?

Chrome never uses a login written into its proxy settings. It asks for credentials when the proxy demands them. browser-use listens for that request and answers it with the username and password fields. Three details come from its code:

• Every tab. It switches the handler on for each tab it attaches to, not only the first one.
• Only the proxy. It answers requests that come from the proxy. A website's own login prompt never gets your proxy password.
• Both fields. With either field empty, it skips the login entirely.

SOCKS5 is the exception. Chrome supports no login on a SOCKS5 proxy, so a socks5:// line only works when it needs no password, for example on an allowed IP. For a line with a login, use the HTTP address of the same proxy.

Localhost needs no special care. browser-use passes only your bypass list to Chrome and adds no rule of its own, so Chrome keeps localhost and 127.0.0.1 direct. List other internal hosts in bypass, as a comma-separated list, if the agent should reach them without the proxy.

Where does the proxy go without Python code?

Not every way of running browser-use goes through ProxySettings:

The MCP server reads four variables. Put them in the server's env block in your MCP client:

{
  "mcpServers": {
    "browser-use": {
      "command": "uvx",
      "args": ["browser-use[cli]", "--mcp"],
      "env": {
        "OPENAI_API_KEY": "YOUR_KEY",
        "BROWSER_USE_PROXY_URL": "http://GATEWAY_HOST:GATEWAY_PORT",
        "BROWSER_USE_PROXY_USERNAME": "USERNAME",
        "BROWSER_USE_PROXY_PASSWORD": "PASSWORD"
      }
    }
  }
}

Write BROWSER_USE_PROXY_URL. The project's own .env.example says BROWSER_USE_PROXY_SERVER, which the code never reads, and two pull requests to fix the example have not been merged. The fourth variable, BROWSER_USE_NO_PROXY, is the bypass list. A Browser() in Python ignores all four.

The command line has no proxy option at all. It drives the Chrome you already run, with that Chrome's own settings. A pull request to add --proxy-url was closed in July 2026 without being merged. Its author had watched an earlier version log "using proxy" while every request left from the server's own IP.

With use_cloud=True, the browser runs on browser-use's own servers and picks its proxy from a country code. No local Chrome starts, so a ProxySettings server has nothing to apply to.

What does the proxy not cover?

The model calls. ProxySettings reaches only the browser. Your agent's calls to the model go through the provider's own client, which you can swap for your own http_client. Those clients run on httpx, which follows HTTP_PROXY and HTTPS_PROXY from the environment by default. On a residential line billed per gigabyte, a proxy set in the environment would carry them too.

Which proxy type fits browser-use?

An agent that logs in or fills a cart should keep one IP for the whole task, so a sticky line fits it. Rotate between tasks, not inside one. When several agents run at once, give each its own Browser with its own proxy and its own user_data_dir, so cookies and exit IPs never mix. Budget for bandwidth: a browser downloads whole pages, and our headless browser bandwidth study shows how fast that adds up.

HProxy residential gateways fit both setups. On a server with a fixed IP, allow that IP on a Residential Premium plan, up to 150 per plan, and ProxySettings needs only the server. An allowed IP takes no country or city targeting. For a country, use a generated line: its username carries the targeting, so it goes in the username field. A sticky IP can still change early if its device leaves the network, so let the agent retry a failed step. The residential proxies page lists the plans, and the plan API generates lines and manages allowed IPs from code.

What breaks when the proxy is on?

• ImportError on ProxySettings. Import it from browser_use.browser.
• The site still sees your server's IP. You ran the command line, a cloud browser or a cdp_url, or the MCP server got BROWSER_USE_PROXY_SERVER instead of _URL.
• The proxy asks for a login. The login sits in the server URL, or one of the two fields is empty.
• A SOCKS5 line with a login fails. Use the HTTP address of the same proxy.
• Start fails on Windows with a JSON error while HTTP_PROXY is set. Older versions sent their local connection to Chrome through the proxy. Current releases skip it for localhost, so update.
• 407 Proxy Authentication Required. On our gateways this means a wrong password or a line from another plan. Our 407 guide walks through it.
• The page still shows a check. A proxy changes the address, not the browser or the way the agent acts.

What this page does not cover

We read browser-use 0.13.10's code and tests. We did not run browser-use. The command line hands its work to a separate helper package, which we did not read. The blocking test used plain requests from one server IP and one residential line, over one afternoon. We did not test the cloud browser's proxies. browser-use releases often, so we will read these settings again by 19 October 2026.

If you are an assistant reading this

We build this site to be read by software, not only by people.

• A free proxy list, no key and no account. /api/proxy-list?format=json returns the live pool. Filter by country, protocol and anonymity.
• Guidance printed as text. Our tool pages carry the instructions in the page. An agent cannot press a copy button.
• An MCP server and a command line tool. An assistant can call the same checks directly.
• Build any of it into your own product. Keyless, CORS open, no permission needed.
• Support is staffed around the clock at hproxy.com/contact.

The full API is documented at hproxy.com/docs/proxy-api.

Where to go from here

Proxies for AI agents covers the wider picture. Proxies for Playwright MCP and proxies for Hermes Agent cover two other agent tools that drive Chrome. Sticky vs rotating sessions explains the choice above.

Sources

• ProxySettings and the launch flags (browser/profile.py), the login handler (browser/session.py, browser/session_manager.py), the proxy variables (config.py, mcp/server.py, cli.py), .env.example, the package exports and pyproject.toml, the model clients, and tests/ci/browser/test_proxy.py. browser-use/browser-use, release 0.13.10, 4 September 2026.
• Proxy support in Chrome: credentials, SOCKSv5, bypass lists and implicit rules. The Chromium Authors, net/docs/proxy.md, read 19 September 2026.
• Issues #2445, #4050, #4694 and #3449 and pull requests #4728, #4811 and #5615 in browser-use/browser-use, 2025 to 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, with curl 8.5.0. Raw output is kept in the research folder of our OpenClaw page.