How to Use Custom Proxies with Browser Use

Browser Use Cloud supports managed residential proxies and bring-your-own (BYO) proxies. With BYO, you supply a third-party provider's connection details when creating an agent run or cloud browser, giving you control over the provider, exit location, and session settings.

In this tutorial, we'll connect a third-party proxy to Browser Use Cloud, check the browser's exit IP and country, and use the same credentials with Playwright. You'll need Python 3.10 or newer, access to a proxy provider, and a Browser Use API key for the cloud examples.

TL;DR

1. Get your proxy credentials.
2. Connect to Browser Use.
3. Check the exit IP and country.
4. Use the proxy with Playwright.

Managed vs. BYO Proxies

Proxy traffic can cost much more than the browser time itself. For bandwidth-heavy jobs, that makes the proxy rate an important part of the infrastructure bill. Agent and model charges are separate.

Browser Use pricing lists browser time at $0.02/hour. Prepaid residential options in our proxy-provider comparison include rates around $1-$4/GB. Using that range, one browser-hour plus 1 GB would cost about $1.22-$4.22 with BYO, including Browser Use egress, versus $5.02 with the managed proxy.

How It Works

Your Python script sends a task and browser settings to Browser Use. The cloud browser then connects to your proxy provider, which forwards its website requests through the selected exit. The destination sees that exit IP.

Select the exit country through your provider. A custom proxy overrides Browser Use's managed proxyCountryCode setting; browser locale and timezone don't select the proxy exit.

We'll start with a hosted agent, then use Playwright locally and with a cloud browser. The open-source browser-use library uses a separate configuration interface.

Get Your Proxy Credentials

Get the following connection details from your proxy provider:

• Proxy hostname
• Proxy port
• Proxy protocol (HTTP/S)
• Username
• Password

Select the exit country with your provider. For multi-step tasks, choose a sticky IP or session if available to keep requests on the same exit IP. Check the session duration; a sticky IP isn't necessarily permanent.

In your project directory, create a virtual environment and install the dependencies:

$ python3 -m venv venv
$ source venv/bin/activate
(venv)$ python -m pip install browser-use-sdk==3.12.1 playwright==1.62.0 python-dotenv==1.2.2

Create a .env file with your connection details:

BROWSER_USE_API_KEY=your_browser_use_api_key
PROXY_HOST=proxy.example.com
PROXY_PORT=12345
PROXY_PROTOCOL=http
PROXY_USERNAME=your_complete_proxy_username
PROXY_PASSWORD=your_proxy_password

Replace the placeholder host and port with your provider's values. Copy the complete username, including any country or session parameters. Keep PROXY_HOST as a bare hostname. PROXY_PROTOCOL describes the connection to the proxy, so an HTTP proxy can still carry requests to an HTTPS website.

Keep .env private and out of version control. The scripts load it with python-dotenv; credentials should never go in agent tasks or logs.

Connect to Browser Use

Save the following as browser_use_proxy.py beside .env. It creates a hosted agent run with browserSettings.customProxy, waits for the result, and stops its browser afterward.

The task opens ipwho.is, an IP geolocation checker independent of your proxy provider. Its JSON response includes success, ip, and country_code.

import os
 
from browser_use_sdk.v4 import BrowserUse
from dotenv import load_dotenv
 
load_dotenv()
 
proxy = {
    "host": os.environ["PROXY_HOST"],
    "port": int(os.environ["PROXY_PORT"]),
    "protocol": os.getenv("PROXY_PROTOCOL", "http"),
    "username": os.environ["PROXY_USERNAME"],
    "password": os.environ["PROXY_PASSWORD"],
}
 
with BrowserUse() as client:
    run = client.runs.create(
        "Use only the browser to open https://ipwho.is/. "
        "Return only a JSON object containing ip and country_code.",
        model="bu-fast",
        browser_settings={"customProxy": proxy},
        max_cost_usd=0.50,
    )
 
    try:
        result = client.runs.wait_for_completion(run.id, timeout=180)
        print(result.result)
 
    except (Exception, KeyboardInterrupt):
        client.runs.cancel(run.id)
        raise
 
    finally:
        browsers = client.browsers.list(agent_session_id=run.session_id)
 
        for browser in browsers.items:
            if browser.status.value == "active":
                client.browsers.stop(browser.id)

Run the script:

(venv)$ python browser_use_proxy.py

The Python SDK reads BROWSER_USE_API_KEY from your environment and handles polling. max_cost_usd limits model and search charges; browser and network charges are separate. If the wait fails or you interrupt it, the script attempts cancellation before stopping its browser.

Check the Exit IP and Country

Open the run in Browser Use and inspect the browser action that loaded https://ipwho.is/. Compare the page's ip and country_code with the script's output. Our test returned:

{
  "ip": "24.140.205.193",
  "country_code": "US"
}

Your IP will differ.

Check the browser's page, not just the agent's completion status. A curl or requests call from your laptop checks your laptop's route instead of the cloud browser's.

To switch countries, update the provider's connection details in .env, then rerun and check the reported country. Other websites may classify the same IP differently.

Use the Proxy with Playwright

The same credentials work with a local Playwright browser or Browser Use Browser Infrastructure. Choose either example below; each is a complete script.

Configure a Playwright Proxy in Python

Install Chromium for the local example:

(venv)$ python -m playwright install chromium

Save this as playwright_proxy.py beside .env:

import json
import os
 
from dotenv import load_dotenv
from playwright.sync_api import sync_playwright
 
load_dotenv()
 
proxy = {
    "server": (
        f"{os.getenv('PROXY_PROTOCOL', 'http')}://"
        f"{os.environ['PROXY_HOST']}:{os.environ['PROXY_PORT']}"
    ),
    "username": os.environ["PROXY_USERNAME"],
    "password": os.environ["PROXY_PASSWORD"],
}
 
with sync_playwright() as pw:
    browser = pw.chromium.launch(proxy=proxy)
 
    try:
        page = browser.new_page()
        page.goto("https://ipwho.is/", timeout=30_000)
 
        data = json.loads(page.locator("body").inner_text())
 
        print(json.dumps({
            "ip": data["ip"],
            "country_code": data["country_code"],
        }, indent=2))
 
    finally:
        browser.close()

Run the script:

(venv)$ python playwright_proxy.py

The script prints the browser's exit IP and country so you can compare them with your provider's settings.

For Playwright proxy authentication, put the username and password inside proxy. The separate http_credentials option authenticates to the destination website.

Connect Playwright to Browser Use

For a cloud browser, save this as playwright_cloud_proxy.py beside .env. It creates a browser with customProxy, connects through connect_over_cdp(), and checks the exit. You don't need to install local Chromium for this version.

import json
import os
 
from browser_use_sdk.v4 import BrowserUse, CustomProxy
from dotenv import load_dotenv
from playwright.sync_api import sync_playwright
 
load_dotenv()
 
proxy = CustomProxy(
    host=os.environ["PROXY_HOST"],
    port=int(os.environ["PROXY_PORT"]),
    protocol=os.getenv("PROXY_PROTOCOL", "http"),
    username=os.environ["PROXY_USERNAME"],
    password=os.environ["PROXY_PASSWORD"],
)
 
with BrowserUse() as client:
    session = client.browsers.create(custom_proxy=proxy, timeout=3)
 
    try:
        with sync_playwright() as pw:
            browser = pw.chromium.connect_over_cdp(session.cdp_url)
            page = browser.contexts[0].new_page()
            page.goto("https://ipwho.is/", timeout=30_000)
 
            data = json.loads(page.locator("body").inner_text())
 
            print(json.dumps({
                "ip": data["ip"],
                "country_code": data["country_code"],
            }, indent=2))
 
    finally:
        client.browsers.stop(session.id)

Run the script:

(venv)$ python playwright_cloud_proxy.py

The SDK's custom_proxy argument sets the proxy when creating the browser. Agent runs use browser_settings={"customProxy": proxy} instead. Connecting over CDP attaches to the browser you already configured.

Here, timeout limits the cloud browser's lifetime to three minutes. The finally block also stops it explicitly: closing the CDP connection alone doesn't stop the cloud browser.

Troubleshooting

Start with the proxy credentials and endpoint, then check the browser configuration and destination.

In our local tests, a bad password and an unreachable proxy port both caused timeouts. Check credentials and connectivity when diagnosing a timeout; authentication failures don't always produce a visible 407.

Production Tips

For multi-step tasks, preserve browser cookies and storage alongside the proxy session. A sticky IP alone won't preserve a login or ensure separate browsers share an exit.

Bound retries and stop unused browsers. Compare both services' bandwidth bills; failed requests and repeated page loads can consume traffic too.

If a creation request times out before returning an ID, inspect the dashboard before retrying to avoid starting duplicate work.

Conclusion

You now have a setup for connecting a third-party proxy to Browser Use, checking the browser's exit IP and country, and using it with Playwright. Start with a small read-only task on the website you actually need, then build on the working setup.

Sources and further reading:

• Browser Use: Proxies covers managed and custom proxies, authentication, and proxy settings.
• Browser Use: Quick Start covers API keys, SDK setup, and your first run.
• Browser Use: Playwright, Puppeteer, Selenium shows how to connect to a cloud browser over CDP and stop it when finished.