快速开始

Launch a cloud browser and connect to it from your code.

Every browser includes stealth, proxies, live preview, and recording. Its CDP URL is a WebSocket endpoint for remotely controlling Chrome.

<img alt="Your code using a CDP URL to connect to and control a cloud browser that accesses the web" />

<img alt="Your code using a CDP URL to connect to and control a cloud browser that accesses the web" />

Get an API key and export it:

export BROWSER_USE_API_KEY=your_key

Install the SDK

Skip this step if you use curl.

pip install --upgrade browser-use-sdk playwright

npm install browser-use-sdk@latest playwright

npm install browser-use-sdk@latest puppeteer-core

Launch and connect

The SDK and REST examples use API V4. Each SDK example creates a browser, connects over CDP, opens a page, and stops the managed browser in finally. Use its existing browser context so profile cookies and managed settings apply. No local browser download is needed for a remote CDP connection.

from browser_use_sdk.v4 import BrowserUse
from playwright.sync_api import sync_playwright

with BrowserUse() as client:
    session = client.browsers.create(proxy_country_code="us")
    try:
        if not session.cdp_url:
            raise RuntimeError("The browser did not return a CDP URL")
        with sync_playwright() as p:
            browser = p.chromium.connect_over_cdp(session.cdp_url)
            context = browser.contexts[0]
            page = context.pages[0] if context.pages else context.new_page()
            page.goto("https://example.com")
            print(page.title())
    finally:
        client.browsers.stop(session.id)

import { BrowserUse } from "browser-use-sdk/v4";
import { chromium } from "playwright";

const client = new BrowserUse();
const session = await client.browsers.create({ proxyCountryCode: "us" });
try {
  if (!session.cdpUrl) throw new Error("The browser did not return a CDP URL");
  const browser = await chromium.connectOverCDP(session.cdpUrl);
  try {
    const context = browser.contexts()[0];
    const page = context.pages()[0] ?? await context.newPage();
    await page.goto("https://example.com");
    console.log(await page.title());
  } finally {
    await browser.close();
  }
} finally {
  await client.browsers.stop(session.id);
}

import { BrowserUse } from "browser-use-sdk/v4";
import puppeteer from "puppeteer-core";

const client = new BrowserUse();
const session = await client.browsers.create({ proxyCountryCode: "us" });
try {
  if (!session.cdpUrl) throw new Error("The browser did not return a CDP URL");
  const browser = await puppeteer.connect({ browserWSEndpoint: session.cdpUrl });
  try {
    const context = browser.defaultBrowserContext();
    const page = (await context.pages())[0] ?? await context.newPage();
    await page.goto("https://example.com");
    console.log(await page.title());
  } finally {
    await browser.disconnect();
  }
} finally {
  await client.browsers.stop(session.id);
}

# Requires curl and jq. Run this in the shell used by your automation script.
browser=$(curl --fail-with-body -sS https://api.browser-use.com/api/v4/browsers \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"proxyCountryCode":"us"}')

export BROWSER_SESSION_ID=$(echo "$browser" | jq -er .id)
export BROWSER_USE_CDP_URL=$(echo "$browser" | jq -er .cdpUrl)

# Connect your Playwright or Puppeteer script to BROWSER_USE_CDP_URL.
# Keep this browser running until that script finishes, then stop it below.

Disconnecting CDP, Playwright's browser.close(), or client.close() does not stop the managed browser. Use client.browsers.stop(session.id) as above. With Puppeteer, use disconnect() to release the connection, then stop the managed browser through the API.

For a browser created with curl, run this after your automation finishes:

curl --fail-with-body -X PATCH \
  "https://api.browser-use.com/api/v4/browsers/$BROWSER_SESSION_ID" \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"stop"}'

Selenium cannot connect to a remote WebSocket CDP URL; use Playwright or Puppeteer. Use the live preview while the browser is running, then stop it when you are done. Recording is off by default for API browsers. Set enable_recording=True / enableRecording: true when creating the browser if you need a recording. The video becomes available asynchronously after it stops; Zero Data Retention projects never record.

Full connection guide and stop semantics.



Configure proxies, screen size, recording, and timeout.

Install and run your first AI browser agent in minutes. Python setup with pip, environment variables, and a working example.

To get started with Browser Use you need to install the package and create an .env file with your API key.

ChatBrowserUse offers the fastest and most cost-effective models, completing tasks 3-5x faster. Eligible new accounts receive \$15 in one-time credits. Get your API key here.

1. Installing Browser-Use

pip install uv
uv venv --python 3.12

source .venv/bin/activate
# On Windows use `.venv\Scripts\activate`

uv pip install browser-use
uvx browser-use install

2. Choose your favorite LLM

Create a .env file and add your API key.

<Callout icon="key"> We recommend using ChatBrowserUse which is optimized for browser automation tasks (highest accuracy + fastest speed + lowest token cost). Get your API key here — eligible new accounts receive \$15 in one-time credits. </Callout>

touch .env

On Windows, use echo. > .env

Then add your API key to the file.

# add your key to .env file
BROWSER_USE_API_KEY=
# Get your API key at https://cloud.browser-use.com/new-api-key - eligible new accounts receive $15 in one-time credits

# add your key to .env file
GOOGLE_API_KEY=
# Get your free Gemini API key from https://aistudio.google.com/app/u/1/apikey?pli=1.

# add your key to .env file
OPENAI_API_KEY=

# add your key to .env file
ANTHROPIC_API_KEY=

See Supported Models for more.

3. Run your first agent

from browser_use import Agent, ChatBrowserUse
from dotenv import load_dotenv
import asyncio

load_dotenv()

async def main():
    llm = ChatBrowserUse()
    task = "Find the number 1 post on Show HN"
    agent = Agent(task=task, llm=llm)
    await agent.run()

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

from browser_use import Agent, ChatGoogle
from dotenv import load_dotenv
import asyncio

load_dotenv()

async def main():
    llm = ChatGoogle(model="gemini-flash-latest")
    task = "Find the number 1 post on Show HN"
    agent = Agent(task=task, llm=llm)
    await agent.run()

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

from browser_use import Agent, ChatOpenAI
from dotenv import load_dotenv
import asyncio

load_dotenv()

async def main():
    llm = ChatOpenAI(model="gpt-4.1-mini")
    task = "Find the number 1 post on Show HN"
    agent = Agent(task=task, llm=llm)
    await agent.run()

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

from browser_use import Agent, ChatAnthropic
from dotenv import load_dotenv
import asyncio

load_dotenv()

async def main():
    llm = ChatAnthropic(model='claude-sonnet-4-0', temperature=0.0)
    task = "Find the number 1 post on Show HN"
    agent = Agent(task=task, llm=llm)
    await agent.run()

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

Custom browsers can be configured in one line. Check out /open-source/customize/browser/basics for more.

4. Going to Production

Sandboxes are the easiest way to run Browser-Use in production. We handle agents, browsers, persistence, auth, cookies, and LLMs. It is also the fastest way to deploy - the agent runs right next to the browser, so latency is minimal.

To run in production with authentication, add @sandbox to your function:

import asyncio
from browser_use import Browser, sandbox, ChatBrowserUse
from browser_use.agent.service import Agent

@sandbox(cloud_profile_id='your-profile-id')
async def production_task(browser: Browser):
    agent = Agent(
        task="Your authenticated task",
        browser=browser,
        llm=ChatBrowserUse(),
    )
    await agent.run()

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

See Browser Use Cloud for how to sync your cookies to the cloud.

Run a hosted agent or launch a cloud browser.

Give an agent a task and get the result.



Launch a cloud browser and connect to it from your code.

Both Cloud paths use API V4. Choose whether Browser Use drives the browser or your Playwright/Puppeteer code connects directly over CDP. For a local agent, use the open-source library.

Get an API key and export it:

export BROWSER_USE_API_KEY=your_key

Install the SDK

Use Python 3.10 or newer for the Python SDK. Skip installation if you use curl.

pip install --upgrade browser-use-sdk playwright

npm install browser-use-sdk@latest puppeteer-core

Run Browser Use Agents

from browser_use_sdk.v4 import BrowserUse

with BrowserUse() as client:
    run = client.runs.create("Find the top Hacker News story")
    result = client.runs.wait_for_completion(run.id)
    print(result.result)

import { BrowserUse } from "browser-use-sdk/v4";

const client = new BrowserUse();
const run = await client.runs.create({
  task: "Find the top Hacker News story",
});
const result = await client.runs.waitForCompletion(run.id);
console.log(result.result);

curl https://api.browser-use.com/api/v4/runs \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task":"Find the top Hacker News story"}'

Use Browser Infrastructure

These examples connect to the managed browser's existing context and stop it in finally, including when connecting or navigating fails.

from browser_use_sdk.v4 import BrowserUse
from playwright.sync_api import sync_playwright

with BrowserUse() as client:
    session = client.browsers.create(proxy_country_code="us")
    try:
        if not session.cdp_url:
            raise RuntimeError("The browser did not return a CDP URL")
        with sync_playwright() as p:
            browser = p.chromium.connect_over_cdp(session.cdp_url)
            context = browser.contexts[0]
            page = context.pages[0] if context.pages else context.new_page()
            page.goto("https://example.com")
            print(page.title())
    finally:
        client.browsers.stop(session.id)

import { BrowserUse } from "browser-use-sdk/v4";
import puppeteer from "puppeteer-core";

const client = new BrowserUse();
const session = await client.browsers.create({ proxyCountryCode: "us" });
try {
  if (!session.cdpUrl) throw new Error("The browser did not return a CDP URL");
  const browser = await puppeteer.connect({ browserWSEndpoint: session.cdpUrl });
  try {
    const context = browser.defaultBrowserContext();
    const page = (await context.pages())[0] ?? await context.newPage();
    await page.goto("https://example.com");
    console.log(await page.title());
  } finally {
    await browser.disconnect();
  }
} finally {
  await client.browsers.stop(session.id);
}

Disconnecting CDP does not stop the managed browser. Use client.browsers.stop(session.id) as above, or call PATCH /api/v4/browsers/{id} with {"action":"stop"}.

For curl and additional connection options, follow the Browser Infrastructure quickstart.

Give your coding agent the compact API V4 context.

Give a high-accuracy browser agent a goal and get the result.

Create an API key and export it:

export BROWSER_USE_API_KEY=your_key

from browser_use_sdk.v4 import BrowserUse

with BrowserUse() as client:
    run = client.runs.create("Find the top Hacker News story")
    result = client.runs.wait_for_completion(run.id)
    print(result.result)

import { BrowserUse } from "browser-use-sdk/v4";

const client = new BrowserUse();
const run = await client.runs.create({
  task: "Find the top Hacker News story",
});
const result = await client.runs.waitForCompletion(run.id);
console.log(result.result);

curl https://api.browser-use.com/api/v4/runs \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task":"Find the top Hacker News story"}'

Install the latest SDK with pip install --upgrade browser-use-sdk or npm install browser-use-sdk@latest. Curl needs no installation.

Every new run implicitly creates a session for its conversation and live browser, plus a workspace for persistent files.

<img alt="A task starts a run inside a session and the run reads and writes persistent workspace files" />

<img alt="A task starts a run inside a session and the run reads and writes persistent workspace files" />

Give the compact context file to your coding agent.

Run browser automation in the cloud

Sandboxes are the easiest way to run Browser-Use in production. We handle agents, browsers, persistence, auth, cookies, and LLMs. It is also the fastest way to deploy - the agent runs right next to the browser, so latency is minimal.

Get your API key at cloud.browser-use.com/new-api-key — eligible new accounts receive \$15 in one-time credits.

Basic Example

Wrap your function with @sandbox():

from browser_use import Browser, sandbox, ChatBrowserUse
from browser_use.agent.service import Agent

@sandbox()
async def my_task(browser: Browser):
    agent = Agent(task="Find the top HN post", browser=browser, llm=ChatBrowserUse())
    await agent.run()

await my_task()

With Cloud Parameters

@sandbox(
    cloud_profile_id='your-profile-id',      # Use saved cookies/auth
    cloud_proxy_country_code='us',           # Bypass captchas, cloudflare, geo-restrictions
    cloud_timeout=60,                        # Max session time (minutes)
)
async def task(browser: Browser, url: str):
    agent = Agent(task=f"Visit {url}", browser=browser, llm=ChatBrowserUse())
    await agent.run()

await task(url="https://example.com")

What each does:

• cloud_profile_id - Use saved cookies/authentication from your cloud profile
• cloud_proxy_country_code - Route through country-specific proxy for stealth (bypass captchas, Cloudflare, geo-blocks)
• cloud_timeout - Maximum time browser stays open in minutes

For more parameters and events, see the other tabs in this section.

Python library for AI browser automation with 79k+ GitHub stars. Connect any LLM and run locally or self-hosted.

<img alt="Browser Use Open Source" />

<img alt="Browser Use Open Source" />

Install and run your first agent.



Full SDK reference in a single page.

Try Browser Use Cloud for our SOTA model, stealth browsers, CAPTCHA solving, and managed infrastructure.