browser-use · repository health snapshot

browser-use: how healthy is this repository?

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.

52source files
16,334source lines
24test files
14modules
Adequateoverall health

1. Summary

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.

RatingScaleScore
Engineering standards7/10 Good
Security5/10 Fair
Configuration and secrets6/10 Fair
Data and persistence6/10 Fair
Error handling and resilience8/10 Good
Availability and recovery6/10 Fair
Performance and scale6/10 Fair
Indicative ratings from a quick read. The full assessment works through every criterion in depth and often finds more, so its ratings are usually the same or lower.

2. Architecture at a glance

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).

module dependencies 10 13 13 14 15 17 20 21 22 28 35 36 40 45 86 149 153 194 260 444 no edge drawn bin 3 files browser_use 16 files browser_use/agent 6 files browser_use/browser 3 files browser_use/llm 1 file browser_use/mcp 3 files browser_use/repl 8 files browser_use/skills 3 files browser_use/telemetry 6 files docker 1 file examples 1 file scripts 1 file tests/ci 24 files
Figure 1 · module dependenciesGenerated from 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.
ModuleFilesWhat it owns
tests/ci24The CI test suite: a real REPL worker, a real headless Chrome and a scripted model, no provider or cloud calls.
browser_use16Shared 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/repl8The REPL: the parent-side session (spawn, allowlisted environment, redaction) and the worker that runs cells, plus captcha, capture, highlight and page helpers.
browser_use/agent6The public Agent, the Pydantic AI loop with budgets, retries and delivery, the system prompt, the run judge and the result views.
browser_use/telemetry6Anonymised usage telemetry to PostHog, run recording and stats, and user feedback.
browser_use/mcp3The --cli-mcp MCP server that exposes the REPL as browser_exec and browser_screenshot tools.
browser_use/browser3The Browser class: cloud browsers on API v4, local Chromium, the user's Chrome, CDP URLs, and their start, stop and cleanup.
browser_use/skills3The shipped browser-use agent skill and its installer.
(repo root)3Top-level code files outside any package.
bin3Developer shell scripts for setup, lint and test.
browser_use/llm1Model resolution: the Browser Use gateway default, the ChatOpenAI / ChatAnthropic / ChatGoogle wrappers and model strings.
scripts1Syncs the browser-harness skill text into this repository.
docker1A smoke test run inside the published container image.
examples1One minimal usage example.
Entry point kindCountWhere
Library API (import browser_use)1browser_use/__init__.py, lazily exporting Agent, Browser, Tools and the Chat classes
Console scripts3browser-use, browseruse and the deprecated browser-use-tui, declared in pyproject.toml
Module mains (python -m or __main__)5browser_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)1browser-use --cli-mcp in browser_use/mcp/cli_mcp.py
Developer and CI scripts5bin/setup.sh, bin/lint.sh, bin/test.sh, scripts/sync_browser_harness_skill.py, docker/smoke.py

3. Ratings

Engineering standards

Engineering standards: 7/10, Good

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.

Security rating

Security: 5/10, Fair

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.

Configuration and secrets rating

Configuration and secrets: 6/10, Fair

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.

Data and persistence rating

Data and persistence: 6/10, Fair

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).

Error handling and resilience rating

Error handling and resilience: 8/10, Good

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.

Availability and recovery rating

Availability and recovery: 6/10, Fair

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.

Performance and scale rating

Performance and scale: 6/10, Fair

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.

4. Findings a quick read turned up

SeverityFindingsRatings they fall under
High1Security
Medium5Security, Configuration and secrets, Data and persistence, Availability and recovery
Low5Engineering 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.

The three that matter most

SeverityFindingRating
HighA 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
MediumScreenshots, including any secret visible in a typed field, reach the model provider and the run judge unredacted.Security rating
MediumUsage telemetry is on by default and sends visited URLs, error messages and final results to a third-party analytics host.Data and persistence rating

5. What the full report covers

The Full Audit and Documentation report of this repository documents:

  • 61 configuration variables, each with where it is read and what sets it
  • 151 external integrations, with what breaks when each is unavailable
  • 17 outbound hosts the code calls, each checked against what the code is for
  • 26 infrastructure and packaging paths probed, present or absent
  • 6 observability signals, present or absent
  • Every entry point, with where it is declared and what handles it
  • The seven ratings reasoned criterion by criterion, with the evidence for each
  • Every finding in a severity-rated risk register, with its evidence
  • A remediation roadmap: what to fix now, next and later, each with its effort
  • README corrections as a patch, and the documents linked into one set
Download