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
Improve OSS-to-cloud conversion: UTM tracking, better error messages, and cloud nudges
Alezander976569995fd92
diff --git a/README.md b/README.mdindex 61412a638..49314a492 100644--- a/README.md+++ b/README.md@@ -13,7 +13,7 @@</div><div align="center">-<a href="https://cloud.browser-use.com"><img src="https://media.browser-use.tools/badges/package" height="48" alt="Browser-Use Package Download Statistics"></a>+<a href="https://cloud.browser-use.com?utm_source=github&utm_medium=readme"><img src="https://media.browser-use.tools/badges/package" height="48" alt="Browser-Use Package Download Statistics"></a></div>---@@ -33,12 +33,12 @@<img width="4 height="1" alt=""><a href="https://link.browser-use.com/discord"><img src="https://media.browser-use.tools/badges/discord" alt="Discord"></a><img width="4" height="1" alt="">-<a href="https://cloud.browser-use.com"><img src="https://media.browser-use.tools/badges/cloud" height="48" alt="Browser-Use Cloud"></a>+<a href="https://cloud.browser-use.com?utm_source=github&utm_medium=readme"><img src="https://media.browser-use.tools/badges/cloud" height="48" alt="Browser-Use Cloud"></a></div></br>-🌤️ Want to skip the setup? Use our <b>[cloud](https://cloud.browser-use.com)</b> for faster, scalable, stealth-enabled browser automation!+🌤️ Want to skip the setup? Use our <b>[cloud](https://cloud.browser-use.com?utm_source=github&utm_medium=readme)</b> for faster, scalable, stealth-enabled browser automation!# 🤖 LLM Quickstart@@ -55,7 +55,7 @@ uv init && uv add browser-use && uv sync# uvx browser-use install # Run if you don't have Chromium installed```-**2. [Optional] Get your API key from [Browser Use Cloud](https://cloud.browser-use.com/new-api-key):**+**2. [Optional] Get your API key from [Browser Use Cloud](https://cloud.browser-use.com/new-api-key?utm_source=github&utm_medium=readme):**```# .envBROWSER_USE_API_KEY=your-key@@ -88,7 +88,7 @@ if __name__ == "__main__":asyncio.run(main())```-Check out the [library docs](https://docs.browser-use.com/open-source/introduction) and the [cloud docs](https://docs.cloud.browser-use.com) for more!+Check out the [library docs](https://docs.browser-use.com/open-source/introduction) and the [cloud docs](https://docs.cloud.browser-use.com?utm_source=github&utm_medium=readme) for more!<br/>@@ -102,20 +102,18 @@ Check out the [library docs](https://docs.browser-use.com/open-source/introductiWe benchmark Browser Use across 100 real-world browser tasks. Full benchmark is open source: **[browser-use/benchmark](https://github.com/browser-use/benchmark)**.-**Use Open Source**+**Use the Open-Source Agent**- You need [custom tools](https://docs.browser-use.com/customize/tools/basics) or deep code-level integration-- You want to self-host and deploy browser agents on your own machines+- We recommend pairing with our [cloud browsers](https://docs.browser-use.com/open-source/customize/browser/remote) for leading stealth, proxy rotation, and scaling+- Or self-host the open-source agent fully on your own machines-**Use [Cloud](https://cloud.browser-use.com) (recommended)**-- Much better agent for complex tasks (see plot above)+**Use the [Fully-Hosted Cloud Agent](https://cloud.browser-use.com?utm_source=github&utm_medium=readme) (recommended)**+- Much more powerful agent for complex tasks (see plot above)- Easiest way to start and scale- Best stealth with proxy rotation and captcha solving- 1000+ integrations (Gmail, Slack, Notion, and more)- Persistent filesystem and memory-**Use Both**-- Use the open-source library with your [custom tools](https://docs.browser-use.com/customize/tools/basics) while running our [cloud browsers](https://docs.browser-use.com/open-source/customize/browser/remote) and [ChatBrowserUse model](https://docs.browser-use.com/open-source/supported-models)-<br/># Demos@@ -273,7 +271,7 @@ These examples show how to maintain sessions and handle authentication seamlessl<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) which provides stealth browsers designed to avoid detection and CAPTCHA challenges.+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) which provides stealth browsers designed to avoid detection and CAPTCHA challenges.</details><details>@@ -281,7 +279,7 @@ For CAPTCHA handling, you need better browser fingerprinting and proxies. Use [BChrome can consume a lot of memory, and running many agents in parallel can be tricky to manage.-For production use cases, use our [Browser Use Cloud API](https://cloud.browser-use.com) which handles:+For production use cases, use our [Browser Use Cloud API](https://cloud.browser-use.com?utm_source=github&utm_medium=readme) which handles:- Scalable browser infrastructure- Memory management- Proxy rotationdiff --git a/browser_use/agent/service.py b/browser_use/agent/service.pyindex 877da1230..9b2fff1f2 100644--- a/browser_use/agent/service.py+++ b/browser_use/agent/service.py@@ -1647,8 +1647,10 @@ class Agent(Generic[Context, AgentStructuredOutput]):if judgement.failure_reason:judge_log += f' Failure Reason: {judgement.failure_reason}\n'if judgement.reached_captcha:- judge_log += ' 🤖 Captcha Detected: Agent encountered captcha challenges\n'- judge_log += ' 👉 🥷 Use Browser Use Cloud for the most stealth browser infra: https://docs.browser-use.com/customize/browser/remote\n'+ self.logger.warning(+ 'Agent was blocked by a captcha. Cloud browsers include stealth fingerprinting and proxy rotation to avoid this.\n'+ ' Try: Browser(use_cloud=True) | Get an API key: https://cloud.browser-use.com?utm_source=oss&utm_medium=captcha_nudge'+ )judge_log += f' {judgement.reasoning}\n'self.logger.info(judge_log)@@ -2160,11 +2162,10 @@ class Agent(Generic[Context, AgentStructuredOutput]):has_captcha_issue = any(keyword in final_result_str for keyword in captcha_keywords)if has_captcha_issue:- # Suggest use_cloud=True for captcha/cloudflare issues- task_preview = self.task[:10] if len(self.task) > 10 else self.task- self.logger.info('')- self.logger.info('Failed because of CAPTCHA? For better browser stealth, try:')- self.logger.info(f' agent = Agent(task="{task_preview}...", browser=Browser(use_cloud=True))')+ self.logger.warning(+ 'Agent was blocked by a captcha. Cloud browsers include stealth fingerprinting and proxy rotation to avoid this.\n'+ ' Try: Browser(use_cloud=True) | Get an API key: https://cloud.browser-use.com?utm_source=oss&utm_medium=captcha_nudge'+ )# General failure messageself.logger.info('')diff --git a/browser_use/browser/cloud/cloud.py b/browser_use/browser/cloud/cloud.pyindex 757b64dd4..c9670394d 100644--- a/browser_use/browser/cloud/cloud.py+++ b/browser_use/browser/cloud/cloud.py@@ -50,7 +50,8 @@ class CloudBrowserClient:if not api_token:raise CloudBrowserAuthError(- 'No authentication token found. Please set BROWSER_USE_API_KEY environment variable to authenticate with the cloud service. You can also create an API key at https://cloud.browser-use.com/new-api-key'+ 'BROWSER_USE_API_KEY is not set. To use cloud browsers, get a key at:\n'+ 'https://cloud.browser-use.com/new-api-key?utm_source=oss&utm_medium=use_cloud')headers = {'X-Browser-Use-API-Key': api_token, 'Content-Type': 'application/json', **(extra_headers or {})}@@ -65,7 +66,8 @@ class CloudBrowserClient:if response.status_code == 401:raise CloudBrowserAuthError(- 'Authentication failed. Please make sure you have set BROWSER_USE_API_KEY environment variable to authenticate with the cloud service. You can also create an API key at https://cloud.browser-use.com/new-api-key'+ 'BROWSER_USE_API_KEY is invalid. Get a new key at:\n'+ 'https://cloud.browser-use.com/new-api-key?utm_source=oss&utm_medium=use_cloud')elif response.status_code == 403:raise CloudBrowserAuthError('Access forbidden. Please check your browser-use cloud subscription status.')@@ -137,7 +139,8 @@ class CloudBrowserClient:if not api_token:raise CloudBrowserAuthError(- 'No authentication token found. Please set BROWSER_USE_API_KEY environment variable to authenticate with the cloud service. You can also create an API key at https://cloud.browser-use.com/new-api-key'+ 'BROWSER_USE_API_KEY is not set. To use cloud browsers, get a key at:\n'+ 'https://cloud.browser-use.com/new-api-key?utm_source=oss&utm_medium=use_cloud')headers = {'X-Browser-Use-API-Key': api_token, 'Content-Type': 'application/json', **(extra_headers or {})}diff --git a/browser_use/browser/session.py b/browser_use/browser/session.pyindex c2e799da6..8ebddac20 100644--- a/browser_use/browser/session.py+++ b/browser_use/browser/session.py@@ -749,9 +749,7 @@ class BrowserSession(BaseModel):self.browser_profile.is_local = Falseself.logger.info('🌤️ Successfully connected to cloud browser service')except CloudBrowserAuthError:- raise CloudBrowserAuthError(- 'Authentication failed for cloud browser service. Set BROWSER_USE_API_KEY environment variable. You can also create an API key at https://cloud.browser-use.com/new-api-key'- )+ raiseexcept CloudBrowserError as e:raise CloudBrowserError(f'Failed to create cloud browser: {e}')elif self.is_local:@@ -836,6 +834,11 @@ class BrowserSession(BaseModel):details={'cdp_url': self.cdp_url, 'is_local': self.is_local},))+ if self.is_local and not isinstance(e, (CloudBrowserAuthError, CloudBrowserError)):+ self.logger.warning(+ 'Local browser failed to start. Cloud browsers require no local install and work out of the box.\n'+ ' Try: Browser(use_cloud=True) | Get an API key: https://cloud.browser-use.com?utm_source=oss&utm_medium=browser_launch_failure'+ )raiseasync def on_NavigateToUrlEvent(self, event: NavigateToUrlEvent) -> None:diff --git a/browser_use/cli.py b/browser_use/cli.pyindex 1534b8ae3..631239146 100644--- a/browser_use/cli.py+++ b/browser_use/cli.py@@ -129,7 +129,7 @@ if '--template' in sys.argv:click.echo(' uv pip install browser-use')click.echo(' 2. Set up your API key in .env file or environment:')click.echo(' BROWSER_USE_API_KEY=your-key')- click.echo(' (Get your key at https://cloud.browser-use.com/new-api-key)')+ click.echo(' (Get your key at https://cloud.browser-use.com/new-api-key?utm_source=oss&utm_medium=cli)')click.echo(' 3. Run your script:')click.echo(f' python {output_path.name}')except Exception as e:@@ -178,9 +178,12 @@ except ImportError:try:import readline+ _add_history = getattr(readline, 'add_history', None)+ if _add_history is None:+ raise ImportError('readline missing add_history')READLINE_AVAILABLE = Trueexcept ImportError:- # readline not available on Windows by default+ _add_history = NoneREADLINE_AVAILABLE = False@@ -341,12 +344,11 @@ def update_config_with_click_args(config: dict[str, Any], ctx: click.Context) ->def setup_readline_history(history: list[str]) -> None:"""Set up readline with command history."""- if not READLINE_AVAILABLE:+ if not _add_history:return- # Add history items to readlinefor item in history:- readline.add_history(item)+ _add_history(item)def get_llm(config: dict[str, Any]):@@ -718,9 +720,9 @@ class BrowserUseApp(App):# Step 2: Set up input historylogger.debug('Setting up readline history...')try:- if READLINE_AVAILABLE and self.task_history:+ if READLINE_AVAILABLE and self.task_history and _add_history:for item in self.task_history:- readline.add_history(item)+ _add_history(item)logger.debug(f'Added {len(self.task_history)} items to readline history')else:logger.debug('No readline history to set up')@@ -1127,7 +1129,7 @@ class BrowserUseApp(App):# Exit the applicationself.exit()- print('\nTry running tasks on our cloud: https://browser-use.com')+ print('\nTry running tasks on our cloud: https://browser-use.com?utm_source=oss&utm_medium=cli')def compose(self) -> ComposeResult:"""Create the UI layout."""@@ -1142,7 +1144,11 @@ class BrowserUseApp(App):with Container(id='links-panel'):with HorizontalGroup(classes='link-row'):yield Static('Run at scale on cloud: [blink]☁️[/] ', markup=True, classes='link-label')- yield Link('https://browser-use.com', url='https://browser-use.com', classes='link-white link-url')+ yield Link(+ 'https://browser-use.com',+ url='https://browser-use.com?utm_source=oss&utm_medium=cli',+ classes='link-white link-url',+ )yield Static('') # Empty line@@ -2222,7 +2228,7 @@ def _run_template_generation(template: str, output: str | None, force: bool):click.echo(' uv pip install browser-use')click.echo(' 2. Set up your API key in .env file or environment:')click.echo(' BROWSER_USE_API_KEY=your-key')- click.echo(' (Get your key at https://cloud.browser-use.com/new-api-key)')+ click.echo(' (Get your key at https://cloud.browser-use.com/new-api-key?utm_source=oss&utm_medium=cli)')click.echo(' 3. Run your script:')click.echo(f' python {output_path.name}')else:@@ -2351,7 +2357,7 @@ def init(click.echo(' uv pip install browser-use')click.echo(' 2. Set up your API key in .env file or environment:')click.echo(' BROWSER_USE_API_KEY=your-key')- click.echo(' (Get your key at https://cloud.browser-use.com/new-api-key)')+ click.echo(' (Get your key at https://cloud.browser-use.com/new-api-key?utm_source=oss&utm_medium=cli)')click.echo(' 3. Run your script:')click.echo(f' python {output_path.name}')else:diff --git a/browser_use/init_cmd.py b/browser_use/init_cmd.pyindex 9353d0620..3e25a7a15 100644--- a/browser_use/init_cmd.py+++ b/browser_use/init_cmd.py@@ -428,7 +428,7 @@ def main(next_steps.append('4. Set up your API key in .env file or environment:\n', style='bold')next_steps.append(' BROWSER_USE_API_KEY=your-key\n', style='dim')next_steps.append(- ' (Get your key at https://cloud.browser-use.com/dashboard/settings?tab=api-keys&new)\n\n',+ ' (Get your key at https://cloud.browser-use.com/dashboard/settings?tab=api-keys&new&utm_source=oss&utm_medium=cli)\n\n',style='dim italic',)next_steps.append('5. Run your script:\n', style='bold')diff --git a/browser_use/llm/browser_use/chat.py b/browser_use/llm/browser_use/chat.pyindex 26b73b12d..0395ffaa5 100644--- a/browser_use/llm/browser_use/chat.py+++ b/browser_use/llm/browser_use/chat.py@@ -90,8 +90,8 @@ class ChatBrowserUse(BaseChatModel):if not self.api_key:raise ValueError(- 'You need to set the BROWSER_USE_API_KEY environment variable. '- 'Get your key at https://cloud.browser-use.com/new-api-key'+ 'BROWSER_USE_API_KEY is not set. To use ChatBrowserUse, get a key at:\n'+ 'https://cloud.browser-use.com/new-api-key?utm_source=oss&utm_medium=chat_browser_use')@property@@ -275,9 +275,17 @@ class ChatBrowserUse(BaseChatModel):status_code = e.response.status_codeif status_code == 401:- raise ModelProviderError(message=f'Invalid API key. {error_detail}', status_code=401, model=self.name)+ raise ModelProviderError(+ message=f'BROWSER_USE_API_KEY is invalid. Get a new key at:\nhttps://cloud.browser-use.com/new-api-key?utm_source=oss&utm_medium=chat_browser_use\n{error_detail}',+ status_code=401,+ model=self.name,+ )elif status_code == 402:- raise ModelProviderError(message=f'Insufficient credits. {error_detail}', status_code=402, model=self.name)+ raise ModelProviderError(+ message=f'Browser Use credits exhausted. Add more at:\nhttps://cloud.browser-use.com/billing?utm_source=oss&utm_medium=chat_browser_use\n{error_detail}',+ status_code=402,+ model=self.name,+ )elif status_code == 429:raise ModelRateLimitError(message=f'Rate limit exceeded. {error_detail}', status_code=429, model=self.name)elif status_code in {500, 502, 503, 504}:diff --git a/browser_use/skill_cli/commands/cloud.py b/browser_use/skill_cli/commands/cloud.pyindex 630273b08..198d0bc1c 100644--- a/browser_use/skill_cli/commands/cloud.py+++ b/browser_use/skill_cli/commands/cloud.py@@ -90,7 +90,10 @@ def _get_api_key() -> str:print(' Note: BROWSER_USE_API_KEY env var is set but not used by the CLI.', file=sys.stderr)print(' Run: browser-use config set api_key "$BROWSER_USE_API_KEY"', file=sys.stderr)else:- print('Already have an account? Get a key at: https://cloud.browser-use.com/settings?tab=api-keys&new=1', file=sys.stderr)+ print(+ 'Already have an account? Get a key at: https://cloud.browser-use.com/settings?tab=api-keys&new=1&utm_source=oss&utm_medium=cli',+ file=sys.stderr,+ )print(' Then run: browser-use cloud login <key>', file=sys.stderr)print('No account? Run: browser-use cloud signup', file=sys.stderr)print(' This creates an agent account you can claim later with: browser-use cloud signup --claim', file=sys.stderr)