Browser Settings

Scrap Web allows you to customize how the browser behaves through two main configuration classes: BrowserConfig and BrowserContextConfig. These 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.

Copy

from browser_use import BrowserConfig

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

​Core Settings

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

• disable_security (default: True) 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.

​Additional Settings

• extra_chromium_args (default: []) Additional arguments passed to the browser at launch.

• 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 Swift providers or use a local Chrome instance.

​External Swift Provider (wss)

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

Copy

config = BrowserConfig(
    wss_url="wss://your-browser-provider.com/ws"
)

• wss_url (default: None) WebSocket URL for connecting to external browser providers (e.g., anchorswift.com, steel.dev, swiftbase.com,swiftrless.io).

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

​Local Chrome Instance (binary)

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

Copy

config = BrowserConfig(
    chrome_instance_path="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
)

• chrome_instance_path (default: None) Path to connect to an existing Chrome 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.

Copy

from browser_use.browser.context import BrowserContextConfig

config = BrowserContextConfig(
    cookies_file="path/to/cookies.json",
    wait_for_network_idle_page_load_time=3.0,
    browser_window_size={'width': 1280, 'height': 1100}
)

​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

• browser_window_size (default: {'width': 1280, 'height': 1100}) Browser window dimensions. The default size is optimized for general use cases and interaction with common UI elements like cookie banners.

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