browser-use · Architecture

Browser Use 1.0: how the system is designed

Created · run_mwili3mq0ddb28b28cf0a330 · github.com/browser-use/browser-use @ main · commit 4b5b1b0aa0ab · model claude-opus-5-5

How the browser-use 1.0 library, CLI and MCP server are built: an Agent on Pydantic AI that has the model write Python in a separate REPL worker process, which drives a cloud or local Chrome through the browser-harness daemon.

52source files (16,334 lines)
769test functions in 23 test modules
29entry points
77environment variables
17hosts called from code

1. What the system is

Browser Use is an open-source Python library, with a command-line tool and an MCP server alongside it, that carries out a task in a real web browser on someone's behalf. You describe the task in plain words ("find the earliest driving test slot and book it"), and a language model does the work in a browser: it looks at the page, writes a few lines of Python to click, type or read, checks what happened, and repeats until it can hand back a verified answer and any files it downloaded. Version 1.0.6 does this differently from the 0.x releases. The model no longer picks one action per step from a dump of the page. It writes Python in one persistent REPL that has the browser-harness helpers and raw Chrome DevTools Protocol (CDP) access, while the 0.x programming interface (Agent, Browser, Tools, run and the result object) is kept on top so existing code keeps working.

The parts a reader meets throughout this document:

The actors around it. The developer writes a script that creates an Agent and runs it, and reads the result. The model does the browsing: by default bu-4.0 on the Browser Use LLM gateway (https://api.browser-use.com/api/v4/llm/v1), or a model the developer chooses from OpenAI, Anthropic, Google, Azure OpenAI or any OpenAI-compatible server. Coding agents (Claude Code and similar tools) drive a browser without the Agent at all, by piping Python to the browser-use command or calling the MCP server's browser_exec tool; the package ships an agent skill and an installer for them. Browser Use Cloud supplies browsers, the default model, search and the API key that the browser-use login command stores. The websites visited are untrusted input: their text reaches the model, so a page can try to steer it. PostHog (eu.i.posthog.com) receives anonymous usage telemetry, on by default and switched off with ANONYMIZED_TELEMETRY=false.

What it is for: letting a program, or another AI agent, complete web tasks that have no API (filling forms, booking, searching, extracting data, downloading files) by delegating the clicking and reading to a model, with budgets, timeouts and a delivery step that make sure a run always ends with an answer, a status and a cost. It is a library and tools that run on the user's machine or in a container; the repository deploys no servers of its own.

Engineering standards

Engineering standards: 8/10, Good

Good. The score rests on enforcement: 769 test functions in 23 modules run in CI on Linux, macOS and Windows across Python 3.11 to 3.14 plus a job against a real headless Chrome, ruff, pre-commit and pyright gate every push and pull request, and every dependency, action and base image is pinned. Against that stand 13 files over 500 lines, 9 functions over 100 lines (the longest, the worker's helper installer, at 445), 39 empty or comment-only error handlers, a narrow ruff rule set with pyright in basic mode, and a little dead code; the problems are local, not structural. The technical assessment gives the reasoning per criterion.

RatingScaleScore
Engineering standards8/10 Good
Security7/10 Good
Configuration and secrets7/10 Good
Data and persistence6/10 Fair
Error handling and resilience8/10 Good
Availability and recovery6/10 Fair
Performance and scale7/10 Good
Each rating is reasoned in the section it names; 6 or below is carried into the risk register.

2. Business process

The system serves one job: someone has a web task with no API behind it, and wants it done and handed back with proof of what happened and what it cost. Seen from the person running it, a library run goes through the steps below. They are the steps a user would recognise in their own terms, not the order of calls in the code.

Before anything is billed The work Wrapping up 01 Task plain words, model, browser 02 Preflight key, model and search checked 03 Browser start cloud by default, billing begins 04 Write and check small Python steps, repeated 05 Delivery answer and files handed back 06 Browser stops billing ends, downloads copied 07 Judge optional, on by default: graded 08 Result status, answer, cost, downloads repeat until the result is verified a failed preflight skips straight to an error result, with no browser started
Figure 2.1 · a run in the user's termsThe two highlighted steps are the business rules that matter most: preflight protects the user's money before a cloud browser is billed, and delivery guarantees a run ends with an answer rather than running out of budget mid-task. The browser stops before the judge runs, so judging adds no browser time.

A library run, step by step

  1. Write the task. The developer describes what they want in plain language ("find the earliest slot and book it"), optionally with a schema for the answer, secrets the model may type without seeing, and domains it may visit.README.md, browser_use/agent/service.py
  2. Pick a model and a browser. Without a choice, the model is bu-4.0 on the Browser Use LLM gateway and the browser is a Browser Use Cloud browser. Either can be swapped: another provider's model, a fresh local Chromium, the user's own Chrome, or a browser at a CDP address.browser_use/llm/__init__.py:29, browser_use/browser/browser.py:517
  3. Preflight: check before paying. The library makes sure there is an API key (a missing Browser Use key stops the run with an error before any browser starts), then asks the gateway or the model's provider whether the key and model are good, and checks the search endpoint when web search is on. If any of these fails, the run ends here with status error and no browser has been created, so nothing has been billed.browser_use/agent/service.py:483-498, browser_use/llm/__init__.py:439, browser_use/auth.py:117-142
  4. The browser starts. A cloud browser is created (and from this moment bills by the hour), or a local one is launched or attached. A workspace folder is created for the run; downloads land in it.browser_use/agent/service.py:500-512
  5. The model works in small steps. It looks at the page (a screenshot and, in the faster mode, the page's accessibility tree), writes a few lines of Python to act, reads what came back, and repeats. Each step is checked by the model before it moves on, and it is told to verify the result before claiming it. A step that hangs past 120 seconds is cut off and the model is told that actions may already have happened, so it looks before trying again.browser_use/agent/loop.py, browser_use/agent/prompt.py, browser_use/repl/session.py
  6. Delivery. When the work is done the model hands back its answer and points to any files it wrote. If the run is about to run out of budget (the step limit, 100 by default; the time limit, 1700 s by default; or the browser has gone away), the model is told to stop browsing and deliver what it has, and one repair turn is allowed if that delivery is malformed. A run that still ends without a full answer returns the partial results it saved along the way.browser_use/agent/service.py:443, browser_use/agent/loop.py:140-150, browser_use/agent/loop.py:423
  7. The browser stops. Unless the developer asked to keep it alive for another task, the browser is stopped; for a cloud browser that ends the billing, and its downloads are copied into the workspace's downloads folder. The workspace itself is kept for the developer to read and delete.browser_use/agent/service.py:663-671, browser_use/agent/service.py:350
  8. The judge grades the run (optional). On by default, one more request to the same model compares what was delivered with the task (and with the developer's expected answer or criteria, if given) and records success or failure, the reason, and whether the page tried to steer the model. Its cost is added to the run's cost. The judge never fails a run: if it cannot answer, the run simply has no judgement.browser_use/agent/service.py:600-620, browser_use/agent/judge.py
  9. The result comes back. The developer gets one result object: the status (completed, max_steps, timeout or error), the answer, whether it succeeded, the judgement, token usage, cost in dollars and the list of downloaded files.browser_use/agent/views.py

The order of the last three steps is the source's. In Agent._run (browser_use/agent/service.py:547-596) the final screenshot for the judge is taken while the browser is still up, then the shutdown stops the browser (and, for a cloud browser, the billing), and only after that does the judge request run; the comment there reads "after the browser stopped (a cloud browser bills until then)".

The coding-agent path

A second, shorter process serves coding agents such as Claude Code, which want a browser as a tool rather than an agent of their own. There is no task, no budget, no delivery and no judge here: the coding agent is the one thinking, and the browser is its hands.

  1. Install and sign in. The user installs the package, optionally installs the bundled browser-use skill into their coding agent, and signs in once with the browser-use login command, which stores a Browser Use API key for later runs.browser_use/cli.py, browser_use/skills/install.py
  2. Send a step. The coding agent pipes a few lines of Python to the browser-use command, or, when it talks MCP, calls the browser_exec tool. The code runs against the browser-harness helpers and a browser that stays open between calls, local by default or a cloud browser once started.browser_use/cli.py:795, browser_use/mcp/cli_mcp.py:442-520
  3. Read and repeat. The output (and a screenshot, when asked for) comes back to the coding agent, which decides the next step itself until its own task is done.browser_use/mcp/cli_mcp.py

3. Entry points

Work enters browser-use in four ways: 29 entry points in all, made of 2 library calls, 11 process entries, 12 CLI commands and 4 MCP tools. A developer's Python code calls the library (Agent.run or Agent.run_sync). A shell, a container or a parent process starts one of the process entries. A person or coding agent types a command that _dispatch in browser_use/cli.py:1065 routes. And an MCP host such as a coding assistant calls one of the four tools that CLIMCPServer declares in _tool_definitions (browser_use/mcp/cli_mcp.py:442) and answers through handle_call_tool and call_tool.

The three console scripts come from [project.scripts] in pyproject.toml: browser-use and its alias browseruse both run browser_use.cli:main, and the deprecated browser-use-tui runs browser_use.cli:browser_use_tui_main, which prints a deprecation line and calls the same main. Every CLI path, including python -m browser_use and the Docker image's ENTRYPOINT ["browser-use"], therefore converges on one dispatcher. main wraps _dispatch so that every command, including a failing one, sends one telemetry event, unless the command was handed to browser-harness, which then records it itself. _dispatch answers --help, --version and --update inline before it imports anything heavy (--update only prints how to upgrade browser-use and exits 2, so it is not counted as an entry point), then routes install, init, skill and feedback without touching browser-harness. Only after that does it check that browser-harness can create its directories, and only then does it route --cli-mcp, --mcp, doctor, login, logout and, with no arguments and a pipe on stdin, the piped Python itself.

Several commands accept more than one spelling, and each spelling counts as one entry point here: doctor also answers to --doctor, login and logout also answer to browser-harness's auth login and auth logout, --help also answers to -h and help, --version also answers to -V, and init also catches --template and -t. Removed 0.x command names are not entry points: _legacy_command recognises them and prints a migration message with exit code 2.

Three of the process entries are not user-facing. The REPL worker (python -P -m browser_use.repl.worker) is spawned only by Repl._start in browser_use/repl/session.py:357, once per Agent, and reads its port and token from the environment the parent sets. docker/smoke.py runs only in the docker.yml workflow against a built image. scripts/sync_browser_harness_skill.py is a maintainer tool that regenerates the shipped SKILL.md from the pinned browser-harness. examples/simple.py is a runnable sample with no function of its own: it calls Agent.run_sync at module level.

The evidence's grep found 25 matches across 15 files, and that list is not the inventory. It includes Markdown code samples (skills/cloud/references/guides/chat-ui.md, skills/open-source/SKILL.md and three in skills/x402/SKILL.md), a JavaScript addEventListener string inside browser_use/ax.py:139, and test helpers in tests/ci (test_agent.py, test_captcha.py, test_harness_cloud.py, test_local_browser.py). None of those are ways work enters the system. The grep also cannot see the library calls, the console scripts, the CLI subcommands or the MCP tools. Those were read from pyproject.toml, _dispatch and _tool_definitions.

Entry points 29 rows
Entry pointKindFile:lineHandlerWhat it does
Agent.runLibrary callbrowser_use/agent/service.py:443Agent.runValidates max_steps (default 100 model requests) and timeout (default 1700 s), refuses a second concurrent run on the same Agent or Browser, then runs the task and returns an AgentHistoryList. Unsupported 0.x keyword arguments raise a TypeError before any browser starts.
Agent.run_syncLibrary callbrowser_use/agent/service.py:629Agent.run_syncRuns Agent.run on an asyncio.Runner it keeps while the REPL lives, so a keep_alive browser can serve several synchronous runs. Raises if called inside a running event loop.
browser-useProcess entry (console script)browser_use/cli.py:1178mainReads sys.argv, hands it to _dispatch, and records one telemetry event per command with its exit code and the tail of stderr, unless browser-harness already recorded it. Returns the command's exit code.
browseruseProcess entry (console script alias)browser_use/cli.py:1178mainThe same function as browser-use, registered under a second name in pyproject.toml.
browser-use-tuiProcess entry (deprecated console script)browser_use/cli.py:1173browser_use_tui_mainPrints that browser-use-tui is deprecated and calls main; the 0.x terminal UI no longer exists.
python -m browser_useProcess entry (module)browser_use/__main__.py:7mainCalls the CLI's main and exits with its result, so the module form behaves exactly like browser-use.
Docker ENTRYPOINTProcess entry (container)Dockerfile:215mainThe image's ENTRYPOINT ["browser-use"] runs the console script, so arguments to docker run are CLI arguments and piped stdin is piped Python.
python -m browser_use.mcpProcess entry (0.x MCP module)browser_use/mcp/__main__.py:8_run_mcp_serverWarns that the 0.x MCP server is deprecated, applies the 0.x config's domain restrictions, and serves the four --cli-mcp tools over stdio on the server's own Chromium, never the user's Chrome.
python -m browser_use.mcp.cli_mcpProcess entry (MCP server module)browser_use/mcp/cli_mcp.py:900main (cli_mcp.py:889)Sets BH_CLIENT and BU_MODEL_CODE, builds a CLIMCPServer and runs it over stdio until the client goes away.
REPL workerProcess entry (child process)browser_use/repl/worker.py:1135mainConnects back to the parent on 127.0.0.1 with the port and token from its environment, receives the secrets to redact, installs the browser helpers into a fresh namespace, then runs each cell the parent sends. Spawned only by Repl._start.
docker/smoke.pyProcess entry (CI only)docker/smoke.py:27mainRuns one Agent on the image's own headless Chromium with a scripted FunctionModel and exits non-zero unless the run completes with the expected page title. No provider and no network.
scripts/sync_browser_harness_skill.pyProcess entry (maintainer script)scripts/sync_browser_harness_skill.py:81mainRegenerates the Browser Use SKILL.md from the pinned browser-harness skill and writes it to the repo and package copies. With --check it writes nothing and fails with a diff if either copy is stale.
examples/simple.pyProcess entry (sample script)examples/simple.py:13Agent.run_syncModule-level code: builds an Agent with the default model and cloud browser, calls Agent.run_sync and prints the final result.
piped Python on stdinCLI command (no arguments, stdin is a pipe)browser_use/cli.py:795_run_browser_harnessPatches browser-harness for browser-use (daemon names, page info, screenshots, plain-HTTP http_get, cloud browser guard) and runs the piped code through browser-harness's runner against the shared daemon. Empty stdin and a missing sign-in are caught earlier, in _dispatch, which exits 1 with a message.
loginCLI commandbrowser_use/cli.py:376_run_login_commandSigns in to Browser Use Cloud through browser-harness's auth CLI (browser, device code, or a key on stdin with --api-key-stdin) and stores the key in the shared auth store. Records the outcome as a telemetry auth event.
logoutCLI commandbrowser_use/cli.py:427_run_logout_commandRemoves the stored key through browser-harness's auth CLI. A corrupt store file is deleted directly and reported as logged out.
installCLI commandbrowser_use/cli.py:299_run_install_commandRuns uvx playwright install chromium (with system dependencies on Linux) for Browser('chromium'), then prints the four browser choices. Exits 1 if uvx is not on the path.
initCLI command (removed in 1.0)browser_use/cli.py:441_run_init_commandPrints that project templates were removed in 1.0 and a three-line starting snippet, and exits 2.
skillCLI commandbrowser_use/skills/install.py:146handleWith show (the default) prints the packaged SKILL.md as UTF-8; with install writes it into one or all coding assistants' skill directories, optionally reinstalling browser-use as a uv tool.
feedbackCLI commandbrowser_use/cli.py:450_run_feedback_commandSends one scrubbed library_feedback event to the Browser Use team from the arguments or stdin, even with usage statistics off, and waits for the send so the confirmation it prints is true.
doctorCLI commandbrowser_use/cli.py:251_run_doctorPrints the browser-use and browser-harness versions, the local browser found, whether Chrome and the daemon are running, and whether a cloud key exists. Exits 1 only when there is neither a local browser nor a key.
--mcpCLI command (deprecated MCP server)browser_use/cli.py:184_run_mcp_serverSame handler as python -m browser_use.mcp: serves the --cli-mcp tools on the server's own Chromium with the 0.x domain restrictions, exiting 2 on an invalid domain pattern.
--cli-mcpCLI command (MCP server)browser_use/cli.py:206_run_cli_mcp_serverStarts the browser_use.mcp.cli_mcp server over stdio with logging silenced, driving the user's own Chrome until a cloud browser is started.
--versionCLI command (inline)browser_use/cli.py:1071_dispatchPrints the browser-use and browser-harness versions and exits 0, before the TLS opener or browser-harness is imported.
--helpCLI command (inline)browser_use/cli.py:1066_dispatchPrints browser-use's own help text, not browser-harness's, and exits 0.
browser_execMCP toolbrowser_use/mcp/cli_mcp.py:445call_toolRuns the given Python in the server's persistent namespace with the browser-harness helpers, under the server's lock, and returns what it printed, cut to the cell output cap with the full text saved to a temp file. A failure sets the result's is_error.
browser_screenshotMCP toolbrowser_use/mcp/cli_mcp.py:467call_toolCaptures the current page, optionally full-page or downscaled to max_dim, and returns it as a PNG image block. Errors come back as a tool result, never a protocol error.
browser_loginMCP toolbrowser_use/mcp/cli_mcp.py:482call_toolStarts or continues a Browser Use Cloud sign-in in a thread and returns either "signed in" or the URL to approve, never the key.
browser_feedbackMCP toolbrowser_use/mcp/cli_mcp.py:499call_toolValidates the message and sends one feedback event through feedback.mcp_call, at most a fixed number per server process. Its definition lives in MCP_TOOL in browser_use/telemetry/feedback.py:29.

Functions the entry points route through

The inventory names these functions without being their row's handler. Each is listed once here.

FunctionFile:lineWhat it does
_dispatchbrowser_use/cli.py:1065Routes CLI arguments to a command handler and returns its exit code with the command name for telemetry. Checks browser-harness's directories before any command that needs them, and turns the not-signed-in and cloud browser errors into one-line messages.
_legacy_commandbrowser_use/cli.py:890Recognises a removed 0.x command in the arguments and returns its name, so _dispatch can print the migration message instead of running it.
_run_mcp_stdio_serverbrowser_use/cli.py:133Silences logging, imports the named MCP module and runs its main on a new event loop. Both --mcp and --cli-mcp start their server through it.
_tool_definitionsbrowser_use/mcp/cli_mcp.py:442Returns the four MCP tool declarations (name, description, input schema) that tools/list reports to the client.
handle_call_toolbrowser_use/mcp/cli_mcp.py:506The tools/call request handler: calls call_tool, collects the errors raised during the call, and records one telemetry entry per call with its duration.
call_toolbrowser_use/mcp/cli_mcp.py:520Dispatches a tool call by name to the exec, screenshot, login or feedback path and wraps the answer as an MCP result. A 0.x tool name gets a "removed" message and any other name "Unknown tool".
Repl._startbrowser_use/repl/session.py:357Closes any previous worker, then spawns python -P -m browser_use.repl.worker in its own process group with an allowlisted environment and waits for it to connect back with a 32-byte random token.
feedback.mcp_callbrowser_use/telemetry/feedback.py:98Handles a browser_feedback call: rejects an empty message, enforces the per-process limit, sends the event and returns the reply text with an error flag.

4. Module boundaries

A filesystem has no modules, so the boundaries here are path prefixes, grouped by modules.cjs from the call and import graph. Its grouping rule, verbatim: grouped by path prefix under ./, starting at depth 2; a group over 25 files is split one level deeper, and only children with 8+ files are promoted. The defaults were used (--big 25, --min-child 8); no tuning was needed. The result is 14 module groups covering 79 files. The tool printed 20 cross-module edges, the top 20 by count (20 more below the top 20 were not printed), and 11 two-way pairs. It ignored 129 edges with an end outside ./.

Read the file counts before the edges. Only tests/ci (24 files) and the top-level browser_use package (16 files) are large. The subsystems the architecture diagram in CLAUDE.md names are small, dense groups. browser_use/repl has 8 files, browser_use/agent 6 and browser_use/browser 3, and browser_use/llm is a single 1-file module, browser_use/llm/__init__.py. Four groups (bin, scripts, docker, examples) are tooling at the repository's edge, and (repo root) is 3 files: pyproject.toml, server.json and context7.json.

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.

Figure 1 draws 13 of the 14 groups. (repo root) holds only the packaging and manifest files above, which take part in no call or import edge, so the figure leaves it out. The table below lists all 14.

Module groups

To drill from one of these groups to its files, its functions and classes, and their callers and callees, use the symbol index.

ModuleFilesWhat it owns
tests/ci24The whole test suite: 23 pytest modules and conftest.py. They use a real REPL worker, a real headless Chrome and a scripted Pydantic AI FunctionModel instead of a provider.
browser_use16The top-level package and its shared modules. These are the public API re-exports (__init__.py), the CLI (cli.py, __main__.py), API key and login (auth.py), configuration, domain rules (domains.py), shared utilities and exceptions, the 0.x removal errors (legacy.py), ultrafast accessibility helpers (ax.py), Tools, web search, cloud browsers for the CLI and MCP server (harness_cloud.py), remote file upload, the update check and logging setup.
browser_use/repl8The REPL. It has a parent side (session.py) and the worker process (worker.py), plus the helpers loaded into the worker: captcha handling, screenshot capture, action highlights, network-idle waiting and page_info.
browser_use/agent6The 0.x-compatible Agent (service.py), the Pydantic AI loop with budgets and delivery (loop.py), the judge, the system prompt and the result views (AgentHistoryList).
browser_use/telemetry6Anonymous product telemetry: the PostHog client and its outbox (service.py), event schemas, the per-run recorder, scrubbing and statistics, and user feedback reports.
browser_use/mcp3The MCP server for coding agents (cli_mcp.py, the browser-use --cli-mcp model) and the python -m browser_use.mcp entry.
browser_use/browser3The Browser class for the four browser kinds (browser.py) and local Chromium discovery and launch (local.py).
browser_use/skills3The browser-use agent skill text and its installer, which writes it into coding agents' skill directories.
(repo root)3pyproject.toml (package metadata, pins, console scripts), server.json (MCP registry manifest) and context7.json (Context7 documentation config).
bin3Developer shell scripts: setup.sh, lint.sh and test.sh.
browser_use/llm1Model resolution: the ChatBrowserUse, ChatOpenAI, ChatAnthropic and ChatGoogle wrappers, model strings, the Browser Use gateway default and the provider preflight.
scripts1A maintainer script that syncs the shipped skill text with browser-harness's own skill.
docker1smoke.py, the image smoke test docker.yml runs: one Agent run on the image's own Chromium with a scripted model.
examples1simple.py, the one shipped usage example.

Cross-module edges

These are the 20 edges modules.cjs printed, heaviest first, counting calls and imports with both ends under ./. The six heaviest all start in tests/ci. That measures how much of each module the suite exercises, not coupling. Among package code, browser_use/agent is the hub. It reaches the top-level package (45), the REPL (36), telemetry (35) and the model layer (15).

Cross-module edges 20 rows
FromToCount
tests/cibrowser_use/agent444
tests/cibrowser_use/browser260
tests/cibrowser_use/repl194
tests/cibrowser_use153
tests/cibrowser_use/llm149
tests/cibrowser_use/telemetry86
browser_use/agentbrowser_use45
browser_use/browserbrowser_use40
browser_use/agentbrowser_use/repl36
browser_use/agentbrowser_use/telemetry35
browser_use/telemetrybrowser_use28
tests/cibrowser_use/mcp22
browser_usebrowser_use/telemetry21
browser_usebrowser_use/browser20
browser_use/mcpbrowser_use17
browser_use/agentbrowser_use/llm15
browser_use/replbrowser_use14
browser_use/llmbrowser_use13
browser_use/mcpbrowser_use/telemetry13
browser_usebrowser_use/mcp10

Two-way pairs

modules.cjs found 11 module pairs where the dependency runs both ways. They are: tests/ci and browser_use/repl; tests/ci and browser_use; browser_use/agent, browser_use/browser, browser_use/telemetry, browser_use/mcp, browser_use/repl, browser_use/llm and browser_use/skills, each paired with browser_use; browser_use/repl and browser_use/telemetry; and browser_use/browser and browser_use/repl.

Most of these cycles run through the top-level browser_use package. Eight of the 11 pairs have it at one end. In the heavy direction, the subpackages import its shared modules: mostly utils.py, exceptions.py, auth.py, legacy.py and domains.py, and also config.py. The light direction comes from four top-level files. __init__.py lazily re-exports Agent, AgentHistoryList, Browser, the Chat* classes and feedback, which makes the agent and llm pairs. cli.py reuses browser, MCP, REPL, skills and telemetry code for its commands. auth.py sends login telemetry. harness_cloud.py reuses the browser module's daemon checks. Inside the package, two pairs connect subpackages. In the REPL and telemetry pair, the worker uses telemetry's URL and error classifiers, and telemetry reuses the REPL's secret redaction. In the browser and REPL pair, each side calls the other's half of the process cleanup that kills REPL workers before browsers stop.

The two pairs with tests/ci are not cycles in the code. Their light directions, browser_use/repl to tests/ci (2 edges) and browser_use to tests/ci (1 edge), are not package code importing tests: no module under browser_use/ imports anything from tests/. The reverse edges are name collisions in the graph. repl/worker.py and repl/capture.py hold browser-harness's CDP sender in a local named raw_cdp, which the graph resolved to the test double of that name. repl/worker.py's event handling was likewise matched to the test helper events. auth.py:224 calls its own callback parameter answer, which the graph resolved to a test function of that name. The graph also links domains.py to test_domains.py through a comment. Both pairs are artefacts of the analysis, not cycles in the code.

PairA to BB to AWhat the light direction is
tests/ci <-> browser_use/repl1942Not a real dependency: graph name collisions with test helpers (see the paragraph above).
tests/ci <-> browser_use1531Not a real dependency: a callback in auth.py resolved to a test function of the same name.
browser_use/agent <-> browser_use452The lazy re-export of Agent and AgentHistoryList in __init__.py.
browser_use/browser <-> browser_use4020cli.py and harness_cloud.py calling the browser module's daemon and local Chromium helpers, and the Browser re-export.
browser_use/telemetry <-> browser_use2821cli.py and auth.py sending telemetry and feedback events, and the feedback re-export.
browser_use/mcp <-> browser_use1710cli.py reusing the MCP server's Chromium install and no-browser messages.
browser_use/repl <-> browser_use144cli.py installing the REPL's page_info and screenshot patches and its plain-HTTP fetch into browser-harness.
browser_use/llm <-> browser_use134The lazy re-export of the Chat* classes in __init__.py.
browser_use/repl <-> browser_use/telemetry87Telemetry statistics and feedback reusing the REPL's secret redaction, while the worker uses telemetry's URL and error classifiers.
browser_use/skills <-> browser_use32cli.py dispatching browser-use skill to the installer.
browser_use/browser <-> browser_use/repl22Process cleanup split across both: the browser module kills REPL workers, and the REPL session installs the browser module's exit cleanup.

Functions this section names

The two package functions named above, and the three test functions that the reverse edges of the tests/ci pairs resolved to:

FunctionWhereWhat it does
page_infobrowser_use/repl/page_info.py:28Replaces browser-harness's page_info helper with one that retries while a new document has no root element yet, for up to a fixed wait. The REPL worker, the CLI and the MCP server all install it.
feedbackbrowser_use/telemetry/feedback.py:87Sends a user's bug, docs or missing-feature report to the Browser Use team in the background, with secrets, keys, emails and URL queries replaced first. It is re-exported from the top-level package and sends even when usage stats are off.
raw_cdptests/ci/test_repl.py:742A fake CDP sender for a screenshot test. It records each method and reports the tab as hidden until it is activated, so the hidden-tab capture fallback can be tested without a browser.
eventstests/ci/test_telemetry.py:187Waits up to a timeout for a fake PostHog server to receive a given number of telemetry events, and returns them.
answertests/ci/test_search.py:138Accepts one connection on a local socket and replies with a broken HTTP response. It stands in for the search endpoint in a test that checks the search preflight never raises.

5. Layered call graph

This is the backbone of the system as the call graph records it: 33 functions in three layers. The entry layer is where work arrives: Agent.run and Agent.run_sync for the library, the CLI's main, and the REPL worker's main. The orchestration layer is the Agent's run lifecycle and the CLI's dispatch. The services layer covers model resolution and the agent loop, the REPL's parent side, the worker's helper setup, and the browser's start path down to the keyed HTTP request to Browser Use Cloud.

Only edges the graph records are drawn: 27 of them, each checked against graphdata.json. Four calls that happen at run time are not in the graph and are not drawn. Agent._run awaits Browser.start on its browser and loop.run (imported under its bare name), and the extractor resolved neither. python reaches Repl.call through the session object Pydantic AI passes it. Browser._start_cloud runs Browser._create on a thread pool, not by a direct call. So the Agent lane, the REPL lane and the Browser lane look disconnected in the figure, but at run time they form one chain: the Agent starts the browser, opens a REPL on the environment it returns, and every python tool call goes through Repl.call into the worker process.

The dashed vertical rule marks the one process boundary on this figure. Everything left of it runs in the caller's process. The worker's main and _install run in the child process that Repl._start spawns, which connects back over a 127.0.0.1 socket. That hop is a spawn and a socket, not a call, so no edge crosses the rule.

entry orchestration services agent/ · llm/ · telemetry/ repl/session.py (parent) repl/worker.py (child) browser.py · utils.py cli.py Agent.run_sync Agent.run main (worker.py) main (cli.py) Agent._run Agent._shutdown Agent._build Agent._judge Agent._capture _dispatch _run_browser_harness resolve_model _resolve_model provider_preflight build_agent python judge_run telemetry usage_and_cost loop.run Repl.call Repl._call Repl.start Repl._start worker_env _install Browser.start Browser._start_locked Browser._start Browser._start_cloud thread pool: not in graph Browser._create _cloud urlopen_keyed
Figure 2 · layered call graphBands are layers (entry, orchestration, services). Columns are subsystems, labelled at the top with the files they come from. Every arrow is an edge recorded in the call graph. The dashed arrow from build_agent to python is an indirect call: the function is registered as the agent's tool, not called. Four runtime calls are not in the graph and are not drawn: Agent._run to Browser.start and to loop.run, python to Repl.call, and Browser._start_cloud to Browser._create through a thread pool. The dashed vertical rule is the process boundary between the caller's process and the REPL worker.

Three things the figure shows that the source does not show in one place. First, everything that can fail before money is spent sits above the browser. Agent._build resolves the model and raises on a missing key, and Agent._run calls provider_preflight before the browser starts. Second, cost is accounted twice, once for the loop and once for the judge, both through usage_and_cost. Third, every keyed request the Browser sends to Browser Use Cloud's browser API (create, stop, profile lookup) goes through _cloud, and so through urlopen_keyed. Downloaded files are fetched from plain URLs without the key, and the CLI and MCP server reach cloud browsers through browser-harness instead. The CLI lane is separate by design: _run_browser_harness hands piped code to browser-harness's own runner and never touches the Agent, the REPL worker or the Pydantic AI loop.

Functions drawn in Figure 2 33 rows
FunctionLayerWhereWhat it does
Agent.runentrybrowser_use/agent/service.py:443The library's main call. It checks max_steps (default 100) and timeout (default 1700 s), refuses a second concurrent run on the same Agent or Browser, and runs the task through Agent._run.
Agent.run_syncentrybrowser_use/agent/service.py:629Runs Agent.run on a private event loop for code without one, and keeps that loop alive while a kept-alive REPL still needs it. It raises if called from inside a running event loop.
main (CLI)entrybrowser_use/cli.py:1178The browser-use and browseruse console script. It passes the arguments to _dispatch and sends a CLI telemetry event with the command, its duration, its result and the tail of stderr.
main (worker)entrybrowser_use/repl/worker.py:1135The REPL worker process. It connects back to the parent on 127.0.0.1 with its token, builds the cell namespace, then runs each cell it receives, sending output through a redacting pump into that cell's file.
Agent._runorchestrationbrowser_use/agent/service.py:466The body of a run. It preflights the model and search before any browser is billed, starts the browser, opens or reuses the REPL and calls loop.run; afterwards it stops or keeps the browser, collects downloads, then judges and sends telemetry.
Agent._buildorchestrationbrowser_use/agent/service.py:378Resolves the model, works out its price reference and whether it runs on the gateway, and builds the Pydantic AI agent with the prompts for the browser kind, search and domain rules. It runs once per Agent, before any browser starts.
Agent._judgeorchestrationbrowser_use/agent/service.py:600Asks the run's own model, once, to judge a run that took steps, and adds the judge's tokens and cost to the result. A failed judgement is logged and never fails the run.
Agent._captureorchestrationbrowser_use/agent/service.py:797Hands the run's one telemetry event to the telemetry thread. The event holds counts, names, hostnames, URLs without query strings, and scrubbed errors and result, never the task text, typed text, code or secrets.
Agent._shutdownorchestrationbrowser_use/agent/service.py:663Closes the REPL worker, then stops the browser even if that close failed. A cloud browser's downloads are copied into the workspace as it stops.
_dispatchorchestrationbrowser_use/cli.py:1065Routes one CLI invocation. It answers help, version and the subcommands (login, logout, install, init, skill, feedback, doctor, --mcp, --cli-mcp) and sends piped Python to _run_browser_harness.
_run_browser_harnessorchestrationbrowser_use/cli.py:795Patches browser-harness for browser-use: per-name daemon files, its update check off, the client identity, a cloud-browser guard, and the REPL's page, screenshot and plain-HTTP helpers. Then it runs browser-harness's own CLI on the piped code.
provider_preflightservicesbrowser_use/llm/__init__.py:439Makes one free GET for the model on OpenAI's, Anthropic's or Google's official endpoint, so a rejected key or unknown model fails before a cloud browser is created. It returns the error line, or None when the model exists or this cannot be told.
resolve_modelservicesbrowser_use/llm/__init__.py:533Turns the llm argument into a Pydantic AI model plus extra settings and checks its API key, raising before any browser starts. A missing-key error is rewritten to name the environment variable to set.
_resolve_modelservicesbrowser_use/llm/__init__.py:547Does the conversion for resolve_model. A Chat* wrapper gives its Pydantic AI model and settings, a Pydantic AI model passes through, and a model string is inferred, naming the extra to install when its provider package is missing.
build_agentservicesbrowser_use/agent/loop.py:1097Builds the Pydantic AI agent, with model settings chosen by API kind (Responses, Chat Completions or another provider) and the BrowserLoop, compaction and recording capabilities. It registers python as a sequential tool next to any custom tools.
pythonservicesbrowser_use/agent/loop.py:168The tool the model calls with code. It runs one cell in the REPL, bounded by the cell deadline and never past the start of the delivery turn, and returns the output and any screenshots.
loop.runservicesbrowser_use/agent/loop.py:1276Runs one task through the Pydantic AI agent under the run's timeout and step budget, including the delivery-only turn and partial results. It never raises for agent or provider failures; it returns an AgentHistoryList with a status.
usage_and_costservicesbrowser_use/agent/loop.py:1210Totals the tokens in a list of messages and prices them: the gateway's own charge for a gateway model, otherwise genai-prices. The cost is None when any request has no known price.
judge_runservicesbrowser_use/agent/judge.py:133Sends one low-effort request with the run's model, carrying the redacted task, the trace and the last screenshots. It returns the judgement (None if it failed) and its messages for costing.
telemetryservicesbrowser_use/telemetry/service.py:628Returns the process-wide product telemetry client, creating it on first use.
Repl.callservicesbrowser_use/repl/session.py:460Runs one cell under the REPL's lock, so cells never overlap. When the browser connection is lost it reattaches the browser, and if that started a new daemon it restarts the worker and tells the model its variables are gone.
Repl._callservicesbrowser_use/repl/session.py:524Starts a worker if none is usable, sends the cell as a JSON line and waits for its answer, answering the worker's search, downloads and feedback requests meanwhile. On a timeout or worker exit it kills the worker and returns an error saying actions may already have happened.
Repl.startservicesbrowser_use/repl/session.py:348Starts the worker in a fresh context, so the run's objects are not kept alive by the worker's socket reader, and adds the startup time to the REPL's counter.
Repl._startservicesbrowser_use/repl/session.py:357Kills any previous worker, listens on 127.0.0.1, and spawns python -P -m browser_use.repl.worker in its own process group with the allowlisted environment. It accepts the worker only when it connects back with the 32-byte token.
worker_envservicesbrowser_use/repl/session.py:78Builds the worker's environment from an allowlist of the parent's. It drops any name that looks like a credential (KEY, TOKEN, SECRET, PASSW, CREDENTIAL, AUTH).
_installservicesbrowser_use/repl/worker.py:494Loads browser-harness's helpers into the cell namespace and wraps them: a timed and dialog-aware CDP sender, screenshot capture, action highlights, file upload and, in ultrafast mode, the bu accessibility helpers. At 445 lines it is the longest function in the repository.
Browser.startservicesbrowser_use/browser/browser.py:695Attaches a browser-harness daemon under the Browser's lock and returns the environment the REPL worker needs. It is idempotent while started, and a dead daemon or a gone kept-alive cloud browser is started again.
Browser._start_lockedservicesbrowser_use/browser/browser.py:701The body of Browser.start under the lock. It starts the browser when there is no environment yet, and adds the domain rules and tabs file the worker enforces.
Browser._startservicesbrowser_use/browser/browser.py:873Starts the configured browser kind: it attaches to the user's Chrome, launches a local Chromium, connects to a cdp_url, or creates a cloud browser, then brings up the browser-harness daemon on it.
Browser._start_cloudservicesbrowser_use/browser/browser.py:969Creates a cloud browser with the proxy, timeout, screen size and optional profile, running the create on a thread pool under the 120 s create deadline. It returns the websocket URL behind the browser's cdpUrl.
Browser._createservicesbrowser_use/browser/browser.py:983POSTs /browsers to Browser Use Cloud and records the new browser's id, live URL and CDP URL, so a start cancelled mid-request still knows which browser to stop.
_cloudservicesbrowser_use/browser/browser.py:215Sends one JSON request to the cloud browser API at https://api.browser-use.com/api/v4 with the X-Browser-Use-API-Key header, through urlopen_keyed. It turns an HTTP error into the server's own message.
urlopen_keyedservicesbrowser_use/utils.py:96Opens a request that carries an API key with an opener that never follows a redirect. A redirect would otherwise copy the key to another origin.

6. Boundary-crossing flows

Most of browser-use runs in one Python process and one event loop, where the call graph in section 5 is a fair picture. Six flows leave that process or that loop, and these are the ones a reader cannot follow by reading call sites: the work continues in another process (the REPL worker, the browser-harness daemon, a watchdog, a detached telemetry sender), on another thread (the browser-use-cloud pool, the telemetry thread), or on another host (Browser Use Cloud, the model provider, PostHog). The table names each flow, the boundary it crosses, how the bytes travel and what bounds the wait. Three of them are drawn as sequence diagrams below because their ordering matters and is spread over several files; the other three are short enough to describe in a paragraph.

FlowBoundary crossedTransportDeadline
REPL cellParent process to REPL worker process, then worker to the browser-harness daemon process, then daemon to ChromeNewline-delimited JSON over a TCP socket on 127.0.0.1 (ephemeral port, 32-byte token); browser-harness IPC to the daemon; CDP over a websocket to Chrome120 s per cell (Session.cell_timeout_s), never past the start of the delivery turn; on expiry the worker's process tree is killed and the next call restarts it
Worker callbackWorker process back to the parent mid-cell, then parent to Browser Use Cloud for searchThe same control socket: the worker writes {"type": "search" | "downloads" | "feedback"} and blocks for one answer line; the parent calls the API over HTTPSSearch 25 s total (SEARCH_TIMEOUT_S); downloads 60 s; all inside the cell's own deadline
Cloud browser lifecycleEvent loop to the browser-use-cloud thread pool, this machine to Browser Use Cloud, and the parent to a separate watchdog processHTTPS to https://api.browser-use.com/api/v4 with the X-Browser-Use-API-Key header through urlopen_keyed; CDP over WSS from the daemonCreate 120 s (CREATE_TIMEOUT_S), each API call 60 s socket timeout, downloads 300 s before and after a stop (10 s when cancelled)
Model requestThis machine to the Browser Use LLM gateway or the provider's APIHTTPS through the Pydantic AI provider clients (OpenAI, Anthropic, Google, OpenAI-compatible); OpenAI Responses requests are streamed300 s per request (MODEL_TIMEOUT_S); a streamed request gets 300 s to its first event and up to 930 s in all (STREAM_TIMEOUT_S); both capped by the time left before the delivery turn; one transient retry per run
Telemetry deliveryCaller's thread to the telemetry thread, this machine to PostHog, and at exit this process to a detached sender processA queue.Queue between threads; gzip JSON POST to https://eu.i.posthog.com/batch/; files in the config dir's telemetry/outbox between processes3 s per send (SEND_TIMEOUT_S) with one retry after 1 s; the exit sender uses 10 s; outbox files expire after 7 days
MCP tool callMCP host process (a coding agent) to the browser-use --cli-mcp server process, then server to the browser-harness daemonJSON-RPC over the server's stdin and stdout (MCP stdio transport); the code runs with exec in a worker thread of the server itself, no separate REPL process; helpers reach the daemon over IPCNone in the server: the client's own timeout cancels the call and releases the lock, while the thread it started runs on

REPL cell, with a worker callback

The REPL cell is the flow every agent step takes. The python tool in browser_use/agent/loop.py calls Repl.call, which serialises cells with a lock and hands them to Repl._call. When no live worker exists (the first cell, a killed worker, or a run on a new event loop), Repl._start opens a listening socket on 127.0.0.1 with an ephemeral port, builds the worker's environment with worker_env, and spawns python -P -m browser_use.repl.worker in its own process group (a job object on Windows). The worker's main connects back, sends the 32-byte token from BU_REPL_TOKEN (the parent compares it in constant time and closes any other client), reads one init line carrying the secrets and which callbacks exist, and answers {"type": "ready"}. The start is bounded at 60 s. The port, token and parent pid travel in environment variables the worker pops on start.

A cell is one JSON line, {"op": "exec", "code": ..., "n": ...}. Inside the worker the code calls browser-harness helpers, which reach the daemon over IPC; the daemon owns the CDP websocket to Chrome. When the code calls search, downloads or report_issue, _ask_parent writes a typed message on the same socket and blocks on the reply: the parent answers it in Repl._search (or the downloads and feedback handlers) while it is still waiting for the cell's result. That is how a cell can use the Browser Use API without the key ever entering the worker. The three callbacks end in different places: search is a POST to Browser Use's /api/v4/search; downloads lists files through the cloud API for a cloud browser and reads the local downloads directory for a browser the Browser launched; report_issue is scrubbed and queued for the telemetry thread, which sends it to PostHog. The reply that ends the wait carries the cell number, so a stale answer is never handed to the wrong call; the parent redacts secrets from it before the model sees it and appends what the domain guard blocked. If the deadline passes or the socket closes, the parent kills the worker's whole process tree and returns a "REPL restarted" error that tells the model actions may already have happened.

So only search, and downloads on a cloud browser, call the Browser Use API (browser_use/search.py, Browser.list_downloads at browser_use/browser/browser.py:1210); report_issue is answered by RunReports in browser_use/telemetry/feedback.py, which queues it for PostHog.

process boundary parent | worker network HTTPS Browser Use API /api/v4/search Agent loop python tool Repl (parent) repl/session.py REPL worker repl/worker.py harness daemon browser-harness Chrome local or cloud start: first call, or after a kill the cell mid-cell callback result call('exec', code, <=120 s) spawn python -P -m worker connect 127.0.0.1:port + token init line: secrets, search {type: ready} {op: exec, code, n} helper call (IPC) CDP over websocket {type: search, args} POST, key header, 25 s hits {value} or {error} {type: result, n, output} redacted result + guard notes only when no live worker, own process group mid-cell callback: the key stays in the parent deadline passes: process group killed (job object on Windows); next call starts a new worker, files kept, variables lost
Figure 6.1 · REPL cell across the process boundaryOne cell from the agent loop to Chrome and back, including a mid-cell search answered by the parent. The dashed red line is the process boundary between the agent's process and the worker it spawns; the token handshake and the callback are drawn in the accent colour because they are the two exchanges the call graph cannot see. Sources: browser_use/repl/session.py, browser_use/repl/worker.py, browser_use/search.py.

Cloud browser lifecycle

A cloud browser (the default Browser()) crosses three boundaries. Browser._start_cloud submits Browser._create to a module-level thread pool named browser-use-cloud, so the POST records the browser id from its own thread: a start that is cancelled mid-request still knows which browser to stop. Browser._create calls _cloud, which sends the request through urlopen_keyed and so never follows a redirect that would carry the key elsewhere. The event loop waits at most 120 s; past that the start fails, and Browser._stop_late is registered to stop the browser the moment its create lands. The returned cdpUrl is resolved to a websocket URL, a browser-harness daemon is started with BU_CDP_WS and BU_BROWSER_ID so that its own shutdown stops the cloud browser, and start_watchdog spawns a separate process that blocks on its stdin pipe. The browser id goes in the watchdog's environment, never its argv, because the id alone drives the browser.

At the end of the run (or a call to Browser.stop), the downloads are listed and copied (300 s in all), then Browser._stop_now kills the watchdog first so it cannot race the normal stop, shuts the daemon down, and sends PATCH /browsers/{id} with {"action": "stop"}, up to three tries. If the owning process dies without a stop (SIGKILL, out of memory), the watchdog's stdin closes, and it stops the cloud browser and kills the daemon itself.

network boundary HTTPS / WSS Browser browser.py pool thread browser-use-cloud harness daemon one per Browser watchdog separate process Browser Use Cloud api/v4/browsers cloud browser Chrome over CDP stop: end of Agent.run, or Browser.stop submit _create(body) POST /browsers, API key, no redirects id, liveUrl, cdpUrl future done (<=120 s) GET cdpUrl: websocket URL start: BU_CDP_WS, BU_BROWSER_ID CDP websocket (helpers) spawn, stdin pipe, id in env GET /browsers/{id}/downloads kill (normal stop) shutdown daemon PATCH {action: stop}, 3 tries stopped: billing ends past 120 s: start fails, stopped when it lands if this process dies: stdin closes, the watchdog stops the browser itself
Figure 6.2 · Cloud browser lifecycleCreate, attach, watch and stop, with the thread hop to the browser-use-cloud pool, the network boundary to Browser Use Cloud and the watchdog process. The graph records no edge from Browser._start_cloud to Browser._create because the call goes through the pool. Source: browser_use/browser/browser.py, browser_use/browser/local.py.

Telemetry delivery

Telemetry is designed so the agent path never waits on the network or the disk. ProductTelemetry.capture_run is a dict update and a put on an in-memory queue; one daemon thread builds the event, gzips it and posts it in ProductTelemetry._send with a 3 s timeout and one retry. When the thread starts it first resends earlier processes' outbox files (ProductTelemetry._send_outbox) and any run that left a crash marker in telemetry/inflight. A send that fails is written to telemetry/outbox/<run_id>.gz by ProductTelemetry._to_outbox for a later process. At interpreter exit, ProductTelemetry._at_exit writes what is still queued to the outbox and spawns a detached python -I sender with those files, so a one-shot CLI call neither waits for the network nor loses its event. A file is claimed by renaming it to .<pid>.sending before it is sent, which is what lets several processes share one outbox (section 7 tables that file's states).

network boundary HTTPS process boundary Calling process Agent.run, CLI, MCP telemetry thread daemon thread config dir telemetry/ exit sender python -I, detached PostHog EU eu.i.posthog.com each run process exit run_started: queue mark inflight/<run_id>.json, every 30 s resend outbox and crashed runs capture_run: queue.put POST /batch/ gzip, 3 s, 1 retry 2xx: marker deleted failed: outbox/<run_id>.gz atexit: spawn with queued + outbox files POST each file, 10 s sent: delete; failed: back to outbox never awaited on the agent path: a dict update and a queue.put
Figure 6.3 · Telemetry deliveryQueue to a background thread, POST to PostHog EU, outbox on failure, and a detached sender at exit. Two boundaries: the network to PostHog and the process hop to the exit sender, which outlives the process that queued the event. Source: browser_use/telemetry/service.py.

Model request and MCP tool call

The model request is not drawn: it is one HTTPS round trip through a Pydantic AI provider client, and its interest is in the deadlines, not the ordering. BrowserLoop.prepare_model_request calls _deadlines on every attempt, which sets request_timeout (and first_event_timeout for a streamed OpenAI Responses request) to the smaller of the constant and the time left before the delivery turn. A request that times out becomes a new request step through BrowserLoop.on_model_request_error; a transient provider error is retried once per run after the provider's Retry-After (at most 60 s), and only where the provider's SDK has not already retried it. Section 13 tables every deadline and retry.

The MCP tool call is not drawn either, because its one boundary is the stdio pipe. handle_call_tool in browser_use/mcp/cli_mcp.py receives a tools/call request and dispatches it in call_tool; browser_exec runs the code with CLIMCPServer._execute through CLIMCPServer._locked, one call at a time in a thread of the server process. Unlike the Agent path there is no separate worker, no environment allowlist and no cell deadline: the caller is a coding agent the user already runs, and a call the client cancels leaves its thread running while later calls proceed.

Functions named in this section

Functions named in section 6 34 rows
FunctionWhereWhat it does
pythonbrowser_use/agent/loop.py:168The single tool the model calls to run code: it sends one cell to the REPL with a deadline that never reaches into the delivery turn, logs a progress line and returns the output and any screenshots.
Repl.callbrowser_use/repl/session.py:460Runs one cell under a lock, reattaches the browser-harness daemon when the cell lost it, applies the domain guard's after-cell sweep, and redacts secrets from the result.
Repl._callbrowser_use/repl/session.py:524Starts a worker if none is alive, writes the cell to the socket, answers the worker's mid-cell callbacks, and on a timeout or a dead worker kills it and returns a restart error.
Repl._startbrowser_use/repl/session.py:357Opens a 127.0.0.1 listener, spawns the worker in its own process group with an allowlisted environment, and accepts it only after the random token and the init handshake succeed within 60 s.
worker_envbrowser_use/repl/session.py:78Builds the worker's environment from an allowlist of the parent's variables, dropping every name that looks like a credential.
Repl._searchbrowser_use/repl/session.py:493Answers a worker's search request in the parent, running the web search in a thread with a 25 s total deadline and turning failures into an error message for the cell.
mainbrowser_use/repl/worker.py:1135The worker's entry point: connects back to the parent, proves itself with the token, installs the helpers and then runs each cell it receives, sending back one result line per cell.
_ask_parentbrowser_use/repl/worker.py:941Returns a function that sends a typed request to the parent over the control socket mid-cell and blocks for its one-line answer, refusing calls from any thread but the main one.
searchbrowser_use/repl/worker.py:966The web search helper a cell calls; it validates the arguments and asks the parent to run the search, so the API key never enters the worker.
downloadsbrowser_use/repl/worker.py:984The helper a cell calls to list the files the browser finished downloading, answered by the parent.
report_issuebrowser_use/repl/worker.py:995Lets the model report a problem with browser-use itself; the parent sends it, scrubbed of the task, secrets and typed text, at most three per run.
_watch_parentbrowser_use/repl/worker.py:1088A worker thread that waits for the parent to die and then kills the worker's own process group, so no cell keeps driving the browser after its owner is gone.
kill_workersbrowser_use/repl/session.py:254Kills every live REPL worker this process started and their child processes, from the atexit, SIGTERM and SIGHUP handlers, before browsers are stopped.
Browser._start_cloudbrowser_use/browser/browser.py:969Submits the cloud create to the thread pool, waits at most 120 s for it, and resolves the returned CDP URL to a websocket URL.
Browser._createbrowser_use/browser/browser.py:983Posts to /browsers from a pool thread and records the browser id, live URL and CDP URL on the Browser as soon as they arrive.
_cloudbrowser_use/browser/browser.py:215Sends one JSON request to the Browser Use Cloud v4 API with the API key header and turns an HTTP error into a message with a fix hint.
urlopen_keyedbrowser_use/utils.py:96Opens a request that carries an API key through the OS-trusting TLS context and refuses every redirect, so the key cannot be forwarded to another origin.
start_watchdogbrowser_use/browser/local.py:548Spawns a small watchdog process that waits on its stdin and, when the owning process dies, stops the cloud browser and kills the daemon (and a launched Chrome).
Browser._stop_nowbrowser_use/browser/browser.py:1030Kills the watchdog, closes the domain guard, shuts the daemon down and stops the cloud browser with up to three PATCH tries, returning False when it could not.
Browser._stop_latebrowser_use/browser/browser.py:1081A callback on a create that outlived its start: it stops that browser when the create finally lands, unless a later stop already did.
Browser.list_downloadsbrowser_use/browser/browser.py:1210Answers the worker's downloads: a cloud browser's finished files as the API lists them, page by page, or the local downloads directory for a Chrome the Browser launched.
Browser.stopbrowser_use/browser/browser.py:1087Stops the daemon this Browser started and the cloud browser or local Chrome it launched, copying a cloud browser's downloads first; it never touches a Chrome the user has open.
ProductTelemetry.capture_runbrowser_use/telemetry/service.py:265Queues a run's telemetry event for the background thread without touching the network or disk, dropping the oldest when 100 are pending.
ProductTelemetry._sendbrowser_use/telemetry/service.py:420Posts one event to PostHog with a 3 s timeout and one retry, and writes it to the outbox when both fail.
ProductTelemetry._to_outboxbrowser_use/telemetry/service.py:439Writes an unsent event to the outbox directory, deleting the oldest files to keep it within 20 files and 512 KiB.
ProductTelemetry._send_outboxbrowser_use/telemetry/service.py:482Sends earlier processes' outbox files oldest first, claiming each by renaming it, and stops at the first failure so the rest wait for the next process.
ProductTelemetry._at_exitbrowser_use/telemetry/service.py:572At interpreter exit, writes still-queued events to the outbox and spawns a detached sender process with them and the backlog, so exit does not wait on the network.
_deadlinesbrowser_use/agent/loop.py:691Sets a model request's timeout, and a streamed request's first-event timeout, to the smaller of the constant and the time left before the delivery turn.
BrowserLoop.prepare_model_requestbrowser_use/agent/loop.py:445A Pydantic AI hook that recomputes the request's deadlines on every attempt, so a retry after a wait never runs past the delivery turn.
BrowserLoop.on_model_request_errorbrowser_use/agent/loop.py:453Turns a model timeout into a new request step and retries one transient provider error per run after the provider's Retry-After, capped at 60 s.
handle_call_toolbrowser_use/mcp/cli_mcp.py:506The MCP server's tools/call handler: it runs the call, records its error classes and sends one telemetry event per call.
call_toolbrowser_use/mcp/cli_mcp.py:520Dispatches an MCP tool by name to code execution, a screenshot, the login flow or feedback, and returns removal notices for 0.x tool names.
CLIMCPServer._lockedbrowser_use/mcp/cli_mcp.py:604Runs a blocking function in a thread one call at a time; a call the client cancels releases the lock while its thread runs on.
CLIMCPServer._executebrowser_use/mcp/cli_mcp.py:746Runs the tool call's code with exec in the server's persistent namespace, attaching the daemon first, and returns the captured output and whether it failed.

7. State machines

Four pieces of state in browser-use move through named states on named events, and each decides something a reader needs to know: whether a run still returns an answer, whether a cell can be retried, whether a cloud browser is still billing, and whether a telemetry event will be sent twice or lost. They are the Run budget, the REPL worker, the Cloud browser and the Telemetry event file. None of them is a declared state-machine object: each is a handful of fields (Session.finalizing, Repl.proc, Browser.id with Browser._creating and Browser.stopped, a file's name and directory) whose combinations are the states. The transition tables below are read from the source; the two machines whose transitions are spread across several files and hooks, the run budget and the cloud browser, are also drawn.

Run budget

The run budget lives in the per-run Session in browser_use/agent/loop.py. A run is working until something forces the delivery-only turn: a request in which the model may only call finish or finish_from_repl (the tool choice is restricted and any python call is answered "Not run"). BrowserLoop.before_model_request moves the run there when the step count reaches max_steps (default 100 on Agent.run), when the elapsed time passes Session.delivery_at (the timeout minus max(10% of the timeout, min(30 s, half the timeout))), or when a cell reported the browser gone. A plain-text reply to a structured result type also starts it, once, as the delivery repair turn. What forced it is recorded in budget_hit (max_steps, timeout or browser_gone). The final status is set by run when the Pydantic AI run returns or raises: "completed", "max_steps", "timeout" or "error". A run that ends in any status other than completed still returns the last checkpoint written with partial=True.

run() Working finalizing = False Delivery-only turn finalizing = True completed max_steps timeout error step >= max_steps or delivery_at passed or browser_gone or structured text reply finish, finish_from_repl or accepted text deliver any other exception (a provider error after its retry) hard timeout_s expires check_delivery repair (once)
Figure 7.1 · Run budgetThe two live states are fields of Session; the four end states are the values of the result's status field (AgentHistoryList). The accent arrows are the path a run normally takes when it runs out of steps or time: it is told to deliver, and still ends completed. The two unlabelled arrows from the delivery-only turn are the request limit (to max_steps) and the hard timeout (to timeout). Source: browser_use/agent/loop.py:123-165, 419-443, 1276-1336.
FromEventTo
WorkingBefore a model request: the step count reaches max_steps, or the elapsed time passes Session.delivery_at, or a cell set budget_hit = 'browser_gone' after the daemon could not be reattachedDelivery-only turn (the model is sent the "deliver now" message and only the delivery tools are allowed)
WorkingA plain-text reply for a structured result, or a tool call written as text (on_text)Delivery-only turn (the delivery repair turn, once per run)
Workingcheck_delivery refuses a placeholder answer or links to files that do not existWorking (one repair retry per run; the next identical delivery is accepted)
Working or delivery-onlyfinish or finish_from_repl validates against the result schema, or an accepted text replycompleted
Delivery-only turnThe request limit of max_steps + 1 is exceeded without a delivery (Pydantic AI's UsageLimitExceeded)max_steps
Any live stateThe hard run timeout (timeout, default 1700 s) expirestimeout
Any live stateAny other exception (a provider error after its retry, a tool error that escapes)error

REPL worker

The REPL worker's state is Repl.proc in browser_use/repl/session.py and whether that process is still running. It is not drawn: it is a short cycle, and section 6 shows the exchange that drives it. What the table makes plain is that a kill is never followed by a retry of the cell. The next call starts a new worker, and the model is told that Python variables are lost, files and browser state survive, and actions may already have happened.

FromEventTo
Not started (proc is None)Repl._start: the spawned worker connects to 127.0.0.1, its token matches, it reads the init line and answers ready within 60 sReady
ReadyRepl._call writes a cell (exec, or eval for finish_from_repl)Running a cell
Running a cellThe worker sends the result line carrying this cell's numberReady
Running a cellThe cell deadline passes, the socket closes (the worker exited), or the run is cancelledKilled (Repl.close kills the process group or job object and sets proc to None)
Killed, or a worker started on a finished event loopThe next Repl._callRestarted through Repl._start: files kept, variables lost, the cell numbering continues

Cloud browser

The cloud browser's state is three fields on Browser in browser_use/browser/browser.py: id, _creating (the pool future of a create still in flight) and stopped. It matters because every state but stopped is billed. Two transitions are designed around that: a create that lands after its start already failed is stopped by a callback rather than leaked, and a stop that fails three times leaves the browser owned (registered for the exit cleanup and the next Browser.stop) instead of forgetting it.

No browser id = None Creating _creating set Running id set, stopped False Stopped stopped True Late create start already failed Gone ended on the cloud start() POST returns stop(), daemon, watchdog past 120 s _stop_late when it lands cloud_timeout or dashboard next keep_alive start: replaced PATCH fails 3 times: stays owned
Figure 7.2 · Cloud browserStates of one cloud browser as the Browser object tracks it. The red states are the two the design has to recover from: a create that outlived its start (billing with no run to use it) and a browser that ended on the cloud while the Browser still holds its id. Each has a designed way out. Source: browser_use/browser/browser.py:695-731, 873-990, 1030-1094.
FromEventTo
No browserBrowser.start: Browser._start_cloud submits the POST to the browser-use-cloud poolCreating
CreatingBrowser._create receives the id, live URL and CDP URL within 120 sRunning
Creating120 s pass (CREATE_TIMEOUT_S) or the start is cancelled; start raisesLate create (still owned through _creating)
Late createThe POST finally returns; Browser._stop_late runsStopped
RunningBrowser.stop at the end of Agent.run (unless keep_alive), the daemon's own shutdown, or the watchdog when the process diedStopped (billing ends)
RunningPATCH /browsers/{id} fails three times in Browser._stop_nowRunning (stays registered for retry at stop or exit)
RunningThe browser ends on the cloud between runs (cloud_timeout, a stop from the dashboard)Gone
GoneThe next Browser.start of a keep_alive Browser: Browser._reattach fails and Browser._start_locked stops the old oneCreating (a new browser replaces it; mid-run the same failure ends cells with browser_gone)

Telemetry event file

An unsent telemetry event is a file in the config dir's telemetry/outbox, and its state is its name. The claim by rename is what lets the telemetry thread of one process, the exit sender of another and a later process share one outbox without sending an event twice. Not drawn: four transitions read as clearly in the table.

FromEventTo
(none)A send fails, or the process exits with the event still queued (ProductTelemetry._to_outbox)Queued: outbox/<run_id>.gz
QueuedA sender renames it before posting (ProductTelemetry._claim, or the exit sender's own rename)Claimed: <run_id>.<pid>.sending
ClaimedPostHog answers 2xxDeleted
ClaimedThe post fails, or the claiming process died mid-send (found by ProductTelemetry._outbox)Queued again, for the next process
QueuedOlder than 7 days, or the oldest file when the outbox would pass 20 files or 512 KiBDeleted unsent

Functions named in this section

Functions named in section 7 24 rows
FunctionWhereWhat it does
Agent.runbrowser_use/agent/service.py:443The public entry point: checks the key and model, starts the browser and the REPL, runs the task under max_steps and timeout, and returns the history with its status.
BrowserLoop.before_model_requestbrowser_use/agent/loop.py:423Before each model request, prunes old screenshots and, when the step or time budget is spent or the browser is gone, switches the run to its delivery-only turn and restricts the tool choice.
Session.delivery_atbrowser_use/agent/loop.py:150Returns the second of the run at which the delivery-only turn starts: 90% of the timeout, or earlier on a short budget so delivery still has up to 30 s.
pythonbrowser_use/agent/loop.py:168The tool that runs one cell; it records browser_gone when the cell could not reattach the browser, so the next request is the delivery turn.
finishbrowser_use/agent/loop.py:351The delivery tool that submits the final result inline, after the split-delivery and placeholder checks, with the model's success verdict.
finish_from_replbrowser_use/agent/loop.py:329The delivery tool that evaluates an expression in the REPL and delivers its value, validated against the result schema, without the model retyping it.
on_textbrowser_use/agent/loop.py:357Handles a plain-text reply: the answer for a string result, otherwise one delivery repair turn and then the text is validated as the result.
check_deliverybrowser_use/agent/loop.py:245Refuses a delivery once per run when it is a placeholder or links to files that are not in the workspace, asking the model to deliver the real result.
runbrowser_use/agent/loop.py:1276Runs one task under the hard timeout and turns how it ended into a status, a redacted result, partial results, usage and cost, never raising for agent or provider failures.
checkpointbrowser_use/repl/worker.py:742The REPL helper that saves a value to a file in the workspace; with partial=True it becomes the partial result a run that does not complete still returns.
Repl._startbrowser_use/repl/session.py:357Spawns the worker and accepts it only after the token and init handshake succeed within 60 s, killing a half-started worker on any failure.
Repl._callbrowser_use/repl/session.py:524Starts a worker when none is alive, sends one cell and waits for its numbered result, killing the worker on a timeout or a closed socket.
Repl.closebrowser_use/repl/session.py:443Closes the parent's end of the socket and kills the worker's whole process group or job object, then waits up to 5 s to reap it.
Browser.startbrowser_use/browser/browser.py:695Attaches a browser-harness daemon under a lock, starting the browser if needed, and returns the environment the REPL worker needs.
Browser._start_lockedbrowser_use/browser/browser.py:701The body of start: starts a browser, relaunches a dead local Chrome, reattaches a lost daemon, or replaces a cloud browser that ended between runs.
Browser._start_cloudbrowser_use/browser/browser.py:969Submits the cloud create to the thread pool and waits at most 120 s for it.
Browser._createbrowser_use/browser/browser.py:983Posts to /browsers and records the new browser's id and URLs on the Browser from the pool thread.
Browser._reattachbrowser_use/browser/browser.py:782Starts the browser-harness daemon again on the same browser after a cell lost it, raising when the browser itself is gone.
Browser._stop_nowbrowser_use/browser/browser.py:1030Stops the watchdog, guard and daemon, then the cloud browser with up to three PATCH tries; returns False and keeps ownership when it cannot.
Browser._stop_latebrowser_use/browser/browser.py:1081Stops a browser whose create landed after its start had already failed, unless a later stop already did.
Browser.stopbrowser_use/browser/browser.py:1087Stops the daemon and the browser this Browser started, copying cloud downloads first, and never touches a Chrome the user has open.
ProductTelemetry._to_outboxbrowser_use/telemetry/service.py:439Writes an unsent event to the outbox, deleting the oldest files to stay within 20 files and 512 KiB.
ProductTelemetry._claimbrowser_use/telemetry/service.py:500Claims an outbox file for this process by renaming it with the pid, or refuses once the process is exiting.
ProductTelemetry._outboxbrowser_use/telemetry/service.py:458Lists the outbox oldest first, returning a dead sender's claims to the box and deleting files older than 7 days.

8. Security model

browser-use is a library that runs model-written Python on the user's machine and points it at the open web, so its security model is mostly about what that code and the pages it reads can reach. The repository states the model in writing (MIGRATING.md, "Trust model for secrets" and "Domain restrictions") and the code follows it: the REPL worker is a separate process with a reduced environment, the Browser Use API key stays in the parent, secrets are typed by name and redacted from a listed set of channels, and domain rules guard navigation. It is equally explicit about what it does not do: the worker is not a sandbox. It runs as the user, and model-written Python can read local files, the parent's environment through the operating system, and every secret value it was given. The documentation's own advice is to run untrusted tasks in a container or VM. This section describes the trust boundaries, how identity and permission work across them, and what is public on purpose.

Trust boundaries

Seven boundaries matter. Five are crossed on every Agent run; the coding-agent path through the CLI and MCP server, and other accounts on the same machine, are listed too because MIGRATING.md treats them as boundaries with their own rules.

BoundaryWhat crosses itHow it is guardedWhat is not guarded
User process ↔ REPL worker (model-written Python)Cells, results, the sensitive_data values in the init line, and the worker's callbacks for search, downloads and feedbackSeparate process in its own process group; the environment is an allowlist built by worker_env (ENV_ALLOW plus LC_, BU_, BH_ prefixes, minus ENV_DENY, minus any name matching KEY|TOKEN|SECRET|PASSW|CREDENTIAL|AUTH); the worker proves itself to the parent with a 32-byte random token compared in constant time on 127.0.0.1; it runs with -P so a module in the workspace cannot shadow the standard library; it gets its own browser-harness agent workspace, so a helper file a prompt-injected run planted in the global one is never loaded; CDP URLs are kept out of its environment and BU_CDP_WS points at a dead portThe code runs as the user: it can read the parent's environment (/proc/<pid>/environ, ps -E), the .env the parent loaded, browser-harness's stored key file and any other file the user can read, and it holds every secret value in memory
This machine ↔ Browser Use CloudThe Browser Use API key, browser create and stop requests, model requests to the gateway, web searches, download listingsHTTPS through the OS certificate verifier (new_tls_context); every keyed request goes through urlopen_keyed, which refuses redirects so the key cannot be forwarded to another origin; the key travels only in the X-Browser-Use-API-Key header; searches run in the parent, never the worker; the browser id (which grants control of the browser) is logged only as an 8-character prefix and the live URL never goes to the logger (it is printed to stderr for the user unless live_view=False), and the watchdog receives the id in its environment, not its argvKey scopes and lifetime are the server's to enforce; the repository only turns a 401 or 403 into a hint
Browser ↔ visited websitesPage text and screenshots that reach the model (the prompt-injection path), and whatever the agent types or uploadsallowed_domains, prohibited_domains and block_ip_addresses in four layers: the REPL helpers refuse a disallowed URL before navigating (check_url), a separate CDP connection with browser-wide Fetch.enable fails disallowed document requests (the Guard), every tab is swept back to about:blank after each cell (sweep), and the system prompt lists the domains; if the guard cannot start, Browser.start raises rather than run unguarded; domain-scoped secrets are typed only into a frame whose URL, as the browser reports it, matchesSubresources (fetch, XHR, images, scripts, iframes, websockets) an allowed page loads from other hosts; the REPL's own Python networking except http_get; speculative prefetches; model code that deliberately goes around browser-use. MIGRATING.md calls the rules "a guard for an aligned model, not a sandbox"
This machine ↔ LLM providerThe task, page text, screenshots, the model's code and the conversation; the provider's API keyHTTPS through the provider's SDK client; secrets are replaced with <secret:name> in the task before the model sees it, and the model types them by name with type_secret, so values do not normally enter the transcriptScreenshots are not redacted, so a typed value visible in a field reaches the provider; everything else the run reads is sent by design
This machine ↔ PostHogAnonymous usage telemetry: model, steps, cost, timing, helper names, URLs visited (without ports, query strings or path tokens), error classes and the final result cut to 500 characters with emails, keys, tokens and 6+ digit runs replacedOn by default, off with ANONYMIZED_TELEMETRY=false; never the task text, typed text, code or secrets; the worker's environment sets BH_TELEMETRY=0 so a browser-harness CLI call from a cell cannot send its piped code and outputThe scrubbed URLs and result still leave the machine unless the user turns telemetry off
Coding agent ↔ CLI and MCP serverPython piped to browser-use or sent in browser_execThe caller is a program the user already runs and trusts; the MCP server does not return live view or CDP URLs unless BH_OPEN_LIVE_URL=1No worker process, no environment allowlist and no secret redaction on this path: the code runs with exec in the server process as the user, and the CLI and --cli-mcp load the global browser-harness agent workspace
Other local accounts ↔ a local browserCDP on the 127.0.0.1 debugging port of Browser('chromium') and Browser('chrome', profile=...)Nothing in browser-use; documented in MIGRATING.md with the advice to use a container, a VM or a cloud browser on a shared machineAny local account can attach to that port, read cookies and drive the browser for as long as it runs

Credentials and secrets

Three kinds of secret pass through a run. The table says where each lives, who can read it, and how it is kept out of the places it should not reach. The redaction covers a value's plain form and its JSON-, repr- and HTML-escaped, lower- and upper-case, reversed, base64 (also inside a longer base64 string), hex and URL-encoded forms, built by secret_forms and applied by redact; a value under 4 characters is redacted only where it stands alone.

SecretWhere it livesWho can read itHow it is kept out or redacted
Browser Use API keyBROWSER_USE_API_KEY, else the key browser-use login stored in browser-harness's auth store (auth.json); the environment variable winsThe parent process; any process of the same user that reads the parent's environment or the auth file, the REPL worker includedDropped from the worker's environment by name; sent only to Browser Use hosts in a header, never through a redirect; the worker's search and downloads are answered by the parent; error messages never print a malformed key (clean_api_key); telemetry replaces key-shaped strings
Provider API keysThe provider's environment variable (OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, GEMINI_API_KEY, AZURE_OPENAI_API_KEY) or an api_key argument held by the model object in the parentThe parent and the provider SDK; same-user processes through the parent's environmentDropped from the worker's environment by name; not part of the sensitive_data redaction, so they are only kept out of cell output by never being in the worker; telemetry replaces key-shaped strings
sensitive_data valuesThe Agent's argument in the parent; sent to the worker in its init line and held in the worker's memoryThe parent and the worker, so model-written Python can read them; the model is told only their namesTyped with type_secret, which for a domain-scoped secret checks the receiving frame's URL from the browser's own records (never page JavaScript) and refuses on any other site; replaced with <secret:name> in cell output and output files, checkpoints and the partial result, tool results, the task, the final result and errors, result.messages, and telemetry. Not redacted: screenshots, files the model's code writes itself, or a transform redaction does not know (rot13, a split value)

Authentication

The only identity in the system is the Browser Use API key, which identifies a Browser Use Cloud account for cloud browsers, the default bu-4.0 model on the gateway, web search and feedback. browser_use_api_key reads BROWSER_USE_API_KEY first and falls back to the key browser-use login stored in browser-harness's auth store. With neither, and only in an interactive desktop session (a terminal on stdin, not CI, not a notebook, BROWSER_USE_AUTO_LOGIN not false, a display on Linux, as _can_open_login decides), it opens a login once per process through _login_for_key; otherwise it raises MissingAPIKeyError before any browser starts or anything is billed. _run_login_command offers three ways to obtain the key: a browser sign-in with an OAuth loopback callback (which harden_login_callback patches to ignore a request whose OAuth state parameter does not match, instead of aborting the pending login), --device-code, and --api-key-stdin. browser-use logout hands over to browser-harness's own logout (or deletes a corrupt key store outright).

Token lifetime is not stated in the repository. The key is a long-lived API key whose expiry and revocation are set by Browser Use Cloud; rotation from this side is logging in again or replacing the environment variable. Provider keys are each provider's own and are passed through untouched. The one authentication browser-use performs itself is local: the REPL worker must present the random token the parent generated for it before the parent accepts its connection, and the parent closes any other client that connects to the port.

Authorisation

The library has no authorisation layer of its own. It has no users or roles: whoever can run the code acts with the user's full permissions, and the code it runs is trusted with them. What a key may do is decided by the server. cloud_error_hint and the gateway's error handling turn a 401, a 403 insufficient_scope or "missing required scope" into the instruction to log in again for a key with v4 access, and note when BROWSER_USE_API_KEY overrides the stored key.

Two controls limit what the agent does rather than who it is. allowed_domains (with prohibited_domains and block_ip_addresses) decides where the browser may navigate, matched by DomainRules.blocked; when a rule is not enforced (a subresource, a raw socket in a cell, an iframe of another site, the user's own attached Chrome where layer 2 is off), the request simply goes through, which is why the documentation calls the rules a guard and not a sandbox. Domain-scoped sensitive_data decides where each secret may be typed, matched by domain_matches; when the receiving frame cannot be established, a scoped secret is not typed (it fails closed). The Python a cell runs, and the files it may read or upload, are not restricted at all: the 0.x file allowlist (available_file_paths) was removed and the agent can upload any file the user can read.

Deliberately public

The PostHog project key POSTHOG_PROJECT_API_KEY at browser_use/telemetry/service.py:34 is committed on purpose: it is the project key every installed copy sends its events with, so it cannot be kept private. It is the only key in the source. Everything else that would grant access is treated as secret even where it is not a credential in the usual sense: the cloud browser's id is logged only as an 8-character prefix, the live view URL is shown to the user on stderr but never logged, and a local browser's debugging port is documented as open to every local account rather than hidden. TLS verification is never turned off; the evidence's one risk-pattern line outside the tests, bin/setup.sh:31 piping the astral.sh uv installer to sh, is a contributor setup script that is not shipped in the wheel, and section 12 gives each flagged line its verdict.

Functions named in this section

Functions named in section 8 22 rows
FunctionWhereWhat it does
searchbrowser_use/repl/worker.py:966The web search helper in a cell; it asks the parent to make the request, so the Browser Use key never enters the worker.
downloadsbrowser_use/repl/worker.py:984The helper that lists the browser's finished downloads, answered by the parent, which holds the key a cloud browser's listing needs.
http_getbrowser_use/repl/worker.py:428The REPL's plain HTTP fetch from this machine; with domain rules set it checks the URL and every redirect it follows against them.
worker_envbrowser_use/repl/session.py:78Builds the REPL worker's environment from an allowlist of the parent's variables, minus the denied CDP and mode names and every credential-like name.
secret_formsbrowser_use/repl/session.py:158Lists every form of each secret value that redaction looks for (escaped, case-changed, reversed, base64, hex, URL-encoded), longest first.
redactbrowser_use/repl/session.py:186Replaces secret values and their encodings with <secret:name> in strings, lists and dicts; only the text passed to it is redacted.
domain_matchesbrowser_use/repl/session.py:116Decides whether a URL matches a 0.x domain pattern for a scoped secret, comparing scheme, host and port and allowing only *.domain style globs.
type_secretbrowser_use/repl/worker.py:853The helper the model uses to type a secret by name: it finds the receiving frame from the browser's records and types a scoped secret only when that frame's URL matches.
check_urlbrowser_use/repl/worker.py:544Refuses a disallowed URL in the REPL's navigation helpers and raw CDP navigation calls before anything navigates.
DomainRules.blockedbrowser_use/domains.py:214Returns why a URL is not allowed under the configured allowed, prohibited and IP-address rules, or None when it is.
sweepbrowser_use/domains.py:456After a cell, navigates every tab that still shows a disallowed page to about:blank and reports which ones it reset.
Browser.startbrowser_use/browser/browser.py:695Attaches the browser-harness daemon and, with domain rules set, starts the guard connection, raising rather than running unguarded when it cannot.
browser_use_api_keybrowser_use/auth.py:116Returns the Browser Use API key from the environment or the stored login, opening a login in an interactive session, else raising MissingAPIKeyError.
_can_open_loginbrowser_use/auth.py:32Decides whether an automatic login may open: a terminal on stdin, not a notebook or CI, auto-login not disabled, and a desktop session.
_login_for_keybrowser_use/auth.py:63Runs the login once per process when no key is stored and returns the key it stored, or raises MissingAPIKeyError.
clean_api_keybrowser_use/auth.py:84Strips surrounding whitespace from a key and rejects one with whitespace, control or non-ASCII characters inside, without printing the key.
harden_login_callbackbrowser_use/auth.py:199Patches browser-harness's OAuth loopback callback so a request with the wrong OAuth state parameter gets a 400 instead of aborting the login in progress.
cloud_error_hintbrowser_use/auth.py:150Turns a Browser Use Cloud 401 or missing-scope error into the fix, and notes when the environment key overrides the stored one.
_run_login_commandbrowser_use/cli.py:376Runs browser-use login by browser sign-in, device code or a key on stdin, after setting a corrupt key store aside, and records the outcome without credentials.
urlopen_keyedbrowser_use/utils.py:96Opens a request carrying an API key through the OS-trusting TLS context and raises on any redirect, so the key never reaches another origin.
new_tls_contextbrowser_use/utils.py:23Builds the TLS context for the package's own HTTPS: the operating system's verifier through truststore, plus SSL_CERT_FILE and SSL_CERT_DIR, or certifi as a fallback.
start_watchdogbrowser_use/browser/local.py:548Spawns the cleanup watchdog with the cloud browser id in its environment rather than its argv, since the id alone drives the browser.

Security rating

Security: 7/10, Good

Good. The trust model is written down and implemented: the worker gets an allowlisted environment that drops credential-like names and must present a 32-byte token compared in constant time, secrets are redacted from the listed channels and typed only into matching frames, keyed requests never follow redirects, TLS uses the OS verifier, and the supply chain is pinned and published through PyPI trusted publishing behind required reviewers, while all 17 hosts called from code are expected. The gaps are known and documented: model-written Python runs unsandboxed as the user and can read local files and the parent's environment, domain rules guard navigation but not subresources, telemetry is on by default, and bin/setup.sh pipes the astral.sh installer to sh. The technical assessment gives the reasoning per criterion.

9. Configuration and secrets

All configuration comes from environment variables and constructor arguments. The repository has no config file of its own: the only file it reads is the 0.x config.json that browser-use --mcp still honours for domain rules. There are 77 environment variables: the 61 the evidence lists, plus 16 that the scan missed (ANTHROPIC_API_KEY, GOOGLE_API_KEY, GEMINI_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY, OPENAI_API_VERSION, CI, BH_DEVICE_NAME, PYDANTIC_AI_NO_BANNER, BU_BROWSER_ID, BH_AGENT_WORKSPACE, BU_REPL_PARENT_PID, BU_REPL_PORT, BU_REPL_TOKEN, BH_TELEMETRY, BU_CDP_URL). Package code reads or sets 13 of those 16. The other three, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY and OPENAI_API_VERSION, appear only in hint strings at browser_use/__init__.py:44 and browser_use/legacy.py:495; Pydantic AI's Azure provider reads them for llm='azure:<deployment>'. Values are read when they are used, not cached at import. The Config class in browser_use/config.py reads the environment on every access, so a change made late to os.environ still takes effect.

The inventory runs in six groups, in this order. User settings: the BROWSER_USE_* variables and ANONYMIZED_TELEMETRY, including four 0.x names that 1.0 no longer honours and so warns or raises about. Parent-to-worker channel: the BU_* variables the library sets for the REPL worker and the browser-harness daemon it starts. Repl._start sets BU_STATE_DIR, BU_REPL_PORT, BU_REPL_TOKEN, BU_REPL_PARENT_PID, BU_MODE, BU_HIGHLIGHT_ACTIONS and BU_MODEL_CODE. Browser._start_locked sets BU_DOMAINS and BU_TABS_FILE. Browser._start sets BU_NAME, BU_OWN_BROWSER, BU_REMOTE_BROWSER, BU_CAPTCHA_SOLVER, BU_SHARED_DAEMON and BU_BROWSER_ID. Nobody is expected to set these by hand. browser-harness: the BH_* variables, which browser-harness reads and this package mostly sets or checks. Provider keys. Platform and OS. Then the names that occur only in tests or CI (BU_TEST_SLOW_START, DOTENV_PROBE, UV_TOOL_INSTALL_ARGS_FILE, CHROME, and GITHUB_WORKSPACE in a workflow) and only in skill docs (NEXT_PUBLIC_BROWSER_USE_API_KEY, BROWSER_USE_X402_PRIVATE_KEY). The package never reads those last seven.

Seven names belong to browser-harness: BH_AUTH_PATH, BH_CONFIG_DIR, BH_RUNTIME_DIR, BH_TMP_DIR, BH_REQUIRE_EXISTING_DAEMON, BU_CDP_WS and BU_CDP_URL. browser-harness consumes all seven, but only BH_AUTH_PATH goes untouched by package code. BH_CONFIG_DIR, BH_RUNTIME_DIR and BH_TMP_DIR are read at browser_use/auth.py:104 and browser_use/browser/browser.py:413 and :441. BH_REQUIRE_EXISTING_DAEMON and BU_CDP_WS are set for the worker at browser_use/repl/session.py:381. BU_CDP_URL is read at browser_use/harness_cloud.py:171. The table gives each one's own lines.

How the worker gets its environment matters for secrets. worker_env passes on only an allowlist: the ENV_ALLOW names plus anything starting LC_, BU_ or BH_. From that it removes the ENV_DENY names (BU_CDP_WS, BU_CDP_URL, BU_MODE, BU_HIGHLIGHT_ACTIONS) and every name matching KEY|TOKEN|SECRET|PASSW|CREDENTIAL|AUTH. As a result, no provider key, BROWSER_USE_API_KEY or BH_AUTH_PATH reaches model-written code through its environment.

Environment variables 77 rows
VariableGroupDefaultRead or set atWhen it is absent
BROWSER_USE_API_KEYUser setting (secret)unsetbrowser_use/auth.py:117, :161; browser_use/harness_cloud.py:242; browser_use/cli.py:422The key browser-use login stored in browser-harness's auth store is used instead. With neither key, an interactive desktop session opens a login; otherwise MissingAPIKeyError is raised before any browser starts.
BROWSER_USE_AUTO_LOGINUser settingtruebrowser_use/auth.py:39Automatic login stays allowed when the key is missing and a terminal and desktop are present; 0, false, no or off turn it off.
ANONYMIZED_TELEMETRYUser settingtruebrowser_use/config.py:37Anonymous telemetry to PostHog stays on. Any value not starting with t, y or 1 turns it off, and so does an empty value.
BROWSER_USE_LOGGING_LEVELUser settinginfobrowser_use/logging_config.py:23; browser_use/config.py:33; set at browser_use/cli.py:140The 'browser_use' logger runs at INFO. An unknown value logs a warning and falls back to info. The MCP server path sets it to critical.
BROWSER_USE_SETUP_LOGGINGUser settingtruebrowser_use/__init__.py:13; set at browser_use/cli.py:141Importing the package installs one stderr handler on the 'browser_use' logger. Only 'false' skips it.
BROWSER_USE_CONFIG_DIRUser setting$XDG_CONFIG_HOME/browseruse (~/.config/browseruse)browser_use/config.py:43; browser_use/cli.py:160The default directory is created and holds device_id, latest_version.json and telemetry/.
BROWSER_USE_CONFIG_PATHUser setting (0.x)unsetbrowser_use/cli.py:158browser-use --mcp looks for config.json in BROWSER_USE_CONFIG_DIR, else under XDG_CONFIG_HOME. Without a config file the server runs with no domain rules.
BROWSER_USE_DEVICE_IDUser settingunsetbrowser_use/telemetry/service.py:94, :372Telemetry uses the device_id persisted in the config dir, or a new random one written there.
BROWSER_USE_NO_UPDATE_CHECKUser settingunsetbrowser_use/update_check.py:30When a CLI or --cli-mcp call fails to attach a browser, the PyPI version check runs at most once a day, waits up to 2 s, and its answer is cached.
BROWSER_USE_TELEMETRY_INTERNALUser setting (vendor)unsetbrowser_use/telemetry/stats.py:621; set at tests/ci/conftest.py:27Events are not marked as Browser Use's own evals or tests.
BROWSER_USE_ALLOWED_DOMAINS0.x, raisesunsetbrowser_use/browser/browser.py:605; browser_use/cli.py:171Nothing happens. When it is set, Browser() raises a RuntimeError pointing to Browser(allowed_domains=...), while --mcp turns it into allowed_domains and removes it.
BROWSER_USE_HEADLESS0.x, warnsunsetbrowser_use/browser/browser.py:585Nothing happens. When it is set and headless is not passed, a warning says 1.0 ignores it. The browser is headless only when there is no display.
BROWSER_USE_LLM_URL0.x, warnsunsetbrowser_use/llm/__init__.py:183Nothing happens. When it is set, a warning says the production gateway is used and to pass ChatBrowserUse(base_url=...).
DEFAULT_LLM0.x, warnsunsetbrowser_use/agent/service.py:287Nothing happens. When it is set and no llm is passed, a warning says the run uses bu-4.0.
BU_STATE_DIRParent to worker.browser-usebrowser_use/repl/worker.py:109; set at browser_use/repl/session.py:378The worker writes its state to .browser-use in its working directory. In normal use the parent always sets <workspace>/.browser-use.
BU_REPL_PORTParent to workernonebrowser_use/repl/worker.py:1143; set at browser_use/repl/session.py:378The worker cannot connect back and exits at start: os.environ.pop has no default here. The parent always sets the ephemeral port on 127.0.0.1.
BU_REPL_TOKENParent to worker (secret)nonebrowser_use/repl/worker.py:1145; set at browser_use/repl/session.py:378The worker exits at start. The parent sets a 32-byte random token, compares it with hmac.compare_digest, and the worker removes it from its environment on read.
BU_REPL_PARENT_PIDParent to worker0browser_use/repl/worker.py:1141; set at browser_use/repl/session.py:385No thread watches the parent, so a worker could outlive a parent that dies.
BU_MODEParent to workerunset (default mode)browser_use/repl/worker.py:912; set at browser_use/repl/session.py:392Default mode: the ultrafast accessibility-tree helpers are not loaded. The name is in ENV_DENY, so only the parent can set it.
BU_HIGHLIGHT_ACTIONSParent to workerunsetbrowser_use/repl/worker.py:562; set at browser_use/repl/session.py:394Actions are not highlighted on the page. The name is in ENV_DENY.
BU_MODEL_CODEParent to workerunsetbrowser_use/telemetry/feedback.py:65; set at browser_use/repl/session.py:389, browser_use/mcp/cli_mcp.py:891A feedback report sent from Python counts as the user's own consent. When it is set (worker and --cli-mcp), model-written code cannot send feedback under the user's name.
BU_NAMEParent to workerdefaultbrowser_use/browser/browser.py:964, :993; browser_use/cli.py:593, :698; browser_use/harness_cloud.py:87The daemon named 'default' is used, which is the shared one for Browser('chrome') and the CLI. Library browsers always set their own name.
BU_OWN_BROWSERParent to workerunsetbrowser_use/repl/worker.py:705, :917; set at browser_use/browser/browser.py:964The worker treats the browser as the user's own Chrome, so it never makes the agent's tab the visible one.
BU_REMOTE_BROWSERParent to workerunsetbrowser_use/repl/worker.py:260, :540; set at browser_use/browser/browser.py:964The worker treats the browser as local, not a cloud browser.
BU_DOMAINSParent to workerunsetbrowser_use/repl/worker.py:541; set at browser_use/browser/browser.py:710The worker parses no domain rules, so it does not guard navigation.
BU_TABS_FILEParent to workerunsetbrowser_use/repl/worker.py:542; set at browser_use/browser/browser.py:715No tabs file is kept. Only Browser('chrome') with domain rules sets one.
BU_CAPTCHA_SOLVERParent to workerunset (on)browser_use/repl/worker.py:710; set at browser_use/browser/browser.py:966The automatic captcha solver stays on. Browser(captcha_solver=False) sets it to 'off'.
BU_SHARED_DAEMONParent to workerunsetbrowser_use/repl/worker.py:529; set at browser_use/browser/browser.py:899The worker treats the daemon as its own. Browser('chrome') sets it when it reuses a daemon that it did not start.
BU_BROWSER_IDParent to daemonunsetset at browser_use/browser/browser.py:935; read at :1051The daemon does not know the cloud browser is its own, so it does not attach to its visible tab and does not stop it on shutdown.
BU_CDP_WSbrowser-harnessunsetbrowser_use/harness_cloud.py:172; set at browser_use/repl/session.py:381, browser_use/browser/browser.py:935, browser_use/cli.py:731browser-harness uses BU_CDP_URL or finds a local Chrome. The worker always gets a dead ws://127.0.0.1:9 URL so a stray daemon cannot reach the user's Chrome, and the user's own value is in ENV_DENY.
BU_CDP_URLbrowser-harnessunsetbrowser_use/harness_cloud.py:171browser-use finds a browser itself. When it is set and nothing listens on that port, the CLI raises at once instead of letting browser-harness retry for 30 s. It is in ENV_DENY.
BU_CLEANUP_BROWSER_IDParent to watchdogemptybrowser_use/browser/local.py:509, set at :564; browser_use/mcp/cli_mcp.py:113, set at :729The watchdog or reaper has no cloud browser to stop. The id goes in the environment, never argv, because it controls the browser without a key.
BU_CLEANUP_PIDParent to watchdogunsetbrowser_use/mcp/cli_mcp.py:97, :103; set at :730The reaper waits for the MCP server to close its stdin instead of waiting on the server's process (the Windows path).
BU_CLEANUP_SINCEParent to watchdognonebrowser_use/mcp/cli_mcp.py:107; set at :730It is read only when BU_CLEANUP_PID is set, and the server always sets both together. It tells a reused pid apart from the server.
BH_AUTH_PATHbrowser-harness (secret path)browser-harness's auth.json in its config dirnot read by the package; set at tests/ci/conftest.py:24browser-harness reads and writes the stored key at its default path. The tests point it at a file that never exists. SECRET_ENV drops it from the worker because the name contains AUTH.
BH_CONFIG_DIRbrowser-harnessunder BH_HOME (~/.config/browser-harness)browser_use/auth.py:104; set at tests/ci/conftest.py:29browser-harness keeps its config and telemetry.json under BH_HOME. The package reads the variable only to name the right setting in an "unwritable dir" error.
BH_RUNTIME_DIRbrowser-harnessunder BH_HOMEbrowser_use/browser/browser.py:413, :441; browser_use/auth.py:104The daemon's socket, pid file and .cloud markers go to browser-harness's default runtime dir. Either way the dir must be owned by the user and not writable by others, or startup raises.
BH_RUNTIME_DIR_SHAREDbrowser-harnessunsetset at browser_use/browser/browser.py:414Set to 1 whenever BH_RUNTIME_DIR or BH_TMP_DIR is set, so each daemon keeps its own socket name. Left unset otherwise.
BH_TMP_DIRbrowser-harnessunder BH_HOMEbrowser_use/browser/browser.py:413, :441; browser_use/auth.py:104Daemon logs and screenshots go to browser-harness's default tmp dir, with the same ownership check.
BH_TMP_DIR_SHAREDbrowser-harnessunsetset at browser_use/browser/browser.py:414Set together with BH_RUNTIME_DIR_SHARED, for the same reason.
BH_REQUIRE_EXISTING_DAEMONbrowser-harnessunsetset at browser_use/repl/session.py:381Outside the worker, a browser-harness call may start or discover a daemon. Inside the worker it is always 1, so a browser-harness call from a cell reuses the run's daemon or fails.
BH_AGENT_WORKSPACEbrowser-harness~/.config/browser-harness/agent-workspaceset at browser_use/repl/session.py:384; read at browser_use/auth.py:104browser-harness would use the user's global agent workspace and run its agent_helpers.py. The worker always gets <workspace>/.browser-use/agent-workspace, so a prompt-injected run cannot plant helpers for later runs.
BH_TAB_MARKERbrowser-harnessbrowser-harness marks tab titlesset at browser_use/repl/session.py:378, browser_use/harness_cloud.py:151, :232, browser_use/browser/browser.py:885, :935browser-harness adds its marker to tab titles. Every daemon and worker this package starts sets 0, so page titles stay untouched.
BH_OPEN_LIVE_URLbrowser-harness0 (setdefault)set at browser_use/harness_cloud.py:294The CLI sets it to 0, so a cloud browser's live URL, which grants control, is not printed, opened or returned. 1 opts in.
BH_UPDATE_CHECKbrowser-harness0 when piped through the CLIset at browser_use/cli.py:810browser-harness's own daily update notice is turned off because browser-use pins it exactly. Library runs leave browser-harness's default.
BH_CLIENTbrowser-harnessbrowser-use-cli or browser-use-mcpset at browser_use/cli.py:33, browser_use/mcp/cli_mcp.py:890browser-harness reports itself as the client. Library runs do not set it.
BH_CLIENT_VERSIONbrowser-harnessthe browser-use versionset at browser_use/cli.py:34browser-harness reports its own version only.
BH_DEVICE_NAMEbrowser-harnessbrowser-use or browser-use-mcp (setdefault)set at browser_use/cli.py:35, browser_use/mcp/cli_mcp.py:346Names the API key that browser-use login creates in the dashboard. A user's value wins.
BH_TELEMETRYbrowser-harnessunset (on)set to 0 at browser_use/repl/session.py:388; read through browser-harness at browser_use/telemetry/service.py:129browser-harness telemetry follows its telemetry.json. The worker always gets 0, so a CLI call from a cell sends nothing. When the user sets 0, the library's events are off too.
OPENAI_API_KEYProvider key (secret)unsetbrowser_use/llm/__init__.py:306, :309An OpenAI model fails in resolve_model with "OPENAI_API_KEY is not set" before any browser starts. On the gateway URL a bu_ key here is used, else the Browser Use key.
OPENAI_BASE_URLProvider settingunset (api.openai.com)browser_use/llm/__init__.py:287ChatOpenAI targets api.openai.com through the Responses API, unless base_url is passed.
ANTHROPIC_API_KEYProvider key (secret)unsetbrowser_use/llm/__init__.py:336An Anthropic model fails before any browser starts with "ANTHROPIC_API_KEY is not set", unless api_key is passed.
GOOGLE_API_KEYProvider key (secret)unsetbrowser_use/llm/__init__.py:355GEMINI_API_KEY is tried next. With neither, a Google model fails before any browser starts.
GEMINI_API_KEYProvider key (secret)unsetbrowser_use/llm/__init__.py:355Read only when GOOGLE_API_KEY is unset, the same order as GoogleProvider.
AZURE_OPENAI_ENDPOINTProvider settingunsetnamed at browser_use/__init__.py:44, browser_use/legacy.py:495; read by Pydantic AIllm='azure:<deployment>' fails in Pydantic AI's Azure provider before any browser starts. resolve_model rewrites an error that names the variable as "<NAME> is not set".
AZURE_OPENAI_API_KEYProvider key (secret)unsetnamed at browser_use/__init__.py:44, browser_use/legacy.py:495; read by Pydantic AISame as AZURE_OPENAI_ENDPOINT.
OPENAI_API_VERSIONProvider settingunsetnamed at browser_use/__init__.py:44, browser_use/legacy.py:495; read by Pydantic AISame as AZURE_OPENAI_ENDPOINT.
XDG_CONFIG_HOMEPlatform~/.configbrowser_use/config.py:42; browser_use/cli.py:163; browser_use/skills/install.py:15The config dir is ~/.config/browseruse, and skill install targets resolve under ~/.config.
XDG_CURRENT_DESKTOPPlatformunsetbrowser_use/auth.py:44On Linux no automatic login opens, so a missing key raises MissingAPIKeyError.
XDG_SESSION_TYPEPlatformunsetbrowser_use/auth.py:45On Linux no automatic login opens unless it is x11 or wayland.
DISPLAYPlatformunsetbrowser_use/auth.py:46; allowlisted at browser_use/repl/session.py:47On Linux no automatic login opens without DISPLAY or WAYLAND_DISPLAY. It is passed to the worker when set.
WAYLAND_DISPLAYPlatformunsetbrowser_use/auth.py:46; allowlisted at browser_use/repl/session.py:47Same as DISPLAY.
LOCALAPPDATAPlatform (Windows)~/AppData/Localbrowser_use/browser/local.py:182, :218On Windows that root is not searched for Chrome, and Playwright's cache is assumed under the home directory.
PLAYWRIGHT_BROWSERS_PATHPlatformplatform cache (~/.cache/ms-playwright on Linux)browser_use/browser/local.py:213Chromium that browser-use install left behind is looked for in Playwright's default cache. A value of 0 also means the default.
SSL_CERT_FILEPlatformunsetbrowser_use/utils.py:37; browser_use/telemetry/service.py:46; allowlisted at browser_use/repl/session.py:49TLS trusts the OS verifier (truststore) only. When set, a corporate proxy's CA is added as an extra root.
SSL_CERT_DIRPlatformunsetbrowser_use/utils.py:37; browser_use/telemetry/service.py:46; allowlisted at browser_use/repl/session.py:49Same as SSL_CERT_FILE.
PYTHONPATHPlatformunsetallowlisted at browser_use/repl/session.py:47; set in tests/ci/test_repl.py:553 and othersNothing changes. When it is set, it is passed to the worker, and tests use it to put the checkout first.
CIPlatformunsetbrowser_use/auth.py:40; browser_use/update_check.py:31; browser_use/telemetry/stats.py:525Automatic login and the update check may run, and telemetry reports is_ci false. In CI none of those happen.
GITHUB_ACTIONSPlatformunsetbrowser_use/auth.py:40; browser_use/telemetry/stats.py:525Same as CI for automatic login and is_ci.
PYDANTIC_AI_NO_BANNERPlatform1 (setdefault)set at browser_use/__init__.py:11Importing browser_use sets it, so Pydantic AI prints no banner. A user's value wins.
BU_TEST_SLOW_STARTTest onlyunsettests/ci/test_repl.py:548, :554Read by a sitecustomize.py that one test writes, to slow down worker start. Never read by the package.
DOTENV_PROBETest onlyunsettests/ci/test_repl.py:262, :267A planted .env value that proves the worker never loads .env. Never read by the package.
UV_TOOL_INSTALL_ARGS_FILETest onlyunsettests/ci/test_browser_use_skill_install_docs.py:44, :63A fake uv records its arguments there in one test. Never read by the package.
CHROMETest and CI onlyunsettests/ci/conftest.py:52; .github/workflows/test.yaml:64The tests look for Chrome on known paths and PATH, and the tests marked chrome skip when none is found.
GITHUB_WORKSPACECI onlyset by GitHub Actions.github/workflows/package.yaml:73Used by the package workflow to check that the installed wheel is not the checkout. Never read by the package.
NEXT_PUBLIC_BROWSER_USE_API_KEYSkill docs onlyunsetskills/cloud/references/guides/chat-ui.md:42A sample in the Cloud skill's chat UI guide. Never read by the package.
BROWSER_USE_X402_PRIVATE_KEYSkill docs only (secret)unsetskills/x402/SKILL.md:83, :219, :250The x402 skill tells an agent to keep a wallet key in .env. Never read by the package.

How secrets are stored and rotated

Where the values come from. load_env runs when the Agent and Browser modules are imported. It loads a .env file from the working directory, or the nearest parent that has one, into os.environ, and variables already set win. The REPL worker never calls it. .env.example documents 10 names: BROWSER_USE_API_KEY, OPENAI_API_KEY, OPENAI_BASE_URL, ANTHROPIC_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY, OPENAI_API_VERSION, GOOGLE_API_KEY, BROWSER_USE_LOGGING_LEVEL and ANONYMIZED_TELEMETRY. The other 67 are not written down anywhere as a set. Most of them are the internal BU_ and BH_ channel or names that belong to browser-harness.

The Browser Use key. The key is BROWSER_USE_API_KEY, else the key browser-use login stored in browser-harness's auth store; how browser_use_api_key chooses, and when a login opens instead, is under Authentication in section 8. For configuration the point is precedence: BROWSER_USE_API_KEY wins over the stored key. When the cloud returns 401 or a missing scope, the error hint says the variable is set and wins, so a stale variable cannot hide behind a fresh login. Keyed requests carry the X-Browser-Use-API-Key header and never follow a redirect.

No secret is in the code, apart from the PostHog project key at browser_use/telemetry/service.py:34. That key is public by design: it can only write anonymous events (section 8, Deliberately public). Provider keys are passed as api_key=... or read from their provider's variable. resolve_model turns a missing one into "<NAME> is not set" before any browser starts. Secrets given to the agent as sensitive_data never pass through the environment.

Rotation and expiry are Browser Use Cloud's and the providers'. The repository does not describe them. Rotating means replacing the key: run browser-use login again, which writes a new key to the store, or set a new BROWSER_USE_API_KEY. browser-use logout removes the stored key. No variable sets a key's lifetime.

Environment separation is limited to per-model base URLs. ChatBrowserUse(base_url=...) or ChatOpenAI(base_url=...) can point at a staging or private gateway, while the 0.x BROWSER_USE_LLM_URL only warns. The cloud browser API base is the constant https://api.browser-use.com/api/v4, with no variable to change it.

FunctionWhereWhat it does
load_envbrowser_use/config.py:9Loads the nearest .env file into the process environment without overriding variables already set. The Agent and Browser modules call it on import, and the worker never does.
BROWSER_USE_LOGGING_LEVELbrowser_use/config.py:32A property of the shared CONFIG object that reads the variable on every access and returns it lowercased, defaulting to info.
ANONYMIZED_TELEMETRYbrowser_use/config.py:36A CONFIG property that reads the variable on every access and returns true only when the value is non-empty and starts with t, y or 1. Telemetry, feedback and the CLI telemetry commands check it.
BROWSER_USE_CONFIG_DIRbrowser_use/config.py:41A CONFIG property that returns the variable as a resolved path, else XDG_CONFIG_HOME/browseruse, and creates the directory. The telemetry device_id, telemetry/ and latest_version.json live there.
worker_envbrowser_use/repl/session.py:78Builds the REPL worker's environment from an allowlist of the parent's variables. It drops ENV_DENY names and every name that looks like a credential.
Repl._startbrowser_use/repl/session.py:357Starts the worker process with that environment plus the BU_ and BH_ channel variables, then waits for the worker to connect back with its token.
Browser._start_lockedbrowser_use/browser/browser.py:701Starts the browser under the instance lock and adds the domain rules (BU_DOMAINS) and tabs file (BU_TABS_FILE) to the environment it returns for the worker.
Browser._startbrowser_use/browser/browser.py:873Starts or attaches the cloud, local or CDP browser and its daemon. It returns the worker variables that describe that browser (BU_NAME, BU_OWN_BROWSER, BU_REMOTE_BROWSER, BU_CAPTCHA_SOLVER, BU_SHARED_DAEMON).
browser_use_api_keybrowser_use/auth.py:116Returns the Browser Use key from BROWSER_USE_API_KEY, else from browser-harness's store. When neither exists it opens a login if allowed, or raises MissingAPIKeyError.
_can_open_loginbrowser_use/auth.py:32Says whether an automatic login may open: it needs a terminal, a desktop session, no CI, and BROWSER_USE_AUTO_LOGIN not turned off.
resolve_modelbrowser_use/llm/__init__.py:533Turns the llm argument into a Pydantic AI model and checks its key before any browser starts. It rewrites a missing-key error as "<NAME> is not set".

Configuration and secrets rating

Configuration and secrets: 7/10, Good

Good. Configuration is externalised in 77 environment variables and read each time it is used, so a late change still applies. A missing Browser Use key fails fast with MissingAPIKeyError before any browser is billed, BROWSER_USE_API_KEY wins over the stored login key and the hints say so, and no secret is in code except the public PostHog project key. The gaps: .env.example documents 10 names and nothing documents the rest, the repository describes no key rotation or expiry, and environments are separated only by base URLs. The technical assessment gives the reasoning per criterion.

10. Infrastructure and deployment topology

The repository owns no servers. It provisions no network, database, queue or cloud account, and there is no Terraform, CloudFormation, Compose file or Kubernetes manifest in it. What it ships is a Python package (version 1.0.6 on PyPI) and a Docker image built from the Dockerfile. Everything else that runs is either on the user's machine, in GitHub Actions, or a hosted service owned by Browser Use or a model provider that this code only calls.

Environments

Five places run something this repository defines or depends on. Only the first three run code from this repository. A deploy reaches the user's machine and the container only when someone installs a release: nothing pushes to them.

EnvironmentWhat runs thereHow a deploy reaches itShared or isolated
Developer or user machineThe caller's Python process (the library, or the browser-use CLI, or the MCP server), one REPL worker process per Agent (python -P -m browser_use.repl.worker in its own process group, a job object on Windows), one browser-harness daemon per Browser, a local Chrome or Chromium when the browser kind is 'chromium' or 'chrome', and two kinds of detached helper: a watchdog per Browser and the telemetry exit sender.The user installs a pinned version from PyPI (pip, uv, uvx); upgrading is installing a newer version. When a CLI or MCP server call fails to attach a browser, the CLI checks PyPI's JSON for a newer release (at most once a day) and only prints a hint.Each Agent has its own workspace, worker and daemon. The config dir (~/.config/browseruse), the browser-harness auth store and the browser-harness runtime dir are shared by every Agent, CLI call and MCP server of one user.
Docker containerThe same processes inside the image: python:3.12-slim pinned by digest, Debian chromium, non-root user browseruse (uid 911), ENTRYPOINT browser-use. It exposes ports 9242 and 9222, declares /data as a volume and links ~/.config/browseruse to it. The HEALTHCHECK is commented out.The user pulls a tagged image from Docker Hub (browseruse/browseruse) or GHCR (ghcr.io/browser-use/browser-use), built for linux/amd64 and linux/arm64 by docker.yml.Whatever the container is given: the Browser Use API key by environment, the config dir and its telemetry spool through the /data volume when one is mounted.
GitHub Actions CIEight workflows in .github/workflows: tests, lint and type checks, wheel builds and installs, the Docker smoke run, releases, the Claude Code action and the stale bot.A push, pull request, release, schedule or manual dispatch (see the workflow table below).Runners are fresh per job. Repository secrets (DOCKER_USERNAME, DOCKER_PASSWORD, ANTHROPIC_API_KEY) and the release environment are shared across runs. Tests run with ANONYMIZED_TELEMETRY=false and make no provider or cloud calls.
Release targetsPyPI (the browser-use package, with PEP 740 attestations), Docker Hub browseruse/browseruse and GitHub Container Registry ghcr.io/browser-use/browser-use.PyPI release: publish.yml on a GitHub release, in the 'release' environment that must have required reviewers, via PyPI trusted publishing (OIDC). Images: docker.yml pushes after its smoke job passes, never for rc tags or pull requests.Published artefacts are immutable per version; the image registry also carries moving branch tags (for example main and stable) and a build cache.
Browser Use Cloud (external)Hosted by Browser Use, not by this repository: the cloud browsers API (https://api.browser-use.com/api/v4), the LLM gateway behind the default model bu-4.0, web search and the login site cloud.browser-use.com.Not deployed from here. The library reaches it over HTTPS with the X-Browser-Use-API-Key header (cloud browsers) or a bearer key (gateway).One Browser Use account and API key is shared by everything a user runs: library, CLI, MCP server and browser-harness all read the same key.

What is shared across environments is the Browser Use API key and the cloud account behind it: every cloud browser, gateway request and search a user's processes make is billed to that one account. What is isolated is per Agent: its workspace (a new temp dir with the prefix browser-use- unless the caller passes one), its REPL worker, which gets an allowlisted environment and its own browser-harness agent workspace, and its daemon. There is no staging environment of the system itself. The only environment switch the code offers is a different gateway or provider base URL (ChatBrowserUse(base_url=...), ChatOpenAI(base_url=...)); the 0.x BROWSER_USE_LLM_URL only warns (section 9).

User's machine, or the Docker image (user browseruse, uid 911) Hosted services, not in this repository Caller process Agent.run, Browser, Repl parent, or the browser-use CLI / MCP server spawns a watchdog per Browser and the detached telemetry exit sender REPL worker (one per Agent) python -P -m browser_use.repl.worker own process group; runs model code Local files Agent workspace, config dir, telemetry spool, harness auth store browser-harness daemon one per Browser; socket and pid file in the browser-harness runtime dir Local Chrome or Chromium Browser('chromium') temp profile, or the user's own Chrome Browser Use Cloud api.browser-use.com/api/v4 LLM gateway (bu-4.0), browsers API, search login at cloud.browser-use.com Cloud browser created by POST /browsers, driven over CDP LLM providers OpenAI, Anthropic, Google, compatible servers PostHog EU anonymous telemetry PyPI JSON CLI update check HTTPS with the API key: model, cloud browsers, search, provider APIs, PostHog, PyPI version check spawns; 127.0.0.1 token socket IPC cells, screenshots, checkpoints CDP (local) CDP wss Release path (GitHub Actions) GitHub Actions, 8 workflows tests, lint, builds, smoke runs PyPI browser-use wheel and sdist Docker Hub browseruse/browseruse GHCR ghcr.io/browser-use/... publish.yml OIDC docker.yml: smoke on both arches, then push linux/amd64 and linux/arm64
Figure 10.1 · deployment topologyEvery process runs on the user's machine or in the container; the hosted services on the right are reached, never deployed. The only deploy this repository performs is the release path at the bottom, from GitHub Actions to PyPI and the two image registries.

How a release is built and published

publish.yml runs on a published GitHub release, or by manual dispatch, which can first tag the pyproject.toml version as a pre-release (it must be X.Y.ZrcN). Before anything is uploaded, the job checks that the 'release' environment exists with a required-reviewers rule and self-review blocked, failing closed otherwise; checks that the tag equals the pyproject.toml version and is the checked-out commit; runs ruff --select PLE and pytest tests/ci -m "not chrome"; builds the wheel and smoke-tests it in a fresh Python 3.11 venv outside the checkout. It then publishes with PyPI trusted publishing (OIDC) and PEP 740 attestations, and a stable (non-rc) release force-pushes the stable branch.

docker.yml first builds the image natively on amd64 and arm64 runners without pushing, runs browser-use --version and a scripted Agent run on the image's Chromium (docker/smoke.py: no provider, no cloud). Only then, and never for pull requests, rc tags or GitHub pre-releases, it builds for linux/amd64 and linux/arm64 and pushes to browseruse/browseruse and ghcr.io/browser-use/browser-use with branch, version, major.minor and commit-SHA tags, using a registry build cache. A push to the main branch therefore publishes an image tagged main. All third-party actions in every workflow are pinned by commit SHA.

Infrastructure and packaging files probed 26 rows
PathPresentWhat it means here
DockerfileyesThe single image: python:3.12-slim by digest, uv 0.12.9 by digest, Debian Chromium, uv sync --locked, non-root user, /data volume, ports 9242 and 9222, ENTRYPOINT browser-use, healthcheck commented out.
docker-compose.ymlnoNo multi-container setup; the image runs alone.
compose.ymlnoAs above.
serverless.ymlnoNo serverless deployment.
template.ymlnoNo SAM or CloudFormation template.
template.yamlnoAs above.
samconfig.tomlnoAs above.
main.tfnoNo Terraform.
terraformnoAs above.
cdk.jsonnoNo AWS CDK.
ProcfilenoNo platform-as-a-service process definition.
MakefilenoDevelopment commands are uv invocations (CLAUDE.md) and scripts under bin/.
k8snoNo Kubernetes manifests.
.github/workflowsyesEight workflows, tabled below; the whole CI and release path.
.gitlab-ci.ymlnoGitHub Actions is the only CI.
JenkinsfilenoAs above.
azure-pipelines.ymlnoAs above.
.env.exampleyesDocuments 10 variable names (section 9); a .env in the working directory is loaded on import.
.env.sampleno.env.example is the only sample.
composer.jsonnoNot a PHP project.
package.jsonnoNo Node.js package.
pyproject.tomlyesThe package: version 1.0.6, Python >=3.11,<4.0, exact pins, console scripts browser-use, browseruse and the deprecated browser-use-tui; uv.lock resolves only packages published before 2026-11-09T09:48:30Z.
go.modnoNot a Go project.
Cargo.tomlnoNot a Rust project.
pom.xmlnoNot a Java project.
.gitattributesyesRepository line-ending and diff attributes; no deployment role.
GitHub Actions workflows 8 rows
WorkflowTriggerWhat it checks or deploys
claude.ymlIssue and pull request comments, reviews and new or assigned issues that mention @claude, from an owner, member or collaboratorRuns the Claude Code GitHub Action with the ANTHROPIC_API_KEY secret; the action itself refuses actors without write access. Deploys nothing.
docker.ymlPush to the main, stable or releases/** branches or any tag; published release; pull requests touching the image inputs; manualSmoke job per architecture (build, --version, scripted Agent run), then builds and pushes the multi-arch image to Docker Hub and GHCR, except for pull requests, rc tags and pre-releases.
install-script.ymlPush to the main or v1 branch and pull requests touching the CLI, the skill or pyproject.toml; manualChecks the generated Browser Use skill matches the pinned browser-harness; installs with uv pip on Linux, macOS and Windows and from a local wheel with uvx, and on the main branch from PyPI, running --help, auth --help and skill show.
lint.ymlPush to the main, v1, stable and releases/** branches, tags; pull requests; manualThree jobs: ruff check --select PLE, pre-commit run --all-files, and pyright.
package.yamlSame as lint.ymlBuilds the wheel and sdist once, then installs the wheel on Linux, macOS and Windows with Python 3.11 and 3.13 and imports the package from outside the checkout.
publish.ymlPublished GitHub release; manual dispatch (optionally tagging an rc first)Verifies the protected 'release' environment and the tag, runs the non-chrome tests, builds and smoke-tests the wheel, publishes to PyPI by trusted publishing with attestations, and moves the stable branch on a stable release.
stale-bot.ymlDaily at 02:00 UTC; manualMarks issues stale after 60 days and pull requests after 45, closing either 14 days later. Deploys nothing.
test.yamlPush to the main, v1, stable and releases/** branches, tags; pull requests; manualUnit job: pytest -m "not chrome" on ubuntu, macos and windows (Python 3.11) and ubuntu Python 3.12, 3.13, 3.14. Chrome job: the chrome-marked tests against real headless google-chrome, failing if Chrome is missing rather than skipping.

11. Data and persistence

There is no database, ORM, cache server, queue or object store in this repository: the evidence's store probe found none, and reading the source confirms it. The state that outlives a call is ordinary files on the local disk, keyed by path, written by the module that owns them. This section tables those files as stores, because they are where task data, page content, credentials and telemetry actually sit.

Stores

Eight file stores. Paths are relative to the location in the second column. <workspace> is the Agent's workspace: a new temp dir with the prefix browser-use- unless the caller passes a workspace, kept after the run for the caller to delete; run state lives under <workspace>/.browser-use. The config dir defaults to $XDG_CONFIG_HOME/browseruse (~/.config/browseruse), overridden by BROWSER_USE_CONFIG_DIR; it holds device_id, latest_version.json and the telemetry spool dir. In the Docker image ~/.config/browseruse is a link to the /data volume.

StoreLocationOwnerLifetime and retentionIndex
Agent workspace<workspace>/ and <workspace>/.browser-use/Agent, Repl and the REPL workerKept after every run with no retention; the caller deletes it (MIGRATING.md). A follow-up run on the same workspace continues the cell numbering rather than overwriting.None: files are addressed by path; cell numbers come from listing cells/*.txt
Browser Use config dir~/.config/browseruse/telemetry service, update check, CLIPermanent; created on first read of the setting. Nothing in it expires except the update-check cache entry (24 h, 1 h after a failed lookup).None
Telemetry spool~/.config/browseruse/telemetry/ProductTelemetryOutbox capped at 20 files, 512 KiB and 7 days, oldest dropped first; in-flight markers deleted when the run ends or when a later process reports the run as crashed.None: the outbox is listed and sorted by file modification time
browser-harness auth store~/.config/browser-harness/auth.jsonbrowser-harness (written by browser-use login); read and repaired hereUntil browser-use logout or a new login. A corrupt store is moved aside to auth.json.corrupt (then .corrupt.2 and so on), never overwritten.None
Cloud browser markersbrowser-harness runtime dir, next to each daemon's pid fileharness_cloud (CLI piped code)One <daemon>.cloud file per daemon name that ran a cloud browser; kept until the browser is stopped and the name is reloaded, because it is the only way to stop that browser once its daemon is gone.None: looked up by daemon name
Local Chromium temp dirs$TMPDIR/browser-use-chrome-*/LocalBrowserDeleted when the Browser stops; a dir left by a dead process is swept by the next LocalBrowser once its .owner lock is free. Browser('chromium', user_data_dir=...) uses the caller's dir instead and keeps it.None
Domain-guard tabs file$TMPDIR/browser-use-tabs-*Browser, appended by the REPL workerCreated when an attached browser has domain rules; read and deleted when the Browser stops.None: one target id per line
Installed agent skill files~/.agents, ~/.claude, ~/.codex, ... /skills/browser-use/SKILL.mdbrowser-use skill (skills/install.py)Permanent until the user removes them; each install overwrites the file.None

Keys and access patterns

No store has an index of any kind. Every lookup is a known path or a directory listing; the only ordering is cell numbers in file names and file modification times in the telemetry outbox. The table has one row per path (the key) with the access pattern it serves.

Keys, one row per path 22 rows
StoreKeyAccess pattern
Agent workspace<workspace>/downloads/Files a launched local Chrome downloads (Chrome writes them by guid, the worker renames them) and a cloud browser's downloads copied in when it stops; the run lists what it added as the result's downloads field.
Agent workspace<workspace>/<any file the model writes>Checkpoints and deliverables the model's code writes, for example with checkpoint, which writes atomically and redacts secrets.
Agent workspace.browser-use/cells/NNNN.txtWritten as a cell runs (stdout and stderr, secrets redacted on the way); the parent reads its first 12,000 characters back for the model, and after a timeout reads what a killed cell left.
Agent workspace.browser-use/screenshots/NNNN.jpgOne JPEG (quality 70) per screenshot the model takes, numbered by counting the dir; read back only when the model asks to show one.
Agent workspace.browser-use/partial.jsonReplaced atomically by checkpoint(..., partial=True); read once when a run ends without a result, deleted at the start of each run.
Agent workspace.browser-use/context/<uuid>.jsonOne compaction archive per client-side compaction (version 1: summary, covered message count, the redacted messages), created 0600 in a 0700 dir; the checkpoint message tells the model the path so it can re-read evidence.
Agent workspace.browser-use/worker.logAppended: the worker's startup output and anything printed between cells, redacted; read by a human when the worker fails to start.
Agent workspace.browser-use/captcha.jsonCaptcha solver state replaced atomically on every change, so a worker restarted after a cell timeout still knows a running solve; deleted when a new Repl is created.
Agent workspace.browser-use/downloads.jsonlAppended by the worker per download start and JSON page shown; read incrementally by the Browser to name downloads and drop a cloud browser's copies of JSON pages.
Agent workspace.browser-use/agent-workspace/browser-harness's agent workspace for this Agent (BH_AGENT_WORKSPACE), so the worker never loads the user's global helpers or domain skills.
Browser Use config dirdevice_idRead once per process; created with a hard link so concurrent processes keep the first id written. BROWSER_USE_DEVICE_ID overrides it.
Browser Use config dirlatest_version.jsonRead before each CLI update check; rewritten after a PyPI lookup with the version and the time checked.
Browser Use config dirconfig.jsonRead only (a 0.x file): the MCP server takes allowed_domains and prohibited_domains from its default browser profile. BROWSER_USE_CONFIG_PATH points elsewhere.
Telemetry spooltelemetry/outbox/<run_id>.gzOne gzip event batch per unsent run; claimed by rename to <run_id>.<pid>.sending while one process sends it, deleted when sent, renamed back on failure.
Telemetry spooltelemetry/inflight/<run_id>.jsonMarker of a running run (pid, start, progress, event properties), refreshed every 30 s and removed at the end; a marker whose process died is sent as a crashed run.
Telemetry spool$TMPDIR/browser-use-<name>.*.gzWith usage stats off, a feedback event the user sent themselves, handed to the exit sender, which deletes it sent or not.
browser-harness auth storeauth.jsonRead for the Browser Use API key when BROWSER_USE_API_KEY is not set; written by login, removed by logout.
Cloud browser markers<daemon>.cloudHolds the cloud browser id (0600, the id alone drives the browser); written on start, emptied on stop, read by the next CLI call and by --reload.
Cloud browser markers<name>-chromium.chromium/The profile of the CLI's own Chromium next to its daemon's pid file; deleted and recreated on each launch, deleted when it closes.
Local Chromium temp dirsbrowser-use-chrome-*/profile and .ownerThe Chrome profile (fresh, or a copy of a real Chrome profile without caches for Browser('chrome', profile=...)) and Chrome's log; .owner is locked while the owning process lives.
Domain-guard tabs filebrowser-use-tabs-*The worker appends the target id of each tab the agent created or attached to; the Browser reads it to know which tabs its sweep may close.
Installed agent skill files<agent>/skills/browser-use/SKILL.mdWritten whole by browser-use skill install into ~/.agents always and into the dirs of agents already installed; printed by skill show.

Files that touch a store

Fourteen package files read or write one of the stores above. The first table names, per file, the functions that do; the second describes each of those functions.

Files that touch a store 14 rows
FileStoreFunctionsWhat it does
browser_use/agent/service.pyAgent workspaceAgent.workspace, Agent._run, Agent._list_downloads, Agent._shutdownCreates the workspace and its .browser-use and downloads dirs before a browser is billed, and collects the files a run added to downloads.
browser_use/agent/loop.pyAgent workspaceSession.partial, _compact, loop.runWrites compaction archives, reads the partial result when a run ends without one, and clears it at the start of each run.
browser_use/repl/session.pyAgent workspaceRepl.__init__, Repl._start, Repl._call, _head, clipSets up the state dir and worker log for each worker, continues cell numbering, and reads a cell's output file back for the model.
browser_use/repl/worker.pyAgent workspacescreenshot, checkpoint, _write_atomic, _pump, _redact_between_cells, _log_download, CellStats.name_downloadWrites cell output, screenshots, checkpoints, the partial result and the download log, redacting secrets before anything reaches the disk.
browser_use/repl/captcha.pyAgent workspaceCaptcha._load, Captcha._savePersists captcha solver state so it survives a worker restart within one Repl.
browser_use/telemetry/service.pyConfig dir, telemetry spooltelemetry_dir, get_or_create_device_id, _persisted_device_id, harness_disabled, _once_file, ProductTelemetry._to_outbox, ProductTelemetry._outbox, ProductTelemetry._send_outbox, ProductTelemetry._claim, ProductTelemetry._mark, ProductTelemetry._unmark, ProductTelemetry._send_crashed, ProductTelemetry._at_exitOwns the device id and the whole telemetry spool: the bounded outbox, the per-run in-flight markers and the hand-off to the exit sender.
browser_use/update_check.pyConfig dir_latestCaches PyPI's latest version in latest_version.json.
browser_use/harness_cloud.pyCloud browser markers_marker, _record, _recorded_id, forgetRecords which daemon name drives which cloud browser so a later CLI call can stop it.
browser_use/browser/browser.pyAgent workspace, tabs file, runtime dir_download, download_records, json_page_copies, _check_runtime_dir, Browser._start_locked, Browser._send_downloads, Browser._touched_tabs, Browser._stop_now, Browser.note_downloads, Browser._fetch_downloadsStreams cloud downloads into the workspace, reads the worker's download log, owns the tabs file, and refuses a runtime dir another user could write.
browser_use/browser/local.pyLocal Chromium temp dirscopy_profile, sweep_stale_dirs, LocalBrowser.__init__, LocalBrowser._start, LocalBrowser._remove_tmpCreates, fills and deletes each launched Chrome's temp profile, and sweeps the ones dead processes left.
browser_use/config.pyConfig dirConfig.BROWSER_USE_CONFIG_DIRResolves the config dir from the environment on every access and creates it.
browser_use/skills/install.pyInstalled agent skill files_all_target_skill_paths, _resolve_output_paths, handleChooses the agent skill dirs and writes SKILL.md into each.
browser_use/auth.pybrowser-harness auth storebrowser_use_api_key, corrupt_store_path, set_aside_corrupt_storeReads the stored key and moves a corrupt store aside instead of overwriting it.
browser_use/cli.pyConfig dir, auth store, markers_mcp_browser_options, _run_login_command, _run_logout_command, _own_chromium_dir, _start_own_chromium, _close_own_chromium, _run_browser_harnessReads the 0.x config.json, drives login and logout of the key store, and owns the CLI's own Chromium profile and the --reload path that clears a cloud marker.
Functions that touch a store 68 rows
FunctionWhereWhat it does
Agent.workspacebrowser_use/agent/service.py:350Returns the Agent's workspace, making a new temp dir with the prefix browser-use- on first use when the caller gave none. The dir is never deleted by the library.
Agent._runbrowser_use/agent/service.py:466Runs one task: creates the workspace with its .browser-use and downloads dirs (failing early if unwritable), starts the browser and REPL, and lists the files the run added to downloads.
Agent._list_downloadsbrowser_use/agent/service.py:657Answers the worker's mid-run downloads request: reads new lines of the workspace's downloads.jsonl, then asks the Browser for its list.
Agent._shutdownbrowser_use/agent/service.py:663Stops the REPL and the browser, telling the Browser to copy a cloud browser's downloads into the workspace.
Session.partialbrowser_use/agent/loop.py:159Reads the last partial checkpoint from partial.json with secrets redacted, or None when it is missing or unreadable.
_compactbrowser_use/agent/loop.py:959Summarises older history with one model request and writes the redacted messages and summary to a new 0600 archive under .browser-use/context.
loop.runbrowser_use/agent/loop.py:1276Runs the Pydantic AI loop for one task under the run's budgets and returns a status instead of raising. It deletes the previous run's partial.json first.
Repl.__init__browser_use/repl/session.py:313Sets the state dir to <workspace>/.browser-use, deletes an earlier session's captcha.json and continues cell numbering from the highest existing cell file.
Repl._startbrowser_use/repl/session.py:357Creates the state dir, opens worker.log for the child and spawns the worker with BU_STATE_DIR and its own BH_AGENT_WORKSPACE.
Repl._callbrowser_use/repl/session.py:524Sends one cell to the worker and waits for its answer; on a timeout or a worker exit it kills the worker and returns the start of the cell's output file.
_headbrowser_use/repl/session.py:213Reads at most 12,001 characters from the start of a cell's output file, so a cell that printed gigabytes is never loaded whole.
clipbrowser_use/repl/session.py:208Cuts cell output to 12,000 characters and appends the path of the full output file.
CellStats.name_downloadbrowser_use/repl/worker.py:255Renames a download a launched Chrome saved under its guid to its real name, looking the name up in downloads.jsonl when an earlier worker saw it start.
_log_downloadbrowser_use/repl/worker.py:307Appends one JSON record per download start or JSON page shown to downloads.jsonl, ignoring write errors.
screenshotbrowser_use/repl/worker.py:728Captures the current tab as a JPEG into .browser-use/screenshots and shows it to the model. Returns the file path.
checkpointbrowser_use/repl/worker.py:742Atomically saves a JSON value (secrets redacted) to a file the model names; with partial=True it also becomes the run's fallback result in partial.json.
_write_atomicbrowser_use/repl/worker.py:1009Writes text to a .tmp sibling and renames it over the target, so a kill mid-write leaves the old file.
_pumpbrowser_use/repl/worker.py:1016Copies a cell's output pipe into its cell file, redacting secret values on the way so they never reach the disk, even when the cell is killed.
_redact_between_cellsbrowser_use/repl/worker.py:1113Routes output written between cells (a leftover thread or subprocess) through the redacting pump into worker.log.
Captcha._loadbrowser_use/repl/captcha.py:51Restores running and unreported captcha solves from captcha.json after a worker restart, starting empty if the file is unreadable.
Captcha._savebrowser_use/repl/captcha.py:64Writes the solver state to a temp file and renames it over captcha.json, ignoring write errors.
telemetry_dirbrowser_use/telemetry/service.py:81Returns the telemetry spool dir inside the config dir, where the outbox and in-flight markers live.
get_or_create_device_idbrowser_use/telemetry/service.py:85Returns the anonymous device id once per process: BROWSER_USE_DEVICE_ID, else the stored id, else a random one for this process only.
_persisted_device_idbrowser_use/telemetry/service.py:98Reads device_id from the config dir or creates it with a hard link from a temp file, so concurrent processes all keep the first id.
harness_disabledbrowser_use/telemetry/service.py:122Reports whether browser-harness's opt-out is set, by its environment names or its telemetry.json, read once per process.
_once_filebrowser_use/telemetry/service.py:152With usage stats off, writes a user-sent feedback event to a temp file for the exit sender, outside the config dir.
ProductTelemetry._to_outboxbrowser_use/telemetry/service.py:439Writes an unsent event batch to outbox/<run_id>.gz, deleting the oldest files first to stay within 20 files and 512 KiB.
ProductTelemetry._outboxbrowser_use/telemetry/service.py:458Lists the outbox oldest first after returning claims of dead senders and deleting files older than 7 days.
ProductTelemetry._send_outboxbrowser_use/telemetry/service.py:482Claims and posts each outbox file in turn, deleting it when sent and stopping at the first failure so the rest wait for a later process.
ProductTelemetry._claimbrowser_use/telemetry/service.py:500Renames a spool file to <stem>.<pid>.<kind> so only one process sends it; returns None once the process is exiting.
ProductTelemetry._markbrowser_use/telemetry/service.py:513Atomically writes or refreshes the in-flight marker of a running run with its pid, start time, progress and event properties.
ProductTelemetry._unmarkbrowser_use/telemetry/service.py:528Forgets a finished run and deletes its in-flight marker.
ProductTelemetry._send_crashedbrowser_use/telemetry/service.py:535Sends the marker of each run whose process died as a crashed-run event, deleting the marker once sent.
ProductTelemetry._at_exitbrowser_use/telemetry/service.py:572At exit, writes queued events to the outbox and hands them, with the backlog, to a detached exit-sender process so exit does not wait on the network.
_latestbrowser_use/update_check.py:82Returns PyPI's latest browser-use version, from latest_version.json when checked within 24 hours (1 hour after a failure), else from PyPI with a 2 s limit, and rewrites the cache.
_markerbrowser_use/harness_cloud.py:59Returns the path of a daemon name's .cloud marker next to its pid file.
_recordbrowser_use/harness_cloud.py:63Writes a cloud browser id into the marker with mode 0600, also fixing the mode of a marker an older version wrote.
_recorded_idbrowser_use/harness_cloud.py:72Reads the recorded cloud browser id for a name: None when it never ran one, empty once it was stopped.
forgetbrowser_use/harness_cloud.py:282Stops a still-recorded cloud browser and deletes the marker so the name can drive a local Chrome again; keeps the marker when the stop fails.
_downloadbrowser_use/browser/browser.py:234Streams one cloud download into a new, exclusively created file in the downloads dir before a deadline, deleting a partial file on failure.
download_recordsbrowser_use/browser/browser.py:269Parses downloads.jsonl lines into records, skipping unreadable ones.
json_page_copiesbrowser_use/browser/browser.py:279Names the cloud downloads that are only copies of JSON pages the tab displayed, so they are not copied into the workspace.
_check_runtime_dirbrowser_use/browser/browser.py:432Refuses a browser-harness runtime or tmp dir that another user owns or can write, since it holds the daemon socket and the .cloud markers.
Browser._start_lockedbrowser_use/browser/browser.py:701Starts or reattaches the browser; for an attached browser with domain rules it creates the browser-use-tabs-* file and passes it to the worker.
Browser._send_downloadsbrowser_use/browser/browser.py:751Tells a Chrome this Browser launched to save downloads into the workspace's downloads dir under their guid.
Browser._touched_tabsbrowser_use/browser/browser.py:1002Reads the tab ids the worker appended to the tabs file and merges them with the tabs it knows the agent used.
Browser._stop_nowbrowser_use/browser/browser.py:1030Stops the daemon, a launched Chrome and a cloud browser (retrying the stop three times), and reads then deletes the tabs file.
Browser.note_downloadsbrowser_use/browser/browser.py:1198Reads the lines of a worker's downloads.jsonl not read before and adds them to the Browser's download records.
Browser._fetch_downloadsbrowser_use/browser/browser.py:1230Copies a cloud browser's finished downloads into a local dir before a deadline, skipping ones already fetched and JSON page copies.
copy_profilebrowser_use/browser/local.py:277Copies Chrome's Local State and one profile dir, without caches, into the temp profile; fails if Chrome holds the cookies locked.
sweep_stale_dirsbrowser_use/browser/local.py:311Deletes browser-use-chrome-* temp dirs whose .owner lock is free, that is, ones left by dead processes.
LocalBrowser.__init__browser_use/browser/local.py:383Sweeps stale dirs, makes a new browser-use-chrome- temp dir and locks its .owner file for this process's lifetime.
LocalBrowser._startbrowser_use/browser/local.py:412Prepares the profile (a copy of a real profile, the caller's user_data_dir, or a fresh one in the temp dir) and launches Chrome on it.
LocalBrowser._remove_tmpbrowser_use/browser/local.py:487Releases the owner lock and deletes the temp dir, retrying while Windows still holds files.
Config.BROWSER_USE_CONFIG_DIRbrowser_use/config.py:41Resolves the config dir from BROWSER_USE_CONFIG_DIR or XDG_CONFIG_HOME on every access and creates it.
_all_target_skill_pathsbrowser_use/skills/install.py:39Lists the SKILL.md paths to install: ~/.agents always, plus the dirs of coding agents that are already installed.
_resolve_output_pathsbrowser_use/skills/install.py:121Turns the chosen target or custom path into the list of SKILL.md files to write.
handlebrowser_use/skills/install.py:146Runs browser-use skill: shows the skill or writes it to each target path, reporting each unwritable one and carrying on.
browser_use_api_keybrowser_use/auth.py:116Returns BROWSER_USE_API_KEY when set, else the key in the browser-harness auth store; raises MissingAPIKeyError on a missing key or a corrupt store.
corrupt_store_pathbrowser_use/auth.py:175Returns the auth store's path when it exists but is not a valid JSON object, else None.
set_aside_corrupt_storebrowser_use/auth.py:186Before a login, renames a corrupt store to a free auth.json.corrupt name so a key it may hold is not lost.
_mcp_browser_optionsbrowser_use/cli.py:148Reads domain rules for the MCP server from the 0.x config.json default profile and BROWSER_USE_ALLOWED_DOMAINS, refusing proxy settings.
_run_login_commandbrowser_use/cli.py:376Runs browser-use login: moves a corrupt store aside, then stores the new key through browser-harness and records the outcome.
_run_logout_commandbrowser_use/cli.py:427Removes a corrupt store directly, otherwise lets browser-harness remove the stored key.
_own_chromium_dirbrowser_use/cli.py:612Returns the profile dir of the CLI's own Chromium, next to its daemon's pid file.
_start_own_chromiumbrowser_use/cli.py:639Deletes any old profile and launches the CLI's own Chromium detached on a fresh one, so it outlives the call.
_close_own_chromiumbrowser_use/cli.py:755Stops the CLI's own Chromium and deletes its profile dir.
_run_browser_harnessbrowser_use/cli.py:795Runs piped Python against browser-harness for the CLI; on --reload it clears the name's cloud marker and closes the CLI's own Chromium.

Personal data held

The personal data the system holds is all on the user's disk, unencrypted: the task text and the model transcript (in the caller's memory and, after a compaction, in the context archives); page text and screenshots of every site visited (cell files, .browser-use/screenshots/, context archives); downloaded files; whatever the model's code chose to save in the workspace. Secret values from sensitive_data are redacted from cell files, checkpoints and archives, but anything else a page shows (names, addresses, account details) is kept as it appeared. With Browser('chrome', profile=...) a copy of that Chrome profile, its cookies and saved logins included, sits in a browser-use-chrome-* temp dir until the Browser stops, or until the next sweep if the process died. The Browser Use API key sits in ~/.config/browser-harness/auth.json. The workspace has no retention: it stays until the caller deletes it.

Sent off the machine by default: anonymous telemetry to PostHog at https://eu.i.posthog.com, on by default and off with ANONYMIZED_TELEMETRY=false. Telemetry sends the URLs visited (no ports, query strings or path tokens), error classes and the final result cut to 500 characters with emails, keys, tokens and 6+ digit runs replaced; never the task text, typed text, code or secrets. The device id is a random UUID, never derived from the machine. Everything the model reads is of course also sent to the model provider as part of the conversation.

Layers and tiers

Layers: there is no data-access layer. No repository, ORM or storage module sits between the code and the disk; each module opens and writes its own files with pathlib and os calls, and owns its own format (plain text cell files, JPEG, JSON, JSON lines, gzip batches). The only shared helper is the worker's _write_atomic, and only the compaction archive carries a format version.

Not every write is atomic. The source uses tmp-then-replace (or a hard link) only for checkpoints, partial.json, captcha.json, the telemetry in-flight markers and device_id. Screenshots, cell output, outbox batches, latest_version.json, compaction archives, .cloud markers and SKILL.md are written directly in place.

Tiers: one tier, the local disk. There is no cache tier (the 24 hour update-check file is the only cached value), no archive or cold storage, and no search or analytics copy kept by the library; the telemetry outbox is a send queue, not a store of record. The one remote copy is opt-in: a Browser Use Cloud profile named by cloud_profile_id, which the cloud saves when a cloud browser stops. The repository does not manage or back it up.

Data and persistence rating

Data and persistence: 6/10, Fair

Fair. There is no database; state is local files, the ones that matter for recovery (checkpoints, the partial result, solver state, run markers, the device id) are written atomically, compaction archives and cloud browser markers get 0600 or 0700 modes, and the telemetry outbox is bounded at 20 files, 512 KiB and 7 days. The real gaps are the Agent workspace, which holds cell output, screenshots, compaction archives with page text and downloads, is kept after every run with no retention and is unencrypted; telemetry on by default sending the URLs visited and a scrubbed 500 character result to PostHog; and no data-access layer, with each module owning its own file format and only the compaction archive versioned. The technical assessment gives the reasoning per criterion.

12. External integrations

The library reaches a few kinds of systems. Browser Use Cloud carries the default model, cloud browsers, web search and login: the default path sends all of them to one host, api.browser-use.com, plus cloud.browser-use.com for the login page. Then there are the LLM providers a caller picks instead of the LLM gateway, PostHog for anonymous telemetry, PyPI for a version check after a CLI or MCP server call fails to attach a browser (at most once a day), and two local processes: the browser-harness daemon and Chrome. CI adds the release targets (PyPI, Docker Hub, GitHub Container Registry) and one GitHub Action. HTTP calls from the package go through urllib, never requests or httpx directly. Calls that carry a Browser Use key go through urlopen_keyed, which never follows a redirect. Model calls go through the Pydantic AI provider SDKs. The table below lists the 17 integrations and what breaks when each is down.

Integrations 17 rows
IntegrationKindWhereWhat breaks when it is down
Browser Use Cloud browsers API (api.browser-use.com/api/v4/browsers)Third-party HTTP API, keyedbrowser_use/browser/browser.py:48, :215The default Browser() cannot create a cloud browser within the 120 s create deadline, so the run fails before the task starts. Downloads cannot be fetched at stop. Browser('chromium'), Browser('chrome') and cdp_url are unaffected.
Browser Use LLM gateway (default bu-4.0)Third-party model API, keyedbrowser_use/llm/__init__.py:29Every run on the default model fails. The preflight check fails it fast before a cloud browser is billed. A run with the user's own provider is unaffected.
Browser Use web search (POST /api/v4/search)Third-party HTTP API, keyedbrowser_use/search.py:22; browser_use/repl/session.py:493search() in a cell returns an error within the 25 s deadline (SEARCH_TIMEOUT_S), and the model goes on browsing without it. The call is made by the parent, never the worker.
Browser Use login (cloud.browser-use.com through browser-harness auth)OAuth or device-code login, run by browser-harnessbrowser_use/cli.py:376; browser_use/auth.py:116browser-use login, automatic login and the MCP browser_login tool cannot get a key. A key already in BROWSER_USE_API_KEY or the store keeps working.
OpenAI APIModel provider SDKbrowser_use/llm/__init__.py:309Runs on OpenAI models fail. A bad key or unknown model is caught by the preflight check before a browser starts. One transient error per run is retried, then the run ends with status error.
Anthropic APIModel provider SDKbrowser_use/llm/__init__.py:336Runs on Claude models fail, with the same preflight check and single transient retry.
Google Gemini API (generativelanguage.googleapis.com)Model provider SDKbrowser_use/llm/__init__.py:36, :355Runs on Gemini models fail. The google-genai client gets max_retries=2.
Azure OpenAI and OpenAI-compatible servers (base_url)Model endpoint the user namesbrowser_use/llm/__init__.py:287Runs on that endpoint fail. No preflight check runs, because it covers official endpoints only.
PostHog EU (eu.i.posthog.com)Telemetry HTTP endpointbrowser_use/telemetry/service.py:35, :385Nothing visible to the user. A send gives up after 3 s and the event waits in the outbox (20 files, 512 KiB, 7 days) for a later process.
PyPI JSON version check (pypi.org/pypi/browser-use/json)Public HTTP APIbrowser_use/update_check.py:13, :82The upgrade hint on a browser-attach error is left out after at most 2 s, and the failed lookup is cached for an hour.
browser-harness daemon (local IPC)Local process over a Unix socket (TCP loopback with a token on Windows)browser_use/browser/browser.py:348Cells cannot reach the browser. After BrowserConnectionLost the library reattaches, and if the browser is gone the run moves to its delivery-only turn (browser_gone).
Chrome or Chromium over CDP (local, or cdp_url)Local or remote process over a CDP websocketbrowser_use/browser/local.py:158; browser_use/browser/browser.py:327The run loses its browser. A dead local Chrome is relaunched, and a cdp_url that does not answer fails at start with a clear error.
Playwright Chromium download (uvx playwright install chromium)Package download, on demandbrowser_use/cli.py:299, :317browser-use install fails. Only Browser('chromium') on a machine with no Chrome, Chromium or Edge needs it.
PyPI publishing (CI)Release target, trusted publishing (OIDC).github/workflows/publish.yml:138A release cannot be published. Installed users are unaffected.
Docker Hub (CI)Image registry, browseruse/browseruse.github/workflows/docker.yml:89, :106The image is not pushed, and the build cache (browseruse/browseruse:buildcache) is unavailable.
GitHub Container Registry (CI)Image registry, ghcr.io/browser-use/browser-use.github/workflows/docker.yml:95, :107The GHCR copy of the image is not pushed.
Claude Code GitHub Action (claude.yml)CI action using the ANTHROPIC_API_KEY repository secret.github/workflows/claude.yml:50The assistant does not answer mentions on issues and pull requests. Nothing shipped is affected.

Outbound calls

The evidence lists 17 hosts called from code, out of 151 distinct hosts named in the repository. "Called from code" means named on a line outside tests and comments. Only five of the 17 are ever contacted, and two of those only by developer or CI scripts. At run time the package contacts api.browser-use.com (cloud browsers, the LLM gateway, web search), eu.i.posthog.com (telemetry) and pypi.org (the version check). bin/setup.sh contacts github.com and astral.sh. The other twelve are links in issue templates, help text and error messages, docstring examples, or JSON schema URLs that nothing fetches. All 17 are expected for a library sold alongside a cloud service.

Hosts called from code 17 rows
HostWhereWhat forContacted?Expected
github.com.github/ISSUE_TEMPLATE/1_element_detection_bug.yml:16; browser_use/exceptions.py:30; browser_use/cli.py:910; bin/setup.sh:26Links to releases, issues and MIGRATING.md in templates, errors and help text. bin/setup.sh runs a git clone of the repository.Only by bin/setup.sh (developer setup)Yes: the project's own repository.
api.browser-use.combrowser_use/browser/browser.py:48; browser_use/llm/__init__.py:29; browser_use/search.py:22; browser_use/mcp/cli_mcp.py:456Cloud browser create, stop and downloads (CLOUD_API), the default model (GATEWAY_URL) and web search. The cli_mcp.py line is text in a tool description.Yes, at run time, with the X-Browser-Use-API-Key headerYes: the vendor's API, which is the default path.
cloud.browser-use.combrowser_use/auth.py:12; browser_use/exceptions.py:12; browser_use/llm/__init__.py:30Links to API keys and billing printed in error hints. The login page is opened by browser-harness's login flow.Not by this package's codeYes: the vendor's dashboard.
docs.browser-use.com.github/ISSUE_TEMPLATE/1_element_detection_bug.yml:20; browser_use/cli.py:990; pyproject.toml:47Documentation links.NoYes.
browser-use.com.github/ISSUE_TEMPLATE/3_feature_request.yml:81; browser_use/skills/browser_use.py:76; context7.json:8Homepage links: the skill file's homepage line, and pricing in context7.json. browser_use/telemetry/stats.py:373 also compares a hostname with it without contacting it.NoYes.
example.com.evil.combrowser_use/domains.py:142A docstring example of a lookalike URL that the domain matcher refuses.NoYes: documents a guard.
pypi.orgbrowser_use/update_check.py:13; server.json:14; .github/ISSUE_TEMPLATE/1_element_detection_bug.yml:21The latest browser-use version, fetched with a 2 s timeout and cached for 24 h, plus the MCP registry entry and template links.Yes, at run time, only after a browser-attach error, not in CI, and opt-out with BROWSER_USE_NO_UPDATE_CHECKYes.
discord.gg.github/workflows/stale-bot.yml:50, :72, :82Invite link in the stale bot's comment text.NoYes.
link.browser-use.com.github/ISSUE_TEMPLATE/config.yml:7; .github/ISSUE_TEMPLATE/3_feature_request.yml:92Discord redirect link in issue templates.NoYes.
x.com.github/ISSUE_TEMPLATE/3_feature_request.yml:93The project's X profile link.NoYes.
site.combrowser_use/agent/service.py:301; browser_use/repl/session.py:96A placeholder in the sensitive_data error message and docstring.NoYes: an example.
astral.shbin/setup.sh:31Downloads the uv installer script and pipes it to sh.Yes, by a developer script not shipped in the wheelExpected for a setup script. The way it runs is a risk pattern (below).
context7.comcontext7.json:2The $schema URL of the Context7 manifest.NoYes.
developer.chrome.com.github/ISSUE_TEMPLATE/1_element_detection_bug.yml:49DevTools documentation link in a bug template.NoYes.
eu.i.posthog.combrowser_use/telemetry/service.py:35Anonymous telemetry, POSTed to /batch/ (POSTHOG_HOST) with a 3 s timeout.Yes, at run time. On by default, off with ANONYMIZED_TELEMETRY=falseYes, and documented in README, MIGRATING.md and .env.example.
news.ycombinator.combrowser_use/cli.py:968An example URL in the CLI help text.NoYes: an example.
static.modelcontextprotocol.ioserver.json:2The $schema URL of the MCP registry manifest.NoYes.

The other 134 distinct hosts are named in tests, comments or documentation, never contacted by package code. Most are fixtures for the domain matcher (tests/ci/test_domains.py), for the telemetry URL scrubber (tests/ci/test_telemetry.py, including tunnel and preview hosts) and for model endpoints (tests/ci/test_llm.py, tests/ci/test_browser.py), whose HTTP calls are mocked. A few are links in README.md and in the skill docs under skills/. Four (api.browser, api.te, cloud.brows, cloud.browser) are prefixes the scan cut out of longer names, not hosts.

Other hosts named in the repository 134 rows
HostClassFirst place
10.0.0.1Test fixture (private IP)tests/ci/test_domains.py:151
172.20.1.1Comment (private IP)tests/ci/test_browser.py:490
180.1.1.1Commenttests/ci/test_domains.py:150
192.168.1.1Test fixture (private IP)tests/ci/test_domains.py:150
192.168.1.20Test fixture (private IP)tests/ci/test_browser.py:488
8.8.8.8Test fixture (IP blocking)tests/ci/test_domains.py:150
8080-zquser-repo-ab12.ws-eu110.gitpod.ioTest fixture (URL scrubbing)tests/ci/test_telemetry.py:512
9.10.11.12Commenttests/ci/test_domains.py:152
a.comTest fixturetests/ci/test_compat.py:139
a.exampleTest fixturetests/ci/test_domains.py
a.example.comTest fixturetests/ci/test_domains.py
a.mail.example.comTest fixturetests/ci/test_domains.py
a.site.testTest fixturetests/ci/test_repl.py
ai.pydantic.devDocumentation linkREADME.md; MIGRATING.md:5; AGENTS.md:5; CLAUDE.md:5
allowed.example.comTest fixturetests/ci/test_domains.py
allowed.localhostTest fixturetests/ci/test_domains.py
amazon.comDocumentation link (skill docs)skills/cloud/references/features.md
anygoogle.comTest fixturetests/ci/test_domains.py:73
api.anthropic.comTest fixture (mocked provider)tests/ci/test_browser.py:295
api.browserTruncated scan artefactprefix of api.browser-use.com
api.deepseek.comTest fixture (mocked provider)tests/ci/test_llm.py:896
api.openai.comTest fixture (mocked provider)tests/ci/test_browser.py:290
api.openai.com.evil.testTest fixture (lookalike host)tests/ci/test_llm.py
api.teTruncated scan artefacttests/ci/test_browser.py:688
api.testTest fixturetests/ci/test_domains.py; tests/ci/test_browser.py
api.x.aiTest fixture (mocked provider)tests/ci/test_llm.py:1186
app.example.comTest fixturetests/ci/test_telemetry.py
bank.exampleTest fixturetests/ci/test_telemetry.py
basescan.orgDocumentation link (skill docs)skills/x402/SKILL.md
blocked.example.orgTest fixturetests/ci/test_harness_cloud.py
blocked0.comTest fixturetests/ci/test_domains.py:139
browsermerch.comDocumentation linkREADME.md:29
cdp.example.invalidTest fixturetests/ci/test_harness_cloud.py
chainlist.orgDocumentation link (skill docs)skills/x402/SKILL.md
cloud.browsTruncated scan artefactprefix of cloud.browser-use.com
cloud.browserTruncated scan artefactprefix of cloud.browser-use.com
connect.browser-use.comDocumentation link (skill docs)skills/cloud/SKILL.md; skills/cloud/references/browser-api.md
de.wikipedia.orgTest fixturetests/ci/test_domains.py:195
deploy-preview-42--zqsite.netlify.appTest fixture (URL scrubbing)tests/ci/test_telemetry.py:509
docs.astral.shComment (install hint text)browser_use/cli.py:312
docs.example.comTest fixturetests/ci/test_telemetry.py
docs.github.comComment.github/workflows/publish.yml:2
docs.google.comCommenttests/ci/test_telemetry.py:1302
en.wikipedia.orgTest fixturetests/ci/test_domains.py:184
evil.comTest fixturetests/ci/test_domains.py:228
evil.localhostTest fixturetests/ci/test_domains.py
evil.testTest fixturetests/ci/test_repl.py; tests/ci/test_domains.py
evilgood.comTest fixturetests/ci/test_domains.py:64
evilsite.testTest fixturetests/ci/test_repl.py
example.comDocumentation example and test fixture.github/ISSUE_TEMPLATE/1_element_detection_bug.yml:53; CLOUD.md:52; MIGRATING.md:191; tests/ci
example.computerCommenttests/ci/test_domains.py:221
example.invalidTest fixturetests/ci/test_repl.py; tests/ci/test_browser.py
example.orgDocumentation example and test fixtureREADME.md; browser_use/domains.py (docstring); tests/ci/test_domains.py
fass.deTest fixture (IDN)tests/ci/test_domains.py:202
files.exampleTest fixturetests/ci/test_browser.py
files.testTest fixturetests/ci/test_browser.py
generativelanguage.googleapis.comTest fixture (mocked provider); also the GOOGLE_HOST constanttests/ci/test_browser.py:276; browser_use/llm/__init__.py:36
github.devTest fixture (URL scrubbing)tests/ci/test_telemetry.py:517
good.testTest fixturetests/ci/test_domains.py
google.comTest fixturetests/ci/test_domains.py:63
html.duckduckgo.comDocumentation link (skill docs)skills/cloud/references/guides/tools-integration.md
httpbin.orgTest fixture (docstring of a mocked cloud test)tests/ci/test_browser.py:1354
img.shields.ioDocumentation linkREADME.md:299
intranet.exampleTest fixturetests/ci/test_telemetry.py
ipinfo.ioTest fixture (docstring)tests/ci/test_browser.py:1422
live.example.invalidTest fixturetests/ci/test_harness_cloud.py
live.example.testTest fixturetests/ci/test_browser.py
llm-proxy.example.testTest fixturetests/ci/test_browser.py
llm.staging.example.testTest fixturetests/ci/test_compat.py
localhostLocal address (hint text and test fixtures)browser_use/__init__.py:53; tests/ci/test_agent.py:363
mail.example.co.ukTest fixturetests/ci/test_domains.py:95
mail.example.comDocumentation example and test fixturebrowser_use/domains.py (docstring); MIGRATING.md; tests/ci/test_domains.py
mail.example.orgTest fixturetests/ci/test_domains.py
mail.google.comTest fixturetests/ci/test_domains.py:140
mainnet.base.orgDocumentation link (skill docs)skills/x402/SKILL.md
media.browser-use.toolsDocumentation link (README badges)README.md:17
metamask.ioDocumentation link (skill docs)skills/x402/SKILL.md
myapp-git-zq-branch-acme.vercel.appCommenttests/ci/test_telemetry.py:1282
myapp.vercel.appTest fixture (URL scrubbing)tests/ci/test_telemetry.py:515
mysite.netlify.appTest fixture (URL scrubbing)tests/ci/test_telemetry.py:516
notawiki.comTest fixturetests/ci/test_domains.py:79
notexample.comTest fixturetests/ci/test_domains.py:61
notwikipedia.orgCommenttests/ci/test_domains.py:189
ok.testTest fixturetests/ci/test_domains.py
openrouter.aiTest fixture (mocked provider)tests/ci/test_llm.py:1187
other.comTest fixturetests/ci/test_domains.py:166
pay.example.comTest fixturetests/ci/test_telemetry.py
proxy.testTest fixturetests/ci/test_llm.py
raw.githubusercontent.comTest fixture (asserted docs URL); README image linkstests/ci/test_browser_use_skill_install_docs.py:11; README.md:73
redsymbol.netCommentbin/setup.sh:7
server1.example.comTest fixturetests/ci/test_domains.py
shop.exampleTest fixturetests/ci/test_telemetry.py
shop.example.comTest fixturetests/ci/test_telemetry.py
site.testTest fixturetests/ci/test_repl.py; tests/ci/test_agent.py
site.test.evilTest fixture (lookalike host)tests/ci/test_repl.py:481
slack.comTest fixture (URL scrubbing)tests/ci/test_telemetry.py:1300
sub.example.comTest fixturetests/ci/test_domains.py
subdomain.example.comTest fixturetests/ci/test_domains.py
test.orgTest fixturetests/ci/test_domains.py:88
wiki.orgTest fixturetests/ci/test_domains.py:62
wikipedia.org.evil.comCommenttests/ci/test_domains.py:188
www.airbnb.comTest fixture (URL scrubbing)tests/ci/test_telemetry.py:1375
www.allowed0.comTest fixturetests/ci/test_domains.py:142
www.apple.comTest fixture (URL scrubbing)tests/ci/test_telemetry.py:1305
www.example.comDocumentation example and test fixturebrowser_use/domains.py (docstring); MIGRATING.md; tests/ci/test_domains.py
www.gnu.orgCommentbin/setup.sh:8
www.google.comTest fixture; a comment in package codetests/ci/test_domains.py:63; browser_use/browser/local.py:255
www.google.evil.comTest fixturetests/ci/test_domains.py:83
www.iana.orgTest fixturetests/ci/test_harness_cloud.py:181
www.mail.example.comTest fixturetests/ci/test_domains.py
www.test.comTest fixturetests/ci/test_domains.py:74
www.x402.orgDocumentation link (skill docs)skills/x402/SKILL.md
www.xn--bcher-kva.deTest fixture (IDN)tests/ci/test_domains.py:204
www.zillow.comTest fixture (URL scrubbing)tests/ci/test_telemetry.py:1372
x.testTest fixturetests/ci/test_browser.py; tests/ci/test_telemetry.py; tests/ci/test_compat.py
x402.api.browser-use.comDocumentation link (skill docs)skills/x402/SKILL.md
xn--fa-hia.deTest fixture (IDN)tests/ci/test_domains.py:201
xn--mnchen-3ya.deTest fixture (IDN)tests/ci/test_domains.py:250
xn--mnchen-3ya.de.evilTest fixture (lookalike IDN)tests/ci/test_domains.py:251
zq-nowhere.invalidTest fixturetests/ci/test_telemetry.py
zq-quiet-river.trycloudflare.comTest fixture (URL scrubbing)tests/ci/test_telemetry.py:501
zq-tidy-cat.loca.ltTest fixture (URL scrubbing)tests/ci/test_telemetry.py:505
zq-user-repo-5x7-3000.app.github.devTest fixture (URL scrubbing)tests/ci/test_telemetry.py:511
zq-user-repo-5x7.github.devTest fixture (URL scrubbing)tests/ci/test_telemetry.py:510
zq1a2b3c.ngrok-free.appTest fixture (URL scrubbing)tests/ci/test_telemetry.py:502
zq1a2b3c.ngrok.appTest fixture (URL scrubbing)tests/ci/test_telemetry.py:504
zq1a2b3c.ngrok.ioTest fixture (URL scrubbing)tests/ci/test_telemetry.py:503
zq4f9k2.csb.appTest fixture (URL scrubbing)tests/ci/test_telemetry.py:514
zq9.testTest fixturetests/ci/test_telemetry.py
zqabc123def.lambda-url.us-east-1.on.awsTest fixture (URL scrubbing)tests/ci/test_telemetry.py:506
zqapp.zquser.repl.coTest fixture (URL scrubbing)tests/ci/test_telemetry.py:513
zqshop-git-fix-login-acme.vercel.appTest fixture (URL scrubbing)tests/ci/test_telemetry.py:508
zqshop-k3j2h1g0f-acme.vercel.appTest fixture (URL scrubbing)tests/ci/test_telemetry.py:507
zqtenant.internal.exampleTest fixturetests/ci/test_telemetry.py

Install hooks: none. No package lifecycle script runs on install. The wheel is built by hatchling (pinned at 1.32.0 in pyproject.toml), with no setup.py and no post-install step.

Lines that match a risk pattern: 11, of which 10 are in tests. Only one, bin/setup.sh:31, actually runs anything from the network. It is a contributor's convenience script, not shipped in the wheel, and it is a supply-chain exposure for whoever runs it. The rest are test inputs that open no connection.

PatternWhereVerdict
Remote script piped to a shellbin/setup.sh:31A finding, minor: curl -LsSf https://astral.sh/uv/install.sh | sh installs uv by running a remote script unpinned and unverified. It is a developer setup script, not in the wheel or the Docker image, but a contributor who runs it trusts astral.sh's server at that moment.
Download at run time from raw source hostingtests/ci/test_browser_use_skill_install_docs.py:11Benign: a constant (BROWSER_USE_REPO_SKILL_URL) that a docs test compares with the install instructions. Nothing is downloaded.
Download at run time from raw source hostingtests/ci/test_browser_use_skill_install_docs.py:75Benign: an assertion that the README no longer points at browser-harness's raw SKILL.md. Nothing is downloaded.
Raw public IP addresstests/ci/test_domains.py:167Benign: 8.8.8.8 is an input that checks block_ips refuses a public IP. The domain matcher is called directly, and no connection is made.
Raw public IP addresstests/ci/test_domains.py:169Benign: the same address as an input to prohibited_domains matching. No connection is made.
Paste, tunnel, webhook or file-drop hosttests/ci/test_telemetry.py:501Benign: a made-up trycloudflare.com URL that checks telemetry scrubs a tunnel host down to *.trycloudflare.com.
Paste, tunnel, webhook or file-drop hosttests/ci/test_telemetry.py:502Benign: the same scrubbing check for *.ngrok-free.app.
Paste, tunnel, webhook or file-drop hosttests/ci/test_telemetry.py:503Benign: the same scrubbing check for *.ngrok.io.
Paste, tunnel, webhook or file-drop hosttests/ci/test_telemetry.py:504Benign: the same scrubbing check for *.ngrok.app.
Paste, tunnel, webhook or file-drop hosttests/ci/test_telemetry.py:1280Benign: checks that a tunnel URL inside an error message is scrubbed, and its port dropped, before it is sent.
Paste, tunnel, webhook or file-drop hosttests/ci/test_telemetry.py:1388Benign: checks that a tunnel URL loses its query string and host label in telemetry.

Functions named in this section

FunctionWhereWhat it does
urlopen_keyedbrowser_use/utils.py:96Opens a urllib request that carries an API key through an opener that refuses redirects. A redirect raises instead of passing the key to another origin.

13. Error handling and resilience

The exception strategy splits a run into two halves. Before the browser is billed, problems in the caller's setup raise: MissingAPIKeyError, BrowserConfigError (a profile name that matches none) and the TypeError that names a 0.x option 1.0 cannot honour all leave Agent.run before any browser starts. Once the run is under way, failures return. loop.run is documented as "Never raises for agent/provider failures": it catches the run budget's TimeoutError and every other exception and returns an AgentHistoryList whose status is one of completed, max_steps, timeout or error, carrying partial results from the model's last checkpoint(..., partial=True), read back by Session.partial, or the model's last text when there is none (browser_use/agent/loop.py:1276-1336). A preflight failure (a dead gateway, a rejected key, an unknown model, a missing search endpoint) and a failed cloud create return the same shape through Agent._failed: status error, no steps, and no browser left running (browser_use/agent/service.py:486-513, 622-627).

Two things are best effort by design and never decide the outcome. The judge never fails a run: judge_run catches a provider error, an answer that does not fit its schema and its own 180 s timeout, logs the class and HTTP status only, and leaves result.judgement as None (browser_use/agent/judge.py:166-180). Telemetry and cleanup are wrapped so that they cannot break a run ("telemetry never breaks a run", browser_use/agent/service.py:794, 952), and the shutdown path runs in nested finally blocks so the browser stops and the telemetry event is captured even after a cancellation; the judge runs only when the run itself raised nothing.

Timeouts

Every boundary has a deadline, and the timeouts nest. The delivery-only turn starts at timeout minus max(10% of the timeout, min(30 s, half the timeout)), or when the step count reaches max_steps, or after the browser is gone (budget_hit: max_steps | timeout | browser_gone), and every per-request and per-cell deadline is clipped so it never runs past that point (_deadlines, and the cell budget in python). The table lists the sixteen deadlines the code sets.

Deadlines 16 rows
DeadlineValueSet atWhat happens when it expires
Agent run (the agent loop; browser start and stop not counted)1700 sbrowser_use/agent/service.py:443, browser_use/agent/loop.py:1292The budget's TimeoutError becomes status timeout with the partial result; the delivery-only turn has already run before it.
REPL cell (Session.cell_timeout_s)120 sbrowser_use/agent/loop.py:129The worker's process tree is killed and restarted; the model gets the cell's output so far and "Actions may already have happened; inspect before retrying".
One model request (MODEL_TIMEOUT_S)300 sbrowser_use/agent/loop.py:110A ModelRequestTimeout becomes a new request step (ModelRetry), or the delivery turn when its time has come.
A streamed request in all (STREAM_TIMEOUT_S)930 sbrowser_use/agent/loop.py:115300 s to the first event, then up to the gateway's 15 minute stream limit plus 30 s, so the gateway's own end arrives first.
Judge (JUDGE_TIMEOUT_S)180 sbrowser_use/agent/judge.py:54Logged; result.judgement stays None and the run's status is unchanged.
Final screenshot for the judge10 sbrowser_use/agent/judge.py:53The judge goes without the final page.
Cloud browser create (CREATE_TIMEOUT_S)120 sbrowser_use/browser/browser.py:199The browser start fails and the run returns status error; a browser the API creates later is stopped.
Downloads before a stop (DOWNLOADS_TIMEOUT_S)300 sbrowser_use/browser/browser.py:201A slow download is abandoned, so it never holds the billing longer; the loss is logged.
Downloads of a cancelled run (CANCEL_DOWNLOADS_TIMEOUT_S)10 sbrowser_use/browser/browser.py:202All copy passes share it; a file still copying goes to the next run or to the browser's own stop.
Web search, total (SEARCH_TIMEOUT_S)25 sbrowser_use/search.py:22The cell's search call raises "Search failed: timed out", under the 120 s cell deadline, so the call fails and the cell does not.
Preflight (PREFLIGHT_TIMEOUT_S)15 sbrowser_use/llm/__init__.py:35An unreachable official provider counts as "cannot be told" and the run goes on; an unreachable gateway, a rejected key or an unknown model returns status error before any browser starts.
Telemetry send (SEND_TIMEOUT_S)3 sbrowser_use/telemetry/service.py:36The event goes to the outbox for a later process to send.
Update check (TIMEOUT_SECONDS)2 sbrowser_use/update_check.py:16No hint is shown; a failed lookup is not retried for an hour.
Local Chrome start (START_TIMEOUT_S)30 sbrowser_use/browser/local.py:26RuntimeError: the binary "did not open its DevTools port"; the run returns status error.
Browser('chrome') start plus the user clicking Allow (LOCAL_START_WAIT_S)120 sbrowser_use/browser/browser.py:200The start fails and the run returns status error.
REPL worker start (connect, then the init reply)60 sbrowser_use/repl/session.py:423, browser_use/repl/session.py:432"REPL worker failed to start; see worker.log"; the half-started worker is killed first.

Retries

Retries are counted, not stacked. The provider retry is skipped wherever the provider's SDK has already retried the same request, and its wait is capped so it never runs into the delivery turn.

RetryWhereBoundWhat it repeats
One transient provider retry per runbrowser_use/agent/loop.py:453-485Once per run, after the provider's Retry-After capped at 60 s and never past the delivery turnThe same model request after a rate limit, overload, 5xx, dropped connection or a failure inside an HTTP 200 (server_error, overloaded, request_timeout). Only inference is repeated: a failed request returned no tool calls.
SDK retriesbrowser_use/agent/loop.py:1151-1154OpenAI and Anthropic SDKs: max_retries=2 with backoff; Google models get max_retries=2An HTTP error before the response stream opens. When the SDK retried, the provider retry above is not spent.
Model request timeout becomes a new requestbrowser_use/agent/loop.py:463-466Each one costs a step (bounded by max_steps and the run budget)The request that got no answer within its deadline, as a ModelRetry, so the run moves to the delivery turn when its time has come.
Tool and output retriesbrowser_use/tools.py:34, browser_use/agent/loop.py:1180-1189TOOL_RETRIES = 1,000,000, bounded in practice by max_stepsA failed tool call, an unknown tool name or a rejected delivery goes back to the model as a retry message, as bu-pi does, instead of ending the run at Pydantic AI's default cap.
One delivery repair turnbrowser_use/agent/loop.py:92-95, browser_use/agent/loop.py:246, browser_use/agent/loop.py:371Once per runA delivery with a placeholder or links to files never written is refused once and the model asked for the real result (check_delivery); a structured result sent as plain text gets one delivery-only repair turn (on_text). Section 7 tables both transitions.
Daemon reattach after BrowserConnectionLostbrowser_use/repl/session.py:465-481Once per failed cellStarts the browser-harness daemon again on the same browser and tells the model to check the page and retry; when that fails the next turn is delivery-only (browser_gone).
Telemetry outbox resend by a later processbrowser_use/telemetry/service.py:439-500Outbox capped at 20 files, 512 KiB and 7 daysAn event that could not be sent within 3 s, claimed as .sending so two processes do not send it twice.
A gone cloud browser replaced at the next keep_alive startbrowser_use/browser/browser.py:695-724At the start of the next run only; mid-run it raisesA kept-alive cloud browser that ended between runs (cloud_timeout, a stop from the dashboard) is replaced by a new one, as a dead local Chrome is relaunched.

One further fallback is not a retry of the same thing: when a text-only model rejects the judge's screenshots with a 4xx, the judge asks once more with the trace alone (browser_use/agent/judge.py:171-175).

Idempotency

The idempotency rule is simple: cells are never retried. A cell that times out or loses its worker returns an error, the worker restarts with files and browser state intact and Python variables lost, and the model is told "Actions may already have happened; inspect before retrying" (browser_use/repl/session.py:553-565). The decision to repeat an action belongs to the model, after it has looked at the page. Nothing else the library repeats has a side effect outside this machine except the provider retry (inference only) and the telemetry resend (deduplicated by claiming the file).

Dead letters and failure isolation

There are no dead letters beyond the telemetry outbox. Failure isolation is by process: model-written Python runs in a worker in its own process group (a job object on Windows), so a hung or crashed cell kills that tree and not the run, and kill_workers runs at exit and on SIGTERM and SIGHUP before browsers are stopped, so no orphaned worker keeps driving a browser. Custom 0.x Tools that raise return their error to the model through BrowserLoop.on_tool_execute_error rather than ending the run.

What is swallowed and what surfaces

The evidence counts 39 empty or comment-only error handlers. Of the ten it names, eight are in browser_use/ax.py, where an optional CDP step around an action (scroll into view, release a remote object, pump pending events) fails without failing the action; one is the telemetry capture in browser_use/auth.py:28; and one is the running-loop probe in Agent.run_sync (browser_use/agent/service.py:636), where the exception is the expected answer. The evidence does not name the other 29; a scan of the source finds them in the same kinds of place: cleanup of a local Chrome and the watchdog, telemetry, the update-check cache, and optional imports or CDP steps, each a best-effort path. What surfaces to the user is the run's status and error (redacted), one ERROR log line for a failed run, and WARNING lines for a provider retry, a model timeout, a failed compaction and a failed judge (section 16 lists every log signal).

Functions named in this section

Functions 22 rows
FunctionWhereWhat it does
Agent.runbrowser_use/agent/service.py:443The public async entry: runs the task with max_steps=100 and timeout=1700 s by default and returns an AgentHistoryList. Unsupported 0.x keyword arguments raise a TypeError naming them.
Agent.run_syncbrowser_use/agent/service.py:629The same run without async, on one event loop kept for the REPL's lifetime. It refuses to run inside an already running event loop.
Agent._runbrowser_use/agent/service.py:466One run end to end: preflight, browser start, REPL, agent loop, then shutdown, judge and telemetry in finally blocks. Setup errors re-raise; a failed preflight or browser start returns status error.
Agent._failedbrowser_use/agent/service.py:622Builds the result of a run that failed before the agent loop: status error, no steps, the error redacted and logged.
Agent._judgebrowser_use/agent/service.py:600Runs the judge on a run that took steps and adds its tokens and cost to the result. A failure leaves result.judgement as None.
judge_runbrowser_use/agent/judge.py:133Sends one low-effort request to the run's own model with the redacted trace and screenshots, under a 180 s timeout. Returns None and the messages when anything fails.
provider_preflightbrowser_use/llm/__init__.py:439One free GET of the model on OpenAI, Anthropic or Google, so a rejected key or unknown model fails before a cloud browser is billed. Returns the error line, or None when the model is there or it cannot be told.
loop.runbrowser_use/agent/loop.py:1276Runs one task under the run budget and maps every agent or provider failure to a status instead of raising. Fills in the partial result, usage and cost.
Session.partialbrowser_use/agent/loop.py:159Reads the last checkpoint(..., partial=True) value from partial.json with secrets redacted. Returns None when it is missing or unreadable, so recovery data never turns a timeout into a crash.
checkpointbrowser_use/repl/worker.py:742The REPL helper the model calls to write a value to a file in the workspace. With partial=True it also records the value as the run's partial result.
pythonbrowser_use/agent/loop.py:168The model's one tool: runs a cell in the REPL with a deadline clipped to the time left before the delivery turn. Logs one INFO line per step and marks the run browser_gone when the browser could not be reattached.
_deadlinesbrowser_use/agent/loop.py:691Sets request_timeout and, for streamed Responses requests, first_event_timeout on a model request. Both are capped by the time left before the delivery turn.
BrowserLoop.on_model_request_errorbrowser_use/agent/loop.py:453Turns a model request timeout into a new request, and retries one transient provider error per run after Retry-After capped at 60 s. Skips the retry where the SDK already retried.
BrowserLoop.on_tool_execute_errorbrowser_use/agent/loop.py:494Returns a custom tool's exception to the model as an ActionResult error so the model can recover. Errors from python and framework control flow pass through.
Repl.startbrowser_use/repl/session.py:348Starts the REPL worker process in a fresh context and times the start for telemetry. The start waits up to 60 s for the worker to connect and answer.
Repl.callbrowser_use/repl/session.py:460Runs one cell under the REPL's lock and, on BrowserConnectionLost, reattaches the daemon and appends what happened to the error. Redacts secrets from the output, error and value.
Repl._callbrowser_use/repl/session.py:524Sends a cell to the worker and waits for its answer under the cell deadline, serving the worker's search, downloads and feedback requests meanwhile. On a timeout or worker exit it kills the worker and returns a restart error.
kill_workersbrowser_use/repl/session.py:254Kills every live REPL worker's process tree. Run by the atexit, SIGTERM and SIGHUP cleanup so workers die before browsers stop.
Browser._start_lockedbrowser_use/browser/browser.py:701Starts or reuses the browser and its daemon under the Browser's lock. With replace_gone_cloud a kept-alive cloud browser that ended between runs is replaced.
Browser.reattachbrowser_use/browser/browser.py:770Starts the browser-harness daemon again on the same browser after a crash or lost connection. Raises when the browser itself is gone.
ProductTelemetry._to_outboxbrowser_use/telemetry/service.py:439Writes an unsent event to the outbox, deleting the oldest files first when it holds 20 files or 512 KiB.
ProductTelemetry._send_outboxbrowser_use/telemetry/service.py:482Sends the outbox's queued events, oldest first, claiming each file as .sending so another process does not send it too. A failed send puts the file back.

Error handling and resilience rating

Error handling and resilience: 8/10, Good

Good. Every boundary has a deadline, the one provider retry per run honours Retry-After up to 60 s without running into the delivery turn, and SDK retries are counted so the two do not stack. A hung cell kills and restarts the worker with files intact and the model told actions may already have happened, and a delivery-only turn with partial results means a timeout still returns an answer, because loop.run returns a status instead of raising. The gaps are local: 39 empty handlers, most of them commented best-effort paths, and a TOOL_RETRIES of 1,000,000 bounded only by max_steps. The technical assessment gives the reasoning per criterion.

14. Availability and recovery

A library has no HA topology of its own: browser-use runs inside the caller's process on one machine, with no replicas, load balancer or failover, and its availability is that of the caller's process plus the services it calls.

Single points of failure

Five components each stop a run when they fail. The first two are outside the repository; the other three are processes the library starts and therefore recovers itself. On the default path the model (bu-4.0 on the Browser Use LLM gateway https://api.browser-use.com/api/v4/llm/v1), the cloud browser and web search all sit on one host, so that host is the largest single point of failure.

Single point of failureWhat failsHow it is detectedHow it recovers
Browser Use Cloud APIapi.browser-use.com carries the default model, cloud browsers and search. Down, every default run fails: no model, no browser, no web search.Before anything is billed, the run preflights the gateway (one free GET /models, 15 s); a cloud create that does not answer in 120 s fails the start; a search past its 25 s deadline returns an error to the cell.No automatic fallback. The run returns status error without starting a browser; the caller's only alternative is a local browser ('chromium' or 'chrome') with their own provider key. A cloud browser that cannot be stopped stays registered and its stop is retried at exit; the server stops it after cloud_timeout minutes (60 by default) regardless.
LLM providerOpenAI, Anthropic, Google or a compatible server, when the caller chose one instead of the gateway. Down or rejecting the key, no step can be taken.Preflight before billing (a free GET of the model on the official endpoints); mid-run, each model request has a 300 s deadline (930 s streamed) and provider errors surface in the loop.One transient provider error per run is retried, after the provider's Retry-After capped at 60 s and never past the delivery turn; past that the run ends with status error and returns any partial result the model checkpointed.
browser-harness daemon (one per Browser)The process between the worker and Chrome. If it crashes or loses its browser connection, cells fail with BrowserConnectionLost.The error type on the cell's result; a daemon that answers but whose browser connection is stuck is found by a health check.The REPL reattaches: a stuck daemon is killed (never shut down, which would stop a cloud browser) and started again on the same browser, and the model is told to check the page state and retry. If reattaching fails the run is told the browser is gone and its next turn is delivery-only.
REPL worker process (one per Agent)The child that runs model-written Python. A hung cell or a worker crash loses the Python variables.The 120 s cell deadline, or the worker's socket closing.Kill and restart: the worker's whole process tree is killed, the cell returns a CellTimeout or WorkerExited error with "Actions may already have happened; inspect before retrying", and the next cell starts a new worker. Files in the workspace survive. A worker whose parent dies exits on its own.
local Chrome processA Chrome or Chromium the Browser launched ('chromium', or 'chrome' with a profile copy), or the user's own Chrome. A crash, OOM or kill takes the tabs, logins and page state with it.The launched process has exited when the next start or reattach checks it; a lost CDP connection surfaces as BrowserConnectionLost.A dead launched Chrome is relaunched on the next start, and the worker is restarted against it (variables lost, files kept). The user's own Chrome is not the library's to restart. A kept-alive cloud browser that ended between runs is replaced by a new one at the next start.

Cleanup is designed so a failure of the caller's process does not leave billed or running resources behind. On normal exit, SIGTERM and SIGHUP, the library first kills every live REPL worker (so no agent code keeps acting on a browser) and then stops each live browser. A watchdog process runs detached next to each Browser's daemon: when the owning process dies however it dies, it stops the cloud browser, ends the daemon and removes a launched Chrome and its temp profile. The REPL worker watches its parent and exits when the parent dies.

Functions that detect and recover failures 16 rows
FunctionWhereWhat it does
ChatBrowserUse.preflightbrowser_use/llm/__init__.py:228Lists the gateway's models with one free GET (15 s limit) before a browser is created; returns an error line for a missing gateway, a rejected key or an unlisted model.
provider_preflightbrowser_use/llm/__init__.py:439One free GET of the model on OpenAI, Anthropic or Google official endpoints, so a rejected key or unknown model fails before a cloud browser is billed. Returns None when it cannot tell.
Repl.callbrowser_use/repl/session.py:460Runs one cell under the REPL lock; on BrowserConnectionLost it asks the Browser to reattach and tells the model whether the browser is the same, new, or gone.
Repl._callbrowser_use/repl/session.py:524Sends a cell to the worker (starting it if needed) and waits up to the cell deadline; on a timeout or worker exit it kills the worker and returns the output so far with a restart notice.
kill_workersbrowser_use/repl/session.py:254Kills every live REPL worker and the processes its cells started; used at exit and on SIGTERM and SIGHUP.
_watch_parentbrowser_use/repl/worker.py:1088In the worker, waits for the parent process to die and then exits, taking the worker's process group (or Windows job) with it.
Browser.startbrowser_use/browser/browser.py:695Attaches a browser-harness daemon under the Browser's lock, allowing a gone kept-alive cloud browser to be replaced. Idempotent while started.
Browser._start_lockedbrowser_use/browser/browser.py:701Starts the browser, or relaunches a launched Chrome that died, or reattaches a daemon, replacing a cloud browser that ended between runs.
Browser.reattachbrowser_use/browser/browser.py:770Called by the REPL after a lost connection: restarts the daemon on the same browser, or relaunches a launched Chrome that died, and returns the worker's environment. It raises when the Browser was stopped meanwhile, and mid-run never replaces a gone cloud browser.
Browser._reattachbrowser_use/browser/browser.py:782Leaves a healthy daemon alone, kills a stuck one and starts the daemon again on the same browser; raises "the browser is gone" when that fails.
Browser._start_cloudbrowser_use/browser/browser.py:969Creates a cloud browser from a thread pool with a 120 s total deadline; a browser that lands after the deadline is stopped.
Browser._stop_nowbrowser_use/browser/browser.py:1030Stops the daemon, a launched Chrome and the cloud browser, retrying the cloud stop three times; a browser it cannot stop stays registered so exit retries.
_stop_allbrowser_use/browser/browser.py:487Kills every REPL worker first, then stops every live Browser; the atexit and signal handler.
_on_signalbrowser_use/browser/browser.py:495On SIGTERM or SIGHUP runs the cleanup, restores the default handler and re-sends the signal so the process still ends.
_install_cleanupbrowser_use/browser/browser.py:501Registers the cleanup with atexit and for SIGTERM and SIGHUP on the main thread, leaving a handler the application already set alone.
start_watchdogbrowser_use/browser/local.py:548Starts a detached watchdog that, when the owning process dies, stops the cloud browser, ends the daemon and removes a launched Chrome and its temp profile.

Backup and restore

Nothing to back up beyond the user's own workspace, and no backup or restore procedure is written anywhere in the repository. The persistent files are listed in section 11; losing the config dir only resets the anonymous device id and the update-check cache, and losing the auth store means running browser-use login again. A cloud profile lives in Browser Use Cloud and is not backed up from here.

RTO and RPO

Not stated anywhere: no recovery time or recovery point objective appears in the code, README, MIGRATING.md or the workflows. Within one run the design bounds loss instead: a run that times out still returns its delivery-turn answer or the last partial checkpoint.

Deployment safety

Releases are pinned versions on PyPI and tagged images on Docker Hub and GHCR, so rollback is installing or pulling the previous version; nothing in the repository yanks a release or moves a tag back. Publishing needs the protected 'release' environment with required reviewers (section 10), runs the non-chrome tests and a wheel smoke test first, and images are smoke-tested on both architectures before they are pushed.

Disaster recovery

None in the repository. There is no second region, account or alternative endpoint for Browser Use Cloud; ChatBrowserUse(base_url=...) can point the model at another gateway (the 0.x BROWSER_USE_LLM_URL only warns), but nothing switches to it automatically, and the cloud browser API base is a constant. Failure is detected only by the caller reading the run's status, and by Browser Use in aggregate through telemetry when it is on; there is no alerting (section 16).

Availability and recovery rating

Availability and recovery: 6/10, Fair

Fair. The processes the library owns recover on purpose: the worker restarts, the daemon reattaches, a dead local Chrome is relaunched, a gone cloud browser is replaced on a keep_alive start, a watchdog stops a cloud browser when the owning process dies, and atexit and SIGTERM cleanup stops workers before browsers. The gaps a reader can name are that the default path puts the model, the browser and search on one host (api.browser-use.com), so a gateway outage stops every default run with only a local browser and the user's own model as a fallback, and that no RTO, RPO, backup or disaster recovery is stated. The technical assessment gives the reasoning per criterion.

15. Performance and scale

A run's wall time is spent almost entirely outside this package: in the model provider, in Chrome and in Browser Use Cloud. The library's own work (serialising history, redaction, piping cell output) is small next to a model request that may take minutes. So the design effort goes into making each of those external waits shorter or cheaper (keeping the provider's prompt cache warm, sending fewer images, compacting history only when it is due) and into running many Agents side by side in one process.

Hot paths

Hot pathWhereWhat dominates its timeWhat the design does about it
model requestbrowser_use/agent/loop.py:1097-1189, browser_use/agent/loop.py:691Provider inference and prompt size: every step resends the whole history, screenshots included. One request may take up to 300 s, a streamed one up to 930 s.Prompt caching kept warm (Anthropic cache on, images pruned in batches so the cached prefix stays byte-identical), store=False on Responses (a stored response came back 170 to 320 ms later to first byte, per the comment).
cell executionbrowser_use/agent/loop.py:168, browser_use/repl/session.py:524The model's Python driving Chrome through the browser-harness daemon over CDP: page loads, waits and clicks. Bounded by the 120 s cell deadline; each CDP call waits up to 20 s (CDP_TIMEOUT_S).One persistent worker per Agent, so imports and the daemon connection are paid once; output cut to 12,000 characters in the worker so a huge print never crosses the channel.
screenshot capturebrowser_use/repl/capture.py:11Page.captureScreenshot in Chrome, up to 60 s (SCREENSHOT_TIMEOUT_S) because cloud screenshots routinely take longer; a hidden tab gets a 10 s first try before it is activated. Each image then adds input tokens to every later request until pruned.Hidden-tab fallback so a headless background tab cannot hang the capture; images pruned to the newest 2 once more than 20 tool results carry one; use_vision=False sends none.
context compactionbrowser_use/agent/loop.py:702-808A summarisation request to the same model at low effort (client-side), or the provider compacting server-side (OpenAI Responses). Either is a full extra model round trip.Requested only when due: server-side once the last request passed min(150,000 tokens, 65% of the context window), because sending context_management on every request made each call about 0.8 s slower at 45k tokens; client-side past 75% of the character budget or 65% of the window.
cloud browser startbrowser_use/browser/browser.py:969-990POST /browsers to Browser Use Cloud, then the CDP websocket lookup and the daemon attach. Up to 120 s for the create alone.The create runs on the browser-use-cloud thread pool so the caller's event loop stays free; a keep_alive browser is reused across runs and skips the start.

Concurrency model

The library is asyncio in the caller's event loop: Agent.run is a coroutine, and many Agents can run concurrently as tasks in one process. Each Agent owns one REPL worker process (about 35 MB, per the comment at browser_use/repl/session.py:414) and one browser-harness daemon for its browser. Within an Agent, cells run one at a time: Repl.call holds Repl.lock, and the python tool is registered with sequential=True, so parallel tool calls in one model response run one after another, each timed from its own start. Blocking HTTP never runs on the event loop: preflight, search, cloud API calls and screenshots for the judge go through asyncio.to_thread, and the cloud create goes to the browser-use-cloud thread pool. Telemetry sends on its own background thread. Before the first socket, raise_fd_limit lifts the open-file soft limit toward FD_LIMIT = 10,240, for many concurrent Agents in one process.

Caching

Four caches, all aimed at a cost the run would otherwise pay again. The Anthropic prompt cache is turned on, because Anthropic caches nothing unless asked and every request otherwise re-billed the whole prompt (browser_use/agent/loop.py:1155-1161). On OpenAI Responses, store=False keeps responses off the provider's store; nothing reads them back, since reasoning and compaction items round-trip encrypted (browser_use/agent/loop.py:1119-1122). Images are pruned in batches rather than one at a time: _prune_images returns nothing until the threshold is crossed, so the history and the provider's cached prefix stay byte-identical between prunes. The PyPI update check is cached for 24 hours in the config dir (an offline failure for one hour), and get_browser_use_version is memoised for the process.

Known limits

LimitValueSet atWhen it bites
PRUNE_IMAGES_AT / KEEP_IMAGE_RESULTS20 / 2browser_use/agent/loop.py:85-86On a long visual run, once more than 20 tool results carry a screenshot: all but the newest 2 become "[older screenshot removed]", so the model cannot look back at older pages.
Server-side compaction thresholdmin(150,000 tokens, 65% of the window)browser_use/agent/loop.py:713On a long run, or on a small-window model (gpt-4o's 128k window rejected every request before a fixed 150k was reached).
MAX_OUTPUT_CHARS12,000browser_use/repl/session.py:42A cell that prints more: the model sees the first 12,000 characters and the path of the full output file.
STREAM_LIMIT256 MiBbrowser_use/repl/session.py:41A single line on the parent-worker channel (a cell's answer with its images) over 256 MiB.
FD_LIMIT10,240browser_use/utils.py:15Thousands of concurrent Agents in one process, at about 3 open files each; on a hard limit below it, sooner.
Telemetry MAX_BYTES64 KiBbrowser_use/telemetry/service.py:37A run with many steps: the per-step arrays and maps are shrunk level by level until the event fits.
max_tokens on Responses reasoning models32,768browser_use/agent/loop.py:1126A single model response (reasoning plus output) longer than that is cut off.
Browser Use Cloud concurrency10 to 1,000 sessions per projectCLOUD.md:23Agents and browsers share one project limit, rising with lifetime payments; Enterprise above 1,000. A cloud run past it cannot get a browser.

The pruning threshold is exclusive: _prune_images returns early while the count is at most PRUNE_IMAGES_AT (browser_use/agent/loop.py:1039), and its docstring says "Once more than PRUNE_IMAGES_AT tool results carry images", so the 21st screenshot-bearing result is the first to trigger a prune.

Load evidence

There is no load test in the repository. The load evidence is the README's benchmark chart (Browser Use Benchmark v2, a 60-task subset of BU Bench V2, mean rubric score and cost per task by model, README.md:184-188) and the BU Bench run figures quoted in code comments as the reason for a setting (for example the image pruning and compaction thresholds, and the sequential=True tool). Those measure task success and cost per task, not throughput, so no stated load level says how many concurrent Agents one host sustains.

Functions named in this section

FunctionWhereWhat it does
Agent.runbrowser_use/agent/service.py:443The public async entry: runs the task with max_steps=100 and timeout=1700 s by default and returns an AgentHistoryList. Many can run concurrently as tasks in one event loop.
pythonbrowser_use/agent/loop.py:168The model's one tool: runs a cell in the REPL with a deadline clipped to the time left before the delivery turn. Registered with sequential=True, so one response's calls run one after another.
Repl.callbrowser_use/repl/session.py:460Runs one cell under the REPL's lock, so a worker runs one cell at a time. Reattaches the daemon on a lost browser connection and redacts secrets from the answer.
capturebrowser_use/repl/capture.py:11Takes a screenshot with Page.captureScreenshot, giving a hidden tab a short first try before activating it. Keeps a background tab of a headless browser from hanging the capture.
_prune_imagesbrowser_use/agent/loop.py:1030Once more than 20 tool results carry images, replaces the images in all but the newest 2 with a note. Returns None when nothing changes, so the cached prompt prefix is untouched.
LazyCompaction.get_model_settingsbrowser_use/agent/loop.py:708Asks the provider for server-side compaction only when the last request's input passed min(150,000 tokens, 65% of the window). Leaves a caller's own context management setting alone.
Compaction._duebrowser_use/agent/loop.py:791Decides whether client-side compaction runs before this request: past 75% of the character budget or 65% of the context window in tokens, or at the caller's token threshold.
build_agentbrowser_use/agent/loop.py:1097Builds the Pydantic AI agent with per-provider settings: store=False and max_tokens 32,768 on Responses, the Anthropic cache, Google retries, and the compaction capabilities. Registers python as the sequential tool.
Browser._start_cloudbrowser_use/browser/browser.py:969Submits the cloud create to the browser-use-cloud thread pool and waits up to 120 s for it. Then resolves the CDP websocket URL off the event loop.
Browser._createbrowser_use/browser/browser.py:983POSTs /browsers to Browser Use Cloud from a pool thread and records the id, live URL and CDP URL. Recording from its own thread lets a cancelled start still stop the browser.
raise_fd_limitbrowser_use/utils.py:102Raises the soft open-file limit toward 10,240 or the hard limit, whichever is lower. Never lowers a limit and does nothing on Windows.
get_browser_use_versionbrowser_use/utils.py:131Returns the installed browser-use version, or "unknown". Memoised with functools.cache for the life of the process.

Performance and scale rating

Performance and scale: 7/10, Good

Good. The hot paths are designed for: screenshots pruned in batches so the provider's prompt cache survives, server-side compaction at min(150,000 tokens, 65% of the window), Anthropic prompt caching on, cell output capped at 12,000 characters, blocking HTTP moved to threads, and the open-file limit raised to 10,240 for many concurrent Agents. The gaps are that each Agent costs a worker process of about 35 MB and a daemon, cells run one at a time per Agent, and there is no load test: the only load evidence is the README benchmark and BU Bench figures quoted in comments. The technical assessment gives the reasoning per criterion.

16. Observability

browser-use is a library that runs inside someone else's process, so its observability is designed to hand signals to that process rather than to run a pipeline of its own. It writes log lines to the caller's stderr, returns a result object that says how the run ended, and leaves tracing to the caller to switch on. Separately, anonymous product telemetry tells the vendor, Browser Use, how runs go in aggregate. Of the six signals the evidence probes for, two are present and four are absent. The table reproduces the evidence's signal table in full, one row per signal, with where each present signal goes and what it covers.

SignalPresentMatchesFilesWhere it goesWhat it covers
Loggingyes10022The browser_use logger (logging.getLogger('browser_use')), to the caller's stderr through one handler that setup_logging installs on import, unless BROWSER_USE_SETUP_LOGGING=false; the level comes from BROWSER_USE_LOGGING_LEVEL (default info). The REPL worker's own output goes to <workspace>/.browser-use/worker.log. No log file is written by the library; the caller adds a handler for one.The task and workspace at the start, one INFO line per step (the cell's first line and its last error line, secrets redacted), WARNING lines for a provider retry, a model timeout, a failed compaction and a failed judge, the judge's verdict, and one ERROR line or a completion line at the end.
Metricsno00None the operator can read. Product telemetry to PostHog (eu.i.posthog.com) counts runs, steps, cost and errors, but it goes to the vendor, not to a metrics backend the user owns.Not applicable. The per-run figures a user has are on the result: steps, duration_s, usage and cost_usd.
Tracingyes (opt-in)32Pydantic AI's OpenTelemetry spans to the global tracer provider, once the caller runs pydantic_ai.Agent.instrument_all() (or logfire.instrument_pydantic_ai()). Nothing is wired by the library itself (MIGRATING.md:293-294, browser_use/legacy.py:38).Spans for every model request and tool call: invoke_agent, chat <model>, execute_tool python. The REPL cell's inside, the browser and the cloud API calls are not traced.
Error reportingno00No error reporting service. Error classes ride in the telemetry event to PostHog; user reports go there too, through browser-use feedback on the CLI, the browser_feedback MCP tool and report_issue in a cell.Not applicable. A failed run's message is on the result's error field and in the ERROR log line.
Alertingno00None.Not applicable. Nothing pages anyone when runs fail.
Health checksno00None. The Dockerfile's HEALTHCHECK is commented out (Dockerfile:212-213), and browser-use --doctor is a manual check a person runs.Not applicable. The doctor prints versions, the local browser, whether Chrome and the daemon are running and whether a cloud key is set, and exits 1 only when nothing can run.

Who would notice a failure, and how long it would take

The developer who started the run, at the end of it. A run that fails returns status error, max_steps or timeout with a redacted error, and logs one ERROR line; a preflight or browser start failure surfaces within seconds, a stuck run when its budget expires, up to the 1700 s default plus the browser stop. Between those points the step lines on stderr are the only progress signal, and they are read only if someone is watching the terminal or the caller kept them. For the CLI and MCP server, the coding agent driving it sees each failed cell's error at once, and nobody else does.

Browser Use notices only in aggregate, through telemetry, and only when telemetry is on (it is on by default and off with ANONYMIZED_TELEMETRY=false). An event is sent when the run ends, or by a later process from the outbox within 7 days; a crashed run is reported from its in-flight marker by the next process. That shows the vendor failure rates by model, error class and phase; it does not tell any individual user that their run failed. Logs exist and nothing in the repository reads them: no dashboard, alert or health endpoint consumes them, which is a design fact for a library and an absence for the Docker image.

Functions named in this section

FunctionWhereWhat it does
setup_loggingbrowser_use/logging_config.py:21Puts one stderr handler on the browser_use logger at the level from BROWSER_USE_LOGGING_LEVEL. Warns when the level is not one it knows, or when a 0.x log-file variable is set that 1.0 ignores.
pythonbrowser_use/agent/loop.py:168The model's one tool: runs a cell in the REPL and logs one INFO line per step with the cell's first line and its last error line. Secrets and terminal escapes are removed from the line.
Repl._startbrowser_use/repl/session.py:357Spawns the REPL worker with its stdout and stderr appended to worker.log and waits for it to connect back. A failed start names that log file.
feedbackbrowser_use/telemetry/feedback.py:87Library call that sends a user's report to the Browser Use team in the background, also with usage stats off, after replacing secrets, keys, emails and home folders. Returns whether it was queued.
report_issuebrowser_use/repl/worker.py:995The REPL helper the model calls to report a problem with browser-use itself; the parent sends it as feedback. At most 3 per run.
_run_feedback_commandbrowser_use/cli.py:450Handles browser-use feedback: sends one feedback event with the message from the arguments or stdin. Waits for the send, so the line it prints is true.
_run_doctorbrowser_use/cli.py:251Handles browser-use --doctor: prints the browser-use, browser-harness and Python versions, the local browser, Chrome and daemon state, and whether a cloud key is set. Exits 1 only when there is neither a local browser nor a key.

17. Redundant code

The evidence lists 3 duplicate-body groups (29 removable lines) and 10 functions named only at their definition. Each was checked against the source. Five items survive as redundant: one production helper that copies another, two production functions nothing calls, and two test-only copies. The other eight candidates are reached by name through a framework (urllib's handler dispatch, Pydantic AI's hooks and capabilities), so they are not redundant and are listed with the reason. Two of the kept items are in tests, and none of the five changes what the shipped package does when removed.

One kept item has a reason behind it. browser_use/cli.py imports browser_use.utils only after it has answered --version, with the comment "importing it costs ~12 ms on macOS (proxy lookup)" at browser_use/cli.py:1077, and --version calls _browser_use_version before that import. The copy keeps utils off that path on purpose. It stays in the kept table because the speed-up does not need a second body: a version lookup in a module that imports only importlib.metadata would serve both callers.

Kept: redundant

CodeFile and linesWhat it doesWhat makes it redundant
_browser_use_versionbrowser_use/cli.py:15-19Returns the installed browser-use version from package metadata, or "unknown". The CLI uses it for BH_CLIENT_VERSION, the MCP server's version, --version, the doctor and the quickstart text.A copy of get_browser_use_version (browser_use/utils.py:131-135), body for body, without its @cache. The weakest of the five: the CLI imports browser_use.utils only lazily, after --version is handled, because that import costs about 12 ms (browser_use/cli.py:1077), so the copy keeps that module off the startup path on purpose. A version lookup that imports only importlib.metadata would serve both.
singletonbrowser_use/utils.py:119-128A class decorator that returns the first instance on every later call.No caller anywhere in the repository, tests included, and not named in MIGRATING.md or exported from browser_use/__init__.py.
thinking_and_textbrowser_use/agent/loop.py:1348-1353Lists a model response's thinking and text parts as (kind, content) pairs, skipping empty ones.No caller anywhere in the repository, tests included.
do_GET (the second Slow handler)tests/ci/test_local_browser.py:825-839A test HTTP handler that serves a page linking to a 30,000-byte file, sent slowly in 15 chunks with a download filename.A copy of the first Slow handler's do_GET at tests/ci/test_local_browser.py:784-798 in the same file. Test-only: one module-level handler would serve both tests.
no_browsertests/ci/test_telemetry.py:216-224Monkeypatches Browser.start and Browser.stop with no-ops, so a test runs an Agent without a browser.The same body as the fake_browser fixture in tests/ci/test_judge.py:24-32. Test-only: one shared fixture in tests/ci/conftest.py would serve both modules.

The bodies the kept copies duplicate

These stay; they are the originals the copies above repeat.

CodeFile and linesWhat it does
get_browser_use_versionbrowser_use/utils.py:131-135Returns the installed browser-use version, or "unknown", memoised for the process. Used by telemetry, the update check, auth, skills install and the MCP server.
do_GET (the first Slow handler)tests/ci/test_local_browser.py:784-798The test HTTP handler that serves a link page and a slowly sent 30,000-byte download. The download test that owns it checks the file is named, not a guid.
fake_browsertests/ci/test_judge.py:24-32A pytest fixture that replaces Browser.start and Browser.stop with no-ops for the judge tests.
Browser.startbrowser_use/browser/browser.py:695Starts the browser and its browser-harness daemon, or reuses them, and returns the environment the REPL worker needs. A kept-alive cloud browser that ended between runs is replaced.
Browser.stopbrowser_use/browser/browser.py:1087Stops the browser and its daemon after copying the run's downloads, and returns their local paths. A cloud browser stops billing here.

Rejected: not redundant

Eight candidates have no caller by name in the repository because the caller is a framework that looks them up.

CodeWhereWhat it doesWhy it is not redundant
https_openbrowser_use/utils.py:70Opens an HTTPS connection with the process's TLS context, which uses the OS certificate verifier.urllib calls <scheme>_open by name on every handler of an opener; this override is how TLSHandler works, so urlopen_keyed and the installed opener depend on it.
_process_provider_detailsbrowser_use/llm/__init__.py:151Pulls the gateway's browser_use block (resolved model, service tier, charge) out of the final response.An override of a Pydantic AI OpenAIResponsesModel hook on the gateway model class; Pydantic AI calls it on every response.
before_model_requestbrowser_use/agent/loop.py:423Prunes old screenshots and, at the step or time budget, switches the run to its delivery-only turn.A BrowserLoop capability hook that Pydantic AI calls before each model request.
wrap_tool_validatebrowser_use/agent/loop.py:487Skips argument validation for a tool call on the delivery-only turn, since that call is not run.A BrowserLoop capability hook that Pydantic AI calls around tool argument validation.
on_tool_execute_errorbrowser_use/agent/loop.py:494Returns a custom tool's exception to the model as an ActionResult error instead of ending the run.A BrowserLoop capability hook that Pydantic AI calls when a tool raises.
after_model_requestbrowser_use/agent/loop.py:539Records a successful model attempt for telemetry.A Recording capability hook that Pydantic AI calls after each model response.
get_wrapper_modelbrowser_use/agent/loop.py:581Wraps an OpenAI Responses model in StreamedRequest so its requests stream.A StreamResponses capability hook that Pydantic AI calls when it builds the run's model.
get_model_settingsbrowser_use/agent/loop.py:708Asks for server-side compaction only once the last request passed min(150,000 tokens, 65% of the window).A LazyCompaction capability hook that Pydantic AI calls for each request's settings.

Functions named in this section

FunctionWhereWhat it does
urlopen_keyedbrowser_use/utils.py:96Opens a request that carries an API key through an opener that never follows a redirect, so the key cannot be sent to another origin. A 3xx raises HTTPError.

18. What was deliberately not drawn

Every figure in this document had to show something the source cannot show on its own: a relationship that crosses a process, network or file boundary the call graph does not follow, or a structure too spread out to read from one file. Nine figures passed that test: the business process step strip (section 2), the module dependency graph (section 4), the layered call graph of the 33-function backbone with graph-verified edges only (section 5), three sequence diagrams for the REPL cell with its worker callback, the cloud browser lifecycle and telemetry delivery (section 6), state diagrams for the run budget and the cloud browser (section 7), and the deployment topology (section 10).

The five diagram types below were considered and rejected. Each is a figure a generated architecture document would usually carry; leaving it out is a decision, and the reason is recorded so a reader can disagree with it.

Diagram typeWhy it was not drawnWhere the information is instead
class diagramAgent, Browser, Repl, Session and the Pydantic AI capabilities are thin classes over functions; their fields are documented in the code and MIGRATING.md, and a class diagram would show inheritance from Pydantic AI types rather than how the system works.Section 5 (the functions that do the work) and MIGRATING.md (every option)
entity-relationship diagramThere is no database; the persistent state is files keyed by path, tabled in section 11.Section 11, stores and keys tables
agent loop flowchartThe loop is Pydantic AI's run plus BrowserLoop hooks; a flowchart would restate ordinary control flow the source already shows, and the part that matters (budget and delivery) is the state diagram in section 7.Section 7, run budget state diagram
full call graph782 functions and 7,386 graph edges cannot be read as one figure; section 5 draws the 33-function backbone instead.Section 5, layered call graph
network diagramThe repository provisions no network, VPC or servers; the hosts it reaches are listed in section 12 and placed in the section 10 topology.Section 12 (hosts) and section 10 (topology)

Two narrower omissions follow the same rule. Section 6 tables six boundary-crossing flows but draws sequences for three; the model request and the MCP tool call are one hop each, and a two-lifeline diagram would add nothing to the table row. Section 7 tables four state machines but draws two; the REPL worker and the telemetry event file have four transitions each and read completely as tables.

This document describes how the system is built, not whether it is built well. Which of these omissions and absences matter, how severe each risk is, and what operating it involves are questions for the technical assessment: its risk register, its operations section and its remediation roadmap.

Absences carried into the assessment

Every absence the sections state, one per line, with the section that states it.

Download