Cloud Sandbox Boilerplate

Overview

Execute browser automation tasks in the cloud with the @sandbox decorator - a convenience wrapper that automatically configures Browser Use for cloud-based execution with advanced features like persistent authentication and proxy routing.

What is the @sandbox decorator?

The @sandbox decorator is a simple wrapper that automatically configures your browser automation to run in the cloud with custom settings, eliminating the need for manual browser setup and configuration.

Key Features

• Cloud-based execution - Browser runs entirely in the cloud, no local browser needed
• Persistent authentication - Save login sessions across runs using cloud profiles
• Proxy routing - Route browser traffic through specific countries
• Configurable timeouts - Control how long browser sessions stay active
• Simplified setup - Automatically handles all cloud configuration

Installation

uvx browser-use init --template sandbox

Requirements

Optional for persistent authentication:

• Cloud Profile ID - Create at cloud.browser-use.com/#settings/profiles

How It Works

The @sandbox decorator automatically injects a cloud-configured browser into your function:

from browser_use import sandbox
 
@sandbox(
    cloud_profile_id=os.getenv('CLOUD_PROFILE_ID'),
    cloud_proxy_country_code='us',
    cloud_timeout=60
)
async def main(browser: Browser):
    agent = Agent(task="Your task here", browser=browser)
    await agent.run()

The browser parameter is automatically configured with:

1. Cloud execution enabled (use_cloud=True)
2. Your specified cloud profile for persistent auth
3. Proxy routing through your chosen country
4. Custom session timeout

Configuration Options

All settings are controlled via environment variables in your .env file:

# Required
BROWSER_USE_API_KEY=your-key-here
 
# Optional - Cloud Settings
CLOUD_PROFILE_ID=your-profile-id-here     # For persistent authentication
CLOUD_PROXY_COUNTRY_CODE=us               # Two-letter ISO country code
CLOUD_TIMEOUT=60                          # Session timeout in minutes

Use Cases

Persistent Authentication

• Maintain login sessions across multiple runs
• No need to re-authenticate each time
• Perfect for tasks requiring logged-in access

Country-Specific Automation

• Route traffic through any country using two-letter ISO codes
• Test geo-restricted content
• Comply with regional requirements

Zero Local Setup

• No Chrome/Chromium installation needed
• No display configuration required
• Works on any machine with Python

Available Proxy Countries

Use any two-letter ISO country code: us, uk, de, jp, au, fr, ca, etc.

See ISO 3166-1 alpha-2 for the complete list.

Learn More

📖 See the detailed README for cloud profiles setup, troubleshooting, and advanced configuration.