Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/browser-use/browser-use/llms.txt

Use this file to discover all available pages before exploring further.

Sandbox settings control how your Browser Use code runs in production environments with cloud-hosted browsers.
Sandboxes are the easiest way to run Browser Use in production. They handle agents, browsers, persistence, auth, cookies, and LLMs with minimal latency.See Going to Production for the complete guide.

​
Quick Start

Wrap your function with @sandbox() to run it in production: 
from browser_use import Browser, sandbox, ChatBrowserUse
from browser_use.agent.service import Agent
import asyncio

@sandbox()
async def my_task(browser: Browser):
    agent = Agent(
        task="Your task here",
        browser=browser,
        llm=ChatBrowserUse()
    )
    await agent.run()

asyncio.run(my_task())

​
Cloud Browser Parameters

​
use_cloud

​
use_cloud
bool
default:"False"
Enable Browser Use cloud browser service.Automatically provisions a remote browser optimized for automation.Example:
browser = Browser(use_cloud=True)

​
cloud_profile_id

​
cloud_profile_id
string
UUID of a browser profile to use.If not specified, uses the default profile.Get profile ID:
export BROWSER_USE_API_KEY=your_key && curl -fsSL https://browser-use.com/profile.sh | sh
See Going to Production for details.

​
cloud_proxy_country_code

​
cloud_proxy_country_code
string
Country code for proxy location.Supported countries: us, uk, fr, it, jp, au, de, fi, ca, inUse cases:
  • Bypass captchas
  • Bypass Cloudflare protection
  • Access geo-restricted content
Example:
browser = Browser(
    use_cloud=True,
    cloud_proxy_country_code='us'
)

​
cloud_timeout

​
cloud_timeout
int
Session timeout in minutes.Limits:
  • Free users: max 15 minutes
  • Paid users: max 240 minutes
Example:
browser = Browser(
    use_cloud=True,
    cloud_timeout=30
)

​
Authentication Setup

​
Prerequisites

  1. Get an API key from cloud.browser-use.com/new-api-key
  2. Set the environment variable: 
    export BROWSER_USE_API_KEY=your_key

​
Sync Local Cookies to Cloud

To use your local authentication in production: 
export BROWSER_USE_API_KEY=your_key && curl -fsSL https://browser-use.com/profile.sh | sh
This:
  1. Opens a browser where you log into your accounts
  2. Syncs cookies to the cloud
  3. Returns a profile_id

​
Use Authenticated Profile

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

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

asyncio.run(authenticated_task())
Your cloud browser is already logged in!

​
Sandbox Decorator Parameters

All parameters are optional:
​
cloud_profile_id
string
Browser profile ID for authentication
​
cloud_proxy_country_code
string
Proxy country code (us, uk, fr, etc.)
​
cloud_timeout
int
Session timeout in minutes

​
Complete Example

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

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

# With proxy for stealth
@sandbox(cloud_proxy_country_code='us')
async def stealth_task(browser: Browser):
    agent = Agent(
        task="Your task",
        browser=browser,
        llm=ChatBrowserUse()
    )
    await agent.run()

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

# Full configuration
@sandbox(
    cloud_profile_id='your-profile-id',
    cloud_proxy_country_code='us',
    cloud_timeout=30
)
async def production_task(browser: Browser):
    agent = Agent(
        task="Complex production task",
        browser=browser,
        llm=ChatBrowserUse()
    )
    history = await agent.run()
    return history.final_result()

# Run any task
asyncio.run(production_task())

​
Benefits of Cloud Sandboxes

Zero Setup

No local browser configuration or dependencies needed

Built for Scale

Handle millions of agents with automatic resource management

Lowest Latency

Agent runs next to the browser for minimal network overhead

Anti-Bot Protection

Bypass captchas, Cloudflare, and bot detection automatically

Global Proxies

Access geo-restricted content with country-specific proxies

Authentication

Sync local cookies to cloud for seamless authenticated sessions

​
Advanced Configuration

For more sandbox parameters and events, see Sandbox Quickstart.