Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.
Python ai-agentsai-toolsbrowser-agentbrowser-automationbrowser-usecdpcloud-browsercomputer-useheadless-browserllmmcpplaywrightpythonremote-browserstealth-browserweb-automationweb-scraping
Add authenticated proxy support
matt-greathouse4e0ce78f4338
diff --git a/browser_use/browser/profile.py b/browser_use/browser/profile.pyindex 2aedc9129..e7e4ab43a 100644--- a/browser_use/browser/profile.py+++ b/browser_use/browser/profile.py@@ -592,6 +592,22 @@ class BrowserProfile(BrowserConnectArgs, BrowserLaunchPersistentContextArgs, Brodescription='List of allowed domains for navigation e.g. ["*.google.com", "https://example.com", "chrome-extension://*"]',)keep_alive: bool | None = Field(default=None, description='Keep browser alive after agent run.')++ # --- Proxy settings ---+ proxy_server: str | None = Field(+ default=None,+ description='Proxy server URL for Chromium traffic. Example: http://proxy.local:8080 or socks5://host:1080',+ )+ proxy_bypass_list: list[str] | None = Field(+ default=None,+ description='Hosts/patterns to bypass proxy, e.g. ["localhost", "127.0.0.1", "*.internal"]',+ )+ proxy_pac_url: str | None = Field(+ default=None,+ description='Proxy PAC URL (mutually exclusive with proxy_server).',+ )+ proxy_username: str | None = Field(default=None, description='Proxy auth username (for authenticated proxies).')+ proxy_password: str | None = Field(default=None, description='Proxy auth password (for authenticated proxies).')enable_default_extensions: bool = Field(default=True,description="Enable automation-optimized extensions: ad blocking (uBlock Origin), cookie handling (I still don't care about cookies), and URL cleaning (ClearURLs). All extensions work automatically without manual intervention. Extensions are automatically downloaded and loaded when enabled.",@@ -716,6 +732,13 @@ class BrowserProfile(BrowserConnectArgs, BrowserLaunchPersistentContextArgs, Bro)return self+ @model_validator(mode='after')+ def validate_proxy_settings(self) -> Self:+ """Ensure proxy configuration is consistent."""+ if self.proxy_server and self.proxy_pac_url:+ raise ValueError('proxy_server and proxy_pac_url cannot both be set. Choose one.')+ return self+def get_args(self) -> list[str]:"""Get the list of all Chrome CLI launch args for this profile (compiled from defaults, user-provided, and system-specific)."""@@ -751,6 +774,14 @@ class BrowserProfile(BrowserConnectArgs, BrowserLaunchPersistentContextArgs, Bro*(self._get_extension_args() if self.enable_default_extensions else []),]+ # Proxy flags+ if self.proxy_server and not self.proxy_pac_url:+ pre_conversion_args.append(f'--proxy-server={self.proxy_server}')+ if self.proxy_bypass_list:+ pre_conversion_args.append(f'--proxy-bypass-list={",".join(self.proxy_bypass_list)}')+ elif self.proxy_pac_url and not self.proxy_server:+ pre_conversion_args.append(f'--proxy-pac-url={self.proxy_pac_url}')+# convert to dict and back to dedupe and merge duplicate argsfinal_args_list = BrowserLaunchArgs.args_as_list(BrowserLaunchArgs.args_as_dict(pre_conversion_args))return final_args_listdiff --git a/browser_use/browser/session.py b/browser_use/browser/session.pyindex 3b1b1f8e9..2c4643a13 100644--- a/browser_use/browser/session.py+++ b/browser_use/browser/session.py@@ -1003,6 +1003,9 @@ class BrowserSession(BaseModel):if self.agent_focus:self._cdp_session_pool[target_id] = self.agent_focus+ # Enable proxy authentication handling if configured+ await self._setup_proxy_auth()+# Verify the session is workingtry:if self.agent_focus:@@ -1038,6 +1041,82 @@ class BrowserSession(BaseModel):return self+ async def _setup_proxy_auth(self) -> None:+ """Enable CDP Fetch auth handling for authenticated proxy, if credentials provided.++ Handles HTTP proxy authentication challenges (Basic/Proxy) by providing+ configured credentials from BrowserProfile.+ """++ try:+ username = getattr(self.browser_profile, 'proxy_username', None)+ password = getattr(self.browser_profile, 'proxy_password', None)+ if not username or not password:+ return++ # Enable Fetch domain with auth handling+ # Try enabling globally+ try:+ await self._cdp_client_root.send.Fetch.enable(params={'handleAuthRequests': True, 'patterns': [{'urlPattern': '*'}]})+ except Exception:+ pass++ # Also try enabling on current session if available+ try:+ if self.agent_focus:+ await self.agent_focus.cdp_client.send.Fetch.enable(+ params={'handleAuthRequests': True, 'patterns': [{'urlPattern': '*'}]},+ session_id=self.agent_focus.session_id,+ )+ except Exception:+ pass++ def _on_auth_required(event: dict, session_id: SessionID | None = None):+ # event keys may be snake_case or camelCase depending on generator; handle both+ request_id = event.get('requestId') or event.get('request_id')+ challenge = event.get('authChallenge') or event.get('auth_challenge') or {}+ source = (challenge.get('source') or '').lower()+ # Only respond to proxy challenges+ if source == 'proxy' and request_id:+ async def _respond():+ try:+ await self._cdp_client_root.send.Fetch.continueWithAuth(+ params={+ 'requestId': request_id,+ 'authChallengeResponse': {+ 'response': 'ProvideCredentials',+ 'username': username,+ 'password': password,+ },+ },+ session_id=session_id,+ )+ except Exception as e:+ self.logger.debug(f'Proxy auth respond failed: {e}')+ # schedule+ asyncio.create_task(_respond())+ else:+ # Default behaviour for non-proxy challenges: let browser handle+ async def _default():+ try:+ await self._cdp_client_root.send.Fetch.continueWithAuth(+ params={'requestId': request_id, 'authChallengeResponse': {'response': 'Default'}},+ session_id=session_id,+ )+ except Exception:+ pass+ if request_id:+ asyncio.create_task(_default())++ # Register event handler on root client+ try:+ self._cdp_client_root.register.Fetch.authRequired(_on_auth_required)+ except Exception:+ pass++ except Exception as e:+ self.logger.debug(f'Skipping proxy auth setup: {e}')+async def get_tabs(self) -> list[TabInfo]:"""Get information about all open tabs using CDP Target.getTargetInfo for speed."""tabs = []diff --git a/browser_use/cli.py b/browser_use/cli.pyindex 2d8fc3814..4859f8465 100644--- a/browser_use/cli.py+++ b/browser_use/cli.py@@ -177,6 +177,14 @@ def update_config_with_click_args(config: dict[str, Any], ctx: click.Context) ->config['browser']['profile_directory'] = ctx.params['profile_directory']if ctx.params.get('cdp_url'):config['browser']['cdp_url'] = ctx.params['cdp_url']+ if ctx.params.get('proxy_url'):+ config['browser']['proxy_server'] = ctx.params['proxy_url']+ if ctx.params.get('no_proxy'):+ config['browser']['proxy_bypass_list'] = [p.strip() for p in ctx.params['no_proxy'].split(',') if p.strip()]+ if ctx.params.get('proxy_username'):+ config['browser']['proxy_username'] = ctx.params['proxy_username']+ if ctx.params.get('proxy_password'):+ config['browser']['proxy_password'] = ctx.params['proxy_password']return config@@ -1573,6 +1581,10 @@ async def textual_interface(config: dict[str, Any]):)@click.option('--profile-directory', type=str, help='Chrome profile directory name (e.g. "Default", "Profile 1")')@click.option('--cdp-url', type=str, help='Connect to existing Chrome via CDP URL (e.g. http://localhost:9222)')[email protected]('--proxy-url', type=str, help='Proxy server for Chromium traffic (e.g. http://host:8080 or socks5://host:1080)')[email protected]('--no-proxy', type=str, help='Comma-separated hosts to bypass proxy (e.g. localhost,127.0.0.1,*.internal)')[email protected]('--proxy-username', type=str, help='Proxy auth username')[email protected]('--proxy-password', type=str, help='Proxy auth password')@click.option('-p', '--prompt', type=str, help='Run a single task without the TUI (headless mode)')@click.option('--mcp', is_flag=True, help='Run as MCP server (exposes JSON RPC via stdin/stdout)')@click.pass_contextdiff --git a/browser_use/config.py b/browser_use/config.pyindex 5a75e1da0..f943b4e29 100644--- a/browser_use/config.py+++ b/browser_use/config.py@@ -213,6 +213,12 @@ class FlatEnvConfig(BaseSettings):BROWSER_USE_ALLOWED_DOMAINS: str | None = Field(default=None)BROWSER_USE_LLM_MODEL: str | None = Field(default=None)+ # Proxy env vars+ BROWSER_USE_PROXY_URL: str | None = Field(default=None)+ BROWSER_USE_NO_PROXY: str | None = Field(default=None)+ BROWSER_USE_PROXY_USERNAME: str | None = Field(default=None)+ BROWSER_USE_PROXY_PASSWORD: str | None = Field(default=None)+class DBStyleEntry(BaseModel):"""Database-style entry with UUID and metadata."""@@ -447,6 +453,17 @@ class Config:domains = [d.strip() for d in env_config.BROWSER_USE_ALLOWED_DOMAINS.split(',') if d.strip()]config['browser_profile']['allowed_domains'] = domains+ # Proxy settings (Chromium)+ if env_config.BROWSER_USE_PROXY_URL:+ config['browser_profile']['proxy_server'] = env_config.BROWSER_USE_PROXY_URL+ if env_config.BROWSER_USE_NO_PROXY:+ bypass = [d.strip() for d in env_config.BROWSER_USE_NO_PROXY.split(',') if d.strip()]+ config['browser_profile']['proxy_bypass_list'] = bypass+ if env_config.BROWSER_USE_PROXY_USERNAME:+ config['browser_profile']['proxy_username'] = env_config.BROWSER_USE_PROXY_USERNAME+ if env_config.BROWSER_USE_PROXY_PASSWORD:+ config['browser_profile']['proxy_password'] = env_config.BROWSER_USE_PROXY_PASSWORD+if env_config.OPENAI_API_KEY:config['llm']['api_key'] = env_config.OPENAI_API_KEYdiff --git a/tests/ci/test_proxy_smoke.py b/tests/ci/test_proxy_smoke.pynew file mode 100644index 000000000..a8901b405--- /dev/null+++ b/tests/ci/test_proxy_smoke.py@@ -0,0 +1,91 @@+import asyncio+from typing import Any++import pytest++from browser_use.browser import BrowserProfile, BrowserSession+from browser_use.config import CONFIG+++def test_chromium_args_include_proxy_flags():+ profile = BrowserProfile(+ headless=True,+ user_data_dir=str(CONFIG.BROWSER_USE_PROFILES_DIR / 'proxy-smoke'),+ proxy_server='http://proxy.local:8080',+ proxy_bypass_list=['localhost', '127.0.0.1'],+ )+ args = profile.get_args()+ assert any(a == '--proxy-server=http://proxy.local:8080' for a in args), args+ assert any(a == '--proxy-bypass-list=localhost,127.0.0.1' for a in args), args+++async def test_cdp_proxy_auth_handler_registers_and_responds():+ # Create profile with proxy auth credentials+ profile = BrowserProfile(+ headless=True,+ user_data_dir=str(CONFIG.BROWSER_USE_PROFILES_DIR / 'proxy-smoke'),+ proxy_username='user',+ proxy_password='pass',+ )+ session = BrowserSession(browser_profile=profile)++ # Stub CDP client with minimal Fetch support+ class StubCDP:+ def __init__(self) -> None:+ self.enabled = False+ self.last_auth: dict[str, Any] | None = None+ self.auth_callback = None++ class _FetchSend:+ def __init__(self, outer: 'StubCDP') -> None:+ self._outer = outer++ async def enable(self, params: dict, session_id: str | None = None) -> None:+ self._outer.enabled = True++ async def continueWithAuth(self, params: dict, session_id: str | None = None) -> None:+ self._outer.last_auth = {'params': params, 'session_id': session_id}++ class _Send:+ def __init__(self, outer: 'StubCDP') -> None:+ self.Fetch = _FetchSend(outer)++ class _FetchRegister:+ def __init__(self, outer: 'StubCDP') -> None:+ self._outer = outer++ def authRequired(self, callback) -> None:+ self._outer.auth_callback = callback++ class _Register:+ def __init__(self, outer: 'StubCDP') -> None:+ self.Fetch = _FetchRegister(outer)++ self.send = _Send(self)+ self.register = _Register(self)++ root = StubCDP()++ # Attach stubs to session+ session._cdp_client_root = root # type: ignore[attr-defined]+ # No need to attach a real CDPSession; _setup_proxy_auth works with root client++ # Should register Fetch handler and enable auth handling without raising+ await session._setup_proxy_auth()++ assert root.enabled is True+ assert callable(root.auth_callback)++ # Simulate proxy auth required event+ ev = {'requestId': 'r1', 'authChallenge': {'source': 'Proxy'}}+ root.auth_callback(ev, session_id='s1') # type: ignore[misc]++ # Let scheduled task run+ await asyncio.sleep(0.01)++ assert root.last_auth is not None+ params = root.last_auth['params']+ assert params['authChallengeResponse']['response'] == 'ProvideCredentials'+ assert params['authChallengeResponse']['username'] == 'user'+ assert params['authChallengeResponse']['password'] == 'pass'