Skip to content

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

Update documentation for browser customization

Magnus Müller483c824e806e
diff --git a/docs/customize/browser-keep-open.mdx b/docs/customize/browser-keep-open.mdx
index 9fe85479c..7e46d87c7 100644
--- a/docs/customize/browser-keep-open.mdx
+++ b/docs/customize/browser-keep-open.mdx
@@ -1,7 +1,7 @@
---
-title: "Chain agents in one browser"
+title: "Reuse same browser"
description: ""
-icon: "window-restore"
+icon: "repeat"
mode: "wide"
---
@@ -13,20 +13,18 @@ browser = Browser(
headless=False,
keep_alive=True, # Don't close browser after each agent
)
-
+tasks = [
+ 'Search for Browser Use',
+ 'Click on the first link',
+ 'Find the social media page',
+]
async def main():
- # Run multiple agents with the same browser
- agent1 = Agent(task='Search for Browser Use', browser=browser)
- await agent1.run()
-
- agent2 = Agent(task='Click on the first link', browser=browser)
- await agent2.run()
+ for task in tasks:
+ agent = Agent(task=task, browser=browser)
+ await agent.run()
- agent3 = Agent(task='Find the social media page', browser=browser)
- await agent3.run()
- # Close browser when completely done
await browser.stop()
```
diff --git a/docs/customize/browser-multiple.mdx b/docs/customize/browser-multiple.mdx
new file mode 100644
index 000000000..5493ac23b
--- /dev/null
+++ b/docs/customize/browser-multiple.mdx
@@ -0,0 +1,109 @@
+---
+title: "Multiple Browser Instances"
+description: "Run multiple agents in parallel with separate browser instances"
+icon: "copy"
+---
+
+Run multiple browser-use agents simultaneously, each with their own isolated browser instance.
+
+## Basic Example
+
+```python
+import asyncio
+from browser_use import Agent, Browser, ChatOpenAI
+
+async def main():
+ # Create 3 separate browser instances
+ browsers = [
+ Browser(
+ user_data_dir=f'./temp-profile-{i}',
+ headless=False, # Set to True for production
+ keep_alive=True,
+ )
+ for i in range(3)
+ ]
+
+ # Create 3 agents with different tasks
+ agents = [
+ Agent(
+ task='Search for "browser automation" on Google',
+ browser=browsers[0],
+ llm=ChatOpenAI(model='gpt-4.1-mini'),
+ ),
+ Agent(
+ task='Search for "AI agents" on DuckDuckGo',
+ browser=browsers[1],
+ llm=ChatOpenAI(model='gpt-4.1-mini'),
+ ),
+ Agent(
+ task='Visit Wikipedia and search for "web scraping"',
+ browser=browsers[2],
+ llm=ChatOpenAI(model='gpt-4.1-mini'),
+ ),
+ ]
+
+ print('🚀 Starting 3 agents in parallel...')
+
+ # Run all agents in parallel
+ tasks = [agent.run() for agent in agents]
+ results = await asyncio.gather(*tasks, return_exceptions=True)
+
+ # Print results
+ for i, result in enumerate(results):
+ if isinstance(result, Exception):
+ print(f'❌ Agent {i+1} failed: {result}')
+ else:
+ print(f'✅ Agent {i+1} completed successfully')
+
+ # Clean up browsers
+ print('🧹 Cleaning up browsers...')
+ for browser in browsers:
+ await browser.stop()
+
+ print('🎉 All agents completed!')
+
+if __name__ == '__main__':
+ asyncio.run(main())
+```
+
+## How it Works
+
+1. **Separate Profiles**: Each browser gets a unique `user_data_dir` to avoid conflicts
+2. **Parallel Execution**: `asyncio.gather()` runs all agents simultaneously
+3. **Isolated Sessions**: Each agent operates independently
+4. **Resource Management**: Browsers are properly cleaned up after completion
+
+## Key Benefits
+
+- ✅ **True Parallelism**: Multiple tasks execute simultaneously
+- ✅ **Isolation**: Each browser has separate cookies, cache, and state
+- ✅ **Scalability**: Add more browsers/agents as needed
+- ✅ **Resource Efficiency**: Clean shutdown prevents memory leaks
+
+## Best Practices
+
+```python
+# Use headless for production
+browsers = [
+ Browser(
+ user_data_dir=f'./profile-{i}',
+ headless=True, # Better performance
+ keep_alive=True,
+ )
+ for i in range(5)
+]
+
+# Handle errors gracefully
+results = await asyncio.gather(*tasks, return_exceptions=True)
+for i, result in enumerate(results):
+ if isinstance(result, Exception):
+ print(f'Agent {i+1} error: {result}')
+
+# Always clean up
+finally:
+ for browser in browsers:
+ try:
+ await browser.stop()
+ except Exception as e:
+ print(f'Cleanup error: {e}')
+```
diff --git a/docs/customize/browser-real-browser.mdx b/docs/customize/browser-real-browser.mdx
index ac7998d0d..a2e5cbec3 100644
--- a/docs/customize/browser-real-browser.mdx
+++ b/docs/customize/browser-real-browser.mdx
@@ -1,251 +1,57 @@
---
-title: "Connect to Real Browser"
-description: "Connect Browser Use to your existing browser instances and manage persistent profiles"
+title: "Real Browser"
+description: ""
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.
+Connect Browser Use to your existing Chrome browser to preserve authentication and use extensions.
----
-
-## 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:
+## Basic Example
```python
-from browser_use import Browser
+from browser_use import Agent, Browser, ChatOpenAI
-session = Browser(
- cdp_url="http://localhost:9222",
- is_local=False # Don't launch new browser
+# Connect to your existing Chrome browser
+browser = Browser(
+ executable_path='/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+ user_data_dir='~/Library/Application Support/Google/Chrome',
+ profile_directory='Default',
)
-```
-
-### Method 2: Using Browser Profile Path
-Connect to an existing Chrome profile:
-
-```python
-session = Browser(
- user_data_dir="/path/to/existing/chrome/profile",
- executable_path="/path/to/chrome", # Optional: specify browser location
+agent = Agent(
+ task='Visit https://duckduckgo.com and search for "browser-use founders"',
+ browser=browser,
+ llm=ChatOpenAI(model='gpt-4.1-mini'),
)
+async def main():
+ await agent.run()
```
-## Browser Profile Management
+> **Note:** You need to fully close chrome before running this example.
-### Persistent Profiles
+> **Note:** Google blocks this approach currently so we use DuckDuckGo instead.
-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
-)
+## How it Works
-session = Browser(browser_profile=profile)
-```
+1. **`executable_path`** - Path to your Chrome installation
+2. **`user_data_dir`** - Your Chrome profile folder (keeps cookies, extensions, bookmarks)
+3. **`profile_directory`** - Specific profile name (Default, Profile 1, etc.)
-### 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 = Browser(browser_profile=profiles["testing"])
-```
-
-## Authentication & Cookies
-
-### Loading Saved Authentication
-
-```python
-# Method 1: Storage state (recommended)
-session = Browser(
- storage_state="./saved-auth.json",
- user_data_dir=None # Use temporary profile with loaded auth
-)
-
-# Method 2: Existing profile with cookies
-session = Browser(
- 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 Browser
-```
-
-### Saving Authentication for Reuse
+## Platform Paths
```python
-# Keep browser alive to maintain session
-session = Browser(
- 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)
-await agent1.run()
-
-agent2 = Agent(task="Update profile", browser=session)
-await agent2.run()
-
-# Manually close when done
-await session.stop()
-```
-
-## Browser Extensions
+# macOS
+executable_path='/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
+user_data_dir='~/Library/Application Support/Google/Chrome'
-### Using Existing Extensions
+# Windows
+executable_path='C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'
+user_data_dir='%LOCALAPPDATA%\\Google\\Chrome\\User Data'
-```python
-# Connect to browser with your installed extensions
-session = Browser(
- user_data_dir="/path/to/chrome/profile/with/extensions",
- # Extensions will be available automatically
-)
-```
-
-### Default Extensions
-
-Browser Use includes automation-friendly extensions:
-
-```python
-session = Browser(
- 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 = Browser(
- 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 = Browser(
- 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 = Browser(
- cdp_url="http://localhost:9222",
- timeout=5000 # Fail fast if can't connect
-)
-```
-
-### Profile Conflicts
-```python
-# Avoid conflicts with existing browser instances
-session = Browser(
- 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 = Browser(
- permissions=['clipboard-read', 'clipboard-write', 'notifications'],
- bypass_csp=True # If needed for specific sites
-)
-```
-
----
+# Linux
+executable_path='/usr/bin/google-chrome'
+user_data_dir='~/.config/google-chrome'
+```
\ No newline at end of file
diff --git a/docs/customize/browser-remote.mdx b/docs/customize/browser-remote.mdx
index d88180961..be211f6b4 100644
--- a/docs/customize/browser-remote.mdx
+++ b/docs/customize/browser-remote.mdx
@@ -5,19 +5,6 @@ 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
@@ -35,105 +22,6 @@ session = Browser(
)
```
-### With Authentication
-
-For secured remote browsers:
-
-```python
-session = Browser(
- 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 = Browser(
- 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 = [
- Browser(cdp_url=url, is_local=False)
- for url in cloud_browsers
-]
-```
-
## Advanced Remote Configuration
### Proxy Through Remote Browser
@@ -164,163 +52,4 @@ session = Browser(
)
```
-## Connection Management
-
-### Connection Pooling
-
-```python
-class BrowserPool:
- def __init__(self, remote_urls):
- self.sessions = [
- Browser(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)
-```
-
-### 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 = [
- Browser(cdp_url=url, is_local=False)
- for url in healthy_urls
-]
-```
-
-## Security Considerations
-
-### Secure Connections
-
-```python
-# Use HTTPS when possible
-session = Browser(
- 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 = Browser(
- 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 = Browser(cdp_url=cdp_url, is_local=False, keep_alive=True)
-
- results = []
- for task in tasks:
- agent = Agent(task=task, browser=session)
- result = await agent.run()
- results.append(result)
-
- await session.stop() # Clean shutdown
- return results
-```
-
-### Resource Management
-
-```python
-# Monitor resource usage
-session = Browser(
- 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 = Browser(
- 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 = Browser(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 = Browser(
- cdp_url="http://remote:9222",
- is_local=False
-)
-# Check logs for detailed connection information
-```
-
---
diff --git a/docs/customize/real-browser.mdx b/docs/customize/real-browser.mdx
index 08c7246da..7573eb186 100644
--- a/docs/customize/real-browser.mdx
+++ b/docs/customize/real-browser.mdx
@@ -233,14 +233,14 @@ reused_profile = BrowserProfile(user_data_dir='~/.config/browseruse/profiles/def
agent1 = Agent(
task="The first task...",
- llm=ChatOpenAI(model="gpt-4.1-mini-mini"),
+ llm=ChatOpenAI(model="gpt-4.1-mini"),
browser_profile=reused_profile, # pass the profile in, it will auto-create a session
)
await agent1.run()
agent2 = Agent(
task="The second task...",
- llm=ChatOpenAI(model="gpt-4.1-mini-mini"),
+ llm=ChatOpenAI(model="gpt-4.1-mini"),
browser_profile=reused_profile, # agent will auto-create its own new session
)
await agent2.run()
@@ -265,14 +265,14 @@ await reused_session.start() # when keep_alive=True, session must be started m
agent1 = Agent(
task="The first task...",
- llm=ChatOpenAI(model="gpt-4.1-mini-mini"),
+ llm=ChatOpenAI(model="gpt-4.1-mini"),
browser=reused_session,
)
await agent1.run()
agent2 = Agent(
task="The second task...",
- llm=ChatOpenAI(model="gpt-4.1-mini-mini"),
+ llm=ChatOpenAI(model="gpt-4.1-mini"),
browser=reused_session, # re-use the same session
)
await agent2.run()
@@ -305,13 +305,13 @@ tabs = await browser.get_tabs()
# Create agents that will work with different tabs
agent1 = Agent(
task="The first task...",
- llm=ChatOpenAI(model="gpt-4.1-mini-mini"),
+ llm=ChatOpenAI(model="gpt-4.1-mini"),
browser=browser,
)
agent2 = Agent(
task="The second task...",
- llm=ChatOpenAI(model="gpt-4.1-mini-mini"),
+ llm=ChatOpenAI(model="gpt-4.1-mini"),
browser=browser,
)
@@ -343,12 +343,12 @@ await navigate_event
agent1 = Agent(
task="Fill out the form in section A...",
- llm=ChatOpenAI(model="gpt-4.1-mini-mini"),
+ llm=ChatOpenAI(model="gpt-4.1-mini"),
browser=shared_session
)
agent2 = Agent(
task="Fill out the form in section B...",
- llm=ChatOpenAI(model="gpt-4.1-mini-mini"),
+ llm=ChatOpenAI(model="gpt-4.1-mini"),
browser=shared_session,
)
diff --git a/docs/customize/system-prompt.mdx b/docs/customize/system-prompt.mdx
index 23c72654a..4d6329db8 100644
--- a/docs/customize/system-prompt.mdx
+++ b/docs/customize/system-prompt.mdx
@@ -67,7 +67,7 @@ Always suggest exploring multiple options before making a decision.
# Create agent with extended planner system prompt
llm = ChatOpenAI(model='gpt-4.1-mini')
-planner_llm = ChatOpenAI(model='gpt-4.1-mini-mini')
+planner_llm = ChatOpenAI(model='gpt-4.1-mini')
agent = Agent(
task="Your task here",
diff --git a/docs/docs.json b/docs/docs.json
index 376222100..40e926c37 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -55,8 +55,9 @@
"isDefaultOpen": false,
"pages": [
"customize/browser-basic",
- "customize/browser-keep-open",
"customize/browser-real-browser",
+ "customize/browser-keep-open",
+ "customize/browser-multiple",
"customize/browser-remote",
"customize/browser-parameters"
]
diff --git a/examples/browser/real_browser.py b/examples/browser/real_browser.py
index 1092a8aca..09fef6670 100644
--- a/examples/browser/real_browser.py
+++ b/examples/browser/real_browser.py
@@ -8,21 +8,22 @@ from dotenv import load_dotenv
load_dotenv()
-from browser_use import Agent, BrowserProfile, BrowserSession, ChatOpenAI
+from browser_use import Agent, Browser, ChatOpenAI
-browser_profile = BrowserProfile(
+# Connect to your existing Chrome browser
+browser = Browser(
executable_path='/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
user_data_dir='~/Library/Application Support/Google/Chrome',
profile_directory='Default',
)
-browser_session = BrowserSession(browser_profile=browser_profile)
async def main():
agent = Agent(
llm=ChatOpenAI(model='gpt-4.1-mini'),
+ # Google blocks this approach, so we use a different search engine
task='Visit https://duckduckgo.com and search for "browser-use founders"',
- browser_session=browser_session,
+ browser=browser,
)
await agent.run()