[P4] Phase 6.4 Sandbox Security and Resource Policies

[frankbria]

Summary

Implement fine-grained security and resource control policies for sandbox execution. This allows users to restrict what sandboxed Ralph can do, protecting against malicious or runaway code.

Problem Statement

Autonomous code execution is inherently risky. Even in a sandbox, code could:

• Exfiltrate sensitive data over the network
• Consume excessive resources (CPU, memory, disk)
• Make unauthorized API calls
• Access credentials/secrets improperly
• Run indefinitely, wasting resources

Users need controls to limit blast radius and enforce security boundaries.

Security Policy Dimensions

1. Network Policies

Control what network access the sandbox has.

# No network access (highest security)
ralph --sandbox docker --network none

# Allow only essential services
ralph --sandbox docker --network restricted
# Allows: api.anthropic.com, npm registry, pip registry

# Custom allowlist
ralph --sandbox docker --network-allow "api.anthropic.com,github.com"

# Custom denylist
ralph --sandbox docker --network-deny "*.internal.company.com"

# Full access (lowest security)
ralph --sandbox docker --network open

Restricted mode default allowlist:

• api.anthropic.com (Claude API)
• registry.npmjs.org (npm packages)
• pypi.org, files.pythonhosted.org (pip packages)
• github.com (if git operations needed)

2. Filesystem Policies

Control filesystem access within the sandbox.

# Read-only project, writable output directory
ralph --sandbox docker --fs-policy restricted

# Specify writable paths explicitly
ralph --sandbox docker --writable "/workspace/output,/workspace/logs"

# Read-only root filesystem
ralph --sandbox docker --read-only-root

# Prevent deletion of certain files
ralph --sandbox docker --protect "PROMPT.md,@fix_plan.md"

3. Resource Limits

Prevent resource exhaustion.

# Memory limit
ralph --sandbox docker --memory 4g
ralph --sandbox e2b --memory 8g

# CPU limit
ralph --sandbox docker --cpus 2

# Disk space limit
ralph --sandbox docker --disk 10g

# Execution time limit (entire session)
ralph --sandbox docker --max-duration 2h
ralph --sandbox e2b --max-duration 30m

# Per-loop time limit
ralph --sandbox docker --loop-timeout 15m

# Cost limit (for paid sandboxes)
ralph --sandbox e2b --max-cost 10.00

4. Secret Management

Secure handling of credentials.

# Inject secrets from file (not in environment)
ralph --sandbox docker --secrets-file ~/.ralph/secrets

# Inject specific secrets
ralph --sandbox docker --secret ANTHROPIC_API_KEY

# Use secret manager
ralph --sandbox docker --secrets-from aws-secrets-manager
ralph --sandbox docker --secrets-from 1password

Secret injection methods:

• Mounted file (preferred): /run/secrets/ANTHROPIC_API_KEY
• Docker secrets (for Docker sandbox)
• Secure environment (cleared after read)

Secret hygiene:

• Never log secrets
• Mask secrets in output
• Clear secrets from memory after use
• No secrets in sync'd files

5. Capability Restrictions

Fine-grained syscall/capability control (Docker-specific).

# Drop all capabilities except essential
ralph --sandbox docker --cap-drop ALL --cap-add NET_RAW

# No privilege escalation
ralph --sandbox docker --no-new-privileges

# User namespace isolation
ralph --sandbox docker --userns host

Policy Presets

Predefined security profiles for common use cases.

# Maximum security (paranoid)
ralph --sandbox docker --policy paranoid
# - No network
# - Read-only filesystem
# - 1GB memory, 1 CPU
# - 30 minute timeout

# Standard security (default)
ralph --sandbox docker --policy standard
# - Restricted network (allowlist)
# - Writable /workspace
# - 4GB memory, 2 CPUs
# - 2 hour timeout

# Permissive (development)
ralph --sandbox docker --policy permissive
# - Full network
# - Full filesystem access
# - No resource limits
# - No timeout

Configuration File

Policies can be defined in .ralphrc or ~/.ralph/config.yaml:

sandbox:
  security:
    network:
      mode: restricted  # none | restricted | open
      allow:
        - api.anthropic.com
        - "*.npmjs.org"
      deny:
        - "*.internal.corp"
        
    filesystem:
      readOnlyRoot: true
      writable:
        - /workspace/output
        - /workspace/logs
      protected:
        - PROMPT.md
        - "@fix_plan.md"
        
    resources:
      memory: 4g
      cpus: 2
      disk: 10g
      maxDuration: 2h
      loopTimeout: 15m
      
    secrets:
      source: file  # file | env | aws | 1password
      path: ~/.ralph/secrets
      inject:
        - ANTHROPIC_API_KEY
        - GITHUB_TOKEN

Key Design Questions

1. Default Policy

   • Should default be restrictive or permissive?
   • Different defaults for different sandbox types?

2. Policy Validation

   • Validate policies before starting sandbox?
   • Warn on potentially dangerous configurations?

3. Policy Enforcement

   • How to enforce network policies? (iptables, network namespaces)
   • How to enforce filesystem policies? (mounts, AppArmor, SELinux)
   • E2B may have different enforcement mechanisms

4. Secret Rotation

   • Handle secret expiration mid-session?
   • Re-inject rotated secrets?

5. Audit Logging

   • Log policy violations?
   • Log resource usage?
   • Security audit trail?

6. Policy Inheritance

   • Project-level policies override user defaults?
   • Or user defaults take precedence for security?

Acceptance Criteria

• Network policy: none, restricted, open modes
• Network allowlist/denylist configuration
• Filesystem read-only and writable path controls
• Resource limits: memory, CPU, disk, time
• Cost limits for cloud sandboxes
• Secret injection via mounted files
• Secret masking in logs
• Policy presets (paranoid, standard, permissive)
• Configuration file support for policies
• Policy validation on startup
• Tests for policy enforcement

Dependencies

• Network namespaces / iptables (Docker)
• Filesystem mounts and permissions
• Docker capabilities system
• Secret management infrastructure

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 - primary enforcement target)
• Phase 6.2: [P4] Phase 6.2 E2B Cloud Sandbox Integration #75 (E2B - different enforcement mechanisms)
• Phase 6.3: [P4] Phase 6.3 Sandbox File Synchronization #76 (File sync - secret exclusion)

[traycerai]

Plan

Observations

The Ralph codebase is a mature bash-based autonomous development loop tool (v0.9.8) with 75 passing tests and comprehensive documentation. Currently, there is no sandbox implementation - Ralph executes Claude Code directly on the host system. Phase 6.4 (Security and Resource Policies) is a lower-priority future feature (P4) that depends on Phase 6.1 (Docker sandbox), Phase 6.2 (E2B sandbox), and Phase 6.3 (File sync) being implemented first. The existing architecture uses configuration variables at the script level, CLI argument parsing with standard bash patterns, and library modules for circuit breaker and response analysis functionality.

Approach

The implementation will follow a layered security architecture where policies are defined at multiple levels (CLI flags, config files, presets) and enforced by sandbox-specific adapters. Since Ralph is bash-based, the approach will create a new lib/sandbox_policy.sh module for policy management, extend the existing CLI parser to accept sandbox-related flags, add configuration file support (.ralphrc) for persistent policies, and implement sandbox-specific enforcement adapters for Docker and E2B. The design prioritizes security by default with a "standard" policy preset, while allowing flexibility through policy customization. This approach integrates seamlessly with Ralph's existing patterns (library modules, CLI parsing, configuration variables) and maintains backward compatibility. As a P4 priority feature, implementation should be deferred until higher-priority phases (6.1, 6.2, 6.3) are complete.

Implementation Steps

1. Policy Management Infrastructure

Create file:lib/sandbox_policy.sh as the central policy management module:

Core Functions:

• init_sandbox_policy() - Initialize policy system with defaults
• load_policy_config() - Load policies from .ralphrc or ~/.ralph/config.yaml
• validate_policy() - Validate policy configuration before sandbox start
• get_policy_value() - Retrieve specific policy values
• apply_policy_preset() - Apply predefined policy presets (paranoid/standard/permissive)

Policy Data Structure:
Store policies in bash associative arrays or JSON files:

SANDBOX_POLICY_NETWORK_MODE="restricted"
SANDBOX_POLICY_NETWORK_ALLOW=("api.anthropic.com" "*.npmjs.org" "pypi.org")
SANDBOX_POLICY_NETWORK_DENY=("*.internal.corp")
SANDBOX_POLICY_MEMORY="4g"
SANDBOX_POLICY_CPUS="2"
SANDBOX_POLICY_DISK="10g"
SANDBOX_POLICY_MAX_DURATION="2h"
SANDBOX_POLICY_LOOP_TIMEOUT="15m"

2. Configuration File Support

Implement .ralphrc and ~/.ralph/config.yaml support:

File Locations (Priority Order):

1. Project-level: ./.ralphrc (highest priority)
2. User-level: ~/.ralph/config.yaml
3. Defaults: Built into lib/sandbox_policy.sh

Configuration Format:
Support both bash-style .ralphrc (for simple key=value) and YAML config.yaml (for structured policies). Use yq if available, fallback to custom bash parser for YAML. Note: Configuration file support is already partially implemented in Ralph's existing codebase (see load_config() in Week 5 of IMPLEMENTATION_PLAN.md), so this step should integrate with existing patterns.

Example .ralphrc:

# Sandbox security policies
SANDBOX_TYPE=docker
SANDBOX_POLICY_PRESET=standard
SANDBOX_NETWORK_MODE=restricted
SANDBOX_MEMORY=4g
SANDBOX_CPUS=2
SANDBOX_MAX_DURATION=2h

Example ~/.ralph/config.yaml:

sandbox:
  type: docker
  security:
    network:
      mode: restricted
      allow:
        - api.anthropic.com
        - "*.npmjs.org"
      deny:
        - "*.internal.corp"
    resources:
      memory: 4g
      cpus: 2
      disk: 10g
      maxDuration: 2h
      loopTimeout: 15m
    secrets:
      source: file
      path: ~/.ralph/secrets

Implementation:

• Add load_config() function in file:ralph_loop.sh (call before main loop)
• Parse YAML using yq if available, fallback to bash parsing for .ralphrc
• Merge configs: defaults → user config → project config → CLI flags

3. CLI Flag Extensions

Extend file:ralph_loop.sh CLI parser to accept sandbox policy flags:

New Flags:

--sandbox TYPE              # docker | e2b | none (default: none)
--sandbox-policy PRESET     # paranoid | standard | permissive
--network MODE              # none | restricted | open
--network-allow HOSTS       # Comma-separated allowlist
--network-deny HOSTS        # Comma-separated denylist
--memory SIZE               # e.g., 4g, 8g
--cpus NUM                  # e.g., 2, 4
--disk SIZE                 # e.g., 10g, 20g
--max-duration TIME         # e.g., 2h, 30m
--loop-timeout TIME         # e.g., 15m, 30m
--max-cost AMOUNT           # e.g., 10.00 (for E2B)
--secrets-file PATH         # Path to secrets file
--secret NAME               # Inject specific secret
--read-only-root            # Enable read-only root filesystem
--writable PATHS            # Comma-separated writable paths
--protect FILES             # Comma-separated protected files

Integration:
Add cases to the existing while [[ $# -gt 0 ]] loop in file:ralph_loop.sh (around line 1141). Store values in global variables like SANDBOX_TYPE, SANDBOX_POLICY_PRESET, etc.

4. Policy Presets

Implement three predefined security profiles in file:lib/sandbox_policy.sh:

Paranoid Preset:

• Network: none
• Filesystem: read-only root, writable /workspace/output only
• Resources: 1GB memory, 1 CPU, 5GB disk
• Duration: 30 minutes max
• Use case: Untrusted code, maximum security

Standard Preset (Default):

• Network: restricted (allowlist: Claude API, npm, pip, GitHub)
• Filesystem: writable /workspace, protected PROMPT.md and @fix_plan.md
• Resources: 4GB memory, 2 CPUs, 10GB disk
• Duration: 2 hours max
• Use case: Normal development, balanced security

Permissive Preset:

• Network: open (full access)
• Filesystem: full access
• Resources: 8GB memory, 4 CPUs, 20GB disk
• Duration: no limit
• Use case: Development/debugging, minimal restrictions

Function:

apply_policy_preset() {
    local preset=$1
    case $preset in
        paranoid) apply_paranoid_preset ;;
        standard) apply_standard_preset ;;
        permissive) apply_permissive_preset ;;
    esac
}

5. Network Policy Enforcement

Create network policy enforcement adapters:

Docker Enforcement (file:lib/sandbox_docker.sh):

• none mode: --network none flag
• restricted mode: Custom Docker network with iptables rules or DNS filtering
• open mode: --network bridge (default)
• Allowlist/denylist: Use Docker DNS configuration or iptables rules

E2B Enforcement (file:lib/sandbox_e2b.sh):

• Use E2B SDK network configuration options
• May have different enforcement mechanisms than Docker
• Consult E2B documentation for network isolation capabilities

Implementation:

apply_network_policy_docker() {
    local mode=$1
    case $mode in
        none)
            DOCKER_NETWORK_FLAGS="--network none"
            ;;
        restricted)
            # Create custom network with DNS filtering
            setup_restricted_network_docker
            DOCKER_NETWORK_FLAGS="--network ralph-restricted"
            ;;
        open)
            DOCKER_NETWORK_FLAGS="--network bridge"
            ;;
    esac
}

6. Filesystem Policy Enforcement

Implement filesystem access controls:

Docker Enforcement:

• Read-only root: --read-only flag
• Writable paths: --tmpfs or volume mounts with rw flag
• Protected files: Mount as read-only volumes
• Example: docker run --read-only -v /workspace/output:/workspace/output:rw

E2B Enforcement:

• Use E2B filesystem configuration
• May use different mechanisms (check E2B SDK)

Implementation:

apply_filesystem_policy_docker() {
    local read_only_root=$1
    local writable_paths=$2
    local protected_files=$3
    
    if [[ "$read_only_root" == "true" ]]; then
        DOCKER_FS_FLAGS="--read-only"
    fi
    
    # Add writable mounts
    for path in ${writable_paths//,/ }; do
        DOCKER_FS_FLAGS="$DOCKER_FS_FLAGS -v $path:$path:rw"
    done
    
    # Add protected files as read-only mounts
    for file in ${protected_files//,/ }; do
        DOCKER_FS_FLAGS="$DOCKER_FS_FLAGS -v $file:$file:ro"
    done
}

7. Resource Limit Enforcement

Implement resource constraints:

Docker Enforcement:

• Memory: --memory 4g flag
• CPU: --cpus 2 flag
• Disk: Docker storage driver limits or volume size limits
• Duration: Implement timeout wrapper around Docker execution

E2B Enforcement:

• Use E2B SDK resource configuration
• Cost limits: Track E2B API usage and halt when limit reached

Implementation:

apply_resource_limits_docker() {
    local memory=$1
    local cpus=$2
    local disk=$3
    
    DOCKER_RESOURCE_FLAGS="--memory $memory --cpus $cpus"
    
    # Disk limits via storage driver (requires Docker configuration)
    if [[ -n "$disk" ]]; then
        DOCKER_RESOURCE_FLAGS="$DOCKER_RESOURCE_FLAGS --storage-opt size=$disk"
    fi
}

enforce_duration_limit() {
    local max_duration=$1  # e.g., "2h"
    local timeout_seconds=$(parse_duration_to_seconds "$max_duration")
    
    # Use timeout command to enforce
    timeout "$timeout_seconds" docker run ...
}

8. Secret Management

Implement secure secret injection:

Preferred Method: Mounted Files

• Store secrets in ~/.ralph/secrets/ directory
• Mount as read-only files in sandbox: /run/secrets/ANTHROPIC_API_KEY
• Never log or sync secrets

Docker Implementation:

inject_secrets_docker() {
    local secrets_file=$1
    local secret_names=$2
    
    # Mount secrets directory
    DOCKER_SECRET_FLAGS="-v ~/.ralph/secrets:/run/secrets:ro"
    
    # Set environment variables pointing to secret files
    for secret in ${secret_names//,/ }; do
        DOCKER_SECRET_FLAGS="$DOCKER_SECRET_FLAGS -e ${secret}_FILE=/run/secrets/$secret"
    done
}

Secret Masking:
Add to file:lib/response_analyzer.sh:

mask_secrets_in_output() {
    local output=$1
    # Replace known secret patterns with [REDACTED]
    output=$(echo "$output" | sed 's/sk-ant-[a-zA-Z0-9-]*/[REDACTED]/g')
    echo "$output"
}

9. Policy Validation

Implement policy validation before sandbox start:

Validation Checks:

• Network allowlist/denylist conflicts
• Resource limits are valid (memory > 0, cpus > 0)
• Duration formats are correct (e.g., "2h", "30m")
• Secret files exist and are readable
• Writable paths don't conflict with protected files

Implementation in file:lib/sandbox_policy.sh:

validate_policy() {
    local errors=()
    
    # Validate network policy
    if [[ "$SANDBOX_POLICY_NETWORK_MODE" == "restricted" ]]; then
        if [[ -z "${SANDBOX_POLICY_NETWORK_ALLOW[@]}" ]]; then
            errors+=("Restricted network mode requires allowlist")
        fi
    fi
    
    # Validate resource limits
    if ! validate_memory_format "$SANDBOX_POLICY_MEMORY"; then
        errors+=("Invalid memory format: $SANDBOX_POLICY_MEMORY")
    fi
    
    # Validate duration
    if ! validate_duration_format "$SANDBOX_POLICY_MAX_DURATION"; then
        errors+=("Invalid duration format: $SANDBOX_POLICY_MAX_DURATION")
    fi
    
    # Report errors
    if [[ ${#errors[@]} -gt 0 ]]; then
        log_status "ERROR" "Policy validation failed:"
        for error in "${errors[@]}"; do
            log_status "ERROR" "  - $error"
        done
        return 1
    fi
    
    return 0
}

10. Sandbox Adapter Architecture

Create sandbox-specific adapters:

File Structure:

• file:lib/sandbox_policy.sh - Policy management (shared)
• file:lib/sandbox_docker.sh - Docker-specific enforcement (depends on Phase 6.1)
• file:lib/sandbox_e2b.sh - E2B-specific enforcement (depends on Phase 6.2)
• file:lib/sandbox_none.sh - No-op adapter for host execution

Adapter Interface:
Each adapter implements:

• init_sandbox_TYPE() - Initialize sandbox
• apply_network_policy_TYPE() - Enforce network policy
• apply_filesystem_policy_TYPE() - Enforce filesystem policy
• apply_resource_limits_TYPE() - Enforce resource limits
• inject_secrets_TYPE() - Inject secrets
• execute_in_sandbox_TYPE() - Execute command in sandbox
• cleanup_sandbox_TYPE() - Cleanup sandbox resources

Dynamic Loading:

# In ralph_loop.sh
source "$SCRIPT_DIR/lib/sandbox_policy.sh"

if [[ "$SANDBOX_TYPE" == "docker" ]]; then
    source "$SCRIPT_DIR/lib/sandbox_docker.sh"
elif [[ "$SANDBOX_TYPE" == "e2b" ]]; then
    source "$SCRIPT_DIR/lib/sandbox_e2b.sh"
else
    source "$SCRIPT_DIR/lib/sandbox_none.sh"
fi

Implementation Note: Docker and E2B adapters should be implemented only after their respective sandbox implementations (Phase 6.1 and 6.2) are complete.

11. Integration with Main Loop

Modify file:ralph_loop.sh to integrate sandbox policies:

Initialization (before main loop):

# Load configuration files
load_config

# Initialize sandbox policy
init_sandbox_policy

# Apply policy preset if specified
if [[ -n "$SANDBOX_POLICY_PRESET" ]]; then
    apply_policy_preset "$SANDBOX_POLICY_PRESET"
fi

# Validate policy
if ! validate_policy; then
    exit 1
fi

# Initialize sandbox
init_sandbox_"$SANDBOX_TYPE"

Execution (in main loop):
Replace direct Claude Code execution with sandbox execution:

# Old: execute_claude_code
# New: execute_in_sandbox_"$SANDBOX_TYPE" execute_claude_code

Cleanup (on exit):

cleanup() {
    # Existing cleanup...
    
    # Cleanup sandbox
    cleanup_sandbox_"$SANDBOX_TYPE"
}

12. Audit Logging

Add security audit logging to file:lib/sandbox_policy.sh:

Log Events:

• Policy initialization and validation
• Network policy violations (if detectable)
• Resource limit breaches
• Secret access attempts
• Sandbox start/stop events

Implementation:

audit_log() {
    local event=$1
    local details=$2
    local timestamp=$(date -Iseconds)
    
    echo "{\"timestamp\":\"$timestamp\",\"event\":\"$event\",\"details\":\"$details\"}" \
        >> "$LOG_DIR/security_audit.jsonl"
}

# Usage
audit_log "sandbox_start" "type=docker,policy=standard,network=restricted"
audit_log "policy_violation" "attempted_network_access=blocked.example.com"

13. Testing Strategy

Create comprehensive test suite:

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

• Policy loading from config files
• Policy validation logic
• Policy preset application
• Secret masking functions
• Duration/memory format parsing
• Estimated: 15-20 tests

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

• Docker sandbox initialization
• Network policy enforcement
• Filesystem policy enforcement
• Resource limit enforcement
• Secret injection
• Estimated: 20-25 tests (depends on Phase 6.1 completion)

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

• E2B sandbox initialization
• E2B-specific policy enforcement
• Cost limit tracking
• Estimated: 15-20 tests (depends on Phase 6.2 completion)

Edge Case Tests:

• Invalid policy configurations
• Conflicting policies
• Missing dependencies (Docker not installed)
• Secret file permissions
• Resource exhaustion scenarios
• Estimated: 10-15 tests

Test Sequencing: Unit tests for policy management can be written immediately. Integration tests for Docker and E2B enforcement should be deferred until their respective sandbox implementations are complete.

14. Documentation

Update documentation files:

file:README.md:

• Add "Sandbox Execution" section
• Document CLI flags for sandbox policies
• Provide examples of common configurations
• Security best practices

Create file:docs/SANDBOX_SECURITY.md:

• Detailed security policy documentation
• Policy preset descriptions
• Network policy configuration guide
• Secret management best practices
• Troubleshooting guide

Update file:IMPLEMENTATION_PLAN.md:

• Add Phase 6.4 completion status
• Document test coverage for sandbox features

15. Backward Compatibility

Ensure backward compatibility:

Default Behavior:

• SANDBOX_TYPE=none by default (no sandbox, current behavior)
• No breaking changes to existing CLI flags
• Config files are optional

Migration Path:

• Users can opt-in to sandbox execution with --sandbox docker
• Existing projects continue to work without modification
• Gradual migration: test with sandbox, then make it default

Architecture Diagram

sequenceDiagram
    participant User
    participant ralph_loop.sh
    participant sandbox_policy.sh
    participant sandbox_docker.sh
    participant Docker
    participant Claude

    User->>ralph_loop.sh: ralph --sandbox docker --sandbox-policy standard
    ralph_loop.sh->>ralph_loop.sh: load_config() from .ralphrc
    ralph_loop.sh->>sandbox_policy.sh: init_sandbox_policy()
    sandbox_policy.sh->>sandbox_policy.sh: apply_policy_preset("standard")
    sandbox_policy.sh->>sandbox_policy.sh: validate_policy()
    sandbox_policy.sh-->>ralph_loop.sh: Policy validated
    
    ralph_loop.sh->>sandbox_docker.sh: init_sandbox_docker()
    sandbox_docker.sh->>sandbox_docker.sh: apply_network_policy_docker("restricted")
    sandbox_docker.sh->>sandbox_docker.sh: apply_filesystem_policy_docker()
    sandbox_docker.sh->>sandbox_docker.sh: apply_resource_limits_docker()
    sandbox_docker.sh->>sandbox_docker.sh: inject_secrets_docker()
    sandbox_docker.sh->>Docker: docker run with policy flags
    Docker-->>sandbox_docker.sh: Container ready
    
    loop Main Loop
        ralph_loop.sh->>sandbox_docker.sh: execute_in_sandbox_docker(claude_command)
        sandbox_docker.sh->>Docker: docker exec
        Docker->>Claude: Execute Claude Code
        Claude-->>Docker: Response
        Docker-->>sandbox_docker.sh: Output
        sandbox_docker.sh->>sandbox_policy.sh: mask_secrets_in_output()
        sandbox_docker.sh-->>ralph_loop.sh: Sanitized output
        ralph_loop.sh->>sandbox_policy.sh: audit_log("execution_complete")
    end
    
    ralph_loop.sh->>sandbox_docker.sh: cleanup_sandbox_docker()
    sandbox_docker.sh->>Docker: docker stop & rm
    Docker-->>sandbox_docker.sh: Cleanup complete

Loading

Policy Configuration Example

# ~/.ralph/config.yaml
sandbox:
  type: docker
  
  security:
    # Network policy
    network:
      mode: restricted
      allow:
        - api.anthropic.com
        - registry.npmjs.org
        - pypi.org
        - files.pythonhosted.org
        - github.com
      deny:
        - "*.internal.company.com"
        - "*.local"
    
    # Filesystem policy
    filesystem:
      readOnlyRoot: true
      writable:
        - /workspace/output
        - /workspace/logs
        - /workspace/.ralph_session
      protected:
        - PROMPT.md
        - "@fix_plan.md"
        - specs/
    
    # Resource limits
    resources:
      memory: 4g
      cpus: 2
      disk: 10g
      maxDuration: 2h
      loopTimeout: 15m
    
    # Secret management
    secrets:
      source: file
      path: ~/.ralph/secrets
      inject:
        - ANTHROPIC_API_KEY
        - GITHUB_TOKEN
      
    # Audit logging
    audit:
      enabled: true
      logFile: logs/security_audit.jsonl

Dependencies

Required:

• Docker (for Docker sandbox) - docker --version (Phase 6.1 prerequisite)
• E2B SDK (for E2B sandbox) - npm install -g @e2b/sdk (Phase 6.2 prerequisite)
• yq (for YAML parsing) - brew install yq or apt-get install yq
• jq (already required by Ralph)

Optional:

• iptables (for advanced Docker network filtering)
• Secret managers: AWS Secrets Manager CLI, 1Password CLI

Phase Dependencies:

• Phase 6.1 (Docker sandbox) must be complete before Docker policy enforcement can be tested
• Phase 6.2 (E2B sandbox) must be complete before E2B policy enforcement can be tested
• Phase 6.3 (File sync) should be complete before secret exclusion policies are finalized

Risk Mitigation

Security Risks:

• Secret leakage: Mitigated by secret masking, read-only mounts, and audit logging
• Network exfiltration: Mitigated by network policies and allowlist/denylist
• Resource exhaustion: Mitigated by resource limits and duration timeouts

Implementation Risks:

• Docker not available: Graceful fallback to host execution with warning
• E2B API changes: Version pinning and adapter pattern for isolation
• Policy conflicts: Validation before sandbox start prevents runtime errors
• Dependency on earlier phases: As a P4 feature, this work should not block higher-priority phases (6.1, 6.2, 6.3)

Backward Compatibility:

• Default SANDBOX_TYPE=none ensures existing workflows continue unchanged
• All sandbox features are opt-in via CLI flags or config files
• Policy management infrastructure can be implemented independently of sandbox implementations

Phasing Strategy:

• Implement policy management infrastructure (steps 1-9) early for code organization
• Defer sandbox-specific enforcement (steps 10-12) until Phase 6.1 and 6.2 are complete
• Write unit tests for policy management immediately
• Write integration tests for enforcement after sandbox implementations are available

Import In IDE

🤖 Prompt for AI Agents

## Observations

The Ralph codebase is a mature bash-based autonomous development loop tool (v0.9.8) with 75 passing tests and comprehensive documentation. Currently, there is **no sandbox implementation** - Ralph executes Claude Code directly on the host system. Phase 6.4 (Security and Resource Policies) is a lower-priority future feature (P4) that depends on Phase 6.1 (Docker sandbox), Phase 6.2 (E2B sandbox), and Phase 6.3 (File sync) being implemented first. The existing architecture uses configuration variables at the script level, CLI argument parsing with standard bash patterns, and library modules for circuit breaker and response analysis functionality.

## Approach

The implementation will follow a **layered security architecture** where policies are defined at multiple levels (CLI flags, config files, presets) and enforced by sandbox-specific adapters. Since Ralph is bash-based, the approach will create a new `lib/sandbox_policy.sh` module for policy management, extend the existing CLI parser to accept sandbox-related flags, add configuration file support (`.ralphrc`) for persistent policies, and implement sandbox-specific enforcement adapters for Docker and E2B. The design prioritizes **security by default** with a "standard" policy preset, while allowing flexibility through policy customization. This approach integrates seamlessly with Ralph's existing patterns (library modules, CLI parsing, configuration variables) and maintains backward compatibility. As a P4 priority feature, implementation should be deferred until higher-priority phases (6.1, 6.2, 6.3) are complete.

## Implementation Steps

### 1. Policy Management Infrastructure

Create `file:lib/sandbox_policy.sh` as the central policy management module:

**Core Functions:**
- `init_sandbox_policy()` - Initialize policy system with defaults
- `load_policy_config()` - Load policies from `.ralphrc` or `~/.ralph/config.yaml`
- `validate_policy()` - Validate policy configuration before sandbox start
- `get_policy_value()` - Retrieve specific policy values
- `apply_policy_preset()` - Apply predefined policy presets (paranoid/standard/permissive)

**Policy Data Structure:**
Store policies in bash associative arrays or JSON files:
```
SANDBOX_POLICY_NETWORK_MODE="restricted"
SANDBOX_POLICY_NETWORK_ALLOW=("api.anthropic.com" "*.npmjs.org" "pypi.org")
SANDBOX_POLICY_NETWORK_DENY=("*.internal.corp")
SANDBOX_POLICY_MEMORY="4g"
SANDBOX_POLICY_CPUS="2"
SANDBOX_POLICY_DISK="10g"
SANDBOX_POLICY_MAX_DURATION="2h"
SANDBOX_POLICY_LOOP_TIMEOUT="15m"
```

### 2. Configuration File Support

Implement `.ralphrc` and `~/.ralph/config.yaml` support:

**File Locations (Priority Order):**
1. Project-level: `./.ralphrc` (highest priority)
2. User-level: `~/.ralph/config.yaml`
3. Defaults: Built into `lib/sandbox_policy.sh`

**Configuration Format:**
Support both bash-style `.ralphrc` (for simple key=value) and YAML `config.yaml` (for structured policies). Use `yq` if available, fallback to custom bash parser for YAML. Note: Configuration file support is already partially implemented in Ralph's existing codebase (see `load_config()` in Week 5 of IMPLEMENTATION_PLAN.md), so this step should integrate with existing patterns.

**Example `.ralphrc`:**
```bash
# Sandbox security policies
SANDBOX_TYPE=docker
SANDBOX_POLICY_PRESET=standard
SANDBOX_NETWORK_MODE=restricted
SANDBOX_MEMORY=4g
SANDBOX_CPUS=2
SANDBOX_MAX_DURATION=2h
```

**Example `~/.ralph/config.yaml`:**
```yaml
sandbox:
  type: docker
  security:
    network:
      mode: restricted
      allow:
        - api.anthropic.com
        - "*.npmjs.org"
      deny:
        - "*.internal.corp"
    resources:
      memory: 4g
      cpus: 2
      disk: 10g
      maxDuration: 2h
      loopTimeout: 15m
    secrets:
      source: file
      path: ~/.ralph/secrets
```

**Implementation:**
- Add `load_config()` function in `file:ralph_loop.sh` (call before main loop)
- Parse YAML using `yq` if available, fallback to bash parsing for `.ralphrc`
- Merge configs: defaults → user config → project config → CLI flags

### 3. CLI Flag Extensions

Extend `file:ralph_loop.sh` CLI parser to accept sandbox policy flags:

**New Flags:**
```bash
--sandbox TYPE              # docker | e2b | none (default: none)
--sandbox-policy PRESET     # paranoid | standard | permissive
--network MODE              # none | restricted | open
--network-allow HOSTS       # Comma-separated allowlist
--network-deny HOSTS        # Comma-separated denylist
--memory SIZE               # e.g., 4g, 8g
--cpus NUM                  # e.g., 2, 4
--disk SIZE                 # e.g., 10g, 20g
--max-duration TIME         # e.g., 2h, 30m
--loop-timeout TIME         # e.g., 15m, 30m
--max-cost AMOUNT           # e.g., 10.00 (for E2B)
--secrets-file PATH         # Path to secrets file
--secret NAME               # Inject specific secret
--read-only-root            # Enable read-only root filesystem
--writable PATHS            # Comma-separated writable paths
--protect FILES             # Comma-separated protected files
```

**Integration:**
Add cases to the existing `while [[ $# -gt 0 ]]` loop in `file:ralph_loop.sh` (around line 1141). Store values in global variables like `SANDBOX_TYPE`, `SANDBOX_POLICY_PRESET`, etc.

### 4. Policy Presets

Implement three predefined security profiles in `file:lib/sandbox_policy.sh`:

**Paranoid Preset:**
- Network: none
- Filesystem: read-only root, writable `/workspace/output` only
- Resources: 1GB memory, 1 CPU, 5GB disk
- Duration: 30 minutes max
- Use case: Untrusted code, maximum security

**Standard Preset (Default):**
- Network: restricted (allowlist: Claude API, npm, pip, GitHub)
- Filesystem: writable `/workspace`, protected `PROMPT.md` and `@fix_plan.md`
- Resources: 4GB memory, 2 CPUs, 10GB disk
- Duration: 2 hours max
- Use case: Normal development, balanced security

**Permissive Preset:**
- Network: open (full access)
- Filesystem: full access
- Resources: 8GB memory, 4 CPUs, 20GB disk
- Duration: no limit
- Use case: Development/debugging, minimal restrictions

**Function:**
```bash
apply_policy_preset() {
    local preset=$1
    case $preset in
        paranoid) apply_paranoid_preset ;;
        standard) apply_standard_preset ;;
        permissive) apply_permissive_preset ;;
    esac
}
```

### 5. Network Policy Enforcement

Create network policy enforcement adapters:

**Docker Enforcement (`file:lib/sandbox_docker.sh`):**
- `none` mode: `--network none` flag
- `restricted` mode: Custom Docker network with iptables rules or DNS filtering
- `open` mode: `--network bridge` (default)
- Allowlist/denylist: Use Docker DNS configuration or iptables rules

**E2B Enforcement (`file:lib/sandbox_e2b.sh`):**
- Use E2B SDK network configuration options
- May have different enforcement mechanisms than Docker
- Consult E2B documentation for network isolation capabilities

**Implementation:**
```bash
apply_network_policy_docker() {
    local mode=$1
    case $mode in
        none)
            DOCKER_NETWORK_FLAGS="--network none"
            ;;
        restricted)
            # Create custom network with DNS filtering
            setup_restricted_network_docker
            DOCKER_NETWORK_FLAGS="--network ralph-restricted"
            ;;
        open)
            DOCKER_NETWORK_FLAGS="--network bridge"
            ;;
    esac
}
```

### 6. Filesystem Policy Enforcement

Implement filesystem access controls:

**Docker Enforcement:**
- Read-only root: `--read-only` flag
- Writable paths: `--tmpfs` or volume mounts with `rw` flag
- Protected files: Mount as read-only volumes
- Example: `docker run --read-only -v /workspace/output:/workspace/output:rw`

**E2B Enforcement:**
- Use E2B filesystem configuration
- May use different mechanisms (check E2B SDK)

**Implementation:**
```bash
apply_filesystem_policy_docker() {
    local read_only_root=$1
    local writable_paths=$2
    local protected_files=$3
    
    if [[ "$read_only_root" == "true" ]]; then
        DOCKER_FS_FLAGS="--read-only"
    fi
    
    # Add writable mounts
    for path in ${writable_paths//,/ }; do
        DOCKER_FS_FLAGS="$DOCKER_FS_FLAGS -v $path:$path:rw"
    done
    
    # Add protected files as read-only mounts
    for file in ${protected_files//,/ }; do
        DOCKER_FS_FLAGS="$DOCKER_FS_FLAGS -v $file:$file:ro"
    done
}
```

### 7. Resource Limit Enforcement

Implement resource constraints:

**Docker Enforcement:**
- Memory: `--memory 4g` flag
- CPU: `--cpus 2` flag
- Disk: Docker storage driver limits or volume size limits
- Duration: Implement timeout wrapper around Docker execution

**E2B Enforcement:**
- Use E2B SDK resource configuration
- Cost limits: Track E2B API usage and halt when limit reached

**Implementation:**
```bash
apply_resource_limits_docker() {
    local memory=$1
    local cpus=$2
    local disk=$3
    
    DOCKER_RESOURCE_FLAGS="--memory $memory --cpus $cpus"
    
    # Disk limits via storage driver (requires Docker configuration)
    if [[ -n "$disk" ]]; then
        DOCKER_RESOURCE_FLAGS="$DOCKER_RESOURCE_FLAGS --storage-opt size=$disk"
    fi
}

enforce_duration_limit() {
    local max_duration=$1  # e.g., "2h"
    local timeout_seconds=$(parse_duration_to_seconds "$max_duration")
    
    # Use timeout command to enforce
    timeout "$timeout_seconds" docker run ...
}
```

### 8. Secret Management

Implement secure secret injection:

**Preferred Method: Mounted Files**
- Store secrets in `~/.ralph/secrets/` directory
- Mount as read-only files in sandbox: `/run/secrets/ANTHROPIC_API_KEY`
- Never log or sync secrets

**Docker Implementation:**
```bash
inject_secrets_docker() {
    local secrets_file=$1
    local secret_names=$2
    
    # Mount secrets directory
    DOCKER_SECRET_FLAGS="-v ~/.ralph/secrets:/run/secrets:ro"
    
    # Set environment variables pointing to secret files
    for secret in ${secret_names//,/ }; do
        DOCKER_SECRET_FLAGS="$DOCKER_SECRET_FLAGS -e ${secret}_FILE=/run/secrets/$secret"
    done
}
```

**Secret Masking:**
Add to `file:lib/response_analyzer.sh`:
```bash
mask_secrets_in_output() {
    local output=$1
    # Replace known secret patterns with [REDACTED]
    output=$(echo "$output" | sed 's/sk-ant-[a-zA-Z0-9-]*/[REDACTED]/g')
    echo "$output"
}
```

### 9. Policy Validation

Implement policy validation before sandbox start:

**Validation Checks:**
- Network allowlist/denylist conflicts
- Resource limits are valid (memory > 0, cpus > 0)
- Duration formats are correct (e.g., "2h", "30m")
- Secret files exist and are readable
- Writable paths don't conflict with protected files

**Implementation in `file:lib/sandbox_policy.sh`:**
```bash
validate_policy() {
    local errors=()
    
    # Validate network policy
    if [[ "$SANDBOX_POLICY_NETWORK_MODE" == "restricted" ]]; then
        if [[ -z "${SANDBOX_POLICY_NETWORK_ALLOW[@]}" ]]; then
            errors+=("Restricted network mode requires allowlist")
        fi
    fi
    
    # Validate resource limits
    if ! validate_memory_format "$SANDBOX_POLICY_MEMORY"; then
        errors+=("Invalid memory format: $SANDBOX_POLICY_MEMORY")
    fi
    
    # Validate duration
    if ! validate_duration_format "$SANDBOX_POLICY_MAX_DURATION"; then
        errors+=("Invalid duration format: $SANDBOX_POLICY_MAX_DURATION")
    fi
    
    # Report errors
    if [[ ${#errors[@]} -gt 0 ]]; then
        log_status "ERROR" "Policy validation failed:"
        for error in "${errors[@]}"; do
            log_status "ERROR" "  - $error"
        done
        return 1
    fi
    
    return 0
}
```

### 10. Sandbox Adapter Architecture

Create sandbox-specific adapters:

**File Structure:**
- `file:lib/sandbox_policy.sh` - Policy management (shared)
- `file:lib/sandbox_docker.sh` - Docker-specific enforcement (depends on Phase 6.1)
- `file:lib/sandbox_e2b.sh` - E2B-specific enforcement (depends on Phase 6.2)
- `file:lib/sandbox_none.sh` - No-op adapter for host execution

**Adapter Interface:**
Each adapter implements:
- `init_sandbox_TYPE()` - Initialize sandbox
- `apply_network_policy_TYPE()` - Enforce network policy
- `apply_filesystem_policy_TYPE()` - Enforce filesystem policy
- `apply_resource_limits_TYPE()` - Enforce resource limits
- `inject_secrets_TYPE()` - Inject secrets
- `execute_in_sandbox_TYPE()` - Execute command in sandbox
- `cleanup_sandbox_TYPE()` - Cleanup sandbox resources

**Dynamic Loading:**
```bash
# In ralph_loop.sh
source "$SCRIPT_DIR/lib/sandbox_policy.sh"

if [[ "$SANDBOX_TYPE" == "docker" ]]; then
    source "$SCRIPT_DIR/lib/sandbox_docker.sh"
elif [[ "$SANDBOX_TYPE" == "e2b" ]]; then
    source "$SCRIPT_DIR/lib/sandbox_e2b.sh"
else
    source "$SCRIPT_DIR/lib/sandbox_none.sh"
fi
```

**Implementation Note:** Docker and E2B adapters should be implemented only after their respective sandbox implementations (Phase 6.1 and 6.2) are complete.

### 11. Integration with Main Loop

Modify `file:ralph_loop.sh` to integrate sandbox policies:

**Initialization (before main loop):**
```bash
# Load configuration files
load_config

# Initialize sandbox policy
init_sandbox_policy

# Apply policy preset if specified
if [[ -n "$SANDBOX_POLICY_PRESET" ]]; then
    apply_policy_preset "$SANDBOX_POLICY_PRESET"
fi

# Validate policy
if ! validate_policy; then
    exit 1
fi

# Initialize sandbox
init_sandbox_"$SANDBOX_TYPE"
```

**Execution (in main loop):**
Replace direct Claude Code execution with sandbox execution:
```bash
# Old: execute_claude_code
# New: execute_in_sandbox_"$SANDBOX_TYPE" execute_claude_code
```

**Cleanup (on exit):**
```bash
cleanup() {
    # Existing cleanup...
    
    # Cleanup sandbox
    cleanup_sandbox_"$SANDBOX_TYPE"
}
```

### 12. Audit Logging

Add security audit logging to `file:lib/sandbox_policy.sh`:

**Log Events:**
- Policy initialization and validation
- Network policy violations (if detectable)
- Resource limit breaches
- Secret access attempts
- Sandbox start/stop events

**Implementation:**
```bash
audit_log() {
    local event=$1
    local details=$2
    local timestamp=$(date -Iseconds)
    
    echo "{\"timestamp\":\"$timestamp\",\"event\":\"$event\",\"details\":\"$details\"}" \
        >> "$LOG_DIR/security_audit.jsonl"
}

# Usage
audit_log "sandbox_start" "type=docker,policy=standard,network=restricted"
audit_log "policy_violation" "attempted_network_access=blocked.example.com"
```

### 13. Testing Strategy

Create comprehensive test suite:

**Unit Tests (`file:tests/unit/test_sandbox_policy.bats`):**
- Policy loading from config files
- Policy validation logic
- Policy preset application
- Secret masking functions
- Duration/memory format parsing
- Estimated: 15-20 tests

**Integration Tests (`file:tests/integration/test_sandbox_docker.bats`):**
- Docker sandbox initialization
- Network policy enforcement
- Filesystem policy enforcement
- Resource limit enforcement
- Secret injection
- Estimated: 20-25 tests (depends on Phase 6.1 completion)

**Integration Tests (`file:tests/integration/test_sandbox_e2b.bats`):**
- E2B sandbox initialization
- E2B-specific policy enforcement
- Cost limit tracking
- Estimated: 15-20 tests (depends on Phase 6.2 completion)

**Edge Case Tests:**
- Invalid policy configurations
- Conflicting policies
- Missing dependencies (Docker not installed)
- Secret file permissions
- Resource exhaustion scenarios
- Estimated: 10-15 tests

**Test Sequencing:** Unit tests for policy management can be written immediately. Integration tests for Docker and E2B enforcement should be deferred until their respective sandbox implementations are complete.

### 14. Documentation

Update documentation files:

**`file:README.md`:**
- Add "Sandbox Execution" section
- Document CLI flags for sandbox policies
- Provide examples of common configurations
- Security best practices

**Create `file:docs/SANDBOX_SECURITY.md`:**
- Detailed security policy documentation
- Policy preset descriptions
- Network policy configuration guide
- Secret management best practices
- Troubleshooting guide

**Update `file:IMPLEMENTATION_PLAN.md`:**
- Add Phase 6.4 completion status
- Document test coverage for sandbox features

### 15. Backward Compatibility

Ensure backward compatibility:

**Default Behavior:**
- `SANDBOX_TYPE=none` by default (no sandbox, current behavior)
- No breaking changes to existing CLI flags
- Config files are optional

**Migration Path:**
- Users can opt-in to sandbox execution with `--sandbox docker`
- Existing projects continue to work without modification
- Gradual migration: test with sandbox, then make it default

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant ralph_loop.sh
    participant sandbox_policy.sh
    participant sandbox_docker.sh
    participant Docker
    participant Claude

    User->>ralph_loop.sh: ralph --sandbox docker --sandbox-policy standard
    ralph_loop.sh->>ralph_loop.sh: load_config() from .ralphrc
    ralph_loop.sh->>sandbox_policy.sh: init_sandbox_policy()
    sandbox_policy.sh->>sandbox_policy.sh: apply_policy_preset("standard")
    sandbox_policy.sh->>sandbox_policy.sh: validate_policy()
    sandbox_policy.sh-->>ralph_loop.sh: Policy validated
    
    ralph_loop.sh->>sandbox_docker.sh: init_sandbox_docker()
    sandbox_docker.sh->>sandbox_docker.sh: apply_network_policy_docker("restricted")
    sandbox_docker.sh->>sandbox_docker.sh: apply_filesystem_policy_docker()
    sandbox_docker.sh->>sandbox_docker.sh: apply_resource_limits_docker()
    sandbox_docker.sh->>sandbox_docker.sh: inject_secrets_docker()
    sandbox_docker.sh->>Docker: docker run with policy flags
    Docker-->>sandbox_docker.sh: Container ready
    
    loop Main Loop
        ralph_loop.sh->>sandbox_docker.sh: execute_in_sandbox_docker(claude_command)
        sandbox_docker.sh->>Docker: docker exec
        Docker->>Claude: Execute Claude Code
        Claude-->>Docker: Response
        Docker-->>sandbox_docker.sh: Output
        sandbox_docker.sh->>sandbox_policy.sh: mask_secrets_in_output()
        sandbox_docker.sh-->>ralph_loop.sh: Sanitized output
        ralph_loop.sh->>sandbox_policy.sh: audit_log("execution_complete")
    end
    
    ralph_loop.sh->>sandbox_docker.sh: cleanup_sandbox_docker()
    sandbox_docker.sh->>Docker: docker stop & rm
    Docker-->>sandbox_docker.sh: Cleanup complete
```

## Policy Configuration Example

```yaml
# ~/.ralph/config.yaml
sandbox:
  type: docker
  
  security:
    # Network policy
    network:
      mode: restricted
      allow:
        - api.anthropic.com
        - registry.npmjs.org
        - pypi.org
        - files.pythonhosted.org
        - github.com
      deny:
        - "*.internal.company.com"
        - "*.local"
    
    # Filesystem policy
    filesystem:
      readOnlyRoot: true
      writable:
        - /workspace/output
        - /workspace/logs
        - /workspace/.ralph_session
      protected:
        - PROMPT.md
        - "@fix_plan.md"
        - specs/
    
    # Resource limits
    resources:
      memory: 4g
      cpus: 2
      disk: 10g
      maxDuration: 2h
      loopTimeout: 15m
    
    # Secret management
    secrets:
      source: file
      path: ~/.ralph/secrets
      inject:
        - ANTHROPIC_API_KEY
        - GITHUB_TOKEN
      
    # Audit logging
    audit:
      enabled: true
      logFile: logs/security_audit.jsonl
```

## Dependencies

**Required:**
- Docker (for Docker sandbox) - `docker --version` (Phase 6.1 prerequisite)
- E2B SDK (for E2B sandbox) - `npm install -g @e2b/sdk` (Phase 6.2 prerequisite)
- `yq` (for YAML parsing) - `brew install yq` or `apt-get install yq`
- `jq` (already required by Ralph)

**Optional:**
- `iptables` (for advanced Docker network filtering)
- Secret managers: AWS Secrets Manager CLI, 1Password CLI

**Phase Dependencies:**
- Phase 6.1 (Docker sandbox) must be complete before Docker policy enforcement can be tested
- Phase 6.2 (E2B sandbox) must be complete before E2B policy enforcement can be tested
- Phase 6.3 (File sync) should be complete before secret exclusion policies are finalized

## Risk Mitigation

**Security Risks:**
- **Secret leakage**: Mitigated by secret masking, read-only mounts, and audit logging
- **Network exfiltration**: Mitigated by network policies and allowlist/denylist
- **Resource exhaustion**: Mitigated by resource limits and duration timeouts

**Implementation Risks:**
- **Docker not available**: Graceful fallback to host execution with warning
- **E2B API changes**: Version pinning and adapter pattern for isolation
- **Policy conflicts**: Validation before sandbox start prevents runtime errors
- **Dependency on earlier phases**: As a P4 feature, this work should not block higher-priority phases (6.1, 6.2, 6.3)

**Backward Compatibility:**
- Default `SANDBOX_TYPE=none` ensures existing workflows continue unchanged
- All sandbox features are opt-in via CLI flags or config files
- Policy management infrastructure can be implemented independently of sandbox implementations

**Phasing Strategy:**
- Implement policy management infrastructure (steps 1-9) early for code organization
- Defer sandbox-specific enforcement (steps 10-12) until Phase 6.1 and 6.2 are complete
- Write unit tests for policy management immediately
- Write integration tests for enforcement after sandbox implementations are available

---

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.

Previous Plan

Observations

The Ralph codebase is a mature bash-based autonomous development loop tool (v0.9.8) with 276 passing tests and comprehensive documentation. Currently, there is no sandbox implementation - Ralph executes Claude Code directly on the host system. Phase 6.4 (Security and Resource Policies) is a future feature that depends on Phase 6.1 (Docker sandbox), Phase 6.2 (E2B sandbox), and Phase 6.3 (File sync) being implemented first. The existing architecture uses configuration variables at the script level, CLI argument parsing with standard bash patterns, and library modules for circuit breaker and response analysis functionality.

Approach

The implementation will follow a layered security architecture where policies are defined at multiple levels (CLI flags, config files, presets) and enforced by sandbox-specific adapters. Since Ralph is bash-based, the approach will create a new lib/sandbox_policy.sh module for policy management, extend the existing CLI parser to accept sandbox-related flags, add configuration file support (.ralphrc) for persistent policies, and implement sandbox-specific enforcement adapters for Docker and E2B. The design prioritizes security by default with a "standard" policy preset, while allowing flexibility through policy customization. This approach integrates seamlessly with Ralph's existing patterns (library modules, CLI parsing, configuration variables) and maintains backward compatibility.

Implementation Steps

1. Policy Management Infrastructure

Create file:lib/sandbox_policy.sh as the central policy management module:

Core Functions:

• init_sandbox_policy() - Initialize policy system with defaults
• load_policy_config() - Load policies from .ralphrc or ~/.ralph/config.yaml
• validate_policy() - Validate policy configuration before sandbox start
• get_policy_value() - Retrieve specific policy values
• apply_policy_preset() - Apply predefined policy presets (paranoid/standard/permissive)

Policy Data Structure:
Store policies in bash associative arrays or JSON files:

SANDBOX_POLICY_NETWORK_MODE="restricted"
SANDBOX_POLICY_NETWORK_ALLOW=("api.anthropic.com" "*.npmjs.org" "pypi.org")
SANDBOX_POLICY_NETWORK_DENY=("*.internal.corp")
SANDBOX_POLICY_MEMORY="4g"
SANDBOX_POLICY_CPUS="2"
SANDBOX_POLICY_DISK="10g"
SANDBOX_POLICY_MAX_DURATION="2h"
SANDBOX_POLICY_LOOP_TIMEOUT="15m"

2. Configuration File Support

Implement .ralphrc and ~/.ralph/config.yaml support:

File Locations (Priority Order):

1. Project-level: ./.ralphrc (highest priority)
2. User-level: ~/.ralph/config.yaml
3. Defaults: Built into lib/sandbox_policy.sh

Configuration Format:
Support both bash-style .ralphrc (for simple key=value) and YAML config.yaml (for structured policies). Use yq or custom bash parser for YAML.

Example .ralphrc:

# Sandbox security policies
SANDBOX_TYPE=docker
SANDBOX_POLICY_PRESET=standard
SANDBOX_NETWORK_MODE=restricted
SANDBOX_MEMORY=4g
SANDBOX_CPUS=2
SANDBOX_MAX_DURATION=2h

Example ~/.ralph/config.yaml:

sandbox:
  type: docker
  security:
    network:
      mode: restricted
      allow:
        - api.anthropic.com
        - "*.npmjs.org"
      deny:
        - "*.internal.corp"
    resources:
      memory: 4g
      cpus: 2
      disk: 10g
      maxDuration: 2h
      loopTimeout: 15m
    secrets:
      source: file
      path: ~/.ralph/secrets

Implementation:

• Add load_config() function in file:ralph_loop.sh (call before main loop)
• Parse YAML using yq if available, fallback to bash parsing for .ralphrc
• Merge configs: defaults → user config → project config → CLI flags

3. CLI Flag Extensions

Extend file:ralph_loop.sh CLI parser to accept sandbox policy flags:

New Flags:

--sandbox TYPE              # docker | e2b | none (default: none)
--sandbox-policy PRESET     # paranoid | standard | permissive
--network MODE              # none | restricted | open
--network-allow HOSTS       # Comma-separated allowlist
--network-deny HOSTS        # Comma-separated denylist
--memory SIZE               # e.g., 4g, 8g
--cpus NUM                  # e.g., 2, 4
--disk SIZE                 # e.g., 10g, 20g
--max-duration TIME         # e.g., 2h, 30m
--loop-timeout TIME         # e.g., 15m, 30m
--max-cost AMOUNT           # e.g., 10.00 (for E2B)
--secrets-file PATH         # Path to secrets file
--secret NAME               # Inject specific secret
--read-only-root            # Enable read-only root filesystem
--writable PATHS            # Comma-separated writable paths
--protect FILES             # Comma-separated protected files

Integration:
Add cases to the existing while [[ $# -gt 0 ]] loop in file:ralph_loop.sh (around line 1141). Store values in global variables like SANDBOX_TYPE, SANDBOX_POLICY_PRESET, etc.

4. Policy Presets

Implement three predefined security profiles in file:lib/sandbox_policy.sh:

Paranoid Preset:

• Network: none
• Filesystem: read-only root, writable /workspace/output only
• Resources: 1GB memory, 1 CPU, 5GB disk
• Duration: 30 minutes max
• Use case: Untrusted code, maximum security

Standard Preset (Default):

• Network: restricted (allowlist: Claude API, npm, pip, GitHub)
• Filesystem: writable /workspace, protected PROMPT.md and @fix_plan.md
• Resources: 4GB memory, 2 CPUs, 10GB disk
• Duration: 2 hours max
• Use case: Normal development, balanced security

Permissive Preset:

• Network: open (full access)
• Filesystem: full access
• Resources: 8GB memory, 4 CPUs, 20GB disk
• Duration: no limit
• Use case: Development/debugging, minimal restrictions

Function:

apply_policy_preset() {
    local preset=$1
    case $preset in
        paranoid) apply_paranoid_preset ;;
        standard) apply_standard_preset ;;
        permissive) apply_permissive_preset ;;
    esac
}

5. Network Policy Enforcement

Create network policy enforcement adapters:

Docker Enforcement (file:lib/sandbox_docker.sh):

• none mode: --network none flag
• restricted mode: Custom Docker network with iptables rules or DNS filtering
• open mode: --network bridge (default)
• Allowlist/denylist: Use Docker DNS configuration or iptables rules

E2B Enforcement (file:lib/sandbox_e2b.sh):

• Use E2B SDK network configuration options
• May have different enforcement mechanisms than Docker
• Consult E2B documentation for network isolation capabilities

Implementation:

apply_network_policy_docker() {
    local mode=$1
    case $mode in
        none)
            DOCKER_NETWORK_FLAGS="--network none"
            ;;
        restricted)
            # Create custom network with DNS filtering
            setup_restricted_network_docker
            DOCKER_NETWORK_FLAGS="--network ralph-restricted"
            ;;
        open)
            DOCKER_NETWORK_FLAGS="--network bridge"
            ;;
    esac
}

6. Filesystem Policy Enforcement

Implement filesystem access controls:

Docker Enforcement:

• Read-only root: --read-only flag
• Writable paths: --tmpfs or volume mounts with rw flag
• Protected files: Mount as read-only volumes
• Example: docker run --read-only -v /workspace/output:/workspace/output:rw

E2B Enforcement:

• Use E2B filesystem configuration
• May use different mechanisms (check E2B SDK)

Implementation:

apply_filesystem_policy_docker() {
    local read_only_root=$1
    local writable_paths=$2
    local protected_files=$3
    
    if [[ "$read_only_root" == "true" ]]; then
        DOCKER_FS_FLAGS="--read-only"
    fi
    
    # Add writable mounts
    for path in ${writable_paths//,/ }; do
        DOCKER_FS_FLAGS="$DOCKER_FS_FLAGS -v $path:$path:rw"
    done
    
    # Add protected files as read-only mounts
    for file in ${protected_files//,/ }; do
        DOCKER_FS_FLAGS="$DOCKER_FS_FLAGS -v $file:$file:ro"
    done
}

7. Resource Limit Enforcement

Implement resource constraints:

Docker Enforcement:

• Memory: --memory 4g flag
• CPU: --cpus 2 flag
• Disk: Docker storage driver limits or volume size limits
• Duration: Implement timeout wrapper around Docker execution

E2B Enforcement:

• Use E2B SDK resource configuration
• Cost limits: Track E2B API usage and halt when limit reached

Implementation:

apply_resource_limits_docker() {
    local memory=$1
    local cpus=$2
    local disk=$3
    
    DOCKER_RESOURCE_FLAGS="--memory $memory --cpus $cpus"
    
    # Disk limits via storage driver (requires Docker configuration)
    if [[ -n "$disk" ]]; then
        DOCKER_RESOURCE_FLAGS="$DOCKER_RESOURCE_FLAGS --storage-opt size=$disk"
    fi
}

enforce_duration_limit() {
    local max_duration=$1  # e.g., "2h"
    local timeout_seconds=$(parse_duration_to_seconds "$max_duration")
    
    # Use timeout command to enforce
    timeout "$timeout_seconds" docker run ...
}

8. Secret Management

Implement secure secret injection:

Preferred Method: Mounted Files

• Store secrets in ~/.ralph/secrets/ directory
• Mount as read-only files in sandbox: /run/secrets/ANTHROPIC_API_KEY
• Never log or sync secrets

Docker Implementation:

inject_secrets_docker() {
    local secrets_file=$1
    local secret_names=$2
    
    # Mount secrets directory
    DOCKER_SECRET_FLAGS="-v ~/.ralph/secrets:/run/secrets:ro"
    
    # Set environment variables pointing to secret files
    for secret in ${secret_names//,/ }; do
        DOCKER_SECRET_FLAGS="$DOCKER_SECRET_FLAGS -e ${secret}_FILE=/run/secrets/$secret"
    done
}

Secret Masking:
Add to file:lib/response_analyzer.sh:

mask_secrets_in_output() {
    local output=$1
    # Replace known secret patterns with [REDACTED]
    output=$(echo "$output" | sed 's/sk-ant-[a-zA-Z0-9-]*/[REDACTED]/g')
    echo "$output"
}

9. Policy Validation

Implement policy validation before sandbox start:

Validation Checks:

• Network allowlist/denylist conflicts
• Resource limits are valid (memory > 0, cpus > 0)
• Duration formats are correct (e.g., "2h", "30m")
• Secret files exist and are readable
• Writable paths don't conflict with protected files

Implementation in file:lib/sandbox_policy.sh:

validate_policy() {
    local errors=()
    
    # Validate network policy
    if [[ "$SANDBOX_POLICY_NETWORK_MODE" == "restricted" ]]; then
        if [[ -z "${SANDBOX_POLICY_NETWORK_ALLOW[@]}" ]]; then
            errors+=("Restricted network mode requires allowlist")
        fi
    fi
    
    # Validate resource limits
    if ! validate_memory_format "$SANDBOX_POLICY_MEMORY"; then
        errors+=("Invalid memory format: $SANDBOX_POLICY_MEMORY")
    fi
    
    # Validate duration
    if ! validate_duration_format "$SANDBOX_POLICY_MAX_DURATION"; then
        errors+=("Invalid duration format: $SANDBOX_POLICY_MAX_DURATION")
    fi
    
    # Report errors
    if [[ ${#errors[@]} -gt 0 ]]; then
        log_status "ERROR" "Policy validation failed:"
        for error in "${errors[@]}"; do
            log_status "ERROR" "  - $error"
        done
        return 1
    fi
    
    return 0
}

10. Sandbox Adapter Architecture

Create sandbox-specific adapters:

File Structure:

• file:lib/sandbox_policy.sh - Policy management (shared)
• file:lib/sandbox_docker.sh - Docker-specific enforcement
• file:lib/sandbox_e2b.sh - E2B-specific enforcement
• file:lib/sandbox_none.sh - No-op adapter for host execution

Adapter Interface:
Each adapter implements:

• init_sandbox_TYPE() - Initialize sandbox
• apply_network_policy_TYPE() - Enforce network policy
• apply_filesystem_policy_TYPE() - Enforce filesystem policy
• apply_resource_limits_TYPE() - Enforce resource limits
• inject_secrets_TYPE() - Inject secrets
• execute_in_sandbox_TYPE() - Execute command in sandbox
• cleanup_sandbox_TYPE() - Cleanup sandbox resources

Dynamic Loading:

# In ralph_loop.sh
source "$SCRIPT_DIR/lib/sandbox_policy.sh"

if [[ "$SANDBOX_TYPE" == "docker" ]]; then
    source "$SCRIPT_DIR/lib/sandbox_docker.sh"
elif [[ "$SANDBOX_TYPE" == "e2b" ]]; then
    source "$SCRIPT_DIR/lib/sandbox_e2b.sh"
else
    source "$SCRIPT_DIR/lib/sandbox_none.sh"
fi

11. Integration with Main Loop

Modify file:ralph_loop.sh to integrate sandbox policies:

Initialization (before main loop):

# Load configuration files
load_config

# Initialize sandbox policy
init_sandbox_policy

# Apply policy preset if specified
if [[ -n "$SANDBOX_POLICY_PRESET" ]]; then
    apply_policy_preset "$SANDBOX_POLICY_PRESET"
fi

# Validate policy
if ! validate_policy; then
    exit 1
fi

# Initialize sandbox
init_sandbox_"$SANDBOX_TYPE"

Execution (in main loop):
Replace direct Claude Code execution with sandbox execution:

# Old: execute_claude_code
# New: execute_in_sandbox_"$SANDBOX_TYPE" execute_claude_code

Cleanup (on exit):

cleanup() {
    # Existing cleanup...
    
    # Cleanup sandbox
    cleanup_sandbox_"$SANDBOX_TYPE"
}

12. Audit Logging

Add security audit logging to file:lib/sandbox_policy.sh:

Log Events:

• Policy initialization and validation
• Network policy violations (if detectable)
• Resource limit breaches
• Secret access attempts
• Sandbox start/stop events

Implementation:

audit_log() {
    local event=$1
    local details=$2
    local timestamp=$(date -Iseconds)
    
    echo "{\"timestamp\":\"$timestamp\",\"event\":\"$event\",\"details\":\"$details\"}" \
        >> "$LOG_DIR/security_audit.jsonl"
}

# Usage
audit_log "sandbox_start" "type=docker,policy=standard,network=restricted"
audit_log "policy_violation" "attempted_network_access=blocked.example.com"

13. Testing Strategy

Create comprehensive test suite:

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

• Policy loading from config files
• Policy validation logic
• Policy preset application
• Secret masking functions
• Duration/memory format parsing

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

• Docker sandbox initialization
• Network policy enforcement
• Filesystem policy enforcement
• Resource limit enforcement
• Secret injection

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

• E2B sandbox initialization
• E2B-specific policy enforcement
• Cost limit tracking

Edge Case Tests:

• Invalid policy configurations
• Conflicting policies
• Missing dependencies (Docker not installed)
• Secret file permissions
• Resource exhaustion scenarios

14. Documentation

Update documentation files:

file:README.md:

• Add "Sandbox Execution" section
• Document CLI flags for sandbox policies
• Provide examples of common configurations
• Security best practices

Create file:docs/SANDBOX_SECURITY.md:

• Detailed security policy documentation
• Policy preset descriptions
• Network policy configuration guide
• Secret management best practices
• Troubleshooting guide

Update file:IMPLEMENTATION_PLAN.md:

• Add Phase 6.4 completion status
• Document test coverage for sandbox features

15. Backward Compatibility

Ensure backward compatibility:

Default Behavior:

• SANDBOX_TYPE=none by default (no sandbox, current behavior)
• No breaking changes to existing CLI flags
• Config files are optional

Migration Path:

• Users can opt-in to sandbox execution with --sandbox docker
• Existing projects continue to work without modification
• Gradual migration: test with sandbox, then make it default

Architecture Diagram

sequenceDiagram
    participant User
    participant ralph_loop.sh
    participant sandbox_policy.sh
    participant sandbox_docker.sh
    participant Docker
    participant Claude

    User->>ralph_loop.sh: ralph --sandbox docker --sandbox-policy standard
    ralph_loop.sh->>ralph_loop.sh: load_config() from .ralphrc
    ralph_loop.sh->>sandbox_policy.sh: init_sandbox_policy()
    sandbox_policy.sh->>sandbox_policy.sh: apply_policy_preset("standard")
    sandbox_policy.sh->>sandbox_policy.sh: validate_policy()
    sandbox_policy.sh-->>ralph_loop.sh: Policy validated
    
    ralph_loop.sh->>sandbox_docker.sh: init_sandbox_docker()
    sandbox_docker.sh->>sandbox_docker.sh: apply_network_policy_docker("restricted")
    sandbox_docker.sh->>sandbox_docker.sh: apply_filesystem_policy_docker()
    sandbox_docker.sh->>sandbox_docker.sh: apply_resource_limits_docker()
    sandbox_docker.sh->>sandbox_docker.sh: inject_secrets_docker()
    sandbox_docker.sh->>Docker: docker run with policy flags
    Docker-->>sandbox_docker.sh: Container ready
    
    loop Main Loop
        ralph_loop.sh->>sandbox_docker.sh: execute_in_sandbox_docker(claude_command)
        sandbox_docker.sh->>Docker: docker exec
        Docker->>Claude: Execute Claude Code
        Claude-->>Docker: Response
        Docker-->>sandbox_docker.sh: Output
        sandbox_docker.sh->>sandbox_policy.sh: mask_secrets_in_output()
        sandbox_docker.sh-->>ralph_loop.sh: Sanitized output
        ralph_loop.sh->>sandbox_policy.sh: audit_log("execution_complete")
    end
    
    ralph_loop.sh->>sandbox_docker.sh: cleanup_sandbox_docker()
    sandbox_docker.sh->>Docker: docker stop & rm
    Docker-->>sandbox_docker.sh: Cleanup complete

Loading

Policy Configuration Example

# ~/.ralph/config.yaml
sandbox:
  type: docker
  
  security:
    # Network policy
    network:
      mode: restricted
      allow:
        - api.anthropic.com
        - registry.npmjs.org
        - pypi.org
        - files.pythonhosted.org
        - github.com
      deny:
        - "*.internal.company.com"
        - "*.local"
    
    # Filesystem policy
    filesystem:
      readOnlyRoot: true
      writable:
        - /workspace/output
        - /workspace/logs
        - /workspace/.ralph_session
      protected:
        - PROMPT.md
        - "@fix_plan.md"
        - specs/
    
    # Resource limits
    resources:
      memory: 4g
      cpus: 2
      disk: 10g
      maxDuration: 2h
      loopTimeout: 15m
    
    # Secret management
    secrets:
      source: file
      path: ~/.ralph/secrets
      inject:
        - ANTHROPIC_API_KEY
        - GITHUB_TOKEN
      
    # Audit logging
    audit:
      enabled: true
      logFile: logs/security_audit.jsonl

Dependencies

Required:

• Docker (for Docker sandbox) - docker --version
• E2B SDK (for E2B sandbox) - npm install -g @e2b/sdk
• yq (for YAML parsing) - brew install yq or apt-get install yq
• jq (already required by Ralph)

Optional:

• iptables (for advanced Docker network filtering)
• Secret managers: AWS Secrets Manager CLI, 1Password CLI

Risk Mitigation

Security Risks:

• Secret leakage: Mitigated by secret masking, read-only mounts, and audit logging
• Network exfiltration: Mitigated by network policies and allowlist/denylist
• Resource exhaustion: Mitigated by resource limits and duration timeouts

Implementation Risks:

• Docker not available: Graceful fallback to host execution with warning
• E2B API changes: Version pinning and adapter pattern for isolation
• Policy conflicts: Validation before sandbox start prevents runtime errors

Backward Compatibility:

• Default SANDBOX_TYPE=none ensures existing workflows continue unchanged
• All sandbox features are opt-in via CLI flags or config files

Import In IDE

🤖 Prompt for AI Agents

## Observations

The Ralph codebase is a mature bash-based autonomous development loop tool (v0.9.8) with 276 passing tests and comprehensive documentation. Currently, there is **no sandbox implementation** - Ralph executes Claude Code directly on the host system. Phase 6.4 (Security and Resource Policies) is a future feature that depends on Phase 6.1 (Docker sandbox), Phase 6.2 (E2B sandbox), and Phase 6.3 (File sync) being implemented first. The existing architecture uses configuration variables at the script level, CLI argument parsing with standard bash patterns, and library modules for circuit breaker and response analysis functionality.

## Approach

The implementation will follow a **layered security architecture** where policies are defined at multiple levels (CLI flags, config files, presets) and enforced by sandbox-specific adapters. Since Ralph is bash-based, the approach will create a new `lib/sandbox_policy.sh` module for policy management, extend the existing CLI parser to accept sandbox-related flags, add configuration file support (`.ralphrc`) for persistent policies, and implement sandbox-specific enforcement adapters for Docker and E2B. The design prioritizes **security by default** with a "standard" policy preset, while allowing flexibility through policy customization. This approach integrates seamlessly with Ralph's existing patterns (library modules, CLI parsing, configuration variables) and maintains backward compatibility.

## Implementation Steps

### 1. Policy Management Infrastructure

Create `file:lib/sandbox_policy.sh` as the central policy management module:

**Core Functions:**
- `init_sandbox_policy()` - Initialize policy system with defaults
- `load_policy_config()` - Load policies from `.ralphrc` or `~/.ralph/config.yaml`
- `validate_policy()` - Validate policy configuration before sandbox start
- `get_policy_value()` - Retrieve specific policy values
- `apply_policy_preset()` - Apply predefined policy presets (paranoid/standard/permissive)

**Policy Data Structure:**
Store policies in bash associative arrays or JSON files:
```
SANDBOX_POLICY_NETWORK_MODE="restricted"
SANDBOX_POLICY_NETWORK_ALLOW=("api.anthropic.com" "*.npmjs.org" "pypi.org")
SANDBOX_POLICY_NETWORK_DENY=("*.internal.corp")
SANDBOX_POLICY_MEMORY="4g"
SANDBOX_POLICY_CPUS="2"
SANDBOX_POLICY_DISK="10g"
SANDBOX_POLICY_MAX_DURATION="2h"
SANDBOX_POLICY_LOOP_TIMEOUT="15m"
```

### 2. Configuration File Support

Implement `.ralphrc` and `~/.ralph/config.yaml` support:

**File Locations (Priority Order):**
1. Project-level: `./.ralphrc` (highest priority)
2. User-level: `~/.ralph/config.yaml`
3. Defaults: Built into `lib/sandbox_policy.sh`

**Configuration Format:**
Support both bash-style `.ralphrc` (for simple key=value) and YAML `config.yaml` (for structured policies). Use `yq` or custom bash parser for YAML.

**Example `.ralphrc`:**
```bash
# Sandbox security policies
SANDBOX_TYPE=docker
SANDBOX_POLICY_PRESET=standard
SANDBOX_NETWORK_MODE=restricted
SANDBOX_MEMORY=4g
SANDBOX_CPUS=2
SANDBOX_MAX_DURATION=2h
```

**Example `~/.ralph/config.yaml`:**
```yaml
sandbox:
  type: docker
  security:
    network:
      mode: restricted
      allow:
        - api.anthropic.com
        - "*.npmjs.org"
      deny:
        - "*.internal.corp"
    resources:
      memory: 4g
      cpus: 2
      disk: 10g
      maxDuration: 2h
      loopTimeout: 15m
    secrets:
      source: file
      path: ~/.ralph/secrets
```

**Implementation:**
- Add `load_config()` function in `file:ralph_loop.sh` (call before main loop)
- Parse YAML using `yq` if available, fallback to bash parsing for `.ralphrc`
- Merge configs: defaults → user config → project config → CLI flags

### 3. CLI Flag Extensions

Extend `file:ralph_loop.sh` CLI parser to accept sandbox policy flags:

**New Flags:**
```bash
--sandbox TYPE              # docker | e2b | none (default: none)
--sandbox-policy PRESET     # paranoid | standard | permissive
--network MODE              # none | restricted | open
--network-allow HOSTS       # Comma-separated allowlist
--network-deny HOSTS        # Comma-separated denylist
--memory SIZE               # e.g., 4g, 8g
--cpus NUM                  # e.g., 2, 4
--disk SIZE                 # e.g., 10g, 20g
--max-duration TIME         # e.g., 2h, 30m
--loop-timeout TIME         # e.g., 15m, 30m
--max-cost AMOUNT           # e.g., 10.00 (for E2B)
--secrets-file PATH         # Path to secrets file
--secret NAME               # Inject specific secret
--read-only-root            # Enable read-only root filesystem
--writable PATHS            # Comma-separated writable paths
--protect FILES             # Comma-separated protected files
```

**Integration:**
Add cases to the existing `while [[ $# -gt 0 ]]` loop in `file:ralph_loop.sh` (around line 1141). Store values in global variables like `SANDBOX_TYPE`, `SANDBOX_POLICY_PRESET`, etc.

### 4. Policy Presets

Implement three predefined security profiles in `file:lib/sandbox_policy.sh`:

**Paranoid Preset:**
- Network: none
- Filesystem: read-only root, writable `/workspace/output` only
- Resources: 1GB memory, 1 CPU, 5GB disk
- Duration: 30 minutes max
- Use case: Untrusted code, maximum security

**Standard Preset (Default):**
- Network: restricted (allowlist: Claude API, npm, pip, GitHub)
- Filesystem: writable `/workspace`, protected `PROMPT.md` and `@fix_plan.md`
- Resources: 4GB memory, 2 CPUs, 10GB disk
- Duration: 2 hours max
- Use case: Normal development, balanced security

**Permissive Preset:**
- Network: open (full access)
- Filesystem: full access
- Resources: 8GB memory, 4 CPUs, 20GB disk
- Duration: no limit
- Use case: Development/debugging, minimal restrictions

**Function:**
```bash
apply_policy_preset() {
    local preset=$1
    case $preset in
        paranoid) apply_paranoid_preset ;;
        standard) apply_standard_preset ;;
        permissive) apply_permissive_preset ;;
    esac
}
```

### 5. Network Policy Enforcement

Create network policy enforcement adapters:

**Docker Enforcement (`file:lib/sandbox_docker.sh`):**
- `none` mode: `--network none` flag
- `restricted` mode: Custom Docker network with iptables rules or DNS filtering
- `open` mode: `--network bridge` (default)
- Allowlist/denylist: Use Docker DNS configuration or iptables rules

**E2B Enforcement (`file:lib/sandbox_e2b.sh`):**
- Use E2B SDK network configuration options
- May have different enforcement mechanisms than Docker
- Consult E2B documentation for network isolation capabilities

**Implementation:**
```bash
apply_network_policy_docker() {
    local mode=$1
    case $mode in
        none)
            DOCKER_NETWORK_FLAGS="--network none"
            ;;
        restricted)
            # Create custom network with DNS filtering
            setup_restricted_network_docker
            DOCKER_NETWORK_FLAGS="--network ralph-restricted"
            ;;
        open)
            DOCKER_NETWORK_FLAGS="--network bridge"
            ;;
    esac
}
```

### 6. Filesystem Policy Enforcement

Implement filesystem access controls:

**Docker Enforcement:**
- Read-only root: `--read-only` flag
- Writable paths: `--tmpfs` or volume mounts with `rw` flag
- Protected files: Mount as read-only volumes
- Example: `docker run --read-only -v /workspace/output:/workspace/output:rw`

**E2B Enforcement:**
- Use E2B filesystem configuration
- May use different mechanisms (check E2B SDK)

**Implementation:**
```bash
apply_filesystem_policy_docker() {
    local read_only_root=$1
    local writable_paths=$2
    local protected_files=$3
    
    if [[ "$read_only_root" == "true" ]]; then
        DOCKER_FS_FLAGS="--read-only"
    fi
    
    # Add writable mounts
    for path in ${writable_paths//,/ }; do
        DOCKER_FS_FLAGS="$DOCKER_FS_FLAGS -v $path:$path:rw"
    done
    
    # Add protected files as read-only mounts
    for file in ${protected_files//,/ }; do
        DOCKER_FS_FLAGS="$DOCKER_FS_FLAGS -v $file:$file:ro"
    done
}
```

### 7. Resource Limit Enforcement

Implement resource constraints:

**Docker Enforcement:**
- Memory: `--memory 4g` flag
- CPU: `--cpus 2` flag
- Disk: Docker storage driver limits or volume size limits
- Duration: Implement timeout wrapper around Docker execution

**E2B Enforcement:**
- Use E2B SDK resource configuration
- Cost limits: Track E2B API usage and halt when limit reached

**Implementation:**
```bash
apply_resource_limits_docker() {
    local memory=$1
    local cpus=$2
    local disk=$3
    
    DOCKER_RESOURCE_FLAGS="--memory $memory --cpus $cpus"
    
    # Disk limits via storage driver (requires Docker configuration)
    if [[ -n "$disk" ]]; then
        DOCKER_RESOURCE_FLAGS="$DOCKER_RESOURCE_FLAGS --storage-opt size=$disk"
    fi
}

enforce_duration_limit() {
    local max_duration=$1  # e.g., "2h"
    local timeout_seconds=$(parse_duration_to_seconds "$max_duration")
    
    # Use timeout command to enforce
    timeout "$timeout_seconds" docker run ...
}
```

### 8. Secret Management

Implement secure secret injection:

**Preferred Method: Mounted Files**
- Store secrets in `~/.ralph/secrets/` directory
- Mount as read-only files in sandbox: `/run/secrets/ANTHROPIC_API_KEY`
- Never log or sync secrets

**Docker Implementation:**
```bash
inject_secrets_docker() {
    local secrets_file=$1
    local secret_names=$2
    
    # Mount secrets directory
    DOCKER_SECRET_FLAGS="-v ~/.ralph/secrets:/run/secrets:ro"
    
    # Set environment variables pointing to secret files
    for secret in ${secret_names//,/ }; do
        DOCKER_SECRET_FLAGS="$DOCKER_SECRET_FLAGS -e ${secret}_FILE=/run/secrets/$secret"
    done
}
```

**Secret Masking:**
Add to `file:lib/response_analyzer.sh`:
```bash
mask_secrets_in_output() {
    local output=$1
    # Replace known secret patterns with [REDACTED]
    output=$(echo "$output" | sed 's/sk-ant-[a-zA-Z0-9-]*/[REDACTED]/g')
    echo "$output"
}
```

### 9. Policy Validation

Implement policy validation before sandbox start:

**Validation Checks:**
- Network allowlist/denylist conflicts
- Resource limits are valid (memory > 0, cpus > 0)
- Duration formats are correct (e.g., "2h", "30m")
- Secret files exist and are readable
- Writable paths don't conflict with protected files

**Implementation in `file:lib/sandbox_policy.sh`:**
```bash
validate_policy() {
    local errors=()
    
    # Validate network policy
    if [[ "$SANDBOX_POLICY_NETWORK_MODE" == "restricted" ]]; then
        if [[ -z "${SANDBOX_POLICY_NETWORK_ALLOW[@]}" ]]; then
            errors+=("Restricted network mode requires allowlist")
        fi
    fi
    
    # Validate resource limits
    if ! validate_memory_format "$SANDBOX_POLICY_MEMORY"; then
        errors+=("Invalid memory format: $SANDBOX_POLICY_MEMORY")
    fi
    
    # Validate duration
    if ! validate_duration_format "$SANDBOX_POLICY_MAX_DURATION"; then
        errors+=("Invalid duration format: $SANDBOX_POLICY_MAX_DURATION")
    fi
    
    # Report errors
    if [[ ${#errors[@]} -gt 0 ]]; then
        log_status "ERROR" "Policy validation failed:"
        for error in "${errors[@]}"; do
            log_status "ERROR" "  - $error"
        done
        return 1
    fi
    
    return 0
}
```

### 10. Sandbox Adapter Architecture

Create sandbox-specific adapters:

**File Structure:**
- `file:lib/sandbox_policy.sh` - Policy management (shared)
- `file:lib/sandbox_docker.sh` - Docker-specific enforcement
- `file:lib/sandbox_e2b.sh` - E2B-specific enforcement
- `file:lib/sandbox_none.sh` - No-op adapter for host execution

**Adapter Interface:**
Each adapter implements:
- `init_sandbox_TYPE()` - Initialize sandbox
- `apply_network_policy_TYPE()` - Enforce network policy
- `apply_filesystem_policy_TYPE()` - Enforce filesystem policy
- `apply_resource_limits_TYPE()` - Enforce resource limits
- `inject_secrets_TYPE()` - Inject secrets
- `execute_in_sandbox_TYPE()` - Execute command in sandbox
- `cleanup_sandbox_TYPE()` - Cleanup sandbox resources

**Dynamic Loading:**
```bash
# In ralph_loop.sh
source "$SCRIPT_DIR/lib/sandbox_policy.sh"

if [[ "$SANDBOX_TYPE" == "docker" ]]; then
    source "$SCRIPT_DIR/lib/sandbox_docker.sh"
elif [[ "$SANDBOX_TYPE" == "e2b" ]]; then
    source "$SCRIPT_DIR/lib/sandbox_e2b.sh"
else
    source "$SCRIPT_DIR/lib/sandbox_none.sh"
fi
```

### 11. Integration with Main Loop

Modify `file:ralph_loop.sh` to integrate sandbox policies:

**Initialization (before main loop):**
```bash
# Load configuration files
load_config

# Initialize sandbox policy
init_sandbox_policy

# Apply policy preset if specified
if [[ -n "$SANDBOX_POLICY_PRESET" ]]; then
    apply_policy_preset "$SANDBOX_POLICY_PRESET"
fi

# Validate policy
if ! validate_policy; then
    exit 1
fi

# Initialize sandbox
init_sandbox_"$SANDBOX_TYPE"
```

**Execution (in main loop):**
Replace direct Claude Code execution with sandbox execution:
```bash
# Old: execute_claude_code
# New: execute_in_sandbox_"$SANDBOX_TYPE" execute_claude_code
```

**Cleanup (on exit):**
```bash
cleanup() {
    # Existing cleanup...
    
    # Cleanup sandbox
    cleanup_sandbox_"$SANDBOX_TYPE"
}
```

### 12. Audit Logging

Add security audit logging to `file:lib/sandbox_policy.sh`:

**Log Events:**
- Policy initialization and validation
- Network policy violations (if detectable)
- Resource limit breaches
- Secret access attempts
- Sandbox start/stop events

**Implementation:**
```bash
audit_log() {
    local event=$1
    local details=$2
    local timestamp=$(date -Iseconds)
    
    echo "{\"timestamp\":\"$timestamp\",\"event\":\"$event\",\"details\":\"$details\"}" \
        >> "$LOG_DIR/security_audit.jsonl"
}

# Usage
audit_log "sandbox_start" "type=docker,policy=standard,network=restricted"
audit_log "policy_violation" "attempted_network_access=blocked.example.com"
```

### 13. Testing Strategy

Create comprehensive test suite:

**Unit Tests (`file:tests/unit/test_sandbox_policy.bats`):**
- Policy loading from config files
- Policy validation logic
- Policy preset application
- Secret masking functions
- Duration/memory format parsing

**Integration Tests (`file:tests/integration/test_sandbox_docker.bats`):**
- Docker sandbox initialization
- Network policy enforcement
- Filesystem policy enforcement
- Resource limit enforcement
- Secret injection

**Integration Tests (`file:tests/integration/test_sandbox_e2b.bats`):**
- E2B sandbox initialization
- E2B-specific policy enforcement
- Cost limit tracking

**Edge Case Tests:**
- Invalid policy configurations
- Conflicting policies
- Missing dependencies (Docker not installed)
- Secret file permissions
- Resource exhaustion scenarios

### 14. Documentation

Update documentation files:

**`file:README.md`:**
- Add "Sandbox Execution" section
- Document CLI flags for sandbox policies
- Provide examples of common configurations
- Security best practices

**Create `file:docs/SANDBOX_SECURITY.md`:**
- Detailed security policy documentation
- Policy preset descriptions
- Network policy configuration guide
- Secret management best practices
- Troubleshooting guide

**Update `file:IMPLEMENTATION_PLAN.md`:**
- Add Phase 6.4 completion status
- Document test coverage for sandbox features

### 15. Backward Compatibility

Ensure backward compatibility:

**Default Behavior:**
- `SANDBOX_TYPE=none` by default (no sandbox, current behavior)
- No breaking changes to existing CLI flags
- Config files are optional

**Migration Path:**
- Users can opt-in to sandbox execution with `--sandbox docker`
- Existing projects continue to work without modification
- Gradual migration: test with sandbox, then make it default

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant ralph_loop.sh
    participant sandbox_policy.sh
    participant sandbox_docker.sh
    participant Docker
    participant Claude

    User->>ralph_loop.sh: ralph --sandbox docker --sandbox-policy standard
    ralph_loop.sh->>ralph_loop.sh: load_config() from .ralphrc
    ralph_loop.sh->>sandbox_policy.sh: init_sandbox_policy()
    sandbox_policy.sh->>sandbox_policy.sh: apply_policy_preset("standard")
    sandbox_policy.sh->>sandbox_policy.sh: validate_policy()
    sandbox_policy.sh-->>ralph_loop.sh: Policy validated
    
    ralph_loop.sh->>sandbox_docker.sh: init_sandbox_docker()
    sandbox_docker.sh->>sandbox_docker.sh: apply_network_policy_docker("restricted")
    sandbox_docker.sh->>sandbox_docker.sh: apply_filesystem_policy_docker()
    sandbox_docker.sh->>sandbox_docker.sh: apply_resource_limits_docker()
    sandbox_docker.sh->>sandbox_docker.sh: inject_secrets_docker()
    sandbox_docker.sh->>Docker: docker run with policy flags
    Docker-->>sandbox_docker.sh: Container ready
    
    loop Main Loop
        ralph_loop.sh->>sandbox_docker.sh: execute_in_sandbox_docker(claude_command)
        sandbox_docker.sh->>Docker: docker exec
        Docker->>Claude: Execute Claude Code
        Claude-->>Docker: Response
        Docker-->>sandbox_docker.sh: Output
        sandbox_docker.sh->>sandbox_policy.sh: mask_secrets_in_output()
        sandbox_docker.sh-->>ralph_loop.sh: Sanitized output
        ralph_loop.sh->>sandbox_policy.sh: audit_log("execution_complete")
    end
    
    ralph_loop.sh->>sandbox_docker.sh: cleanup_sandbox_docker()
    sandbox_docker.sh->>Docker: docker stop & rm
    Docker-->>sandbox_docker.sh: Cleanup complete
```

## Policy Configuration Example

```yaml
# ~/.ralph/config.yaml
sandbox:
  type: docker
  
  security:
    # Network policy
    network:
      mode: restricted
      allow:
        - api.anthropic.com
        - registry.npmjs.org
        - pypi.org
        - files.pythonhosted.org
        - github.com
      deny:
        - "*.internal.company.com"
        - "*.local"
    
    # Filesystem policy
    filesystem:
      readOnlyRoot: true
      writable:
        - /workspace/output
        - /workspace/logs
        - /workspace/.ralph_session
      protected:
        - PROMPT.md
        - "@fix_plan.md"
        - specs/
    
    # Resource limits
    resources:
      memory: 4g
      cpus: 2
      disk: 10g
      maxDuration: 2h
      loopTimeout: 15m
    
    # Secret management
    secrets:
      source: file
      path: ~/.ralph/secrets
      inject:
        - ANTHROPIC_API_KEY
        - GITHUB_TOKEN
      
    # Audit logging
    audit:
      enabled: true
      logFile: logs/security_audit.jsonl
```

## Dependencies

**Required:**
- Docker (for Docker sandbox) - `docker --version`
- E2B SDK (for E2B sandbox) - `npm install -g @e2b/sdk`
- `yq` (for YAML parsing) - `brew install yq` or `apt-get install yq`
- `jq` (already required by Ralph)

**Optional:**
- `iptables` (for advanced Docker network filtering)
- Secret managers: AWS Secrets Manager CLI, 1Password CLI

## Risk Mitigation

**Security Risks:**
- **Secret leakage**: Mitigated by secret masking, read-only mounts, and audit logging
- **Network exfiltration**: Mitigated by network policies and allowlist/denylist
- **Resource exhaustion**: Mitigated by resource limits and duration timeouts

**Implementation Risks:**
- **Docker not available**: Graceful fallback to host execution with warning
- **E2B API changes**: Version pinning and adapter pattern for isolation
- **Policy conflicts**: Validation before sandbox start prevents runtime errors

**Backward Compatibility:**
- Default `SANDBOX_TYPE=none` ensures existing workflows continue unchanged
- All sandbox features are opt-in via CLI flags or config files

---

Execution Information

Branch: main
Commit: d0208c4

New Plan

Observations

The Ralph codebase is a mature bash-based autonomous development loop tool (v0.9.8) with 75 passing tests and comprehensive documentation. Currently, there is no sandbox implementation - Ralph executes Claude Code directly on the host system. Phase 6.4 (Security and Resource Policies) is a lower-priority future feature (P4) that depends on Phase 6.1 (Docker sandbox), Phase 6.2 (E2B sandbox), and Phase 6.3 (File sync) being implemented first. The existing architecture uses configuration variables at the script level, CLI argument parsing with standard bash patterns, and library modules for circuit breaker and response analysis functionality.

Approach

The implementation will follow a layered security architecture where policies are defined at multiple levels (CLI flags, config files, presets) and enforced by sandbox-specific adapters. Since Ralph is bash-based, the approach will create a new lib/sandbox_policy.sh module for policy management, extend the existing CLI parser to accept sandbox-related flags, add configuration file support (.ralphrc) for persistent policies, and implement sandbox-specific enforcement adapters for Docker and E2B. The design prioritizes security by default with a "standard" policy preset, while allowing flexibility through policy customization. This approach integrates seamlessly with Ralph's existing patterns (library modules, CLI parsing, configuration variables) and maintains backward compatibility. As a P4 priority feature, implementation should be deferred until higher-priority phases (6.1, 6.2, 6.3) are complete.

Implementation Steps

1. Policy Management Infrastructure

Create file:lib/sandbox_policy.sh as the central policy management module:

Core Functions:

• init_sandbox_policy() - Initialize policy system with defaults
• load_policy_config() - Load policies from .ralphrc or ~/.ralph/config.yaml
• validate_policy() - Validate policy configuration before sandbox start
• get_policy_value() - Retrieve specific policy values
• apply_policy_preset() - Apply predefined policy presets (paranoid/standard/permissive)

Policy Data Structure:
Store policies in bash associative arrays or JSON files:

SANDBOX_POLICY_NETWORK_MODE="restricted"
SANDBOX_POLICY_NETWORK_ALLOW=("api.anthropic.com" "*.npmjs.org" "pypi.org")
SANDBOX_POLICY_NETWORK_DENY=("*.internal.corp")
SANDBOX_POLICY_MEMORY="4g"
SANDBOX_POLICY_CPUS="2"
SANDBOX_POLICY_DISK="10g"
SANDBOX_POLICY_MAX_DURATION="2h"
SANDBOX_POLICY_LOOP_TIMEOUT="15m"

2. Configuration File Support

Implement .ralphrc and ~/.ralph/config.yaml support:

File Locations (Priority Order):

1. Project-level: ./.ralphrc (highest priority)
2. User-level: ~/.ralph/config.yaml
3. Defaults: Built into lib/sandbox_policy.sh

Configuration Format:
Support both bash-style .ralphrc (for simple key=value) and YAML config.yaml (for structured policies). Use yq if available, fallback to custom bash parser for YAML. Note: Configuration file support is already partially implemented in Ralph's existing codebase (see load_config() in Week 5 of IMPLEMENTATION_PLAN.md), so this step should integrate with existing patterns.

Example .ralphrc:

# Sandbox security policies
SANDBOX_TYPE=docker
SANDBOX_POLICY_PRESET=standard
SANDBOX_NETWORK_MODE=restricted
SANDBOX_MEMORY=4g
SANDBOX_CPUS=2
SANDBOX_MAX_DURATION=2h

Example ~/.ralph/config.yaml:

sandbox:
  type: docker
  security:
    network:
      mode: restricted
      allow:
        - api.anthropic.com
        - "*.npmjs.org"
      deny:
        - "*.internal.corp"
    resources:
      memory: 4g
      cpus: 2
      disk: 10g
      maxDuration: 2h
      loopTimeout: 15m
    secrets:
      source: file
      path: ~/.ralph/secrets

Implementation:

• Add load_config() function in file:ralph_loop.sh (call before main loop)
• Parse YAML using yq if available, fallback to bash parsing for .ralphrc
• Merge configs: defaults → user config → project config → CLI flags

3. CLI Flag Extensions

Extend file:ralph_loop.sh CLI parser to accept sandbox policy flags:

New Flags:

--sandbox TYPE              # docker | e2b | none (default: none)
--sandbox-policy PRESET     # paranoid | standard | permissive
--network MODE              # none | restricted | open
--network-allow HOSTS       # Comma-separated allowlist
--network-deny HOSTS        # Comma-separated denylist
--memory SIZE               # e.g., 4g, 8g
--cpus NUM                  # e.g., 2, 4
--disk SIZE                 # e.g., 10g, 20g
--max-duration TIME         # e.g., 2h, 30m
--loop-timeout TIME         # e.g., 15m, 30m
--max-cost AMOUNT           # e.g., 10.00 (for E2B)
--secrets-file PATH         # Path to secrets file
--secret NAME               # Inject specific secret
--read-only-root            # Enable read-only root filesystem
--writable PATHS            # Comma-separated writable paths
--protect FILES             # Comma-separated protected files

Integration:
Add cases to the existing while [[ $# -gt 0 ]] loop in file:ralph_loop.sh (around line 1141). Store values in global variables like SANDBOX_TYPE, SANDBOX_POLICY_PRESET, etc.

4. Policy Presets

Implement three predefined security profiles in file:lib/sandbox_policy.sh:

Paranoid Preset:

• Network: none
• Filesystem: read-only root, writable /workspace/output only
• Resources: 1GB memory, 1 CPU, 5GB disk
• Duration: 30 minutes max
• Use case: Untrusted code, maximum security

Standard Preset (Default):

• Network: restricted (allowlist: Claude API, npm, pip, GitHub)
• Filesystem: writable /workspace, protected PROMPT.md and @fix_plan.md
• Resources: 4GB memory, 2 CPUs, 10GB disk
• Duration: 2 hours max
• Use case: Normal development, balanced security

Permissive Preset:

• Network: open (full access)
• Filesystem: full access
• Resources: 8GB memory, 4 CPUs, 20GB disk
• Duration: no limit
• Use case: Development/debugging, minimal restrictions

Function:

apply_policy_preset() {
    local preset=$1
    case $preset in
        paranoid) apply_paranoid_preset ;;
        standard) apply_standard_preset ;;
        permissive) apply_permissive_preset ;;
    esac
}

5. Network Policy Enforcement

Create network policy enforcement adapters:

Docker Enforcement (file:lib/sandbox_docker.sh):

• none mode: --network none flag
• restricted mode: Custom Docker network with iptables rules or DNS filtering
• open mode: --network bridge (default)
• Allowlist/denylist: Use Docker DNS configuration or iptables rules

E2B Enforcement (file:lib/sandbox_e2b.sh):

• Use E2B SDK network configuration options
• May have different enforcement mechanisms than Docker
• Consult E2B documentation for network isolation capabilities

Implementation:

apply_network_policy_docker() {
    local mode=$1
    case $mode in
        none)
            DOCKER_NETWORK_FLAGS="--network none"
            ;;
        restricted)
            # Create custom network with DNS filtering
            setup_restricted_network_docker
            DOCKER_NETWORK_FLAGS="--network ralph-restricted"
            ;;
        open)
            DOCKER_NETWORK_FLAGS="--network bridge"
            ;;
    esac
}

6. Filesystem Policy Enforcement

Implement filesystem access controls:

Docker Enforcement:

• Read-only root: --read-only flag
• Writable paths: --tmpfs or volume mounts with rw flag
• Protected files: Mount as read-only volumes
• Example: docker run --read-only -v /workspace/output:/workspace/output:rw

E2B Enforcement:

• Use E2B filesystem configuration
• May use different mechanisms (check E2B SDK)

Implementation:

apply_filesystem_policy_docker() {
    local read_only_root=$1
    local writable_paths=$2
    local protected_files=$3
    
    if [[ "$read_only_root" == "true" ]]; then
        DOCKER_FS_FLAGS="--read-only"
    fi
    
    # Add writable mounts
    for path in ${writable_paths//,/ }; do
        DOCKER_FS_FLAGS="$DOCKER_FS_FLAGS -v $path:$path:rw"
    done
    
    # Add protected files as read-only mounts
    for file in ${protected_files//,/ }; do
        DOCKER_FS_FLAGS="$DOCKER_FS_FLAGS -v $file:$file:ro"
    done
}

7. Resource Limit Enforcement

Implement resource constraints:

Docker Enforcement:

• Memory: --memory 4g flag
• CPU: --cpus 2 flag
• Disk: Docker storage driver limits or volume size limits
• Duration: Implement timeout wrapper around Docker execution

E2B Enforcement:

• Use E2B SDK resource configuration
• Cost limits: Track E2B API usage and halt when limit reached

Implementation:

apply_resource_limits_docker() {
    local memory=$1
    local cpus=$2
    local disk=$3
    
    DOCKER_RESOURCE_FLAGS="--memory $memory --cpus $cpus"
    
    # Disk limits via storage driver (requires Docker configuration)
    if [[ -n "$disk" ]]; then
        DOCKER_RESOURCE_FLAGS="$DOCKER_RESOURCE_FLAGS --storage-opt size=$disk"
    fi
}

enforce_duration_limit() {
    local max_duration=$1  # e.g., "2h"
    local timeout_seconds=$(parse_duration_to_seconds "$max_duration")
    
    # Use timeout command to enforce
    timeout "$timeout_seconds" docker run ...
}

8. Secret Management

Implement secure secret injection:

Preferred Method: Mounted Files

• Store secrets in ~/.ralph/secrets/ directory
• Mount as read-only files in sandbox: /run/secrets/ANTHROPIC_API_KEY
• Never log or sync secrets

Docker Implementation:

inject_secrets_docker() {
    local secrets_file=$1
    local secret_names=$2
    
    # Mount secrets directory
    DOCKER_SECRET_FLAGS="-v ~/.ralph/secrets:/run/secrets:ro"
    
    # Set environment variables pointing to secret files
    for secret in ${secret_names//,/ }; do
        DOCKER_SECRET_FLAGS="$DOCKER_SECRET_FLAGS -e ${secret}_FILE=/run/secrets/$secret"
    done
}

Secret Masking:
Add to file:lib/response_analyzer.sh:

mask_secrets_in_output() {
    local output=$1
    # Replace known secret patterns with [REDACTED]
    output=$(echo "$output" | sed 's/sk-ant-[a-zA-Z0-9-]*/[REDACTED]/g')
    echo "$output"
}

9. Policy Validation

Implement policy validation before sandbox start:

Validation Checks:

• Network allowlist/denylist conflicts
• Resource limits are valid (memory > 0, cpus > 0)
• Duration formats are correct (e.g., "2h", "30m")
• Secret files exist and are readable
• Writable paths don't conflict with protected files

Implementation in file:lib/sandbox_policy.sh:

validate_policy() {
    local errors=()
    
    # Validate network policy
    if [[ "$SANDBOX_POLICY_NETWORK_MODE" == "restricted" ]]; then
        if [[ -z "${SANDBOX_POLICY_NETWORK_ALLOW[@]}" ]]; then
            errors+=("Restricted network mode requires allowlist")
        fi
    fi
    
    # Validate resource limits
    if ! validate_memory_format "$SANDBOX_POLICY_MEMORY"; then
        errors+=("Invalid memory format: $SANDBOX_POLICY_MEMORY")
    fi
    
    # Validate duration
    if ! validate_duration_format "$SANDBOX_POLICY_MAX_DURATION"; then
        errors+=("Invalid duration format: $SANDBOX_POLICY_MAX_DURATION")
    fi
    
    # Report errors
    if [[ ${#errors[@]} -gt 0 ]]; then
        log_status "ERROR" "Policy validation failed:"
        for error in "${errors[@]}"; do
            log_status "ERROR" "  - $error"
        done
        return 1
    fi
    
    return 0
}

10. Sandbox Adapter Architecture

Create sandbox-specific adapters:

File Structure:

• file:lib/sandbox_policy.sh - Policy management (shared)
• file:lib/sandbox_docker.sh - Docker-specific enforcement (depends on Phase 6.1)
• file:lib/sandbox_e2b.sh - E2B-specific enforcement (depends on Phase 6.2)
• file:lib/sandbox_none.sh - No-op adapter for host execution

Adapter Interface:
Each adapter implements:

• init_sandbox_TYPE() - Initialize sandbox
• apply_network_policy_TYPE() - Enforce network policy
• apply_filesystem_policy_TYPE() - Enforce filesystem policy
• apply_resource_limits_TYPE() - Enforce resource limits
• inject_secrets_TYPE() - Inject secrets
• execute_in_sandbox_TYPE() - Execute command in sandbox
• cleanup_sandbox_TYPE() - Cleanup sandbox resources

Dynamic Loading:

# In ralph_loop.sh
source "$SCRIPT_DIR/lib/sandbox_policy.sh"

if [[ "$SANDBOX_TYPE" == "docker" ]]; then
    source "$SCRIPT_DIR/lib/sandbox_docker.sh"
elif [[ "$SANDBOX_TYPE" == "e2b" ]]; then
    source "$SCRIPT_DIR/lib/sandbox_e2b.sh"
else
    source "$SCRIPT_DIR/lib/sandbox_none.sh"
fi

Implementation Note: Docker and E2B adapters should be implemented only after their respective sandbox implementations (Phase 6.1 and 6.2) are complete.

11. Integration with Main Loop

Modify file:ralph_loop.sh to integrate sandbox policies:

Initialization (before main loop):

# Load configuration files
load_config

# Initialize sandbox policy
init_sandbox_policy

# Apply policy preset if specified
if [[ -n "$SANDBOX_POLICY_PRESET" ]]; then
    apply_policy_preset "$SANDBOX_POLICY_PRESET"
fi

# Validate policy
if ! validate_policy; then
    exit 1
fi

# Initialize sandbox
init_sandbox_"$SANDBOX_TYPE"

Execution (in main loop):
Replace direct Claude Code execution with sandbox execution:

# Old: execute_claude_code
# New: execute_in_sandbox_"$SANDBOX_TYPE" execute_claude_code

Cleanup (on exit):

cleanup() {
    # Existing cleanup...
    
    # Cleanup sandbox
    cleanup_sandbox_"$SANDBOX_TYPE"
}

12. Audit Logging

Add security audit logging to file:lib/sandbox_policy.sh:

Log Events:

• Policy initialization and validation
• Network policy violations (if detectable)
• Resource limit breaches
• Secret access attempts
• Sandbox start/stop events

Implementation:

audit_log() {
    local event=$1
    local details=$2
    local timestamp=$(date -Iseconds)
    
    echo "{\"timestamp\":\"$timestamp\",\"event\":\"$event\",\"details\":\"$details\"}" \
        >> "$LOG_DIR/security_audit.jsonl"
}

# Usage
audit_log "sandbox_start" "type=docker,policy=standard,network=restricted"
audit_log "policy_violation" "attempted_network_access=blocked.example.com"

13. Testing Strategy

Create comprehensive test suite:

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

• Policy loading from config files
• Policy validation logic
• Policy preset application
• Secret masking functions
• Duration/memory format parsing
• Estimated: 15-20 tests

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

• Docker sandbox initialization
• Network policy enforcement
• Filesystem policy enforcement
• Resource limit enforcement
• Secret injection
• Estimated: 20-25 tests (depends on Phase 6.1 completion)

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

• E2B sandbox initialization
• E2B-specific policy enforcement
• Cost limit tracking
• Estimated: 15-20 tests (depends on Phase 6.2 completion)

Edge Case Tests:

• Invalid policy configurations
• Conflicting policies
• Missing dependencies (Docker not installed)
• Secret file permissions
• Resource exhaustion scenarios
• Estimated: 10-15 tests

Test Sequencing: Unit tests for policy management can be written immediately. Integration tests for Docker and E2B enforcement should be deferred until their respective sandbox implementations are complete.

14. Documentation

Update documentation files:

file:README.md:

• Add "Sandbox Execution" section
• Document CLI flags for sandbox policies
• Provide examples of common configurations
• Security best practices

Create file:docs/SANDBOX_SECURITY.md:

• Detailed security policy documentation
• Policy preset descriptions
• Network policy configuration guide
• Secret management best practices
• Troubleshooting guide

Update file:IMPLEMENTATION_PLAN.md:

• Add Phase 6.4 completion status
• Document test coverage for sandbox features

15. Backward Compatibility

Ensure backward compatibility:

Default Behavior:

• SANDBOX_TYPE=none by default (no sandbox, current behavior)
• No breaking changes to existing CLI flags
• Config files are optional

Migration Path:

• Users can opt-in to sandbox execution with --sandbox docker
• Existing projects continue to work without modification
• Gradual migration: test with sandbox, then make it default

Architecture Diagram

sequenceDiagram
    participant User
    participant ralph_loop.sh
    participant sandbox_policy.sh
    participant sandbox_docker.sh
    participant Docker
    participant Claude

    User->>ralph_loop.sh: ralph --sandbox docker --sandbox-policy standard
    ralph_loop.sh->>ralph_loop.sh: load_config() from .ralphrc
    ralph_loop.sh->>sandbox_policy.sh: init_sandbox_policy()
    sandbox_policy.sh->>sandbox_policy.sh: apply_policy_preset("standard")
    sandbox_policy.sh->>sandbox_policy.sh: validate_policy()
    sandbox_policy.sh-->>ralph_loop.sh: Policy validated
    
    ralph_loop.sh->>sandbox_docker.sh: init_sandbox_docker()
    sandbox_docker.sh->>sandbox_docker.sh: apply_network_policy_docker("restricted")
    sandbox_docker.sh->>sandbox_docker.sh: apply_filesystem_policy_docker()
    sandbox_docker.sh->>sandbox_docker.sh: apply_resource_limits_docker()
    sandbox_docker.sh->>sandbox_docker.sh: inject_secrets_docker()
    sandbox_docker.sh->>Docker: docker run with policy flags
    Docker-->>sandbox_docker.sh: Container ready
    
    loop Main Loop
        ralph_loop.sh->>sandbox_docker.sh: execute_in_sandbox_docker(claude_command)
        sandbox_docker.sh->>Docker: docker exec
        Docker->>Claude: Execute Claude Code
        Claude-->>Docker: Response
        Docker-->>sandbox_docker.sh: Output
        sandbox_docker.sh->>sandbox_policy.sh: mask_secrets_in_output()
        sandbox_docker.sh-->>ralph_loop.sh: Sanitized output
        ralph_loop.sh->>sandbox_policy.sh: audit_log("execution_complete")
    end
    
    ralph_loop.sh->>sandbox_docker.sh: cleanup_sandbox_docker()
    sandbox_docker.sh->>Docker: docker stop & rm
    Docker-->>sandbox_docker.sh: Cleanup complete

Loading

Policy Configuration Example

# ~/.ralph/config.yaml
sandbox:
  type: docker
  
  security:
    # Network policy
    network:
      mode: restricted
      allow:
        - api.anthropic.com
        - registry.npmjs.org
        - pypi.org
        - files.pythonhosted.org
        - github.com
      deny:
        - "*.internal.company.com"
        - "*.local"
    
    # Filesystem policy
    filesystem:
      readOnlyRoot: true
      writable:
        - /workspace/output
        - /workspace/logs
        - /workspace/.ralph_session
      protected:
        - PROMPT.md
        - "@fix_plan.md"
        - specs/
    
    # Resource limits
    resources:
      memory: 4g
      cpus: 2
      disk: 10g
      maxDuration: 2h
      loopTimeout: 15m
    
    # Secret management
    secrets:
      source: file
      path: ~/.ralph/secrets
      inject:
        - ANTHROPIC_API_KEY
        - GITHUB_TOKEN
      
    # Audit logging
    audit:
      enabled: true
      logFile: logs/security_audit.jsonl

Dependencies

Required:

• Docker (for Docker sandbox) - docker --version (Phase 6.1 prerequisite)
• E2B SDK (for E2B sandbox) - npm install -g @e2b/sdk (Phase 6.2 prerequisite)
• yq (for YAML parsing) - brew install yq or apt-get install yq
• jq (already required by Ralph)

Optional:

• iptables (for advanced Docker network filtering)
• Secret managers: AWS Secrets Manager CLI, 1Password CLI

Phase Dependencies:

• Phase 6.1 (Docker sandbox) must be complete before Docker policy enforcement can be tested
• Phase 6.2 (E2B sandbox) must be complete before E2B policy enforcement can be tested
• Phase 6.3 (File sync) should be complete before secret exclusion policies are finalized

Risk Mitigation

Security Risks:

• Secret leakage: Mitigated by secret masking, read-only mounts, and audit logging
• Network exfiltration: Mitigated by network policies and allowlist/denylist
• Resource exhaustion: Mitigated by resource limits and duration timeouts

Implementation Risks:

• Docker not available: Graceful fallback to host execution with warning
• E2B API changes: Version pinning and adapter pattern for isolation
• Policy conflicts: Validation before sandbox start prevents runtime errors
• Dependency on earlier phases: As a P4 feature, this work should not block higher-priority phases (6.1, 6.2, 6.3)

Backward Compatibility:

• Default SANDBOX_TYPE=none ensures existing workflows continue unchanged
• All sandbox features are opt-in via CLI flags or config files
• Policy management infrastructure can be implemented independently of sandbox implementations

Phasing Strategy:

• Implement policy management infrastructure (steps 1-9) early for code organization
• Defer sandbox-specific enforcement (steps 10-12) until Phase 6.1 and 6.2 are complete
• Write unit tests for policy management immediately
• Write integration tests for enforcement after sandbox implementations are available

Import In IDE

🤖 Prompt for AI Agents

## Observations

The Ralph codebase is a mature bash-based autonomous development loop tool (v0.9.8) with 75 passing tests and comprehensive documentation. Currently, there is **no sandbox implementation** - Ralph executes Claude Code directly on the host system. Phase 6.4 (Security and Resource Policies) is a lower-priority future feature (P4) that depends on Phase 6.1 (Docker sandbox), Phase 6.2 (E2B sandbox), and Phase 6.3 (File sync) being implemented first. The existing architecture uses configuration variables at the script level, CLI argument parsing with standard bash patterns, and library modules for circuit breaker and response analysis functionality.

## Approach

The implementation will follow a **layered security architecture** where policies are defined at multiple levels (CLI flags, config files, presets) and enforced by sandbox-specific adapters. Since Ralph is bash-based, the approach will create a new `lib/sandbox_policy.sh` module for policy management, extend the existing CLI parser to accept sandbox-related flags, add configuration file support (`.ralphrc`) for persistent policies, and implement sandbox-specific enforcement adapters for Docker and E2B. The design prioritizes **security by default** with a "standard" policy preset, while allowing flexibility through policy customization. This approach integrates seamlessly with Ralph's existing patterns (library modules, CLI parsing, configuration variables) and maintains backward compatibility. As a P4 priority feature, implementation should be deferred until higher-priority phases (6.1, 6.2, 6.3) are complete.

## Implementation Steps

### 1. Policy Management Infrastructure

Create `file:lib/sandbox_policy.sh` as the central policy management module:

**Core Functions:**
- `init_sandbox_policy()` - Initialize policy system with defaults
- `load_policy_config()` - Load policies from `.ralphrc` or `~/.ralph/config.yaml`
- `validate_policy()` - Validate policy configuration before sandbox start
- `get_policy_value()` - Retrieve specific policy values
- `apply_policy_preset()` - Apply predefined policy presets (paranoid/standard/permissive)

**Policy Data Structure:**
Store policies in bash associative arrays or JSON files:
```
SANDBOX_POLICY_NETWORK_MODE="restricted"
SANDBOX_POLICY_NETWORK_ALLOW=("api.anthropic.com" "*.npmjs.org" "pypi.org")
SANDBOX_POLICY_NETWORK_DENY=("*.internal.corp")
SANDBOX_POLICY_MEMORY="4g"
SANDBOX_POLICY_CPUS="2"
SANDBOX_POLICY_DISK="10g"
SANDBOX_POLICY_MAX_DURATION="2h"
SANDBOX_POLICY_LOOP_TIMEOUT="15m"
```

### 2. Configuration File Support

Implement `.ralphrc` and `~/.ralph/config.yaml` support:

**File Locations (Priority Order):**
1. Project-level: `./.ralphrc` (highest priority)
2. User-level: `~/.ralph/config.yaml`
3. Defaults: Built into `lib/sandbox_policy.sh`

**Configuration Format:**
Support both bash-style `.ralphrc` (for simple key=value) and YAML `config.yaml` (for structured policies). Use `yq` if available, fallback to custom bash parser for YAML. Note: Configuration file support is already partially implemented in Ralph's existing codebase (see `load_config()` in Week 5 of IMPLEMENTATION_PLAN.md), so this step should integrate with existing patterns.

**Example `.ralphrc`:**
```bash
# Sandbox security policies
SANDBOX_TYPE=docker
SANDBOX_POLICY_PRESET=standard
SANDBOX_NETWORK_MODE=restricted
SANDBOX_MEMORY=4g
SANDBOX_CPUS=2
SANDBOX_MAX_DURATION=2h
```

**Example `~/.ralph/config.yaml`:**
```yaml
sandbox:
  type: docker
  security:
    network:
      mode: restricted
      allow:
        - api.anthropic.com
        - "*.npmjs.org"
      deny:
        - "*.internal.corp"
    resources:
      memory: 4g
      cpus: 2
      disk: 10g
      maxDuration: 2h
      loopTimeout: 15m
    secrets:
      source: file
      path: ~/.ralph/secrets
```

**Implementation:**
- Add `load_config()` function in `file:ralph_loop.sh` (call before main loop)
- Parse YAML using `yq` if available, fallback to bash parsing for `.ralphrc`
- Merge configs: defaults → user config → project config → CLI flags

### 3. CLI Flag Extensions

Extend `file:ralph_loop.sh` CLI parser to accept sandbox policy flags:

**New Flags:**
```bash
--sandbox TYPE              # docker | e2b | none (default: none)
--sandbox-policy PRESET     # paranoid | standard | permissive
--network MODE              # none | restricted | open
--network-allow HOSTS       # Comma-separated allowlist
--network-deny HOSTS        # Comma-separated denylist
--memory SIZE               # e.g., 4g, 8g
--cpus NUM                  # e.g., 2, 4
--disk SIZE                 # e.g., 10g, 20g
--max-duration TIME         # e.g., 2h, 30m
--loop-timeout TIME         # e.g., 15m, 30m
--max-cost AMOUNT           # e.g., 10.00 (for E2B)
--secrets-file PATH         # Path to secrets file
--secret NAME               # Inject specific secret
--read-only-root            # Enable read-only root filesystem
--writable PATHS            # Comma-separated writable paths
--protect FILES             # Comma-separated protected files
```

**Integration:**
Add cases to the existing `while [[ $# -gt 0 ]]` loop in `file:ralph_loop.sh` (around line 1141). Store values in global variables like `SANDBOX_TYPE`, `SANDBOX_POLICY_PRESET`, etc.

### 4. Policy Presets

Implement three predefined security profiles in `file:lib/sandbox_policy.sh`:

**Paranoid Preset:**
- Network: none
- Filesystem: read-only root, writable `/workspace/output` only
- Resources: 1GB memory, 1 CPU, 5GB disk
- Duration: 30 minutes max
- Use case: Untrusted code, maximum security

**Standard Preset (Default):**
- Network: restricted (allowlist: Claude API, npm, pip, GitHub)
- Filesystem: writable `/workspace`, protected `PROMPT.md` and `@fix_plan.md`
- Resources: 4GB memory, 2 CPUs, 10GB disk
- Duration: 2 hours max
- Use case: Normal development, balanced security

**Permissive Preset:**
- Network: open (full access)
- Filesystem: full access
- Resources: 8GB memory, 4 CPUs, 20GB disk
- Duration: no limit
- Use case: Development/debugging, minimal restrictions

**Function:**
```bash
apply_policy_preset() {
    local preset=$1
    case $preset in
        paranoid) apply_paranoid_preset ;;
        standard) apply_standard_preset ;;
        permissive) apply_permissive_preset ;;
    esac
}
```

### 5. Network Policy Enforcement

Create network policy enforcement adapters:

**Docker Enforcement (`file:lib/sandbox_docker.sh`):**
- `none` mode: `--network none` flag
- `restricted` mode: Custom Docker network with iptables rules or DNS filtering
- `open` mode: `--network bridge` (default)
- Allowlist/denylist: Use Docker DNS configuration or iptables rules

**E2B Enforcement (`file:lib/sandbox_e2b.sh`):**
- Use E2B SDK network configuration options
- May have different enforcement mechanisms than Docker
- Consult E2B documentation for network isolation capabilities

**Implementation:**
```bash
apply_network_policy_docker() {
    local mode=$1
    case $mode in
        none)
            DOCKER_NETWORK_FLAGS="--network none"
            ;;
        restricted)
            # Create custom network with DNS filtering
            setup_restricted_network_docker
            DOCKER_NETWORK_FLAGS="--network ralph-restricted"
            ;;
        open)
            DOCKER_NETWORK_FLAGS="--network bridge"
            ;;
    esac
}
```

### 6. Filesystem Policy Enforcement

Implement filesystem access controls:

**Docker Enforcement:**
- Read-only root: `--read-only` flag
- Writable paths: `--tmpfs` or volume mounts with `rw` flag
- Protected files: Mount as read-only volumes
- Example: `docker run --read-only -v /workspace/output:/workspace/output:rw`

**E2B Enforcement:**
- Use E2B filesystem configuration
- May use different mechanisms (check E2B SDK)

**Implementation:**
```bash
apply_filesystem_policy_docker() {
    local read_only_root=$1
    local writable_paths=$2
    local protected_files=$3
    
    if [[ "$read_only_root" == "true" ]]; then
        DOCKER_FS_FLAGS="--read-only"
    fi
    
    # Add writable mounts
    for path in ${writable_paths//,/ }; do
        DOCKER_FS_FLAGS="$DOCKER_FS_FLAGS -v $path:$path:rw"
    done
    
    # Add protected files as read-only mounts
    for file in ${protected_files//,/ }; do
        DOCKER_FS_FLAGS="$DOCKER_FS_FLAGS -v $file:$file:ro"
    done
}
```

### 7. Resource Limit Enforcement

Implement resource constraints:

**Docker Enforcement:**
- Memory: `--memory 4g` flag
- CPU: `--cpus 2` flag
- Disk: Docker storage driver limits or volume size limits
- Duration: Implement timeout wrapper around Docker execution

**E2B Enforcement:**
- Use E2B SDK resource configuration
- Cost limits: Track E2B API usage and halt when limit reached

**Implementation:**
```bash
apply_resource_limits_docker() {
    local memory=$1
    local cpus=$2
    local disk=$3
    
    DOCKER_RESOURCE_FLAGS="--memory $memory --cpus $cpus"
    
    # Disk limits via storage driver (requires Docker configuration)
    if [[ -n "$disk" ]]; then
        DOCKER_RESOURCE_FLAGS="$DOCKER_RESOURCE_FLAGS --storage-opt size=$disk"
    fi
}

enforce_duration_limit() {
    local max_duration=$1  # e.g., "2h"
    local timeout_seconds=$(parse_duration_to_seconds "$max_duration")
    
    # Use timeout command to enforce
    timeout "$timeout_seconds" docker run ...
}
```

### 8. Secret Management

Implement secure secret injection:

**Preferred Method: Mounted Files**
- Store secrets in `~/.ralph/secrets/` directory
- Mount as read-only files in sandbox: `/run/secrets/ANTHROPIC_API_KEY`
- Never log or sync secrets

**Docker Implementation:**
```bash
inject_secrets_docker() {
    local secrets_file=$1
    local secret_names=$2
    
    # Mount secrets directory
    DOCKER_SECRET_FLAGS="-v ~/.ralph/secrets:/run/secrets:ro"
    
    # Set environment variables pointing to secret files
    for secret in ${secret_names//,/ }; do
        DOCKER_SECRET_FLAGS="$DOCKER_SECRET_FLAGS -e ${secret}_FILE=/run/secrets/$secret"
    done
}
```

**Secret Masking:**
Add to `file:lib/response_analyzer.sh`:
```bash
mask_secrets_in_output() {
    local output=$1
    # Replace known secret patterns with [REDACTED]
    output=$(echo "$output" | sed 's/sk-ant-[a-zA-Z0-9-]*/[REDACTED]/g')
    echo "$output"
}
```

### 9. Policy Validation

Implement policy validation before sandbox start:

**Validation Checks:**
- Network allowlist/denylist conflicts
- Resource limits are valid (memory > 0, cpus > 0)
- Duration formats are correct (e.g., "2h", "30m")
- Secret files exist and are readable
- Writable paths don't conflict with protected files

**Implementation in `file:lib/sandbox_policy.sh`:**
```bash
validate_policy() {
    local errors=()
    
    # Validate network policy
    if [[ "$SANDBOX_POLICY_NETWORK_MODE" == "restricted" ]]; then
        if [[ -z "${SANDBOX_POLICY_NETWORK_ALLOW[@]}" ]]; then
            errors+=("Restricted network mode requires allowlist")
        fi
    fi
    
    # Validate resource limits
    if ! validate_memory_format "$SANDBOX_POLICY_MEMORY"; then
        errors+=("Invalid memory format: $SANDBOX_POLICY_MEMORY")
    fi
    
    # Validate duration
    if ! validate_duration_format "$SANDBOX_POLICY_MAX_DURATION"; then
        errors+=("Invalid duration format: $SANDBOX_POLICY_MAX_DURATION")
    fi
    
    # Report errors
    if [[ ${#errors[@]} -gt 0 ]]; then
        log_status "ERROR" "Policy validation failed:"
        for error in "${errors[@]}"; do
            log_status "ERROR" "  - $error"
        done
        return 1
    fi
    
    return 0
}
```

### 10. Sandbox Adapter Architecture

Create sandbox-specific adapters:

**File Structure:**
- `file:lib/sandbox_policy.sh` - Policy management (shared)
- `file:lib/sandbox_docker.sh` - Docker-specific enforcement (depends on Phase 6.1)
- `file:lib/sandbox_e2b.sh` - E2B-specific enforcement (depends on Phase 6.2)
- `file:lib/sandbox_none.sh` - No-op adapter for host execution

**Adapter Interface:**
Each adapter implements:
- `init_sandbox_TYPE()` - Initialize sandbox
- `apply_network_policy_TYPE()` - Enforce network policy
- `apply_filesystem_policy_TYPE()` - Enforce filesystem policy
- `apply_resource_limits_TYPE()` - Enforce resource limits
- `inject_secrets_TYPE()` - Inject secrets
- `execute_in_sandbox_TYPE()` - Execute command in sandbox
- `cleanup_sandbox_TYPE()` - Cleanup sandbox resources

**Dynamic Loading:**
```bash
# In ralph_loop.sh
source "$SCRIPT_DIR/lib/sandbox_policy.sh"

if [[ "$SANDBOX_TYPE" == "docker" ]]; then
    source "$SCRIPT_DIR/lib/sandbox_docker.sh"
elif [[ "$SANDBOX_TYPE" == "e2b" ]]; then
    source "$SCRIPT_DIR/lib/sandbox_e2b.sh"
else
    source "$SCRIPT_DIR/lib/sandbox_none.sh"
fi
```

**Implementation Note:** Docker and E2B adapters should be implemented only after their respective sandbox implementations (Phase 6.1 and 6.2) are complete.

### 11. Integration with Main Loop

Modify `file:ralph_loop.sh` to integrate sandbox policies:

**Initialization (before main loop):**
```bash
# Load configuration files
load_config

# Initialize sandbox policy
init_sandbox_policy

# Apply policy preset if specified
if [[ -n "$SANDBOX_POLICY_PRESET" ]]; then
    apply_policy_preset "$SANDBOX_POLICY_PRESET"
fi

# Validate policy
if ! validate_policy; then
    exit 1
fi

# Initialize sandbox
init_sandbox_"$SANDBOX_TYPE"
```

**Execution (in main loop):**
Replace direct Claude Code execution with sandbox execution:
```bash
# Old: execute_claude_code
# New: execute_in_sandbox_"$SANDBOX_TYPE" execute_claude_code
```

**Cleanup (on exit):**
```bash
cleanup() {
    # Existing cleanup...
    
    # Cleanup sandbox
    cleanup_sandbox_"$SANDBOX_TYPE"
}
```

### 12. Audit Logging

Add security audit logging to `file:lib/sandbox_policy.sh`:

**Log Events:**
- Policy initialization and validation
- Network policy violations (if detectable)
- Resource limit breaches
- Secret access attempts
- Sandbox start/stop events

**Implementation:**
```bash
audit_log() {
    local event=$1
    local details=$2
    local timestamp=$(date -Iseconds)
    
    echo "{\"timestamp\":\"$timestamp\",\"event\":\"$event\",\"details\":\"$details\"}" \
        >> "$LOG_DIR/security_audit.jsonl"
}

# Usage
audit_log "sandbox_start" "type=docker,policy=standard,network=restricted"
audit_log "policy_violation" "attempted_network_access=blocked.example.com"
```

### 13. Testing Strategy

Create comprehensive test suite:

**Unit Tests (`file:tests/unit/test_sandbox_policy.bats`):**
- Policy loading from config files
- Policy validation logic
- Policy preset application
- Secret masking functions
- Duration/memory format parsing
- Estimated: 15-20 tests

**Integration Tests (`file:tests/integration/test_sandbox_docker.bats`):**
- Docker sandbox initialization
- Network policy enforcement
- Filesystem policy enforcement
- Resource limit enforcement
- Secret injection
- Estimated: 20-25 tests (depends on Phase 6.1 completion)

**Integration Tests (`file:tests/integration/test_sandbox_e2b.bats`):**
- E2B sandbox initialization
- E2B-specific policy enforcement
- Cost limit tracking
- Estimated: 15-20 tests (depends on Phase 6.2 completion)

**Edge Case Tests:**
- Invalid policy configurations
- Conflicting policies
- Missing dependencies (Docker not installed)
- Secret file permissions
- Resource exhaustion scenarios
- Estimated: 10-15 tests

**Test Sequencing:** Unit tests for policy management can be written immediately. Integration tests for Docker and E2B enforcement should be deferred until their respective sandbox implementations are complete.

### 14. Documentation

Update documentation files:

**`file:README.md`:**
- Add "Sandbox Execution" section
- Document CLI flags for sandbox policies
- Provide examples of common configurations
- Security best practices

**Create `file:docs/SANDBOX_SECURITY.md`:**
- Detailed security policy documentation
- Policy preset descriptions
- Network policy configuration guide
- Secret management best practices
- Troubleshooting guide

**Update `file:IMPLEMENTATION_PLAN.md`:**
- Add Phase 6.4 completion status
- Document test coverage for sandbox features

### 15. Backward Compatibility

Ensure backward compatibility:

**Default Behavior:**
- `SANDBOX_TYPE=none` by default (no sandbox, current behavior)
- No breaking changes to existing CLI flags
- Config files are optional

**Migration Path:**
- Users can opt-in to sandbox execution with `--sandbox docker`
- Existing projects continue to work without modification
- Gradual migration: test with sandbox, then make it default

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant ralph_loop.sh
    participant sandbox_policy.sh
    participant sandbox_docker.sh
    participant Docker
    participant Claude

    User->>ralph_loop.sh: ralph --sandbox docker --sandbox-policy standard
    ralph_loop.sh->>ralph_loop.sh: load_config() from .ralphrc
    ralph_loop.sh->>sandbox_policy.sh: init_sandbox_policy()
    sandbox_policy.sh->>sandbox_policy.sh: apply_policy_preset("standard")
    sandbox_policy.sh->>sandbox_policy.sh: validate_policy()
    sandbox_policy.sh-->>ralph_loop.sh: Policy validated
    
    ralph_loop.sh->>sandbox_docker.sh: init_sandbox_docker()
    sandbox_docker.sh->>sandbox_docker.sh: apply_network_policy_docker("restricted")
    sandbox_docker.sh->>sandbox_docker.sh: apply_filesystem_policy_docker()
    sandbox_docker.sh->>sandbox_docker.sh: apply_resource_limits_docker()
    sandbox_docker.sh->>sandbox_docker.sh: inject_secrets_docker()
    sandbox_docker.sh->>Docker: docker run with policy flags
    Docker-->>sandbox_docker.sh: Container ready
    
    loop Main Loop
        ralph_loop.sh->>sandbox_docker.sh: execute_in_sandbox_docker(claude_command)
        sandbox_docker.sh->>Docker: docker exec
        Docker->>Claude: Execute Claude Code
        Claude-->>Docker: Response
        Docker-->>sandbox_docker.sh: Output
        sandbox_docker.sh->>sandbox_policy.sh: mask_secrets_in_output()
        sandbox_docker.sh-->>ralph_loop.sh: Sanitized output
        ralph_loop.sh->>sandbox_policy.sh: audit_log("execution_complete")
    end
    
    ralph_loop.sh->>sandbox_docker.sh: cleanup_sandbox_docker()
    sandbox_docker.sh->>Docker: docker stop & rm
    Docker-->>sandbox_docker.sh: Cleanup complete
```

## Policy Configuration Example

```yaml
# ~/.ralph/config.yaml
sandbox:
  type: docker
  
  security:
    # Network policy
    network:
      mode: restricted
      allow:
        - api.anthropic.com
        - registry.npmjs.org
        - pypi.org
        - files.pythonhosted.org
        - github.com
      deny:
        - "*.internal.company.com"
        - "*.local"
    
    # Filesystem policy
    filesystem:
      readOnlyRoot: true
      writable:
        - /workspace/output
        - /workspace/logs
        - /workspace/.ralph_session
      protected:
        - PROMPT.md
        - "@fix_plan.md"
        - specs/
    
    # Resource limits
    resources:
      memory: 4g
      cpus: 2
      disk: 10g
      maxDuration: 2h
      loopTimeout: 15m
    
    # Secret management
    secrets:
      source: file
      path: ~/.ralph/secrets
      inject:
        - ANTHROPIC_API_KEY
        - GITHUB_TOKEN
      
    # Audit logging
    audit:
      enabled: true
      logFile: logs/security_audit.jsonl
```

## Dependencies

**Required:**
- Docker (for Docker sandbox) - `docker --version` (Phase 6.1 prerequisite)
- E2B SDK (for E2B sandbox) - `npm install -g @e2b/sdk` (Phase 6.2 prerequisite)
- `yq` (for YAML parsing) - `brew install yq` or `apt-get install yq`
- `jq` (already required by Ralph)

**Optional:**
- `iptables` (for advanced Docker network filtering)
- Secret managers: AWS Secrets Manager CLI, 1Password CLI

**Phase Dependencies:**
- Phase 6.1 (Docker sandbox) must be complete before Docker policy enforcement can be tested
- Phase 6.2 (E2B sandbox) must be complete before E2B policy enforcement can be tested
- Phase 6.3 (File sync) should be complete before secret exclusion policies are finalized

## Risk Mitigation

**Security Risks:**
- **Secret leakage**: Mitigated by secret masking, read-only mounts, and audit logging
- **Network exfiltration**: Mitigated by network policies and allowlist/denylist
- **Resource exhaustion**: Mitigated by resource limits and duration timeouts

**Implementation Risks:**
- **Docker not available**: Graceful fallback to host execution with warning
- **E2B API changes**: Version pinning and adapter pattern for isolation
- **Policy conflicts**: Validation before sandbox start prevents runtime errors
- **Dependency on earlier phases**: As a P4 feature, this work should not block higher-priority phases (6.1, 6.2, 6.3)

**Backward Compatibility:**
- Default `SANDBOX_TYPE=none` ensures existing workflows continue unchanged
- All sandbox features are opt-in via CLI flags or config files
- Policy management infrastructure can be implemented independently of sandbox implementations

**Phasing Strategy:**
- Implement policy management infrastructure (steps 1-9) early for code organization
- Defer sandbox-specific enforcement (steps 10-12) until Phase 6.1 and 6.2 are complete
- Write unit tests for policy management immediately
- Write integration tests for enforcement after sandbox implementations are available

---

Execution Information

Branch: main
Commit: d0208c4

[frankbria]

Closing as not planned. The practical 80% of this shipped piecemeal: --sandbox-memory/--sandbox-cpus/--sandbox-network (Docker resource/network policy), --sandbox-max-cost/--sandbox-cost-alert (E2B budget policy), ALLOWED_TOOLS restrictions, sync filtering with secret-exclusion patterns (#76), and pre-loop file-protection integrity checks. A fuller policy framework (secret injection, org-level policy) is a product concern that belongs in CodeFrame.