Skip to main content
browser-use is a Python-based browser agent that provides programmable browser automation capabilities. It supports local Chrome, Lexmount cloud browsers, and AgentBay cloud browsers.

​
Installation

# Create and activate the project virtual environment
uv venv
source .venv/bin/activate

# Install browseruse-bench
uv pip install -e .
bubench run will create the agent venv defined in config.yaml (default .venvs/browser_use) and install the browser-use extra on first use. Activate .venv (or use uv run bubench ...) before running bubench commands.

​
Configuration

Configure browser-use in the root config.yaml under agents.browser-use: 
agents:
  browser-use:
    active_model: browser-use   # active model profile
    models:
      browser-use:              # Browser Use official API
        model_type: BROWSER_USE
        model_id: bu-2-0
        api_key: $BROWSER_USE_API_KEY
      gpt:                      # OpenAI-compatible model
        model_type: OPENAI
        model_id: gpt-5.4
        api_key: $OPENAI_API_KEY
        base_url: $OPENAI_BASE_URL
    browser:
      browser_id: lexmount
      lexmount_browser_mode: normal
      lexmount_api_key: $LEXMOUNT_API_KEY
      lexmount_project_id: $LEXMOUNT_PROJECT_ID
    defaults:
      use_vision: false
      max_steps: 40
      flash_mode: true
      timeout: 600
Set active_model to the profile name you want to use by default, then switch at runtime with --model <name>.

​
Supported Model Types

model_typeDescriptionAdditional Keys
BROWSER_USEBrowser Use official APIapi_key ($BROWSER_USE_API_KEY)
OPENAIOpenAI-compatible modelsapi_key, base_url
GEMINIGemini modelsapi_key, base_url

​
Configuration Parameters

ParameterDescriptionExample
active_modelDefault model profilebrowser-use, gpt
model_typeModel provider typeBROWSER_USE, OPENAI, GEMINI
model_idModel IDbu-2-0, gpt-4.1
api_keyAPI key (use $ENV_VAR form)$BROWSER_USE_API_KEY
browser_idBrowser backendChrome-Local, lexmount, agentbay
use_visionPass screenshots to the LLM alongside DOM statetrue, false
max_stepsMax steps per task40
timeoutTask timeout (seconds)600
lexmount_browser_modeLexmount browser modenormal (default), light
agentbay_api_keyAgentBay API key (use $ENV_VAR form)$AGENTBAY_API_KEY
agentbay_image_idAgentBay session imageDefault browser_latest
agentbay_enable_browser_replayEnable AgentBay replaytrue (default), false
agentbay_browser_use_stealthEnable AgentBay stealthfalse (default), true
Why no browser_control?browser-use always operates with DOM and vision running in parallel internally — there is no separate “DOM-only” or “vision-only” mode to expose. use_vision only controls whether screenshots are included in the LLM’s context; the underlying interaction strategy is fixed by the framework itself.
Not Recommended: configs/agents/browser-use/config.yamlPer-agent config files under configs/agents/ are no longer the recommended approach and may be removed in a future release. Use the root config.yaml instead (see above).

​
Browser Modes

Local Browser: Use local Chrome, suitable for development and debugging. No extra parameters required. 
browser:
  browser_id: Chrome-Local
Lexmount Cloud Browser: Suitable for large-scale evaluation. Set LEXMOUNT_API_KEY / LEXMOUNT_PROJECT_ID in .env, then reference them under browser in config.yaml: 
browser:
  browser_id: lexmount
  lexmount_browser_mode: normal           # normal | light
  lexmount_api_key: $LEXMOUNT_API_KEY
  lexmount_project_id: $LEXMOUNT_PROJECT_ID
  # lexmount_base_url: $LEXMOUNT_BASE_URL  # optional; override per region:
                                          #   https://api.lexmount.cn            (mainland China / 国内, default)
                                          #   https://api.lexmount.com           (international / 国外)
See Lexmount Cloud Browser for detailed configuration. AgentBay Cloud Browser: Suitable for large-scale evaluation. Set AGENTBAY_API_KEY in .env, then reference it under browser in config.yaml: 
browser:
  browser_id: agentbay
  agentbay_api_key: $AGENTBAY_API_KEY
  # agentbay_image_id: browser_latest
  # agentbay_enable_browser_replay: true
  # agentbay_browser_use_stealth: false
Runtime notes:
  • AgentBay SDK is treated as an optional dependency. Missing packages or incompatible exports fail only when browser_id: agentbay; other browser modes continue to work.
  • Session cleanup failures in AgentBay backend are logged and do not mask task execution errors.

​
Usage Examples

​
Basic Run

# Run top 3 tasks of LexBench-Browser L1 (no-login subset)
bubench run \
  --agent browser-use \
  --benchmark LexBench-Browser \
  --split L1 \
  --mode first_n \
  --count 3

# Run all L1 tasks (skip completed)
bubench run \
  --agent browser-use \
  --benchmark LexBench-Browser \
  --split L1 \
  --mode all \
  --skip-completed

​
Run Specific Tasks

# Run tasks by ID
bubench run \
  --agent browser-use \
  --benchmark LexBench-Browser \
  --split L1 \
  --mode specific \
  --task-ids task_id_1 task_id_2

​
Evaluation

# Evaluate results (--model-id matches the model_id used at run time)
bubench eval --agent browser-use --benchmark LexBench-Browser --model-id bu-2-0

# Custom score threshold
bubench eval --agent browser-use --benchmark LexBench-Browser --model-id bu-2-0 --score-threshold 70

​
Supported Benchmarks

  • ✅ LexBench-Browser
  • ✅ Online-Mind2Web
  • ✅ BrowseComp