BROWSER USE

- Browser Use Agents: give Browser Use a task and receive completed work. API V4 is current for new integrations.
- Browser Infrastructure: connect your agent or automation to managed browsers through SDK, REST, or CDP. Starts at $0.02/browser-hour.
- Developer tools: Open Source, Browser Harness, SDK, and MCP support the two products above.

[Developer Index](https://browser-use.com/index.md)
[Product Map](https://browser-use.com/llms.txt)
[Full Product Context](https://browser-use.com/llms-full.txt)
[Pricing](https://browser-use.com/pricing.md)
[Cloud Docs](https://docs.browser-use.com/cloud/quickstart)
[Open Source Docs](https://docs.browser-use.com/open-source/introduction)

---

# Cloud Sandbox Boilerplate

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

---

### 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](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:

```bash
# 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.