Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

Improve OSS-to-cloud conversion: UTM tracking, better error messages, and cloud nudges

Alezander976569995fd92
diff --git a/README.md b/README.md
index 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):**
```
# .env
BROWSER_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/introducti
We 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 [B
Chrome 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 rotation
diff --git a/browser_use/agent/service.py b/browser_use/agent/service.py
index 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 message
self.logger.info('')
diff --git a/browser_use/browser/cloud/cloud.py b/browser_use/browser/cloud/cloud.py
index 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.py
index 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 = False
self.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'
- )
+ raise
except 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'
+ )
raise
async def on_NavigateToUrlEvent(self, event: NavigateToUrlEvent) -> None:
diff --git a/browser_use/cli.py b/browser_use/cli.py
index 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 = True
except ImportError:
- # readline not available on Windows by default
+ _add_history = None
READLINE_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 readline
for 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 history
logger.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 application
self.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.py
index 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.py
index 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_code
if 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.py
index 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)