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.

​

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.

​

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

​

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.

​

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.