Browser Use Proxy: Run an Agent Through an HTTP Proxy

The current Browser Use proxy API

Browser Use documents the proxy as a parameter of the browser: proxy takes a ProxySettings object with server, username, password and bypass. Browser is an alias for BrowserSession, so Browser(proxy=...) is the whole setup.

BrowserConfig, which older tutorials import, comes from older releases and is not in the current API; code that imports it fails with an ImportError. Use the example below instead.

• Sources:
• Browser Use docs: all parameters
• Browser Use source: browser/profile.py

Browser Use with ProxySettings: check the exit first

import asyncio
import os
from browser_use import Agent, Browser, ChatOpenAI
from browser_use.browser.profile import ProxySettings

browser = Browser(
    proxy=ProxySettings(
        server=f"http://{os.environ['PROXY_HOST']}:{os.environ['PROXY_PORT']}",  # HTTP endpoint
        username=os.environ["PROXY_USER"],
        password=os.environ["PROXY_PASS"],
        bypass="localhost,127.0.0.1",  # optional
    )
)


async def main():
    agent = Agent(
        task=(
            "Open https://ipinfo.io/json and report the IP address and country it shows. "
            "Then continue with the real task."
        ),
        llm=ChatOpenAI(model=os.environ["LLM_MODEL"]),
        browser=browser,
    )
    history = await agent.run()
    print(history.final_result())


asyncio.run(main())

Example only: replace the environment variables with your own values. The task asks the agent to report the exit IP and country before it does anything else.

• Sources:
• Browser Use docs: all parameters

Why check the exit first

The first step turns "the proxy is configured" into "the agent's browser really shows the country I chose". Do it at the start of every run, and compare the country with the one you chose when you generated the proxy.

bypass is a comma-separated list of hosts that do not go through the proxy, for example localhost,127.0.0.1. Leave it out if you do not need it.

One proxy per agent

Give each agent its own Browser with its own ProxySettings, and run the agents together with asyncio.gather. A proxy belongs to the browser it was set on, so two agents never share an exit by accident. Browser Use's own parallel example is marked experimental, so keep one agent per Browser object.

• Sources:
• Browser Use docs: all parameters

Two agents, two proxies, run in parallel

import asyncio
import os
from browser_use import Agent, Browser, ChatOpenAI
from browser_use.browser.profile import ProxySettings


def make_browser(host_env, port_env, user_env, pass_env):
    return Browser(
        proxy=ProxySettings(
            server=f"http://{os.environ[host_env]}:{os.environ[port_env]}",
            username=os.environ[user_env],
            password=os.environ[pass_env],
        )
    )


async def run_one(task, browser):
    agent = Agent(task=task, llm=ChatOpenAI(model=os.environ["LLM_MODEL"]), browser=browser)
    return await agent.run()


async def main():
    de = make_browser("DE_HOST", "DE_PORT", "DE_USER", "DE_PASS")
    jp = make_browser("JP_HOST", "JP_PORT", "JP_USER", "JP_PASS")
    results = await asyncio.gather(
        run_one("Open https://ipinfo.io/json and report the IP and country", de),
        run_one("Open https://ipinfo.io/json and report the IP and country", jp),
    )
    for history in results:
        print(history.final_result())


asyncio.run(main())

Example only: replace the placeholder values with your own.

The same proxy in plain Playwright

Browser Use drives Chromium through Playwright, so Playwright's own proxy options are worth knowing. The proxy can be set for the whole browser in launch, or for one browser context in new_context (newContext in Node.js), and the options are server, bypass, username and password.

The Playwright option reference says username and password are for HTTP proxies. So an authenticated SOCKS5 proxy is not a Chromium option: use the HTTP endpoint. On Proxy302 that is proxy.proxy302.com port 2222; SOCKS5 is port 3333.

• Sources:
• Playwright docs: Network, HTTP proxy
• Playwright docs: proxy option reference

Playwright for Python: launch-level and per-context proxy

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    # Proxy for the whole browser
    browser = p.chromium.launch(
        proxy={
            "server": "http://HOST:PORT",
            "username": "USERNAME",
            "password": "PASSWORD",
            "bypass": "localhost,127.0.0.1",
        }
    )
    page = browser.new_page()
    page.goto("https://ipinfo.io/json")
    print(page.inner_text("body"))
    browser.close()

    # Or one proxy per context
    browser = p.chromium.launch()
    context = browser.new_context(
        proxy={"server": "http://HOST:PORT", "username": "USERNAME", "password": "PASSWORD"}
    )
    page = context.new_page()
    page.goto("https://ipinfo.io/json")
    print(page.inner_text("body"))
    browser.close()

Example only: replace the placeholder values with your own.

• Sources:
• Playwright docs: Network, HTTP proxy

Playwright for Node.js: launch-level and per-context proxy

import { chromium } from 'playwright';

// Proxy for the whole browser
const browser = await chromium.launch({
  proxy: {
    server: 'http://HOST:PORT',
    username: 'USERNAME',
    password: 'PASSWORD',
    bypass: 'localhost,127.0.0.1',
  },
});
const page = await browser.newPage();
await page.goto('https://ipinfo.io/json');
console.log(await page.innerText('body'));
await browser.close();

// Or one proxy per context
const browser2 = await chromium.launch();
const context = await browser2.newContext({
  proxy: { server: 'http://HOST:PORT', username: 'USERNAME', password: 'PASSWORD' },
});
const page2 = await context.newPage();
await page2.goto('https://ipinfo.io/json');
console.log(await page2.innerText('body'));
await browser2.close();

Example only: replace the placeholder values with your own.

• Sources:
• Playwright docs: Network, HTTP proxy

Playwright MCP

If you drive the browser through the Playwright MCP server instead of Python code, the equivalents are the --proxy-server and --proxy-bypass arguments. The README puts the credentials in the proxy URL: http://user:password@host:port. If the password has special characters such as @, : or /, percent-encode them.

The same README lists SOCKS5 in the URL form, but as with Playwright above, use the HTTP endpoint when you need a username and password.

• Sources:
• Playwright MCP README

Playwright MCP with a proxy: mcpServers entry

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--proxy-server",
        "http://USER:PASS@HOST:PORT",
        "--proxy-bypass",
        "localhost,127.0.0.1"
      ]
    }
  }
}

Example only: replace the placeholder values with your own.

• Sources:
• Playwright MCP README

Fetching a page through a proxy from an MCP client

If you only need an agent to read a public page through a Proxy302 proxy, without running a browser, see the proxy-mcp-server guide. proxy302-mcp is the official Proxy302 MCP server, open source on GitHub and maintained by the Proxy302 team. Proxy302 also runs it at https://proxy302.com/v1/mcp: clients that can send an Authorization header, such as Claude Code, Cursor and VS Code, connect with an API key and install nothing.

• proxy-mcp-server

• Sources:
• proxy302-mcp README (official Proxy302 MCP server)

Time zone and language for the exit region

Some sites show a different currency, language or shipping text depending on where the visitor appears to be. To see the local version of a page, set the browser's language and time zone to the exit region as well as the proxy.

Playwright's context options for this are locale (a language tag such as de-DE) and timezone_id (a time zone ID such as Europe/Berlin; timezoneId in Node.js). Both are listed in the official options. They change what the browser reports; the proxy changes the address.

• Sources:
• Playwright for Python: Browser.new_context
• Playwright docs: Emulation, locale and timezone

Python: proxy, locale and time zone in one context

context = browser.new_context(
    proxy={"server": "http://HOST:PORT", "username": "USERNAME", "password": "PASSWORD"},
    locale="de-DE",
    timezone_id="Europe/Berlin",
)

Example only: replace the placeholder values with your own.

• Sources:
• Playwright for Python: Browser.new_context

Node.js: proxy, locale and time zone in one context

const context = await browser.newContext({
  proxy: { server: 'http://HOST:PORT', username: 'USERNAME', password: 'PASSWORD' },
  locale: 'de-DE',
  timezoneId: 'Europe/Berlin',
});

Example only: replace the placeholder values with your own.

• Sources:
• Playwright docs: Emulation, locale and timezone

Measured exits seen from Amazon

Hourly check of the Proxy302 probe, 3 November 2026, 18:18 UTC: one request to Amazon per country through a rotating residential exit. Only the first three octets of an IP are public. One sample per country, not an average; later checks will differ.

• Sources:
• Proxy302 hourly connectivity check

Common errors and fixes

What to use it for

Typical uses are reading public pages, checking how a page looks in another region, QA of a localized site, and collecting data in line with the site's terms and rate limits. A proxy changes only the network address a service sees; keep your request rate polite and follow each site's rules.

How to do it with Proxy302

Rotating residential fits agents that read many pages or check several regions: pick the country, generate a proxy as HTTP, and use proxy.proxy302.com port 2222. A static ISP IP fits an agent that signs in to an account and needs one fixed address. See the rotating residential page for the product.

• rotating residential proxies

How to do it with Proxy302: steps

1. Step 1

   Open the rotating residential page (or the static ISP page), choose the country and the protocol HTTP, and generate the proxy.

2. Step 2

   Open My assets (the console page that holds everything you bought) and copy HOST, PORT, USERNAME and PASSWORD. The Connect page shows a ready example with your own endpoint.

3. Step 3

   Put them into ProxySettings, the Playwright proxy option or the MCP argument.

4. Step 4

   Run the exit check: ask the agent to open https://ipinfo.io/json and report the IP and country. The country should match the one you chose.

5. Step 5

   From mainland China, open the Helper from the Connect page, click 「一键加速」 (One-click boost) and keep it open while you use the proxy.

   • Helper tool guide

Prices and limits

Rotating residential costs from US$1.50 per GB on the Budget line and US$5 per GB on the Premium line, less in larger packages. A static ISP IP costs US$0.50 for one day and US$7.99 for 30 days. There is no free trial: the smallest purchase is 1 GB or one IP for one day. A proxy does not lift a restriction, undo a ban or raise a limit.

• Sources:
• Proxy302 product facts and price list

Proxy302 at a glance

Prices are in PTC, paid from the wallet; 1 PTC = US$1. There is no free trial: the smallest purchase is 1 GB of rotating residential traffic or one IP for one day. Checked on 4 November 2026.

• Sources:
• Proxy302 product facts and price list
• Proxy302 ISP for AI subscriptions: public catalog

FAQ

Read next

Playwright proxies

Playwright proxy setup with username and password: static datacenter IPs for tests and CI, rotating residential from US$1.50/GB when a site blocks servers.

View options and pricing

Proxy MCP server for AI coding tools

What a proxy MCP server is, how local and remote MCP servers differ, how to install one in Claude Code, Codex CLI and Cursor, and how to route the server's own traffic through a proxy.

Residential, ISP or Datacenter: Which Proxy an AI Agent Needs

Rotating residential, static ISP and datacenter proxies in plain words, matched to four agent tasks: research, signing in, API calls and data collection.

Rotating residential proxies

Real household IPs in 195+ countries with state and city targeting. Rotate on every request or keep sticky sessions. From US$1.50/GB, US$1.35/GB at 100 GB. HTTP and SOCKS5.

View options and pricing

Check a proxy's IP, country and ISP

Check the exit IP, country and ISP your proxy really gives you in 30 seconds — and why IP databases disagree on the city. With our own test of three lookup services.