# Cloud Sandbox Boilerplate

Cloud browser automation with @sandbox decorator for persistent auth and proxy routing

---

**Browser Use Team**  
[GH: @browser-use](https://github.com/browser-use)

[Source](https://github.com/browser-use/template-library/blob/main/sandbox/)

## 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

```bash
uvx browser-use init --template sandbox
```

## Requirements

Get your Browser Use API Key [here](https://cloud.browser-use.com/new-api-key)

**Optional** for persistent authentication:

- Cloud Profile ID - Create at [cloud.browser-use.com/#settings/profiles](https://cloud.browser-use.com/#settings/profiles)

## How It Works

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

```python
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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) for the complete list.

## Learn More

📖 See the [detailed README](https://github.com/browser-use/template-library/blob/main/sandbox/README.md) for cloud profiles setup, troubleshooting, and advanced configuration.