Agent.run() starts the browser and stops it when the run ends, unless keep_alive=True. Every Browser(...) parameter with its default: All parameters.
Cloud browser
Browser() creates a Browser Use Cloud browser through API v4, with a 1440x900 screen. It needs your Browser Use key (see Quickstart).
A cloud browser bills until it stops. browser-use stops it when the run ends, when your process exits, or on SIGTERM or SIGHUP. See pricing and Cloud browser features.
A cloud browser cannot reach
localhost or your private network. When the task mentions one, the agent logs a warning that suggests Browser('chromium').
The proxy applies to the browser only. Python networking in the agent’s cells (http_get, urllib, requests) runs on your machine. When the location matters, say “in the browser” in the task.
Local Chromium
No Chrome installed (servers, CI)? Run
browser-use install once to download Playwright’s Chromium.
Files the browser downloads land in agent.workspace/downloads. See Files.
Fresh local browsers and Chrome profile copies expose an unauthenticated debugging port on 127.0.0.1. Other users on the same machine can attach and access the browser and its logins; use a container or cloud browser on shared machines.
Your Chrome
Browser('chrome') attaches to the Chrome you have open: your tabs, cookies and logins.
- Open
chrome://inspect/#remote-debuggingand turn remote debugging on (once). - Run the agent and click Allow when Chrome asks.
Browser('chrome') runs at a time.
Browser('chrome', profile='Work') launches a new Chrome on a temporary copy of the profile Work (its display name or directory, such as 'Profile 1'). A name that matches none raises BrowserConfigError (a ValueError) from run(), listing your profiles. You get its logins; sync is off and nothing is written back. Your Chrome can stay open, except on Windows, where you must quit it first. headless and executable_path work here too.
Any CDP endpoint
http:// URL is resolved through /json/version. Custom connection headers are not supported yet (headers= raises): use a cdp_url that needs no headers. Downloads stay in that browser’s own download folder.
Keep a browser between runs
keep_alive=True leaves the browser running after run(). One keep_alive browser can serve several agents, one after another. Stop it yourself:
Parallel agents
Give each agent its own browser. Two agents running on oneBrowser at once raise RuntimeError.
Browser() per request, not one at module level. Browser('chrome') can’t run in parallel: every one in a process shares one daemon and one attached tab.
Each agent holds a few open files (model connection, REPL socket, worker pipe). run() raises the process’s soft open-file limit to 10240, or the hard limit if lower, so 100 agents in one process fit on macOS, which starts at 256. It never lowers a limit.
Options that raise
Options that don’t fit the browser raise aValueError that names the right call, for example headless on a cloud browser or profile on 'chromium'. Removed 0.x options raise a TypeError with the replacement:
The full list is in Migrating.