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
browser docs
Magnus Müller3ef2d83c121e
diff --git a/browser_use/browser/profile.py b/browser_use/browser/profile.pyindex dbbb709f7..c05906a4c 100644--- a/browser_use/browser/profile.py+++ b/browser_use/browser/profile.py@@ -388,7 +388,6 @@ class BrowserConnectArgs(BaseModel):model_config = ConfigDict(extra='ignore', validate_assignment=True, revalidate_instances='always', populate_by_name=True)- cdp_url: UrlStr | None = Field(default=None, description='CDP URL for connecting to existing browser instance')headers: dict[str, str] | None = Field(default=None, description='Additional HTTP headers to be sent with connect request')slow_mo: float = 0.0timeout: float = 30_000@@ -596,7 +595,8 @@ class BrowserProfile(BrowserConnectArgs, BrowserLaunchPersistentContextArgs, Bro# ... extends options defined in:# BrowserLaunchPersistentContextArgs, BrowserLaunchArgs, BrowserNewContextArgs, BrowserConnectArgs- # Session/connection configuration (cdp_url inherited from BrowserConnectArgs)+ # Session/connection configuration+ cdp_url: str | None = Field(default=None, description='CDP URL for connecting to existing browser instance')is_local: bool = Field(default=True, description='Whether this is a local browser instance')# label: str = 'default'@@ -676,7 +676,7 @@ class BrowserProfile(BrowserConnectArgs, BrowserLaunchPersistentContextArgs, Broreturn f'BrowserProfile(user_data_dir= {short_dir}, headless={self.headless})'def __str__(self) -> str:- return f'BrowserProfile({_log_pretty_path(self.user_data_dir) if self.user_data_dir else "<incognito>"})'+ return 'BrowserProfile'@model_validator(mode='after')def copy_old_config_names_to_new(self) -> Self:diff --git a/docs/customize/browser-basic.mdx b/docs/customize/browser-basic.mdxnew file mode 100644index 000000000..d87aae556--- /dev/null+++ b/docs/customize/browser-basic.mdx@@ -0,0 +1,148 @@+---+title: "Browser Quickstart"+description: "Get started with Browser Use browser management - launch browsers and configure basic settings"+icon: "globe"+mode: "wide"+---++Browser Use manages real browsers for your AI agents using either local browser instances or remote connections. This guide shows you how to get started with browser configuration.++---++## Quick Start++The simplest way to start is with a basic `BrowserSession`:++```python+from browser_use import Agent, BrowserSession++# Simple local browser (headless by default if no display)+session = BrowserSession()+agent = Agent(task="Search for Browser Use on Google", browser_session=session)+await agent.run()+```++## Basic Configuration++Pass configuration directly to `BrowserSession`:++```python+from browser_use import BrowserSession, Agent++session = BrowserSession(+ headless=False, # Show browser window+ user_data_dir="./my-profile", # Persistent profile+ viewport={'width': 1280, 'height': 1100}+)++agent = Agent(task="Fill out the form", browser_session=session)+await agent.run()+```++## Using Browser Profiles++For reusable configurations, use `BrowserProfile`:++```python+from browser_use.browser import BrowserProfile, BrowserSession++# Create a reusable profile+profile = BrowserProfile(+ headless=False,+ user_data_dir="./chrome-profile",+ stealth=True,+ viewport={'width': 1920, 'height': 1080},+ allowed_domains=['*.example.com']+)++# Use the profile for multiple sessions+session1 = BrowserSession(browser_profile=profile)+session2 = BrowserSession(browser_profile=profile, headless=True) # Override specific settings+```++## Session vs Profile++- **`BrowserSession`**: Manages the active browser connection and runtime state+- **`BrowserProfile`**: Reusable configuration template for browser settings++```python+# Direct configuration+session = BrowserSession(headless=True, stealth=False)++# Using profile with overrides+profile = BrowserProfile(headless=False, stealth=True)+session = BrowserSession(browser_profile=profile, headless=True) # headless=True overrides profile+```++## Essential Settings++### Display Mode+```python+session = BrowserSession(+ headless=False, # Show browser window+ window_size={'width': 1920, 'height': 1080}+)+```++### User Data Directory+```python+session = BrowserSession(+ user_data_dir="./my-profile", # Persistent browser profile+ # user_data_dir=None, # Incognito/temporary profile+)+```++### Stealth Mode+```python+session = BrowserSession(+ stealth=True, # Use stealth techniques to avoid detection+)+```++### Domain Restrictions+```python+session = BrowserSession(+ allowed_domains=['*.google.com', 'https://docs.google.com'], # Restrict navigation+)+```++## Common Patterns++### Development Setup+```python+# Best for development - visible browser with dev tools+dev_session = BrowserSession(+ headless=False,+ devtools=True,+ user_data_dir="./dev-profile"+)+```++### Production Setup+```python+# Best for production - headless with stealth+prod_session = BrowserSession(+ headless=True,+ stealth=True,+ user_data_dir=None, # Don't persist data+ viewport={'width': 1920, 'height': 1080}+)+```++### Authenticated Sessions+```python+# Reuse login sessions+auth_session = BrowserSession(+ user_data_dir="./auth-profile",+ storage_state="./cookies.json", # Load saved authentication+ keep_alive=True # Keep browser open after task+)+```++## Next Steps++- Learn about [browser parameters](/customize/browser-parameters) for advanced configuration+- Set up [real browser connections](/customize/browser-real-browser) for existing browsers+- Configure [remote browser connections](/customize/browser-remote) for cloud setups++---diff --git a/docs/customize/browser-parameters.mdx b/docs/customize/browser-parameters.mdxnew file mode 100644index 000000000..985064856--- /dev/null+++ b/docs/customize/browser-parameters.mdx@@ -0,0 +1,517 @@+---+title: "Browser Parameters"+description: "Complete reference for all Browser Use browser configuration parameters"+icon: "sliders"+mode: "wide"+---++Complete reference for configuring browsers in Browser Use. All parameters can be passed to `BrowserSession(...)` directly or stored in a `BrowserProfile(...)` template.++---++## Session vs Profile Parameters++### Session-Specific (BrowserSession only)+These parameters control the browser connection and cannot be stored in a `BrowserProfile`:++- `id` - Session identifier+- `browser_profile` - BrowserProfile template to use++### Shared Parameters+All other parameters can be used in both `BrowserSession(...)` and `BrowserProfile(...)`.++---++## Browser-Use Specific Parameters++Enhanced functionality provided by Browser Use on top of standard browser features.++### `stealth`+```python+stealth: bool = False+```+Use stealth techniques to avoid bot detection. Uses advanced browser fingerprint masking.++### `disable_security`+```python+disable_security: bool = False+```+<Warning>⚠️ NOT RECOMMENDED. Disables all browser security features - only use for debugging isolated environments.</Warning>++### `deterministic_rendering`+```python+deterministic_rendering: bool = False+```+<Warning>⚠️ NOT RECOMMENDED. Forces consistent rendering across OS platforms but reduces performance and increases bot detection risk.</Warning>++### `allowed_domains`+```python+allowed_domains: list[str] | None = None+```+Restrict agent navigation to specific domains. Supports glob patterns:+- `['example.com']` - Only https://example.com/*+- `['*.example.com']` - All subdomains of example.com+- `['https://docs.example.com', '*.api.example.com']` - Mixed patterns++```python+session = BrowserSession(+ allowed_domains=['*.google.com', 'https://stackoverflow.com']+)+```++### `keep_alive`+```python+keep_alive: bool | None = None+```+Keep browser running after agent completes. Default behavior:+- `None` - Close browser if launched by Browser Use, keep open if connected to existing+- `True` - Always keep browser running+- `False` - Always close browser++### `enable_default_extensions`+```python+enable_default_extensions: bool = True+```+Load automation-optimized extensions:+- uBlock Origin (ad blocking)+- I still don't care about cookies (cookie handling)+- ClearURLs (URL cleaning)++### `cross_origin_iframes`+```python+cross_origin_iframes: bool = False+```+Enable cross-origin iframe support. When False (default), only same-origin frames are processed to avoid complexity.++---++## Connection Parameters++### `cdp_url`+```python+cdp_url: str | None = None+```+CDP URL for connecting to existing browser instance (e.g., `http://localhost:9222`).++### `is_local`+```python+is_local: bool = True+```+Whether this is a local browser instance. Set to `False` when connecting to remote browsers.++---++## Display & Viewport++### `headless`+```python+headless: bool | None = None+```+Run browser without visible UI. If `None`, auto-detects based on display availability.++### `window_size`+```python+window_size: dict | None = None+```+Browser window size for headful mode:+```python+window_size={'width': 1920, 'height': 1080}+```++### `window_position`+```python+window_position: dict | None = {'width': 0, 'height': 0}+```+Window position from top-left corner:+```python+window_position={'width': 100, 'height': 50}+```++### `viewport`+```python+viewport: dict | None = None+```+Content area size (used in headless mode):+```python+viewport={'width': 1280, 'height': 720}+```++### `no_viewport`+```python+no_viewport: bool | None = None+```+Disable fixed viewport - content resizes with window. Auto-configured based on `headless` setting.++### `device_scale_factor`+```python+device_scale_factor: float | None = None+```+Device scale factor (DPI). Useful for high-resolution screenshots (set to 2 or 3).++### `screen`+```python+screen: dict | None = None+```+Screen size available to browser. Auto-detected if not specified.++---++## Browser Launch Options++### `executable_path`+```python+executable_path: str | Path | None = None+```+Path to browser executable for custom installations.++### `channel`+```python+channel: BrowserChannel | None = None+```+Browser channel: `'chromium'`, `'chrome'`, `'chrome-beta'`, `'chrome-dev'`, `'chrome-canary'`, `'msedge'`, etc.++### `args`+```python+args: list[str] = []+```+Additional command-line arguments for the browser. See [Chrome command line switches](https://peter.sh/experiments/chromium-command-line-switches/).++### `ignore_default_args`+```python+ignore_default_args: list[str] | Literal[True] = [...]+```+Default CLI args to exclude. Set to `True` to disable all defaults (not recommended).++### `env`+```python+env: dict[str, str | float | bool] | None = None+```+Environment variables for browser process:+```python+env={'DISPLAY': ':1'} # Use specific X11 display+```++### `chromium_sandbox`+```python+chromium_sandbox: bool = True # False in Docker+```+Enable Chromium sandboxing. Automatically disabled in Docker environments.++### `devtools`+```python+devtools: bool = False+```+Open DevTools panel automatically (requires `headless=False`).++---++## User Data & Profiles++### `user_data_dir`+```python+user_data_dir: str | Path | None = '~/.config/browseruse/profiles/default'+```+Directory for browser profile data. Set to `None` for incognito/temporary profile.++<Warning>+Multiple browsers cannot share the same `user_data_dir` simultaneously. Use unique directories or `None` for parallel browsers.+</Warning>++### `profile_directory`+```python+profile_directory: str = 'Default'+```+Chrome profile subdirectory name (e.g., `'Default'`, `'Profile 1'`, `'Work'`).++### `storage_state`+```python+storage_state: str | Path | dict[str, Any] | None = None+```+Browser storage state (cookies, localStorage). Can be file path or dict:++```python+# From file+storage_state='./auth.json'++# From dict+storage_state={+ 'cookies': [...],+ 'origins': [...]+}+```++---++## Network & Security++### `proxy`+```python+proxy: ProxySettings | None = None+```+Proxy configuration:+```python+from browser_use.browser.profile import ProxySettings++proxy=ProxySettings(+ server="http://proxy.com:8080",+ username="user",+ password="pass",+ bypass="localhost,127.0.0.1"+)+```++### `permissions`+```python+permissions: list[str] = ['clipboardReadWrite', 'notifications']+```+Browser permissions to grant. Default includes clipboard access and notifications.++### `bypass_csp`+```python+bypass_csp: bool = False+```+<Warning>⚠️ Increases security risk and bot fingerprinting. Only use when necessary for specific CSP-restricted sites.</Warning>++### `ignore_https_errors`+```python+ignore_https_errors: bool = False+```+Ignore HTTPS certificate errors.++### `java_script_enabled`+```python+java_script_enabled: bool = True+```+<Warning>⚠️ Not recommended. Disabling JavaScript will break most modern websites and Browser Use functionality.</Warning>++### `extra_http_headers`+```python+extra_http_headers: dict[str, str] = {}+```+Additional HTTP headers sent with every request:+```python+extra_http_headers={'User-Agent': 'Custom Agent'}+```++---++## Page Behavior & Timing++### `default_timeout`+```python+default_timeout: float | None = None+```+Default timeout for browser operations in milliseconds:+```python+default_timeout=30000 # 30 seconds+```++### `default_navigation_timeout`+```python+default_navigation_timeout: float | None = None+```+Default timeout for page navigation in milliseconds.++### `minimum_wait_page_load_time`+```python+minimum_wait_page_load_time: float = 0.25+```+Minimum time to wait before capturing page state for AI analysis.++### `wait_for_network_idle_page_load_time`+```python+wait_for_network_idle_page_load_time: float = 0.5+```+Time to wait for network activity to cease. Increase to 3-5s for slower websites.++### `maximum_wait_page_load_time`+```python+maximum_wait_page_load_time: float = 5.0+```+Maximum time to wait for page load before proceeding.++### `wait_between_actions`+```python+wait_between_actions: float = 0.5+```+Time to wait between agent actions.++### `slow_mo`+```python+slow_mo: float = 0.0+```+Slow down actions by this many milliseconds.++---++## AI Integration++### `highlight_elements`+```python+highlight_elements: bool = True+```+Highlight interactive elements with colored bounding boxes for AI vision.++### `viewport_expansion`+```python+viewport_expansion: int = 500+```+Viewport expansion in pixels for AI context:+- `-1` - Include entire page (highest token usage)+- `0` - Only visible viewport+- `500` - Viewport + 500px in each direction (balanced)++### `include_dynamic_attributes`+```python+include_dynamic_attributes: bool = True+```+Include dynamic attributes in selectors for better element targeting.++---++## Downloads & Files++### `accept_downloads`+```python+accept_downloads: bool = True+```+Automatically accept all downloads.++### `downloads_path`+```python+downloads_path: str | Path | None = None+```+Directory for downloaded files. Auto-created if not specified.++### `auto_download_pdfs`+```python+auto_download_pdfs: bool = True+```+Automatically download PDFs when navigating to PDF viewer pages.++---++## Device Emulation++### `user_agent`+```python+user_agent: str | None = None+```+Custom user agent string:+```python+user_agent="Mozilla/5.0 (iPhone; CPU iPhone OS 13_0 like Mac OS X)"+```++### `is_mobile`+```python+is_mobile: bool = False+```+Enable mobile viewport meta tag handling and touch events.++### `has_touch`+```python+has_touch: bool = False+```+Enable touch event support.++### `locale`+```python+locale: str | None = None+```+User locale (e.g., `'en-GB'`, `'de-DE'`). Affects `navigator.language` and formatting.++### `timezone_id`+```python+timezone_id: str | None = None+```+Timezone identifier:+```python+timezone_id='America/New_York' # or 'UTC'+```++### `color_scheme`+```python+color_scheme: ColorScheme = 'light'+```+Preferred color scheme: `'light'`, `'dark'`, `'no-preference'`++---++## Recording Options++### `record_video_dir`+```python+record_video_dir: str | Path | None = None+```+Directory to save video recordings as `.webm` files.++### `record_video_size`+```python+record_video_size: dict | None = None+```+Video recording dimensions:+```python+record_video_size={'width': 1280, 'height': 720}+```++### `record_har_path`+```python+record_har_path: str | Path | None = None+```+Path to save network trace files as `.har` format.++### `traces_dir`+```python+traces_dir: str | Path | None = None+```+Directory to save complete trace files including screenshots, DOM snapshots, and network traces.++---++## Complete Example++```python+from browser_use.browser import BrowserProfile, BrowserSession+from browser_use.browser.profile import ProxySettings++# Comprehensive configuration example+profile = BrowserProfile(+ # Display+ headless=False,+ window_size={'width': 1920, 'height': 1080},+ viewport={'width': 1280, 'height': 720},++ # Browser+ stealth=True,+ executable_path="/opt/chrome/chrome",+ user_data_dir="./work-profile",++ # Network+ proxy=ProxySettings(server="http://proxy:8080"),+ allowed_domains=['*.company.com', 'https://trusted.com'],++ # Timing+ wait_between_actions=1.0,+ default_timeout=30000,++ # AI Integration+ highlight_elements=True,+ viewport_expansion=500,++ # Downloads+ downloads_path="./downloads",+ auto_download_pdfs=True,++ # Recording+ record_video_dir="./recordings"+)++# Use profile with session-specific overrides+session = BrowserSession(+ browser_profile=profile,+ headless=True, # Override profile setting+ cdp_url="http://remote:9222" # Session-specific connection+)+```++---diff --git a/docs/customize/browser-real-browser.mdx b/docs/customize/browser-real-browser.mdxnew file mode 100644index 000000000..e35164ac8--- /dev/null+++ b/docs/customize/browser-real-browser.mdx@@ -0,0 +1,251 @@+---+title: "Connect to Real Browser"+description: "Connect Browser Use to your existing browser instances and manage persistent profiles"+icon: "link"+mode: "wide"+---++Browser Use can connect to existing browser instances instead of launching new ones. This is useful for debugging, using existing authentication, or working with browsers that have specific extensions or configurations.++---++## Why Use Real Browsers?++- **🔐 Preserve Authentication**: Keep your existing login sessions+- **🧩 Use Extensions**: Access your installed browser extensions+- **🐛 Debug Easily**: See exactly what the agent is doing in real-time+- **⚡ Faster Startup**: Skip browser launch time+- **🔒 Enterprise Settings**: Use browsers with corporate policies++---++## Local Browser Connection++### Method 1: Connect via CDP URL++Launch Chrome with remote debugging enabled:++```bash+# macOS/Linux+google-chrome --remote-debugging-port=9222 --user-data-dir="./chrome-profile"++# Windows+chrome.exe --remote-debugging-port=9222 --user-data-dir="./chrome-profile"+```++Then connect Browser Use:++```python+from browser_use import BrowserSession++session = BrowserSession(+ cdp_url="http://localhost:9222",+ is_local=False # Don't launch new browser+)+```++### Method 2: Using Browser Profile Path++Connect to an existing Chrome profile:++```python+session = BrowserSession(+ user_data_dir="/path/to/existing/chrome/profile",+ executable_path="/path/to/chrome", # Optional: specify browser location+)+```++## Browser Profile Management++### Persistent Profiles++Create browsers that remember state between sessions:++```python+from browser_use.browser import BrowserProfile++# Create a persistent profile+profile = BrowserProfile(+ user_data_dir="./work-profile",+ profile_directory="Work", # Chrome profile name+ storage_state="./auth.json", # Load authentication state+)++session = BrowserSession(browser_profile=profile)+```++### Profile Organization++```python+# Separate profiles for different purposes+profiles = {+ "development": BrowserProfile(+ user_data_dir="./profiles/dev",+ headless=False,+ devtools=True+ ),+ "testing": BrowserProfile(+ user_data_dir="./profiles/test",+ headless=True,+ stealth=True+ ),+ "production": BrowserProfile(+ user_data_dir="./profiles/prod",+ headless=True,+ allowed_domains=['*.mycompany.com']+ )+}++# Use different profiles for different environments+test_session = BrowserSession(browser_profile=profiles["testing"])+```++## Authentication & Cookies++### Loading Saved Authentication++```python+# Method 1: Storage state (recommended)+session = BrowserSession(+ storage_state="./saved-auth.json",+ user_data_dir=None # Use temporary profile with loaded auth+)++# Method 2: Existing profile with cookies+session = BrowserSession(+ user_data_dir="./authenticated-profile"+)+```++### Creating Storage State++Use the browser to create authentication files:++```bash+# Open browser and login to your sites+npx playwright open --save-storage=./auth.json https://example.com++# Or use Chrome directly+google-chrome --user-data-dir="./auth-profile" https://example.com+# Login manually, then use the profile path in BrowserSession+```++### Saving Authentication for Reuse++```python+# Keep browser alive to maintain session+session = BrowserSession(+ keep_alive=True, # Don't close browser after agent finishes+ user_data_dir="./persistent-auth"+)++# Run multiple agents with same authentication+agent1 = Agent(task="Check email", browser_session=session)+await agent1.run()++agent2 = Agent(task="Update profile", browser_session=session)+await agent2.run()++# Manually close when done+await session.stop()+```++## Browser Extensions++### Using Existing Extensions++```python+# Connect to browser with your installed extensions+session = BrowserSession(+ user_data_dir="/path/to/chrome/profile/with/extensions",+ # Extensions will be available automatically+)+```++### Default Extensions++Browser Use includes automation-friendly extensions:++```python+session = BrowserSession(+ enable_default_extensions=True, # Includes uBlock Origin, cookie handlers+ user_data_dir="./profile-with-extensions"+)+```++## Advanced Connection Options++### Custom Browser Paths++```python+# Use specific browser installation+session = BrowserSession(+ executable_path="/opt/google/chrome/chrome",+ channel="chrome", # or "chromium", "chrome-beta", etc.+ user_data_dir="./custom-profile"+)+```++### Multiple Browser Instances++```python+# Run multiple browsers simultaneously+sessions = []+for i in range(3):+ session = BrowserSession(+ user_data_dir=f"./profile-{i}",+ cdp_url=f"http://localhost:{9222 + i}", # Different ports+ is_local=False+ )+ sessions.append(session)+```++## Best Practices++### 🔒 Security+- Use separate profiles for different domains/purposes+- Don't share profiles between trusted and untrusted automation+- Regularly clean temporary profiles++### ⚡ Performance+- Reuse existing browser instances when possible+- Use `keep_alive=True` for multiple sequential tasks+- Close browsers explicitly with `session.stop()` when done++### 🐛 Debugging+- Use `headless=False` and `devtools=True` during development+- Check Chrome's `chrome://inspect` to see available debugging targets+- Monitor browser console for errors++---++## Troubleshooting++### Connection Issues+```python+# Check if CDP port is available+session = BrowserSession(+ cdp_url="http://localhost:9222",+ timeout=5000 # Fail fast if can't connect+)+```++### Profile Conflicts+```python+# Avoid conflicts with existing browser instances+session = BrowserSession(+ user_data_dir="./unique-profile-name", # Use unique directory+ # Don't use default Chrome profile if Chrome is already running+)+```++### Permission Issues+```python+# Grant required permissions+session = BrowserSession(+ permissions=['clipboard-read', 'clipboard-write', 'notifications'],+ bypass_csp=True # If needed for specific sites+)+```++---diff --git a/docs/customize/browser-remote.mdx b/docs/customize/browser-remote.mdxnew file mode 100644index 000000000..4d7871806--- /dev/null+++ b/docs/customize/browser-remote.mdx@@ -0,0 +1,326 @@+---+title: "Remote Browser Connections"+description: "Connect to remote browsers running in containers, VMs, or cloud environments"+icon: "cloud"+mode: "wide"+---++Connect Browser Use to browsers running on remote servers, containers, or cloud environments for scalable automation.++---++## When to Use Remote Browsers++- **☁️ Cloud Environments**: Run browsers in containers or VMs+- **🔄 Scalable Automation**: Multiple browsers across different machines+- **🐳 Docker Deployments**: Browsers in containerized environments+- **🖥️ Headless Servers**: Browsers on servers without displays+- **🌐 Distributed Testing**: Browsers in different geographic locations++---++## Basic Remote Connection++### CDP URL Connection++Connect to a browser with Chrome DevTools Protocol:++```python+from browser_use import BrowserSession++# Connect to remote browser+session = BrowserSession(+ cdp_url="http://remote-server:9222",+ is_local=False # Important: don't try to launch local browser+)+```++### With Authentication++For secured remote browsers:++```python+session = BrowserSession(+ cdp_url="http://username:password@remote-server:9222",+ headers={'Authorization': 'Bearer your-token'},+ is_local=False+)+```++## Docker Setup++### Launch Chrome in Docker++```bash+# Run Chrome in Docker container+docker run -d \+ --name chrome-remote \+ -p 9222:9222 \+ --shm-size=2gb \+ browseruse/chrome:latest \+ --remote-debugging-address=0.0.0.0 \+ --remote-debugging-port=9222 \+ --no-sandbox \+ --disable-gpu+```++Connect from Browser Use:++```python+session = BrowserSession(+ cdp_url="http://localhost:9222",+ is_local=False+)+```++### Docker Compose++```yaml+# docker-compose.yml+version: '3.8'+services:+ chrome:+ image: browseruse/chrome:latest+ ports:+ - "9222:9222"+ shm_size: 2gb+ command: >+ --remote-debugging-address=0.0.0.0+ --remote-debugging-port=9222+ --no-sandbox+ --disable-gpu+ --headless=new++ automation:+ build: .+ depends_on:+ - chrome+ environment:+ - CDP_URL=http://chrome:9222+```++## Cloud Browser Services++### Browser Use Cloud++Use managed browser infrastructure:++```python+# Browser Use Cloud handles browser management automatically+from browser_use.cloud import CloudAgent++agent = CloudAgent(+ task="Search and extract data",+ api_key="your-api-key"+)+result = await agent.run()+```++### Custom Cloud Setup++Connect to your own cloud browsers:++```python+# Connect to cloud browser instances+cloud_browsers = [+ "http://browser-1.example.com:9222",+ "http://browser-2.example.com:9222",+ "http://browser-3.example.com:9222"+]++sessions = [+ BrowserSession(cdp_url=url, is_local=False)+ for url in cloud_browsers+]+```++## Advanced Remote Configuration++### Proxy Through Remote Browser++```python+from browser_use.browser.profile import ProxySettings++session = BrowserSession(+ cdp_url="http://remote-server:9222",+ proxy=ProxySettings(+ server="http://proxy-server:8080",+ username="proxy-user",+ password="proxy-pass"+ ),+ is_local=False+)+```++### Remote with Specific Settings++```python+session = BrowserSession(+ cdp_url="http://remote-server:9222",+ viewport={'width': 1920, 'height': 1080},+ user_agent="Mozilla/5.0 Custom Agent",+ timeout=60000, # Longer timeout for remote connections+ is_local=False+)+```++## Connection Management++### Connection Pooling++```python+class BrowserPool:+ def __init__(self, remote_urls):+ self.sessions = [+ BrowserSession(cdp_url=url, is_local=False)+ for url in remote_urls+ ]+ self.current = 0++ def get_session(self):+ session = self.sessions[self.current]+ self.current = (self.current + 1) % len(self.sessions)+ return session++# Use the pool+pool = BrowserPool([+ "http://browser-1:9222",+ "http://browser-2:9222",+ "http://browser-3:9222"+])++# Get available browser for each task+session = pool.get_session()+agent = Agent(task="Process data", browser_session=session)+```++### Health Checking++```python+import asyncio+import aiohttp++async def check_browser_health(cdp_url):+ """Check if remote browser is available"""+ try:+ async with aiohttp.ClientSession() as session:+ async with session.get(f"{cdp_url}/json/version", timeout=5) as resp:+ return resp.status == 200+ except:+ return False++# Only use healthy browsers+remote_urls = ["http://browser-1:9222", "http://browser-2:9222"]+healthy_urls = [+ url for url in remote_urls+ if await check_browser_health(url)+]++sessions = [+ BrowserSession(cdp_url=url, is_local=False)+ for url in healthy_urls+]+```++## Security Considerations++### Secure Connections++```python+# Use HTTPS when possible+session = BrowserSession(+ cdp_url="https://secure-browser.example.com:9222",+ headers={'X-API-Key': 'your-secure-key'},+ is_local=False+)+```++### Network Isolation++```python+# Restrict browser network access+session = BrowserSession(+ cdp_url="http://isolated-browser:9222",+ allowed_domains=['*.trusted-domain.com'], # Only allow specific domains+ disable_security=False, # Keep security features enabled+ is_local=False+)+```++## Performance Optimization++### Batch Operations++```python+# Process multiple tasks on same remote browser+async def batch_process(tasks, cdp_url):+ session = BrowserSession(cdp_url=cdp_url, is_local=False, keep_alive=True)++ results = []+ for task in tasks:+ agent = Agent(task=task, browser_session=session)+ result = await agent.run()+ results.append(result)++ await session.stop() # Clean shutdown+ return results+```++### Resource Management++```python+# Monitor resource usage+session = BrowserSession(+ cdp_url="http://remote-browser:9222",+ viewport={'width': 1280, 'height': 720}, # Smaller viewport for lower memory+ headless=True, # No display resources needed+ is_local=False+)+```++## Troubleshooting++### Connection Timeouts++```python+session = BrowserSession(+ cdp_url="http://slow-remote:9222",+ timeout=120000, # 2 minute timeout+ slow_mo=100, # Slow down actions for stability+ is_local=False+)+```++### Network Issues++```python+# Retry connection with backoff+import asyncio++async def connect_with_retry(cdp_url, max_attempts=3):+ for attempt in range(max_attempts):+ try:+ session = BrowserSession(cdp_url=cdp_url, is_local=False)+ await session.start()+ return session+ except Exception as e:+ if attempt == max_attempts - 1:+ raise e+ await asyncio.sleep(2 ** attempt) # Exponential backoff+```++### Debugging Remote Issues++```python+# Enable detailed logging for remote connections+import logging+logging.getLogger('browser_use').setLevel(logging.DEBUG)++session = BrowserSession(+ cdp_url="http://remote:9222",+ is_local=False+)+# Check logs for detailed connection information+```++---diff --git a/docs/customize/browser-settings.mdx b/docs/customize/browser-settings.mdxdeleted file mode 100644index a6ce50ba7..000000000--- a/docs/customize/browser-settings.mdx+++ /dev/null@@ -1,971 +0,0 @@-----title: "Browser Settings"-description: "Launch or connect to an existing browser and configure it to your needs."-icon: "globe"-mode: "wide"------Browser Use uses [playwright](https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch-persistent-context) (or [patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright)) to manage its connection with a real browser.-------**To launch or connect to a browser**, pass any playwright / browser-use configuration arguments you want to `BrowserSession(...)`:--```python-from browser_use import BrowserSession, Agent--browser_session = BrowserSession(- headless=True,- viewport={'width': 964, 'height': 647},- user_data_dir='~/.config/browseruse/profiles/default',-)-agent = Agent('fill out the form on this page', browser_session=browser_session)-```--<Note>- The new `BrowserSession` & `BrowserProfile` accept all the same arguments that- Playwright's- [`launch_persistent_context(...)`](https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch-persistent-context)- takes, giving you full control over browser settings at launch. (see below for- the full list)-</Note>-------## `BrowserSession`--- `BrowserSession(**params)` is Browser Use's object that tracks a connection to a running browser. It sets up:- - the CDP client connection and tracks which tabs the agent is focused on- - methods to interact with the browser window, apply config needed by the Agent, and run the `DOMService` for element detection- - it can take a `browser_profile=BrowserProfile(...)` template containing some config defaults, and `**kwargs` session-specific config overrides--### Browser Connection Parameters--Provide any one of these options to connect to an existing browser. These options are session-specific and cannot be stored in a `BrowserProfile(...)` template.--#### `wss_url`--```python-wss_url: str | None = None-```--WSS URL of the playwright-protocol browser server to connect to. See here for [WSS connection instructions](https://docs.browser-use.com/customize/real-browser#method-d%3A-connect-to-remote-playwright-node-js-browser-server-via-wss-url).--#### `cdp_url`--```python-cdp_url: str | None = None-```--CDP URL of the browser to connect to (e.g. `http://localhost:9222`). See here for [CDP connection instructions](https://docs.browser-use.com/customize/real-browser#method-e%3A-connect-to-remote-browser-via-cdp-url).--#### `browser_pid`--```python-browser_pid: int | None = None-```--PID of a running chromium-based browser process to connect to on localhost. See here for [connection via pid](https://docs.browser-use.com/customize/real-browser#method-c%3A-connect-to-local-browser-using-browser-pid) instructions.--<Note>- For web scraping tasks on sites that restrict automated access, we recommend- using [our cloud](https://browser-use.com) or an external browser provider for- better reliability. See the [Connect to your Browser](/customize/real-browser)- guide for detailed connection instructions.-</Note>--### Session-Specific Parameters--#### `browser_profile`--```python-browser_profile: BrowserProfile = BrowserProfile()-```--Optional `BrowserProfile` template containing default config to use for the `BrowserSession`. (see below for more info)--#### `**kwargs`--`BrowserSession` can also accept _all_ of the parameters [below](#browserprofile).-(the parameters _above_ this point are specific to `BrowserSession` and cannot be stored in a `BrowserProfile` template)--Extra `**kwargs` passed to `BrowserSession(...)` act as session-specific overrides to the `BrowserProfile(...)` template.--```python-base_iphone13 = BrowserProfile(- storage_state='/tmp/auth.json', # share cookies between parallel browsers- **playwright.devices['iPhone 13'],- timezone_id='UTC',-)-usa_phone = BrowserSession(- browser_profile=base_iphone13,- timezone_id='America/New_York', # kwargs override values in base_iphone13-)-eu_phone = BrowserSession(- browser_profile=base_iphone13,- timezone_id='Europe/Paris',-)--usa_agent = Agent(task='show me todays schedule...', browser_session=usa_phone)-eu_agent = Agent(task='show me todays schedule...', browser_session=eu_phone)-await asyncio.gather(agent1.run(), agent2.run())-```-------## `BrowserProfile`--A `BrowserProfile` is a 📋 config template for a 🎭 `BrowserSession(...)`.--It's basically just a typed + validated version of a `dict` to hold config.--When you find yourself storing or re-using many browser configs, you can upgrade from:--```diff-- config = {key: val, key: val, ...}-- BrowserSession(**config)-```--To this instead:--```diff-+ config = BrowserProfile(key=val, key=val, ...)-+ BrowserSession(browser_profile=config)-```--<Tip>-You don't ever *need* to use a `BrowserProfile`, you can always pass config parameters directly to `BrowserSession`:-```python-session = BrowserSession(headless=True, storage_state='auth.json', viewport={...}, ...)-```-</Tip>--`BrowserProfile` is optional, but it provides a number of benefits over a normal `dict` for holding config:--- has type hints and pydantic field descriptions that show up in your IDE-- validates config at runtime quickly without having to start a browser-- provides helper methods to autodetect screen size, set up local paths, save/load config as json, and more...--<Tip>-`BrowserProfiles`s are designed to easily be given 🆔 `uuid`s and put in a database + made editable by users.-`BrowserSession`s get their own 🆔 `uuid`s and be linked by 🖇 foreign key to whatever `BrowserProfiles` they use.--This cleanly separates the per-connection rows from the bulky re-usable config and avoids wasting space in your db.-This is useful because a user may only have 2 or 3 profiles, but they could have 100k+ sessions within a few months.--</Tip>--`BrowserProfile` and `BrowserSession` can both take any of the:--- [Playwright parameters](#playwright)-- [Browser-Use parameters](#browser-use-parameters) (extra options we provide on top of `playwright`)--The only parameters `BrowserProfile` can NOT take are the session-specific connection parameters:-`cdp_url`, `wss_url`, `browser_pid`, etc.--<Note>-Playwright Page/Browser/Context objects are no longer supported as parameters.-</Note>--### Basic Example--```python-from browser_use.browser import BrowserProfile--profile = BrowserProfile(- stealth=True,- storage_state='/tmp/google_docs_cookies.json',- allowed_domains=['docs.google.com', 'https://accounts.google.com'],- viewport={'width': 396, 'height': 774},- # ... playwright args / browser-use config args ...-)--phone1 = BrowserSession(browser_profile=profile, device_scale_factor=1)-phone2 = BrowserSession(browser_profile=profile, device_scale_factor=2)-phone3 = BrowserSession(browser_profile=profile, device_scale_factor=3)-```--### Browser-Use Parameters--These parameters control Browser Use-specific features, and are outside the standard playwright set. They can be passed to `BrowserSession(...)` and/or stored in a `BrowserProfile` template.--#### `keep_alive`--```python-keep_alive: bool | None = None-```--If `True` it wont close the browser after the first `agent.run()` ends. Useful for running multiple tasks with the same browser instance. If this is left as `None` and the Agent launched its own browser, the default is to close the browser after the agent completes. If the agent connected to an existing browser then it will leave it open.--#### `stealth`--```python-stealth: bool = False-```--Set to `True` to use [`patchright`](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright) to avoid bot-blocking. (Might cause issues with some sites, requires manual testing.)--<a name="restrict-urls"></a>--#### `allowed_domains`--```python-allowed_domains: list[str] | None = None-```--List of allowed domains for navigation. If None, all domains are allowed.-Example: `['google.com', '*.wikipedia.org']` - Here the agent will only be able to access `google.com` exactly and `wikipedia.org` + `*.wikipedia.org`.--Glob patterns are supported:--- `['example.com']` ✅ will match only `https://example.com/*` exactly, subdomains will not be allowed.- It's always the most secure to list all the domains you want to give the access to explicitly w/ schemes e.g.- `['https://google.com', 'http*://www.google.com', 'https://myaccount.google.com', 'https://mail.google.com', 'https://docs.google.com']`-- `['*.example.com']` ⚠️ **CAUTION** this will match `https://example.com` and _all_ its subdomains.- Make sure _all_ the subdomains are safe for the agent! `abc.example.com`, `def.example.com`, ..., `useruploads.example.com`, `admin.example.com`--#### `disable_security`--```python-disable_security: bool = False-```--<Warning>- ⚠️ Setting this to `True` is NOT RECOMMENDED. It completely disables all basic- browser security features.-</Warning>--This option is for debugging and interacting across cross-origin iFrames when there are no cookies or sensitive data in use.-It's very INSECURE, under no circumstances should you enable this while using real cookies or sensitive data, visiting a single untrusted URL in this mode can immediately compromise all the profile cookies instantly. Consider a less nuclear option like `bypass_csp=True` instead.--#### `deterministic_rendering`--```python-deterministic_rendering: bool = False-```--<Warning>- ⚠️ Setting this to `True` is NOT RECOMMENDED. It can be glitchy & slow, and it- increases chances of getting blocked by anti-bot systems. It's mostly useful- for QA applications.-</Warning>--It's a shortcut for adding these launch args:--- `--deterministic-mode`-- `--js-flags=--random-seed=1157259159`-- `--force-color-profile=srgb`-- `--font-render-hinting=none`-- `--force-device-scale-factor=2`-- `--enable-webgl`--With these options fonts will look slightly worse than macOS and slightly than Windows, but rendering will be more consistent between OSs and runs. The cost is performance and stability. Software rendering is slower, easier to fingerprint as a bot, and sometimes glitchy. You likely _don't need this option_ unless you're trying to do screenshot diffing.--#### `highlight_elements`--```python-highlight_elements: bool = True-```--Highlight interactive elements on the screen with colorful bounding boxes.--#### `viewport_expansion`--```python-viewport_expansion: int = 500-```--Viewport expansion in pixels. With this you can control how much of the page is included in the context of the LLM:--- `-1`: All elements from the entire page will be included, regardless of visibility (highest token usage but most complete).-- `0`: Only elements which are currently visible in the viewport will be included.-- `500` (default): Elements in the viewport plus an additional 500 pixels in each direction will be included, providing a balance between context and token usage.--#### `include_dynamic_attributes`--```python-include_dynamic_attributes: bool = True-```--Include dynamic attributes in selectors for better element targeting.--#### `minimum_wait_page_load_time`--```python-minimum_wait_page_load_time: float = 0.25-```--Minimum time to wait before capturing page state for LLM input.--#### `wait_for_network_idle_page_load_time`--```python-wait_for_network_idle_page_load_time: float = 0.5-```--Time to wait for network activity to cease. Increase to 3-5s for slower websites. This tracks essential content loading, not dynamic elements like videos.--#### `maximum_wait_page_load_time`--```python-maximum_wait_page_load_time: float = 5.0-```--Maximum time to wait for page load before proceeding.--#### `wait_between_actions`--```python-wait_between_actions: float = 0.5-```--Time to wait between agent actions.--#### `cookies_file`--```python-cookies_file: str | None = None-```--JSON file path to save cookies to.--<Warning>-This option is DEPRECATED. Use [`storage_state`](#storage-state) instead, it's the standard playwright format and also supports `localStorage` and `indexedDB`!--The library will automatically save a new `storage_state.json` next to any `cookies_file` path you provide, just use `storage_state='path/to/storage_state.json' to switch to the new format:--`cookies_file.json`: `[{cookie}, {cookie}, {cookie}]`-⬇️-`storage_state.json`: `{"cookies": [{cookie}, {cookie}, {cookie}], "origins": {... optional localstorage state ...}}`--Or run `playwright open https://example.com/ --save-storage=storage_state.json` and log into any sites you need to generate a fresh storage state file.--</Warning>--#### `profile_directory`--```python-profile_directory: str = 'Default'-```--Chrome profile subdirectory name inside of your `user_data_dir` (e.g. `Default`, `Profile 1`, `Work`, etc.).-No need to set this unless you have multiple profiles set up in a single `user_data_dir` and need to use a specific one.--#### `window_position`--```python-window_position: dict | None = {"width": 0, "height": 0}-```--Window position from top-left corner.--#### `save_recording_path`--```python-save_recording_path: str | None = None-```--Directory path for saving video recordings.--#### `trace_path`--```python-trace_path: str | None = None-```--Directory path for saving Agent trace files. Files are automatically named as `{trace_path}/{context_id}.zip`.-------<a name="playwright-parameters"></a>-<a name="playwright"></a>--### Playwright Launch Options--All the parameters below are standard playwright parameters and can be passed to both `BrowserSession` and `BrowserProfile`.-They are defined in `browser_use/browser/profile.py`. See here for the [official Playwright documentation](https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch-persistent-context) for all of these options.--#### `headless`--```python-headless: bool | None = None-```--Runs the browser without a visible UI. If None, auto-detects based on display availability. If you set `headless=False` on a server with no monitor attached, the browser will fail to launch (use `xvfb` + vnc to give a headless server a virtual display you can remote control).--`headless=False` is recommended for maximum stealth and is required for human-in-the-loop workflows.--#### `channel`--```python-channel: BrowserChannel = 'chromium'-```--Browser channel: `['chromium']` (default when `stealth=False`), `'chrome'` (default when `stealth=True`), `'chrome-beta'`, `'chrome-dev'`, `'chrome-canary'`, `'msedge'`, `'msedge-beta'`, `'msedge-dev'`, `'msedge-canary'`--Don't worry, other chromium-based browsers not in this list (e.g. `brave`) are still supported if you provide your own [`executable_path`](#executable_path), just set it to `chromium` for those.--#### `executable_path`--```python-executable_path: str | Path | None = None-```--Path to browser executable for custom installations.--#### `user_data_dir`--```python-user_data_dir: str | Path | None = '~/.config/browseruse/profiles/default'-```--Directory for browser profile data. Set to `None` to use an ephemeral temporary profile (aka incognito mode).--Multiple running browsers **cannot share a single `user_data_dir` at the same time**. You must set it to `None` or-provide a unique `user_data_dir` per-session if you plan to run multiple browsers.--The browser version run must always be equal to or greater than the version used to create the `user_data_dir`.-If you see errors like `Failed to parse Extensions` or similar and failures when launching, you're attempting to run an older browser with an incompatible `user_data_dir` that's already been migrated to a newer schema version.--#### `args`--```python-args: list[str] = []-```--Additional command-line arguments to pass to the browser. See here for the [full list of available chrome launch options](https://peter.sh/experiments/chromium-command-line-switches/).--#### `ignore_default_args`--```python-ignore_default_args: list[str] | bool = ['--enable-automation', '--disable-extensions']-```--List of default CLI args to stop playwright from including when launching chrome. Set it to `True` to disable _all_ default options (not recommended).--#### `env`--```python-env: dict[str, str] = {}-```--Extra environment variables to set when launching browser. e.g. `{'DISPLAY': '1'}` to use a specific X11 display.--#### `chromium_sandbox`--```python-chromium_sandbox: bool = not IN_DOCKER-```--Whether to enable Chromium sandboxing (recommended for security). Should always be `False` when running inside Docker-because Docker provides its own sandboxing can conflict with Chrome's.--#### `devtools`--```python-devtools: bool = False-```--Whether to open DevTools panel automatically (only works when `headless=False`).--#### `slow_mo`--```python-slow_mo: float = 0-```--Slow down actions by this many milliseconds.--#### `timeout`--```python-timeout: float = 30000-```--Default timeout in milliseconds for connecting to a remote browser.--#### `accept_downloads`--```python-accept_downloads: bool = True-```--Whether to automatically accept all downloads.--#### `proxy`--```python-proxy: ProxySettings | None = None-```--Proxy settings (typed). Example:--```python-proxy=ProxySettings(server="http://proxy.com:8080", username="user", password="pass")-```--#### `permissions`--```python-permissions: list[str] = ['clipboard-read', 'clipboard-write', 'notifications']-```--Browser permissions to grant. See here for the [full list of available permission](https://playwright.dev/python/docs/api/class-browsercontext#browser-context-grant-permissions).--#### `storage_state`--```python-storage_state: str | Path | dict | None = None-```--Browser storage state (cookies, localStorage). Can be file path or dict. See here for the [Playwright `storage_state` documentation](https://playwright.dev/python/docs/api/class-browsercontext#browser-context-storage-state) on how to use it.-This option is only applied when launching a new browser using the default builtin playwright chromium and `user_data_dir=None` is set.--```bash-# to create a storage state file, run the following and log into the sites you need once the browser opens:-playwright open https://example.com/ --save-storage=./storage_state.json-# then setup a BrowserSession with storage_state='./storage_state.json' and user_data_dir=None to use it-```--### Playwright Timing Settings--These control how the browser waits for CDP API calls to complete and pages to load.--#### `default_timeout`--```python-default_timeout: float | None = None-```--Default timeout for Playwright operations in milliseconds (e.g. `10000` if you want 10s).--#### `default_navigation_timeout`--```python-default_navigation_timeout: float | None = None-```--Default timeout for page navigation in milliseconds (e.g. `30000` if you want 30s).--### Playwright Viewport Options--Configure browser window size, viewport, and display properties:--#### `user_agent`--```python-user_agent: str | None = None-```--Specific user agent to use in this context. See [`playwright.devices`](https://playwright.dev/python/docs/emulation).--#### `is_mobile`--```python-is_mobile: bool = False-```--Whether the meta viewport tag is taken into account and touch events are enabled.--#### `has_touch`--```python-has_touch: bool = False-```--Specifies if viewport supports touch events.--#### `geolocation`--```python-geolocation: dict | None = None-```--Geolocation coordinates. Example: `{"latitude": 59.95, "longitude": 30.31667}`--#### `locale`--```python-locale: str | None = None-```--Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect the `navigator.language` value, `Accept-Language` request header value as well as number and date formatting rules.--#### `timezone_id`--```python-timezone_id: str | None = None-```--Timezone identifier (e.g. `'America/New_York'` or `'UTC'`).--#### `window_size`--```python-window_size: dict | None = None-```--Browser window size for headful mode. Example: `{"width": 1920, "height": 1080}`--#### `viewport`--```python-viewport: dict | None = None-```--Viewport size with `width` and `height`. Example: `{"width": 1280, "height": 720}`--#### `no_viewport`--```python-no_viewport: bool | None = not headless-```--Disable fixed viewport. Content will resize with window.--_Tip:_ don't use this parameter, it's a playwright standard parameter but it's redundant and only serves to override the `viewport` setting above.-A viewport is _always_ used in headless mode regardless of this setting, and is _never_ used in headful mode unless you pass `viewport={width, height}` explicitly.--#### `device_scale_factor`--```python-device_scale_factor: float | None = None-```--Device scale factor (DPI). Useful for high-resolution screenshots (set it to 2 or 3).--#### `screen`--```python-screen: dict | None = None-```--Screen size available to browser. Auto-detected if not specified.--#### `color_scheme`--```python-color_scheme: ColorScheme = 'light'-```--Preferred color scheme: `'light'`, `'dark'`, `'no-preference'`--#### `contrast`--```python-contrast: Contrast = 'no-preference'-```--Contrast preference: `'no-preference'`, `'more'`, `'null'`--#### `reduced_motion`--```python-reduced_motion: ReducedMotion = 'no-preference'-```--Reduced motion preference: `'reduce'`, `'no-preference'`, `'null'`--#### `forced_colors`--```python-forced_colors: ForcedColors = 'none'-```--Forced colors mode: `'active'`, `'none'`, `'null'`--#### `**playwright.devices[...]`--Playwright provides launch & context arg presets to [emulate common device fingerprints](https://playwright.dev/python/docs/emulation).--```python-BrowserProfile(- ...- **playwright.devices['iPhone 13'], # playwright = await async_playwright().start()-)-```--Because `BrowserSession` and `BrowserProfile` take all the standard playwright args, we are able to support these device presets as well.--### Playwright Security Options--> See `allowed_domains` above too!--#### `offline`--```python-offline: bool = False-```--Emulate network being offline.--#### `http_credentials`--```python-http_credentials: dict | None = None-```--Credentials for HTTP authentication.--#### `extra_http_headers`--```python-extra_http_headers: dict[str, str] = {}-```--Additional HTTP headers to be sent with every request.--#### `ignore_https_errors`--```python-ignore_https_errors: bool = False-```--Whether to ignore HTTPS errors when sending network requests.--#### `bypass_csp`--```python-bypass_csp: bool = False-```--<Warning>- Enabling this can increase security risk and makes the bot very easy to- fingerprint. (Cloudflare, Datadome, etc. will block you)-</Warning>--Toggles bypassing Content-Security-Policy. Enabling reduces some CSP-related errors that can arise from automation scripts injected into pages with strict policies that forbid inline scripts.--#### `java_script_enabled`--```python-java_script_enabled: bool = True-```--<Warning>- Not recommended, untested with Browser Use and likely breaks things.-</Warning>--Whether or not to enable JavaScript in the context.--#### `service_workers`--```python-service_workers: ServiceWorkers = 'allow'-```--Whether to allow sites to register Service workers: `'allow'`, `'block'`--#### `base_url`--```python-base_url: str | None = None-```--Base URL to be used in `page.goto()` and similar operations.--#### `strict_selectors`--```python-strict_selectors: bool = False-```--If true, selector passed to Playwright methods will throw if more than one element matches.--#### `client_certificates`--```python-client_certificates: list[ClientCertificate] = []-```--Client certificates to be used with requests.--### Playwright Recording Options--Note: Browser Use also provides some of our own recording-related options not listed below (see above).--#### `record_video_dir`--<a name="record-video-dir"></a>-<a name="save-recording-path"></a>--```python-record_video_dir: str | Path | None = None-```--Directory to save `.webm` video recordings. [Playwright Docs: `record_video_dir`](https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch-persistent-context-option-record-video-dir)--<Note>- This parameter also has an alias `save_recording_path` for backwards- compatibility with past versions, but we recommend using the standard- Playwright name `record_video_dir` going forward.-</Note>--#### `record_video_size`--```python-record_video_size: dict | None = None. [Playwright Docs: `record_video_size`](https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch-persistent-context-option-record-video-size)--```--Video size. Example: `{"width": 1280, "height": 720}`--#### `record_har_path`--<a name="record-har-path"></a>-<a name="save-har-path"></a>--```python-record_har_path: str | Path | None = None-```--Path to save `.har` network trace files. [Playwright Docs: `record_har_path`](https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch-persistent-context-option-record-har-path)--<Note>- This parameter also has an alias `save_har_path` for backwards compatibility- with past versions, but we recommend using the standard Playwright name- `record_har_path` going forward.-</Note>--#### `record_har_content`--```python-record_har_content: RecordHarContent = 'embed'-```--How to persist HAR content: `'omit'`, `'embed'`, `'attach'`--#### `record_har_mode`--```python-record_har_mode: RecordHarMode = 'full'-```--HAR recording mode: `'full'`, `'minimal'`--#### `record_har_omit_content`--```python-record_har_omit_content: bool = False-```--Whether to omit request content from the HAR.--#### `record_har_url_filter`--```python-record_har_url_filter: str | Pattern | None = None-```--URL filter for HAR recording.--#### `downloads_path`--```python-downloads_path: str | Path | None = '~/.config/browseruse/downloads'-```--(aliases: `downloads_dir`, `save_downloads_path`)--Local filesystem directory to save browser file downloads to.--#### `traces_dir`--<a name="traces-dir"></a>-<a name="trace-path"></a>--```python-traces_dir: str | Path | None = None-```--Directory to save all-in-one trace files. Files are automatically named as `{traces_dir}/{context_id}.zip`. [Playwright Docs: `traces_dir`](https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch-persistent-context-option-traces-dir)--<Note>- This parameter also has an alias `trace_path` for backwards compatibility with- past versions, but we recommend using the standard Playwright name- `traces_dir` going forward.-</Note>--#### `handle_sighup`--```python-handle_sighup: bool = True-```--Whether playwright should swallow SIGHUP signals and kill the browser.--#### `handle_sigint`--```python-handle_sigint: bool = False-```--Whether playwright should swallow SIGINT signals and kill the browser.--#### `handle_sigterm`--```python-handle_sigterm: bool = False-```--Whether playwright should swallow SIGTERM signals and kill the browser.-------## Full Example--```python-from browser_use import BrowserSession, BrowserProfile, Agent--browser_profile = BrowserProfile(- headless=False,- storage_state="path/to/storage_state.json",- wait_for_network_idle_page_load_time=3.0,- viewport={"width": 1280, "height": 1100},- locale='en-US',- user_agent='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.102 Safari/537.36',- highlight_elements=True,- viewport_expansion=500,- allowed_domains=['*.google.com', 'http*://*.wikipedia.org'],- user_data_dir=None,-)--browser_session = BrowserSession(- browser_profile=browser_profile,- headless=True, # extra kwargs to the session override the defaults in the profile-)--# you can drive a session without the agent / reuse it between agents-await browser_session.start()--# Navigate using events-from browser_use.browser.events import NavigateToUrlEvent-navigate_event = browser_session.event_bus.dispatch(NavigateToUrlEvent(url='https://example.com/first/page'))-await navigate_event--async def run_search():- agent = Agent(- task='Your task',- llm=llm,- browser_session=browser_session, # optional: pass an existing browser session to an agent- )-```-------## Summary--- **BrowserSession** (defined in `browser_use/browser/session.py`) handles the live browser connection and runtime state-- **BrowserProfile** (defined in `browser_use/browser/profile.py`) is a template that can store default config parameters for a `BrowserSession(...)`--Configuration parameters defined in both scopes consumed by these calls depending on whether we're connecting/launching:--- `BrowserConnectArgs` - args for `playwright.BrowserType.connect_over_cdp(...)`-- `BrowserLaunchArgs` - args for `playwright.BrowserType.launch(...)`-- `BrowserNewContextArgs` - args for `playwright.BrowserType.new_context(...)`-- `BrowserLaunchPersistentContextArgs` - args for `playwright.BrowserType.launch_persistent_context(...)`-- Browser Use's own internal methods--For more details on Playwright's browser context options, see their [launch args documentation](https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch-persistent-context).-----diff --git a/docs/docs.json b/docs/docs.jsonindex 8cbb6efd8..74eb6653b 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -49,8 +49,17 @@"customize/agent-output-format"]},- "customize/browser-settings",- "customize/real-browser",+ {+ "group": "Browser",+ "icon": "globe",+ "isDefaultOpen": false,+ "pages": [+ "customize/browser-basic",+ "customize/browser-real-browser",+ "customize/browser-remote",+ "customize/browser-parameters"+ ]+ },"customize/sensitive-data","customize/custom-functions"]