Connect to your Browser
Connect to a remote browser or launch a new local browser.
Overview
Browser Use supports a wide variety of ways to launch or connect to a browser:
- Launch a new local browser using playwright/patchright chromium (the default)
- Connect to a remote browser using CDP or WSS
- Use an existing playwright
Page
,Browser
, orBrowserContext
object - Connect to a local browser already running using
browser_pid
Don’t want to manage your own browser infrastructure? Try ☁️ Browser Use Cloud ➡️
We provide automatic CAPTCHA solving, proxies, human-in-the-loop automation, and more!
Connection Methods
Method A: Launch a New Local Browser (Default)
Launch a local browser using built-in default (playwright chromium
) or a provided executable_path
:
We support most chromium
-based browsers in executable_path
, including Brave, patchright chromium, rebrowser, Edge, and more. See examples/browser/stealth.py
for more. We do not support Firefox or Safari at the moment.
As of Chrome v136, driving browsers with the default profile is no longer supported for security reasons. Browser-Use has transitioned to creating a new dedicated profile for agents in: ~/.config/browseruse/profiles/default
. You can open this profile and log into everything you need your agent to have access to, and it will persist over time.
Method B: Connect Using Existing Playwright Objects
Pass existing Playwright Page
, BrowserContext
, Browser
, and/or playwright
API object to BrowserSession(...)
:
You can also pass page
directly to Agent(...)
as a shortcut.
Method C: Connect to Local Browser Using Browser PID
Connect to a browser with open --remote-debugging-port
:
Method D: Connect to remote Playwright Node.js Browser Server via WSS URL
Connect to Playwright Node.js server providers:
Method E: Connect to Remote Browser via CDP URL
Connect to any remote Chromium-based browser:
Security Considerations
When using any browser profile, the agent will have access to:
- All its logged-in sessions and cookies
- Saved passwords (if autofill is enabled)
- Browser history and bookmarks
- Extensions and their data
Always review the task you’re giving to the agent and ensure it aligns with your security requirements!
Use Agent(sensitive_data={'https://auth.example.com': {x_key: value}})
for any secrets, and restrict the browser with BrowserSession(allowed_domains=['https://*.example.com'])
.
Best Practices
-
Use isolated profiles: Create separate Chrome profiles for different agents to limit scope of risk:
-
Limit domain access: Restrict which sites the agent can visit:
-
Enable keep_alive for multiple tasks: Keep the browser open between agent runs:
Re-Using a Browser
A BrowserSession
starts when the browser is launched/connected, and ends when the browser process exits/disconnects. A session internally manages a single live playwright browser context, and is normally auto-closed by the agent when its task is complete (if the agent started the session itself). If you pass an existing BrowserSession
into an Agent, or if you set BrowserSession(keep_alive=True)
, the session will not be closed and can be re-used between agents.
Browser Use provides a number of ways to re-use profiles, sessions, and other configuration across multiple agents.
- ✅ sequential agents can re-use a single
user_data_dir
in newBrowserSession
s - ✅ sequential agents can re-use a single
BrowserSession
without closing it - ❌ parallel agents cannot run separate
BrowserSession
s using the sameuser_data_dir
- ✅ parallel agents can run separate
BrowserSession
s using the samestorage_state
- ✅ parallel agents can share a single
BrowserSession
, working in different tabs - ⚠️ parallel agents can share a single
BrowserSession
, working in the same tab
Sequential Agents, Same Profile, Different Browser
If you are only running one agent & browser at a time, they can re-use the same user_data_dir
sequentially.
Make sure to never mix different browser versions or
executable_path
s with the sameuser_data_dir
. Once run with a newer browser version, some migrations are applied to the dir and older browsers wont be able to read it.
Sequential Agents, Same Profile, Same Browser
If you are only running one agent at a time, they can re-use the same active BrowserSession
and avoid having to relaunch chrome.
Parallel Agents, Same Browser, Multiple Tabs
Parallel Agents, Same Browser, Same Tab
⚠️ This mode is not recommended. Agents are not yet optimized to share the same tab in the same browser, they may interfere with each other or cause errors.
Parallel Agents, Same Profile, Different Browsers
This mode is the recommended default.
To share a single set of configuration or cookies, but still have agents working in their own browser sessions (potentially in parallel), use our provided BrowserProfile
object.
The recommended way to re-use cookies and localStorage state between separate parallel sessions is to use the storage_state
option.
Troubleshooting
Chrome Won’t Connect
If you’re having trouble connecting:
- Close all Chrome instances before trying to launch with a custom profile
- Check if Chrome is running with debugging port:
- Verify the executable path is correct for your system
- Check profile permissions - ensure your user has read/write access
Profile Lock Issues
If you get a “profile is already in use” error:
- Close all Chrome instances
- The profile will automatically be unlocked when BrowserSession starts
- Alternatively, manually delete the
SingletonLock
file in the profile directory
For more configuration options, see the Browser Settings documentation.
Profile Version Issues
The browser version you 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
when launching, you’re likely attempting to run an older browser with an incompatible user_data_dir
that’s already been migrated to a newer Chrome version.
Playwright ships a version of chromium that’s newer than the default stable Google Chrome release channel, so this can happen if you try to use
a profile created by the default playwright chromium (e.g. user_data_dir='~/.config/browseruse/profiles/default'
) with an older
local browser like executable_path='/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
.