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

## 📚 Related Documentation

- [CLI Reference](./cli-reference.md) - Complete command-line parameter documentation
- [E2B Official Documentation](https://e2b.dev/docs) - E2B cloud service documentation
