Browser Use allows you to customize the browser’s behavior through two main configuration classes: BrowserConfig and BrowserContextConfig. These settings control everything from headless mode to proxy settings and page load behavior.

We are currently working on improving how browser contexts are managed. The system will soon transition to a “1 agent, 1 browser, 1 context” model for better stability and developer experience.

Browser Configuration

The BrowserConfig class controls the core browser behavior and connection settings.

from browser_use import BrowserConfig

# Basic configuration
config = BrowserConfig(
    headless=False,
    disable_security=False
)

browser = Browser(config=config)

agent = Agent(
    browser=browser,
    # ...
)

Core Settings

  • headless (default: False) Runs the browser without a visible UI. Note that some websites may detect headless mode.

  • disable_security (default: False) Disables browser security features. While this can fix certain functionality issues (like cross-site iFrames), it should be used cautiously, especially when visiting untrusted websites.

  • keep_alive (default: False) Keeps the browser alive after the agent has finished running. This is useful when you need to run multiple tasks with the same browser instance.

Additional Settings

  • extra_browser_args (default: []) Additional arguments are passed to the browser at launch. See the full list of available arguments.

  • proxy (default: None) Standard Playwright proxy settings for using external proxy services.

  • new_context_config (default: BrowserContextConfig()) Default settings for new browser contexts. See Context Configuration below.

For web scraping tasks on sites that restrict automated access, we recommend using external browser or proxy providers for better reliability.

Alternative Initialization

These settings allow you to connect to external browser providers or use a local Chrome instance.

External Browser Provider (wss)

Connect to cloud-based browser services for enhanced reliability and proxy capabilities.

config = BrowserConfig(
    wss_url="wss://your-browser-provider.com/ws"
)
  • wss_url (default: None) WebSocket URL for connecting to external browser providers (e.g., anchorbrowser.io, steel.dev, browserbase.com, browserless.io, TestingBot).

This overrides local browser settings and uses the provider’s configuration. Refer to their documentation for settings.

External Browser Provider (cdp)

Connect to cloud or local Chrome instances using Chrome DevTools Protocol (CDP) for use with tools like headless-shell or browserless.

config = BrowserConfig(
    cdp_url="http://localhost:9222"
)
  • cdp_url (default: None) URL for connecting to a Chrome instance via CDP. Commonly used for debugging or connecting to locally running Chrome instances.

Local Chrome Instance (binary)

Connect to your existing Chrome installation to access saved states and cookies.

config = BrowserConfig(
    browser_binary_path="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
)
  • browser_binary_path (default: None) Path to connect to an existing Browser installation. Particularly useful for workflows requiring existing login states or browser preferences.
This will overwrite other browser settings.

Context Configuration

The BrowserContextConfig class controls settings for individual browser contexts.

from browser_use.browser.context import BrowserContextConfig

config = BrowserContextConfig(
    cookies_file="path/to/cookies.json",
    wait_for_network_idle_page_load_time=3.0,
    window_width=1280,
    window_height=1100,
    locale='en-US',
    user_agent='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.102 Safari/537.36',
    highlight_elements=True,
    viewport_expansion=500,
    allowed_domains=['google.com', 'wikipedia.org'],
)

browser = Browser()
context = BrowserContext(browser=browser, config=config)


async def run_search():
	agent = Agent(
		browser_context=context,
		task='Your task',
		llm=llm)

Configuration Options

Page Load Settings

  • minimum_wait_page_load_time (default: 0.5) Minimum time to wait before capturing page state for LLM input.

  • wait_for_network_idle_page_load_time (default: 1.0) Time to wait for network activity to cease. Increase to 3-5s for slower websites. This tracks essential content loading, not dynamic elements like videos.

  • maximum_wait_page_load_time (default: 5.0) Maximum time to wait for page load before proceeding.

Display Settings

  • window_width (default: 1280) and window_height (default: 1100) Browser window dimensions. The default size is optimized for general use cases and interaction with common UI elements like cookie banners.

  • locale (default: None) Specify user locale, for example en-GB, de-DE, etc. Locale will affect the navigator. Language value, Accept-Language request header value as well as number and date formatting rules. If not provided, defaults to the system default locale.

  • highlight_elements (default: True) Highlight interactive elements on the screen with colorful bounding boxes.

  • viewport_expansion (default: 500) Viewport expansion in pixels. With this you can control how much of the page is included in the context of the LLM. Setting this parameter controls the highlighting of elements:

    • -1: All elements from the entire page will be included, regardless of visibility (highest token usage but most complete).
    • 0: Only elements which are currently visible in the viewport will be included.
    • 500 (default): Elements in the viewport plus an additional 500 pixels in each direction will be included, providing a balance between context and token usage.

Restrict URLs

  • allowed_domains (default: None) List of allowed domains that the agent can access. If None, all domains are allowed. Example: [‘google.com’, ‘*.wikipedia.org’] - Here the agent will only be able to access google.com exactly and wikipedia.org + *.wikipedia.org.

    Glob patterns are supported:

    • ['example.com'] ✅ will match only example.com exactly, subdomains will not be allowed. It’s always the most secure to list all the domains you want to give the access to explicitly e.g. ['google.com', 'www.google.com', 'myaccount.google.com', 'mail.google.com', 'docs.google.com']
    • ['*.example.com'] ⚠️ CAUTION this will match example.com and all subdomains. Make sure all the subdomains are safe for the agent! abc.example.com, def.example.com, …, useruploads.example.com, admin.example.com
    • ['*google.com']DON’T DO THIS, it will match any domains that end in google.com, including evilgoogle.com
    • ['*.google.*']DON’T DO THIS, it will match google.com, google.co.uk, google.fr, etc. but also www.google.evil.com

Session Management

  • keep_alive (default: False) Keeps the browser context (tab/session) alive after an agent task has completed. This is useful for maintaining session state across multiple tasks.

Debug and Recording

  • save_recording_path (default: None) Directory path for saving video recordings.

  • trace_path (default: None) Directory path for saving trace files. Files are automatically named as {trace_path}/{context_id}.zip.

  • save_playwright_script_path (default: None) BETA: Filename to save a replayable playwright python script to containing the steps the agent took.