Sandbox Usage Guide (Beta) ​

⚠️ Beta Feature: The Sandbox feature is currently in Beta. APIs and functionality may change.

CodeBuddy supports running in isolated sandbox environments, providing secure code execution and project development environments.

🎯 Sandbox Types ​

  • Container Sandbox: Local container environment based on Docker/Podman
  • E2B Sandbox: Remote isolated environment based on E2B cloud service
  • Teleport Mode: Connect to remotely deployed sandbox services

🚀 Quick Start ​

Container Sandbox ​

bash
# Basic usage - automatically mounts current directory
codebuddy --sandbox "Help me analyze this project"

# Equivalent to
codebuddy --sandbox container "Help me analyze this project"

# Pipe mode
echo "Run tests" | codebuddy --sandbox --print

Prerequisites:

  • Docker or Podman installed
  • Docker daemon running

E2B Sandbox (Cloud) ​

bash
# Set E2B API Key
export E2B_API_KEY=your_api_key

# Basic usage (requires full API URL)
codebuddy --sandbox https://api.e2b.dev "Create a Python web application"

# Upload current working directory
codebuddy --sandbox https://api.e2b.dev --sandbox-upload-dir "Analyze this project"

Teleport Mode (Remote Connection) ​

Teleport mode is used to connect to remote sandbox environments created by BGA (Background Agent). This is a special connection mode primarily used for cloud scheduling scenarios.

bash
# Connect to remote sandbox using teleport value
codebuddy --teleport session_abc123XYZ4567890 "Connect to remote sandbox"

# Custom headers (for authentication or routing)
codebuddy --teleport session_abc123XYZ4567890 \
  -H "X-Domain: example.com" \
  -H "X-Enterprise-Id: ent123" \
  "Execute task"

Teleport Value Format:

  • Format: session_{cliSessionId}
  • cliSessionId: Unique session identifier
  • Example: session_abc123XYZ4567890

How It Works:

  1. BGA backend generates a unique cliSessionId
  2. BGA clones code to /workspace/{cliSessionId} directory in the sandbox
  3. BGA generates teleport command: codebuddy --teleport session_{cliSessionId}
  4. CLI parses the teleport value, connects to the specified sandbox and switches to the correct working directory
  5. Executes commands as root user in the sandbox

Prerequisites:

  • Valid teleport value (generated by BGA backend)
  • Correct authentication credentials (via E2B_API_KEY or CODEBUDDY_AUTH_TOKEN)
  • Network connectivity to BGA backend service

Features:

  • Code is prepared by BGA backend, no upload needed
  • Automatically executes commands as root user
  • Working directory automatically set to /workspace/{cliSessionId}
  • Supports custom HTTP headers for authentication and routing

📦 Sandbox Reuse Mechanism ​

Alias System ​

Assign independent sandboxes for users/projects:

bash
# Use user ID as alias
codebuddy --sandbox https://api.e2b.dev --sandbox-id user-123 -p "Task"

# Use project name as alias
codebuddy --sandbox https://api.e2b.dev --sandbox-id project-foo -p "Task"

Alias mappings are stored in ~/.codebuddy/sandbox-state.json, supporting automatic creation and reuse.

Default Behavior ​

Sandboxes are automatically reused without manually specifying IDs:

bash
# First time - creates new sandbox
$ codebuddy --sandbox https://api.e2b.dev "Hello"
[Sandbox] Creating new E2B sandbox...
[Sandbox] Created new sandbox: sb_abc123

# Next launch - automatically reuses
$ codebuddy --sandbox https://api.e2b.dev "Continue working"
[Sandbox] Reusing sandbox: sb_abc123

Multi-Project Management ​

A single sandbox can host multiple projects, automatically isolated in different directories:

/workspace/
  ├── home-user-projectA/
  ├── home-user-projectB/
  └── var-www-website/

⚙️ Advanced Parameters ​

Sandbox Creation and Connection ​

bash
# Force create new sandbox (ignore cache)
codebuddy --sandbox --sandbox-new "Start from scratch"

# Connect to specific sandbox ID (real ID)
codebuddy --sandbox --sandbox-id sb_abc123 "Continue previous work"

# Use aliases (custom names, auto-create and reuse)
codebuddy --sandbox https://api.e2b.dev --sandbox-id user-123 -p "Task"     # User ID
codebuddy --sandbox https://api.e2b.dev --sandbox-id project-foo -p "Task"  # Project name
codebuddy --sandbox https://api.e2b.dev --sandbox-id team-backend -p "Task" # Team name

# Terminate sandbox on exit (default keeps running for reuse)
codebuddy --sandbox --sandbox-kill "Clean up after completion"

Environment Variable Configuration ​

bash
# E2B configuration
export E2B_API_KEY=your_api_key              # Required
export E2B_TEMPLATE=base                     # Template name (default: base)
export E2B_TIMEOUT_MS=3600000                # Timeout (default: 1 hour)
export E2B_ALLOW_INTERNET_ACCESS=true        # Allow internet access (default: true)

# Container Sandbox configuration
export CODEBUDDY_SANDBOX_IMAGE=node:20-alpine  # Docker image

📊 Sandbox Management ​

List Sandboxes ​

bash
$ codebuddy sandbox list
E2B Sandboxes:
* sb_abc123 (2 projects, last used 2m ago)
  sb_xyz789 (1 project, last used 2h ago)

View Details ​

bash
# View current sandbox
$ codebuddy sandbox info

# View specific sandbox
$ codebuddy sandbox info sb_xyz789

Terminate Sandbox ​

bash
$ codebuddy sandbox kill sb_abc123

Clean Up Invalid Sandboxes ​

bash
$ codebuddy sandbox clean

🔍 How It Works ​

Project Directory Mapping ​

bash
Local path: /Users/yangsubo/projectA
Sandbox path: /workspace/Users-yangsubo-projectA

State Persistence ​

Sandbox state is saved in ~/.codebuddy/sandbox-state.json

💡 Best Practices ​

1. Choose the Right Sandbox Type ​

bash
# Need local container isolation
codebuddy --sandbox container "Local development task"

# Cloud collaboration or no local environment
codebuddy --sandbox https://api.e2b.dev "Cloud development"

# Connect to remotely deployed sandbox service
codebuddy --teleport session_abc123XYZ4567890 "Remote development"

2. Project Isolation ​

bash
cd ~/work/projectA
codebuddy --sandbox "Develop feature X"

cd ~/work/projectB
codebuddy --sandbox "Fix bug Y"

3. Long-term Development ​

bash
# Day one
codebuddy --sandbox "Set up development environment"

# Day two - instant startup, environment preserved
codebuddy --sandbox "Continue development"

4. Temporary Tasks ​

Use --sandbox-kill for automatic cleanup:

bash
codebuddy --sandbox --sandbox-kill "Quickly test an idea"

5. Regular Cleanup ​

bash
# View all sandboxes
codebuddy sandbox list

# Clean up invalid ones
codebuddy sandbox clean

# Manually terminate specific sandbox
codebuddy sandbox kill sb_old123

⚠️ Important Notes ​

Container Sandbox ​

  • Mount Mode: Container sandbox automatically mounts current directory, file changes sync in real-time
  • Network Isolation: Docker container is isolated from host network
  • Resource Limits: Subject to Docker configuration limits

E2B Sandbox ​

  • Upload Delay: Initial project upload takes time, more files means slower upload
  • File Sync: Automatic sync not supported, requires re-upload or manual sync
  • Cost: E2B cloud service may incur charges, check official pricing
  • Timeout: Sandboxes have maximum runtime limits (default: 1 hour)

Interactive Commands ​

Both E2B and Container support interactive PTY:

bash
codebuddy --sandbox "Edit main.py with vim"
codebuddy --sandbox "Run htop to view processes"

🔧 Troubleshooting ​

Docker Not Running ​

bash
Error: Neither Docker nor Podman is available

Solution: Start Docker Desktop or Podman

E2B API Key Missing ​

bash
Error: E2B_API_KEY environment variable is required

Solution: export E2B_API_KEY=your_key_here

Sandbox Connection Failed ​

bash
Failed to connect to sandbox sb_abc123

Solution: Sandbox may have expired, use --sandbox-new to create a new one

View Debug Logs ​

bash
codebuddy --sandbox --debug "Test command"