[P4] Phase 6.7 Cloudflare Sandbox Integration

[frankbria]

Summary

Integrate Cloudflare as a first-class sandbox backend for Ralph. Cloudflare offers edge compute and container capabilities that can provide globally distributed, low-latency sandbox execution.

Problem Statement

Users may prefer Cloudflare over other sandbox options when they:

• Already use Cloudflare infrastructure
• Need edge/global distribution for latency reasons
• Want integration with Cloudflare's security features
• Prefer Cloudflare's pricing model
• Need to stay within Cloudflare's ecosystem for compliance

Cloudflare Compute Options

Cloudflare Containers (Primary Target)

• Container-based execution
• Longer-running workloads than Workers
• Full Linux environment
• Suitable for Ralph's autonomous execution

Cloudflare Workers (Limited Applicability)

• V8 isolate-based serverless
• Short execution limits (may be too restrictive)
• Could be used for lightweight tasks

Workers for Platforms

• Multi-tenant execution
• Could enable "Ralph as a Service" scenarios

Proposed CLI Interface

# Basic Cloudflare sandbox execution
ralph --sandbox cloudflare

# Specify Cloudflare product
ralph --sandbox cloudflare --cf-product containers
ralph --sandbox cloudflare --cf-product workers  # Limited use cases

# Account configuration
ralph --sandbox cloudflare --cf-account-id "abc123"
ralph --sandbox cloudflare --cf-api-token "$CF_API_TOKEN"

# Region/location preferences
ralph --sandbox cloudflare --cf-region "us-east"
ralph --sandbox cloudflare --cf-colo "EWR"  # Specific datacenter

# Resource configuration
ralph --sandbox cloudflare --memory 2g
ralph --sandbox cloudflare --timeout 3600

# Networking
ralph --sandbox cloudflare --cf-network "my-network"  # Cloudflare network

Key Design Questions

1. Which Cloudflare Product?

   • Containers most likely for full Ralph execution
   • Workers for specific lightweight tasks?
   • How to handle product evolution (CF adds new compute options)?

2. Authentication

   • API token management
   • Account ID configuration
   • Scoped tokens for security

3. Container Image

   • Use Ralph's official Docker image?
   • Push to Cloudflare's registry?
   • Or pull from Docker Hub/GHCR?

4. Networking

   • Cloudflare's network model
   • Access to Claude API from edge
   • Tunnels for accessing user's services?

5. Persistence

   • Cloudflare containers are ephemeral
   • R2 for artifact storage?
   • Durable Objects for state?

6. Cost Model

   • Cloudflare has different pricing than E2B
   • CPU-time based? Request-based?
   • Budget controls needed

7. Edge Distribution

   • Run near user for latency?
   • Run near Claude API for API latency?
   • Let Cloudflare decide?

Cloudflare API Overview

# Conceptual - actual API may differ
# Cloudflare Containers API
curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/containers" \
  -H "Authorization: Bearer $CF_API_TOKEN" \
  -d '{"image": "ralph:latest", "resources": {"memory": "2g"}}'

# Get container status
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/containers/{id}"

# Stream logs
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/containers/{id}/logs"

Implementation Approach

1. Create lib/sandbox/cloudflare.sh implementing sandbox interface
2. Implement Cloudflare API client for containers
3. Handle container image deployment
4. Implement file sync (upload to container, download artifacts)
5. Integrate with ralph-monitor for log streaming
6. Add cost tracking integration
7. Tests with mocked Cloudflare API

Cloudflare-Specific Considerations

• Edge-first: Cloudflare's model is edge compute
• Ephemeral: Containers don't persist by default
• Global: Can run in multiple locations
• Integrated Security: WAF, DDoS protection built-in
• R2 Storage: Natural artifact storage option
• Evolving Platform: Cloudflare compute is rapidly evolving

Acceptance Criteria

• --sandbox cloudflare flag launches Ralph in Cloudflare container
• Cloudflare authentication (API token, account ID)
• Container creation and lifecycle management
• File upload to container, artifact download
• Log streaming to ralph-monitor
• Cost tracking and budget limits
• Region/location preferences
• Graceful cleanup on exit
• Tests for Cloudflare sandbox execution

Dependencies

• Cloudflare account with Containers access
• Cloudflare API token with appropriate permissions
• Phase 6.5 ([P4] Phase 6.5 Generic Sandbox Interface and Plugin Architecture #78) generic interface (implements this)

Related

• Phase 6.0: [P4] Phase 6.0 Sandbox execution environments (E2B, Docker, and others) #49 (Umbrella issue)
• Phase 6.2: [P4] Phase 6.2 E2B Cloud Sandbox Integration #75 (E2B - alternative cloud option)
• Phase 6.3: [P4] Phase 6.3 Sandbox File Synchronization #76 (File sync - Cloudflare-specific implementation)
• Phase 6.5: [P4] Phase 6.5 Generic Sandbox Interface and Plugin Architecture #78 (Generic interface - Cloudflare implements this)
• Phase 6.6: [P4] Phase 6.6 Daytona Sandbox Integration #79 (Daytona - alternative self-hosted option)

Notes

Cloudflare's compute offerings are evolving rapidly. This issue should be reviewed against current Cloudflare capabilities when implementation begins. The Containers product specifically should be validated as GA and suitable for this use case.

[traycerai]

Plan

Implementation Plan: Phase 6.7 Cloudflare Sandbox Integration

Observations

Ralph is a bash-based autonomous development loop with a modular architecture using lib/ directory for reusable components. The project currently has no sandbox implementation—this is a greenfield feature. The codebase follows patterns of JSON-based state management with jq, cross-platform compatibility (macOS/Linux), and exported bash functions. The existing modules (file:lib/circuit_breaker.sh, file:lib/response_analyzer.sh, file:lib/date_utils.sh) demonstrate mature error handling, state persistence, and monitoring integration. The main execution flow in file:ralph_loop.sh orchestrates Claude Code CLI calls locally, which will need to be abstracted to support remote sandbox execution.

Approach

The implementation follows a layered architecture: (1) Create a generic sandbox interface (Phase 6.5 dependency) that abstracts sandbox operations, (2) Implement Cloudflare-specific backend using Cloudflare Containers API, (3) Integrate with existing Ralph components (monitoring, circuit breaker, file sync), and (4) Add CLI flags for Cloudflare configuration. This approach prioritizes Cloudflare Containers over Workers due to execution time requirements and full Linux environment needs. The design emphasizes fail-safe defaults, graceful degradation, and cost tracking to prevent runaway expenses.

Implementation Steps

1. Generic Sandbox Interface (Phase 6.5 Prerequisite)

Create file:lib/sandbox_interface.sh as the abstraction layer:

Core Functions to Define:

• sandbox_init() - Initialize sandbox provider with configuration
• sandbox_create() - Create new sandbox instance, return instance ID
• sandbox_upload_files() - Upload project files to sandbox
• sandbox_execute() - Execute command in sandbox, stream output
• sandbox_download_artifacts() - Download modified files from sandbox
• sandbox_destroy() - Clean up sandbox instance
• sandbox_get_status() - Query sandbox state (running/stopped/error)
• sandbox_get_logs() - Retrieve execution logs
• sandbox_get_cost() - Get current cost metrics

State Management:

• Create .sandbox_state JSON file tracking active instances
• Store provider type, instance ID, creation timestamp, cost accumulator
• Integrate with existing status.json for ralph-monitor display

Configuration Variables:

• SANDBOX_PROVIDER - Provider name (cloudflare, e2b, daytona, local)
• SANDBOX_ENABLED - Boolean flag to enable/disable sandbox mode
• SANDBOX_CLEANUP_ON_EXIT - Auto-cleanup flag (default: true)

2. Cloudflare Sandbox Implementation

Create file:lib/sandbox/cloudflare.sh implementing the interface:

Authentication & Configuration:

• CF_API_TOKEN - Cloudflare API token (from env or config)
• CF_ACCOUNT_ID - Cloudflare account identifier
• CF_PRODUCT - Product type (containers, workers) - default: containers
• CF_REGION - Preferred region/colo (optional, let CF decide by default)
• CF_CONTAINER_IMAGE - Docker image to use (default: official Ralph image)
• CF_MEMORY - Memory allocation (default: 2g)
• CF_TIMEOUT - Container timeout in seconds (default: 3600)

API Client Functions:

• cf_api_call() - Generic Cloudflare API wrapper with error handling
• cf_create_container() - POST to /accounts/{id}/containers endpoint
• cf_get_container_status() - GET container state
• cf_stream_logs() - Stream logs from container to ralph-monitor
• cf_delete_container() - DELETE container instance
• cf_upload_to_r2() - Upload files to R2 bucket for container access
• cf_download_from_r2() - Download artifacts from R2 bucket

Container Lifecycle:

sequenceDiagram
    participant Ralph as Ralph Loop
    participant CF as Cloudflare Module
    participant API as Cloudflare API
    participant R2 as R2 Storage
    participant Container as CF Container

    Ralph->>CF: sandbox_init()
    CF->>API: Validate credentials
    API-->>CF: Account verified
    
    Ralph->>CF: sandbox_create()
    CF->>R2: Upload project files
    CF->>API: Create container
    API->>Container: Start container
    API-->>CF: Container ID
    CF-->>Ralph: Instance ready
    
    Ralph->>CF: sandbox_execute(command)
    CF->>Container: Execute Claude Code
    Container-->>CF: Stream output
    CF-->>Ralph: Execution logs
    
    Ralph->>CF: sandbox_download_artifacts()
    CF->>Container: List changed files
    Container->>R2: Upload artifacts
    CF->>R2: Download artifacts
    CF-->>Ralph: Files synced
    
    Ralph->>CF: sandbox_destroy()
    CF->>API: Delete container
    CF->>R2: Cleanup temp files
    CF-->>Ralph: Cleanup complete

Loading

Error Handling:

• Detect Cloudflare API errors (rate limits, auth failures, quota exceeded)
• Implement exponential backoff for transient failures
• Integrate with circuit breaker pattern for persistent failures
• Log all API responses to logs/cloudflare_api.log

Cost Tracking:

• Track container runtime duration
• Estimate costs based on Cloudflare pricing model
• Update .sandbox_cost JSON file with running totals
• Implement budget limits with CF_BUDGET_LIMIT variable
• Alert when approaching budget threshold (80%, 90%, 100%)

3. File Synchronization (Phase 6.3 Integration)

Create file:lib/sandbox/file_sync.sh for bidirectional sync:

Upload Strategy:

• Create tarball of project directory (exclude logs/, .git/, node_modules/)
• Upload to R2 bucket with unique key: ralph-{project}-{timestamp}.tar.gz
• Container pulls tarball on startup and extracts
• Alternative: Direct file upload via Cloudflare API if available

Download Strategy:

• Container tracks modified files using git diff
• Package changed files into tarball
• Upload to R2 bucket: ralph-{project}-{timestamp}-artifacts.tar.gz
• Ralph downloads and extracts to local directory
• Merge strategy: overwrite local files with remote changes

Exclusion Patterns:

• .git/ - Version control (too large)
• node_modules/, vendor/ - Dependencies (reinstall in container)
• logs/ - Local logs (container has separate logs)
• .sandbox_* - Sandbox state files (local only)
• .claude_session_id - Session state (local only)

Sync Verification:

• Checksum validation (SHA256) for uploaded/downloaded files
• Retry logic for failed transfers (3 attempts with backoff)
• Log sync operations to logs/file_sync.log

4. CLI Integration

Modify file:ralph_loop.sh to add Cloudflare flags:

New CLI Flags:

--sandbox cloudflare              # Enable Cloudflare sandbox
--cf-product containers           # Cloudflare product (containers/workers)
--cf-account-id <id>              # Cloudflare account ID
--cf-api-token <token>            # API token (prefer env: CF_API_TOKEN)
--cf-region <region>              # Preferred region/colo
--cf-memory <size>                # Memory allocation (e.g., 2g)
--cf-timeout <seconds>            # Container timeout
--cf-budget <amount>              # Budget limit in USD
--sandbox-cleanup                 # Force cleanup on exit (default: true)
--sandbox-no-cleanup              # Keep sandbox running after exit

Argument Parsing:

• Add to existing CLI parser in ralph_loop.sh (around line 1085-1238)
• Validate required flags (account ID, API token)
• Set defaults for optional flags
• Store in global variables for sandbox module access

Execution Flow Modification:

• In execute_claude_code() function, check if SANDBOX_ENABLED=true
• If sandbox enabled, call sandbox_execute() instead of local Claude CLI
• Stream output from sandbox to local logs/claude_output_*.log
• Integrate with existing progress monitoring and circuit breaker

5. Monitoring Integration

Extend file:ralph_monitor.sh to display sandbox status:

New Status Fields:

• Sandbox provider (Cloudflare/E2B/Daytona/Local)
• Container ID and status (running/stopped)
• Container uptime and cost estimate
• Region/location information
• Last sync timestamp

Display Section:

┌─ Sandbox Status ────────────────────────────────────────────┐
│ Provider:       Cloudflare Containers
│ Container ID:   cf-abc123xyz
│ Status:         Running (15m 32s)
│ Region:         us-east (EWR)
│ Cost Estimate:  $0.12 / $10.00 budget
│ Last Sync:      2m 15s ago
└─────────────────────────────────────────────────────────────┘

Real-time Updates:

• Poll .sandbox_state file every refresh cycle (2 seconds)
• Display warnings if cost approaching budget limit
• Show sync errors or connection issues

6. Configuration File Support

Create file:.ralphrc example with Cloudflare settings:

# Cloudflare Sandbox Configuration
SANDBOX_PROVIDER="cloudflare"
CF_ACCOUNT_ID="your-account-id-here"
CF_API_TOKEN="$CF_API_TOKEN"  # Use environment variable
CF_PRODUCT="containers"
CF_REGION="auto"  # Let Cloudflare choose optimal region
CF_MEMORY="2g"
CF_TIMEOUT="3600"
CF_BUDGET_LIMIT="50.00"  # USD
SANDBOX_CLEANUP_ON_EXIT="true"

# Container Image Configuration
CF_CONTAINER_IMAGE="ghcr.io/frankbria/ralph-claude-code:latest"

Loading Priority:

1. CLI flags (highest priority)
2. Project .ralphrc file
3. Global ~/.ralphrc file
4. Environment variables
5. Hardcoded defaults (lowest priority)

7. Container Image Preparation

Create file:Dockerfile for Ralph container image:

Base Image:

• Use official Node.js image (for Claude Code CLI)
• Install bash, git, jq, curl, tmux
• Install Claude Code CLI: npm install -g @anthropic-ai/claude-code
• Copy Ralph scripts and lib/ modules
• Set working directory to /workspace

Entrypoint:

• Script that accepts commands via stdin
• Executes Claude Code with provided prompt
• Outputs results to stdout (JSON format)
• Handles signals for graceful shutdown

Image Registry:

• Build and push to GitHub Container Registry (ghcr.io)
• Tag with version numbers (e.g., v0.9.8, latest)
• Cloudflare pulls image on container creation

8. Testing Strategy

Create test files following existing BATS pattern:

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

• Test Cloudflare API client functions with mocked responses
• Test authentication validation
• Test cost calculation logic
• Test configuration parsing
• Test error handling for API failures

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

• Test full sandbox lifecycle (create, execute, destroy)
• Test file sync upload/download
• Test monitoring integration
• Test budget limit enforcement
• Test graceful cleanup on errors

Mock Cloudflare API:

• Create file:tests/helpers/mock_cloudflare_api.bash
• Mock container creation, status, logs, deletion endpoints
• Simulate API errors (rate limits, auth failures)
• Return realistic JSON responses

9. Documentation Updates

Update file:README.md:

• Add Cloudflare sandbox section under "Configuration"
• Document CLI flags and environment variables
• Provide setup instructions (API token creation)
• Add troubleshooting section for common issues

Create file:docs/cloudflare-sandbox.md:

• Detailed Cloudflare setup guide
• API token permissions required
• Cost estimation and budget management
• Region selection recommendations
• Container image customization guide

Update file:IMPLEMENTATION_STATUS.md:

• Mark Phase 6.7 as complete
• Update test count and coverage metrics
• Document new features and capabilities

10. Security Considerations

API Token Management:

• Never log API tokens (sanitize logs)
• Prefer environment variables over CLI flags
• Support scoped tokens (minimum required permissions)
• Validate token before creating containers

Container Security:

• Run containers with minimal privileges
• Isolate containers from each other (Cloudflare handles this)
• Limit network access (only Claude API and R2)
• Implement timeout to prevent runaway containers

Data Privacy:

• Encrypt files in R2 bucket (server-side encryption)
• Auto-delete R2 objects after download (configurable retention)
• Don't upload sensitive files (.env, credentials)
• Add .ralphrc to .gitignore

11. Cost Optimization

Strategies:

• Reuse containers across loops when possible (session continuity)
• Implement container pooling for frequent executions
• Use spot/preemptible instances if Cloudflare offers them
• Set aggressive timeouts to prevent idle containers
• Monitor and alert on cost anomalies

Budget Controls:

• Hard limit: Stop creating containers when budget reached
• Soft limit: Warn at 80% and 90% thresholds
• Daily/weekly budget caps (configurable)
• Cost reporting: Generate cost summary on exit

12. Graceful Degradation

Fallback Mechanisms:

• If Cloudflare API unavailable, fall back to local execution
• If R2 upload fails, retry with exponential backoff
• If container creation fails, log error and continue locally
• If budget exceeded, prompt user to increase or exit

User Notifications:

• Clear error messages for common issues
• Actionable suggestions (e.g., "Check API token permissions")
• Link to documentation for troubleshooting
• Log all errors to logs/cloudflare_errors.log

Dependencies

• Phase 6.5 ([P4] Phase 6.5 Generic Sandbox Interface and Plugin Architecture #78): Generic sandbox interface must be implemented first
• Cloudflare Account: With Containers product access
• Cloudflare API Token: With Workers/Containers permissions
• R2 Bucket: For file storage (auto-created or pre-configured)
• Docker Image: Ralph container image in registry
• jq: JSON parsing (already required)
• curl: HTTP client for API calls (already required)

Testing Checklist

• Cloudflare API authentication works
• Container creation and deletion lifecycle
• File upload to R2 and download from R2
• Command execution in container with output streaming
• Cost tracking and budget limit enforcement
• Monitoring dashboard displays sandbox status
• Circuit breaker integration with sandbox failures
• Graceful cleanup on Ctrl+C / SIGINT
• Error handling for API failures
• Configuration file loading and CLI flag parsing
• Session continuity across sandbox executions
• Multiple concurrent Ralph instances (different projects)

Success Metrics

• Container creation time < 30 seconds
• File sync overhead < 10% of execution time
• Cost tracking accuracy within 5% of actual
• Zero leaked containers (all cleaned up)
• 100% test pass rate for sandbox tests
• Documentation complete and accurate

Import In IDE

🤖 Prompt for AI Agents

# Implementation Plan: Phase 6.7 Cloudflare Sandbox Integration

## Observations

Ralph is a bash-based autonomous development loop with a modular architecture using lib/ directory for reusable components. The project currently has no sandbox implementation—this is a greenfield feature. The codebase follows patterns of JSON-based state management with jq, cross-platform compatibility (macOS/Linux), and exported bash functions. The existing modules (file:lib/circuit_breaker.sh, file:lib/response_analyzer.sh, file:lib/date_utils.sh) demonstrate mature error handling, state persistence, and monitoring integration. The main execution flow in file:ralph_loop.sh orchestrates Claude Code CLI calls locally, which will need to be abstracted to support remote sandbox execution.

## Approach

The implementation follows a layered architecture: (1) Create a generic sandbox interface (Phase 6.5 dependency) that abstracts sandbox operations, (2) Implement Cloudflare-specific backend using Cloudflare Containers API, (3) Integrate with existing Ralph components (monitoring, circuit breaker, file sync), and (4) Add CLI flags for Cloudflare configuration. This approach prioritizes Cloudflare Containers over Workers due to execution time requirements and full Linux environment needs. The design emphasizes fail-safe defaults, graceful degradation, and cost tracking to prevent runaway expenses.

## Implementation Steps

### 1. Generic Sandbox Interface (Phase 6.5 Prerequisite)

Create file:lib/sandbox_interface.sh as the abstraction layer:

**Core Functions to Define:**
- `sandbox_init()` - Initialize sandbox provider with configuration
- `sandbox_create()` - Create new sandbox instance, return instance ID
- `sandbox_upload_files()` - Upload project files to sandbox
- `sandbox_execute()` - Execute command in sandbox, stream output
- `sandbox_download_artifacts()` - Download modified files from sandbox
- `sandbox_destroy()` - Clean up sandbox instance
- `sandbox_get_status()` - Query sandbox state (running/stopped/error)
- `sandbox_get_logs()` - Retrieve execution logs
- `sandbox_get_cost()` - Get current cost metrics

**State Management:**
- Create `.sandbox_state` JSON file tracking active instances
- Store provider type, instance ID, creation timestamp, cost accumulator
- Integrate with existing status.json for ralph-monitor display

**Configuration Variables:**
- `SANDBOX_PROVIDER` - Provider name (cloudflare, e2b, daytona, local)
- `SANDBOX_ENABLED` - Boolean flag to enable/disable sandbox mode
- `SANDBOX_CLEANUP_ON_EXIT` - Auto-cleanup flag (default: true)

### 2. Cloudflare Sandbox Implementation

Create file:lib/sandbox/cloudflare.sh implementing the interface:

**Authentication & Configuration:**
- `CF_API_TOKEN` - Cloudflare API token (from env or config)
- `CF_ACCOUNT_ID` - Cloudflare account identifier
- `CF_PRODUCT` - Product type (containers, workers) - default: containers
- `CF_REGION` - Preferred region/colo (optional, let CF decide by default)
- `CF_CONTAINER_IMAGE` - Docker image to use (default: official Ralph image)
- `CF_MEMORY` - Memory allocation (default: 2g)
- `CF_TIMEOUT` - Container timeout in seconds (default: 3600)

**API Client Functions:**
- `cf_api_call()` - Generic Cloudflare API wrapper with error handling
- `cf_create_container()` - POST to `/accounts/{id}/containers` endpoint
- `cf_get_container_status()` - GET container state
- `cf_stream_logs()` - Stream logs from container to ralph-monitor
- `cf_delete_container()` - DELETE container instance
- `cf_upload_to_r2()` - Upload files to R2 bucket for container access
- `cf_download_from_r2()` - Download artifacts from R2 bucket

**Container Lifecycle:**
```mermaid
sequenceDiagram
    participant Ralph as Ralph Loop
    participant CF as Cloudflare Module
    participant API as Cloudflare API
    participant R2 as R2 Storage
    participant Container as CF Container

    Ralph->>CF: sandbox_init()
    CF->>API: Validate credentials
    API-->>CF: Account verified
    
    Ralph->>CF: sandbox_create()
    CF->>R2: Upload project files
    CF->>API: Create container
    API->>Container: Start container
    API-->>CF: Container ID
    CF-->>Ralph: Instance ready
    
    Ralph->>CF: sandbox_execute(command)
    CF->>Container: Execute Claude Code
    Container-->>CF: Stream output
    CF-->>Ralph: Execution logs
    
    Ralph->>CF: sandbox_download_artifacts()
    CF->>Container: List changed files
    Container->>R2: Upload artifacts
    CF->>R2: Download artifacts
    CF-->>Ralph: Files synced
    
    Ralph->>CF: sandbox_destroy()
    CF->>API: Delete container
    CF->>R2: Cleanup temp files
    CF-->>Ralph: Cleanup complete
```

**Error Handling:**
- Detect Cloudflare API errors (rate limits, auth failures, quota exceeded)
- Implement exponential backoff for transient failures
- Integrate with circuit breaker pattern for persistent failures
- Log all API responses to logs/cloudflare_api.log

**Cost Tracking:**
- Track container runtime duration
- Estimate costs based on Cloudflare pricing model
- Update `.sandbox_cost` JSON file with running totals
- Implement budget limits with `CF_BUDGET_LIMIT` variable
- Alert when approaching budget threshold (80%, 90%, 100%)

### 3. File Synchronization (Phase 6.3 Integration)

Create file:lib/sandbox/file_sync.sh for bidirectional sync:

**Upload Strategy:**
- Create tarball of project directory (exclude logs/, .git/, node_modules/)
- Upload to R2 bucket with unique key: `ralph-{project}-{timestamp}.tar.gz`
- Container pulls tarball on startup and extracts
- Alternative: Direct file upload via Cloudflare API if available

**Download Strategy:**
- Container tracks modified files using git diff
- Package changed files into tarball
- Upload to R2 bucket: `ralph-{project}-{timestamp}-artifacts.tar.gz`
- Ralph downloads and extracts to local directory
- Merge strategy: overwrite local files with remote changes

**Exclusion Patterns:**
- `.git/` - Version control (too large)
- `node_modules/`, `vendor/` - Dependencies (reinstall in container)
- `logs/` - Local logs (container has separate logs)
- `.sandbox_*` - Sandbox state files (local only)
- `.claude_session_id` - Session state (local only)

**Sync Verification:**
- Checksum validation (SHA256) for uploaded/downloaded files
- Retry logic for failed transfers (3 attempts with backoff)
- Log sync operations to logs/file_sync.log

### 4. CLI Integration

Modify file:ralph_loop.sh to add Cloudflare flags:

**New CLI Flags:**
```bash
--sandbox cloudflare              # Enable Cloudflare sandbox
--cf-product containers           # Cloudflare product (containers/workers)
--cf-account-id <id>              # Cloudflare account ID
--cf-api-token <token>            # API token (prefer env: CF_API_TOKEN)
--cf-region <region>              # Preferred region/colo
--cf-memory <size>                # Memory allocation (e.g., 2g)
--cf-timeout <seconds>            # Container timeout
--cf-budget <amount>              # Budget limit in USD
--sandbox-cleanup                 # Force cleanup on exit (default: true)
--sandbox-no-cleanup              # Keep sandbox running after exit
```

**Argument Parsing:**
- Add to existing CLI parser in ralph_loop.sh (around line 1085-1238)
- Validate required flags (account ID, API token)
- Set defaults for optional flags
- Store in global variables for sandbox module access

**Execution Flow Modification:**
- In `execute_claude_code()` function, check if `SANDBOX_ENABLED=true`
- If sandbox enabled, call `sandbox_execute()` instead of local Claude CLI
- Stream output from sandbox to local logs/claude_output_*.log
- Integrate with existing progress monitoring and circuit breaker

### 5. Monitoring Integration

Extend file:ralph_monitor.sh to display sandbox status:

**New Status Fields:**
- Sandbox provider (Cloudflare/E2B/Daytona/Local)
- Container ID and status (running/stopped)
- Container uptime and cost estimate
- Region/location information
- Last sync timestamp

**Display Section:**
```
┌─ Sandbox Status ────────────────────────────────────────────┐
│ Provider:       Cloudflare Containers
│ Container ID:   cf-abc123xyz
│ Status:         Running (15m 32s)
│ Region:         us-east (EWR)
│ Cost Estimate:  $0.12 / $10.00 budget
│ Last Sync:      2m 15s ago
└─────────────────────────────────────────────────────────────┘
```

**Real-time Updates:**
- Poll `.sandbox_state` file every refresh cycle (2 seconds)
- Display warnings if cost approaching budget limit
- Show sync errors or connection issues

### 6. Configuration File Support

Create file:.ralphrc example with Cloudflare settings:

```bash
# Cloudflare Sandbox Configuration
SANDBOX_PROVIDER="cloudflare"
CF_ACCOUNT_ID="your-account-id-here"
CF_API_TOKEN="$CF_API_TOKEN"  # Use environment variable
CF_PRODUCT="containers"
CF_REGION="auto"  # Let Cloudflare choose optimal region
CF_MEMORY="2g"
CF_TIMEOUT="3600"
CF_BUDGET_LIMIT="50.00"  # USD
SANDBOX_CLEANUP_ON_EXIT="true"

# Container Image Configuration
CF_CONTAINER_IMAGE="ghcr.io/frankbria/ralph-claude-code:latest"
```

**Loading Priority:**
1. CLI flags (highest priority)
2. Project `.ralphrc` file
3. Global `~/.ralphrc` file
4. Environment variables
5. Hardcoded defaults (lowest priority)

### 7. Container Image Preparation

Create file:Dockerfile for Ralph container image:

**Base Image:**
- Use official Node.js image (for Claude Code CLI)
- Install bash, git, jq, curl, tmux
- Install Claude Code CLI: `npm install -g @anthropic-ai/claude-code`
- Copy Ralph scripts and lib/ modules
- Set working directory to /workspace

**Entrypoint:**
- Script that accepts commands via stdin
- Executes Claude Code with provided prompt
- Outputs results to stdout (JSON format)
- Handles signals for graceful shutdown

**Image Registry:**
- Build and push to GitHub Container Registry (ghcr.io)
- Tag with version numbers (e.g., v0.9.8, latest)
- Cloudflare pulls image on container creation

### 8. Testing Strategy

Create test files following existing BATS pattern:

**Unit Tests (file:tests/unit/test_cloudflare_sandbox.bats):**
- Test Cloudflare API client functions with mocked responses
- Test authentication validation
- Test cost calculation logic
- Test configuration parsing
- Test error handling for API failures

**Integration Tests (file:tests/integration/test_cloudflare_integration.bats):**
- Test full sandbox lifecycle (create, execute, destroy)
- Test file sync upload/download
- Test monitoring integration
- Test budget limit enforcement
- Test graceful cleanup on errors

**Mock Cloudflare API:**
- Create file:tests/helpers/mock_cloudflare_api.bash
- Mock container creation, status, logs, deletion endpoints
- Simulate API errors (rate limits, auth failures)
- Return realistic JSON responses

### 9. Documentation Updates

**Update file:README.md:**
- Add Cloudflare sandbox section under "Configuration"
- Document CLI flags and environment variables
- Provide setup instructions (API token creation)
- Add troubleshooting section for common issues

**Create file:docs/cloudflare-sandbox.md:**
- Detailed Cloudflare setup guide
- API token permissions required
- Cost estimation and budget management
- Region selection recommendations
- Container image customization guide

**Update file:IMPLEMENTATION_STATUS.md:**
- Mark Phase 6.7 as complete
- Update test count and coverage metrics
- Document new features and capabilities

### 10. Security Considerations

**API Token Management:**
- Never log API tokens (sanitize logs)
- Prefer environment variables over CLI flags
- Support scoped tokens (minimum required permissions)
- Validate token before creating containers

**Container Security:**
- Run containers with minimal privileges
- Isolate containers from each other (Cloudflare handles this)
- Limit network access (only Claude API and R2)
- Implement timeout to prevent runaway containers

**Data Privacy:**
- Encrypt files in R2 bucket (server-side encryption)
- Auto-delete R2 objects after download (configurable retention)
- Don't upload sensitive files (.env, credentials)
- Add `.ralphrc` to .gitignore

### 11. Cost Optimization

**Strategies:**
- Reuse containers across loops when possible (session continuity)
- Implement container pooling for frequent executions
- Use spot/preemptible instances if Cloudflare offers them
- Set aggressive timeouts to prevent idle containers
- Monitor and alert on cost anomalies

**Budget Controls:**
- Hard limit: Stop creating containers when budget reached
- Soft limit: Warn at 80% and 90% thresholds
- Daily/weekly budget caps (configurable)
- Cost reporting: Generate cost summary on exit

### 12. Graceful Degradation

**Fallback Mechanisms:**
- If Cloudflare API unavailable, fall back to local execution
- If R2 upload fails, retry with exponential backoff
- If container creation fails, log error and continue locally
- If budget exceeded, prompt user to increase or exit

**User Notifications:**
- Clear error messages for common issues
- Actionable suggestions (e.g., "Check API token permissions")
- Link to documentation for troubleshooting
- Log all errors to logs/cloudflare_errors.log

## Dependencies

- **Phase 6.5 (#78)**: Generic sandbox interface must be implemented first
- **Cloudflare Account**: With Containers product access
- **Cloudflare API Token**: With Workers/Containers permissions
- **R2 Bucket**: For file storage (auto-created or pre-configured)
- **Docker Image**: Ralph container image in registry
- **jq**: JSON parsing (already required)
- **curl**: HTTP client for API calls (already required)

## Testing Checklist

- [ ] Cloudflare API authentication works
- [ ] Container creation and deletion lifecycle
- [ ] File upload to R2 and download from R2
- [ ] Command execution in container with output streaming
- [ ] Cost tracking and budget limit enforcement
- [ ] Monitoring dashboard displays sandbox status
- [ ] Circuit breaker integration with sandbox failures
- [ ] Graceful cleanup on Ctrl+C / SIGINT
- [ ] Error handling for API failures
- [ ] Configuration file loading and CLI flag parsing
- [ ] Session continuity across sandbox executions
- [ ] Multiple concurrent Ralph instances (different projects)

## Success Metrics

- Container creation time < 30 seconds
- File sync overhead < 10% of execution time
- Cost tracking accuracy within 5% of actual
- Zero leaked containers (all cleaned up)
- 100% test pass rate for sandbox tests
- Documentation complete and accurate

---

Execution Information

Branch: main
Commit: d0208c4

---

💡 Tips

Supported Commands (Inside Comments)

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

Supported Commands (Inside Description)

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

Community

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

[frankbria]

Closing as not planned — same rationale as #79: Docker (local) + E2B (cloud) are ralph's complete and final sandbox provider set. Multi-environment execution beyond that is CodeFrame territory.