browser-use · repository health snapshot
Created · run_mwilecsj653de18f2be52119 · github.com/browser-use/browser-use @ main · commit 4b5b1b0aa0ab · model claude-opus-5-5
A five-minute read on the health of the browser-use 1.0 library at commit 4b5b1b0, with seven ratings and the findings a quick read turned up.
browser-use is a Python library and CLI that runs a browser agent: a model, by default the Browser Use gateway's bu-4.0, writes Python that a persistent REPL worker executes against a Chromium browser over raw CDP, with the 0.x Agent / Browser / Tools API kept on top of a Pydantic AI loop. Browsers are cloud browsers by default (Browser Use API v4), or a local Chromium, the user's own Chrome, or any CDP endpoint, and an MCP server exposes the same REPL to coding agents.
Overall health: Adequate. The engineering is careful (exactly pinned dependencies, 24 test files that drive a real headless Chrome, explicit timeouts and cleanup on every outbound path), but its central design runs model-written Python as the user's own account with no sandbox, so a prompt-injected page can reach the user's keys and files, and the code documents that risk rather than containing it.
| Rating | Scale | Score |
|---|---|---|
| Engineering standards | 7/10 Good | |
| Security | 5/10 Fair | |
| Configuration and secrets | 6/10 Fair | |
| Data and persistence | 6/10 Fair | |
| Error handling and resilience | 8/10 Good | |
| Availability and recovery | 6/10 Fair | |
| Performance and scale | 6/10 Fair |
The package is one library with a thin layering: browser_use/agent owns the run and calls down into repl, browser, llm and telemetry, while the top-level browser_use package holds shared helpers (auth, domains, config, CLI) that most modules call back into. Several pairs depend on each other both ways, the largest being browser_use/browser and browser_use (40 calls one way, 20 back) and browser_use/telemetry and browser_use (28 and 21).
modules.cjs, so it matches the tables in this section exactly. Columns are dependency depth: a module sits one column right of everything that calls into it. Line thickness is the number of calls and imports crossing that boundary, and an edge that loops underneath is a cycle, drawn rather than hidden. The 5 modules under “no edge drawn” take part in none of the edges shown, heaviest first. The accented box is the module with the most files.| Module | Files | What it owns |
|---|---|---|
| tests/ci | 24 | The CI test suite: a real REPL worker, a real headless Chrome and a scripted model, no provider or cloud calls. |
| browser_use | 16 | Shared core: API key lookup and login, domain allow and block rules, .env loading, the CLI, cloud harness, accessibility-tree helpers, update check and 0.x removed-name errors. |
| browser_use/repl | 8 | The REPL: the parent-side session (spawn, allowlisted environment, redaction) and the worker that runs cells, plus captcha, capture, highlight and page helpers. |
| browser_use/agent | 6 | The public Agent, the Pydantic AI loop with budgets, retries and delivery, the system prompt, the run judge and the result views. |
| browser_use/telemetry | 6 | Anonymised usage telemetry to PostHog, run recording and stats, and user feedback. |
| browser_use/mcp | 3 | The --cli-mcp MCP server that exposes the REPL as browser_exec and browser_screenshot tools. |
| browser_use/browser | 3 | The Browser class: cloud browsers on API v4, local Chromium, the user's Chrome, CDP URLs, and their start, stop and cleanup. |
| browser_use/skills | 3 | The shipped browser-use agent skill and its installer. |
| (repo root) | 3 | Top-level code files outside any package. |
| bin | 3 | Developer shell scripts for setup, lint and test. |
| browser_use/llm | 1 | Model resolution: the Browser Use gateway default, the ChatOpenAI / ChatAnthropic / ChatGoogle wrappers and model strings. |
| scripts | 1 | Syncs the browser-harness skill text into this repository. |
| docker | 1 | A smoke test run inside the published container image. |
| examples | 1 | One minimal usage example. |
| Entry point kind | Count | Where |
|---|---|---|
Library API (import browser_use) | 1 | browser_use/__init__.py, lazily exporting Agent, Browser, Tools and the Chat classes |
| Console scripts | 3 | browser-use, browseruse and the deprecated browser-use-tui, declared in pyproject.toml |
Module mains (python -m or __main__) | 5 | browser_use/__main__.py, browser_use/cli.py, browser_use/mcp/__main__.py, browser_use/mcp/cli_mcp.py, browser_use/repl/worker.py (spawned by the parent, not by users) |
| MCP server (stdio) | 1 | browser-use --cli-mcp in browser_use/mcp/cli_mcp.py |
| Developer and CI scripts | 5 | bin/setup.sh, bin/lint.sh, bin/test.sh, scripts/sync_browser_harness_skill.py, docker/smoke.py |
Weakest: structure and modularity
Ruff, pyright and pre-commit are configured in pyproject.toml and enforced in .github/workflows/lint.yml, every dependency is pinned exactly, and 24 test files drive a real Chrome, with no TODO or FIXME in source. What holds it back is size: 13 source files exceed 500 lines, five exceed 950 (browser_use/agent/loop.py is 1,354), and _install in browser_use/repl/worker.py:494 is a single 445-line function.
Weakest: input validation and injection
The REPL worker executes model-written Python as the user's own account, and the model reads untrusted web pages, so a prompt injection becomes code execution that can read the parent's .env and ~/.config/browser-harness/auth.json and send them anywhere, since the REPL's own networking is not domain-checked (MIGRATING.md "Trust model for secrets" says "This is not a sandbox"). Supply chain is strong: SHA-pinned actions and PyPI trusted publishing in .github/workflows/publish.yml, and a credential-free allowlisted worker environment in browser_use/repl/session.py:79.
Weakest: secret storage
Secrets live in plain files: the API key from browser-use login is read from browser-harness's stored auth record (browser_use/auth.py), and browser_use/config.py:14 loads the first .env found walking up from the working directory into the process environment. Configuration is otherwise externalised and validated early (cloud_timeout range checks and 0.x option TypeErrors in browser_use/browser/browser.py:599), though .env.example documents about a dozen of the 61 variables the code reads.
Weakest: personal data
The library keeps no database (the evidence found no store); its data is workspace files, checkpoints and a telemetry outbox. Telemetry is on unless ANONYMIZED_TELEMETRY is set false (browser_use/config.py:37) and sends the URLs visited, error messages and the final result, scrubbed of emails, keys and digit runs, to eu.i.posthog.com (browser_use/telemetry/service.py:35).
Weakest: surfacing and swallowing
browser_use/agent/loop.py sets a deadline on every model request (300 s, 930 s streamed), retries a transient provider error once after its Retry-After, kills and restarts a hung cell's worker tree, and keeps partial results through timeouts, while browser_use/browser/browser.py:502 stops billed cloud browsers on exit, SIGTERM and SIGHUP. Against that, the evidence counts 39 empty or comment-only error handlers, nine of the first ten listed in browser_use/ax.py.
Weakest: single points of failure
As a library it has no service to keep up, but its defaults put both the model (the gateway in browser_use/llm/__init__.py:29) and the browser (API v4 in browser_use/browser/browser.py:48) on Browser Use's cloud, so one outage there stops a default run. Release safety is good: .github/workflows/publish.yml checks for a required-reviewer environment and smoke-tests the built wheel before publishing.
Weakest: load evidence
Context growth is bounded on purpose: images are pruned past 20 tool results keeping the last 2 (browser_use/agent/loop.py:85), the context is compacted when it overflows, and the judge trace is capped at 120,000 characters (browser_use/agent/judge.py:48). Nothing in the repository measures throughput or concurrency of the library itself; the README's benchmark scores models on task quality, not load.
| Severity | Findings | Ratings they fall under |
|---|---|---|
| High | 1 | Security |
| Medium | 5 | Security, Configuration and secrets, Data and persistence, Availability and recovery |
| Low | 5 | Engineering standards, Security, Error handling and resilience, Performance and scale |
These counts are a floor, not a total: they are at least the findings a quick read turned up. The full report works through every rating criterion and lists each finding with its evidence.
| Severity | Finding | Rating |
|---|---|---|
| High | A prompt-injected web page can steer model-written Python that runs unsandboxed as the user to read local keys and files and send them off the machine. | Security rating |
| Medium | Screenshots, including any secret visible in a typed field, reach the model provider and the run judge unredacted. | Security rating |
| Medium | Usage telemetry is on by default and sends visited URLs, error messages and final results to a third-party analytics host. | Data and persistence rating |
The Full Audit and Documentation report of this repository documents: