agent-sandboxes

# Agent Sandboxes This skill provides access to E2B sandboxes through a streamlined CLI for safe code execution and file operations in isolated environments. ## Variables - **E2B_API_KEY**: The environment variable containing the E2B API key (stored in the environment file) - **SANDBOX_CLI_PATH**: `.claude/skills/agent-sandboxes/sandbox_cli/` - **ENVIRONMENT_FILE_PATH**: `../../../../.env` - **TIMEOUT_DURATION_IN_SECONDS**: `43200` (12 hours) ## Prerequisites Before using sandbox operations, **validate the environment**: 1. **Check for E2B_API_KEY**: ```bash # Verify the API key is set grep "E2B_API_KEY" `ENVIRONMENT_FILE_PATH` ``` If missing, instruct the user: ``` Error: E2B_API_KEY not found in .env file Please add your E2B API key to the .env file in the project root: echo "E2B_API_KEY=your_api_key_here" >> .env Get your API key from: https://e2b.dev/docs ``` 2. **Verify CLI is available**: The sandbox CLI is located at `SANDBOX_CLI_PATH` The `.env` file is automatically loaded from the project root. ## Instructions - IMPORTANT: **Don't create files locally**, always use the sandbox. Only do this if the user explicitly asks you to do so. - **ALWAYS USE --timeout TIMEOUT_DURATION_IN_SECONDS** - **CAPTURE AND REMEMBER SANDBOX ID** - Store it in your context, don't use shell variables or files - **Multi-agent safe** - Each agent tracks its own sandbox ID independently - **Always validate E2B_API_KEY first** - Don't proceed without it - **Change directory to SANDBOX_CLI_PATH** - All commands must be run from there - **Use --shell for complex commands** - Enables pipes, redirections, wildcards - **Use --cwd instead of cd** - More reliable for working directory changes - **Binary files** - Use `upload`/`download` for images, PDFs, executables - **Never delete the sandbox unless you're explicitly asked to do so** - Sandboxes auto-timeout after TIMEOUT_DURATION_IN_SECONDS ### Template Tiers Pre-built templates with different resource levels. Use `--template` flag with `sbx init`: | Template | vCPU | RAM | Cost | Best For | |----------|------|-----|------|----------| | `fullstack-vue-fastapi-node22` | 2 | 2GB | $0.13/hr | Simple apps (default) | | `fullstack-vue-fastapi-node22-lite` | 2 | 4GB | $0.15/hr | Browser tests | | `fullstack-vue-fastapi-node22-standard` | 4 | 4GB | $0.27/hr | Parallel builds | | `fullstack-vue-fastapi-node22-heavy` | 4 | 8GB | $0.33/hr | Multi-browser | | `fullstack-vue-fastapi-node22-max` | 8 | 8GB | $0.44/hr | Fastest | Build new templates: `uv run build_template.py --tier <tier>` or `--list-tiers` to see options. ### When to Use Sandboxes Use agent sandboxes when the user needs to: - **Run untrusted or experimental code** safely - **Test packages or dependencies** without affecting the local system - **Execute system commands** in an isolated environment - **Work with binary files** (images, PDFs, executables) - **Clone and test repositories** in isolation - **Install and test different package versions** - **Run long-running processes** without blocking ### CLI Overview The sandbox CLI has **four core command groups**: 1. **`sbx init`** - Quick sandbox initialization 2. **`sbx sandbox`** - Lifecycle management (create, connect, kill, pause, extend-lifetime, info) 3. **`sbx files`** - File operations (ls, read, write, upload, download, rm, mkdir, mv) 4. **`sbx exec`** - Unified command execution (the most powerful command) 5. **`sbx browser`** - Browser automation for UI validation (visual testing) **Get CLI Help**: Use `sbx --help` to see all available commands and options: ```bash cd SANDBOX_CLI_PATH uv run sbx --help # Main help uv run sbx init --help # Help for init command uv run sbx sandbox --help # Help for sandbox commands uv run sbx files --help # Help for file operations uv run sbx exec --help # Help for exec command ``` ### Key Command: `sbx exec` The `exec` command is the primary interface for running commands in sandboxes: ```bash uv run sbx exec $SANDBOX_ID "command" [options] Options: --cwd PATH Working directory --env KEY=VALUE Environment variables (multiple allowed) --root Run as root user --shell Enable shell features (pipes, redirections, wildcards) --timeout SECONDS Command timeout (default: 60) --background Run command in background ``` **Important**: All commands must be run from `SANDBOX_CLI_PATH` directory. ### Key Command: `sbx browser` Browser automation for visual validation of sandbox applications using Playwright's isolated Chromium. **Commands** (all support `--port PORT` for parallel agents): ```bash sbx browser init # First-time setup (once per machine) sbx browser start [--headed] # Start browser (--headed shows window) sbx browser nav <url> # Navigate to URL sbx browser eval <code> # Run JavaScript, returns result sbx browser screenshot [--path P] [--full] # Screenshot (--full for entire page) sbx browser click <selector> # Click element by CSS selector sbx browser type <selector> <text> # Type text into input field sbx browser scroll <direction> # up | down | top | bottom sbx browser a11y # Get accessibility tree (JSON) sbx browser dom [--full] # Get DOM (--full for raw HTML) sbx browser status # Check if browser is running sbx browser close # Close browser and kill process ``` **For parallel agents**: Use `--port` flag with unique ports (9222-9999). ### Multi-Agent Considerations **CRITICAL**: Multiple agents may be running sandboxes simultaneously. Each agent MUST: 1. **Always use `--timeout TIMEOUT_DURATION_IN_SECONDS`** when initializing (unless the user specifies a different timeout) 2. **Capture the sandbox ID** from `sbx init` output and remember it in your context 3. **DO NOT use shell variables** like `export SANDBOX_ID=...` (conflicts with other agents) 4. **DO NOT rely on `.sandbox_id` file** (gets overwritten by other agents) 5. **Track the sandbox ID yourself** and use it directly in all subsequent commands 6. **Report the sandbox ID** to the user when done **Example of proper ID handling**: ```bash # When you run this: uv run sbx init # Capture the sandbox ID from output (e.g., "sbx_abc123def456") # Store it in YOUR context/memory as: sandbox_id = "sbx_abc123def456" # Then use it directly in all commands: uv run sbx exec sbx_abc123def456 "python --version" uv run sbx files write sbx_abc123def456 /home/user/test.py "print('hello')" ``` ## Cookbook Extended documentation for specific features. **Read these when you need to use the feature.** | Feature | When to Read | Documentation | | ------------------ | ---------------------------------------------------------------------- | ------------------------------------------ | | Browser Automation | When validating UIs, taking screenshots, or interacting with web pages | [cookbook/browser.md](cookbook/browser.md) | ## Workflow ### Step 1: Validate Environment Always start by checking for the E2B_API_KEY: ```bash cd SANDBOX_CLI_PATH grep "E2B_API_KEY" `ENVIRONMENT_FILE_PATH` ``` If not found, stop and request the user to add their API key. ### Step 2: Initialize Sandbox and Capture ID Create a new sandbox and **capture the sandbox ID from the output**: ```bash cd SANDBOX_CLI_PATH uv run sbx init --timeout TIMEOUT_DURATION_IN_SECONDS ``` **CRITICAL**: - **Always use `--timeout TIMEOUT_DURATION_IN_SECONDS`** - The command will output a sandbox ID (e.g., `sbx_abc123def456`) - **Capture this ID** and remember it in your context - **DO NOT use environment variables** or files to store it - **Use this exact ID** in all subsequent commands Additional options (optional): - `--template NAME` - Use a specific template (default: base) - `--env KEY=VALUE` - Set environment variables Example: ```bash uv run sbx init --timeout TIMEOUT_DURATION_IN_SECONDS # Output: Created sandbox: sbx_abc123def456 # YOU remember: sandbox_id = "sbx_abc123def456" ``` ### Step 3: Perform Operations Use the appropriate command based on the task, **using the sandbox ID you captured**: **Run commands** (replace `<sandbox_id>` with your captured ID): ```bash uv run sbx exec <sandbox_id> "python --version" uv run sbx exec <sandbox_id> "pip list" --cwd /home/user/project ``` **File operations**: ```bash uv run sbx files write <sandbox_id> /home/user/script.py "print('hello')" uv run sbx files read <sandbox_id> /home/user/output.txt uv run sbx files upload <sandbox_id> ./local.png /home/user/image.png uv run sbx files edit <sandbox_id> /home/user/config.ts --old "old text" --new "new text" uv run sbx files edit <sandbox_id> /home/user/config.ts --old "find" --new "replace" --all ``` **Download directories** (clone sandbox code locally): ```bash # Download directory (excludes .venv, node_modules, .git, __pycache__ by default) uv run sbx files download-dir <sandbox_id> /home/user/project ./local/project # Include everything (no exclusions) uv run sbx files download-dir <sandbox_id> /home/user/project ./local/project --all ``` **IMPORTANT - Writing Files with Special Characters**: The `sbx files write` command has limitations with special characters like brackets `[]` when passing content as an argument due to shell glob expansion. Use one of these workarounds: **Option 1: Use --stdin flag (recommended)**: ```bash # Pipe content through stdin to avoid shell escaping issues echo 'const arr = [1, 2, 3]; const val = obj["key"];' | uv run sbx files write <sandbox_id> /home/user/file.js --stdin # Or with heredoc uv run sbx files write <sandbox_id> /home/user/file.js --stdin << 'EOF' const arr = [1, 2, 3]; const value = obj["key"]; EOF ``` **Option 2: Write locally, then upload**: ```bash # Write file locally first (using Write tool) # Then upload to sandbox - bypasses shell escaping entirely uv run sbx files upload <sandbox_id> ./local/file.js /home/user/file.js ``` **Option 3: Use sbx exec with heredoc or Python**: ```bash # Use cat heredoc for complex content uv run sbx exec <sandbox_id> "cat > /home/user/file.js << 'EOF' const arr = [1, 2, 3]; const value = obj['key']; EOF " --shell # Or use Python to write files uv run sbx exec <sandbox_id> "python3 << 'EOF' with open('/home/user/file.js', 'w') as f: f.write('''const arr = [1, 2, 3]; const value = obj[\"key\"];''') EOF " --shell ``` **Install packages**: ```bash # Install uv package manager uv run sbx exec <sandbox_id> "curl -LsSf https://astral.sh/uv/install.sh | sh" --shell --timeout 120 # Install Python packages uv run sbx exec <sandbox_id> "/home/user/.local/bin/uv pip install --system requests" ``` ### Step 4: Expose Frontend (If Applicable) **When building applications with a frontend/UI**, create a lightweight server to host your work and expose it: #### 4.1: Start the Server **Always default to port 5173** and ensure your frontend is configured to use this port: ```bash # For Python/Flask uv run sbx exec <sandbox_id> "python -m http.server 5173" --background --cwd /home/user/project # For Node/React (Vite) uv run sbx exec <sandbox_id> "npm run dev -- --port 5173" --background --cwd /home/user/project # For static HTML/CSS/JS uv run sbx exec <sandbox_id> "python -m http.server 5173" --background --cwd /home/user/dist # For a custom Python server uv run sbx files write <sandbox_id> /home/user/server.py "from flask import Flask; app = Flask(__name__); app.run(host='0.0.0.0', port=5173)" uv run sbx exec <sandbox_id> "python /home/user/server.py" --background ``` **Key points**: - Use `--background` flag to keep server running - **Port 5173 is the default** - use this unless you have a specific reason not to - Ensure your frontend code is configured for the same port #### 4.2: Get the Exposed URL **CRITICAL**: Always use the `get-host` command to retrieve the actual public URL. **Do NOT try to construct or infer the URL**. ```bash uv run sbx sandbox get-host <sandbox_id> --port 5173 ```