comeonoliver/skillshub/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 ```

1. 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:

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:

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:

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):

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:

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

Workflow

Step 1: Validate Environment

Always start by checking for the E2B_API_KEY:

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:

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:

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):

uv run sbx exec <sandbox_id> "python --version"
uv run sbx exec <sandbox_id> "pip list" --cwd /home/user/project

File operations:

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):

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

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

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

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

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

# 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