Skip to content

Latest commit

 

History

History
533 lines (421 loc) · 11.7 KB

CONFIGURATION.md

File metadata and controls

533 lines (421 loc) · 11.7 KB

Configuration Guide

Browser-Use provides flexible configuration through environment variables, configuration files, and constructor parameters.

Configuration Priority

Configuration values are resolved in this order (highest priority first):

  1. Constructor Parameters - Direct values passed to Agent, BrowserSession, etc.
  2. Environment Variables - System environment variables
  3. Configuration File - ~/.config/browseruse/config.json
  4. Default Values - Built-in defaults

Environment Variables

Core Settings

Variable Type Default Description
BROWSER_USE_LOGGING_LEVEL string 'info' Log level: debug, info, warning, error
BROWSER_USE_CONFIG_DIR string ~/.config/browseruse Configuration directory path
BROWSER_USE_HEADLESS boolean false Run browser in headless mode
IN_DOCKER boolean auto-detect Force Docker mode behavior (sandbox defaults, launch args)
BROWSER_USE_ALLOWED_DOMAINS string - Comma-separated allowed domains

LLM Settings

Variable Type Default Description
BROWSER_USE_LLM_MODEL string - Default LLM model
OPENAI_API_KEY string - OpenAI API key
ANTHROPIC_API_KEY string - Anthropic API key
GOOGLE_API_KEY string - Google API key
AZURE_OPENAI_API_KEY string - Azure OpenAI API key
AZURE_OPENAI_ENDPOINT string - Azure OpenAI endpoint
GROQ_API_KEY string - Groq API key
DEEPSEEK_API_KEY string - DeepSeek API key
OPENROUTER_API_KEY string - OpenRouter API key

Display Settings

Variable Type Default Description
BROWSER_USE_SCREEN_WIDTH number - Override screen width
BROWSER_USE_SCREEN_HEIGHT number - Override screen height

Telemetry

Variable Type Default Description
ANONYMIZED_TELEMETRY boolean true Enable anonymous telemetry

Configuration File

The configuration file is located at ~/.config/browseruse/config.json.

Structure

{
  "browser_profile": {
    "default-profile-id": {
      "id": "default-profile-id",
      "default": true,
      "headless": false,
      "user_data_dir": "~/.config/browseruse/profiles/default",
      "viewport": {
        "width": 1280,
        "height": 720
      }
    }
  },
  "llm": {
    "default-llm-id": {
      "id": "default-llm-id",
      "default": true,
      "model": "gpt-4o",
      "api_key": "sk-...",
      "temperature": 0.7
    }
  },
  "agent": {
    "default-agent-id": {
      "id": "default-agent-id",
      "default": true,
      "max_steps": 100,
      "use_vision": true,
      "max_failures": 3
    }
  }
}

Browser Profile Configuration

{
  "browser_profile": {
    "my-profile": {
      "id": "my-profile",
      "default": false,
      "headless": true,
      "user_data_dir": "/path/to/profile",
      "viewport": { "width": 1920, "height": 1080 },
      "proxy": {
        "server": "http://proxy.example.com:8080",
        "username": "user",
        "password": "pass"
      },
      "user_agent": "Mozilla/5.0 ...",
      "locale": "en-US",
      "timezone_id": "America/New_York",
      "geolocation": {
        "latitude": 40.7128,
        "longitude": -74.006
      }
    }
  }
}

LLM Configuration

{
  "llm": {
    "openai-gpt4": {
      "id": "openai-gpt4",
      "default": true,
      "model": "gpt-4o",
      "api_key": "sk-...",
      "temperature": 0.7
    },
    "anthropic-claude": {
      "id": "anthropic-claude",
      "model": "claude-sonnet-4-20250514",
      "api_key": "sk-ant-...",
      "temperature": 0.7
    }
  }
}

Agent Configuration

{
  "agent": {
    "default": {
      "id": "default",
      "default": true,
      "max_steps": 100,
      "use_vision": true,
      "vision_detail_level": "auto",
      "max_failures": 3,
      "retry_delay": 10,
      "final_response_after_failure": true,
      "max_actions_per_step": 5,
      "use_judge": true,
      "judge_llm": null,
      "ground_truth": null,
      "enable_planning": true,
      "planning_replan_on_stall": 3,
      "planning_exploration_limit": 5,
      "use_thinking": true,
      "flash_mode": false,
      "validate_output": false
    }
  }
}

BrowserProfile Options

Display Options

const profile = new BrowserProfile({
  // Headless mode
  headless: true, // true, false, or null for auto-detect

  // Viewport (for headless or forced viewport mode)
  viewport: { width: 1280, height: 720 },

  // Window size (for headed mode)
  window_size: { width: 1920, height: 1080 },

  // Window position
  window_position: { width: 0, height: 0 },

  // Device scale factor
  device_scale_factor: 2,

  // Mobile emulation
  is_mobile: false,
  has_touch: false,
});

Network Options

const profile = new BrowserProfile({
  // Proxy configuration
  proxy: {
    server: 'http://proxy.example.com:8080',
    bypass: 'localhost',
    username: 'user',
    password: 'pass',
  },

  // SSL/TLS
  ignore_https_errors: false,

  // Offline mode
  offline: false,

  // Extra HTTP headers
  extra_http_headers: {
    'X-Custom-Header': 'value',
  },
});

Identity Options

const profile = new BrowserProfile({
  // User agent
  user_agent: 'Mozilla/5.0 ...',

  // Locale
  locale: 'en-US',

  // Timezone
  timezone_id: 'America/New_York',

  // Geolocation
  geolocation: {
    latitude: 40.7128,
    longitude: -74.006,
    accuracy: 100,
  },

  // Color scheme
  color_scheme: 'light', // 'light', 'dark', 'no-preference'

  // Reduced motion
  reduced_motion: 'no-preference',
});

Storage Options

const profile = new BrowserProfile({
  // User data directory for persistent sessions
  user_data_dir: '/path/to/profile',

  // Storage state (cookies, localStorage)
  storage_state: '/path/to/state.json',
  // or
  storage_state: {
    cookies: [...],
    origins: [...]
  },

  // Cookies file
  cookies_file: '/path/to/cookies.json'
});

Performance Options

const profile = new BrowserProfile({
  // Slow down operations (debugging)
  slow_mo: 100, // milliseconds

  // Timeouts
  timeout: 30000,
  default_timeout: 30000,
  default_navigation_timeout: 30000,

  // Page load timing
  minimum_wait_page_load_time: 0.25, // seconds
  wait_for_network_idle_page_load_time: 0.5,
  maximum_wait_page_load_time: 5.0,

  // Action timing
  wait_between_actions: 0.5,
});

Browser-Use Specific Options

const profile = new BrowserProfile({
  // Viewport expansion for scrolling detection
  viewport_expansion: 500,

  // Highlight interactive elements
  highlight_elements: true,

  // Include dynamic attributes in DOM
  include_dynamic_attributes: true,

  // Enable default extensions (uBlock, cookie consent)
  enable_default_extensions: true,

  // Stealth mode
  stealth: false,

  // Disable security features (for testing)
  disable_security: false,

  // Deterministic rendering (for consistent screenshots)
  deterministic_rendering: false,
});

Agent Settings

Basic Settings

const agent = new Agent({
  task: 'Your task',
  llm,

  // Per-step limits
  max_actions_per_step: 5,

  // Failure handling
  max_failures: 3,
  retry_delay: 10, // seconds
  final_response_after_failure: true,
});

// Overall step cap is set when running:
const history = await agent.run(100);

Vision Settings

const agent = new Agent({
  task: 'Your task',
  llm,

  // Enable vision
  use_vision: true,

  // Vision detail level
  // 'auto' - Let the model decide
  // 'low' - Lower resolution, fewer tokens
  // 'high' - Higher resolution, more tokens
  vision_detail_level: 'auto',
});

Prompt Settings

const agent = new Agent({
  task: 'Your task',
  llm,

  // Extended thinking prompts
  use_thinking: true,

  // Optimized prompts for speed
  flash_mode: false,

  // Override system message
  override_system_message: 'Custom system message...',

  // Extend system message
  extend_system_message: 'Additional instructions...',
});

Output Settings

const agent = new Agent({
  task: 'Your task',
  llm,

  // Strict output validation
  validate_output: true,

  // Save conversation logs
  save_conversation_path: './logs/conversations',

  // Generate session GIF
  generate_gif: true,
  // or specify path
  generate_gif: './recordings/session.gif',
});

Timeout Settings

const agent = new Agent({
  task: 'Your task',
  llm,

  // LLM call timeout
  llm_timeout: 60, // 60 seconds

  // Step execution timeout
  step_timeout: 180, // 3 minutes
});

DOM Settings

const agent = new Agent({
  task: 'Your task',
  llm,

  // Include additional HTML attributes
  include_attributes: ['data-testid', 'aria-label'],

  // Include tool call examples in prompts
  include_tool_call_examples: true,
});

Creating Custom Configurations

Programmatic Configuration

import { Agent, BrowserSession, BrowserProfile } from 'browser-use';
import { ChatOpenAI } from 'browser-use/llm/openai';

// Create custom profile
const profile = new BrowserProfile({
  headless: false,
  viewport: { width: 1920, height: 1080 },
  user_data_dir: './my-profile',
  highlight_elements: true,
});

// Create session with profile
const session = new BrowserSession({
  browser_profile: profile,
});

// Create LLM
const llm = new ChatOpenAI({
  model: 'gpt-4o',
  apiKey: process.env.OPENAI_API_KEY,
  temperature: 0.5,
});

// Create agent with all options
const agent = new Agent({
  task: 'Your task',
  llm,
  browser_session: session,
  use_vision: true,
  max_failures: 5,
});

const history = await agent.run(50);

Using .env Files

Create a .env file:

# LLM
OPENAI_API_KEY=sk-your-key
BROWSER_USE_LLM_MODEL=gpt-4o

# Browser
BROWSER_USE_HEADLESS=false

# Logging
BROWSER_USE_LOGGING_LEVEL=debug

# Telemetry
ANONYMIZED_TELEMETRY=false

Load with dotenv:

import 'dotenv/config';
import { Agent } from 'browser-use';
import { ChatOpenAI } from 'browser-use/llm/openai';

const agent = new Agent({
  task: 'Your task',
  llm: new ChatOpenAI({
    model: process.env.BROWSER_USE_LLM_MODEL || 'gpt-4o',
  }),
});

Docker Configuration

For Docker environments, use these settings:

const profile = new BrowserProfile({
  headless: true,
  chromium_sandbox: false, // Recommended for containerized CI/Docker
  args: [
    '--no-sandbox',
    '--disable-gpu-sandbox',
    '--disable-setuid-sandbox',
    '--disable-dev-shm-usage',
  ],
});

If sandbox is enabled and Chromium launch fails with No usable sandbox, browser-use automatically retries once with no-sandbox flags and logs a warning. For deterministic behavior in CI, prefer setting chromium_sandbox: false explicitly in that environment.

Or set environment variables:

ENV BROWSER_USE_HEADLESS=true
ENV IN_DOCKER=true