[P4] Phase 6.5 Generic Sandbox Interface and Plugin Architecture

[frankbria]

Summary

Create an abstract sandbox interface that allows multiple sandbox backends (Docker, E2B, Daytona, etc.) to be used interchangeably. This enables a plugin architecture where new sandbox types can be added without modifying core Ralph code.

Problem Statement

Phases 6.1-6.4 implement Docker and E2B specifically. As more sandbox platforms emerge, we need:

• Consistent interface across all sandbox types
• Easy addition of new sandbox backends
• Common configuration schema
• Unified monitoring and lifecycle management
• Community contributions without core code changes

Proposed Interface

Every sandbox backend must implement these operations:

# Lifecycle
sandbox_create <config>          # Create/start sandbox, return session ID
sandbox_destroy <session_id>     # Terminate and cleanup sandbox
sandbox_status <session_id>      # Get sandbox status (running/stopped/error)

# Execution
sandbox_exec <session_id> <cmd>  # Execute command in sandbox
sandbox_exec_async <session_id> <cmd>  # Non-blocking execution

# File Operations
sandbox_upload <session_id> <local> <remote>   # Copy file to sandbox
sandbox_download <session_id> <remote> <local> # Copy file from sandbox
sandbox_list <session_id> <path>               # List files in sandbox

# Streams
sandbox_logs <session_id>        # Stream stdout/stderr
sandbox_attach <session_id>      # Interactive session (if supported)

# Configuration
sandbox_validate_config <config> # Validate configuration before create
sandbox_capabilities             # Return supported features

Plugin Structure

Each sandbox backend is a separate file in lib/sandbox/:

lib/sandbox/
├── interface.sh      # Abstract interface definition
├── docker.sh         # Docker implementation
├── e2b.sh           # E2B implementation
├── daytona.sh       # Daytona implementation (future)
├── gitpod.sh        # Gitpod implementation (future)
└── local.sh         # Passthrough (no sandbox, for testing)

Configuration Schema

Unified configuration that works across all backends:

sandbox:
  # Required
  type: docker | e2b | daytona | gitpod | local
  
  # Common options (all backends)
  common:
    workdir: /workspace
    shell: /bin/bash
    timeout: 3600
    
  # Sync options (handled by generic sync layer)
  sync:
    strategy: snapshot | realtime | git
    include: ["src/**", "tests/**"]
    exclude: ["node_modules/**"]
    
  # Security options (backend interprets as supported)
  security:
    network: restricted
    filesystem: isolated
    resources:
      memory: 4g
      cpus: 2
      
  # Backend-specific options
  docker:
    image: "python:3.11"
    volumes: ["./data:/data:ro"]
    
  e2b:
    template: "python"
    api_key_env: E2B_API_KEY
    
  daytona:
    workspace: "my-workspace"
    provider: "docker"

Capability Detection

Backends report what features they support:

# Query backend capabilities
sandbox_capabilities docker
# Returns:
# {
#   "realtime_sync": true,
#   "network_policies": true,
#   "resource_limits": true,
#   "interactive_shell": true,
#   "persistence": true,
#   "cost_tracking": false
# }

sandbox_capabilities e2b
# Returns:
# {
#   "realtime_sync": false,
#   "network_policies": false,
#   "resource_limits": true,
#   "interactive_shell": true,
#   "persistence": false,
#   "cost_tracking": true
# }

Ralph adapts behavior based on capabilities:

• Skip realtime sync if not supported
• Skip network policies if not supported
• Enable cost tracking UI if supported

Adding a New Backend

To add a new sandbox backend (e.g., Gitpod):

1. Create lib/sandbox/gitpod.sh
2. Implement all interface functions
3. Define backend-specific config options
4. Register in lib/sandbox/registry.sh
5. Add tests

Example minimal implementation:

#!/usr/bin/env bash
# lib/sandbox/gitpod.sh

source "$(dirname "$0")/interface.sh"

gitpod_create() {
    local config="$1"
    # Gitpod-specific creation logic
    # Return session ID
}

gitpod_destroy() {
    local session_id="$1"
    # Gitpod-specific cleanup
}

gitpod_exec() {
    local session_id="$1"
    local cmd="$2"
    # Execute via Gitpod API
}

# ... implement all interface functions ...

gitpod_capabilities() {
    echo '{
        "realtime_sync": true,
        "network_policies": false,
        "resource_limits": true,
        "interactive_shell": true,
        "persistence": true,
        "cost_tracking": true
    }'
}

# Register this backend
register_sandbox_backend "gitpod" \
    gitpod_create \
    gitpod_destroy \
    gitpod_exec \
    gitpod_upload \
    gitpod_download \
    gitpod_logs \
    gitpod_status \
    gitpod_capabilities

Key Design Questions

1. Interface Completeness

   • What's the minimal viable interface?
   • What optional methods should exist?
   • How to handle unsupported operations?

2. Configuration Validation

   • Validate before attempting creation?
   • Backend-specific validation rules?
   • User-friendly error messages?

3. Error Handling

   • Standard error codes across backends?
   • Retry policies?
   • Fallback to local execution on failure?

4. Monitoring Abstraction

   • Unified log streaming interface
   • Status polling vs. push notifications
   • How does ralph-monitor adapt?

5. Testing Strategy

   • Mock backend for testing core logic
   • Integration tests per backend
   • Capability-based test selection

6. Plugin Discovery

   • Auto-discover backends in lib/sandbox/?
   • User-provided plugins from ~/.ralph/plugins/?
   • Plugin versioning?

Acceptance Criteria

• Define abstract sandbox interface in interface.sh
• Migrate Docker implementation to use interface
• Migrate E2B implementation to use interface
• Implement capability detection system
• Unified configuration schema
• Backend registration mechanism
• Plugin discovery and loading
• Fallback handling for unsupported features
• Mock backend for testing
• Documentation for creating new backends
• Tests for interface compliance

Future Backends to Consider

• Daytona - Self-hosted dev environments
• Gitpod - Cloud-based workspaces
• GitHub Codespaces - GitHub-integrated environments
• Replit - Browser-based development
• Modal - Serverless compute
• Fly.io - Edge compute
• Railway - App hosting with ephemeral environments

Dependencies

• Phases 6.1 ([P4] Phase 6.1 Local Docker Sandbox Execution #74) and 6.2 ([P4] Phase 6.2 E2B Cloud Sandbox Integration #75) implemented first
• Phase 6.3 ([P4] Phase 6.3 Sandbox File Synchronization #76) sync mechanism
• Phase 6.4 ([P4] Phase 6.4 Sandbox Security and Resource Policies #77) security policies

Related

• Phase 6.0: [P4] Phase 6.0 Sandbox execution environments (E2B, Docker, and others) #49 (Umbrella issue)
• Phase 6.1: [P4] Phase 6.1 Local Docker Sandbox Execution #74 (Docker - first implementation)
• Phase 6.2: [P4] Phase 6.2 E2B Cloud Sandbox Integration #75 (E2B - second implementation)
• Phase 6.3: [P4] Phase 6.3 Sandbox File Synchronization #76 (File sync - shared layer)
• Phase 6.4: [P4] Phase 6.4 Sandbox Security and Resource Policies #77 (Security - shared policies)

[traycerai]

Plan

Observations

The Ralph codebase currently has no sandbox infrastructure - all Claude Code execution happens locally. The existing lib/ directory contains well-structured modular components (response_analyzer.sh, circuit_breaker.sh, date_utils.sh) that follow consistent patterns: self-contained bash scripts with exported functions, jq-based JSON processing, and cross-platform compatibility. The installation system copies lib/ modules to ~/.ralph/lib/ for global availability. This provides a solid foundation for implementing the sandbox plugin architecture.

Approach

The implementation will create an abstract sandbox interface following Ralph's existing module patterns. The approach uses a registry-based plugin system where each sandbox backend (Docker, E2B, local, etc.) implements a standard interface defined in file:lib/sandbox/interface.sh. A central registry (file:lib/sandbox/registry.sh) manages backend discovery and dispatching. The design prioritizes capability detection over feature enforcement, allowing backends to report what they support and Ralph to adapt accordingly. This enables incremental implementation - starting with a local passthrough backend for testing, then adding Docker and E2B implementations as Phases 6.1-6.2 are completed.

Implementation Steps

1. Create Sandbox Directory Structure

Create the sandbox module directory within the existing lib/ structure:

lib/sandbox/
├── interface.sh      # Abstract interface definition and validation
├── registry.sh       # Backend registration and dispatching
├── local.sh          # Passthrough backend (no sandboxing, for testing)
├── config.sh         # Configuration schema and validation
└── capabilities.sh   # Capability detection and feature flags

2. Define Abstract Interface (file:lib/sandbox/interface.sh)

Implement the core interface specification with these functions:

Lifecycle Operations:

• sandbox_create() - Initialize sandbox from config, return session ID
• sandbox_destroy() - Terminate and cleanup sandbox resources
• sandbox_status() - Query sandbox state (running/stopped/error)

Execution Operations:

• sandbox_exec() - Execute command synchronously, return output
• sandbox_exec_async() - Execute command asynchronously, return job ID

File Operations:

• sandbox_upload() - Copy local file/directory to sandbox
• sandbox_download() - Copy sandbox file/directory to local
• sandbox_list() - List files in sandbox path

Metadata Operations:

• sandbox_logs() - Stream stdout/stderr from sandbox
• sandbox_capabilities() - Return JSON of supported features
• sandbox_validate_config() - Validate configuration before creation

Each function should:

• Accept standardized parameters (session_id, config JSON, paths)
• Return consistent exit codes (0=success, 1=error, 2=unsupported)
• Output JSON for structured responses
• Log to stderr for debugging

Include validation helpers:

• validate_session_id() - Check session ID format and existence
• validate_backend_implementation() - Verify backend implements required functions
• get_backend_function() - Resolve backend-specific function names

3. Implement Backend Registry (file:lib/sandbox/registry.sh)

Create the plugin registration and dispatching system:

Registration Functions:

• register_sandbox_backend() - Register backend with function mappings
• list_sandbox_backends() - Return array of available backends
• get_backend_info() - Return backend metadata (name, version, capabilities)

Dispatching Functions:

• dispatch_sandbox_call() - Route function call to appropriate backend
• load_sandbox_backend() - Source backend script and validate interface
• unload_sandbox_backend() - Cleanup backend resources

Discovery Functions:

• discover_backends() - Auto-discover backends in lib/sandbox/
• discover_user_plugins() - Scan ~/.ralph/plugins/ for custom backends

Registry should maintain state in .sandbox_registry JSON file:

{
  "backends": {
    "local": {
      "script": "lib/sandbox/local.sh",
      "loaded": true,
      "capabilities": {...}
    },
    "docker": {
      "script": "lib/sandbox/docker.sh",
      "loaded": false,
      "capabilities": null
    }
  },
  "active_sessions": {
    "session-123": {
      "backend": "local",
      "created": "2026-01-10T10:00:00+00:00",
      "config": {...}
    }
  }
}

4. Define Configuration Schema (file:lib/sandbox/config.sh)

Implement unified configuration handling:

Configuration Structure:

{
  "type": "local|docker|e2b|daytona",
  "common": {
    "workdir": "/workspace",
    "shell": "/bin/bash",
    "timeout": 3600,
    "env": {"KEY": "value"}
  },
  "sync": {
    "strategy": "snapshot|realtime|git",
    "include": ["src/**", "tests/**"],
    "exclude": ["node_modules/**", ".git/**"]
  },
  "security": {
    "network": "restricted|isolated|full",
    "filesystem": "isolated|shared",
    "resources": {
      "memory": "4g",
      "cpus": 2
    }
  },
  "backend_specific": {
    "docker": {"image": "python:3.11"},
    "e2b": {"template": "python", "api_key_env": "E2B_API_KEY"}
  }
}

Configuration Functions:

• load_sandbox_config() - Load from file or environment
• validate_sandbox_config() - Validate against schema
• merge_sandbox_config() - Merge defaults with user config
• get_backend_config() - Extract backend-specific section
• normalize_config_paths() - Resolve relative paths

Support multiple config sources (priority order):

1. Command-line arguments (--sandbox-config config.json)
2. Project config (.ralph_sandbox.json)
3. User config (~/.ralph/sandbox_config.json)
4. Environment variables (RALPH_SANDBOX_TYPE, RALPH_SANDBOX_WORKDIR)
5. Defaults (local backend, /workspace, bash shell)

5. Implement Capability System (file:lib/sandbox/capabilities.sh)

Create feature detection and adaptation:

Capability Schema:

{
  "realtime_sync": true,
  "network_policies": false,
  "resource_limits": true,
  "interactive_shell": true,
  "persistence": false,
  "cost_tracking": false,
  "file_watching": true,
  "port_forwarding": false
}

Capability Functions:

• query_backend_capabilities() - Get capabilities from backend
• check_capability() - Test if backend supports specific feature
• get_required_capabilities() - Return minimum required features
• find_compatible_backend() - Find backend matching capability requirements
• adapt_behavior() - Adjust Ralph behavior based on capabilities

Adaptation Logic:

• If realtime_sync=false, use snapshot sync strategy
• If network_policies=false, skip network isolation setup
• If cost_tracking=true, enable cost monitoring in ralph-monitor
• If interactive_shell=false, disable attach operations

6. Create Local Backend (file:lib/sandbox/local.sh)

Implement passthrough backend for testing and local development:

Implementation:

• local_create() - Return dummy session ID, no actual sandboxing
• local_destroy() - Cleanup session state only
• local_exec() - Execute commands directly in current shell
• local_upload()/local_download() - Use cp for file operations
• local_list() - Use ls for directory listing
• local_logs() - Tail local log files
• local_capabilities() - Return all capabilities as true (no restrictions)

This backend enables:

• Testing sandbox interface without Docker/E2B dependencies
• Backward compatibility with current Ralph behavior
• Development and debugging of sandbox abstraction layer

7. Integrate with Ralph Loop (file:ralph_loop.sh)

Modify the main loop to use sandbox abstraction:

Integration Points:

In initialization section (after sourcing lib modules):

source "$SCRIPT_DIR/lib/sandbox/interface.sh"
source "$SCRIPT_DIR/lib/sandbox/registry.sh"
source "$SCRIPT_DIR/lib/sandbox/config.sh"
source "$SCRIPT_DIR/lib/sandbox/capabilities.sh"

# Initialize sandbox system
init_sandbox_system
load_sandbox_config
discover_backends

In execute_claude_code() function:

• Replace direct Claude CLI execution with sandbox dispatch
• Wrap command in sandbox_exec() call
• Handle sandbox-specific errors (session expired, backend unavailable)
• Stream logs via sandbox_logs() instead of direct file tailing

Add new CLI flags:

• --sandbox-type TYPE - Select backend (local, docker, e2b)
• --sandbox-config FILE - Load sandbox configuration
• --sandbox-reset - Destroy and recreate sandbox session
• --sandbox-status - Show sandbox session information

Error Handling:

• Fallback to local backend if configured backend unavailable
• Graceful degradation when capabilities missing
• Clear error messages for configuration issues

8. Update Installation (file:install.sh)

Modify installation to include sandbox modules:

In install_scripts() function:

# Copy lib scripts including sandbox modules
cp -r "$SCRIPT_DIR/lib/"* "$RALPH_HOME/lib/"
chmod +x "$RALPH_HOME/lib/sandbox/"*.sh

Ensure sandbox directory structure is created:

mkdir -p "$RALPH_HOME/lib/sandbox"

9. Create Testing Infrastructure

Implement comprehensive tests for sandbox abstraction:

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

• Interface validation functions
• Backend registration and discovery
• Configuration loading and validation
• Capability detection and querying

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

• Local backend lifecycle (create, exec, destroy)
• File operations (upload, download, list)
• Log streaming and status queries
• Error handling and fallback behavior

Mock Backend (file:tests/helpers/mock_sandbox.sh):

• Minimal backend implementation for testing
• Configurable success/failure responses
• Capability simulation

10. Documentation

Create comprehensive documentation:

Developer Guide (file:docs/sandbox_plugin_guide.md):

• How to create a new sandbox backend
• Interface requirements and best practices
• Testing and validation procedures
• Example implementation walkthrough

User Guide (file:docs/sandbox_configuration.md):

• Available sandbox backends
• Configuration options and examples
• Capability matrix (which backends support what)
• Troubleshooting common issues

API Reference (file:docs/sandbox_api.md):

• Complete function reference
• Parameter specifications
• Return value formats
• Error codes and handling

11. Prepare for Future Backends

Create placeholder files for Phase 6.1-6.2 implementations:

Docker Backend (file:lib/sandbox/docker.sh):

• Stub implementation with TODO comments
• Reference to Phase 6.1 issue ([P4] Phase 6.1 Local Docker Sandbox Execution #74)
• Basic structure following interface

E2B Backend (file:lib/sandbox/e2b.sh):

• Stub implementation with TODO comments
• Reference to Phase 6.2 issue ([P4] Phase 6.2 E2B Cloud Sandbox Integration #75)
• API key handling placeholder

Plugin Template (file:templates/sandbox_backend_template.sh):

• Boilerplate for creating new backends
• All required functions with documentation
• Example capability definition

Architecture Diagram

sequenceDiagram
    participant RL as ralph_loop.sh
    participant REG as registry.sh
    participant INT as interface.sh
    participant BE as Backend (local/docker/e2b)
    participant SB as Sandbox Environment

    RL->>REG: init_sandbox_system()
    REG->>REG: discover_backends()
    REG->>INT: load_sandbox_backend("local")
    INT->>BE: source local.sh
    BE->>INT: register functions
    INT->>REG: backend registered
    
    RL->>REG: sandbox_create(config)
    REG->>INT: dispatch_sandbox_call("create")
    INT->>BE: local_create(config)
    BE->>SB: initialize environment
    SB-->>BE: session_id
    BE-->>INT: session_id
    INT-->>REG: session_id
    REG-->>RL: session_id
    
    RL->>REG: sandbox_exec(session_id, cmd)
    REG->>INT: dispatch_sandbox_call("exec")
    INT->>BE: local_exec(session_id, cmd)
    BE->>SB: execute command
    SB-->>BE: output
    BE-->>INT: output
    INT-->>REG: output
    REG-->>RL: output
    
    RL->>REG: sandbox_destroy(session_id)
    REG->>INT: dispatch_sandbox_call("destroy")
    INT->>BE: local_destroy(session_id)
    BE->>SB: cleanup
    SB-->>BE: success
    BE-->>INT: success
    INT-->>REG: success
    REG-->>RL: success

Loading

Backend Capability Matrix

Capability	Local	Docker (6.1)	E2B (6.2)	Daytona (Future)
realtime_sync	✅	✅	❌	✅
network_policies	❌	✅	❌	✅
resource_limits	❌	✅	✅	✅
interactive_shell	✅	✅	✅	✅
persistence	✅	✅	❌	✅
cost_tracking	❌	❌	✅	✅
file_watching	✅	✅	❌	✅
port_forwarding	✅	✅	❌	✅

Configuration Example

# .ralph_sandbox.json
{
  "type": "local",
  "common": {
    "workdir": "/workspace",
    "shell": "/bin/bash",
    "timeout": 3600
  },
  "sync": {
    "strategy": "snapshot",
    "include": ["src/**", "tests/**", "PROMPT.md", "@fix_plan.md"],
    "exclude": ["node_modules/**", ".git/**", "logs/**"]
  },
  "security": {
    "network": "full",
    "filesystem": "shared"
  }
}

Testing Strategy

1. Interface Compliance: Validate all backends implement required functions
2. Mock Backend: Test registry and dispatching with controllable backend
3. Local Backend: Integration tests for passthrough behavior
4. Configuration: Test loading, validation, and merging from multiple sources
5. Capabilities: Test feature detection and adaptation logic
6. Error Handling: Test fallback behavior and error propagation
7. Cross-Platform: Test on Linux and macOS

Success Criteria

• Abstract interface defined with all required operations
• Registry system loads and dispatches to backends
• Configuration schema supports all backend types
• Capability detection system functional
• Local backend fully implemented and tested
• Ralph loop integrated with sandbox abstraction
• Installation includes sandbox modules
• Comprehensive test coverage (unit + integration)
• Documentation complete (user + developer guides)
• Backward compatible (local backend matches current behavior)
• Stub implementations for Docker and E2B backends
• Plugin template for community contributions

Dependencies and Sequencing

Prerequisites:

• None - this is the foundation for Phases 6.1-6.4

Enables:

• Phase 6.1 ([P4] Phase 6.1 Local Docker Sandbox Execution #74): Docker backend implementation
• Phase 6.2 ([P4] Phase 6.2 E2B Cloud Sandbox Integration #75): E2B backend implementation
• Phase 6.3 ([P4] Phase 6.3 Sandbox File Synchronization #76): File sync mechanism (uses sandbox file operations)
• Phase 6.4 ([P4] Phase 6.4 Sandbox Security and Resource Policies #77): Security policies (uses sandbox security config)

Implementation Order:

1. Interface and registry (foundation)
2. Configuration and capabilities (supporting systems)
3. Local backend (testing and validation)
4. Ralph loop integration (consumption)
5. Testing and documentation (quality assurance)
6. Stub implementations (future preparation)

Import In IDE

🤖 Prompt for AI Agents

## Observations

The Ralph codebase currently has no sandbox infrastructure - all Claude Code execution happens locally. The existing lib/ directory contains well-structured modular components (response_analyzer.sh, circuit_breaker.sh, date_utils.sh) that follow consistent patterns: self-contained bash scripts with exported functions, jq-based JSON processing, and cross-platform compatibility. The installation system copies lib/ modules to ~/.ralph/lib/ for global availability. This provides a solid foundation for implementing the sandbox plugin architecture.

## Approach

The implementation will create an abstract sandbox interface following Ralph's existing module patterns. The approach uses a registry-based plugin system where each sandbox backend (Docker, E2B, local, etc.) implements a standard interface defined in `file:lib/sandbox/interface.sh`. A central registry (`file:lib/sandbox/registry.sh`) manages backend discovery and dispatching. The design prioritizes capability detection over feature enforcement, allowing backends to report what they support and Ralph to adapt accordingly. This enables incremental implementation - starting with a local passthrough backend for testing, then adding Docker and E2B implementations as Phases 6.1-6.2 are completed.

## Implementation Steps

### 1. Create Sandbox Directory Structure

Create the sandbox module directory within the existing lib/ structure:

```
lib/sandbox/
├── interface.sh      # Abstract interface definition and validation
├── registry.sh       # Backend registration and dispatching
├── local.sh          # Passthrough backend (no sandboxing, for testing)
├── config.sh         # Configuration schema and validation
└── capabilities.sh   # Capability detection and feature flags
```

### 2. Define Abstract Interface (`file:lib/sandbox/interface.sh`)

Implement the core interface specification with these functions:

**Lifecycle Operations:**
- `sandbox_create()` - Initialize sandbox from config, return session ID
- `sandbox_destroy()` - Terminate and cleanup sandbox resources
- `sandbox_status()` - Query sandbox state (running/stopped/error)

**Execution Operations:**
- `sandbox_exec()` - Execute command synchronously, return output
- `sandbox_exec_async()` - Execute command asynchronously, return job ID

**File Operations:**
- `sandbox_upload()` - Copy local file/directory to sandbox
- `sandbox_download()` - Copy sandbox file/directory to local
- `sandbox_list()` - List files in sandbox path

**Metadata Operations:**
- `sandbox_logs()` - Stream stdout/stderr from sandbox
- `sandbox_capabilities()` - Return JSON of supported features
- `sandbox_validate_config()` - Validate configuration before creation

Each function should:
- Accept standardized parameters (session_id, config JSON, paths)
- Return consistent exit codes (0=success, 1=error, 2=unsupported)
- Output JSON for structured responses
- Log to stderr for debugging

Include validation helpers:
- `validate_session_id()` - Check session ID format and existence
- `validate_backend_implementation()` - Verify backend implements required functions
- `get_backend_function()` - Resolve backend-specific function names

### 3. Implement Backend Registry (`file:lib/sandbox/registry.sh`)

Create the plugin registration and dispatching system:

**Registration Functions:**
- `register_sandbox_backend()` - Register backend with function mappings
- `list_sandbox_backends()` - Return array of available backends
- `get_backend_info()` - Return backend metadata (name, version, capabilities)

**Dispatching Functions:**
- `dispatch_sandbox_call()` - Route function call to appropriate backend
- `load_sandbox_backend()` - Source backend script and validate interface
- `unload_sandbox_backend()` - Cleanup backend resources

**Discovery Functions:**
- `discover_backends()` - Auto-discover backends in lib/sandbox/
- `discover_user_plugins()` - Scan ~/.ralph/plugins/ for custom backends

Registry should maintain state in `.sandbox_registry` JSON file:
```json
{
  "backends": {
    "local": {
      "script": "lib/sandbox/local.sh",
      "loaded": true,
      "capabilities": {...}
    },
    "docker": {
      "script": "lib/sandbox/docker.sh",
      "loaded": false,
      "capabilities": null
    }
  },
  "active_sessions": {
    "session-123": {
      "backend": "local",
      "created": "2026-01-10T10:00:00+00:00",
      "config": {...}
    }
  }
}
```

### 4. Define Configuration Schema (`file:lib/sandbox/config.sh`)

Implement unified configuration handling:

**Configuration Structure:**
```json
{
  "type": "local|docker|e2b|daytona",
  "common": {
    "workdir": "/workspace",
    "shell": "/bin/bash",
    "timeout": 3600,
    "env": {"KEY": "value"}
  },
  "sync": {
    "strategy": "snapshot|realtime|git",
    "include": ["src/**", "tests/**"],
    "exclude": ["node_modules/**", ".git/**"]
  },
  "security": {
    "network": "restricted|isolated|full",
    "filesystem": "isolated|shared",
    "resources": {
      "memory": "4g",
      "cpus": 2
    }
  },
  "backend_specific": {
    "docker": {"image": "python:3.11"},
    "e2b": {"template": "python", "api_key_env": "E2B_API_KEY"}
  }
}
```

**Configuration Functions:**
- `load_sandbox_config()` - Load from file or environment
- `validate_sandbox_config()` - Validate against schema
- `merge_sandbox_config()` - Merge defaults with user config
- `get_backend_config()` - Extract backend-specific section
- `normalize_config_paths()` - Resolve relative paths

Support multiple config sources (priority order):
1. Command-line arguments (`--sandbox-config config.json`)
2. Project config (`.ralph_sandbox.json`)
3. User config (`~/.ralph/sandbox_config.json`)
4. Environment variables (`RALPH_SANDBOX_TYPE`, `RALPH_SANDBOX_WORKDIR`)
5. Defaults (local backend, /workspace, bash shell)

### 5. Implement Capability System (`file:lib/sandbox/capabilities.sh`)

Create feature detection and adaptation:

**Capability Schema:**
```json
{
  "realtime_sync": true,
  "network_policies": false,
  "resource_limits": true,
  "interactive_shell": true,
  "persistence": false,
  "cost_tracking": false,
  "file_watching": true,
  "port_forwarding": false
}
```

**Capability Functions:**
- `query_backend_capabilities()` - Get capabilities from backend
- `check_capability()` - Test if backend supports specific feature
- `get_required_capabilities()` - Return minimum required features
- `find_compatible_backend()` - Find backend matching capability requirements
- `adapt_behavior()` - Adjust Ralph behavior based on capabilities

**Adaptation Logic:**
- If `realtime_sync=false`, use snapshot sync strategy
- If `network_policies=false`, skip network isolation setup
- If `cost_tracking=true`, enable cost monitoring in ralph-monitor
- If `interactive_shell=false`, disable attach operations

### 6. Create Local Backend (`file:lib/sandbox/local.sh`)

Implement passthrough backend for testing and local development:

**Implementation:**
- `local_create()` - Return dummy session ID, no actual sandboxing
- `local_destroy()` - Cleanup session state only
- `local_exec()` - Execute commands directly in current shell
- `local_upload()/local_download()` - Use cp for file operations
- `local_list()` - Use ls for directory listing
- `local_logs()` - Tail local log files
- `local_capabilities()` - Return all capabilities as true (no restrictions)

This backend enables:
- Testing sandbox interface without Docker/E2B dependencies
- Backward compatibility with current Ralph behavior
- Development and debugging of sandbox abstraction layer

### 7. Integrate with Ralph Loop (`file:ralph_loop.sh`)

Modify the main loop to use sandbox abstraction:

**Integration Points:**

In initialization section (after sourcing lib modules):
```bash
source "$SCRIPT_DIR/lib/sandbox/interface.sh"
source "$SCRIPT_DIR/lib/sandbox/registry.sh"
source "$SCRIPT_DIR/lib/sandbox/config.sh"
source "$SCRIPT_DIR/lib/sandbox/capabilities.sh"

# Initialize sandbox system
init_sandbox_system
load_sandbox_config
discover_backends
```

In `execute_claude_code()` function:
- Replace direct Claude CLI execution with sandbox dispatch
- Wrap command in `sandbox_exec()` call
- Handle sandbox-specific errors (session expired, backend unavailable)
- Stream logs via `sandbox_logs()` instead of direct file tailing

Add new CLI flags:
- `--sandbox-type TYPE` - Select backend (local, docker, e2b)
- `--sandbox-config FILE` - Load sandbox configuration
- `--sandbox-reset` - Destroy and recreate sandbox session
- `--sandbox-status` - Show sandbox session information

**Error Handling:**
- Fallback to local backend if configured backend unavailable
- Graceful degradation when capabilities missing
- Clear error messages for configuration issues

### 8. Update Installation (`file:install.sh`)

Modify installation to include sandbox modules:

In `install_scripts()` function:
```bash
# Copy lib scripts including sandbox modules
cp -r "$SCRIPT_DIR/lib/"* "$RALPH_HOME/lib/"
chmod +x "$RALPH_HOME/lib/sandbox/"*.sh
```

Ensure sandbox directory structure is created:
```bash
mkdir -p "$RALPH_HOME/lib/sandbox"
```

### 9. Create Testing Infrastructure

Implement comprehensive tests for sandbox abstraction:

**Unit Tests** (`file:tests/unit/test_sandbox_interface.bats`):
- Interface validation functions
- Backend registration and discovery
- Configuration loading and validation
- Capability detection and querying

**Integration Tests** (`file:tests/integration/test_sandbox_local.bats`):
- Local backend lifecycle (create, exec, destroy)
- File operations (upload, download, list)
- Log streaming and status queries
- Error handling and fallback behavior

**Mock Backend** (`file:tests/helpers/mock_sandbox.sh`):
- Minimal backend implementation for testing
- Configurable success/failure responses
- Capability simulation

### 10. Documentation

Create comprehensive documentation:

**Developer Guide** (`file:docs/sandbox_plugin_guide.md`):
- How to create a new sandbox backend
- Interface requirements and best practices
- Testing and validation procedures
- Example implementation walkthrough

**User Guide** (`file:docs/sandbox_configuration.md`):
- Available sandbox backends
- Configuration options and examples
- Capability matrix (which backends support what)
- Troubleshooting common issues

**API Reference** (`file:docs/sandbox_api.md`):
- Complete function reference
- Parameter specifications
- Return value formats
- Error codes and handling

### 11. Prepare for Future Backends

Create placeholder files for Phase 6.1-6.2 implementations:

**Docker Backend** (`file:lib/sandbox/docker.sh`):
- Stub implementation with TODO comments
- Reference to Phase 6.1 issue (#74)
- Basic structure following interface

**E2B Backend** (`file:lib/sandbox/e2b.sh`):
- Stub implementation with TODO comments
- Reference to Phase 6.2 issue (#75)
- API key handling placeholder

**Plugin Template** (`file:templates/sandbox_backend_template.sh`):
- Boilerplate for creating new backends
- All required functions with documentation
- Example capability definition

## Architecture Diagram

```mermaid
sequenceDiagram
    participant RL as ralph_loop.sh
    participant REG as registry.sh
    participant INT as interface.sh
    participant BE as Backend (local/docker/e2b)
    participant SB as Sandbox Environment

    RL->>REG: init_sandbox_system()
    REG->>REG: discover_backends()
    REG->>INT: load_sandbox_backend("local")
    INT->>BE: source local.sh
    BE->>INT: register functions
    INT->>REG: backend registered
    
    RL->>REG: sandbox_create(config)
    REG->>INT: dispatch_sandbox_call("create")
    INT->>BE: local_create(config)
    BE->>SB: initialize environment
    SB-->>BE: session_id
    BE-->>INT: session_id
    INT-->>REG: session_id
    REG-->>RL: session_id
    
    RL->>REG: sandbox_exec(session_id, cmd)
    REG->>INT: dispatch_sandbox_call("exec")
    INT->>BE: local_exec(session_id, cmd)
    BE->>SB: execute command
    SB-->>BE: output
    BE-->>INT: output
    INT-->>REG: output
    REG-->>RL: output
    
    RL->>REG: sandbox_destroy(session_id)
    REG->>INT: dispatch_sandbox_call("destroy")
    INT->>BE: local_destroy(session_id)
    BE->>SB: cleanup
    SB-->>BE: success
    BE-->>INT: success
    INT-->>REG: success
    REG-->>RL: success
```

## Backend Capability Matrix

| Capability | Local | Docker (6.1) | E2B (6.2) | Daytona (Future) |
|------------|-------|--------------|-----------|------------------|
| realtime_sync | ✅ | ✅ | ❌ | ✅ |
| network_policies | ❌ | ✅ | ❌ | ✅ |
| resource_limits | ❌ | ✅ | ✅ | ✅ |
| interactive_shell | ✅ | ✅ | ✅ | ✅ |
| persistence | ✅ | ✅ | ❌ | ✅ |
| cost_tracking | ❌ | ❌ | ✅ | ✅ |
| file_watching | ✅ | ✅ | ❌ | ✅ |
| port_forwarding | ✅ | ✅ | ❌ | ✅ |

## Configuration Example

```yaml
# .ralph_sandbox.json
{
  "type": "local",
  "common": {
    "workdir": "/workspace",
    "shell": "/bin/bash",
    "timeout": 3600
  },
  "sync": {
    "strategy": "snapshot",
    "include": ["src/**", "tests/**", "PROMPT.md", "@fix_plan.md"],
    "exclude": ["node_modules/**", ".git/**", "logs/**"]
  },
  "security": {
    "network": "full",
    "filesystem": "shared"
  }
}
```

## Testing Strategy

1. **Interface Compliance**: Validate all backends implement required functions
2. **Mock Backend**: Test registry and dispatching with controllable backend
3. **Local Backend**: Integration tests for passthrough behavior
4. **Configuration**: Test loading, validation, and merging from multiple sources
5. **Capabilities**: Test feature detection and adaptation logic
6. **Error Handling**: Test fallback behavior and error propagation
7. **Cross-Platform**: Test on Linux and macOS

## Success Criteria

- [ ] Abstract interface defined with all required operations
- [ ] Registry system loads and dispatches to backends
- [ ] Configuration schema supports all backend types
- [ ] Capability detection system functional
- [ ] Local backend fully implemented and tested
- [ ] Ralph loop integrated with sandbox abstraction
- [ ] Installation includes sandbox modules
- [ ] Comprehensive test coverage (unit + integration)
- [ ] Documentation complete (user + developer guides)
- [ ] Backward compatible (local backend matches current behavior)
- [ ] Stub implementations for Docker and E2B backends
- [ ] Plugin template for community contributions

## Dependencies and Sequencing

**Prerequisites:**
- None - this is the foundation for Phases 6.1-6.4

**Enables:**
- Phase 6.1 (#74): Docker backend implementation
- Phase 6.2 (#75): E2B backend implementation
- Phase 6.3 (#76): File sync mechanism (uses sandbox file operations)
- Phase 6.4 (#77): Security policies (uses sandbox security config)

**Implementation Order:**
1. Interface and registry (foundation)
2. Configuration and capabilities (supporting systems)
3. Local backend (testing and validation)
4. Ralph loop integration (consumption)
5. Testing and documentation (quality assurance)
6. Stub implementations (future preparation)

---

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.

[frankbria]

Closing as not planned. A generic provider interface only pays off with a growing provider set, and ralph is capping at Docker + E2B (#79/#80 closed as not planned). The abstraction would be refactor risk to stable, well-tested code with no payoff — the two providers already share their seams (SANDBOX_EXEC_ARGS wrapping, get_sandbox_status routing, lib/sync.sh filtering) where it matters.