# How to use a proxy with Browser Use

Source: https://ipvolt.com/guides/browser-use-proxy-setup
Markdown: https://ipvolt.com/guides/browser-use-proxy-setup.md

[Home](https://ipvolt.com/index.md) / [Guides](https://ipvolt.com/guides.md) / [How to use a proxy with Browser Use](https://ipvolt.com/guides/browser-use-proxy-setup.md)

Category: Integration
Published: 2026-11-18
Reading time: 11 minutes
Author: ipvolt

Add an HTTP or SOCKS5 proxy to a Browser Use 1.0 agent: a tested Playwright setup, why SOCKS5 passwords fail, rotation, sticky sessions and leak checks.

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](https://chromedevtools.github.io/devtools-protocol/) that [browser-harness](https://github.com/browser-use/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:

```python
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](https://docs.browser-use.com/open-source/browsers) says "Local: not yet", and `ProxySettings` now raises ["Browser('chromium') has no proxy yet"](https://github.com/browser-use/browser-use/blob/1.0.6/browser_use/legacy.py#L211). Attaching with `cdp_url` is the documented way to drive [any browser with a CDP endpoint](https://docs.browser-use.com/open-source/browsers#any-cdp-endpoint), as in the docs' own [Playwright example](https://docs.browser-use.com/open-source/examples#combine-with-playwright). This guide covers 1.0 only.

## What you need

- Python 3.11 or newer and uv, as in the [Browser Use quickstart](https://docs.browser-use.com/open-source/quickstart).
- A proxy: host, port, username and password. The commands below use placeholders.
- A key for the model. By default `Agent` runs Browser Use's own model and reads `BROWSER_USE_API_KEY`; [other models](https://docs.browser-use.com/open-source/models) go in `llm=`.

```sh
uv init --python 3.12 browser-use-proxy && cd browser-use-proxy
uv add 'browser-use==1.0.6' playwright
uv run playwright install chromium
```

```sh
export PROXY_HOST=proxy.example.com
export PROXY_PORT=8080
export PROXY_USER=USERNAME
export PROXY_PASS=PASSWORD
export BROWSER_USE_API_KEY=YOUR_KEY
```

We ran the install commands as shown; the second block holds placeholders for your own values. For an ipvolt [mobile proxy](/mobile-proxies), they are the host, HTTP port, username and password on the device card. For [residential proxies](/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](/docs/residential-quickstart)).

## A complete working example

Save this as `agent_proxy.py`:

```python
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.

```text
Exit IP, checked by Playwright: 203.0.113.24
Exit IP, reported by the agent: 203.0.113.24
```

What 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](https://www.rfc-editor.org/rfc/rfc5737.html)) 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](https://docs.browser-use.com/open-source/browsers#local-chromium); on a shared machine, use a container.
- An agent attached with `cdp_url` leaves the browser running when it ends, so `context.close()` stops it.

[Rent a mobile proxy for 1 day: Germany, O2, $9](/dashboard/mobile?country=DE&plan=day&carrier=O2)

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](https://chromium.googlesource.com/chromium/src/+/HEAD/net/docs/proxy.md) 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](https://www.rfc-editor.org/rfc/rfc1929.html)). An HTTP proxy's 407 challenge ([RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-407-proxy-authentication-re)) needs an answer, which Playwright's launcher gives; its [proxy option](https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch-persistent-context) documents a username and password for HTTP proxies only. [Configure a proxy in Playwright](/guides/playwright-proxy-setup) 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:

```sh
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](https://github.com/qwj/python-proxy) 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 and `None` turns it off ([Browsers: Cloud browser](https://docs.browser-use.com/open-source/browsers#cloud-browser)). The Cloud [Proxies page](https://docs.browser-use.com/cloud/browser/proxies) 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, and `http` or `https`. 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](https://docs.browser-use.com/cloud/browser/playwright-puppeteer-selenium); 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](/guides/rotating-vs-sticky-proxies)).

```python
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](/docs/rotation) (`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-3600` asks 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](/docs/residential-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](/guides/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](https://www.rfc-editor.org/rfc/rfc6888.html)).
- **Residential proxies** suit many short, independent jobs across countries, billed per GB, with a sticky session for each job.
- **[Shared mobile proxies](/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](/blog/cloudflare-ai-agent-proxy-setup) 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](/blog/how-many-gb-of-proxies-do-i-need), and cut images and fonts with [block images and fonts in Playwright](/guides/playwright-block-images-save-bandwidth). 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](/blog/mobile-proxy-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 exceeded` in Chromium 159 and as `net::ERR_HTTP_RESPONSE_CODE_FAILURE` in Chrome 157, not as a 407. Check the credentials with one curl request, then read [fix proxy error 407](/guides/fix-proxy-error-407).
- **`net::ERR_NO_SUPPORTED_PROXIES`.** Credentials are inside `--proxy-server`. Pass them to Playwright's `proxy` option, or use the forwarder above.
- **Tunnel connection failed.** `net::ERR_TUNNEL_CONNECTION_FAILED` means the proxy refused the CONNECT; [fix ERR_TUNNEL_CONNECTION_FAILED](/guides/fix-err-tunnel-connection-failed) reads its answer. A 502 or 503 right after a rotation is covered in [tunnel connection failed: 502/503](/guides/fix-proxy-tunnel-502-503).
- **Timeouts.** Separate a slow proxy from a slow page with [diagnose proxy timeouts](/guides/proxy-timeout-troubleshooting).
- **The proxy seems ignored.** The agent's own Python networking (`http_get`, `requests`) runs on your machine: in our test, `http_get` returned 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 for `browser=Browser(cdp_url=...)`: without it, `Agent` starts a Cloud browser. For tools that read proxy variables, see [proxy environment variables](/guides/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](/blog/socks5-vs-socks5h) 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_udp` changed nothing. The profile preference `webrtc.ip_handling_policy` set to `disable_non_proxied_udp`, which `fresh_profile()` writes, removed every candidate. It is the setting behind Chrome's [WebRtcIPHandling policy](https://chromium.googlesource.com/chromium/src/+/HEAD/components/policy/resources/templates/policy_definitions/WebRtc/WebRtcIPHandling.yaml), the "force proxy" mode of [RFC 8828](https://www.rfc-editor.org/rfc/rfc8828.html#section-5.2). Check with [IP, DNS and WebRTC leak checks](/blog/proxy-leak-check-todetect) or our [proxy checker](/tools/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](/mcp) gives a coding agent proxy configurations, error diagnostics and these guides. Per GB, [residential proxies](/residential-proxies) cost from $0.60 per GB, in packs from $5. Compare every option on [Pricing](/pricing), and test any proxy with the [proxy checker](/tools/proxy-checker). Agents can also [rent through the API](/docs/ai-agents) and top up with their own USDC.

[Rent a mobile proxy for 1 day: Germany, O2, $9](/dashboard/mobile?country=DE&plan=day&carrier=O2)

No account needed.

## Sources & further reading

- [Browser Use: Browsers (cloud, local Chromium, any CDP endpoint)](https://docs.browser-use.com/open-source/browsers)
- [Browser Use: Examples, Combine with Playwright](https://docs.browser-use.com/open-source/examples#combine-with-playwright)
- [Browser Use: Quickstart](https://docs.browser-use.com/open-source/quickstart)
- [Browser Use: Models](https://docs.browser-use.com/open-source/models)
- [Browser Use: Migrating from 0.x (proxy: local dropped for now)](https://docs.browser-use.com/open-source/migrating)
- [Browser Use Cloud: Proxies](https://docs.browser-use.com/cloud/browser/proxies)
- [Browser Use Cloud: Playwright, Puppeteer, Selenium](https://docs.browser-use.com/cloud/browser/playwright-puppeteer-selenium)
- [browser-use 1.0.6 source: ProxySettings removal note (legacy.py)](https://github.com/browser-use/browser-use/blob/1.0.6/browser_use/legacy.py#L211)
- [browser-use 1.0.6 source: local Chrome launch flags (browser/local.py)](https://github.com/browser-use/browser-use/blob/1.0.6/browser_use/browser/local.py#L332)
- [browser-harness: the engine inside Browser Use](https://github.com/browser-use/browser-harness)
- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)
- [Playwright for Python: BrowserType.launch_persistent_context (proxy, args)](https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch-persistent-context)
- [Chromium: proxy support in Chrome](https://chromium.googlesource.com/chromium/src/+/HEAD/net/docs/proxy.md)
- [Chromium policy definition: WebRtcIPHandling](https://chromium.googlesource.com/chromium/src/+/HEAD/components/policy/resources/templates/policy_definitions/WebRtc/WebRtcIPHandling.yaml)
- [RFC 8828: WebRTC IP Address Handling Requirements, section 5.2](https://www.rfc-editor.org/rfc/rfc8828.html#section-5.2)
- [RFC 1929: Username/Password Authentication for SOCKS V5](https://www.rfc-editor.org/rfc/rfc1929.html)
- [RFC 9110: 407 Proxy Authentication Required](https://www.rfc-editor.org/rfc/rfc9110.html#name-407-proxy-authentication-re)
- [RFC 6888: Common Requirements for Carrier-Grade NATs](https://www.rfc-editor.org/rfc/rfc6888.html)
- [RFC 5737: IPv4 Address Blocks Reserved for Documentation](https://www.rfc-editor.org/rfc/rfc5737.html)
- [pproxy (python-proxy)](https://github.com/qwj/python-proxy)

## Related guides

- [Configure a proxy in Playwright](https://ipvolt.com/guides/playwright-proxy-setup.md)
- [Rotating vs sticky proxies: plan for session continuity](https://ipvolt.com/guides/rotating-vs-sticky-proxies.md)
- [Mobile vs residential proxies: build a useful evaluation](https://ipvolt.com/guides/mobile-vs-residential-proxies.md)
- [Fix proxy error 407 without guessing](https://ipvolt.com/guides/fix-proxy-error-407.md)
- [Block Images, Fonts and Media in Playwright to Cut Proxy Bandwidth](https://ipvolt.com/guides/playwright-block-images-save-bandwidth.md)

## About ipvolt

Examples use generic proxy settings, with links to the original technical documentation. Product-specific behavior must be checked with your provider. ipvolt sells mobile proxies and residential proxies from $0.60/GB.

Also in: [Русский](https://ipvolt.com/ru/guides/browser-use-proxy-setup.md) · [Español](https://ipvolt.com/es/guides/browser-use-proxy-setup.md) · [中文](https://ipvolt.com/zh/guides/browser-use-proxy-setup.md)

**Plug in your first proxy.**

Mobile from $9 a day. Residential from $0.60 per GB, in packs from $5.

[Buy mobile](https://ipvolt.com/dashboard/mobile)

[Buy residential](https://ipvolt.com/dashboard/residential)

