Browser Use 1.0 has no proxy setting for a browser it starts on your machine. To send an agent through your own proxy, start Chromium with the proxy yourself and give the agent that browser over CDP, the Chrome DevTools Protocol that browser-harness, the engine inside Browser Use, drives Chrome with. With Playwright as the launcher, a Browser Use proxy takes a few lines and works with an HTTP proxy that needs a username and password.
Tested on 18 November 2026 with browser-use 1.0.6, browser-harness 0.1.13, Playwright 1.65.2 (its Chromium 159.0.8154.6), Google Chrome 157.0.8103.79 and Python 3.12.16 on macOS 26.5.1. Under each code block we say what ran and what didn't.
Short answer
The whole browser-use proxy setup is two calls:
context = await p.chromium.launch_persistent_context(
profile,
proxy={'server': 'http://HOST:PORT', 'username': 'USERNAME', 'password': 'PASSWORD'},
args=['--remote-debugging-port=9242'],
)
agent = Agent(task, browser=Browser(cdp_url='http://127.0.0.1:9242'))Playwright starts Chromium through your proxy and answers its login, and Browser(cdp_url=...) hands that browser to the agent, so every page the agent opens goes through the proxy. This is an excerpt of the full script below and doesn't run on its own.
Why not a Browser Use setting? In 1.0 the old proxy option exists only for Cloud browsers; for a local browser the Browsers page says "Local: not yet", and ProxySettings now raises "Browser('chromium') has no proxy yet". Attaching with cdp_url is the documented way to drive any browser with a CDP endpoint, as in the docs' own Playwright example. This guide covers 1.0 only.
What you need
- Python 3.11 or newer and uv, as in the Browser Use quickstart.
- A proxy: host, port, username and password. The commands below use placeholders.
- A key for the model. By default
Agentruns Browser Use's own model and readsBROWSER_USE_API_KEY; other models go inllm=.
uv init --python 3.12 browser-use-proxy && cd browser-use-proxy
uv add 'browser-use==1.0.6' playwright
uv run playwright install chromiumexport PROXY_HOST=proxy.example.com
export PROXY_PORT=8080
export PROXY_USER=USERNAME
export PROXY_PASS=PASSWORD
export BROWSER_USE_API_KEY=YOUR_KEYWe ran the install commands as shown; the second block holds placeholders for your own values. For an ipvolt mobile proxy, they are the host, HTTP port, username and password on the device card. For residential proxies, the host is res.ipvolt.com, the HTTP port is 7000, the username is the one the dashboard builds for your network and country, and the password is your key (residential quickstart).
A complete working example
Save this as agent_proxy.py:
import asyncio
import json
import os
import tempfile
from pathlib import Path
from playwright.async_api import async_playwright
from browser_use import Agent, Browser
PROXY = {
'server': f"http://{os.environ['PROXY_HOST']}:{os.environ['PROXY_PORT']}",
'username': os.environ['PROXY_USER'],
'password': os.environ['PROXY_PASS'],
}
CDP_PORT = 9242
def fresh_profile() -> str:
"""A new Chrome profile in which WebRTC cannot go around the proxy."""
profile = tempfile.mkdtemp(prefix='agent-')
prefs = Path(profile, 'Default', 'Preferences')
prefs.parent.mkdir()
prefs.write_text(json.dumps({'webrtc': {'ip_handling_policy': 'disable_non_proxied_udp'}}))
return profile
async def main():
async with async_playwright() as p:
context = await p.chromium.launch_persistent_context(
fresh_profile(),
headless=True,
proxy=PROXY,
args=[f'--remote-debugging-port={CDP_PORT}'],
)
try:
page = context.pages[0]
await page.goto('https://api.ipify.org')
print('Exit IP, checked by Playwright:', await page.inner_text('body'))
agent = Agent(
'Open https://api.ipify.org in the browser and return only the IP address it shows.',
browser=Browser(cdp_url=f'http://127.0.0.1:{CDP_PORT}'),
)
result = await agent.run()
print('Exit IP, reported by the agent:', result.final_result())
finally:
await context.close()
asyncio.run(main())Run it with uv run agent_proxy.py. The first line comes from Playwright alone, so it confirms the proxy before the model does any work; the second is the agent's answer.
Exit IP, checked by Playwright: 203.0.113.24
Exit IP, reported by the agent: 203.0.113.24What ran: this exact file, against a test proxy that requires a username and password and exits at our own server. With no model API key, a scripted stand-in (a Pydantic AI FunctionModel) took the model's place at run time and returned the page's text; the browser, proxy, CDP connection and agent loop were real. The output shows a documentation address (RFC 5737) in place of our server's. A real model words its own answer.
Three details in the script matter:
fresh_profile()writes one Chrome preference that stops WebRTC from revealing your real address; see WebRTC leaks under Troubleshooting below.- The debugging port is open to every program on the machine, as the docs warn for local browsers; on a shared machine, use a container.
- An agent attached with
cdp_urlleaves the browser running when it ends, socontext.close()stops it.
Rent a mobile proxy for 1 day: Germany, O2, $9
No account needed. Pay with crypto and keep the invoice ID; the order page then shows the host, ports, username and password for the script.
Authentication: HTTP and SOCKS5
Results were the same in Google Chrome 157 and Playwright's Chromium 159:
| Setup | Result |
|---|---|
Playwright proxy with username and password, HTTP proxy | Works, including in tabs the agent opens |
Playwright proxy with username and password, SOCKS5 proxy | Doesn't launch: Browser does not support socks5 proxy authentication |
SOCKS5 proxy without a password, socks5://HOST:PORT | Works |
Credentials in Chrome's flag, --proxy-server=http://USER:PASS@HOST:PORT | net::ERR_NO_SUPPORTED_PROXIES |
--proxy-server without credentials, proxy needs a password | HTTP: net::ERR_INVALID_AUTH_CREDENTIALS; SOCKS5: net::ERR_SOCKS_CONNECTION_FAILED |
Chromium's proxy documentation explains it: Chrome "will not use any credentials embedded in the proxy settings", and "No authentication methods are supported for SOCKSv5 in Chrome", although the protocol has one (RFC 1929). An HTTP proxy's 407 challenge (RFC 9110) needs an answer, which Playwright's launcher gives; its proxy option documents a username and password for HTTP proxies only. Configure a proxy in Playwright covers its other proxy options.
So use the HTTP endpoint when the proxy needs a password. For SOCKS5 with a password, run a local forwarder that adds the credentials:
uv run --with pproxy pproxy -l http://127.0.0.1:8899 -r "socks5://$PROXY_HOST:$PROXY_PORT#$PROXY_USER:$PROXY_PASS"Then run the example with PROXY_HOST=127.0.0.1 and PROXY_PORT=8899; the forwarder never asks for a password. #user:password is pproxy's syntax for a remote login, and the 127.0.0.1 listener keeps others off your proxy. What ran: this exact command against our test SOCKS5 proxy with a password, then agent_proxy.py, which reported the test exit address.
Running it yourself or in Browser Use Cloud
- On your machine (this guide): any proxy Chromium accepts, HTTP or SOCKS5, with the rules above. Browser Use plays no part in the proxy; the browser does.
- Browser Use Cloud:
Browser()with no argument is a Cloud browser with a residential proxy on by default;cloud_proxy_country_code='de'picks another country andNoneturns it off (Browsers: Cloud browser). The Cloud Proxies page makes a custom proxy an enterprise feature that sales enables (projects created before 13 November 2026 keep access), with host, port, an optional username and password, andhttporhttps. It can change a standalone browser's proxy without a restart, and{"rotate": true}asks for a new residential IP in the same country.
The library's Browser() takes only the country code. A custom proxy goes on browsers created through the API, driven with Playwright or another CDP client; attaching one with Browser(cdp_url=...) would follow this guide's pattern. We had no Cloud key, so nothing in Cloud was run.
Rotation and sessions
Two rules:
- A new IP between tasks: start a new browser for each job and change the exit before it starts.
- The same IP while signed in: keep one browser, and one proxy session, for every task that needs the login. Several agents can use it one after another.
Cookies live in the browser profile and the proxy decides the exit, so both must stay the same while an agent is signed in (rotating vs sticky proxies).
import asyncio
import json
import os
import secrets
import tempfile
import urllib.request
from playwright.async_api import async_playwright
from browser_use import Agent, Browser
SERVER = f"http://{os.environ['PROXY_HOST']}:{os.environ['PROXY_PORT']}"
CDP_PORT = 9242
CHECK = 'Open https://api.ipify.org in the browser and return only the IP address it shows.'
def rotate_mobile_ip():
"""Dedicated mobile proxy: ask the device for a new IP with its rotation link."""
with urllib.request.urlopen(os.environ['ROTATION_LINK'], timeout=90) as response:
print('rotation:', json.load(response))
def sticky_username(job: str) -> str:
"""Residential or mobile per GB: a session ID keeps one exit for the whole job."""
return f"{os.environ['PROXY_USER']}-sid-{job}-rot-sticky-ttl-3600"
async def run_job(p, username, tasks):
"""One browser per job: one exit and one cookie jar for every task in it."""
context = await p.chromium.launch_persistent_context(
tempfile.mkdtemp(),
headless=True,
args=[f'--remote-debugging-port={CDP_PORT}'],
proxy={'server': SERVER, 'username': username, 'password': os.environ['PROXY_PASS']},
)
try:
for task in tasks:
result = await Agent(task, browser=Browser(cdp_url=f'http://127.0.0.1:{CDP_PORT}')).run()
print(username, '->', result.final_result())
finally:
await context.close()
async def main():
mobile = os.environ.get('PROXY_KIND', 'mobile') == 'mobile'
async with async_playwright() as p:
for job in range(2):
if mobile:
if job:
rotate_mobile_ip()
username = os.environ['PROXY_USER']
else:
username = sticky_username(f'job{job}_{secrets.token_hex(4)}')
await run_job(p, username, [CHECK, CHECK])
asyncio.run(main())How this maps to the proxy you use:
- Mobile proxy, a dedicated device: one IP at a time, shared by every connection of a signed-in job. Between jobs, call the device's rotation link (
ROTATION_LINK, under More controls in the dashboard where the device has one), or press Rotate IP. Keep automatic rotation off while a job is signed in, and start the next job once a rotation has finished. - Residential or mobile per GB: the session is part of the username. Without a session ID, each connection picks an exit again, and a browser opens many connections per page. Add one:
-sid-NAME-rot-sticky-ttl-3600asks the gateway to keep one exit for an hour, and a new ID starts a new session. IDs are lowercase letters, digits and underscores, up to 64 characters (targeting and sessions).
What ran: rotate.py as shown, with the scripted model, in both modes. Mobile mode ran against our own test HTTP proxy, with a local stand-in for the rotation link; session mode ran against a test proxy that ignores the username. Each job ran two agents in turn in one browser. Real rotations and sessions happen at the proxy and weren't tested here.
Mobile or residential for an agent
Choose by what the agent does; mobile vs residential proxies has a scorecard for testing both.
- A dedicated mobile proxy suits an agent that stays signed in to one account, or needs a named country and carrier. Nobody else uses the device during the rental, and its address is a carrier address, which carriers often share among many subscribers (RFC 6888).
- Residential proxies suit many short, independent jobs across countries, billed per GB, with a sticky session for each job.
- Shared mobile proxies are carrier addresses from a shared pool of modems, billed per GB like residential.
A proxy changes the address and nothing else. It won't help when the block comes from the browser (a headless or automation fingerprint), from behaviour (speed, repetition), or from a login wall or CAPTCHA tied to the account. Test it: run the same task in a normal browser on your own connection. If it's blocked there too, the IP isn't the cause. Cloudflare AI agent blocks: what to fix first works through those cases.
Bandwidth
A browser loads every image, font, script and video on a page, and Chrome adds requests of its own. In our test, Google Chrome left idle for 30 seconds on a blank page opened 21 connections through the proxy in one run and 22 in another, mostly to Google services, and 13 with --disable-background-networking. Playwright's Chromium opened 4 or 5.
- Per-GB plans: all of that counts. Residential costs from $0.60 per GB, in packs from $5. Mobile per GB costs from $3 per GB in the countries of its shared pool. Estimate first with how many GB of proxies do I need, and cut images and fonts with block images and fonts in Playwright. We didn't measure blocking with an agent attached.
- A mobile day rental: priced by time, with no traffic limit, from $9 a day. Heavy pages don't change the price; rent a mobile proxy for 1 day compares it with 30 days.
Troubleshooting
- Proxy authentication required. With Playwright's launcher, a wrong password showed up as
Page.goto: Timeout 30000ms exceededin Chromium 159 and asnet::ERR_HTTP_RESPONSE_CODE_FAILUREin Chrome 157, not as a 407. Check the credentials with one curl request, then read fix proxy error 407. net::ERR_NO_SUPPORTED_PROXIES. Credentials are inside--proxy-server. Pass them to Playwright'sproxyoption, or use the forwarder above.- Tunnel connection failed.
net::ERR_TUNNEL_CONNECTION_FAILEDmeans the proxy refused the CONNECT; fix ERR_TUNNEL_CONNECTION_FAILED reads its answer. A 502 or 503 right after a rotation is covered in tunnel connection failed: 502/503. - Timeouts. Separate a slow proxy from a slow page with diagnose proxy timeouts.
- The proxy seems ignored. The agent's own Python networking (
http_get,requests) runs on your machine: in our test,http_getreturned the machine's address while the page showed the proxy's, as the docs say of Cloud browsers. Say "in the browser" in the task, and check forbrowser=Browser(cdp_url=...): without it,Agentstarts a Cloud browser. For tools that read proxy variables, see proxy environment variables. - DNS leaks. Our proxy logs showed Chrome sending the hostname to the proxy over HTTP and SOCKS5, so destinations aren't looked up locally; Chromium's documentation says so for SOCKS5. socks5 vs socks5h, tested shows clients that differ.
- WebRTC leaks. By default, a page could read the machine's real public IPv4 and IPv6 addresses through WebRTC in both browsers, and the often-quoted switch
--force-webrtc-ip-handling-policy=disable_non_proxied_udpchanged nothing. The profile preferencewebrtc.ip_handling_policyset todisable_non_proxied_udp, whichfresh_profile()writes, removed every candidate. It is the setting behind Chrome's WebRtcIPHandling policy, the "force proxy" mode of RFC 8828. Check with IP, DNS and WebRTC leak checks or our proxy checker.
Questions
How do I set up a proxy in Browser Use?
Start Chromium with Playwright's proxy option and a debugging port, then pass Browser(cdp_url='http://127.0.0.1:9242') to the agent.
Does Browser Use support SOCKS5 proxies?
Yes, without a password: socks5://HOST:PORT. Chromium can't send SOCKS5 credentials, so use the HTTP endpoint or a local forwarder.
Can I use a residential proxy with Browser Use?
Yes. A Browser Use residential proxy uses the same script: the gateway in the proxy option and a sticky session ID in the username, so the exit holds while the agent is signed in.
Can I use a mobile proxy with Browser Use?
Yes. A Browser Use mobile proxy takes the device's HTTP port, username and password; rotate its carrier IP between tasks.
What is the best proxy for AI agents?
It depends on the task: a dedicated mobile proxy for long signed-in sessions or a named carrier, residential for many short jobs across countries. No proxy fixes a fingerprint block.
Does Browser Use Cloud include a proxy?
Yes, a residential proxy, in the United States unless you choose another country. A custom proxy there is an enterprise feature.
Why does the agent still show my real IP?
Usually the request didn't come from the browser: the agent's Python helpers run on your machine. Ask for the page in the browser, and block WebRTC with fresh_profile().
Put your agent on a carrier IP. A dedicated ipvolt mobile proxy costs from $9 a day, with no traffic limit, over HTTP and SOCKS5. The free Proxy Toolkit MCP gives a coding agent proxy configurations, error diagnostics and these guides. Per GB, residential proxies cost from $0.60 per GB, in packs from $5. Compare every option on Pricing, and test any proxy with the proxy checker. Agents can also rent through the API and top up with their own USDC.
Rent a mobile proxy for 1 day: Germany, O2, $9
No account needed.
Sources & further reading
Technical references used for this guide. Check the documentation for your installed version and your provider’s supported configuration.
- Browser Use: Browsers (cloud, local Chromium, any CDP endpoint)
- Browser Use: Examples, Combine with Playwright
- Browser Use: Quickstart
- Browser Use: Models
- Browser Use: Migrating from 0.x (proxy: local dropped for now)
- Browser Use Cloud: Proxies
- Browser Use Cloud: Playwright, Puppeteer, Selenium
- browser-use 1.0.6 source: ProxySettings removal note (legacy.py)
- browser-use 1.0.6 source: local Chrome launch flags (browser/local.py)
- browser-harness: the engine inside Browser Use
- Chrome DevTools Protocol
- Playwright for Python: BrowserType.launch_persistent_context (proxy, args)
- Chromium: proxy support in Chrome
- Chromium policy definition: WebRtcIPHandling
- RFC 8828: WebRTC IP Address Handling Requirements, section 5.2
- RFC 1929: Username/Password Authentication for SOCKS V5
- RFC 9110: 407 Proxy Authentication Required
- RFC 6888: Common Requirements for Carrier-Grade NATs
- RFC 5737: IPv4 Address Blocks Reserved for Documentation
- pproxy (python-proxy)