Configure TrueProxies with Browser Use

Browser Use takes a proxy on the Browser it launches: pass ProxySettings(server=..., username=..., password=...) as proxy. Browser Use starts Chromium with the proxy server and answers the proxy’s authentication challenge with your username and proxy password, so no browser extension is needed. Use the HTTP port; targeting rides on the username.

Installation

uv pip install browser-use
uvx browser-use install

uvx browser-use install installs Chromium. The example uses ChatBrowserUse, which reads BROWSER_USE_API_KEY from the environment; any chat model Browser Use supports works the same way with the proxy.

Basic usage

import asyncio

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

browser = Browser(
    proxy=ProxySettings(
        server="http://YOUR_HOST:YOUR_HTTP_PORT",
        username="your_username",
        password="your_password",
    ),
)


async def main() -> None:
    agent = Agent(
        task="Open https://httpbin.org/ip and report the IP address shown",
        llm=ChatBrowserUse(),
        browser=browser,
    )
    await agent.run()


asyncio.run(main())

The agent reports the exit IP address. The proxy applies to the browser’s traffic only; the agent’s calls to the chat model do not go through it.

Residential IPv4 country targeting

browser = Browser(
    proxy=ProxySettings(
        server="http://YOUR_HOST:YOUR_HTTP_PORT",
        username="your_username-country-us",
        password="your_password",
    ),
)

Residential IPv4 sticky session per agent run

Without a session option, each new connection gets a new exit IP, so one agent run can reach a site from several addresses. Give each run its own session to keep one exit for the whole task:

import uuid

session = uuid.uuid4().hex[:16]  # 1 to 32 letters or digits

browser = Browser(
    proxy=ProxySettings(
        server="http://YOUR_HOST:YOUR_HTTP_PORT",
        username=f"your_username-session-{session}-lifetime-1800",
        password="your_password",
    ),
)

lifetime is in seconds. The accepted range depends on the product; see the options table.

When the browser cannot connect

A refused proxy connection reaches the agent as a browser network error, and the browser does not show the proxy’s reason. Send the same username and proxy password with curl -v, read the X-Proxy-Reason header, and look it up in Proxy errors and refusal reasons.