Skip to content

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

Change proxy argument to typed dict to match past format

matt-greathouse284a2e8a50e0
diff --git a/browser_use/browser/__init__.py b/browser_use/browser/__init__.py
index 4db71d9fd..48d852010 100644
--- a/browser_use/browser/__init__.py
+++ b/browser_use/browser/__init__.py
@@ -2,11 +2,12 @@ from typing import TYPE_CHECKING
# Type stubs for lazy imports
if TYPE_CHECKING:
- from .profile import BrowserProfile
+ from .profile import BrowserProfile, ProxySettings
from .session import BrowserSession
# Lazy imports mapping for heavy browser components
_LAZY_IMPORTS = {
+ 'ProxySettings': ('.profile', 'ProxySettings'),
'BrowserProfile': ('.profile', 'BrowserProfile'),
'BrowserSession': ('.session', 'BrowserSession'),
}
@@ -35,4 +36,5 @@ def __getattr__(name: str):
__all__ = [
'BrowserSession',
'BrowserProfile',
+ 'ProxySettings',
]
diff --git a/browser_use/browser/profile.py b/browser_use/browser/profile.py
index e7e4ab43a..d6c5cd914 100644
--- a/browser_use/browser/profile.py
+++ b/browser_use/browser/profile.py
@@ -556,6 +556,20 @@ class BrowserLaunchPersistentContextArgs(BrowserLaunchArgs, BrowserContextArgs):
return Path(v).expanduser().resolve()
+class ProxySettings(BaseModel):
+ """Typed proxy settings for Chromium traffic.
+
+ - server: Full proxy URL, e.g. "http://host:8080" or "socks5://host:1080"
+ - bypass: Comma-separated hosts to bypass (e.g. "localhost,127.0.0.1,*.internal")
+ - username/password: Optional credentials for authenticated proxies
+ """
+
+ server: str | None = Field(default=None, description='Proxy URL, e.g. http://host:8080 or socks5://host:1080')
+ bypass: str | None = Field(default=None, description='Comma-separated hosts to bypass, e.g. localhost,127.0.0.1,*.internal')
+ username: str | None = Field(default=None, description='Proxy auth username')
+ password: str | None = Field(default=None, description='Proxy auth password')
+
+
class BrowserProfile(BrowserConnectArgs, BrowserLaunchPersistentContextArgs, BrowserLaunchArgs, BrowserNewContextArgs):
"""
A BrowserProfile is a static template collection of kwargs that can be passed to:
@@ -594,20 +608,11 @@ class BrowserProfile(BrowserConnectArgs, BrowserLaunchPersistentContextArgs, Bro
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(
+ # New consolidated proxy config (typed)
+ proxy: ProxySettings | dict | None = Field(
default=None,
- description='Proxy PAC URL (mutually exclusive with proxy_server).',
+ description='Proxy settings. Use ProxySettings(server, bypass, username, password). Dicts are accepted and coerced.',
)
- 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.",
@@ -732,11 +737,21 @@ class BrowserProfile(BrowserConnectArgs, BrowserLaunchPersistentContextArgs, Bro
)
return self
+ @field_validator('proxy', mode='before')
+ @classmethod
+ def _coerce_proxy(cls, v: Any) -> Any:
+ """Accept dicts for proxy and coerce to ProxySettings."""
+ if v is None or isinstance(v, ProxySettings):
+ return v
+ if isinstance(v, dict):
+ return ProxySettings(**v)
+ return v
+
@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.')
+ if self.proxy and (self.proxy.bypass and not self.proxy.server):
+ logger.warning('BrowserProfile.proxy.bypass provided but proxy has no server; bypass will be ignored.')
return self
def get_args(self) -> list[str]:
@@ -775,12 +790,13 @@ class BrowserProfile(BrowserConnectArgs, BrowserLaunchPersistentContextArgs, Bro
]
# 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}')
+ proxy_server = self.proxy.server if self.proxy else None
+ proxy_bypass = self.proxy.bypass if self.proxy else None
+
+ if proxy_server:
+ pre_conversion_args.append(f'--proxy-server={proxy_server}')
+ if proxy_bypass:
+ pre_conversion_args.append(f'--proxy-bypass-list={proxy_bypass}')
# 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))
diff --git a/browser_use/browser/session.py b/browser_use/browser/session.py
index 607f179a7..f9c6ced60 100644
--- a/browser_use/browser/session.py
+++ b/browser_use/browser/session.py
@@ -1049,8 +1049,9 @@ class BrowserSession(BaseModel):
"""
try:
- username = getattr(self.browser_profile, 'proxy_username', None)
- password = getattr(self.browser_profile, 'proxy_password', None)
+ proxy_cfg = self.browser_profile.proxy
+ username = proxy_cfg.username if proxy_cfg else None
+ password = proxy_cfg.password if proxy_cfg else None
if not username or not password:
self.logger.debug('Proxy credentials not provided; skipping proxy auth setup')
return
diff --git a/browser_use/cli.py b/browser_use/cli.py
index 4859f8465..6e8fcc140 100644
--- a/browser_use/cli.py
+++ b/browser_use/cli.py
@@ -177,14 +177,20 @@ 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']
+
+ # Consolidated proxy dict
+ proxy: dict[str, str] = {}
if ctx.params.get('proxy_url'):
- config['browser']['proxy_server'] = ctx.params['proxy_url']
+ 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()]
+ # Store as comma-separated list string to match Chrome flag
+ proxy['bypass'] = ','.join([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']
+ proxy['username'] = ctx.params['proxy_username']
if ctx.params.get('proxy_password'):
- config['browser']['proxy_password'] = ctx.params['proxy_password']
+ proxy['password'] = ctx.params['proxy_password']
+ if proxy:
+ config['browser']['proxy'] = proxy
return config
diff --git a/browser_use/config.py b/browser_use/config.py
index f943b4e29..54fa64fcc 100644
--- a/browser_use/config.py
+++ b/browser_use/config.py
@@ -453,16 +453,23 @@ 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)
+ # Proxy settings (Chromium) -> consolidated `proxy` dict
+ proxy_dict: dict[str, Any] = {}
if env_config.BROWSER_USE_PROXY_URL:
- config['browser_profile']['proxy_server'] = env_config.BROWSER_USE_PROXY_URL
+ proxy_dict['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
+ # store bypass as comma-separated string to match Chrome flag
+ proxy_dict['bypass'] = ','.join(
+ [d.strip() for d in env_config.BROWSER_USE_NO_PROXY.split(',') if d.strip()]
+ )
if env_config.BROWSER_USE_PROXY_USERNAME:
- config['browser_profile']['proxy_username'] = env_config.BROWSER_USE_PROXY_USERNAME
+ proxy_dict['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
+ proxy_dict['password'] = env_config.BROWSER_USE_PROXY_PASSWORD
+ if proxy_dict:
+ # ensure section exists
+ config.setdefault('browser_profile', {})
+ config['browser_profile']['proxy'] = proxy_dict
if env_config.OPENAI_API_KEY:
config['llm']['api_key'] = env_config.OPENAI_API_KEY
diff --git a/docs/customize/browser-settings.mdx b/docs/customize/browser-settings.mdx
index 1a6bb7518..d09bed33f 100644
--- a/docs/customize/browser-settings.mdx
+++ b/docs/customize/browser-settings.mdx
@@ -488,10 +488,14 @@ Whether to automatically accept all downloads.
#### `proxy`
```python
-proxy: dict | None = None
+proxy: ProxySettings | None = None
```
-Proxy settings. Example: `{"server": "http://proxy.com:8080", "username": "user", "password": "pass"}`.
+Proxy settings (typed). Example:
+
+```python
+proxy=ProxySettings(server="http://proxy.com:8080", username="user", password="pass")
+```
#### `permissions`
diff --git a/tests/ci/test_proxy_smoke.py b/tests/ci/test_proxy_smoke.py
index d766ff249..75afd36e0 100644
--- a/tests/ci/test_proxy_smoke.py
+++ b/tests/ci/test_proxy_smoke.py
@@ -11,42 +11,23 @@ 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'],
+ proxy={
+ 'server': 'http://proxy.local:8080',
+ 'bypass': '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
-def test_chromium_args_include_pac_url_flag_and_exclusivity():
- # PAC URL should produce --proxy-pac-url and not --proxy-server
- profile = BrowserProfile(
- headless=True,
- user_data_dir=str(CONFIG.BROWSER_USE_PROFILES_DIR / 'proxy-smoke-pac'),
- proxy_pac_url='http://proxy.local/proxy.pac',
- )
- args = profile.get_args()
- assert any(a == '--proxy-pac-url=http://proxy.local/proxy.pac' for a in args), args
- assert all(not a.startswith('--proxy-server=') for a in args), args
-
- # Setting both PAC URL and server should raise
- with pytest.raises(ValueError):
- BrowserProfile(
- headless=True,
- user_data_dir=str(CONFIG.BROWSER_USE_PROFILES_DIR / 'proxy-smoke-bad'),
- proxy_server='http://proxy.local:8080',
- proxy_pac_url='http://proxy.local/proxy.pac',
- )
-
@pytest.mark.asyncio
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',
+ proxy={'username': 'user', 'password': 'pass'},
)
session = BrowserSession(browser_profile=profile)