browser-use/browser-use
The installable package is browser_use, built with hatchling and exposed as the console scripts browser-use, browseruse, bu, and browser (browser_use.cli:main), plus python -m browser_use. The runtime splits into an Agent orchestrator, a BrowserSession that owns a bubus event bus and a cdp-use CDP client, a Tools/Registry action layer, and a DomService that serializes the page for the model. Persistence is local (temp agent directories, cookie storage state, config under ~/.config/browseruse) plus optional cloud event sync. External systems are the Browser Use cloud browser API, the LLM gateway, the sandbox stream API, PostHog telemetry, and optional provider SDKs (OpenAI, Anthropic, Google, Groq, Ollama, AWS, MCP). CI is GitHub Actions: per-file pytest of tests/ci, ruff/pre-commit/pyright, PyPI publish on GitHub release, and a multi-arch Docker image.
- pyproject.toml names the package browser-use version 0.13.10, requires Python >=3.11,<4.0, and registers console scripts browser-use, browseruse, bu, and browser to browser_use.cli:main, with the deprecated browser-use-tui alias.
- The public import surface is lazy: browser_use/__init__.py __getattr__ loads Agent, Tools, Controller, DomService, Chat* model classes, and sandbox on first access, and maps the name Browser to BrowserSession.
- python -m browser_use calls browser_use.cli.main and exits with its return code.
- Agent in browser_use/agent/service.py is the task orchestrator. BrowserSession in browser_use/browser/session.py owns the CDP connection, tab targets, and a bubus event bus; start() is handled by on_BrowserStartEvent, which attaches watchdogs before launching or connecting.
- BrowserSession.attach_all_watchdogs constructs Downloads, StorageState (conditional), LocalBrowser, Security, AboutBlank, Popups, Permissions, DefaultAction, Screenshot, DOM, Recording, optional HAR, and optional Captcha watchdogs. CrashWatchdog registration in that method is commented out.
- Local Chrome is started by LocalBrowserWatchdog.on_BrowserLaunchEvent → _launch_browser, which returns a psutil.Process and a CDP URL. Cloud browsers are created when BrowserProfile.use_cloud or cloud_browser_params is set, via CloudBrowserClient.create_browser POST {api}/api/v2/browsers using BROWSER_USE_API_KEY or CloudAuthConfig.
- Configuration is env-driven. OldConfig and FlatEnvConfig in browser_use/config.py read BROWSER_USE_LOGGING_LEVEL, ANONYMIZED_TELEMETRY, BROWSER_USE_CLOUD_SYNC, BROWSER_USE_CLOUD_API_URL (default https://api.browser-use.com), LLM keys, and proxy vars. Config, profiles, and extensions live under BROWSER_USE_CONFIG_DIR, defaulting to ~/.config/browseruse.
- If Agent is constructed with llm=None and DEFAULT_LLM is empty, it instantiates ChatBrowserUse(). get_llm_by_name in browser_use/llm/models.py is the string factory for openai_, azure_, google_, anthropic_, mistral_, cerebras_, and bu_ names and refuses OCI (use ChatOCIRaw directly).
- ChatBrowserUse posts to BROWSER_USE_LLM_URL or https://llm.api.browser-use.com, default model bu-2-0, and requires BROWSER_USE_API_KEY. The @sandbox decorator posts cloudpickled user code to https://sandbox.api.browser-use.com/sandbox-stream.
- CI test workflow .github/workflows/test.yaml discovers every tests/ci/**/test_*.py and runs them as a matrix on ubuntu with uv, IN_DOCKER=true, and ANONYMIZED_TELEMETRY=false. lint.yml runs ruff PLE, pre-commit, and pyright. publish.yml uploads to PyPI on GitHub release. docker.yml builds and publishes the image. The root Dockerfile is python:3.12-slim with IN_DOCKER=True.
- DomService.get_dom_tree / get_serialized_dom_tree is the DOM boundary the agent consumes. FileSystem and ScreenshotService are rooted at a per-run temp directory tempfile.gettempdir()/browser_use_agent_{id}_{timestamp} unless file_system_path is passed.