Browser Use Integration

Browser Use is a Python library that allows AI agents to control a browser. By integrating Browserless with Browser Use, you can give your AI applications web browsing capabilities without managing browser infrastructure.

Prerequisites

• Python 3.11+
• Browserless API token (available in your account dashboard)
• An LLM provider API key (OpenAI used in this guide; get your key from OpenAI's API keys page)

Video Tutorial

Visual learner? Check out this video Never Get Blocked by CAPTCHAs Again with Browser Use for a step-by-step tutorial.

Tooling

• Virtual environment: python -m venv is the recommended, built-in way to create a virtual environment (no additional installation required).
• Optional tools:
  • uv - Fast Python package installer and resolver
  • conda - Package and environment manager

Step-by-Step Setup

1. Set your Browserless token + LLM API key

   You'll need three environment variables:

   • BROWSERLESS_TOKEN - Your Browserless token (get it from your Browserless account dashboard)
   • OPENAI_API_KEY - Your OpenAI key (get it from OpenAI's API keys page)
   • BROWSERLESS_WS_URL - Browserless WebSocket URL (default: wss://production-sfo.browserless.io)

   Note: While other LLM providers can be used, this guide uses OpenAI for the examples.

   See the Environment Variables + .env file section below for detailed setup instructions.

2. Create a virtual environment

   Set up a Python virtual environment to manage your dependencies. The built-in venv module is recommended as it requires no additional installs:

   venv (recommended)

   macOS/Linux

   # Verify Python version (should be 3.11+)
   python3 --version
   
   # Create virtual environment
   python3 -m venv .venv
   source .venv/bin/activate

   Windows (CMD)

   # Verify Python version (should be 3.11+)
   py --version
   
   # Create virtual environment
   py -m venv .venv
   .venv\Scripts\activate

   Optional: Using uv

   If you have uv installed, you can use it as an alternative:

   python -m venv .venv
   source .venv/bin/activate  # On Windows (CMD): .venv\Scripts\activate

   After activation, install dependencies with uv pip install (see step 3).

   Optional: Using conda

   If you have conda installed, you can use it as an alternative:

   conda create -n browserless-env python=3.11
   conda activate browserless-env

   Note: The default path is venv + pip. uv and conda are optional alternatives.

3. Install required packages

   Make sure your virtual environment is activated, then install the required packages:

   pip (default)

   macOS/Linux

   # Make sure your virtual environment is activated
   source .venv/bin/activate
   
   # Install required packages
   pip install "browser-use>=0.12.0" python-dotenv openai

   Windows

   # Make sure your virtual environment is activated
   .venv\Scripts\activate
   
   # Install required packages
   pip install "browser-use>=0.12.0" python-dotenv openai

   Optional: Using uv

   If you're using uv (see step 2), install with:

   # Make sure your virtual environment is activated
   source .venv/bin/activate  # macOS/Linux
   # or
   .venv\Scripts\activate  # Windows CMD
   
   # Install required packages
   uv pip install browser-use python-dotenv openai

   Note: The quickstart uses uv pip install, not uv add or uv init.

4. Environment Variables + .env file

   Create a .env file in your project directory with the following variables:

   BROWSERLESS_TOKEN=your_browserless_token_here
   OPENAI_API_KEY=your_openai_key_here
   BROWSERLESS_WS_URL=wss://production-sfo.browserless.io

   Note: This guide uses BROWSERLESS_TOKEN to match the repository standard. Other scripts in this repository also use BROWSERLESS_TOKEN for consistency.

   Important: Do not commit .env to version control. Add .env to your .gitignore file.

   If you prefer to set environment variables directly (without a .env file):

   macOS/Linux

   export BROWSERLESS_TOKEN=your_browserless_token_here
   export OPENAI_API_KEY=your_openai_key_here
   export BROWSERLESS_WS_URL=wss://production-sfo.browserless.io

   Windows (PowerShell)

   $env:BROWSERLESS_TOKEN="your_browserless_token_here"
   $env:OPENAI_API_KEY="your_openai_key_here"
   $env:BROWSERLESS_WS_URL="wss://production-sfo.browserless.io"

   Windows (CMD)

   set BROWSERLESS_TOKEN=your_browserless_token_here
   set OPENAI_API_KEY=your_openai_key_here
   set BROWSERLESS_WS_URL=wss://production-sfo.browserless.io

   Note: The examples in this guide use python-dotenv to automatically load the .env file.

5. Create the main.py file

   Create a new file named main.py with the following complete code:

       from browser_use import Agent, BrowserSession
       from browser_use.llm import ChatOpenAI
       from dotenv import load_dotenv
       import os
       import asyncio
   
       # Load environment variables from .env file
       load_dotenv()
   
       async def main():
           # Validate required environment variables
           browserless_token = os.getenv('BROWSERLESS_TOKEN')
           openai_key = os.getenv('OPENAI_API_KEY')
           browserless_ws_url = os.getenv('BROWSERLESS_WS_URL', 'wss://production-sfo.browserless.io')
   
           if not browserless_token:
               raise RuntimeError("BROWSERLESS_TOKEN environment variable is required. Get your token from https://browserless.io/account/")
           if not openai_key:
               raise RuntimeError("OPENAI_API_KEY environment variable is required. Get your key from https://platform.openai.com/api-keys")
   
           # Create browser session using BROWSERLESS_WS_URL
           browser_session = BrowserSession(
               cdp_url=f"{browserless_ws_url}?token={browserless_token}"
           )
   
           # Setup LLM
           llm = ChatOpenAI(model="gpt-4o-mini", api_key=openai_key)
   
           # Create and run agent with a simple task
           agent = Agent(
               task="Go to https://example.com and tell me the main heading on the page",
               llm=llm,
               browser_session=browser_session
           )
   
           result = await agent.run()
           print(result)
   
       if __name__ == "__main__":
           asyncio.run(main())

6. Run your application

   Make sure your virtual environment is activated, then run your application:

   macOS/Linux

   # Make sure your virtual environment is activated
   source .venv/bin/activate
   
   # Run your application
   python main.py

   Windows

   # Make sure your virtual environment is activated
   .venv\Scripts\activate
   
   # Run your application
   python main.py

   You should see output indicating that the browser is initialized and the agent is running.

How It Works

1. Connection Setup: Browser Use connects to Browserless using the WebSocket endpoint with your API token
2. Agent Configuration: The AI agent is configured with a task and a language model
3. Automation: The agent uses the browser to navigate and interact with websites
4. LLM Integration: The agent uses an LLM (like GPT-4o) to interpret web content and make decisions

Complete Example with Cloud Browser

Here's a complete example that demonstrates the modern BrowserSession approach with proper environment variable handling:

"""Simple browser-use + Browserless connection example"""

import asyncio
import os
from browser_use import Agent
from browser_use.browser import BrowserSession
from browser_use.llm import ChatOpenAI
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

async def main():
    # Validate required environment variables
    browserless_token = os.getenv('BROWSERLESS_TOKEN')
    openai_key = os.getenv('OPENAI_API_KEY')
    browserless_ws_url = os.getenv('BROWSERLESS_WS_URL', 'wss://production-sfo.browserless.io')

    if not browserless_token:
        raise RuntimeError("BROWSERLESS_TOKEN environment variable is required. Get your token from https://browserless.io/account/")
    if not openai_key:
        raise RuntimeError("OPENAI_API_KEY environment variable is required. Get your key from https://platform.openai.com/api-keys")

    # Setup LLM
    llm = ChatOpenAI(model="gpt-4o-mini", api_key=openai_key)

    # Setup browser session using BROWSERLESS_WS_URL
    url = f"{browserless_ws_url}?token={browserless_token}"
    browser_session = BrowserSession(cdp_url=url)
    print("🌐 Using cloud browser")

    # Create and run agent
    agent = Agent(
        task="Go to https://example.com and tell me the main heading",
        llm=llm,
        browser_session=browser_session
    )

    result = await agent.run(max_steps=5)
    print(f"✅ Done! Result: {type(result).__name__}")

if __name__ == "__main__":
    asyncio.run(main())

Advanced / Bot-Protected Sites

For sites with bot protection (like eBay), you may need additional configuration:

from browser_use import Agent, BrowserSession
from browser_use.llm import ChatOpenAI
from dotenv import load_dotenv
import os
import asyncio

load_dotenv()

async def main():
    browserless_token = os.getenv('BROWSERLESS_TOKEN')
    openai_key = os.getenv('OPENAI_API_KEY')
    browserless_ws_url = os.getenv('BROWSERLESS_WS_URL', 'wss://production-sfo.browserless.io')

    if not browserless_token:
        raise RuntimeError("BROWSERLESS_TOKEN environment variable is required")
    if not openai_key:
        raise RuntimeError("OPENAI_API_KEY environment variable is required")

    # Use stealth mode and residential proxy for bot-protected sites
    browser_session = BrowserSession(
        cdp_url=f"{browserless_ws_url}/chromium/stealth?token={browserless_token}&proxy=residential"
    )

    llm = ChatOpenAI(model="gpt-4o-mini", api_key=openai_key)

    agent = Agent(
        task="Find me the top cheapest trainer on ebay.co.uk",
        llm=llm,
        browser_session=browser_session
    )

    result = await agent.run()
    print(result)

if __name__ == "__main__":
    asyncio.run(main())

Additional Configuration Options

Using Different Browserless Regions

You can connect to different Browserless regions for better performance by setting BROWSERLESS_WS_URL in your .env file:

# US West Coast (default)
BROWSERLESS_WS_URL=wss://production-sfo.browserless.io

# Europe (London)
BROWSERLESS_WS_URL=wss://production-lon.browserless.io

Proxy Support

You can enable a residential proxy for improved website compatibility:

browserless_ws_url = os.getenv('BROWSERLESS_WS_URL', 'wss://production-sfo.browserless.io')
browserless_token = os.getenv('BROWSERLESS_TOKEN')
browser_session = BrowserSession(
    cdp_url=f"{browserless_ws_url}?token={browserless_token}&proxy=residential"
)

Stealth Mode and Proxy Support

Enable stealth mode and residential proxies for better website compatibility. Stealth mode uses the /chromium/stealth path:

browserless_ws_url = os.getenv('BROWSERLESS_WS_URL', 'wss://production-sfo.browserless.io')
browserless_token = os.getenv('BROWSERLESS_TOKEN')
browser_session = BrowserSession(
    cdp_url=f"{browserless_ws_url}/chromium/stealth?token={browserless_token}&proxy=residential"
)

Automatic CAPTCHA Solving

Requires browser-use 0.12.0+

The automatic CAPTCHA pause/resume feature requires browser-use version 0.12.0 or later, which includes the CaptchaWatchdog. Earlier versions don't have this. Upgrade with pip install browser-use>=0.12.0.

Enable automatic CAPTCHA solving so the agent pauses while CAPTCHAs are solved and resumes when done. This requires solveCaptchas=true to enable the captcha engine and integrations=browseruse to bridge the events to browser-use's watchdog:

browserless_ws_url = os.getenv('BROWSERLESS_WS_URL', 'wss://production-sfo.browserless.io')
browserless_token = os.getenv('BROWSERLESS_TOKEN')
browser_session = BrowserSession(
    cdp_url=f"{browserless_ws_url}/chromium?token={browserless_token}&solveCaptchas=true&integrations=browseruse"
)

When the agent navigates to a page with a CAPTCHA (reCAPTCHA, hCaptcha, Cloudflare Turnstile, etc.), Browserless automatically detects and solves it. The agent pauses during solving and resumes once the CAPTCHA is resolved.

Stealth + Proxy + CAPTCHA Solving

Combine all features for maximum compatibility with bot-protected sites:

browserless_ws_url = os.getenv('BROWSERLESS_WS_URL', 'wss://production-sfo.browserless.io')
browserless_token = os.getenv('BROWSERLESS_TOKEN')

# Stealth mode + residential proxy + auto CAPTCHA solving
browser_session = BrowserSession(
    cdp_url=(
        f"{browserless_ws_url}/chromium/stealth?token={browserless_token}"
        f"&proxy=residential&proxyCountry=US"
        f"&solveCaptchas=true&integrations=browseruse"
    )
)

llm = ChatOpenAI(model="gpt-4o-mini", api_key=os.getenv('OPENAI_API_KEY'))

agent = Agent(
    task="Navigate to a protected site and extract data",
    llm=llm,
    browser_session=browser_session
)

result = await agent.run()

Available query parameters:

Parameter	Description	Example
token	Your API token (required)	token=your_token
solveCaptchas	Enable automatic CAPTCHA solving	solveCaptchas=true
integrations	Enable browser-use event bridge for CAPTCHA pause/resume	integrations=browseruse
proxy	Enable residential proxy	proxy=residential
proxyCountry	Proxy country (two-letter code)	proxyCountry=US
proxyCity	Proxy city	proxyCity=New+York
proxyState	Proxy state/region	proxyState=CA
stealth	Enable stealth mode (use /chromium/stealth path instead)	Path-based

Available stealth routes:

Route	Description
/chromium	Standard Chromium (default)
/chromium/stealth	Chromium with anti-detection
/chrome/stealth	Chrome with anti-detection

Custom Browser Configuration

Configure browser settings using BrowserProfile:

from browser_use.browser import BrowserProfile

browserless_ws_url = os.getenv('BROWSERLESS_WS_URL', 'wss://production-sfo.browserless.io')
browserless_token = os.getenv('BROWSERLESS_TOKEN')

browser_session = BrowserSession(
    cdp_url=f"{browserless_ws_url}?token={browserless_token}",
    browser_profile=BrowserProfile(
        user_agent="Custom User Agent",
        viewport_size={"width": 1920, "height": 1080},
        headless=True,
    )
)

FAQ & Troubleshooting

Missing environment variables (BROWSERLESS_TOKEN or OPENAI_API_KEY)

Ensure your .env file contains both variables and is in the same directory as your script. Call load_dotenv() at the top of your script before accessing them. If using uv, run uv pip install python-dotenv.

.env file not being loaded

Install python-dotenv (pip install python-dotenv) and call load_dotenv() before accessing environment variables. Verify the .env file is in the same directory as your script.

uv add fails or does not work as expected

The quickstart uses uv pip install instead of uv add. The uv add command requires a project initialized with uv init. Use uv pip install browser-use python-dotenv after activating your virtual environment.

Windows ExecutionPolicy error when activating the virtual environment

Run PowerShell as Administrator and execute Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser. Alternatively, use Command Prompt (CMD) or activate with .venv\Scripts\activate.bat.

Connection timeout or failed to connect

Verify BROWSERLESS_WS_URL is set correctly (default: wss://production-sfo.browserless.io). Check that your BROWSERLESS_TOKEN is valid and active. Try a different region endpoint if you are experiencing latency, and ensure your network allows WebSocket connections.

Next steps

Browser Agent

a managed alternative that skips the setup and model wiring

AI integrations overview

all supported AI frameworks and tools