feat: added cloud_browser feature

.github/ISSUE_TEMPLATE/2_bug_report.yml

@@ -14,7 +14,7 @@ body:
         ---
         > [!IMPORTANT]
         > 🙏 Please **go check *right now before filling this out* that you are *actually* on the [⬆️ LATEST VERSION](https://github.com/browser-use/browser-use/releases)**.
-        > 🚀 We ship changes every hour and we might've already fixed your issue today!  
+        > 🚀 We ship changes every hour and we might've already fixed your issue today!
         > <a href="https://github.com/browser-use/browser-use/releases"><img src="https://github.com/user-attachments/assets/4cd34ee6-bafb-4f24-87e2-27a31dc5b9a4" width="500px"/></a>
         > If you are running an old version, the **first thing we will ask you to do is *upgrade to the latest version* and try again**:
         > - 🆕 [`beta`](https://docs.browser-use.com/development/local-setup):   `uv pip install --upgrade git+https://github.com/browser-use/browser-use.git@main`
@@ -25,7 +25,7 @@ body:
     attributes:
       label: Browser Use Version
       description: |
-        What exact version of `browser-use` are you using? (Run `uv pip show browser-use` or `git log -n 1`)  
+        What exact version of `browser-use` are you using? (Run `uv pip show browser-use` or `git log -n 1`)
         **DO NOT WRITE `latest release` or `main` or a very old version or we will close your issue!**
       placeholder: "e.g. 0.4.45 or 62760baaefd"
     validations:
@@ -58,7 +58,7 @@ body:
 
         agent = Agent(
             task='...',
-            llm=ChatOpenAI(model="gpt-4o"),
+            llm=ChatOpenAI(model="gpt-4.1-mini"),
             browser_session=BrowserSession(headless=False),
         )
         ...
@@ -70,8 +70,6 @@ body:
       description: Which LLM model(s) are you using?
       multiple: true
       options:
-        - gpt-4o
-        - gpt-4o-mini
         - gpt-4
         - gpt-4.1
         - gpt-4.1-mini

README.md

@@ -15,20 +15,20 @@
 [![Weave Badge](https://img.shields.io/endpoint?url=https%3A%2F%2Fapp.workweave.ai%2Fapi%2Frepository%2Fbadge%2Forg_T5Pvn3UBswTHIsN1dWS3voPg%2F881458615&labelColor=#EC6341)](https://app.workweave.ai/reports/repository/org_T5Pvn3UBswTHIsN1dWS3voPg/881458615)
 
 <!-- Keep these links. Translations will automatically update with the README. -->
-[Deutsch](https://www.readme-i18n.com/browser-use/browser-use?lang=de) | 
-[Español](https://www.readme-i18n.com/browser-use/browser-use?lang=es) | 
-[français](https://www.readme-i18n.com/browser-use/browser-use?lang=fr) | 
-[日本語](https://www.readme-i18n.com/browser-use/browser-use?lang=ja) | 
-[한국어](https://www.readme-i18n.com/browser-use/browser-use?lang=ko) | 
-[Português](https://www.readme-i18n.com/browser-use/browser-use?lang=pt) | 
-[Русский](https://www.readme-i18n.com/browser-use/browser-use?lang=ru) | 
+[Deutsch](https://www.readme-i18n.com/browser-use/browser-use?lang=de) |
+[Español](https://www.readme-i18n.com/browser-use/browser-use?lang=es) |
+[français](https://www.readme-i18n.com/browser-use/browser-use?lang=fr) |
+[日本語](https://www.readme-i18n.com/browser-use/browser-use?lang=ja) |
+[한국어](https://www.readme-i18n.com/browser-use/browser-use?lang=ko) |
+[Português](https://www.readme-i18n.com/browser-use/browser-use?lang=pt) |
+[Русский](https://www.readme-i18n.com/browser-use/browser-use?lang=ru) |
 [中文](https://www.readme-i18n.com/browser-use/browser-use?lang=zh)
 
 🌤️ Want to skip the setup? Use our <b>[cloud](https://cloud.browser-use.com)</b> for faster, scalable, stealth-enabled browser automation!
 
-**🚀 Use the latest version!** 
+**🚀 Use the latest version!**
 
-> We ship every day improvements for **speed**, **accuracy**, and **UX**. 
+> We ship every day improvements for **speed**, **accuracy**, and **UX**.
 > ```bash
 > uv pip install --upgrade browser-use
 > ```
@@ -74,6 +74,22 @@ OPENAI_API_KEY=
 
 For other settings, models, and more, check out the [documentation 📕](https://docs.browser-use.com).
 
+**🌤️ Want to use cloud browsers?** Simply add `cloud_browser=True` to your Browser config:
+
+```python
+from browser_use import Agent, Browser, ChatOpenAI
+
+agent = Agent(
+    task="Find the number of stars of the browser-use repo",
+    llm=ChatOpenAI(model="gpt-4.1-mini"),
+    browser=Browser(cloud_browser=True),  # Uses Browser-Use cloud service
+)
+```
+
+First Set BROWSER_USE_API_KEY environment variable. You can get your API key from [here](https://cloud.browser-use.com).
+
+For other settings, models, and more, check out the [Cloud documentation 📕](https://docs.cloud.browser-use.com).
+
 # Demos
 
 <br/><br/>
@@ -254,11 +270,11 @@ If you use Browser Use in your research or project, please cite:
 }
 ```
 
- <div align="center"> <img src="https://github.com/user-attachments/assets/06fa3078-8461-4560-b434-445510c1766f" width="400"/> 
- 
+ <div align="center"> <img src="https://github.com/user-attachments/assets/06fa3078-8461-4560-b434-445510c1766f" width="400"/>
+
 [![Twitter Follow](https://img.shields.io/twitter/follow/Gregor?style=social)](https://x.com/intent/user?screen_name=gregpr07)
 [![Twitter Follow](https://img.shields.io/twitter/follow/Magnus?style=social)](https://x.com/intent/user?screen_name=mamagnus00)
- 
+
  </div>
 
 <div align="center">

browser_use/browser/cloud.py

@@ -0,0 +1,286 @@
+"""Cloud browser service integration for browser-use.
+
+This module provides integration with the browser-use cloud browser service.
+When cloud_browser=True, it automatically creates a cloud browser instance
+and returns the CDP URL for connection.
+"""
+
+import logging
+import os
+
+import httpx
+from pydantic import BaseModel, Field
+
+from browser_use.sync.auth import CloudAuthConfig
+
+logger = logging.getLogger(__name__)
+
+
+class CloudBrowserResponse(BaseModel):
+	"""Response from cloud browser API."""
+
+	id: str
+	status: str
+	liveUrl: str = Field(alias='liveUrl')
+	cdpUrl: str = Field(alias='cdpUrl')
+	timeoutAt: str = Field(alias='timeoutAt')
+	startedAt: str = Field(alias='startedAt')
+	finishedAt: str | None = Field(alias='finishedAt', default=None)
+
+
+class CloudBrowserError(Exception):
+	"""Exception raised when cloud browser operations fail."""
+
+	pass
+
+
+class CloudBrowserAuthError(CloudBrowserError):
+	"""Exception raised when cloud browser authentication fails."""
+
+	pass
+
+
+class CloudBrowserClient:
+	"""Client for browser-use cloud browser service."""
+
+	def __init__(self, api_base_url: str = 'https://api.browser-use.com'):
+		self.api_base_url = api_base_url
+		self.client = httpx.AsyncClient(timeout=30.0)
+		self.current_session_id: str | None = None
+
+	async def create_browser(self) -> CloudBrowserResponse:
+		"""Create a new cloud browser instance.
+
+		Returns:
+			CloudBrowserResponse: Contains CDP URL and other browser info
+
+		Raises:
+			CloudBrowserAuthError: If authentication fails
+			CloudBrowserError: If browser creation fails
+		"""
+		url = f'{self.api_base_url}/api/v2/browsers'
+
+		# Try to get API key from environment variable first, then auth config
+		api_token = os.getenv('BROWSER_USE_API_KEY')
+
+		if not api_token:
+			# Fallback to auth config file
+			try:
+				auth_config = CloudAuthConfig.load_from_file()
+				api_token = auth_config.api_token
+			except Exception:
+				pass
+
+		if not api_token:
+			raise CloudBrowserAuthError(
+				'No authentication token found. Please set BROWSER_USE_API_KEY environment variable to authenticate with the cloud service.'
+			)
+
+		headers = {'X-Browser-Use-API-Key': api_token, 'Content-Type': 'application/json'}
+
+		# Empty request body as per API specification
+		request_body = {}
+
+		try:
+			logger.info('🌤️ Creating cloud browser instance...')
+
+			response = await self.client.post(url, headers=headers, json=request_body)
+
+			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.'
+				)
+			elif response.status_code == 403:
+				raise CloudBrowserAuthError('Access forbidden. Please check your browser-use cloud subscription status.')
+			elif not response.is_success:
+				error_msg = f'Failed to create cloud browser: HTTP {response.status_code}'
+				try:
+					error_data = response.json()
+					if 'detail' in error_data:
+						error_msg += f' - {error_data["detail"]}'
+				except Exception:
+					pass
+				raise CloudBrowserError(error_msg)
+
+			browser_data = response.json()
+			browser_response = CloudBrowserResponse(**browser_data)
+
+			# Store session ID for cleanup
+			self.current_session_id = browser_response.id
+
+			logger.info(f'🌤️ Cloud browser created successfully: {browser_response.id}')
+			logger.debug(f'🌤️ CDP URL: {browser_response.cdpUrl}')
+			logger.debug(f'🌤️ Live URL: {browser_response.liveUrl}')
+
+			return browser_response
+
+		except httpx.TimeoutException:
+			raise CloudBrowserError('Timeout while creating cloud browser. Please try again.')
+		except httpx.ConnectError:
+			raise CloudBrowserError('Failed to connect to cloud browser service. Please check your internet connection.')
+		except Exception as e:
+			if isinstance(e, (CloudBrowserError, CloudBrowserAuthError)):
+				raise
+			raise CloudBrowserError(f'Unexpected error creating cloud browser: {e}')
+
+	async def stop_browser(self, session_id: str | None = None) -> CloudBrowserResponse:
+		"""Stop a cloud browser session.
+
+		Args:
+			session_id: Session ID to stop. If None, uses current session.
+
+		Returns:
+			CloudBrowserResponse: Updated browser info with stopped status
+
+		Raises:
+			CloudBrowserAuthError: If authentication fails
+			CloudBrowserError: If stopping fails
+		"""
+		if session_id is None:
+			session_id = self.current_session_id
+
+		if not session_id:
+			raise CloudBrowserError('No session ID provided and no current session available')
+
+		url = f'{self.api_base_url}/api/v2/browsers/{session_id}'
+
+		# Try to get API key from environment variable first, then auth config
+		api_token = os.getenv('BROWSER_USE_API_KEY')
+
+		if not api_token:
+			# Fallback to auth config file
+			try:
+				auth_config = CloudAuthConfig.load_from_file()
+				api_token = auth_config.api_token
+			except Exception:
+				pass
+
+		if not api_token:
+			raise CloudBrowserAuthError(
+				'No authentication token found. Please set BROWSER_USE_API_KEY environment variable to authenticate with the cloud service.'
+			)
+
+		headers = {'X-Browser-Use-API-Key': api_token, 'Content-Type': 'application/json'}
+
+		request_body = {'action': 'stop'}
+
+		try:
+			logger.info(f'🌤️ Stopping cloud browser session: {session_id}')
+
+			response = await self.client.patch(url, headers=headers, json=request_body)
+
+			if response.status_code == 401:
+				raise CloudBrowserAuthError(
+					'Authentication failed. Please make sure you have set the BROWSER_USE_API_KEY environment variable to authenticate with the cloud service.'
+				)
+			elif response.status_code == 404:
+				# Session already stopped or doesn't exist - treating as error and clearing session
+				logger.debug(f'🌤️ Cloud browser session {session_id} not found (already stopped)')
+				# Clear current session if it was this one
+				if session_id == self.current_session_id:
+					self.current_session_id = None
+				raise CloudBrowserError(f'Cloud browser session {session_id} not found')
+			elif not response.is_success:
+				error_msg = f'Failed to stop cloud browser: HTTP {response.status_code}'
+				try:
+					error_data = response.json()
+					if 'detail' in error_data:
+						error_msg += f' - {error_data["detail"]}'
+				except Exception:
+					pass
+				raise CloudBrowserError(error_msg)
+
+			browser_data = response.json()
+			browser_response = CloudBrowserResponse(**browser_data)
+
+			# Clear current session if it was this one
+			if session_id == self.current_session_id:
+				self.current_session_id = None
+
+			logger.info(f'🌤️ Cloud browser session stopped: {browser_response.id}')
+			logger.debug(f'🌤️ Status: {browser_response.status}')
+
+			return browser_response
+
+		except httpx.TimeoutException:
+			raise CloudBrowserError('Timeout while stopping cloud browser. Please try again.')
+		except httpx.ConnectError:
+			raise CloudBrowserError('Failed to connect to cloud browser service. Please check your internet connection.')
+		except Exception as e:
+			if isinstance(e, (CloudBrowserError, CloudBrowserAuthError)):
+				raise
+			raise CloudBrowserError(f'Unexpected error stopping cloud browser: {e}')
+
+	async def close(self):
+		"""Close the HTTP client and cleanup any active sessions."""
+		# Try to stop current session if active
+		if self.current_session_id:
+			try:
+				await self.stop_browser()
+			except Exception as e:
+				logger.debug(f'Failed to stop cloud browser session during cleanup: {e}')
+
+		await self.client.aclose()
+
+
+# Global client instance
+_cloud_client: CloudBrowserClient | None = None
+
+
+async def get_cloud_browser_cdp_url() -> str:
+	"""Get a CDP URL for a new cloud browser instance.
+
+	Returns:
+		str: CDP URL for connecting to the cloud browser
+
+	Raises:
+		CloudBrowserAuthError: If authentication fails
+		CloudBrowserError: If browser creation fails
+	"""
+	global _cloud_client
+
+	if _cloud_client is None:
+		_cloud_client = CloudBrowserClient()
+
+	try:
+		browser_response = await _cloud_client.create_browser()
+		return browser_response.cdpUrl
+	except Exception:
+		# Clean up client on error
+		if _cloud_client:
+			await _cloud_client.close()
+			_cloud_client = None
+		raise
+
+
+async def stop_cloud_browser_session(session_id: str | None = None) -> CloudBrowserResponse:
+	"""Stop a cloud browser session.
+
+	Args:
+		session_id: Session ID to stop. If None, uses current session from global client.
+
+	Returns:
+		CloudBrowserResponse: Updated browser info with stopped status
+
+	Raises:
+		CloudBrowserAuthError: If authentication fails
+		CloudBrowserError: If stopping fails
+	"""
+	global _cloud_client
+
+	if _cloud_client is None:
+		_cloud_client = CloudBrowserClient()
+
+	try:
+		return await _cloud_client.stop_browser(session_id)
+	except Exception:
+		# Don't clean up client on stop errors - session might still be valid
+		raise
+
+
+async def cleanup_cloud_client():
+	"""Clean up the global cloud client."""
+	global _cloud_client
+	if _cloud_client:
+		await _cloud_client.close()
+		_cloud_client = None