Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.
Python ai-agentsai-toolsbrowser-agentbrowser-automationbrowser-usecdpcloud-browsercomputer-useheadless-browserllmmcpplaywrightpythonremote-browserstealth-browserweb-automationweb-scraping
docs: refresh README quickstart and FAQ
MagMuellerbfc01ebfad2b
diff --git a/README.md b/README.mdindex 00c61571a..db1decc1b 100644--- a/README.md+++ b/README.md@@ -61,7 +61,7 @@ Find an available slot, pick a date and time, handle the CAPTCHA, and book a dri</picture>- **[Path 1: Fully Hosted Cloud](#path-1-fully-hosted-cloud):** Send a task through the API; we run the agent and browser.-- **[Path 2: CLI](#path-2-cli):** Give Claude Code, Codex, OpenCode, Pi, or another agent browser access.+- **[Path 2: CLI](#path-2-cli):** Give Claude Code, Codex, Hermes, OpenClaw, OpenCode, Pi, or another agent browser access.- **[Path 3: Python Library](#path-3-python-library):** Run the open source Browser Use agent locally from your own code.# Quickstart@@ -78,7 +78,7 @@ New Google, GitHub, or Microsoft signups get **$15 cloud credit**.## Path 2: CLI-If you want to use Browser Use in your agent (Claude Code, Codex, OpenCode, Pi, Cursor, Hermes, OpenClaw, etc.), paste this prompt, and it sets everything up itself:+If you want to use Browser Use in your agent (Claude Code, Codex, Hermes, OpenClaw, OpenCode, Pi, Cursor, etc.), paste this prompt, and it sets everything up itself:```textInstall or upgrade browser-use to the latest stable version with uv using Python 3.12, run `browser-use skill install` to register the skill, and connect it to my browser. If setup or connection fails, follow https://github.com/browser-use/browser-harness/blob/main/install.md.@@ -94,9 +94,10 @@ Run the Browser Use agent locally from Python, with your choice of model and a l**1. Install Browser Use (Python >= 3.11):**+With [uv](https://docs.astral.sh/uv/getting-started/installation/) installed, run `uv init --python 3.12` first if you're starting a new project.+```bashuv add browser-use-# or: pip install browser-use```**2. Add your [OpenAI API key](https://platform.openai.com/api-keys) to `.env`:**@@ -104,29 +105,46 @@ uv add browser-use```bash# .envOPENAI_API_KEY=your-key+# BROWSER_USE_API_KEY=your-key # Optional: BU2 model or cloud browser```-**3. Run your first agent:**+For either optional Browser Use service, get a [Browser Use API key](https://cloud.browser-use.com/new-api-key).++**3. Save this as `agent.py`:**```pythonimport asyncio-from browser_use import Agent, ChatOpenAI+from browser_use import Agent, Browser, ChatBrowserUse, ChatOpenAIfrom dotenv import load_dotenvload_dotenv()async def main():+ llm = ChatOpenAI(model='gpt-5.6-luna', reasoning_effort='xhigh')+ # llm = ChatBrowserUse(model='bu-2-0') # Use BU2 instead; requires BROWSER_USE_API_KEYagent = Agent(task="Find the number of stars of the browser-use repo",- llm=ChatOpenAI(model='gpt-5.6-luna', reasoning_effort='xhigh'),+ llm=llm,+ # browser=Browser(use_cloud=True), # Use a cloud browser; requires BROWSER_USE_API_KEY)history = await agent.run()+ print(history.final_result())if __name__ == "__main__":asyncio.run(main())```+To use BU2, replace the `ChatOpenAI` line with the commented `ChatBrowserUse` line. The cloud-browser option works with either model.++**4. Run it:**++```bash+uv run agent.py+```++The agent opens a browser, looks up the repository, and prints its answer.+[Python library docs ↗](https://docs.browser-use.com/open-source/introduction)<br/>@@ -144,33 +162,27 @@ This [very hard benchmark](https://github.com/browser-use/benchmark) targets the# FAQ<details>-<summary><b>Should I use the CLI vs. the Python library?</b></summary>--**Use the CLI** if you already have an agent (Claude Code, Codex, OpenCode, Pi, Cursor, Hermes, OpenClaw, etc.) that you want to complete browser tasks for you. The agent installs the skill once (see [CLI quickstart](#path-2-cli)) and can then control the browser. Examples:-- "Upload this video to YouTube"-- "Compare these three laptops and give me a table with prices"-- "Fill in this job application with my resume"+<summary><b>Should I use the fully hosted cloud, CLI, or Python library?</b></summary>-**Use the Python library** when you are building software that automates the web. Examples:-- Run many tasks on a schedule or in parallel (scraping, monitoring, QA)-- Embed a browser agent into your own product-- Custom tools, custom system prompts, structured output, fine-grained browser control+- **[Fully Hosted Cloud](#path-1-fully-hosted-cloud):** Send tasks through the API and let Browser Use run the agent, browser, and infrastructure.+- **[CLI](#path-2-cli):** Give an existing agent (Claude Code, Codex, Hermes, OpenClaw, OpenCode, Pi, Cursor, etc.) browser access. You can use it interactively or in scripts.+- **[Python Library](#path-3-python-library):** Run the open source agent in your own application, with custom tools, structured output, and your choice of model.-Rule of thumb: one-off tasks through an agent → CLI. Repeatable automation in code → Python library.+The CLI and Python library can each connect to a local or cloud browser. A cloud browser hosts the browser; the fully hosted API runs the agent as well.</details><details><summary><b>What's the best model to use?</b></summary>-We optimized **ChatBrowserUse()** specifically for browser automation tasks. On avg it completes tasks 3-5x faster than other models with SOTA accuracy.+We recommend **BU2**, our model optimized for browser automation: `ChatBrowserUse(model='bu-2-0')`. It uses `BROWSER_USE_API_KEY`; `ChatBrowserUse()` currently selects the same model.-For pricing and other LLM providers, see our [supported models documentation](https://docs.browser-use.com/supported-models).+The best choice depends on your tasks, latency, and budget. See the [BU2 model card](https://docs.browser-use.com/open-source/bu-2-0-model-card), [benchmark](https://github.com/browser-use/benchmark), and [supported models and pricing](https://docs.browser-use.com/open-source/supported-models) to compare options.</details><details><summary><b>Can I use Claude / GPT / Gemini through ChatBrowserUse?</b></summary>-Yes. `ChatBrowserUse` accepts provider-prefixed model ids, so a single `BROWSER_USE_API_KEY` reaches all of them — no separate OpenAI/Anthropic/Google keys required:+Yes. `ChatBrowserUse` accepts provider-prefixed model IDs through the Browser Use gateway, using `BROWSER_USE_API_KEY`:```pythonfrom browser_use import Agent, ChatBrowserUse@@ -179,39 +191,47 @@ llm = ChatBrowserUse(model='anthropic/claude-sonnet-4-6') # or 'google/gemini-3agent = Agent(task='...', llm=llm)```-For the best speed and cost we still recommend the default `bu-*` models.+You can also use providers directly through wrappers such as `ChatOpenAI`, `ChatAnthropic`, and `ChatGoogle`, with each provider's own API key. See [supported models](https://docs.browser-use.com/open-source/supported-models).</details><details>-<summary><b>Should I use the Browser Use system prompt with the open-source preview model?</b></summary>+<summary><b>Do I need to provide a system prompt?</b></summary>-Yes. If you use `ChatBrowserUse(model='browser-use/bu-30b-a3b-preview')` with a normal `Agent(...)`, Browser Use still sends its default agent system prompt for you.+No. `Agent(...)` supplies the Browser Use system prompt automatically, including when you change models. Put your task in `task=`. Use `extend_system_message` to add instructions or `override_system_message` to replace the default prompt when you need custom behavior.-You do **not** need to add a separate custom "Browser Use system message" just because you switched to the open-source preview model. Only use `extend_system_message` or `override_system_message` when you intentionally want to customize the default behavior for your task.--If you want the best default speed/accuracy, we still recommend the newer hosted `bu-*` models. If you want the open-source preview model, the setup stays the same apart from the `model=` value.+See the [custom system prompt example](https://github.com/browser-use/browser-use/blob/main/examples/features/custom_system_prompt.py).</details><details><summary><b>Can I use custom tools with the agent?</b></summary>-Yes! You can add custom tools to extend the agent's capabilities:+Yes. Register a function with `Tools` and pass it to the agent. This example adds a tool for the current UTC time and uses `BROWSER_USE_API_KEY` from `.env`:```python-from browser_use import Tools+import asyncio+from datetime import datetime, timezone+from browser_use import ActionResult, Agent, ChatBrowserUse, Tools+from dotenv import load_dotenv++load_dotenv()tools = Tools()[email protected](description='Description of what this tool does.')-def custom_tool(param: str) -> str:- return f"Result: {param}"[email protected](description='Get the current date and time in UTC.')+def get_current_time() -> ActionResult:+ return ActionResult(extracted_content=datetime.now(timezone.utc).isoformat())-agent = Agent(- task="Your task",- llm=llm,- browser=browser,- tools=tools,-)+async def main():+ agent = Agent(+ task="What is the current UTC time?",+ llm=ChatBrowserUse(model='bu-2-0'),+ tools=tools,+ )+ history = await agent.run()+ print(history.final_result())++if __name__ == "__main__":+ asyncio.run(main())```</details>@@ -219,7 +239,7 @@ agent = Agent(<details><summary><b>Can I use this for free?</b></summary>-Yes! Browser-Use is open source and free to use. You only need to choose an LLM provider (like OpenAI, Google, ChatBrowserUse, or run local models with Ollama).+The Python library is free and [MIT-licensed](LICENSE). Model inference and hosted browsers are separate: API providers, including `ChatBrowserUse`, and Browser Use Cloud charge for usage. You can also use a local browser and a local model through [Ollama](https://docs.browser-use.com/open-source/supported-models#ollama), subject to your hardware and model requirements.</details><details>@@ -231,31 +251,29 @@ This open-source library is licensed under the MIT License. For Browser Use serv<details><summary><b>How do I handle authentication?</b></summary>-Check out our authentication examples:-- [Using real browser profiles](https://github.com/browser-use/browser-use/blob/main/examples/browser/real_browser.py) - Reuse your existing Chrome profile with saved logins-- If you want to use temporary accounts with inbox, choose AgentMail-- To sync your auth profile with a remote browser, install `profile-use` for your platform from the [official releases](https://github.com/browser-use/profile-use-releases/releases/latest), then follow the [profile sync guide](https://github.com/browser-use/browser-harness/blob/main/interaction-skills/profile-sync.md).+- **Local browser:** Use `Browser.from_system_chrome()` to reuse a Chrome profile. See the [real-browser guide](https://docs.browser-use.com/open-source/customize/browser/real-browser) and [example](https://github.com/browser-use/browser-use/blob/main/examples/browser/real_browser.py).+- **Cloud browser:** Follow the [profile sync guide](https://github.com/browser-use/browser-harness/blob/main/interaction-skills/profile-sync.md), then use `Browser(use_cloud=True, cloud_profile_id='your-profile-id')`.-These examples show how to maintain sessions and handle authentication seamlessly.+Profile sync transfers cookies, not local storage, IndexedDB, or extensions. Some sites may require you to sign in again.</details><details><summary><b>How do I solve CAPTCHAs?</b></summary>-For CAPTCHA handling, you need better browser fingerprinting and proxies. Use [Browser Use Cloud](https://cloud.browser-use.com?utm_source=github&utm_medium=readme-faq-captcha) which provides stealth browsers designed to avoid detection and CAPTCHA challenges.+[Browser Use Cloud](https://docs.browser-use.com/cloud/browser/quickstart) provides stealth browsers and proxies designed to reduce bot detection and CAPTCHA challenges. With the Python library, enable a cloud browser with `Browser(use_cloud=True)` and set `BROWSER_USE_API_KEY`.++Results depend on the site and challenge; no browser configuration guarantees that every CAPTCHA can be avoided or solved.</details><details><summary><b>How do I go into production?</b></summary>-Chrome can consume a lot of memory, and running many agents in parallel can be tricky to manage.+Choose how much you want to manage:++- **Keep your agent code:** Connect the CLI or Python library to [cloud browsers](https://docs.browser-use.com/cloud/browser/quickstart) for managed browser infrastructure, stealth, profiles, and recordings.+- **Have us run the agent too:** Use the [fully hosted Cloud API](https://docs.browser-use.com/cloud/agent/quickstart) to submit tasks and retrieve results.-For production use cases, use our [Browser Use Cloud API](https://cloud.browser-use.com?utm_source=github&utm_medium=readme-faq-production) which handles:-- Scalable browser infrastructure-- Memory management-- Proxy rotation-- Stealth browser fingerprinting-- High-performance parallel execution+You can also host the Python library and browsers on your own infrastructure.</details><br/>diff --git a/static/readme/which-product-dark.svg b/static/readme/which-product-dark.svgindex 4cb1de917..7365cedc9 100644--- a/static/readme/which-product-dark.svg+++ b/static/readme/which-product-dark.svg@@ -1,6 +1,6 @@<svg xmlns="http://www.w3.org/2000/svg" width="1440" height="690" viewBox="0 0 1440 690" role="img" aria-labelledby="title desc"><title id="title">Three ways to use Browser Use</title>- <desc id="desc">Path 1: fully hosted cloud runs our OpenCode agent, Browser Use CLI, and a cloud browser through the V4 API. Path 2: the CLI connects your existing agent, including Claude Code, Codex, OpenCode, Hermes, or Pi, to a local or cloud browser. Path 3: the open source Browser Use agent is a Python library that connects directly to a local or cloud browser.</desc>+ <desc id="desc">Path 1: fully hosted cloud runs our OpenCode agent, Browser Use CLI, and a cloud browser through the V4 API. Path 2: the CLI connects your existing agent, including Claude Code, Codex, Hermes, OpenClaw, OpenCode, or Pi, to a local or cloud browser. Path 3: the open source Browser Use agent is a Python library that connects directly to a local or cloud browser.</desc><defs><marker id="arrow" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M0 0L8 4L0 8Z" fill="#92929C"/></marker><marker id="cloud-arrow" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M0 0L8 4L0 8Z" fill="#FFAB66"/></marker>@@ -23,8 +23,8 @@<text x="240" y="260" text-anchor="middle" fill="#FAFAFA" font-size="29" font-weight="750">OpenCode</text><rect x="520" y="184" width="400" height="112" rx="16" fill="#29292E" stroke="#92929C" stroke-width="2"/><text x="720" y="214" text-anchor="middle" fill="#BDBDC5" font-size="18" font-weight="700">YOUR AGENT</text>- <text x="720" y="247" text-anchor="middle" fill="#FAFAFA" font-size="24" font-weight="600">Claude Code · Codex</text>- <text x="720" y="278" text-anchor="middle" fill="#FAFAFA" font-size="24" font-weight="600">OpenCode · Hermes · Pi</text>+ <text x="720" y="247" text-anchor="middle" fill="#FAFAFA" font-size="22" font-weight="600">Claude Code · Codex · Pi</text>+ <text x="720" y="278" text-anchor="middle" fill="#FAFAFA" font-size="22" font-weight="600">Hermes · OpenClaw · OpenCode</text><rect x="992" y="184" width="400" height="244" rx="16" fill="#302419" stroke="#FFAB66" stroke-width="2"/><text x="1192" y="262" text-anchor="middle" fill="#FFAB66" font-size="20" font-weight="700">OPEN SOURCE</text><text x="1192" y="313" text-anchor="middle" fill="#FAFAFA" font-size="31" font-weight="750">Browser Use Agent</text>diff --git a/static/readme/which-product-light.svg b/static/readme/which-product-light.svgindex 0ce0f9fc0..7d893c825 100644--- a/static/readme/which-product-light.svg+++ b/static/readme/which-product-light.svg@@ -1,6 +1,6 @@<svg xmlns="http://www.w3.org/2000/svg" width="1440" height="690" viewBox="0 0 1440 690" role="img" aria-labelledby="title desc"><title id="title">Three ways to use Browser Use</title>- <desc id="desc">Path 1: fully hosted cloud runs our OpenCode agent, Browser Use CLI, and a cloud browser through the V4 API. Path 2: the CLI connects your existing agent, including Claude Code, Codex, OpenCode, Hermes, or Pi, to a local or cloud browser. Path 3: the open source Browser Use agent is a Python library that connects directly to a local or cloud browser.</desc>+ <desc id="desc">Path 1: fully hosted cloud runs our OpenCode agent, Browser Use CLI, and a cloud browser through the V4 API. Path 2: the CLI connects your existing agent, including Claude Code, Codex, Hermes, OpenClaw, OpenCode, or Pi, to a local or cloud browser. Path 3: the open source Browser Use agent is a Python library that connects directly to a local or cloud browser.</desc><defs><marker id="arrow" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M0 0L8 4L0 8Z" fill="#8B8B94"/></marker><marker id="cloud-arrow" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M0 0L8 4L0 8Z" fill="#C94D00"/></marker>@@ -23,8 +23,8 @@<text x="240" y="260" text-anchor="middle" fill="#242428" font-size="29" font-weight="750">OpenCode</text><rect x="520" y="184" width="400" height="112" rx="16" fill="#F4F4F5" stroke="#8B8B94" stroke-width="2"/><text x="720" y="214" text-anchor="middle" fill="#606068" font-size="18" font-weight="700">YOUR AGENT</text>- <text x="720" y="247" text-anchor="middle" fill="#242428" font-size="24" font-weight="600">Claude Code · Codex</text>- <text x="720" y="278" text-anchor="middle" fill="#242428" font-size="24" font-weight="600">OpenCode · Hermes · Pi</text>+ <text x="720" y="247" text-anchor="middle" fill="#242428" font-size="22" font-weight="600">Claude Code · Codex · Pi</text>+ <text x="720" y="278" text-anchor="middle" fill="#242428" font-size="22" font-weight="600">Hermes · OpenClaw · OpenCode</text><rect x="992" y="184" width="400" height="244" rx="16" fill="#FFF4E8" stroke="#C94D00" stroke-width="2"/><text x="1192" y="262" text-anchor="middle" fill="#C94D00" font-size="20" font-weight="700">OPEN SOURCE</text><text x="1192" y="313" text-anchor="middle" fill="#242428" font-size="31" font-weight="750">Browser Use Agent</text>