[P4] Phase 6.0 Sandbox execution environments (E2B, Docker, and others)

[frankbria]

Summary

Allow users to launch Ralph in isolated sandbox environments rather than directly on the local machine. This provides security isolation, reproducible environments, and protects the host system from autonomous code execution.

Problem Statement

Ralph currently executes Claude Code directly on the local machine, which has risks:

• Code can modify/delete local files unexpectedly
• Code can access sensitive data on the host
• No isolation between different projects
• Difficult to reproduce exact environments
• Security concerns with autonomous code execution

First-Class Sandbox Providers

Three sandbox platforms are implemented as first-class backends:

Provider	Type	Best For
E2B	Cloud-hosted, ephemeral	AI-agent workloads, pay-per-use
Daytona	Self-hosted	Corporate environments, persistent workspaces
Cloudflare	Edge compute	Global distribution, Cloudflare ecosystem

Additional Backends

Other sandbox platforms (Gitpod, Codespaces, Modal, Replit, etc.) can be added as plugins via the generic sandbox interface (Phase 6.5).

Proposed CLI Interface

# Local Docker container
ralph --sandbox docker

# Cloud providers
ralph --sandbox e2b
ralph --sandbox daytona
ralph --sandbox cloudflare

# Common options
ralph --sandbox <type> --sync-strategy snapshot|realtime
ralph --sandbox <type> --ephemeral|--persist
ralph --sandbox <type> --max-duration 30m

Sub-Issues

Phase	Issue	Description
6.1	#74	Local Docker Sandbox Execution (foundation)
6.2	#75	E2B Cloud Sandbox Integration
6.3	#76	Sandbox File Synchronization
6.4	#77	Sandbox Security and Resource Policies
6.5	#78	Generic Sandbox Interface (plugin architecture)
6.6	#79	Daytona Sandbox Integration
6.7	#80	Cloudflare Sandbox Integration

Cross-cutting Concerns

All sandbox implementations must address:

1. File Synchronization ([P4] Phase 6.3 Sandbox File Synchronization #76) - Getting code in and artifacts out
2. Secret Management ([P4] Phase 6.4 Sandbox Security and Resource Policies #77) - Secure credential injection
3. Monitoring Integration - ralph-monitor with remote execution
4. Cost Management - For cloud-based sandboxes
5. State Persistence - Ephemeral vs. persistent environments

Implementation Order

Recommended implementation sequence:

1. Docker ([P4] Phase 6.1 Local Docker Sandbox Execution #74) - Foundation, no external dependencies
2. File Sync ([P4] Phase 6.3 Sandbox File Synchronization #76) - Needed by all backends
3. Security Policies ([P4] Phase 6.4 Sandbox Security and Resource Policies #77) - Needed by all backends
4. E2B ([P4] Phase 6.2 E2B Cloud Sandbox Integration #75) - First cloud provider
5. Generic Interface ([P4] Phase 6.5 Generic Sandbox Interface and Plugin Architecture #78) - Abstract the pattern
6. Daytona ([P4] Phase 6.6 Daytona Sandbox Integration #79) - Self-hosted option
7. Cloudflare ([P4] Phase 6.7 Cloudflare Sandbox Integration #80) - Edge compute option

[traycerai]

Plan

Observations

Ralph is a mature bash-based autonomous development loop tool with 276 passing tests and modular architecture. The current execution model runs Claude Code CLI directly on the local machine via execute_claude_code() in file:ralph_loop.sh. The codebase follows a library pattern with modules in file:lib/ (circuit_breaker.sh, response_analyzer.sh, date_utils.sh). CLI argument parsing occurs at lines 1138-1229, command building at lines 679-732, and execution at lines 735-925. Multiple sandbox platforms provide isolated execution: Docker (local, no external dependencies), E2B (Firecracker microVMs, <200ms startup), Daytona (Docker-compatible, sub-90ms startup), and Cloudflare (edge compute). The implementation must address file synchronization, secret management, monitoring integration, cost management, and state persistence across all providers.

Approach

Implement a comprehensive sandbox abstraction layer with a generic interface that supports multiple providers. Start with Docker as the foundation (no external dependencies), then implement file synchronization and security policies as cross-cutting concerns, followed by cloud providers (E2B, Daytona, Cloudflare). Add CLI flags --sandbox, --sync-strategy, --ephemeral|--persist, and --max-duration to control sandbox behavior. Modify execute_claude_code() to route through the sandbox manager. This approach maintains backward compatibility (local execution remains default), follows the existing modular pattern, and enables future provider additions via a plugin architecture. The implementation prioritizes the recommended order: Docker foundation, file sync, security policies, then cloud providers.

Implementation Steps

Phase 6.1: Docker Sandbox Foundation (Sub-Issue #74)

Create file:lib/sandbox_manager.sh as the core abstraction layer with Docker as the first provider:

Core Functions (Generic Interface):

• init_sandbox() - Initialize sandbox based on selected provider (docker/e2b/daytona/cloudflare)
• execute_in_sandbox() - Execute Claude Code command in the selected sandbox environment
• cleanup_sandbox() - Cleanup sandbox resources after execution
• get_sandbox_status() - Query sandbox health and availability
• validate_sandbox_config() - Validate sandbox-specific configuration
• get_sandbox_provider() - Return current provider name

Docker Provider Functions:

• init_docker_sandbox() - Create Docker container with project volume mount
• execute_docker() - Execute Claude Code inside Docker container
• cleanup_docker() - Stop and remove Docker container
• docker_is_available() - Check Docker daemon availability

Docker-Specific Features:

• Use lightweight base image (alpine or ubuntu-slim)
• Mount project directory as volume for file access
• Support custom Dockerfile for project-specific dependencies
• Implement container resource limits (CPU, memory)
• Handle container networking (localhost access)

Configuration Management:

• Support environment variables: SANDBOX_PROVIDER, DOCKER_IMAGE, DOCKER_MEMORY_LIMIT, DOCKER_CPU_LIMIT
• Support config file entries in .ralphrc: SANDBOX_PROVIDER=docker, DOCKER_IMAGE=ubuntu:latest
• Validate Docker installation and daemon availability
• Create example Docker configuration in ~/.ralph/sandbox-docker.json

Phase 6.2: File Synchronization (Sub-Issue #76)

Create file:lib/sandbox_sync.sh to handle bidirectional file synchronization:

Core Sync Functions:

• init_sync_strategy() - Initialize sync strategy (snapshot or realtime)
• sync_to_sandbox() - Upload project files to sandbox before execution
• sync_from_sandbox() - Download modified files from sandbox after execution
• validate_sync_config() - Validate sync configuration and paths

Snapshot Strategy (default):

• Upload entire project directory before execution
• Download modified files after execution
• Efficient for small projects, simple implementation
• Suitable for ephemeral sandboxes

Realtime Strategy (advanced):

• Watch for file changes and sync incrementally
• Use rsync or similar for efficient transfer
• Suitable for persistent sandboxes
• Requires additional dependencies

File Handling:

• Exclude patterns: .git/, node_modules/, .env, *.log
• Preserve file permissions and timestamps
• Handle symlinks appropriately
• Support large files (>100MB)
• Implement retry logic for failed transfers

Configuration:

• Support --sync-strategy snapshot|realtime flag
• Support .ralphignore file for exclusion patterns
• Support SYNC_TIMEOUT environment variable
• Create example sync configuration in ~/.ralph/sandbox-sync.json

Phase 6.3: Sandbox Security and Resource Policies (Sub-Issue #77)

Create file:lib/sandbox_security.sh to enforce security boundaries:

Secret Management:

• inject_secrets() - Securely inject environment variables into sandbox
• validate_secret_sources() - Validate secret file/env var sources
• Support .env file injection with validation
• Support environment variable mapping
• Prevent secret leakage in logs

Resource Policies:

• set_resource_limits() - Apply CPU, memory, disk, and network limits
• validate_resource_config() - Validate resource limit configuration
• Support --max-duration MIN flag for execution timeout
• Support --max-memory MB for memory limits
• Support --max-cpu CORES for CPU limits

Sandbox Isolation:

• Disable network access by default (configurable)
• Restrict file system access to project directory
• Prevent privilege escalation
• Disable dangerous system calls
• Support allowlist-based network access

Audit and Logging:

• Log all sandbox operations
• Track resource usage per execution
• Log security policy violations
• Support audit trail for compliance

Configuration:

• Support ~/.ralph/sandbox-security.json for policies
• Support --allow-network flag for network access
• Support --allow-privileged flag (with warnings)
• Create example security configuration

Phase 6.4: E2B Cloud Sandbox Integration (Sub-Issue #75)

Implement E2B provider after Docker foundation is stable:

E2B Provider Functions:

• init_e2b_sandbox() - Create E2B sandbox instance via API
• execute_e2b() - Execute Claude Code in E2B environment
• cleanup_e2b() - Terminate E2B sandbox instance
• e2b_is_available() - Check E2B API availability

E2B-Specific Features:

• Use E2B SDK or REST API for sandbox management
• Support E2B templates for pre-configured environments
• Handle E2B region selection
• Implement E2B cost tracking
• Support E2B session persistence

Prerequisites:

• E2B API key validation in validate_sandbox_config()
• E2B CLI or SDK installation check in install.sh
• Document E2B setup in README.md

Configuration:

• Support E2B_API_KEY environment variable
• Support E2B_TEMPLATE for environment selection
• Support E2B_REGION for geographic selection
• Create example E2B configuration in ~/.ralph/sandbox-e2b.json

Phase 6.5: Generic Sandbox Interface and Plugin Architecture (Sub-Issue #78)

Create extensible plugin system for future sandbox providers:

Plugin Interface:

• Define standard functions each provider must implement
• Create provider registry system
• Support dynamic provider loading
• Implement provider discovery mechanism

Standard Provider Functions:

• provider_init() - Initialize provider
• provider_execute() - Execute command
• provider_cleanup() - Cleanup resources
• provider_validate() - Validate configuration
• provider_status() - Get provider status

Plugin Discovery:

• Load providers from ~/.ralph/providers/ directory
• Support provider metadata files
• Implement provider version checking
• Support provider dependencies

Provider Registry:

• Maintain list of available providers
• Support provider enable/disable
• Track provider capabilities
• Support provider configuration per project

Phase 6.6: Daytona Self-Hosted Sandbox Integration (Sub-Issue #79)

Implement Daytona provider following E2B pattern:

Daytona Provider Functions:

• init_daytona_sandbox() - Create Daytona workspace via API
• execute_daytona() - Execute Claude Code in Daytona environment
• cleanup_daytona() - Destroy Daytona workspace
• daytona_is_available() - Check Daytona API availability

Daytona-Specific Features:

• Leverage Docker compatibility for faster setup
• Use Daytona's LSP and Git APIs for better integration
• Support stateful sandboxes for session continuity
• Implement workspace persistence options
• Support custom Daytona server URLs

Prerequisites:

• Daytona API key validation
• Daytona CLI installation check
• Document Daytona setup in README.md

Configuration:

• Support DAYTONA_API_KEY environment variable
• Support DAYTONA_SERVER_URL for self-hosted instances
• Support DAYTONA_WORKSPACE_TEMPLATE for workspace configuration
• Create example Daytona configuration in ~/.ralph/sandbox-daytona.json

Phase 6.7: Cloudflare Edge Compute Sandbox Integration (Sub-Issue #80)

Implement Cloudflare Workers as a sandbox provider:

Cloudflare Provider Functions:

• init_cloudflare_sandbox() - Deploy to Cloudflare Workers
• execute_cloudflare() - Execute Claude Code via Workers
• cleanup_cloudflare() - Cleanup Workers deployment
• cloudflare_is_available() - Check Cloudflare API availability

Cloudflare-Specific Features:

• Deploy project as Cloudflare Worker
• Use Durable Objects for state persistence
• Leverage KV storage for file access
• Support global distribution
• Implement cost tracking for Workers

Prerequisites:

• Cloudflare API key validation
• Wrangler CLI installation check
• Document Cloudflare setup in README.md

Configuration:

• Support CLOUDFLARE_API_KEY environment variable
• Support CLOUDFLARE_ACCOUNT_ID for account selection
• Support CLOUDFLARE_WORKER_NAME for deployment naming
• Create example Cloudflare configuration in ~/.ralph/sandbox-cloudflare.json

Phase 6.0: CLI Integration and Configuration

Modify the CLI argument parsing section (lines 1138-1229) in ralph_loop.sh to add:

New Flags:

• --sandbox PROVIDER - Select sandbox provider: docker (default), e2b, daytona, cloudflare
• --sync-strategy STRATEGY - File sync strategy: snapshot (default), realtime
• --ephemeral|--persist - Ephemeral (default) or persistent sandbox
• --max-duration MIN - Maximum execution duration in minutes
• --allow-network - Allow network access (default: disabled)
• --sandbox-config FILE - Path to sandbox-specific configuration file

Configuration Variables (add to configuration section, lines 1-90):

• SANDBOX_PROVIDER="docker" - Default to Docker execution
• SYNC_STRATEGY="snapshot" - Default to snapshot synchronization
• SANDBOX_EPHEMERAL="true" - Default to ephemeral sandboxes
• SANDBOX_MAX_DURATION="" - Optional execution duration limit
• SANDBOX_ALLOW_NETWORK="false" - Default to network isolation
• SANDBOX_CONFIG_FILE="" - Optional sandbox config file path
• SANDBOX_SESSION_ID="" - Track sandbox session for cleanup

Help Text Updates:
Add new section in show_help() function:

Sandbox Options (Phase 6.0):
    --sandbox PROVIDER      Select execution environment: docker, e2b, daytona, cloudflare (default: docker)
    --sync-strategy STRAT   File sync strategy: snapshot, realtime (default: snapshot)
    --ephemeral|--persist   Ephemeral (default) or persistent sandbox
    --max-duration MIN      Maximum execution duration in minutes
    --allow-network         Allow network access (default: disabled)
    --sandbox-config FILE   Path to sandbox configuration file

Phase 6.0: Modify execute_claude_code() Function

Update execute_claude_code() function (lines 735-925) to route through sandbox manager:

Changes:

• After building Claude command (line 768), call init_sandbox() to prepare environment
• Call sync_to_sandbox() to upload project files before execution
• Replace direct execution (lines 779-802) with execute_in_sandbox() call
• Call sync_from_sandbox() to download modified files after execution
• Handle sandbox-specific errors (connection failures, timeout, resource limits)
• Add sandbox status logging for monitoring
• Call cleanup_sandbox() in cleanup path and on exit

Execution Flow:

build_claude_command() 
  → init_sandbox($SANDBOX_PROVIDER, $SANDBOX_CONFIG_FILE)
  → sync_to_sandbox($PROJECT_DIR, $SANDBOX_ID)
  → execute_in_sandbox($CLAUDE_CMD_ARGS, $output_file, $timeout)
  → sync_from_sandbox($SANDBOX_ID, $PROJECT_DIR)
  → cleanup_sandbox($SANDBOX_SESSION_ID)

Phase 6.0: Update Configuration and Environment Setup

Environment Variables:
Add to documentation and validation:

• SANDBOX_PROVIDER - Default sandbox provider (docker/e2b/daytona/cloudflare)
• DOCKER_IMAGE - Docker image to use (default: ubuntu:latest)
• E2B_API_KEY - E2B authentication token
• DAYTONA_API_KEY - Daytona authentication token
• DAYTONA_SERVER_URL - Daytona server URL for self-hosted
• CLOUDFLARE_API_KEY - Cloudflare authentication token
• CLOUDFLARE_ACCOUNT_ID - Cloudflare account ID
• SANDBOX_TIMEOUT - Sandbox execution timeout
• SYNC_TIMEOUT - File synchronization timeout

Config File Support (.ralphrc):

# Sandbox configuration
SANDBOX_PROVIDER=docker
SYNC_STRATEGY=snapshot
SANDBOX_EPHEMERAL=true
SANDBOX_MAX_DURATION=30
DOCKER_IMAGE=ubuntu:latest
DOCKER_MEMORY_LIMIT=2g
DOCKER_CPU_LIMIT=2

Sandbox Config Files:
Create example configs:

• ~/.ralph/sandbox-docker.json - Docker-specific settings (image, resources, volumes)
• ~/.ralph/sandbox-e2b.json - E2B-specific settings (template, region, resources)
• ~/.ralph/sandbox-daytona.json - Daytona-specific settings (workspace template, resources)
• ~/.ralph/sandbox-cloudflare.json - Cloudflare-specific settings (worker name, KV namespace)
• ~/.ralph/sandbox-sync.json - File sync configuration (strategy, exclusions, timeout)
• ~/.ralph/sandbox-security.json - Security policies (resource limits, network access, secrets)

Phase 6.0: Update install.sh

Modify file:install.sh to:

• Copy lib/sandbox_manager.sh, lib/sandbox_sync.sh, lib/sandbox_security.sh to ~/.ralph/lib/
• Create example sandbox config files in ~/.ralph/
• Check for optional dependencies (Docker, E2B CLI, Daytona CLI, Wrangler)
• Display sandbox setup instructions if dependencies missing
• Create .ralphignore template for file sync exclusions

Phase 6.0: Add Monitoring and Status Updates

Extend ralph_monitor.sh:

• Display current sandbox provider in status dashboard
• Show sandbox session ID and status
• Display sandbox-specific metrics (startup time, resource usage, file sync time)
• Show cost tracking for cloud-based sandboxes
• Display resource utilization (CPU, memory, disk)

Update status.json:
Add sandbox fields:

{
  "sandbox": {
    "provider": "docker",
    "session_id": "docker-container-abc123",
    "status": "active",
    "startup_time_ms": 150,
    "sync_time_ms": 250,
    "resource_usage": {
      "cpu_percent": 45.2,
      "memory_mb": 512,
      "disk_mb": 1024
    },
    "cost_estimate_usd": 0.05
  }
}

Phase 6.0: Testing Strategy

Unit Tests (file:tests/unit/test_sandbox_manager.bats):

• Test sandbox provider selection logic
• Test configuration validation for all providers
• Test error handling for missing credentials
• Test sandbox routing logic (docker/e2b/daytona/cloudflare)
• Mock sandbox API calls
• Test provider availability checks

Unit Tests (file:tests/unit/test_sandbox_sync.bats):

• Test snapshot sync strategy
• Test realtime sync strategy
• Test file exclusion patterns
• Test large file handling
• Test permission preservation
• Test symlink handling

Unit Tests (file:tests/unit/test_sandbox_security.bats):

• Test secret injection
• Test resource limit validation
• Test network isolation
• Test privilege escalation prevention
• Test audit logging

Integration Tests (file:tests/integration/test_sandbox_docker.bats):

• Test Docker sandbox lifecycle (create → execute → cleanup)
• Test Docker container resource limits
• Test Docker volume mounting
• Test Docker network isolation
• Test Docker failure recovery

Integration Tests (file:tests/integration/test_sandbox_e2b.bats):

• Test E2B sandbox lifecycle
• Test E2B API error handling
• Test E2B file synchronization
• Test E2B cost tracking
• Test E2B region selection

Integration Tests (file:tests/integration/test_sandbox_daytona.bats):

• Test Daytona workspace lifecycle
• Test Daytona API error handling
• Test Daytona file synchronization
• Test Daytona workspace persistence
• Test Daytona custom server URLs

Integration Tests (file:tests/integration/test_sandbox_cloudflare.bats):

• Test Cloudflare Workers deployment
• Test Cloudflare KV storage
• Test Cloudflare Durable Objects
• Test Cloudflare cost tracking

E2E Tests (file:tests/e2e/test_sandbox_workflows.bats):

• Test complete Ralph loop with Docker sandbox
• Test complete Ralph loop with E2B sandbox
• Test complete Ralph loop with Daytona sandbox
• Test complete Ralph loop with Cloudflare sandbox
• Test sandbox switching between loops
• Test session continuity across sandbox instances
• Test file synchronization end-to-end
• Test security policy enforcement

Phase 6.0: Documentation Updates

README.md:
Add new section "Sandbox Execution Environments":

• Overview of sandbox options and comparison table
• Setup instructions for Docker (no external dependencies)
• Setup instructions for E2B (API key, CLI installation)
• Setup instructions for Daytona (API key, CLI installation)
• Setup instructions for Cloudflare (API key, Wrangler installation)
• Usage examples with --sandbox flag
• Comparison table: Docker vs E2B vs Daytona vs Cloudflare
• Cost considerations for cloud-based sandboxes
• Troubleshooting sandbox issues

New Documentation Files:

• docs/SANDBOX_SETUP.md - Detailed sandbox configuration guide
• docs/SANDBOX_DOCKER.md - Docker-specific setup and usage
• docs/SANDBOX_E2B.md - E2B-specific setup and usage
• docs/SANDBOX_DAYTONA.md - Daytona-specific setup and usage
• docs/SANDBOX_CLOUDFLARE.md - Cloudflare-specific setup and usage
• docs/SANDBOX_SECURITY.md - Security policies and best practices
• docs/SANDBOX_PLUGINS.md - Plugin architecture and custom providers

Update Existing Docs:

• Add sandbox flags to command reference in README.md
• Update show_help() output with sandbox options
• Add sandbox examples to usage section
• Update CLAUDE.md with sandbox architecture

Phase 6.0: Backward Compatibility and Migration

Ensure Backward Compatibility:

• Default SANDBOX_PROVIDER=docker maintains isolated execution
• No breaking changes to existing CLI flags
• Existing projects work without modification
• Sandbox features are opt-in
• Local execution available via --sandbox docker with local volume mount

Migration Path:

• Users can test sandbox execution with --sandbox e2b flag
• No changes required to existing Ralph projects
• Sandbox config files are optional
• Clear error messages guide users through sandbox setup
• Provide migration guide for users upgrading from Phase 5.0

Architecture Diagram

sequenceDiagram
    participant User
    participant ralph_loop.sh
    participant sandbox_manager.sh
    participant sandbox_sync.sh
    participant sandbox_security.sh
    participant Docker
    participant E2B
    participant Claude Code

    User->>ralph_loop.sh: ralph --sandbox e2b --sync-strategy snapshot
    ralph_loop.sh->>ralph_loop.sh: Parse CLI flags
    ralph_loop.sh->>sandbox_manager.sh: init_sandbox("e2b", config)
    sandbox_manager.sh->>E2B: Create sandbox instance
    E2B-->>sandbox_manager.sh: sandbox_id
    
    loop Each Loop Iteration
        ralph_loop.sh->>sandbox_security.sh: inject_secrets()
        ralph_loop.sh->>sandbox_sync.sh: sync_to_sandbox(project_dir)
        sandbox_sync.sh->>E2B: Upload project files
        
        ralph_loop.sh->>sandbox_manager.sh: execute_in_sandbox(cmd, output)
        sandbox_manager.sh->>E2B: Execute Claude Code
        E2B->>Claude Code: Run in isolated environment
        Claude Code-->>E2B: Execution results
        
        ralph_loop.sh->>sandbox_sync.sh: sync_from_sandbox()
        sandbox_sync.sh->>E2B: Download modified files
        E2B-->>sandbox_sync.sh: Files + output
    end
    
    ralph_loop.sh->>sandbox_manager.sh: cleanup_sandbox(sandbox_id)
    sandbox_manager.sh->>E2B: Terminate sandbox
    E2B-->>sandbox_manager.sh: Cleanup complete

Loading

Rollout Strategy

Phase 6.1 - Docker Sandbox Foundation (Week 1-2)

• Implement lib/sandbox_manager.sh with Docker provider
• Add CLI flags and routing logic
• Test Docker sandbox lifecycle
• Deliverable: Docker sandbox fully functional, foundation for other providers

Phase 6.2 - File Synchronization (Week 2-3)

• Implement lib/sandbox_sync.sh with snapshot and realtime strategies
• Add sync configuration and validation
• Test file synchronization with Docker
• Deliverable: File sync working with Docker, ready for cloud providers

Phase 6.3 - Security and Resource Policies (Week 3-4)

• Implement lib/sandbox_security.sh with secret management and resource limits
• Add security configuration and validation
• Test security policies with Docker
• Deliverable: Security framework in place for all providers

Phase 6.4 - E2B Cloud Integration (Week 4-5)

• Implement E2B provider functions
• Add E2B configuration and validation
• Test E2B sandbox lifecycle with file sync and security
• Document E2B setup and usage
• Deliverable: E2B sandbox fully functional

Phase 6.5 - Generic Plugin Architecture (Week 5-6)

• Create plugin interface and provider registry
• Refactor existing providers to use plugin system
• Document plugin development guide
• Deliverable: Plugin system ready for community contributions

Phase 6.6 - Daytona Self-Hosted Integration (Week 6-7)

• Implement Daytona provider functions
• Add Daytona configuration and validation
• Test Daytona sandbox lifecycle
• Document Daytona setup and usage
• Deliverable: Daytona sandbox fully functional

Phase 6.7 - Cloudflare Edge Compute Integration (Week 7-8)

• Implement Cloudflare Workers provider
• Add Cloudflare configuration and validation
• Test Cloudflare sandbox lifecycle
• Document Cloudflare setup and usage
• Deliverable: Cloudflare sandbox fully functional

Phase 6.0 - Polish and Documentation (Week 8-9)

• Comprehensive testing across all providers
• Performance optimization
• Complete documentation
• Example configurations and tutorials
• Deliverable: Production-ready Phase 6.0

Success Criteria

• ✅ Ralph executes Claude Code in Docker sandbox with --sandbox docker flag
• ✅ Ralph executes Claude Code in E2B sandbox with --sandbox e2b flag
• ✅ Ralph executes Claude Code in Daytona sandbox with --sandbox daytona flag
• ✅ Ralph executes Claude Code in Cloudflare sandbox with --sandbox cloudflare flag
• ✅ File synchronization works correctly for all sandbox providers
• ✅ Security policies enforce resource limits and network isolation
• ✅ Sandbox cleanup occurs on normal exit and interruption
• ✅ Error messages guide users through sandbox setup
• ✅ All existing tests pass without modification
• ✅ New tests cover sandbox functionality (80+ tests across all providers)
• ✅ Documentation includes setup and usage examples for all providers
• ✅ Plugin architecture enables community contributions
• ✅ Cost tracking available for cloud-based sandboxes
• ✅ Monitoring integration shows sandbox metrics in ralph-monitor

Import In IDE

🤖 Prompt for AI Agents

## Observations

Ralph is a mature bash-based autonomous development loop tool with 276 passing tests and modular architecture. The current execution model runs Claude Code CLI directly on the local machine via `execute_claude_code()` in `file:ralph_loop.sh`. The codebase follows a library pattern with modules in `file:lib/` (circuit_breaker.sh, response_analyzer.sh, date_utils.sh). CLI argument parsing occurs at lines 1138-1229, command building at lines 679-732, and execution at lines 735-925. Multiple sandbox platforms provide isolated execution: Docker (local, no external dependencies), E2B (Firecracker microVMs, <200ms startup), Daytona (Docker-compatible, sub-90ms startup), and Cloudflare (edge compute). The implementation must address file synchronization, secret management, monitoring integration, cost management, and state persistence across all providers.

## Approach

Implement a comprehensive sandbox abstraction layer with a generic interface that supports multiple providers. Start with Docker as the foundation (no external dependencies), then implement file synchronization and security policies as cross-cutting concerns, followed by cloud providers (E2B, Daytona, Cloudflare). Add CLI flags `--sandbox`, `--sync-strategy`, `--ephemeral|--persist`, and `--max-duration` to control sandbox behavior. Modify `execute_claude_code()` to route through the sandbox manager. This approach maintains backward compatibility (local execution remains default), follows the existing modular pattern, and enables future provider additions via a plugin architecture. The implementation prioritizes the recommended order: Docker foundation, file sync, security policies, then cloud providers.

## Implementation Steps

### Phase 6.1: Docker Sandbox Foundation (Sub-Issue #74)

Create `file:lib/sandbox_manager.sh` as the core abstraction layer with Docker as the first provider:

**Core Functions (Generic Interface):**
- `init_sandbox()` - Initialize sandbox based on selected provider (docker/e2b/daytona/cloudflare)
- `execute_in_sandbox()` - Execute Claude Code command in the selected sandbox environment
- `cleanup_sandbox()` - Cleanup sandbox resources after execution
- `get_sandbox_status()` - Query sandbox health and availability
- `validate_sandbox_config()` - Validate sandbox-specific configuration
- `get_sandbox_provider()` - Return current provider name

**Docker Provider Functions:**
- `init_docker_sandbox()` - Create Docker container with project volume mount
- `execute_docker()` - Execute Claude Code inside Docker container
- `cleanup_docker()` - Stop and remove Docker container
- `docker_is_available()` - Check Docker daemon availability

**Docker-Specific Features:**
- Use lightweight base image (alpine or ubuntu-slim)
- Mount project directory as volume for file access
- Support custom Dockerfile for project-specific dependencies
- Implement container resource limits (CPU, memory)
- Handle container networking (localhost access)

**Configuration Management:**
- Support environment variables: `SANDBOX_PROVIDER`, `DOCKER_IMAGE`, `DOCKER_MEMORY_LIMIT`, `DOCKER_CPU_LIMIT`
- Support config file entries in `.ralphrc`: `SANDBOX_PROVIDER=docker`, `DOCKER_IMAGE=ubuntu:latest`
- Validate Docker installation and daemon availability
- Create example Docker configuration in `~/.ralph/sandbox-docker.json`

### Phase 6.2: File Synchronization (Sub-Issue #76)

Create `file:lib/sandbox_sync.sh` to handle bidirectional file synchronization:

**Core Sync Functions:**
- `init_sync_strategy()` - Initialize sync strategy (snapshot or realtime)
- `sync_to_sandbox()` - Upload project files to sandbox before execution
- `sync_from_sandbox()` - Download modified files from sandbox after execution
- `validate_sync_config()` - Validate sync configuration and paths

**Snapshot Strategy (default):**
- Upload entire project directory before execution
- Download modified files after execution
- Efficient for small projects, simple implementation
- Suitable for ephemeral sandboxes

**Realtime Strategy (advanced):**
- Watch for file changes and sync incrementally
- Use rsync or similar for efficient transfer
- Suitable for persistent sandboxes
- Requires additional dependencies

**File Handling:**
- Exclude patterns: `.git/`, `node_modules/`, `.env`, `*.log`
- Preserve file permissions and timestamps
- Handle symlinks appropriately
- Support large files (>100MB)
- Implement retry logic for failed transfers

**Configuration:**
- Support `--sync-strategy snapshot|realtime` flag
- Support `.ralphignore` file for exclusion patterns
- Support `SYNC_TIMEOUT` environment variable
- Create example sync configuration in `~/.ralph/sandbox-sync.json`

### Phase 6.3: Sandbox Security and Resource Policies (Sub-Issue #77)

Create `file:lib/sandbox_security.sh` to enforce security boundaries:

**Secret Management:**
- `inject_secrets()` - Securely inject environment variables into sandbox
- `validate_secret_sources()` - Validate secret file/env var sources
- Support `.env` file injection with validation
- Support environment variable mapping
- Prevent secret leakage in logs

**Resource Policies:**
- `set_resource_limits()` - Apply CPU, memory, disk, and network limits
- `validate_resource_config()` - Validate resource limit configuration
- Support `--max-duration MIN` flag for execution timeout
- Support `--max-memory MB` for memory limits
- Support `--max-cpu CORES` for CPU limits

**Sandbox Isolation:**
- Disable network access by default (configurable)
- Restrict file system access to project directory
- Prevent privilege escalation
- Disable dangerous system calls
- Support allowlist-based network access

**Audit and Logging:**
- Log all sandbox operations
- Track resource usage per execution
- Log security policy violations
- Support audit trail for compliance

**Configuration:**
- Support `~/.ralph/sandbox-security.json` for policies
- Support `--allow-network` flag for network access
- Support `--allow-privileged` flag (with warnings)
- Create example security configuration

### Phase 6.4: E2B Cloud Sandbox Integration (Sub-Issue #75)

Implement E2B provider after Docker foundation is stable:

**E2B Provider Functions:**
- `init_e2b_sandbox()` - Create E2B sandbox instance via API
- `execute_e2b()` - Execute Claude Code in E2B environment
- `cleanup_e2b()` - Terminate E2B sandbox instance
- `e2b_is_available()` - Check E2B API availability

**E2B-Specific Features:**
- Use E2B SDK or REST API for sandbox management
- Support E2B templates for pre-configured environments
- Handle E2B region selection
- Implement E2B cost tracking
- Support E2B session persistence

**Prerequisites:**
- E2B API key validation in `validate_sandbox_config()`
- E2B CLI or SDK installation check in `install.sh`
- Document E2B setup in README.md

**Configuration:**
- Support `E2B_API_KEY` environment variable
- Support `E2B_TEMPLATE` for environment selection
- Support `E2B_REGION` for geographic selection
- Create example E2B configuration in `~/.ralph/sandbox-e2b.json`

### Phase 6.5: Generic Sandbox Interface and Plugin Architecture (Sub-Issue #78)

Create extensible plugin system for future sandbox providers:

**Plugin Interface:**
- Define standard functions each provider must implement
- Create provider registry system
- Support dynamic provider loading
- Implement provider discovery mechanism

**Standard Provider Functions:**
- `provider_init()` - Initialize provider
- `provider_execute()` - Execute command
- `provider_cleanup()` - Cleanup resources
- `provider_validate()` - Validate configuration
- `provider_status()` - Get provider status

**Plugin Discovery:**
- Load providers from `~/.ralph/providers/` directory
- Support provider metadata files
- Implement provider version checking
- Support provider dependencies

**Provider Registry:**
- Maintain list of available providers
- Support provider enable/disable
- Track provider capabilities
- Support provider configuration per project

### Phase 6.6: Daytona Self-Hosted Sandbox Integration (Sub-Issue #79)

Implement Daytona provider following E2B pattern:

**Daytona Provider Functions:**
- `init_daytona_sandbox()` - Create Daytona workspace via API
- `execute_daytona()` - Execute Claude Code in Daytona environment
- `cleanup_daytona()` - Destroy Daytona workspace
- `daytona_is_available()` - Check Daytona API availability

**Daytona-Specific Features:**
- Leverage Docker compatibility for faster setup
- Use Daytona's LSP and Git APIs for better integration
- Support stateful sandboxes for session continuity
- Implement workspace persistence options
- Support custom Daytona server URLs

**Prerequisites:**
- Daytona API key validation
- Daytona CLI installation check
- Document Daytona setup in README.md

**Configuration:**
- Support `DAYTONA_API_KEY` environment variable
- Support `DAYTONA_SERVER_URL` for self-hosted instances
- Support `DAYTONA_WORKSPACE_TEMPLATE` for workspace configuration
- Create example Daytona configuration in `~/.ralph/sandbox-daytona.json`

### Phase 6.7: Cloudflare Edge Compute Sandbox Integration (Sub-Issue #80)

Implement Cloudflare Workers as a sandbox provider:

**Cloudflare Provider Functions:**
- `init_cloudflare_sandbox()` - Deploy to Cloudflare Workers
- `execute_cloudflare()` - Execute Claude Code via Workers
- `cleanup_cloudflare()` - Cleanup Workers deployment
- `cloudflare_is_available()` - Check Cloudflare API availability

**Cloudflare-Specific Features:**
- Deploy project as Cloudflare Worker
- Use Durable Objects for state persistence
- Leverage KV storage for file access
- Support global distribution
- Implement cost tracking for Workers

**Prerequisites:**
- Cloudflare API key validation
- Wrangler CLI installation check
- Document Cloudflare setup in README.md

**Configuration:**
- Support `CLOUDFLARE_API_KEY` environment variable
- Support `CLOUDFLARE_ACCOUNT_ID` for account selection
- Support `CLOUDFLARE_WORKER_NAME` for deployment naming
- Create example Cloudflare configuration in `~/.ralph/sandbox-cloudflare.json`

### Phase 6.0: CLI Integration and Configuration

Modify the CLI argument parsing section (lines 1138-1229) in `ralph_loop.sh` to add:

**New Flags:**
- `--sandbox PROVIDER` - Select sandbox provider: `docker` (default), `e2b`, `daytona`, `cloudflare`
- `--sync-strategy STRATEGY` - File sync strategy: `snapshot` (default), `realtime`
- `--ephemeral|--persist` - Ephemeral (default) or persistent sandbox
- `--max-duration MIN` - Maximum execution duration in minutes
- `--allow-network` - Allow network access (default: disabled)
- `--sandbox-config FILE` - Path to sandbox-specific configuration file

**Configuration Variables (add to configuration section, lines 1-90):**
- `SANDBOX_PROVIDER="docker"` - Default to Docker execution
- `SYNC_STRATEGY="snapshot"` - Default to snapshot synchronization
- `SANDBOX_EPHEMERAL="true"` - Default to ephemeral sandboxes
- `SANDBOX_MAX_DURATION=""` - Optional execution duration limit
- `SANDBOX_ALLOW_NETWORK="false"` - Default to network isolation
- `SANDBOX_CONFIG_FILE=""` - Optional sandbox config file path
- `SANDBOX_SESSION_ID=""` - Track sandbox session for cleanup

**Help Text Updates:**
Add new section in `show_help()` function:
```
Sandbox Options (Phase 6.0):
    --sandbox PROVIDER      Select execution environment: docker, e2b, daytona, cloudflare (default: docker)
    --sync-strategy STRAT   File sync strategy: snapshot, realtime (default: snapshot)
    --ephemeral|--persist   Ephemeral (default) or persistent sandbox
    --max-duration MIN      Maximum execution duration in minutes
    --allow-network         Allow network access (default: disabled)
    --sandbox-config FILE   Path to sandbox configuration file
```

### Phase 6.0: Modify execute_claude_code() Function

Update `execute_claude_code()` function (lines 735-925) to route through sandbox manager:

**Changes:**
- After building Claude command (line 768), call `init_sandbox()` to prepare environment
- Call `sync_to_sandbox()` to upload project files before execution
- Replace direct execution (lines 779-802) with `execute_in_sandbox()` call
- Call `sync_from_sandbox()` to download modified files after execution
- Handle sandbox-specific errors (connection failures, timeout, resource limits)
- Add sandbox status logging for monitoring
- Call `cleanup_sandbox()` in cleanup path and on exit

**Execution Flow:**
```
build_claude_command() 
  → init_sandbox($SANDBOX_PROVIDER, $SANDBOX_CONFIG_FILE)
  → sync_to_sandbox($PROJECT_DIR, $SANDBOX_ID)
  → execute_in_sandbox($CLAUDE_CMD_ARGS, $output_file, $timeout)
  → sync_from_sandbox($SANDBOX_ID, $PROJECT_DIR)
  → cleanup_sandbox($SANDBOX_SESSION_ID)
```

### Phase 6.0: Update Configuration and Environment Setup

**Environment Variables:**
Add to documentation and validation:
- `SANDBOX_PROVIDER` - Default sandbox provider (docker/e2b/daytona/cloudflare)
- `DOCKER_IMAGE` - Docker image to use (default: ubuntu:latest)
- `E2B_API_KEY` - E2B authentication token
- `DAYTONA_API_KEY` - Daytona authentication token
- `DAYTONA_SERVER_URL` - Daytona server URL for self-hosted
- `CLOUDFLARE_API_KEY` - Cloudflare authentication token
- `CLOUDFLARE_ACCOUNT_ID` - Cloudflare account ID
- `SANDBOX_TIMEOUT` - Sandbox execution timeout
- `SYNC_TIMEOUT` - File synchronization timeout

**Config File Support (.ralphrc):**
```bash
# Sandbox configuration
SANDBOX_PROVIDER=docker
SYNC_STRATEGY=snapshot
SANDBOX_EPHEMERAL=true
SANDBOX_MAX_DURATION=30
DOCKER_IMAGE=ubuntu:latest
DOCKER_MEMORY_LIMIT=2g
DOCKER_CPU_LIMIT=2
```

**Sandbox Config Files:**
Create example configs:
- `~/.ralph/sandbox-docker.json` - Docker-specific settings (image, resources, volumes)
- `~/.ralph/sandbox-e2b.json` - E2B-specific settings (template, region, resources)
- `~/.ralph/sandbox-daytona.json` - Daytona-specific settings (workspace template, resources)
- `~/.ralph/sandbox-cloudflare.json` - Cloudflare-specific settings (worker name, KV namespace)
- `~/.ralph/sandbox-sync.json` - File sync configuration (strategy, exclusions, timeout)
- `~/.ralph/sandbox-security.json` - Security policies (resource limits, network access, secrets)

### Phase 6.0: Update install.sh

Modify `file:install.sh` to:
- Copy `lib/sandbox_manager.sh`, `lib/sandbox_sync.sh`, `lib/sandbox_security.sh` to `~/.ralph/lib/`
- Create example sandbox config files in `~/.ralph/`
- Check for optional dependencies (Docker, E2B CLI, Daytona CLI, Wrangler)
- Display sandbox setup instructions if dependencies missing
- Create `.ralphignore` template for file sync exclusions

### Phase 6.0: Add Monitoring and Status Updates

**Extend ralph_monitor.sh:**
- Display current sandbox provider in status dashboard
- Show sandbox session ID and status
- Display sandbox-specific metrics (startup time, resource usage, file sync time)
- Show cost tracking for cloud-based sandboxes
- Display resource utilization (CPU, memory, disk)

**Update status.json:**
Add sandbox fields:
```json
{
  "sandbox": {
    "provider": "docker",
    "session_id": "docker-container-abc123",
    "status": "active",
    "startup_time_ms": 150,
    "sync_time_ms": 250,
    "resource_usage": {
      "cpu_percent": 45.2,
      "memory_mb": 512,
      "disk_mb": 1024
    },
    "cost_estimate_usd": 0.05
  }
}
```

### Phase 6.0: Testing Strategy

**Unit Tests (file:tests/unit/test_sandbox_manager.bats):**
- Test sandbox provider selection logic
- Test configuration validation for all providers
- Test error handling for missing credentials
- Test sandbox routing logic (docker/e2b/daytona/cloudflare)
- Mock sandbox API calls
- Test provider availability checks

**Unit Tests (file:tests/unit/test_sandbox_sync.bats):**
- Test snapshot sync strategy
- Test realtime sync strategy
- Test file exclusion patterns
- Test large file handling
- Test permission preservation
- Test symlink handling

**Unit Tests (file:tests/unit/test_sandbox_security.bats):**
- Test secret injection
- Test resource limit validation
- Test network isolation
- Test privilege escalation prevention
- Test audit logging

**Integration Tests (file:tests/integration/test_sandbox_docker.bats):**
- Test Docker sandbox lifecycle (create → execute → cleanup)
- Test Docker container resource limits
- Test Docker volume mounting
- Test Docker network isolation
- Test Docker failure recovery

**Integration Tests (file:tests/integration/test_sandbox_e2b.bats):**
- Test E2B sandbox lifecycle
- Test E2B API error handling
- Test E2B file synchronization
- Test E2B cost tracking
- Test E2B region selection

**Integration Tests (file:tests/integration/test_sandbox_daytona.bats):**
- Test Daytona workspace lifecycle
- Test Daytona API error handling
- Test Daytona file synchronization
- Test Daytona workspace persistence
- Test Daytona custom server URLs

**Integration Tests (file:tests/integration/test_sandbox_cloudflare.bats):**
- Test Cloudflare Workers deployment
- Test Cloudflare KV storage
- Test Cloudflare Durable Objects
- Test Cloudflare cost tracking

**E2E Tests (file:tests/e2e/test_sandbox_workflows.bats):**
- Test complete Ralph loop with Docker sandbox
- Test complete Ralph loop with E2B sandbox
- Test complete Ralph loop with Daytona sandbox
- Test complete Ralph loop with Cloudflare sandbox
- Test sandbox switching between loops
- Test session continuity across sandbox instances
- Test file synchronization end-to-end
- Test security policy enforcement

### Phase 6.0: Documentation Updates

**README.md:**
Add new section "Sandbox Execution Environments":
- Overview of sandbox options and comparison table
- Setup instructions for Docker (no external dependencies)
- Setup instructions for E2B (API key, CLI installation)
- Setup instructions for Daytona (API key, CLI installation)
- Setup instructions for Cloudflare (API key, Wrangler installation)
- Usage examples with `--sandbox` flag
- Comparison table: Docker vs E2B vs Daytona vs Cloudflare
- Cost considerations for cloud-based sandboxes
- Troubleshooting sandbox issues

**New Documentation Files:**
- `docs/SANDBOX_SETUP.md` - Detailed sandbox configuration guide
- `docs/SANDBOX_DOCKER.md` - Docker-specific setup and usage
- `docs/SANDBOX_E2B.md` - E2B-specific setup and usage
- `docs/SANDBOX_DAYTONA.md` - Daytona-specific setup and usage
- `docs/SANDBOX_CLOUDFLARE.md` - Cloudflare-specific setup and usage
- `docs/SANDBOX_SECURITY.md` - Security policies and best practices
- `docs/SANDBOX_PLUGINS.md` - Plugin architecture and custom providers

**Update Existing Docs:**
- Add sandbox flags to command reference in README.md
- Update `show_help()` output with sandbox options
- Add sandbox examples to usage section
- Update CLAUDE.md with sandbox architecture

### Phase 6.0: Backward Compatibility and Migration

**Ensure Backward Compatibility:**
- Default `SANDBOX_PROVIDER=docker` maintains isolated execution
- No breaking changes to existing CLI flags
- Existing projects work without modification
- Sandbox features are opt-in
- Local execution available via `--sandbox docker` with local volume mount

**Migration Path:**
- Users can test sandbox execution with `--sandbox e2b` flag
- No changes required to existing Ralph projects
- Sandbox config files are optional
- Clear error messages guide users through sandbox setup
- Provide migration guide for users upgrading from Phase 5.0

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant ralph_loop.sh
    participant sandbox_manager.sh
    participant sandbox_sync.sh
    participant sandbox_security.sh
    participant Docker
    participant E2B
    participant Claude Code

    User->>ralph_loop.sh: ralph --sandbox e2b --sync-strategy snapshot
    ralph_loop.sh->>ralph_loop.sh: Parse CLI flags
    ralph_loop.sh->>sandbox_manager.sh: init_sandbox("e2b", config)
    sandbox_manager.sh->>E2B: Create sandbox instance
    E2B-->>sandbox_manager.sh: sandbox_id
    
    loop Each Loop Iteration
        ralph_loop.sh->>sandbox_security.sh: inject_secrets()
        ralph_loop.sh->>sandbox_sync.sh: sync_to_sandbox(project_dir)
        sandbox_sync.sh->>E2B: Upload project files
        
        ralph_loop.sh->>sandbox_manager.sh: execute_in_sandbox(cmd, output)
        sandbox_manager.sh->>E2B: Execute Claude Code
        E2B->>Claude Code: Run in isolated environment
        Claude Code-->>E2B: Execution results
        
        ralph_loop.sh->>sandbox_sync.sh: sync_from_sandbox()
        sandbox_sync.sh->>E2B: Download modified files
        E2B-->>sandbox_sync.sh: Files + output
    end
    
    ralph_loop.sh->>sandbox_manager.sh: cleanup_sandbox(sandbox_id)
    sandbox_manager.sh->>E2B: Terminate sandbox
    E2B-->>sandbox_manager.sh: Cleanup complete
```

## Rollout Strategy

**Phase 6.1 - Docker Sandbox Foundation (Week 1-2)**
- Implement `lib/sandbox_manager.sh` with Docker provider
- Add CLI flags and routing logic
- Test Docker sandbox lifecycle
- Deliverable: Docker sandbox fully functional, foundation for other providers

**Phase 6.2 - File Synchronization (Week 2-3)**
- Implement `lib/sandbox_sync.sh` with snapshot and realtime strategies
- Add sync configuration and validation
- Test file synchronization with Docker
- Deliverable: File sync working with Docker, ready for cloud providers

**Phase 6.3 - Security and Resource Policies (Week 3-4)**
- Implement `lib/sandbox_security.sh` with secret management and resource limits
- Add security configuration and validation
- Test security policies with Docker
- Deliverable: Security framework in place for all providers

**Phase 6.4 - E2B Cloud Integration (Week 4-5)**
- Implement E2B provider functions
- Add E2B configuration and validation
- Test E2B sandbox lifecycle with file sync and security
- Document E2B setup and usage
- Deliverable: E2B sandbox fully functional

**Phase 6.5 - Generic Plugin Architecture (Week 5-6)**
- Create plugin interface and provider registry
- Refactor existing providers to use plugin system
- Document plugin development guide
- Deliverable: Plugin system ready for community contributions

**Phase 6.6 - Daytona Self-Hosted Integration (Week 6-7)**
- Implement Daytona provider functions
- Add Daytona configuration and validation
- Test Daytona sandbox lifecycle
- Document Daytona setup and usage
- Deliverable: Daytona sandbox fully functional

**Phase 6.7 - Cloudflare Edge Compute Integration (Week 7-8)**
- Implement Cloudflare Workers provider
- Add Cloudflare configuration and validation
- Test Cloudflare sandbox lifecycle
- Document Cloudflare setup and usage
- Deliverable: Cloudflare sandbox fully functional

**Phase 6.0 - Polish and Documentation (Week 8-9)**
- Comprehensive testing across all providers
- Performance optimization
- Complete documentation
- Example configurations and tutorials
- Deliverable: Production-ready Phase 6.0

## Success Criteria

- ✅ Ralph executes Claude Code in Docker sandbox with `--sandbox docker` flag
- ✅ Ralph executes Claude Code in E2B sandbox with `--sandbox e2b` flag
- ✅ Ralph executes Claude Code in Daytona sandbox with `--sandbox daytona` flag
- ✅ Ralph executes Claude Code in Cloudflare sandbox with `--sandbox cloudflare` flag
- ✅ File synchronization works correctly for all sandbox providers
- ✅ Security policies enforce resource limits and network isolation
- ✅ Sandbox cleanup occurs on normal exit and interruption
- ✅ Error messages guide users through sandbox setup
- ✅ All existing tests pass without modification
- ✅ New tests cover sandbox functionality (80+ tests across all providers)
- ✅ Documentation includes setup and usage examples for all providers
- ✅ Plugin architecture enables community contributions
- ✅ Cost tracking available for cloud-based sandboxes
- ✅ Monitoring integration shows sandbox metrics in ralph-monitor

---

Execution Information

Branch: main
Commit: d0208c4

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

New Plan

Observations

Ralph is a mature bash-based autonomous development loop tool with 276 passing tests and modular architecture. The current execution model runs Claude Code CLI directly on the local machine via execute_claude_code() in file:ralph_loop.sh. The codebase follows a library pattern with modules in file:lib/ (circuit_breaker.sh, response_analyzer.sh, date_utils.sh). CLI argument parsing occurs at lines 1138-1229, command building at lines 679-732, and execution at lines 735-925. E2B provides Firecracker microVM sandboxes with <200ms startup, while Daytona offers sub-90ms Docker-compatible sandboxes. Both platforms provide secure, isolated environments for AI code execution.

Approach

Introduce a sandbox abstraction layer as a new library module (file:lib/sandbox_manager.sh) that encapsulates execution environment logic. Add CLI flags --sandbox and --sandbox-config to select between local (default), E2B, and Daytona execution modes. Modify execute_claude_code() to route through the sandbox manager instead of direct execution. This approach maintains backward compatibility (local execution remains default), follows the existing modular pattern, and enables future sandbox provider additions without core logic changes. The implementation prioritizes incremental rollout: local wrapper first, then E2B, then Daytona.

Implementation Steps

1. Create Sandbox Abstraction Layer

Create file:lib/sandbox_manager.sh as a new library module with the following functions:

Core Functions:

• init_sandbox() - Initialize sandbox based on selected provider (local/e2b/daytona)
• execute_in_sandbox() - Execute Claude Code command in the selected sandbox environment
• cleanup_sandbox() - Cleanup sandbox resources after execution
• get_sandbox_status() - Query sandbox health and availability
• validate_sandbox_config() - Validate sandbox-specific configuration

Provider-Specific Functions:

• init_local_sandbox() - No-op wrapper for local execution (default behavior)
• init_e2b_sandbox() - Initialize E2B sandbox using E2B SDK/CLI
• init_daytona_sandbox() - Initialize Daytona sandbox using Daytona API
• execute_local() - Direct execution (current behavior)
• execute_e2b() - Execute via E2B sandbox API
• execute_daytona() - Execute via Daytona sandbox API

Configuration Management:

• Support environment variables: E2B_API_KEY, DAYTONA_API_KEY, SANDBOX_TIMEOUT
• Support config file entries in .ralphrc: SANDBOX_PROVIDER, SANDBOX_CONFIG_FILE
• Validate required credentials before sandbox initialization

2. Add CLI Flags to ralph_loop.sh

Modify the CLI argument parsing section (lines 1138-1229) to add:

New Flags:

• --sandbox PROVIDER - Select sandbox provider: local (default), e2b, daytona
• --sandbox-config FILE - Path to sandbox-specific configuration file (JSON/YAML)
• --sandbox-timeout MIN - Sandbox-specific timeout (default: inherits from --timeout)

Configuration Variables (add to configuration section, lines 1-90):

• SANDBOX_PROVIDER="local" - Default to local execution
• SANDBOX_CONFIG_FILE="" - Optional sandbox config file path
• SANDBOX_TIMEOUT="" - Optional sandbox-specific timeout
• SANDBOX_SESSION_ID="" - Track sandbox session for cleanup

Help Text Updates:
Add new section in show_help() function:

Sandbox Options (Phase 5.0):
    --sandbox PROVIDER      Select execution environment: local, e2b, daytona (default: local)
    --sandbox-config FILE   Path to sandbox configuration file
    --sandbox-timeout MIN   Sandbox-specific timeout in minutes

3. Modify execute_claude_code() Function

Update execute_claude_code() function (lines 735-925) to route through sandbox manager:

Changes:

• After building Claude command (line 768), call init_sandbox() to prepare environment
• Replace direct execution (lines 779-802) with execute_in_sandbox() call
• Pass sandbox context (provider, config, session ID) to execution function
• Handle sandbox-specific errors (connection failures, timeout, resource limits)
• Add sandbox status logging for monitoring
• Call cleanup_sandbox() in cleanup path and on exit

Execution Flow:

build_claude_command() 
  → init_sandbox($SANDBOX_PROVIDER, $SANDBOX_CONFIG_FILE)
  → execute_in_sandbox($CLAUDE_CMD_ARGS, $output_file, $timeout)
  → cleanup_sandbox($SANDBOX_SESSION_ID)

4. Implement Local Sandbox Provider (Phase 5.1)

Start with local provider as a wrapper around existing behavior:

Implementation in lib/sandbox_manager.sh:

• init_local_sandbox() - Validate local environment, return success
• execute_local() - Call existing execution logic (lines 779-802)
• cleanup_local() - No-op for local execution

Purpose: Establish abstraction layer without changing behavior, enable testing of sandbox routing logic before adding remote providers.

5. Implement E2B Sandbox Provider (Phase 5.2)

Add E2B integration after local provider is stable:

Prerequisites:

• E2B CLI or SDK installation check in install.sh
• E2B API key validation in validate_sandbox_config()
• Document E2B setup in README.md

Implementation:

• init_e2b_sandbox() - Create E2B sandbox instance via API/CLI, return sandbox ID
• execute_e2b() - Upload project files, execute Claude Code in E2B environment, download results
• cleanup_e2b() - Terminate E2B sandbox instance, cleanup resources

File Synchronization:

• Upload PROMPT.md, @fix_plan.md, specs/ directory to E2B sandbox
• Execute Claude Code within E2B environment
• Download modified files back to local project directory
• Handle git operations within sandbox context

Error Handling:

• E2B API connection failures
• Sandbox creation timeout
• File upload/download errors
• E2B rate limits and quota exhaustion

6. Implement Daytona Sandbox Provider (Phase 5.3)

Add Daytona integration following E2B pattern:

Prerequisites:

• Daytona CLI installation check
• Daytona API key validation
• Document Daytona setup in README.md

Implementation:

• init_daytona_sandbox() - Create Daytona workspace via API
• execute_daytona() - Execute Claude Code in Daytona environment
• cleanup_daytona() - Destroy Daytona workspace

Daytona-Specific Features:

• Leverage Docker compatibility for faster setup
• Use Daytona's LSP and Git APIs for better integration
• Support stateful sandboxes for session continuity

7. Update Configuration and Environment Setup

Environment Variables:
Add to documentation and validation:

• E2B_API_KEY - E2B authentication token
• DAYTONA_API_KEY - Daytona authentication token
• SANDBOX_PROVIDER - Default sandbox provider
• SANDBOX_REGION - Geographic region for sandbox (e2b/daytona)

Config File Support (.ralphrc):

# Sandbox configuration
SANDBOX_PROVIDER=e2b
SANDBOX_CONFIG_FILE=~/.ralph/sandbox-e2b.json
SANDBOX_TIMEOUT=20

Sandbox Config Files:
Create example configs:

• ~/.ralph/sandbox-e2b.json - E2B-specific settings (template, region, resources)
• ~/.ralph/sandbox-daytona.json - Daytona-specific settings (workspace template, resources)

8. Update install.sh

Modify file:install.sh to:

• Copy lib/sandbox_manager.sh to ~/.ralph/lib/
• Create example sandbox config files in ~/.ralph/
• Check for optional dependencies (E2B CLI, Daytona CLI)
• Display sandbox setup instructions if dependencies missing

9. Add Monitoring and Status Updates

Extend ralph_monitor.sh:

• Display current sandbox provider in status dashboard
• Show sandbox session ID and status
• Display sandbox-specific metrics (startup time, resource usage)

Update status.json:
Add sandbox fields:

{
  "sandbox": {
    "provider": "e2b",
    "session_id": "e2b-sandbox-12345",
    "status": "active",
    "startup_time_ms": 180
  }
}

10. Testing Strategy

Unit Tests (file:tests/unit/test_sandbox_manager.bats):

• Test sandbox provider selection logic
• Test configuration validation
• Test error handling for missing credentials
• Test sandbox routing logic (local/e2b/daytona)
• Mock sandbox API calls

Integration Tests (file:tests/integration/test_sandbox_execution.bats):

• Test local sandbox execution (wrapper around existing behavior)
• Test E2B sandbox lifecycle (create → execute → cleanup)
• Test Daytona sandbox lifecycle
• Test file synchronization for remote sandboxes
• Test sandbox timeout handling
• Test sandbox failure recovery

E2E Tests (file:tests/e2e/test_sandbox_workflows.bats):

• Test complete Ralph loop with E2B sandbox
• Test complete Ralph loop with Daytona sandbox
• Test sandbox switching between loops
• Test session continuity across sandbox instances

11. Documentation Updates

README.md:
Add new section "Sandbox Execution Environments":

• Overview of sandbox options
• Setup instructions for E2B (API key, CLI installation)
• Setup instructions for Daytona (API key, CLI installation)
• Usage examples with --sandbox flag
• Comparison table: local vs E2B vs Daytona
• Troubleshooting sandbox issues

New Documentation Files:

• docs/SANDBOX_SETUP.md - Detailed sandbox configuration guide
• docs/E2B_INTEGRATION.md - E2B-specific setup and usage
• docs/DAYTONA_INTEGRATION.md - Daytona-specific setup and usage

Update Existing Docs:

• Add sandbox flags to command reference in README.md
• Update show_help() output with sandbox options
• Add sandbox examples to usage section

12. Backward Compatibility and Migration

Ensure Backward Compatibility:

• Default SANDBOX_PROVIDER=local maintains existing behavior
• No breaking changes to existing CLI flags
• Existing projects work without modification
• Sandbox features are opt-in

Migration Path:

• Users can test sandbox execution with --sandbox e2b flag
• No changes required to existing Ralph projects
• Sandbox config files are optional
• Clear error messages guide users through sandbox setup

Architecture Diagram

sequenceDiagram
    participant User
    participant ralph_loop.sh
    participant sandbox_manager.sh
    participant Local
    participant E2B
    participant Daytona
    participant Claude Code

    User->>ralph_loop.sh: ralph --sandbox e2b --monitor
    ralph_loop.sh->>ralph_loop.sh: Parse CLI flags
    ralph_loop.sh->>sandbox_manager.sh: init_sandbox("e2b", config)
    sandbox_manager.sh->>E2B: Create sandbox instance
    E2B-->>sandbox_manager.sh: sandbox_id
    
    loop Each Loop Iteration
        ralph_loop.sh->>sandbox_manager.sh: execute_in_sandbox(cmd, output)
        sandbox_manager.sh->>E2B: Upload project files
        sandbox_manager.sh->>E2B: Execute Claude Code
        E2B->>Claude Code: Run in isolated environment
        Claude Code-->>E2B: Execution results
        sandbox_manager.sh->>E2B: Download modified files
        E2B-->>sandbox_manager.sh: Files + output
        sandbox_manager.sh-->>ralph_loop.sh: Execution complete
    end
    
    ralph_loop.sh->>sandbox_manager.sh: cleanup_sandbox(sandbox_id)
    sandbox_manager.sh->>E2B: Terminate sandbox
    E2B-->>sandbox_manager.sh: Cleanup complete

Loading

Rollout Strategy

Phase 5.1 - Local Sandbox Wrapper (Week 1)

• Implement lib/sandbox_manager.sh with local provider only
• Add CLI flags and routing logic
• Test abstraction layer without changing behavior
• Deliverable: Sandbox infrastructure ready, no functional changes

Phase 5.2 - E2B Integration (Week 2-3)

• Implement E2B provider functions
• Add E2B configuration and validation
• Test E2B sandbox lifecycle
• Document E2B setup and usage
• Deliverable: E2B sandbox fully functional

Phase 5.3 - Daytona Integration (Week 3-4)

• Implement Daytona provider functions
• Add Daytona configuration and validation
• Test Daytona sandbox lifecycle
• Document Daytona setup and usage
• Deliverable: Daytona sandbox fully functional

Phase 5.4 - Polish and Documentation (Week 4)

• Comprehensive testing across all providers
• Performance optimization
• Complete documentation
• Example configurations and tutorials
• Deliverable: Production-ready Phase 5.0

Success Criteria

• ✅ Ralph executes Claude Code in E2B sandbox with --sandbox e2b flag
• ✅ Ralph executes Claude Code in Daytona sandbox with --sandbox daytona flag
• ✅ Local execution remains default and unchanged
• ✅ File synchronization works correctly for remote sandboxes
• ✅ Sandbox cleanup occurs on normal exit and interruption
• ✅ Error messages guide users through sandbox setup
• ✅ All existing tests pass without modification
• ✅ New tests cover sandbox functionality (30+ tests)
• ✅ Documentation includes sandbox setup and usage examples

Import In IDE

🤖 Prompt for AI Agents

## Observations

Ralph is a mature bash-based autonomous development loop tool with 276 passing tests and modular architecture. The current execution model runs Claude Code CLI directly on the local machine via `execute_claude_code()` in `file:ralph_loop.sh`. The codebase follows a library pattern with modules in `file:lib/` (circuit_breaker.sh, response_analyzer.sh, date_utils.sh). CLI argument parsing occurs at lines 1138-1229, command building at lines 679-732, and execution at lines 735-925. E2B provides Firecracker microVM sandboxes with <200ms startup, while Daytona offers sub-90ms Docker-compatible sandboxes. Both platforms provide secure, isolated environments for AI code execution.

## Approach

Introduce a sandbox abstraction layer as a new library module (`file:lib/sandbox_manager.sh`) that encapsulates execution environment logic. Add CLI flags `--sandbox` and `--sandbox-config` to select between local (default), E2B, and Daytona execution modes. Modify `execute_claude_code()` to route through the sandbox manager instead of direct execution. This approach maintains backward compatibility (local execution remains default), follows the existing modular pattern, and enables future sandbox provider additions without core logic changes. The implementation prioritizes incremental rollout: local wrapper first, then E2B, then Daytona.

## Implementation Steps

### 1. Create Sandbox Abstraction Layer

Create `file:lib/sandbox_manager.sh` as a new library module with the following functions:

**Core Functions:**
- `init_sandbox()` - Initialize sandbox based on selected provider (local/e2b/daytona)
- `execute_in_sandbox()` - Execute Claude Code command in the selected sandbox environment
- `cleanup_sandbox()` - Cleanup sandbox resources after execution
- `get_sandbox_status()` - Query sandbox health and availability
- `validate_sandbox_config()` - Validate sandbox-specific configuration

**Provider-Specific Functions:**
- `init_local_sandbox()` - No-op wrapper for local execution (default behavior)
- `init_e2b_sandbox()` - Initialize E2B sandbox using E2B SDK/CLI
- `init_daytona_sandbox()` - Initialize Daytona sandbox using Daytona API
- `execute_local()` - Direct execution (current behavior)
- `execute_e2b()` - Execute via E2B sandbox API
- `execute_daytona()` - Execute via Daytona sandbox API

**Configuration Management:**
- Support environment variables: `E2B_API_KEY`, `DAYTONA_API_KEY`, `SANDBOX_TIMEOUT`
- Support config file entries in `.ralphrc`: `SANDBOX_PROVIDER`, `SANDBOX_CONFIG_FILE`
- Validate required credentials before sandbox initialization

### 2. Add CLI Flags to ralph_loop.sh

Modify the CLI argument parsing section (lines 1138-1229) to add:

**New Flags:**
- `--sandbox PROVIDER` - Select sandbox provider: `local` (default), `e2b`, `daytona`
- `--sandbox-config FILE` - Path to sandbox-specific configuration file (JSON/YAML)
- `--sandbox-timeout MIN` - Sandbox-specific timeout (default: inherits from `--timeout`)

**Configuration Variables (add to configuration section, lines 1-90):**
- `SANDBOX_PROVIDER="local"` - Default to local execution
- `SANDBOX_CONFIG_FILE=""` - Optional sandbox config file path
- `SANDBOX_TIMEOUT=""` - Optional sandbox-specific timeout
- `SANDBOX_SESSION_ID=""` - Track sandbox session for cleanup

**Help Text Updates:**
Add new section in `show_help()` function:
```
Sandbox Options (Phase 5.0):
    --sandbox PROVIDER      Select execution environment: local, e2b, daytona (default: local)
    --sandbox-config FILE   Path to sandbox configuration file
    --sandbox-timeout MIN   Sandbox-specific timeout in minutes
```

### 3. Modify execute_claude_code() Function

Update `execute_claude_code()` function (lines 735-925) to route through sandbox manager:

**Changes:**
- After building Claude command (line 768), call `init_sandbox()` to prepare environment
- Replace direct execution (lines 779-802) with `execute_in_sandbox()` call
- Pass sandbox context (provider, config, session ID) to execution function
- Handle sandbox-specific errors (connection failures, timeout, resource limits)
- Add sandbox status logging for monitoring
- Call `cleanup_sandbox()` in cleanup path and on exit

**Execution Flow:**
```
build_claude_command() 
  → init_sandbox($SANDBOX_PROVIDER, $SANDBOX_CONFIG_FILE)
  → execute_in_sandbox($CLAUDE_CMD_ARGS, $output_file, $timeout)
  → cleanup_sandbox($SANDBOX_SESSION_ID)
```

### 4. Implement Local Sandbox Provider (Phase 5.1)

Start with local provider as a wrapper around existing behavior:

**Implementation in lib/sandbox_manager.sh:**
- `init_local_sandbox()` - Validate local environment, return success
- `execute_local()` - Call existing execution logic (lines 779-802)
- `cleanup_local()` - No-op for local execution

**Purpose:** Establish abstraction layer without changing behavior, enable testing of sandbox routing logic before adding remote providers.

### 5. Implement E2B Sandbox Provider (Phase 5.2)

Add E2B integration after local provider is stable:

**Prerequisites:**
- E2B CLI or SDK installation check in `install.sh`
- E2B API key validation in `validate_sandbox_config()`
- Document E2B setup in README.md

**Implementation:**
- `init_e2b_sandbox()` - Create E2B sandbox instance via API/CLI, return sandbox ID
- `execute_e2b()` - Upload project files, execute Claude Code in E2B environment, download results
- `cleanup_e2b()` - Terminate E2B sandbox instance, cleanup resources

**File Synchronization:**
- Upload `PROMPT.md`, `@fix_plan.md`, `specs/` directory to E2B sandbox
- Execute Claude Code within E2B environment
- Download modified files back to local project directory
- Handle git operations within sandbox context

**Error Handling:**
- E2B API connection failures
- Sandbox creation timeout
- File upload/download errors
- E2B rate limits and quota exhaustion

### 6. Implement Daytona Sandbox Provider (Phase 5.3)

Add Daytona integration following E2B pattern:

**Prerequisites:**
- Daytona CLI installation check
- Daytona API key validation
- Document Daytona setup in README.md

**Implementation:**
- `init_daytona_sandbox()` - Create Daytona workspace via API
- `execute_daytona()` - Execute Claude Code in Daytona environment
- `cleanup_daytona()` - Destroy Daytona workspace

**Daytona-Specific Features:**
- Leverage Docker compatibility for faster setup
- Use Daytona's LSP and Git APIs for better integration
- Support stateful sandboxes for session continuity

### 7. Update Configuration and Environment Setup

**Environment Variables:**
Add to documentation and validation:
- `E2B_API_KEY` - E2B authentication token
- `DAYTONA_API_KEY` - Daytona authentication token
- `SANDBOX_PROVIDER` - Default sandbox provider
- `SANDBOX_REGION` - Geographic region for sandbox (e2b/daytona)

**Config File Support (.ralphrc):**
```bash
# Sandbox configuration
SANDBOX_PROVIDER=e2b
SANDBOX_CONFIG_FILE=~/.ralph/sandbox-e2b.json
SANDBOX_TIMEOUT=20
```

**Sandbox Config Files:**
Create example configs:
- `~/.ralph/sandbox-e2b.json` - E2B-specific settings (template, region, resources)
- `~/.ralph/sandbox-daytona.json` - Daytona-specific settings (workspace template, resources)

### 8. Update install.sh

Modify `file:install.sh` to:
- Copy `lib/sandbox_manager.sh` to `~/.ralph/lib/`
- Create example sandbox config files in `~/.ralph/`
- Check for optional dependencies (E2B CLI, Daytona CLI)
- Display sandbox setup instructions if dependencies missing

### 9. Add Monitoring and Status Updates

**Extend ralph_monitor.sh:**
- Display current sandbox provider in status dashboard
- Show sandbox session ID and status
- Display sandbox-specific metrics (startup time, resource usage)

**Update status.json:**
Add sandbox fields:
```json
{
  "sandbox": {
    "provider": "e2b",
    "session_id": "e2b-sandbox-12345",
    "status": "active",
    "startup_time_ms": 180
  }
}
```

### 10. Testing Strategy

**Unit Tests (file:tests/unit/test_sandbox_manager.bats):**
- Test sandbox provider selection logic
- Test configuration validation
- Test error handling for missing credentials
- Test sandbox routing logic (local/e2b/daytona)
- Mock sandbox API calls

**Integration Tests (file:tests/integration/test_sandbox_execution.bats):**
- Test local sandbox execution (wrapper around existing behavior)
- Test E2B sandbox lifecycle (create → execute → cleanup)
- Test Daytona sandbox lifecycle
- Test file synchronization for remote sandboxes
- Test sandbox timeout handling
- Test sandbox failure recovery

**E2E Tests (file:tests/e2e/test_sandbox_workflows.bats):**
- Test complete Ralph loop with E2B sandbox
- Test complete Ralph loop with Daytona sandbox
- Test sandbox switching between loops
- Test session continuity across sandbox instances

### 11. Documentation Updates

**README.md:**
Add new section "Sandbox Execution Environments":
- Overview of sandbox options
- Setup instructions for E2B (API key, CLI installation)
- Setup instructions for Daytona (API key, CLI installation)
- Usage examples with `--sandbox` flag
- Comparison table: local vs E2B vs Daytona
- Troubleshooting sandbox issues

**New Documentation Files:**
- `docs/SANDBOX_SETUP.md` - Detailed sandbox configuration guide
- `docs/E2B_INTEGRATION.md` - E2B-specific setup and usage
- `docs/DAYTONA_INTEGRATION.md` - Daytona-specific setup and usage

**Update Existing Docs:**
- Add sandbox flags to command reference in README.md
- Update `show_help()` output with sandbox options
- Add sandbox examples to usage section

### 12. Backward Compatibility and Migration

**Ensure Backward Compatibility:**
- Default `SANDBOX_PROVIDER=local` maintains existing behavior
- No breaking changes to existing CLI flags
- Existing projects work without modification
- Sandbox features are opt-in

**Migration Path:**
- Users can test sandbox execution with `--sandbox e2b` flag
- No changes required to existing Ralph projects
- Sandbox config files are optional
- Clear error messages guide users through sandbox setup

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant ralph_loop.sh
    participant sandbox_manager.sh
    participant Local
    participant E2B
    participant Daytona
    participant Claude Code

    User->>ralph_loop.sh: ralph --sandbox e2b --monitor
    ralph_loop.sh->>ralph_loop.sh: Parse CLI flags
    ralph_loop.sh->>sandbox_manager.sh: init_sandbox("e2b", config)
    sandbox_manager.sh->>E2B: Create sandbox instance
    E2B-->>sandbox_manager.sh: sandbox_id
    
    loop Each Loop Iteration
        ralph_loop.sh->>sandbox_manager.sh: execute_in_sandbox(cmd, output)
        sandbox_manager.sh->>E2B: Upload project files
        sandbox_manager.sh->>E2B: Execute Claude Code
        E2B->>Claude Code: Run in isolated environment
        Claude Code-->>E2B: Execution results
        sandbox_manager.sh->>E2B: Download modified files
        E2B-->>sandbox_manager.sh: Files + output
        sandbox_manager.sh-->>ralph_loop.sh: Execution complete
    end
    
    ralph_loop.sh->>sandbox_manager.sh: cleanup_sandbox(sandbox_id)
    sandbox_manager.sh->>E2B: Terminate sandbox
    E2B-->>sandbox_manager.sh: Cleanup complete
```

## Rollout Strategy

**Phase 5.1 - Local Sandbox Wrapper (Week 1)**
- Implement `lib/sandbox_manager.sh` with local provider only
- Add CLI flags and routing logic
- Test abstraction layer without changing behavior
- Deliverable: Sandbox infrastructure ready, no functional changes

**Phase 5.2 - E2B Integration (Week 2-3)**
- Implement E2B provider functions
- Add E2B configuration and validation
- Test E2B sandbox lifecycle
- Document E2B setup and usage
- Deliverable: E2B sandbox fully functional

**Phase 5.3 - Daytona Integration (Week 3-4)**
- Implement Daytona provider functions
- Add Daytona configuration and validation
- Test Daytona sandbox lifecycle
- Document Daytona setup and usage
- Deliverable: Daytona sandbox fully functional

**Phase 5.4 - Polish and Documentation (Week 4)**
- Comprehensive testing across all providers
- Performance optimization
- Complete documentation
- Example configurations and tutorials
- Deliverable: Production-ready Phase 5.0

## Success Criteria

- ✅ Ralph executes Claude Code in E2B sandbox with `--sandbox e2b` flag
- ✅ Ralph executes Claude Code in Daytona sandbox with `--sandbox daytona` flag
- ✅ Local execution remains default and unchanged
- ✅ File synchronization works correctly for remote sandboxes
- ✅ Sandbox cleanup occurs on normal exit and interruption
- ✅ Error messages guide users through sandbox setup
- ✅ All existing tests pass without modification
- ✅ New tests cover sandbox functionality (30+ tests)
- ✅ Documentation includes sandbox setup and usage examples

---

Execution Information

Branch: main
Commit: d0208c4

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

Previous Plan

Observations

Ralph is a mature bash-based autonomous development loop tool with 276 passing tests and modular architecture. The current execution model runs Claude Code CLI directly on the local machine via execute_claude_code() in file:ralph_loop.sh. The codebase follows a library pattern with modules in file:lib/ (circuit_breaker.sh, response_analyzer.sh, date_utils.sh). CLI argument parsing occurs at lines 1138-1229, command building at lines 679-732, and execution at lines 735-925. E2B provides Firecracker microVM sandboxes with <200ms startup, while Daytona offers sub-90ms Docker-compatible sandboxes. Both platforms provide secure, isolated environments for AI code execution.

Approach

Introduce a sandbox abstraction layer as a new library module (file:lib/sandbox_manager.sh) that encapsulates execution environment logic. Add CLI flags --sandbox and --sandbox-config to select between local (default), E2B, and Daytona execution modes. Modify execute_claude_code() to route through the sandbox manager instead of direct execution. This approach maintains backward compatibility (local execution remains default), follows the existing modular pattern, and enables future sandbox provider additions without core logic changes. The implementation prioritizes incremental rollout: local wrapper first, then E2B, then Daytona.

Implementation Steps

1. Create Sandbox Abstraction Layer

Create file:lib/sandbox_manager.sh as a new library module with the following functions:

Core Functions:

• init_sandbox() - Initialize sandbox based on selected provider (local/e2b/daytona)
• execute_in_sandbox() - Execute Claude Code command in the selected sandbox environment
• cleanup_sandbox() - Cleanup sandbox resources after execution
• get_sandbox_status() - Query sandbox health and availability
• validate_sandbox_config() - Validate sandbox-specific configuration

Provider-Specific Functions:

• init_local_sandbox() - No-op wrapper for local execution (default behavior)
• init_e2b_sandbox() - Initialize E2B sandbox using E2B SDK/CLI
• init_daytona_sandbox() - Initialize Daytona sandbox using Daytona API
• execute_local() - Direct execution (current behavior)
• execute_e2b() - Execute via E2B sandbox API
• execute_daytona() - Execute via Daytona sandbox API

Configuration Management:

• Support environment variables: E2B_API_KEY, DAYTONA_API_KEY, SANDBOX_TIMEOUT
• Support config file entries in .ralphrc: SANDBOX_PROVIDER, SANDBOX_CONFIG_FILE
• Validate required credentials before sandbox initialization

2. Add CLI Flags to ralph_loop.sh

Modify the CLI argument parsing section (lines 1138-1229) to add:

New Flags:

• --sandbox PROVIDER - Select sandbox provider: local (default), e2b, daytona
• --sandbox-config FILE - Path to sandbox-specific configuration file (JSON/YAML)
• --sandbox-timeout MIN - Sandbox-specific timeout (default: inherits from --timeout)

Configuration Variables (add to configuration section, lines 1-90):

• SANDBOX_PROVIDER="local" - Default to local execution
• SANDBOX_CONFIG_FILE="" - Optional sandbox config file path
• SANDBOX_TIMEOUT="" - Optional sandbox-specific timeout
• SANDBOX_SESSION_ID="" - Track sandbox session for cleanup

Help Text Updates:
Add new section in show_help() function:

Sandbox Options (Phase 5.0):
    --sandbox PROVIDER      Select execution environment: local, e2b, daytona (default: local)
    --sandbox-config FILE   Path to sandbox configuration file
    --sandbox-timeout MIN   Sandbox-specific timeout in minutes

3. Modify execute_claude_code() Function

Update execute_claude_code() function (lines 735-925) to route through sandbox manager:

Changes:

• After building Claude command (line 768), call init_sandbox() to prepare environment
• Replace direct execution (lines 779-802) with execute_in_sandbox() call
• Pass sandbox context (provider, config, session ID) to execution function
• Handle sandbox-specific errors (connection failures, timeout, resource limits)
• Add sandbox status logging for monitoring
• Call cleanup_sandbox() in cleanup path and on exit

Execution Flow:

build_claude_command() 
  → init_sandbox($SANDBOX_PROVIDER, $SANDBOX_CONFIG_FILE)
  → execute_in_sandbox($CLAUDE_CMD_ARGS, $output_file, $timeout)
  → cleanup_sandbox($SANDBOX_SESSION_ID)

4. Implement Local Sandbox Provider (Phase 5.1)

Start with local provider as a wrapper around existing behavior:

Implementation in lib/sandbox_manager.sh:

• init_local_sandbox() - Validate local environment, return success
• execute_local() - Call existing execution logic (lines 779-802)
• cleanup_local() - No-op for local execution

Purpose: Establish abstraction layer without changing behavior, enable testing of sandbox routing logic before adding remote providers.

5. Implement E2B Sandbox Provider (Phase 5.2)

Add E2B integration after local provider is stable:

Prerequisites:

• E2B CLI or SDK installation check in install.sh
• E2B API key validation in validate_sandbox_config()
• Document E2B setup in README.md

Implementation:

• init_e2b_sandbox() - Create E2B sandbox instance via API/CLI, return sandbox ID
• execute_e2b() - Upload project files, execute Claude Code in E2B environment, download results
• cleanup_e2b() - Terminate E2B sandbox instance, cleanup resources

File Synchronization:

• Upload PROMPT.md, @fix_plan.md, specs/ directory to E2B sandbox
• Execute Claude Code within E2B environment
• Download modified files back to local project directory
• Handle git operations within sandbox context

Error Handling:

• E2B API connection failures
• Sandbox creation timeout
• File upload/download errors
• E2B rate limits and quota exhaustion

6. Implement Daytona Sandbox Provider (Phase 5.3)

Add Daytona integration following E2B pattern:

Prerequisites:

• Daytona CLI installation check
• Daytona API key validation
• Document Daytona setup in README.md

Implementation:

• init_daytona_sandbox() - Create Daytona workspace via API
• execute_daytona() - Execute Claude Code in Daytona environment
• cleanup_daytona() - Destroy Daytona workspace

Daytona-Specific Features:

• Leverage Docker compatibility for faster setup
• Use Daytona's LSP and Git APIs for better integration
• Support stateful sandboxes for session continuity

7. Update Configuration and Environment Setup

Environment Variables:
Add to documentation and validation:

• E2B_API_KEY - E2B authentication token
• DAYTONA_API_KEY - Daytona authentication token
• SANDBOX_PROVIDER - Default sandbox provider
• SANDBOX_REGION - Geographic region for sandbox (e2b/daytona)

Config File Support (.ralphrc):

# Sandbox configuration
SANDBOX_PROVIDER=e2b
SANDBOX_CONFIG_FILE=~/.ralph/sandbox-e2b.json
SANDBOX_TIMEOUT=20

Sandbox Config Files:
Create example configs:

• ~/.ralph/sandbox-e2b.json - E2B-specific settings (template, region, resources)
• ~/.ralph/sandbox-daytona.json - Daytona-specific settings (workspace template, resources)

8. Update install.sh

Modify file:install.sh to:

• Copy lib/sandbox_manager.sh to ~/.ralph/lib/
• Create example sandbox config files in ~/.ralph/
• Check for optional dependencies (E2B CLI, Daytona CLI)
• Display sandbox setup instructions if dependencies missing

9. Add Monitoring and Status Updates

Extend ralph_monitor.sh:

• Display current sandbox provider in status dashboard
• Show sandbox session ID and status
• Display sandbox-specific metrics (startup time, resource usage)

Update status.json:
Add sandbox fields:

{
  "sandbox": {
    "provider": "e2b",
    "session_id": "e2b-sandbox-12345",
    "status": "active",
    "startup_time_ms": 180
  }
}

10. Testing Strategy

Unit Tests (file:tests/unit/test_sandbox_manager.bats):

• Test sandbox provider selection logic
• Test configuration validation
• Test error handling for missing credentials
• Test sandbox routing logic (local/e2b/daytona)
• Mock sandbox API calls

Integration Tests (file:tests/integration/test_sandbox_execution.bats):

• Test local sandbox execution (wrapper around existing behavior)
• Test E2B sandbox lifecycle (create → execute → cleanup)
• Test Daytona sandbox lifecycle
• Test file synchronization for remote sandboxes
• Test sandbox timeout handling
• Test sandbox failure recovery

E2E Tests (file:tests/e2e/test_sandbox_workflows.bats):

• Test complete Ralph loop with E2B sandbox
• Test complete Ralph loop with Daytona sandbox
• Test sandbox switching between loops
• Test session continuity across sandbox instances

11. Documentation Updates

README.md:
Add new section "Sandbox Execution Environments":

• Overview of sandbox options
• Setup instructions for E2B (API key, CLI installation)
• Setup instructions for Daytona (API key, CLI installation)
• Usage examples with --sandbox flag
• Comparison table: local vs E2B vs Daytona
• Troubleshooting sandbox issues

New Documentation Files:

• docs/SANDBOX_SETUP.md - Detailed sandbox configuration guide
• docs/E2B_INTEGRATION.md - E2B-specific setup and usage
• docs/DAYTONA_INTEGRATION.md - Daytona-specific setup and usage

Update Existing Docs:

• Add sandbox flags to command reference in README.md
• Update show_help() output with sandbox options
• Add sandbox examples to usage section

12. Backward Compatibility and Migration

Ensure Backward Compatibility:

• Default SANDBOX_PROVIDER=local maintains existing behavior
• No breaking changes to existing CLI flags
• Existing projects work without modification
• Sandbox features are opt-in

Migration Path:

• Users can test sandbox execution with --sandbox e2b flag
• No changes required to existing Ralph projects
• Sandbox config files are optional
• Clear error messages guide users through sandbox setup

Architecture Diagram

sequenceDiagram
    participant User
    participant ralph_loop.sh
    participant sandbox_manager.sh
    participant Local
    participant E2B
    participant Daytona
    participant Claude Code

    User->>ralph_loop.sh: ralph --sandbox e2b --monitor
    ralph_loop.sh->>ralph_loop.sh: Parse CLI flags
    ralph_loop.sh->>sandbox_manager.sh: init_sandbox("e2b", config)
    sandbox_manager.sh->>E2B: Create sandbox instance
    E2B-->>sandbox_manager.sh: sandbox_id
    
    loop Each Loop Iteration
        ralph_loop.sh->>sandbox_manager.sh: execute_in_sandbox(cmd, output)
        sandbox_manager.sh->>E2B: Upload project files
        sandbox_manager.sh->>E2B: Execute Claude Code
        E2B->>Claude Code: Run in isolated environment
        Claude Code-->>E2B: Execution results
        sandbox_manager.sh->>E2B: Download modified files
        E2B-->>sandbox_manager.sh: Files + output
        sandbox_manager.sh-->>ralph_loop.sh: Execution complete
    end
    
    ralph_loop.sh->>sandbox_manager.sh: cleanup_sandbox(sandbox_id)
    sandbox_manager.sh->>E2B: Terminate sandbox
    E2B-->>sandbox_manager.sh: Cleanup complete

Loading

Rollout Strategy

Phase 5.1 - Local Sandbox Wrapper (Week 1)

• Implement lib/sandbox_manager.sh with local provider only
• Add CLI flags and routing logic
• Test abstraction layer without changing behavior
• Deliverable: Sandbox infrastructure ready, no functional changes

Phase 5.2 - E2B Integration (Week 2-3)

• Implement E2B provider functions
• Add E2B configuration and validation
• Test E2B sandbox lifecycle
• Document E2B setup and usage
• Deliverable: E2B sandbox fully functional

Phase 5.3 - Daytona Integration (Week 3-4)

• Implement Daytona provider functions
• Add Daytona configuration and validation
• Test Daytona sandbox lifecycle
• Document Daytona setup and usage
• Deliverable: Daytona sandbox fully functional

Phase 5.4 - Polish and Documentation (Week 4)

• Comprehensive testing across all providers
• Performance optimization
• Complete documentation
• Example configurations and tutorials
• Deliverable: Production-ready Phase 5.0

Success Criteria

• ✅ Ralph executes Claude Code in E2B sandbox with --sandbox e2b flag
• ✅ Ralph executes Claude Code in Daytona sandbox with --sandbox daytona flag
• ✅ Local execution remains default and unchanged
• ✅ File synchronization works correctly for remote sandboxes
• ✅ Sandbox cleanup occurs on normal exit and interruption
• ✅ Error messages guide users through sandbox setup
• ✅ All existing tests pass without modification
• ✅ New tests cover sandbox functionality (30+ tests)
• ✅ Documentation includes sandbox setup and usage examples

Import In IDE

🤖 Prompt for AI Agents

## Observations

Ralph is a mature bash-based autonomous development loop tool with 276 passing tests and modular architecture. The current execution model runs Claude Code CLI directly on the local machine via `execute_claude_code()` in `file:ralph_loop.sh`. The codebase follows a library pattern with modules in `file:lib/` (circuit_breaker.sh, response_analyzer.sh, date_utils.sh). CLI argument parsing occurs at lines 1138-1229, command building at lines 679-732, and execution at lines 735-925. E2B provides Firecracker microVM sandboxes with <200ms startup, while Daytona offers sub-90ms Docker-compatible sandboxes. Both platforms provide secure, isolated environments for AI code execution.

## Approach

Introduce a sandbox abstraction layer as a new library module (`file:lib/sandbox_manager.sh`) that encapsulates execution environment logic. Add CLI flags `--sandbox` and `--sandbox-config` to select between local (default), E2B, and Daytona execution modes. Modify `execute_claude_code()` to route through the sandbox manager instead of direct execution. This approach maintains backward compatibility (local execution remains default), follows the existing modular pattern, and enables future sandbox provider additions without core logic changes. The implementation prioritizes incremental rollout: local wrapper first, then E2B, then Daytona.

## Implementation Steps

### 1. Create Sandbox Abstraction Layer

Create `file:lib/sandbox_manager.sh` as a new library module with the following functions:

**Core Functions:**
- `init_sandbox()` - Initialize sandbox based on selected provider (local/e2b/daytona)
- `execute_in_sandbox()` - Execute Claude Code command in the selected sandbox environment
- `cleanup_sandbox()` - Cleanup sandbox resources after execution
- `get_sandbox_status()` - Query sandbox health and availability
- `validate_sandbox_config()` - Validate sandbox-specific configuration

**Provider-Specific Functions:**
- `init_local_sandbox()` - No-op wrapper for local execution (default behavior)
- `init_e2b_sandbox()` - Initialize E2B sandbox using E2B SDK/CLI
- `init_daytona_sandbox()` - Initialize Daytona sandbox using Daytona API
- `execute_local()` - Direct execution (current behavior)
- `execute_e2b()` - Execute via E2B sandbox API
- `execute_daytona()` - Execute via Daytona sandbox API

**Configuration Management:**
- Support environment variables: `E2B_API_KEY`, `DAYTONA_API_KEY`, `SANDBOX_TIMEOUT`
- Support config file entries in `.ralphrc`: `SANDBOX_PROVIDER`, `SANDBOX_CONFIG_FILE`
- Validate required credentials before sandbox initialization

### 2. Add CLI Flags to ralph_loop.sh

Modify the CLI argument parsing section (lines 1138-1229) to add:

**New Flags:**
- `--sandbox PROVIDER` - Select sandbox provider: `local` (default), `e2b`, `daytona`
- `--sandbox-config FILE` - Path to sandbox-specific configuration file (JSON/YAML)
- `--sandbox-timeout MIN` - Sandbox-specific timeout (default: inherits from `--timeout`)

**Configuration Variables (add to configuration section, lines 1-90):**
- `SANDBOX_PROVIDER="local"` - Default to local execution
- `SANDBOX_CONFIG_FILE=""` - Optional sandbox config file path
- `SANDBOX_TIMEOUT=""` - Optional sandbox-specific timeout
- `SANDBOX_SESSION_ID=""` - Track sandbox session for cleanup

**Help Text Updates:**
Add new section in `show_help()` function:
```
Sandbox Options (Phase 5.0):
    --sandbox PROVIDER      Select execution environment: local, e2b, daytona (default: local)
    --sandbox-config FILE   Path to sandbox configuration file
    --sandbox-timeout MIN   Sandbox-specific timeout in minutes
```

### 3. Modify execute_claude_code() Function

Update `execute_claude_code()` function (lines 735-925) to route through sandbox manager:

**Changes:**
- After building Claude command (line 768), call `init_sandbox()` to prepare environment
- Replace direct execution (lines 779-802) with `execute_in_sandbox()` call
- Pass sandbox context (provider, config, session ID) to execution function
- Handle sandbox-specific errors (connection failures, timeout, resource limits)
- Add sandbox status logging for monitoring
- Call `cleanup_sandbox()` in cleanup path and on exit

**Execution Flow:**
```
build_claude_command() 
  → init_sandbox($SANDBOX_PROVIDER, $SANDBOX_CONFIG_FILE)
  → execute_in_sandbox($CLAUDE_CMD_ARGS, $output_file, $timeout)
  → cleanup_sandbox($SANDBOX_SESSION_ID)
```

### 4. Implement Local Sandbox Provider (Phase 5.1)

Start with local provider as a wrapper around existing behavior:

**Implementation in lib/sandbox_manager.sh:**
- `init_local_sandbox()` - Validate local environment, return success
- `execute_local()` - Call existing execution logic (lines 779-802)
- `cleanup_local()` - No-op for local execution

**Purpose:** Establish abstraction layer without changing behavior, enable testing of sandbox routing logic before adding remote providers.

### 5. Implement E2B Sandbox Provider (Phase 5.2)

Add E2B integration after local provider is stable:

**Prerequisites:**
- E2B CLI or SDK installation check in `install.sh`
- E2B API key validation in `validate_sandbox_config()`
- Document E2B setup in README.md

**Implementation:**
- `init_e2b_sandbox()` - Create E2B sandbox instance via API/CLI, return sandbox ID
- `execute_e2b()` - Upload project files, execute Claude Code in E2B environment, download results
- `cleanup_e2b()` - Terminate E2B sandbox instance, cleanup resources

**File Synchronization:**
- Upload `PROMPT.md`, `@fix_plan.md`, `specs/` directory to E2B sandbox
- Execute Claude Code within E2B environment
- Download modified files back to local project directory
- Handle git operations within sandbox context

**Error Handling:**
- E2B API connection failures
- Sandbox creation timeout
- File upload/download errors
- E2B rate limits and quota exhaustion

### 6. Implement Daytona Sandbox Provider (Phase 5.3)

Add Daytona integration following E2B pattern:

**Prerequisites:**
- Daytona CLI installation check
- Daytona API key validation
- Document Daytona setup in README.md

**Implementation:**
- `init_daytona_sandbox()` - Create Daytona workspace via API
- `execute_daytona()` - Execute Claude Code in Daytona environment
- `cleanup_daytona()` - Destroy Daytona workspace

**Daytona-Specific Features:**
- Leverage Docker compatibility for faster setup
- Use Daytona's LSP and Git APIs for better integration
- Support stateful sandboxes for session continuity

### 7. Update Configuration and Environment Setup

**Environment Variables:**
Add to documentation and validation:
- `E2B_API_KEY` - E2B authentication token
- `DAYTONA_API_KEY` - Daytona authentication token
- `SANDBOX_PROVIDER` - Default sandbox provider
- `SANDBOX_REGION` - Geographic region for sandbox (e2b/daytona)

**Config File Support (.ralphrc):**
```bash
# Sandbox configuration
SANDBOX_PROVIDER=e2b
SANDBOX_CONFIG_FILE=~/.ralph/sandbox-e2b.json
SANDBOX_TIMEOUT=20
```

**Sandbox Config Files:**
Create example configs:
- `~/.ralph/sandbox-e2b.json` - E2B-specific settings (template, region, resources)
- `~/.ralph/sandbox-daytona.json` - Daytona-specific settings (workspace template, resources)

### 8. Update install.sh

Modify `file:install.sh` to:
- Copy `lib/sandbox_manager.sh` to `~/.ralph/lib/`
- Create example sandbox config files in `~/.ralph/`
- Check for optional dependencies (E2B CLI, Daytona CLI)
- Display sandbox setup instructions if dependencies missing

### 9. Add Monitoring and Status Updates

**Extend ralph_monitor.sh:**
- Display current sandbox provider in status dashboard
- Show sandbox session ID and status
- Display sandbox-specific metrics (startup time, resource usage)

**Update status.json:**
Add sandbox fields:
```json
{
  "sandbox": {
    "provider": "e2b",
    "session_id": "e2b-sandbox-12345",
    "status": "active",
    "startup_time_ms": 180
  }
}
```

### 10. Testing Strategy

**Unit Tests (file:tests/unit/test_sandbox_manager.bats):**
- Test sandbox provider selection logic
- Test configuration validation
- Test error handling for missing credentials
- Test sandbox routing logic (local/e2b/daytona)
- Mock sandbox API calls

**Integration Tests (file:tests/integration/test_sandbox_execution.bats):**
- Test local sandbox execution (wrapper around existing behavior)
- Test E2B sandbox lifecycle (create → execute → cleanup)
- Test Daytona sandbox lifecycle
- Test file synchronization for remote sandboxes
- Test sandbox timeout handling
- Test sandbox failure recovery

**E2E Tests (file:tests/e2e/test_sandbox_workflows.bats):**
- Test complete Ralph loop with E2B sandbox
- Test complete Ralph loop with Daytona sandbox
- Test sandbox switching between loops
- Test session continuity across sandbox instances

### 11. Documentation Updates

**README.md:**
Add new section "Sandbox Execution Environments":
- Overview of sandbox options
- Setup instructions for E2B (API key, CLI installation)
- Setup instructions for Daytona (API key, CLI installation)
- Usage examples with `--sandbox` flag
- Comparison table: local vs E2B vs Daytona
- Troubleshooting sandbox issues

**New Documentation Files:**
- `docs/SANDBOX_SETUP.md` - Detailed sandbox configuration guide
- `docs/E2B_INTEGRATION.md` - E2B-specific setup and usage
- `docs/DAYTONA_INTEGRATION.md` - Daytona-specific setup and usage

**Update Existing Docs:**
- Add sandbox flags to command reference in README.md
- Update `show_help()` output with sandbox options
- Add sandbox examples to usage section

### 12. Backward Compatibility and Migration

**Ensure Backward Compatibility:**
- Default `SANDBOX_PROVIDER=local` maintains existing behavior
- No breaking changes to existing CLI flags
- Existing projects work without modification
- Sandbox features are opt-in

**Migration Path:**
- Users can test sandbox execution with `--sandbox e2b` flag
- No changes required to existing Ralph projects
- Sandbox config files are optional
- Clear error messages guide users through sandbox setup

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant ralph_loop.sh
    participant sandbox_manager.sh
    participant Local
    participant E2B
    participant Daytona
    participant Claude Code

    User->>ralph_loop.sh: ralph --sandbox e2b --monitor
    ralph_loop.sh->>ralph_loop.sh: Parse CLI flags
    ralph_loop.sh->>sandbox_manager.sh: init_sandbox("e2b", config)
    sandbox_manager.sh->>E2B: Create sandbox instance
    E2B-->>sandbox_manager.sh: sandbox_id
    
    loop Each Loop Iteration
        ralph_loop.sh->>sandbox_manager.sh: execute_in_sandbox(cmd, output)
        sandbox_manager.sh->>E2B: Upload project files
        sandbox_manager.sh->>E2B: Execute Claude Code
        E2B->>Claude Code: Run in isolated environment
        Claude Code-->>E2B: Execution results
        sandbox_manager.sh->>E2B: Download modified files
        E2B-->>sandbox_manager.sh: Files + output
        sandbox_manager.sh-->>ralph_loop.sh: Execution complete
    end
    
    ralph_loop.sh->>sandbox_manager.sh: cleanup_sandbox(sandbox_id)
    sandbox_manager.sh->>E2B: Terminate sandbox
    E2B-->>sandbox_manager.sh: Cleanup complete
```

## Rollout Strategy

**Phase 5.1 - Local Sandbox Wrapper (Week 1)**
- Implement `lib/sandbox_manager.sh` with local provider only
- Add CLI flags and routing logic
- Test abstraction layer without changing behavior
- Deliverable: Sandbox infrastructure ready, no functional changes

**Phase 5.2 - E2B Integration (Week 2-3)**
- Implement E2B provider functions
- Add E2B configuration and validation
- Test E2B sandbox lifecycle
- Document E2B setup and usage
- Deliverable: E2B sandbox fully functional

**Phase 5.3 - Daytona Integration (Week 3-4)**
- Implement Daytona provider functions
- Add Daytona configuration and validation
- Test Daytona sandbox lifecycle
- Document Daytona setup and usage
- Deliverable: Daytona sandbox fully functional

**Phase 5.4 - Polish and Documentation (Week 4)**
- Comprehensive testing across all providers
- Performance optimization
- Complete documentation
- Example configurations and tutorials
- Deliverable: Production-ready Phase 5.0

## Success Criteria

- ✅ Ralph executes Claude Code in E2B sandbox with `--sandbox e2b` flag
- ✅ Ralph executes Claude Code in Daytona sandbox with `--sandbox daytona` flag
- ✅ Local execution remains default and unchanged
- ✅ File synchronization works correctly for remote sandboxes
- ✅ Sandbox cleanup occurs on normal exit and interruption
- ✅ Error messages guide users through sandbox setup
- ✅ All existing tests pass without modification
- ✅ New tests cover sandbox functionality (30+ tests)
- ✅ Documentation includes sandbox setup and usage examples

---

Execution Information

Branch: main
Commit: d0208c4

New Plan

Observations

Ralph is a mature bash-based autonomous development loop tool with 276 passing tests and modular architecture. The current execution model runs Claude Code CLI directly on the local machine via execute_claude_code() in file:ralph_loop.sh. The codebase follows a library pattern with modules in file:lib/ (circuit_breaker.sh, response_analyzer.sh, date_utils.sh). CLI argument parsing occurs at lines 1138-1229, command building at lines 679-732, and execution at lines 735-925. E2B provides Firecracker microVM sandboxes with <200ms startup, while Daytona offers sub-90ms Docker-compatible sandboxes. Both platforms provide secure, isolated environments for AI code execution.

Approach

Introduce a sandbox abstraction layer as a new library module (file:lib/sandbox_manager.sh) that encapsulates execution environment logic. Add CLI flags --sandbox and --sandbox-config to select between local (default), E2B, and Daytona execution modes. Modify execute_claude_code() to route through the sandbox manager instead of direct execution. This approach maintains backward compatibility (local execution remains default), follows the existing modular pattern, and enables future sandbox provider additions without core logic changes. The implementation prioritizes incremental rollout: local wrapper first, then E2B, then Daytona.

Implementation Steps

1. Create Sandbox Abstraction Layer

Create file:lib/sandbox_manager.sh as a new library module with the following functions:

Core Functions:

• init_sandbox() - Initialize sandbox based on selected provider (local/e2b/daytona)
• execute_in_sandbox() - Execute Claude Code command in the selected sandbox environment
• cleanup_sandbox() - Cleanup sandbox resources after execution
• get_sandbox_status() - Query sandbox health and availability
• validate_sandbox_config() - Validate sandbox-specific configuration

Provider-Specific Functions:

• init_local_sandbox() - No-op wrapper for local execution (default behavior)
• init_e2b_sandbox() - Initialize E2B sandbox using E2B SDK/CLI
• init_daytona_sandbox() - Initialize Daytona sandbox using Daytona API
• execute_local() - Direct execution (current behavior)
• execute_e2b() - Execute via E2B sandbox API
• execute_daytona() - Execute via Daytona sandbox API

Configuration Management:

• Support environment variables: E2B_API_KEY, DAYTONA_API_KEY, SANDBOX_TIMEOUT
• Support config file entries in .ralphrc: SANDBOX_PROVIDER, SANDBOX_CONFIG_FILE
• Validate required credentials before sandbox initialization

2. Add CLI Flags to ralph_loop.sh

Modify the CLI argument parsing section (lines 1138-1229) to add:

New Flags:

• --sandbox PROVIDER - Select sandbox provider: local (default), e2b, daytona
• --sandbox-config FILE - Path to sandbox-specific configuration file (JSON/YAML)
• --sandbox-timeout MIN - Sandbox-specific timeout (default: inherits from --timeout)

Configuration Variables (add to configuration section, lines 1-90):

• SANDBOX_PROVIDER="local" - Default to local execution
• SANDBOX_CONFIG_FILE="" - Optional sandbox config file path
• SANDBOX_TIMEOUT="" - Optional sandbox-specific timeout
• SANDBOX_SESSION_ID="" - Track sandbox session for cleanup

Help Text Updates:
Add new section in show_help() function:

Sandbox Options (Phase 5.0):
    --sandbox PROVIDER      Select execution environment: local, e2b, daytona (default: local)
    --sandbox-config FILE   Path to sandbox configuration file
    --sandbox-timeout MIN   Sandbox-specific timeout in minutes

3. Modify execute_claude_code() Function

Update execute_claude_code() function (lines 735-925) to route through sandbox manager:

Changes:

• After building Claude command (line 768), call init_sandbox() to prepare environment
• Replace direct execution (lines 779-802) with execute_in_sandbox() call
• Pass sandbox context (provider, config, session ID) to execution function
• Handle sandbox-specific errors (connection failures, timeout, resource limits)
• Add sandbox status logging for monitoring
• Call cleanup_sandbox() in cleanup path and on exit

Execution Flow:

build_claude_command() 
  → init_sandbox($SANDBOX_PROVIDER, $SANDBOX_CONFIG_FILE)
  → execute_in_sandbox($CLAUDE_CMD_ARGS, $output_file, $timeout)
  → cleanup_sandbox($SANDBOX_SESSION_ID)

4. Implement Local Sandbox Provider (Phase 5.1)

Start with local provider as a wrapper around existing behavior:

Implementation in lib/sandbox_manager.sh:

• init_local_sandbox() - Validate local environment, return success
• execute_local() - Call existing execution logic (lines 779-802)
• cleanup_local() - No-op for local execution

Purpose: Establish abstraction layer without changing behavior, enable testing of sandbox routing logic before adding remote providers.

5. Implement E2B Sandbox Provider (Phase 5.2)

Add E2B integration after local provider is stable:

Prerequisites:

• E2B CLI or SDK installation check in install.sh
• E2B API key validation in validate_sandbox_config()
• Document E2B setup in README.md

Implementation:

• init_e2b_sandbox() - Create E2B sandbox instance via API/CLI, return sandbox ID
• execute_e2b() - Upload project files, execute Claude Code in E2B environment, download results
• cleanup_e2b() - Terminate E2B sandbox instance, cleanup resources

File Synchronization:

• Upload PROMPT.md, @fix_plan.md, specs/ directory to E2B sandbox
• Execute Claude Code within E2B environment
• Download modified files back to local project directory
• Handle git operations within sandbox context

Error Handling:

• E2B API connection failures
• Sandbox creation timeout
• File upload/download errors
• E2B rate limits and quota exhaustion

6. Implement Daytona Sandbox Provider (Phase 5.3)

Add Daytona integration following E2B pattern:

Prerequisites:

• Daytona CLI installation check
• Daytona API key validation
• Document Daytona setup in README.md

Implementation:

• init_daytona_sandbox() - Create Daytona workspace via API
• execute_daytona() - Execute Claude Code in Daytona environment
• cleanup_daytona() - Destroy Daytona workspace

Daytona-Specific Features:

• Leverage Docker compatibility for faster setup
• Use Daytona's LSP and Git APIs for better integration
• Support stateful sandboxes for session continuity

7. Update Configuration and Environment Setup

Environment Variables:
Add to documentation and validation:

• E2B_API_KEY - E2B authentication token
• DAYTONA_API_KEY - Daytona authentication token
• SANDBOX_PROVIDER - Default sandbox provider
• SANDBOX_REGION - Geographic region for sandbox (e2b/daytona)

Config File Support (.ralphrc):

# Sandbox configuration
SANDBOX_PROVIDER=e2b
SANDBOX_CONFIG_FILE=~/.ralph/sandbox-e2b.json
SANDBOX_TIMEOUT=20

Sandbox Config Files:
Create example configs:

• ~/.ralph/sandbox-e2b.json - E2B-specific settings (template, region, resources)
• ~/.ralph/sandbox-daytona.json - Daytona-specific settings (workspace template, resources)

8. Update install.sh

Modify file:install.sh to:

• Copy lib/sandbox_manager.sh to ~/.ralph/lib/
• Create example sandbox config files in ~/.ralph/
• Check for optional dependencies (E2B CLI, Daytona CLI)
• Display sandbox setup instructions if dependencies missing

9. Add Monitoring and Status Updates

Extend ralph_monitor.sh:

• Display current sandbox provider in status dashboard
• Show sandbox session ID and status
• Display sandbox-specific metrics (startup time, resource usage)

Update status.json:
Add sandbox fields:

{
  "sandbox": {
    "provider": "e2b",
    "session_id": "e2b-sandbox-12345",
    "status": "active",
    "startup_time_ms": 180
  }
}

10. Testing Strategy

Unit Tests (file:tests/unit/test_sandbox_manager.bats):

• Test sandbox provider selection logic
• Test configuration validation
• Test error handling for missing credentials
• Test sandbox routing logic (local/e2b/daytona)
• Mock sandbox API calls

Integration Tests (file:tests/integration/test_sandbox_execution.bats):

• Test local sandbox execution (wrapper around existing behavior)
• Test E2B sandbox lifecycle (create → execute → cleanup)
• Test Daytona sandbox lifecycle
• Test file synchronization for remote sandboxes
• Test sandbox timeout handling
• Test sandbox failure recovery

E2E Tests (file:tests/e2e/test_sandbox_workflows.bats):

• Test complete Ralph loop with E2B sandbox
• Test complete Ralph loop with Daytona sandbox
• Test sandbox switching between loops
• Test session continuity across sandbox instances

11. Documentation Updates

README.md:
Add new section "Sandbox Execution Environments":

• Overview of sandbox options
• Setup instructions for E2B (API key, CLI installation)
• Setup instructions for Daytona (API key, CLI installation)
• Usage examples with --sandbox flag
• Comparison table: local vs E2B vs Daytona
• Troubleshooting sandbox issues

New Documentation Files:

• docs/SANDBOX_SETUP.md - Detailed sandbox configuration guide
• docs/E2B_INTEGRATION.md - E2B-specific setup and usage
• docs/DAYTONA_INTEGRATION.md - Daytona-specific setup and usage

Update Existing Docs:

• Add sandbox flags to command reference in README.md
• Update show_help() output with sandbox options
• Add sandbox examples to usage section

12. Backward Compatibility and Migration

Ensure Backward Compatibility:

• Default SANDBOX_PROVIDER=local maintains existing behavior
• No breaking changes to existing CLI flags
• Existing projects work without modification
• Sandbox features are opt-in

Migration Path:

• Users can test sandbox execution with --sandbox e2b flag
• No changes required to existing Ralph projects
• Sandbox config files are optional
• Clear error messages guide users through sandbox setup

Architecture Diagram

sequenceDiagram
    participant User
    participant ralph_loop.sh
    participant sandbox_manager.sh
    participant Local
    participant E2B
    participant Daytona
    participant Claude Code

    User->>ralph_loop.sh: ralph --sandbox e2b --monitor
    ralph_loop.sh->>ralph_loop.sh: Parse CLI flags
    ralph_loop.sh->>sandbox_manager.sh: init_sandbox("e2b", config)
    sandbox_manager.sh->>E2B: Create sandbox instance
    E2B-->>sandbox_manager.sh: sandbox_id
    
    loop Each Loop Iteration
        ralph_loop.sh->>sandbox_manager.sh: execute_in_sandbox(cmd, output)
        sandbox_manager.sh->>E2B: Upload project files
        sandbox_manager.sh->>E2B: Execute Claude Code
        E2B->>Claude Code: Run in isolated environment
        Claude Code-->>E2B: Execution results
        sandbox_manager.sh->>E2B: Download modified files
        E2B-->>sandbox_manager.sh: Files + output
        sandbox_manager.sh-->>ralph_loop.sh: Execution complete
    end
    
    ralph_loop.sh->>sandbox_manager.sh: cleanup_sandbox(sandbox_id)
    sandbox_manager.sh->>E2B: Terminate sandbox
    E2B-->>sandbox_manager.sh: Cleanup complete

Loading

Rollout Strategy

Phase 6.1 - Local Sandbox Wrapper (Week 1)

• Implement lib/sandbox_manager.sh with local provider only
• Add CLI flags and routing logic
• Test abstraction layer without changing behavior
• Deliverable: Sandbox infrastructure ready, no functional changes

Phase 6.2 - E2B Integration (Week 2-3)

• Implement E2B provider functions
• Add E2B configuration and validation
• Test E2B sandbox lifecycle
• Document E2B setup and usage
• Deliverable: E2B sandbox fully functional

Phase 6.3 - Daytona Integration (Week 3-4)

• Implement Daytona provider functions
• Add Daytona configuration and validation
• Test Daytona sandbox lifecycle
• Document Daytona setup and usage
• Deliverable: Daytona sandbox fully functional

Phase 6.4 - Polish and Documentation (Week 4)

• Comprehensive testing across all providers
• Performance optimization
• Complete documentation
• Example configurations and tutorials
• Deliverable: Production-ready Phase 6.0

Success Criteria

• ✅ Ralph executes Claude Code in E2B sandbox with --sandbox e2b flag
• ✅ Ralph executes Claude Code in Daytona sandbox with --sandbox daytona flag
• ✅ Local execution remains default and unchanged
• ✅ File synchronization works correctly for remote sandboxes
• ✅ Sandbox cleanup occurs on normal exit and interruption
• ✅ Error messages guide users through sandbox setup
• ✅ All existing tests pass without modification
• ✅ New tests cover sandbox functionality (30+ tests)
• ✅ Documentation includes sandbox setup and usage examples

Import In IDE

🤖 Prompt for AI Agents

## Observations

Ralph is a mature bash-based autonomous development loop tool with 276 passing tests and modular architecture. The current execution model runs Claude Code CLI directly on the local machine via `execute_claude_code()` in `file:ralph_loop.sh`. The codebase follows a library pattern with modules in `file:lib/` (circuit_breaker.sh, response_analyzer.sh, date_utils.sh). CLI argument parsing occurs at lines 1138-1229, command building at lines 679-732, and execution at lines 735-925. E2B provides Firecracker microVM sandboxes with <200ms startup, while Daytona offers sub-90ms Docker-compatible sandboxes. Both platforms provide secure, isolated environments for AI code execution.

## Approach

Introduce a sandbox abstraction layer as a new library module (`file:lib/sandbox_manager.sh`) that encapsulates execution environment logic. Add CLI flags `--sandbox` and `--sandbox-config` to select between local (default), E2B, and Daytona execution modes. Modify `execute_claude_code()` to route through the sandbox manager instead of direct execution. This approach maintains backward compatibility (local execution remains default), follows the existing modular pattern, and enables future sandbox provider additions without core logic changes. The implementation prioritizes incremental rollout: local wrapper first, then E2B, then Daytona.

## Implementation Steps

### 1. Create Sandbox Abstraction Layer

Create `file:lib/sandbox_manager.sh` as a new library module with the following functions:

**Core Functions:**
- `init_sandbox()` - Initialize sandbox based on selected provider (local/e2b/daytona)
- `execute_in_sandbox()` - Execute Claude Code command in the selected sandbox environment
- `cleanup_sandbox()` - Cleanup sandbox resources after execution
- `get_sandbox_status()` - Query sandbox health and availability
- `validate_sandbox_config()` - Validate sandbox-specific configuration

**Provider-Specific Functions:**
- `init_local_sandbox()` - No-op wrapper for local execution (default behavior)
- `init_e2b_sandbox()` - Initialize E2B sandbox using E2B SDK/CLI
- `init_daytona_sandbox()` - Initialize Daytona sandbox using Daytona API
- `execute_local()` - Direct execution (current behavior)
- `execute_e2b()` - Execute via E2B sandbox API
- `execute_daytona()` - Execute via Daytona sandbox API

**Configuration Management:**
- Support environment variables: `E2B_API_KEY`, `DAYTONA_API_KEY`, `SANDBOX_TIMEOUT`
- Support config file entries in `.ralphrc`: `SANDBOX_PROVIDER`, `SANDBOX_CONFIG_FILE`
- Validate required credentials before sandbox initialization

### 2. Add CLI Flags to ralph_loop.sh

Modify the CLI argument parsing section (lines 1138-1229) to add:

**New Flags:**
- `--sandbox PROVIDER` - Select sandbox provider: `local` (default), `e2b`, `daytona`
- `--sandbox-config FILE` - Path to sandbox-specific configuration file (JSON/YAML)
- `--sandbox-timeout MIN` - Sandbox-specific timeout (default: inherits from `--timeout`)

**Configuration Variables (add to configuration section, lines 1-90):**
- `SANDBOX_PROVIDER="local"` - Default to local execution
- `SANDBOX_CONFIG_FILE=""` - Optional sandbox config file path
- `SANDBOX_TIMEOUT=""` - Optional sandbox-specific timeout
- `SANDBOX_SESSION_ID=""` - Track sandbox session for cleanup

**Help Text Updates:**
Add new section in `show_help()` function:
```
Sandbox Options (Phase 5.0):
    --sandbox PROVIDER      Select execution environment: local, e2b, daytona (default: local)
    --sandbox-config FILE   Path to sandbox configuration file
    --sandbox-timeout MIN   Sandbox-specific timeout in minutes
```

### 3. Modify execute_claude_code() Function

Update `execute_claude_code()` function (lines 735-925) to route through sandbox manager:

**Changes:**
- After building Claude command (line 768), call `init_sandbox()` to prepare environment
- Replace direct execution (lines 779-802) with `execute_in_sandbox()` call
- Pass sandbox context (provider, config, session ID) to execution function
- Handle sandbox-specific errors (connection failures, timeout, resource limits)
- Add sandbox status logging for monitoring
- Call `cleanup_sandbox()` in cleanup path and on exit

**Execution Flow:**
```
build_claude_command() 
  → init_sandbox($SANDBOX_PROVIDER, $SANDBOX_CONFIG_FILE)
  → execute_in_sandbox($CLAUDE_CMD_ARGS, $output_file, $timeout)
  → cleanup_sandbox($SANDBOX_SESSION_ID)
```

### 4. Implement Local Sandbox Provider (Phase 5.1)

Start with local provider as a wrapper around existing behavior:

**Implementation in lib/sandbox_manager.sh:**
- `init_local_sandbox()` - Validate local environment, return success
- `execute_local()` - Call existing execution logic (lines 779-802)
- `cleanup_local()` - No-op for local execution

**Purpose:** Establish abstraction layer without changing behavior, enable testing of sandbox routing logic before adding remote providers.

### 5. Implement E2B Sandbox Provider (Phase 5.2)

Add E2B integration after local provider is stable:

**Prerequisites:**
- E2B CLI or SDK installation check in `install.sh`
- E2B API key validation in `validate_sandbox_config()`
- Document E2B setup in README.md

**Implementation:**
- `init_e2b_sandbox()` - Create E2B sandbox instance via API/CLI, return sandbox ID
- `execute_e2b()` - Upload project files, execute Claude Code in E2B environment, download results
- `cleanup_e2b()` - Terminate E2B sandbox instance, cleanup resources

**File Synchronization:**
- Upload `PROMPT.md`, `@fix_plan.md`, `specs/` directory to E2B sandbox
- Execute Claude Code within E2B environment
- Download modified files back to local project directory
- Handle git operations within sandbox context

**Error Handling:**
- E2B API connection failures
- Sandbox creation timeout
- File upload/download errors
- E2B rate limits and quota exhaustion

### 6. Implement Daytona Sandbox Provider (Phase 5.3)

Add Daytona integration following E2B pattern:

**Prerequisites:**
- Daytona CLI installation check
- Daytona API key validation
- Document Daytona setup in README.md

**Implementation:**
- `init_daytona_sandbox()` - Create Daytona workspace via API
- `execute_daytona()` - Execute Claude Code in Daytona environment
- `cleanup_daytona()` - Destroy Daytona workspace

**Daytona-Specific Features:**
- Leverage Docker compatibility for faster setup
- Use Daytona's LSP and Git APIs for better integration
- Support stateful sandboxes for session continuity

### 7. Update Configuration and Environment Setup

**Environment Variables:**
Add to documentation and validation:
- `E2B_API_KEY` - E2B authentication token
- `DAYTONA_API_KEY` - Daytona authentication token
- `SANDBOX_PROVIDER` - Default sandbox provider
- `SANDBOX_REGION` - Geographic region for sandbox (e2b/daytona)

**Config File Support (.ralphrc):**
```bash
# Sandbox configuration
SANDBOX_PROVIDER=e2b
SANDBOX_CONFIG_FILE=~/.ralph/sandbox-e2b.json
SANDBOX_TIMEOUT=20
```

**Sandbox Config Files:**
Create example configs:
- `~/.ralph/sandbox-e2b.json` - E2B-specific settings (template, region, resources)
- `~/.ralph/sandbox-daytona.json` - Daytona-specific settings (workspace template, resources)

### 8. Update install.sh

Modify `file:install.sh` to:
- Copy `lib/sandbox_manager.sh` to `~/.ralph/lib/`
- Create example sandbox config files in `~/.ralph/`
- Check for optional dependencies (E2B CLI, Daytona CLI)
- Display sandbox setup instructions if dependencies missing

### 9. Add Monitoring and Status Updates

**Extend ralph_monitor.sh:**
- Display current sandbox provider in status dashboard
- Show sandbox session ID and status
- Display sandbox-specific metrics (startup time, resource usage)

**Update status.json:**
Add sandbox fields:
```json
{
  "sandbox": {
    "provider": "e2b",
    "session_id": "e2b-sandbox-12345",
    "status": "active",
    "startup_time_ms": 180
  }
}
```

### 10. Testing Strategy

**Unit Tests (file:tests/unit/test_sandbox_manager.bats):**
- Test sandbox provider selection logic
- Test configuration validation
- Test error handling for missing credentials
- Test sandbox routing logic (local/e2b/daytona)
- Mock sandbox API calls

**Integration Tests (file:tests/integration/test_sandbox_execution.bats):**
- Test local sandbox execution (wrapper around existing behavior)
- Test E2B sandbox lifecycle (create → execute → cleanup)
- Test Daytona sandbox lifecycle
- Test file synchronization for remote sandboxes
- Test sandbox timeout handling
- Test sandbox failure recovery

**E2E Tests (file:tests/e2e/test_sandbox_workflows.bats):**
- Test complete Ralph loop with E2B sandbox
- Test complete Ralph loop with Daytona sandbox
- Test sandbox switching between loops
- Test session continuity across sandbox instances

### 11. Documentation Updates

**README.md:**
Add new section "Sandbox Execution Environments":
- Overview of sandbox options
- Setup instructions for E2B (API key, CLI installation)
- Setup instructions for Daytona (API key, CLI installation)
- Usage examples with `--sandbox` flag
- Comparison table: local vs E2B vs Daytona
- Troubleshooting sandbox issues

**New Documentation Files:**
- `docs/SANDBOX_SETUP.md` - Detailed sandbox configuration guide
- `docs/E2B_INTEGRATION.md` - E2B-specific setup and usage
- `docs/DAYTONA_INTEGRATION.md` - Daytona-specific setup and usage

**Update Existing Docs:**
- Add sandbox flags to command reference in README.md
- Update `show_help()` output with sandbox options
- Add sandbox examples to usage section

### 12. Backward Compatibility and Migration

**Ensure Backward Compatibility:**
- Default `SANDBOX_PROVIDER=local` maintains existing behavior
- No breaking changes to existing CLI flags
- Existing projects work without modification
- Sandbox features are opt-in

**Migration Path:**
- Users can test sandbox execution with `--sandbox e2b` flag
- No changes required to existing Ralph projects
- Sandbox config files are optional
- Clear error messages guide users through sandbox setup

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant ralph_loop.sh
    participant sandbox_manager.sh
    participant Local
    participant E2B
    participant Daytona
    participant Claude Code

    User->>ralph_loop.sh: ralph --sandbox e2b --monitor
    ralph_loop.sh->>ralph_loop.sh: Parse CLI flags
    ralph_loop.sh->>sandbox_manager.sh: init_sandbox("e2b", config)
    sandbox_manager.sh->>E2B: Create sandbox instance
    E2B-->>sandbox_manager.sh: sandbox_id
    
    loop Each Loop Iteration
        ralph_loop.sh->>sandbox_manager.sh: execute_in_sandbox(cmd, output)
        sandbox_manager.sh->>E2B: Upload project files
        sandbox_manager.sh->>E2B: Execute Claude Code
        E2B->>Claude Code: Run in isolated environment
        Claude Code-->>E2B: Execution results
        sandbox_manager.sh->>E2B: Download modified files
        E2B-->>sandbox_manager.sh: Files + output
        sandbox_manager.sh-->>ralph_loop.sh: Execution complete
    end
    
    ralph_loop.sh->>sandbox_manager.sh: cleanup_sandbox(sandbox_id)
    sandbox_manager.sh->>E2B: Terminate sandbox
    E2B-->>sandbox_manager.sh: Cleanup complete
```

## Rollout Strategy

**Phase 6.1 - Local Sandbox Wrapper (Week 1)**
- Implement `lib/sandbox_manager.sh` with local provider only
- Add CLI flags and routing logic
- Test abstraction layer without changing behavior
- Deliverable: Sandbox infrastructure ready, no functional changes

**Phase 6.2 - E2B Integration (Week 2-3)**
- Implement E2B provider functions
- Add E2B configuration and validation
- Test E2B sandbox lifecycle
- Document E2B setup and usage
- Deliverable: E2B sandbox fully functional

**Phase 6.3 - Daytona Integration (Week 3-4)**
- Implement Daytona provider functions
- Add Daytona configuration and validation
- Test Daytona sandbox lifecycle
- Document Daytona setup and usage
- Deliverable: Daytona sandbox fully functional

**Phase 6.4 - Polish and Documentation (Week 4)**
- Comprehensive testing across all providers
- Performance optimization
- Complete documentation
- Example configurations and tutorials
- Deliverable: Production-ready Phase 6.0

## Success Criteria

- ✅ Ralph executes Claude Code in E2B sandbox with `--sandbox e2b` flag
- ✅ Ralph executes Claude Code in Daytona sandbox with `--sandbox daytona` flag
- ✅ Local execution remains default and unchanged
- ✅ File synchronization works correctly for remote sandboxes
- ✅ Sandbox cleanup occurs on normal exit and interruption
- ✅ Error messages guide users through sandbox setup
- ✅ All existing tests pass without modification
- ✅ New tests cover sandbox functionality (30+ tests)
- ✅ Documentation includes sandbox setup and usage examples

---

Execution Information

Branch: main
Commit: d0208c4