Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

Add authenticated proxy support

matt-greathouse4e0ce78f4338
diff --git a/browser_use/browser/profile.py b/browser_use/browser/profile.py
index 2aedc9129..e7e4ab43a 100644
--- a/browser_use/browser/profile.py
+++ b/browser_use/browser/profile.py
@@ -592,6 +592,22 @@ class BrowserProfile(BrowserConnectArgs, BrowserLaunchPersistentContextArgs, Bro
description='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 args
final_args_list = BrowserLaunchArgs.args_as_list(BrowserLaunchArgs.args_as_dict(pre_conversion_args))
return final_args_list
diff --git a/browser_use/browser/session.py b/browser_use/browser/session.py
index 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 working
try:
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.py
index 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_context
diff --git a/browser_use/config.py b/browser_use/config.py
index 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_KEY
diff --git a/tests/ci/test_proxy_smoke.py b/tests/ci/test_proxy_smoke.py
new file mode 100644
index 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'