Sandbox Settings

Configuration options for running Browser Use in production with cloud sandboxes

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, in

Use 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.

---

Related Configuration

• Agent Settings - Configure agent behavior
• Browser Settings - Configure browser options
• Going to Production - Complete production deployment guide