[v2.5+] Implement DockerProvider

[frankbria]

Overview

Implement a Docker-based sandbox provider for cross-platform sandboxing without cloud costs.

Implementation

// src/e2b/providers/docker-provider.ts

export class DockerProvider implements SandboxProvider {
  readonly name = 'docker';
  readonly version = '1.0.0';
  
  private defaultImage = 'claude-code:latest';
  
  static async isAvailable(): Promise<boolean> {
    try {
      execSync('docker info', { stdio: 'pipe' });
      return true;
    } catch {
      return false;
    }
  }
  
  async create(config: SandboxConfig): Promise<SandboxInstance> {
    // docker run -d --name <name> -v <workdir>:/workspace <image>
    const containerId = await this.startContainer(config);
    return {
      id: containerId,
      provider: 'docker',
      status: SandboxStatus.RUNNING,
      createdAt: new Date()
    };
  }
  
  async execute(instanceId: string, command: string): AsyncGenerator<string> {
    // docker exec -t <instanceId> <command>
    // Stream output line by line
  }
  
  async destroy(instanceId: string): Promise<void> {
    // docker stop <instanceId> && docker rm <instanceId>
  }
}

Docker Image

Create official claude-code Docker image:

# docker/Dockerfile
FROM node:20-slim

# Install Claude CLI
RUN npm install -g @anthropic-ai/claude-code

# Install common development tools
RUN apt-get update && apt-get install -y \
  git \
  curl \
  python3 \
  python3-pip

WORKDIR /workspace

# Entry point that keeps container running
ENTRYPOINT ["tail", "-f", "/dev/null"]

Configuration

# Use custom image
parallel-cc sandbox-run --provider docker --docker-image my-image:tag

# Resource limits
parallel-cc sandbox-run --provider docker --memory 4g --cpus 2

Platform Support

• macOS (Docker Desktop)
• Linux (Docker Engine)
• Windows (Docker Desktop with WSL2)

Files to Create

• src/e2b/providers/docker-provider.ts
• docker/Dockerfile
• docker/docker-compose.yml (for easy local testing)
• tests/e2b/docker-provider.test.ts

Acceptance Criteria

• Container creation works
• File mounting works correctly
• Command execution with output streaming
• Proper cleanup (stop and remove)
• Works on macOS, Linux, and Windows
• Integration tests pass

Dependencies

• Depends on [v2.5] Define SandboxProvider interface and types #30 (SandboxProvider interface)
• Depends on [v2.5] Add provider registry and factory pattern #32 (Provider registry)

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#1 - Add native sandboxing integration option [merged]
#5 - feat(v1.0): E2B Sandbox Integration - Autonomous Claude Code Execution [merged]
#11 - feat: Use anthropic-claude-code E2B template with fallback installation [merged]
#18 - test: Add comprehensive E2E tests for E2B workflow [merged]
#47 - feat(e2b): Add NPM token injection for private package access [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[traycerai]

Plan

Observations

The codebase currently has E2B-specific sandbox integration (v1.0-v2.0) without provider abstraction. The SandboxManager in src/e2b/sandbox-manager.ts is tightly coupled to E2B SDK. The SANDBOX_INTEGRATION_PLAN.md outlines a comprehensive multi-provider architecture for v1.5+ that includes Docker, Native, E2B, Daytona, and Cloudflare providers. The existing E2B implementation provides excellent patterns for file sync (src/e2b/file-sync.ts), command execution (src/e2b/claude-runner.ts), and security (input sanitization, path validation). No Docker-related files or provider abstraction exists yet. The ticket version is updated to v2.5+ indicating this is a later phase implementation.

Approach

The implementation requires a multi-phase approach: (1) Create the provider abstraction layer first (SandboxProvider interface, types, and registry) since the architecture plan specifies this foundation, (2) Implement DockerProvider using dockerode library following the established patterns from E2B implementation, (3) Create Docker infrastructure files (Dockerfile, docker-compose.yml), (4) Add comprehensive tests, and (5) Integrate with CLI. This approach ensures backward compatibility with existing E2B code while enabling the multi-provider architecture outlined in SANDBOX_INTEGRATION_PLAN.md.

Implementation Steps

Phase 1: Provider Abstraction Layer (Dependencies #30 & #32)

1.1 Create Provider Interface and Types

Create file:src/e2b/providers/types.ts:

• Define SandboxProvider interface with methods:

  • name: string - Provider identifier (e.g., 'docker', 'e2b')
  • version: string - Provider version
  • isAvailable(): Promise<boolean> - Check if provider can be used
  • create(config: SandboxConfig): Promise<SandboxInstance> - Create sandbox
  • execute(instanceId: string, command: string): AsyncGenerator<string> - Execute command with streaming
  • uploadFiles(instanceId: string, files: FileList): Promise<void> - Upload files
  • downloadFiles(instanceId: string, localPath: string): Promise<DownloadResult> - Download changed files
  • destroy(instanceId: string): Promise<void> - Terminate sandbox
  • getHealth(instanceId: string): Promise<SandboxHealthCheck> - Health check

• Define SandboxConfig interface:

  • sessionId: string
  • worktreePath: string
  • timeoutMinutes?: number
  • providerOptions?: Record<string, unknown> - Provider-specific options

• Define SandboxInstance interface:

  • id: string - Sandbox/container ID
  • provider: string - Provider name
  • status: SandboxStatus - Current status
  • createdAt: Date
  • metadata?: Record<string, unknown>

• Define FileList type for file operations

• Define ExecutionChunk type for streaming output

1.2 Create Provider Registry

Create file:src/e2b/providers/registry.ts:

• Implement ProviderRegistry class:

  • register(provider: SandboxProvider): void - Register a provider
  • get(name: string): SandboxProvider | null - Get provider by name
  • list(): string[] - List available provider names
  • getAvailable(): Promise<SandboxProvider[]> - Get all available providers (checks isAvailable())
  • getDefault(): Promise<SandboxProvider> - Get default provider based on platform/config

• Create singleton instance: export const providerRegistry = new ProviderRegistry()

• Add provider selection logic:

  • Check PARALLEL_CC_SANDBOX_PROVIDER environment variable
  • Fall back to platform-specific defaults (Docker for Windows, E2B if API key exists, etc.)

1.3 Update Type Definitions

Update file:src/types.ts:

• Change ExecutionMode from 'local' | 'e2b' to 'local' | 'e2b' | 'docker'
• Add sandbox_provider field to Session interface (nullable string)
• Keep backward compatibility with existing E2B fields

Phase 2: Implement Docker Provider

2.1 Install Dependencies

Add to file:package.json:

{
  "dependencies": {
    "dockerode": "^4.0.2"
  },
  "devDependencies": {
    "@types/dockerode": "^3.3.31"
  }
}

2.2 Create Docker Provider Implementation

Create src/sandbox/providers/docker.ts:

Core Implementation:

• Implement DockerProvider class that implements SandboxProvider:

  • name = 'docker'
  • version = '1.0.0'
  • defaultImage = 'claude-code:latest' (configurable via PARALLEL_CC_DOCKER_IMAGE)

• Implement isAvailable():

  • Use child_process.execSync('docker info', { stdio: 'pipe' })
  • Return true if Docker daemon is running, false otherwise
  • Catch errors gracefully (Docker not installed, daemon not running)

• Implement create(config: SandboxConfig):

  • Extract Docker-specific options from config.providerOptions:
    • image (default: claude-code:latest)
    • network (default: none for isolation)
    • memory (default: 4g)
    • cpus (default: 2)
  • Create container using dockerode:

    const container = await docker.createContainer({
      Image: image,
      Cmd: ['/bin/bash'],
      Tty: true,
      AttachStdin: true,
      AttachStdout: true,
      AttachStderr: true,
      OpenStdin: true,
      HostConfig: {
        NetworkMode: network,
        Memory: parseMemory(memory),
        CpuQuota: cpus * 100000,
        Binds: [`${config.worktreePath}:/workspace:rw`],
        SecurityOpt: ['no-new-privileges'],
        CapDrop: ['ALL'],
        CapAdd: ['CHOWN', 'DAC_OVERRIDE', 'FOWNER', 'SETGID', 'SETUID'] // Minimal caps for file operations
      },
      WorkingDir: '/workspace',
      Env: [
        `ANTHROPIC_API_KEY=${process.env.ANTHROPIC_API_KEY}`,
        `HOME=/workspace`
      ]
    });

  • Start container: await container.start()
  • Return SandboxInstance with container ID

• Implement execute(instanceId: string, command: string):

  • Get container: const container = docker.getContainer(instanceId)
  • Create exec instance:

    const exec = await container.exec({
      Cmd: ['/bin/bash', '-c', command],
      AttachStdout: true,
      AttachStderr: true,
      Tty: false
    });

  • Start exec and stream output:

    const stream = await exec.start({ Detach: false, Tty: false });
    // Use async generator to yield output line by line
    for await (const chunk of stream) {
      yield chunk.toString('utf-8');
    }

• Implement uploadFiles():

  • Since Docker uses volume mounts, files are already accessible
  • This method can be a no-op or verify mount is working
  • Log: "Files available via volume mount at /workspace"

• Implement downloadFiles():

  • Since Docker uses volume mounts, files are already in local worktree
  • This method can be a no-op or verify changes
  • Return DownloadResult with filesDownloaded: 0 (no transfer needed)

• Implement destroy(instanceId: string):

  • Get container: const container = docker.getContainer(instanceId)
  • Stop container: await container.stop({ t: 10 }) (10 second timeout)
  • Remove container: await container.remove({ force: true })
  • Handle errors gracefully (container already stopped/removed)

• Implement getHealth(instanceId: string):

  • Get container: const container = docker.getContainer(instanceId)
  • Inspect container: const info = await container.inspect()
  • Check info.State.Running
  • Return SandboxHealthCheck with status

Security Considerations:

• Validate instanceId to prevent injection (alphanumeric + hyphens only)
• Sanitize commands using same patterns from file:src/e2b/sandbox-manager.ts
• Use NetworkMode: 'none' by default to prevent network access
• Drop all capabilities except minimal required for file operations
• Use SecurityOpt: ['no-new-privileges'] to prevent privilege escalation

Platform-Specific Handling:

• Windows path conversion:

  private normalizePathForDocker(localPath: string): string {
    if (process.platform === 'win32') {
      // Convert C:\Users\... to /c/Users/...
      return localPath.replace(/\\/g, '/').replace(/^([A-Z]):/, (_, drive) => `/${drive.toLowerCase()}`);
    }
    return localPath;
  }

• Check for WSL2 on Windows:

  private async checkWSL2(): Promise<boolean> {
    if (process.platform !== 'win32') return true;
    try {
      execSync('wsl --status', { stdio: 'pipe' });
      return true;
    } catch {
      return false;
    }
  }

2.3 Register Docker Provider

Create src/sandbox/providers/index.ts:

• Auto-register Docker provider on module load:

  import { DockerProvider } from './docker.js';
  import { providerRegistry } from '../registry.js';
  
  providerRegistry.register(new DockerProvider());

Phase 3: Docker Infrastructure Files

3.1 Create Dockerfile

Create docker/Dockerfile:

FROM node:20-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    curl \
    python3 \
    python3-pip \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Install Claude Code CLI
RUN npm install -g @anthropic-ai/claude-code

# Create workspace directory
WORKDIR /workspace

# Keep container running
ENTRYPOINT ["tail", "-f", "/dev/null"]

3.2 Create Docker Compose File

Create docker/docker-compose.yml:

version: '3.8'

services:
  claude-code:
    build:
      context: .
      dockerfile: Dockerfile
    image: claude-code:latest
    container_name: parallel-cc-sandbox
    volumes:
      - ../:/workspace:rw
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    network_mode: none
    security_opt:
      - no-new-privileges
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
      - FOWNER
      - SETGID
      - SETUID
    mem_limit: 4g
    cpus: 2

3.3 Create Docker Ignore File

Create docker/.dockerignore:

node_modules
.git
dist
build
coverage
.next
__pycache__
*.pyc
.env*
*.log

3.4 Create Docker README

Create docker/README.md:

• Document Docker image build process
• Provide usage examples:
  • Building the image: docker build -t claude-code:latest .
  • Running with docker-compose: docker-compose up -d
  • Using with parallel-cc: parallel-cc sandbox-run --provider docker
• Document resource limits and security settings
• Troubleshooting section (Docker not running, WSL2 issues on Windows)

Phase 4: CLI Integration

4.1 Update sandbox-run Command

Update src/cli.ts (around line 1354):

• Add --provider option:

  .option('--provider <name>', 'Sandbox provider: docker, e2b (default: auto-detect)', 'auto')

• Add Docker-specific options:

  .option('--docker-image <image>', 'Docker image to use (default: claude-code:latest)')
  .option('--docker-network <mode>', 'Docker network mode: none, bridge, host (default: none)')
  .option('--docker-memory <limit>', 'Memory limit (e.g., 4g, 2048m)', '4g')
  .option('--docker-cpus <count>', 'CPU limit (default: 2)', '2')

• Update action handler:

  async (options) => {
    // Get provider
    let provider: SandboxProvider;
    if (options.provider === 'auto') {
      provider = await providerRegistry.getDefault();
    } else {
      provider = providerRegistry.get(options.provider);
      if (!provider) {
        throw new Error(`Provider '${options.provider}' not found`);
      }
    }
    
    // Check availability
    const available = await provider.isAvailable();
    if (!available) {
      throw new Error(`Provider '${provider.name}' is not available`);
    }
    
    // Build config
    const config: SandboxConfig = {
      sessionId: generateSessionId(),
      worktreePath: options.repo,
      timeoutMinutes: options.timeout,
      providerOptions: {
        // Docker-specific
        image: options.dockerImage,
        network: options.dockerNetwork,
        memory: options.dockerMemory,
        cpus: parseInt(options.dockerCpus),
        // E2B-specific
        template: options.e2bTemplate
      }
    };
    
    // Create sandbox
    const instance = await provider.create(config);
    
    // Execute command
    for await (const output of provider.execute(instance.id, command)) {
      process.stdout.write(output);
    }
    
    // Cleanup
    await provider.destroy(instance.id);
  }

4.2 Update doctor Command

Update src/cli.ts doctor command (around line 200):

• Add Docker availability check:

  // Check Docker
  try {
    execSync('docker info', { stdio: 'pipe' });
    console.log(chalk.green('✓ Docker: Available'));
    
    // Check Docker version
    const version = execSync('docker --version', { encoding: 'utf-8' }).trim();
    console.log(`  ${version}`);
  } catch {
    console.log(chalk.yellow('✗ Docker: Not available'));
    console.log('  Install: https://docs.docker.com/get-docker/');
  }
  
  // Check WSL2 on Windows
  if (process.platform === 'win32') {
    try {
      execSync('wsl --status', { stdio: 'pipe' });
      console.log(chalk.green('✓ WSL2: Available'));
    } catch {
      console.log(chalk.yellow('✗ WSL2: Not available (required for Docker on Windows)'));
      console.log('  Install: https://docs.microsoft.com/en-us/windows/wsl/install');
    }
  }

• Add provider availability check:

  // Check available providers
  const providers = await providerRegistry.getAvailable();
  console.log(`\nAvailable Sandbox Providers: ${providers.length}`);
  for (const provider of providers) {
    console.log(chalk.green(`  ✓ ${provider.name} (v${provider.version})`));
  }

Phase 5: Testing

5.1 Create Docker Provider Tests

Create tests/sandbox/docker.test.ts:

• Mock dockerode module

• Test suite structure (follow patterns from file:tests/e2b/sandbox-manager.test.ts):

  • describe('DockerProvider')
    • describe('isAvailable') - Test Docker detection
    • describe('create') - Test container creation with various configs
    • describe('execute') - Test command execution and streaming
    • describe('uploadFiles') - Test no-op behavior (volume mounts)
    • describe('downloadFiles') - Test no-op behavior (volume mounts)
    • describe('destroy') - Test container cleanup
    • describe('getHealth') - Test health checks
    • describe('platform-specific') - Test Windows path conversion, WSL2 checks
    • describe('security') - Test input validation, capability dropping
    • describe('error handling') - Test Docker daemon not running, image not found, etc.

• Mock Docker container lifecycle:

  const mockContainer = {
    id: 'test-container-123',
    start: vi.fn().mockResolvedValue(undefined),
    stop: vi.fn().mockResolvedValue(undefined),
    remove: vi.fn().mockResolvedValue(undefined),
    inspect: vi.fn().mockResolvedValue({ State: { Running: true } }),
    exec: vi.fn().mockResolvedValue(mockExec)
  };

• Test resource limits (memory, CPU)

• Test network isolation modes

• Test security options (capabilities, no-new-privileges)

5.2 Create Provider Registry Tests

Create tests/sandbox/registry.test.ts:

• Test provider registration
• Test provider retrieval by name
• Test listing providers
• Test getting available providers (with mocked isAvailable())
• Test default provider selection logic
• Test error handling (provider not found, no providers available)

5.3 Create Integration Tests

Create tests/sandbox/docker-integration.test.ts:

• Mark as integration test (skip in CI if Docker not available)
• Test full workflow:
  1. Create Docker container
  2. Execute simple command (e.g., echo "Hello")
  3. Verify output
  4. Cleanup container
• Test volume mounting (create file in container, verify in host)
• Test network isolation (verify no network access with network: 'none')
• Test resource limits (verify container respects memory/CPU limits)

Phase 6: Documentation

6.1 Update README

Update README.md:

• Add Docker provider section
• Document --provider flag
• Add Docker installation instructions
• Add platform-specific notes (Windows/WSL2, macOS/Docker Desktop, Linux/Docker Engine)

6.2 Create Docker Provider Documentation

Create docs/docker-provider.md:

• Overview of Docker provider
• Installation and setup
• Configuration options
• Security considerations
• Troubleshooting guide
• Comparison with E2B provider

6.3 Update SANDBOX_INTEGRATION_PLAN.md

Update SANDBOX_INTEGRATION_PLAN.md:

• Mark Docker provider as implemented
• Update implementation status
• Add lessons learned

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI
    participant Registry
    participant DockerProvider
    participant Docker
    participant Container

    User->>CLI: sandbox-run --provider docker
    CLI->>Registry: getProvider('docker')
    Registry-->>CLI: DockerProvider instance
    CLI->>DockerProvider: isAvailable()
    DockerProvider->>Docker: docker info
    Docker-->>DockerProvider: daemon running
    DockerProvider-->>CLI: true
    CLI->>DockerProvider: create(config)
    DockerProvider->>Docker: createContainer(options)
    Docker->>Container: create with volume mount
    Docker-->>DockerProvider: container ID
    DockerProvider-->>CLI: SandboxInstance
    CLI->>DockerProvider: execute(id, command)
    DockerProvider->>Container: exec command
    Container-->>DockerProvider: stream output
    DockerProvider-->>CLI: yield output chunks
    CLI->>User: display output
    CLI->>DockerProvider: destroy(id)
    DockerProvider->>Container: stop & remove
    Container-->>DockerProvider: cleanup complete
    DockerProvider-->>CLI: success

Loading

File Structure

src/
├── sandbox/
│   ├── types.ts              # NEW: Provider interface & types
│   ├── registry.ts           # NEW: Provider registry
│   └── providers/
│       ├── index.ts          # NEW: Provider registration
│       └── docker.ts         # NEW: Docker implementation
├── e2b/
│   ├── sandbox-manager.ts    # EXISTING: Keep for E2B internals
│   ├── file-sync.ts          # EXISTING: Reuse for E2B
│   ├── claude-runner.ts      # EXISTING: Reuse for E2B
│   └── ...
├── types.ts                  # UPDATE: Add docker to ExecutionMode
└── cli.ts                    # UPDATE: Add --provider flag

docker/
├── Dockerfile                # NEW: Claude Code image
├── docker-compose.yml        # NEW: Local testing
├── .dockerignore             # NEW: Exclude patterns
└── README.md                 # NEW: Docker docs

tests/
└── sandbox/
    ├── docker.test.ts        # NEW: Unit tests
    ├── registry.test.ts      # NEW: Registry tests
    └── docker-integration.test.ts # NEW: Integration tests

Acceptance Criteria Verification

• ✅ Container creation works - Implemented in DockerProvider.create()
• ✅ File mounting works correctly - Volume mounts configured in container creation
• ✅ Command execution with output streaming - Implemented with async generators in execute()
• ✅ Proper cleanup (stop and remove) - Implemented in destroy()
• ✅ Works on macOS, Linux, and Windows - Platform-specific path handling and WSL2 checks
• ✅ Integration tests pass - Comprehensive test suite created

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently has E2B-specific sandbox integration (v1.0-v2.0) without provider abstraction. The `SandboxManager` in `src/e2b/sandbox-manager.ts` is tightly coupled to E2B SDK. The `SANDBOX_INTEGRATION_PLAN.md` outlines a comprehensive multi-provider architecture for v1.5+ that includes Docker, Native, E2B, Daytona, and Cloudflare providers. The existing E2B implementation provides excellent patterns for file sync (`src/e2b/file-sync.ts`), command execution (`src/e2b/claude-runner.ts`), and security (input sanitization, path validation). No Docker-related files or provider abstraction exists yet. The ticket version is updated to v2.5+ indicating this is a later phase implementation.

## Approach

The implementation requires a multi-phase approach: (1) Create the provider abstraction layer first (SandboxProvider interface, types, and registry) since the architecture plan specifies this foundation, (2) Implement DockerProvider using `dockerode` library following the established patterns from E2B implementation, (3) Create Docker infrastructure files (Dockerfile, docker-compose.yml), (4) Add comprehensive tests, and (5) Integrate with CLI. This approach ensures backward compatibility with existing E2B code while enabling the multi-provider architecture outlined in `SANDBOX_INTEGRATION_PLAN.md`.

## Implementation Steps

### Phase 1: Provider Abstraction Layer (Dependencies #30 & #32)

#### 1.1 Create Provider Interface and Types

Create `file:src/e2b/providers/types.ts`:

- Define `SandboxProvider` interface with methods:
  - `name: string` - Provider identifier (e.g., 'docker', 'e2b')
  - `version: string` - Provider version
  - `isAvailable(): Promise<boolean>` - Check if provider can be used
  - `create(config: SandboxConfig): Promise<SandboxInstance>` - Create sandbox
  - `execute(instanceId: string, command: string): AsyncGenerator<string>` - Execute command with streaming
  - `uploadFiles(instanceId: string, files: FileList): Promise<void>` - Upload files
  - `downloadFiles(instanceId: string, localPath: string): Promise<DownloadResult>` - Download changed files
  - `destroy(instanceId: string): Promise<void>` - Terminate sandbox
  - `getHealth(instanceId: string): Promise<SandboxHealthCheck>` - Health check

- Define `SandboxConfig` interface:
  - `sessionId: string`
  - `worktreePath: string`
  - `timeoutMinutes?: number`
  - `providerOptions?: Record<string, unknown>` - Provider-specific options

- Define `SandboxInstance` interface:
  - `id: string` - Sandbox/container ID
  - `provider: string` - Provider name
  - `status: SandboxStatus` - Current status
  - `createdAt: Date`
  - `metadata?: Record<string, unknown>`

- Define `FileList` type for file operations
- Define `ExecutionChunk` type for streaming output

#### 1.2 Create Provider Registry

Create `file:src/e2b/providers/registry.ts`:

- Implement `ProviderRegistry` class:
  - `register(provider: SandboxProvider): void` - Register a provider
  - `get(name: string): SandboxProvider | null` - Get provider by name
  - `list(): string[]` - List available provider names
  - `getAvailable(): Promise<SandboxProvider[]>` - Get all available providers (checks `isAvailable()`)
  - `getDefault(): Promise<SandboxProvider>` - Get default provider based on platform/config

- Create singleton instance: `export const providerRegistry = new ProviderRegistry()`

- Add provider selection logic:
  - Check `PARALLEL_CC_SANDBOX_PROVIDER` environment variable
  - Fall back to platform-specific defaults (Docker for Windows, E2B if API key exists, etc.)

#### 1.3 Update Type Definitions

Update `file:src/types.ts`:

- Change `ExecutionMode` from `'local' | 'e2b'` to `'local' | 'e2b' | 'docker'`
- Add `sandbox_provider` field to `Session` interface (nullable string)
- Keep backward compatibility with existing E2B fields

### Phase 2: Implement Docker Provider

#### 2.1 Install Dependencies

Add to `file:package.json`:
```json
{
  "dependencies": {
    "dockerode": "^4.0.2"
  },
  "devDependencies": {
    "@types/dockerode": "^3.3.31"
  }
}
```

#### 2.2 Create Docker Provider Implementation

Create `src/sandbox/providers/docker.ts`:

**Core Implementation:**

- Implement `DockerProvider` class that implements `SandboxProvider`:
  - `name = 'docker'`
  - `version = '1.0.0'`
  - `defaultImage = 'claude-code:latest'` (configurable via `PARALLEL_CC_DOCKER_IMAGE`)

- Implement `isAvailable()`:
  - Use `child_process.execSync('docker info', { stdio: 'pipe' })`
  - Return `true` if Docker daemon is running, `false` otherwise
  - Catch errors gracefully (Docker not installed, daemon not running)

- Implement `create(config: SandboxConfig)`:
  - Extract Docker-specific options from `config.providerOptions`:
    - `image` (default: `claude-code:latest`)
    - `network` (default: `none` for isolation)
    - `memory` (default: `4g`)
    - `cpus` (default: `2`)
  - Create container using `dockerode`:
    ```typescript
    const container = await docker.createContainer({
      Image: image,
      Cmd: ['/bin/bash'],
      Tty: true,
      AttachStdin: true,
      AttachStdout: true,
      AttachStderr: true,
      OpenStdin: true,
      HostConfig: {
        NetworkMode: network,
        Memory: parseMemory(memory),
        CpuQuota: cpus * 100000,
        Binds: [`${config.worktreePath}:/workspace:rw`],
        SecurityOpt: ['no-new-privileges'],
        CapDrop: ['ALL'],
        CapAdd: ['CHOWN', 'DAC_OVERRIDE', 'FOWNER', 'SETGID', 'SETUID'] // Minimal caps for file operations
      },
      WorkingDir: '/workspace',
      Env: [
        `ANTHROPIC_API_KEY=${process.env.ANTHROPIC_API_KEY}`,
        `HOME=/workspace`
      ]
    });
    ```
  - Start container: `await container.start()`
  - Return `SandboxInstance` with container ID

- Implement `execute(instanceId: string, command: string)`:
  - Get container: `const container = docker.getContainer(instanceId)`
  - Create exec instance:
    ```typescript
    const exec = await container.exec({
      Cmd: ['/bin/bash', '-c', command],
      AttachStdout: true,
      AttachStderr: true,
      Tty: false
    });
    ```
  - Start exec and stream output:
    ```typescript
    const stream = await exec.start({ Detach: false, Tty: false });
    // Use async generator to yield output line by line
    for await (const chunk of stream) {
      yield chunk.toString('utf-8');
    }
    ```

- Implement `uploadFiles()`:
  - Since Docker uses volume mounts, files are already accessible
  - This method can be a no-op or verify mount is working
  - Log: "Files available via volume mount at /workspace"

- Implement `downloadFiles()`:
  - Since Docker uses volume mounts, files are already in local worktree
  - This method can be a no-op or verify changes
  - Return `DownloadResult` with `filesDownloaded: 0` (no transfer needed)

- Implement `destroy(instanceId: string)`:
  - Get container: `const container = docker.getContainer(instanceId)`
  - Stop container: `await container.stop({ t: 10 })` (10 second timeout)
  - Remove container: `await container.remove({ force: true })`
  - Handle errors gracefully (container already stopped/removed)

- Implement `getHealth(instanceId: string)`:
  - Get container: `const container = docker.getContainer(instanceId)`
  - Inspect container: `const info = await container.inspect()`
  - Check `info.State.Running`
  - Return `SandboxHealthCheck` with status

**Security Considerations:**

- Validate `instanceId` to prevent injection (alphanumeric + hyphens only)
- Sanitize commands using same patterns from `file:src/e2b/sandbox-manager.ts`
- Use `NetworkMode: 'none'` by default to prevent network access
- Drop all capabilities except minimal required for file operations
- Use `SecurityOpt: ['no-new-privileges']` to prevent privilege escalation

**Platform-Specific Handling:**

- Windows path conversion:
  ```typescript
  private normalizePathForDocker(localPath: string): string {
    if (process.platform === 'win32') {
      // Convert C:\Users\... to /c/Users/...
      return localPath.replace(/\\/g, '/').replace(/^([A-Z]):/, (_, drive) => `/${drive.toLowerCase()}`);
    }
    return localPath;
  }
  ```

- Check for WSL2 on Windows:
  ```typescript
  private async checkWSL2(): Promise<boolean> {
    if (process.platform !== 'win32') return true;
    try {
      execSync('wsl --status', { stdio: 'pipe' });
      return true;
    } catch {
      return false;
    }
  }
  ```

#### 2.3 Register Docker Provider

Create `src/sandbox/providers/index.ts`:

- Auto-register Docker provider on module load:
  ```typescript
  import { DockerProvider } from './docker.js';
  import { providerRegistry } from '../registry.js';
  
  providerRegistry.register(new DockerProvider());
  ```

### Phase 3: Docker Infrastructure Files

#### 3.1 Create Dockerfile

Create `docker/Dockerfile`:

```dockerfile
FROM node:20-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    curl \
    python3 \
    python3-pip \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Install Claude Code CLI
RUN npm install -g @anthropic-ai/claude-code

# Create workspace directory
WORKDIR /workspace

# Keep container running
ENTRYPOINT ["tail", "-f", "/dev/null"]
```

#### 3.2 Create Docker Compose File

Create `docker/docker-compose.yml`:

```yaml
version: '3.8'

services:
  claude-code:
    build:
      context: .
      dockerfile: Dockerfile
    image: claude-code:latest
    container_name: parallel-cc-sandbox
    volumes:
      - ../:/workspace:rw
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    network_mode: none
    security_opt:
      - no-new-privileges
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
      - FOWNER
      - SETGID
      - SETUID
    mem_limit: 4g
    cpus: 2
```

#### 3.3 Create Docker Ignore File

Create `docker/.dockerignore`:

```
node_modules
.git
dist
build
coverage
.next
__pycache__
*.pyc
.env*
*.log
```

#### 3.4 Create Docker README

Create `docker/README.md`:

- Document Docker image build process
- Provide usage examples:
  - Building the image: `docker build -t claude-code:latest .`
  - Running with docker-compose: `docker-compose up -d`
  - Using with parallel-cc: `parallel-cc sandbox-run --provider docker`
- Document resource limits and security settings
- Troubleshooting section (Docker not running, WSL2 issues on Windows)

### Phase 4: CLI Integration

#### 4.1 Update sandbox-run Command

Update `src/cli.ts` (around line 1354):

- Add `--provider` option:
  ```typescript
  .option('--provider <name>', 'Sandbox provider: docker, e2b (default: auto-detect)', 'auto')
  ```

- Add Docker-specific options:
  ```typescript
  .option('--docker-image <image>', 'Docker image to use (default: claude-code:latest)')
  .option('--docker-network <mode>', 'Docker network mode: none, bridge, host (default: none)')
  .option('--docker-memory <limit>', 'Memory limit (e.g., 4g, 2048m)', '4g')
  .option('--docker-cpus <count>', 'CPU limit (default: 2)', '2')
  ```

- Update action handler:
  ```typescript
  async (options) => {
    // Get provider
    let provider: SandboxProvider;
    if (options.provider === 'auto') {
      provider = await providerRegistry.getDefault();
    } else {
      provider = providerRegistry.get(options.provider);
      if (!provider) {
        throw new Error(`Provider '${options.provider}' not found`);
      }
    }
    
    // Check availability
    const available = await provider.isAvailable();
    if (!available) {
      throw new Error(`Provider '${provider.name}' is not available`);
    }
    
    // Build config
    const config: SandboxConfig = {
      sessionId: generateSessionId(),
      worktreePath: options.repo,
      timeoutMinutes: options.timeout,
      providerOptions: {
        // Docker-specific
        image: options.dockerImage,
        network: options.dockerNetwork,
        memory: options.dockerMemory,
        cpus: parseInt(options.dockerCpus),
        // E2B-specific
        template: options.e2bTemplate
      }
    };
    
    // Create sandbox
    const instance = await provider.create(config);
    
    // Execute command
    for await (const output of provider.execute(instance.id, command)) {
      process.stdout.write(output);
    }
    
    // Cleanup
    await provider.destroy(instance.id);
  }
  ```

#### 4.2 Update doctor Command

Update `src/cli.ts` doctor command (around line 200):

- Add Docker availability check:
  ```typescript
  // Check Docker
  try {
    execSync('docker info', { stdio: 'pipe' });
    console.log(chalk.green('✓ Docker: Available'));
    
    // Check Docker version
    const version = execSync('docker --version', { encoding: 'utf-8' }).trim();
    console.log(`  ${version}`);
  } catch {
    console.log(chalk.yellow('✗ Docker: Not available'));
    console.log('  Install: https://docs.docker.com/get-docker/');
  }
  
  // Check WSL2 on Windows
  if (process.platform === 'win32') {
    try {
      execSync('wsl --status', { stdio: 'pipe' });
      console.log(chalk.green('✓ WSL2: Available'));
    } catch {
      console.log(chalk.yellow('✗ WSL2: Not available (required for Docker on Windows)'));
      console.log('  Install: https://docs.microsoft.com/en-us/windows/wsl/install');
    }
  }
  ```

- Add provider availability check:
  ```typescript
  // Check available providers
  const providers = await providerRegistry.getAvailable();
  console.log(`\nAvailable Sandbox Providers: ${providers.length}`);
  for (const provider of providers) {
    console.log(chalk.green(`  ✓ ${provider.name} (v${provider.version})`));
  }
  ```

### Phase 5: Testing

#### 5.1 Create Docker Provider Tests

Create `tests/sandbox/docker.test.ts`:

- Mock `dockerode` module
- Test suite structure (follow patterns from `file:tests/e2b/sandbox-manager.test.ts`):
  - `describe('DockerProvider')`
    - `describe('isAvailable')` - Test Docker detection
    - `describe('create')` - Test container creation with various configs
    - `describe('execute')` - Test command execution and streaming
    - `describe('uploadFiles')` - Test no-op behavior (volume mounts)
    - `describe('downloadFiles')` - Test no-op behavior (volume mounts)
    - `describe('destroy')` - Test container cleanup
    - `describe('getHealth')` - Test health checks
    - `describe('platform-specific')` - Test Windows path conversion, WSL2 checks
    - `describe('security')` - Test input validation, capability dropping
    - `describe('error handling')` - Test Docker daemon not running, image not found, etc.

- Mock Docker container lifecycle:
  ```typescript
  const mockContainer = {
    id: 'test-container-123',
    start: vi.fn().mockResolvedValue(undefined),
    stop: vi.fn().mockResolvedValue(undefined),
    remove: vi.fn().mockResolvedValue(undefined),
    inspect: vi.fn().mockResolvedValue({ State: { Running: true } }),
    exec: vi.fn().mockResolvedValue(mockExec)
  };
  ```

- Test resource limits (memory, CPU)
- Test network isolation modes
- Test security options (capabilities, no-new-privileges)

#### 5.2 Create Provider Registry Tests

Create `tests/sandbox/registry.test.ts`:

- Test provider registration
- Test provider retrieval by name
- Test listing providers
- Test getting available providers (with mocked `isAvailable()`)
- Test default provider selection logic
- Test error handling (provider not found, no providers available)

#### 5.3 Create Integration Tests

Create `tests/sandbox/docker-integration.test.ts`:

- Mark as integration test (skip in CI if Docker not available)
- Test full workflow:
  1. Create Docker container
  2. Execute simple command (e.g., `echo "Hello"`)
  3. Verify output
  4. Cleanup container
- Test volume mounting (create file in container, verify in host)
- Test network isolation (verify no network access with `network: 'none'`)
- Test resource limits (verify container respects memory/CPU limits)

### Phase 6: Documentation

#### 6.1 Update README

Update `README.md`:

- Add Docker provider section
- Document `--provider` flag
- Add Docker installation instructions
- Add platform-specific notes (Windows/WSL2, macOS/Docker Desktop, Linux/Docker Engine)

#### 6.2 Create Docker Provider Documentation

Create `docs/docker-provider.md`:

- Overview of Docker provider
- Installation and setup
- Configuration options
- Security considerations
- Troubleshooting guide
- Comparison with E2B provider

#### 6.3 Update SANDBOX_INTEGRATION_PLAN.md

Update `SANDBOX_INTEGRATION_PLAN.md`:

- Mark Docker provider as implemented
- Update implementation status
- Add lessons learned

## Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant CLI
    participant Registry
    participant DockerProvider
    participant Docker
    participant Container

    User->>CLI: sandbox-run --provider docker
    CLI->>Registry: getProvider('docker')
    Registry-->>CLI: DockerProvider instance
    CLI->>DockerProvider: isAvailable()
    DockerProvider->>Docker: docker info
    Docker-->>DockerProvider: daemon running
    DockerProvider-->>CLI: true
    CLI->>DockerProvider: create(config)
    DockerProvider->>Docker: createContainer(options)
    Docker->>Container: create with volume mount
    Docker-->>DockerProvider: container ID
    DockerProvider-->>CLI: SandboxInstance
    CLI->>DockerProvider: execute(id, command)
    DockerProvider->>Container: exec command
    Container-->>DockerProvider: stream output
    DockerProvider-->>CLI: yield output chunks
    CLI->>User: display output
    CLI->>DockerProvider: destroy(id)
    DockerProvider->>Container: stop & remove
    Container-->>DockerProvider: cleanup complete
    DockerProvider-->>CLI: success
```

## File Structure

```
src/
├── sandbox/
│   ├── types.ts              # NEW: Provider interface & types
│   ├── registry.ts           # NEW: Provider registry
│   └── providers/
│       ├── index.ts          # NEW: Provider registration
│       └── docker.ts         # NEW: Docker implementation
├── e2b/
│   ├── sandbox-manager.ts    # EXISTING: Keep for E2B internals
│   ├── file-sync.ts          # EXISTING: Reuse for E2B
│   ├── claude-runner.ts      # EXISTING: Reuse for E2B
│   └── ...
├── types.ts                  # UPDATE: Add docker to ExecutionMode
└── cli.ts                    # UPDATE: Add --provider flag

docker/
├── Dockerfile                # NEW: Claude Code image
├── docker-compose.yml        # NEW: Local testing
├── .dockerignore             # NEW: Exclude patterns
└── README.md                 # NEW: Docker docs

tests/
└── sandbox/
    ├── docker.test.ts        # NEW: Unit tests
    ├── registry.test.ts      # NEW: Registry tests
    └── docker-integration.test.ts # NEW: Integration tests
```

## Acceptance Criteria Verification

- ✅ Container creation works - Implemented in `DockerProvider.create()`
- ✅ File mounting works correctly - Volume mounts configured in container creation
- ✅ Command execution with output streaming - Implemented with async generators in `execute()`
- ✅ Proper cleanup (stop and remove) - Implemented in `destroy()`
- ✅ Works on macOS, Linux, and Windows - Platform-specific path handling and WSL2 checks
- ✅ Integration tests pass - Comprehensive test suite created

---

Execution Information

Branch: main
Commit: 9698ef5

---

💡 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 codebase currently has E2B-specific sandbox integration (v1.0) without provider abstraction. The SandboxManager in file:src/e2b/sandbox-manager.ts is tightly coupled to E2B SDK. The ticket depends on issues #30 (SandboxProvider interface) and #32 (Provider registry) which are not yet implemented. The existing E2B implementation provides excellent patterns for file sync (file:src/e2b/file-sync.ts), command execution (file:src/e2b/claude-runner.ts), and security (input sanitization, path validation). No Docker-related files or provider abstraction exists yet.

Approach

The implementation requires a multi-phase approach: (1) Create the provider abstraction layer first (SandboxProvider interface, types, and registry) since dependencies #30 and #32 don't exist, (2) Refactor existing E2B code to implement the new interface, (3) Implement DockerProvider using dockerode library following the established patterns, (4) Create Docker infrastructure files (Dockerfile, docker-compose.yml), and (5) Add comprehensive tests. This approach ensures backward compatibility while enabling the multi-provider architecture outlined in file:SANDBOX_INTEGRATION_PLAN.md.

Implementation Steps

Phase 1: Provider Abstraction Layer (Dependencies #30 & #32)

1.1 Create Provider Interface and Types

Create file:src/e2b/providers/types.ts:

• Define SandboxProvider interface with methods:

  • name: string - Provider identifier (e.g., 'docker', 'e2b')
  • version: string - Provider version
  • isAvailable(): Promise<boolean> - Check if provider can be used
  • create(config: SandboxConfig): Promise<SandboxInstance> - Create sandbox
  • execute(instanceId: string, command: string): AsyncGenerator<string> - Execute command with streaming
  • uploadFiles(instanceId: string, files: FileList): Promise<void> - Upload files
  • downloadFiles(instanceId: string, localPath: string): Promise<DownloadResult> - Download changed files
  • destroy(instanceId: string): Promise<void> - Terminate sandbox
  • getHealth(instanceId: string): Promise<SandboxHealthCheck> - Health check

• Define SandboxConfig interface:

  • sessionId: string
  • worktreePath: string
  • timeoutMinutes?: number
  • providerOptions?: Record<string, unknown> - Provider-specific options

• Define SandboxInstance interface:

  • id: string - Sandbox/container ID
  • provider: string - Provider name
  • status: SandboxStatus - Current status
  • createdAt: Date
  • metadata?: Record<string, unknown>

• Define FileList type for file operations

• Define ExecutionChunk type for streaming output

1.2 Create Provider Registry

Create file:src/e2b/providers/registry.ts:

• Implement ProviderRegistry class:

  • register(provider: SandboxProvider): void - Register a provider
  • get(name: string): SandboxProvider | null - Get provider by name
  • list(): string[] - List available provider names
  • getAvailable(): Promise<SandboxProvider[]> - Get all available providers (checks isAvailable())
  • getDefault(): Promise<SandboxProvider> - Get default provider based on platform/config

• Create singleton instance: export const providerRegistry = new ProviderRegistry()

• Add provider selection logic:

  • Check PARALLEL_CC_SANDBOX_PROVIDER environment variable
  • Fall back to platform-specific defaults (Docker for Windows, E2B if API key exists, etc.)

1.3 Update Type Definitions

Update file:src/types.ts:

• Change ExecutionMode from 'local' | 'e2b' to 'local' | 'e2b' | 'docker'
• Add sandbox_provider field to Session interface (nullable string)
• Keep backward compatibility with existing E2B fields

Phase 2: Refactor E2B to Use Provider Interface

2.1 Create E2B Provider Adapter

Create file:src/e2b/providers/e2b-provider.ts:

• Implement E2BProvider class that implements SandboxProvider

• Wrap existing SandboxManager functionality:

  • create() → calls SandboxManager.createSandbox()
  • execute() → delegates to executeClaudeInSandbox() from file:src/e2b/claude-runner.ts
  • uploadFiles() → uses uploadToSandbox() from file:src/e2b/file-sync.ts
  • downloadFiles() → uses downloadChangedFiles() from file:src/e2b/file-sync.ts
  • destroy() → calls SandboxManager.terminateSandbox()
  • getHealth() → calls SandboxManager.monitorSandboxHealth()

• Implement isAvailable():

  • Check for E2B_API_KEY environment variable
  • Validate API key format

• Keep existing SandboxManager class for internal E2B operations

• Maintain all security features (input sanitization, timeout enforcement)

2.2 Register E2B Provider

Update file:src/e2b/providers/registry.ts:

• Auto-register E2B provider on module load:

  import { E2BProvider } from './e2b-provider.js';
  providerRegistry.register(new E2BProvider());

Phase 3: Implement Docker Provider

3.1 Install Dependencies

Add to file:package.json:

{
  "dependencies": {
    "dockerode": "^4.0.2"
  },
  "devDependencies": {
    "@types/dockerode": "^3.3.31"
  }
}

3.2 Create Docker Provider Implementation

Create file:src/e2b/providers/docker-provider.ts:

Core Implementation:

• Implement DockerProvider class that implements SandboxProvider:

  • name = 'docker'
  • version = '1.0.0'
  • defaultImage = 'claude-code:latest' (configurable via PARALLEL_CC_DOCKER_IMAGE)

• Implement isAvailable():

  • Use child_process.execSync('docker info', { stdio: 'pipe' })
  • Return true if Docker daemon is running, false otherwise
  • Catch errors gracefully (Docker not installed, daemon not running)

• Implement create(config: SandboxConfig):

  • Extract Docker-specific options from config.providerOptions:
    • image (default: claude-code:latest)
    • network (default: none for isolation)
    • memory (default: 4g)
    • cpus (default: 2)
  • Create container using dockerode:

    const container = await docker.createContainer({
      Image: image,
      Cmd: ['/bin/bash'],
      Tty: true,
      AttachStdin: true,
      AttachStdout: true,
      AttachStderr: true,
      OpenStdin: true,
      HostConfig: {
        NetworkMode: network,
        Memory: parseMemory(memory),
        CpuQuota: cpus * 100000,
        Binds: [`${config.worktreePath}:/workspace:rw`],
        SecurityOpt: ['no-new-privileges'],
        CapDrop: ['ALL'],
        CapAdd: ['CHOWN', 'DAC_OVERRIDE', 'FOWNER', 'SETGID', 'SETUID'] // Minimal caps for file operations
      },
      WorkingDir: '/workspace',
      Env: [
        `ANTHROPIC_API_KEY=${process.env.ANTHROPIC_API_KEY}`,
        `HOME=/workspace`
      ]
    });

  • Start container: await container.start()
  • Return SandboxInstance with container ID

• Implement execute(instanceId: string, command: string):

  • Get container: const container = docker.getContainer(instanceId)
  • Create exec instance:

    const exec = await container.exec({
      Cmd: ['/bin/bash', '-c', command],
      AttachStdout: true,
      AttachStderr: true,
      Tty: false
    });

  • Start exec and stream output:

    const stream = await exec.start({ Detach: false, Tty: false });
    // Use async generator to yield output line by line
    for await (const chunk of stream) {
      yield chunk.toString('utf-8');
    }

• Implement uploadFiles():

  • Since Docker uses volume mounts, files are already accessible
  • This method can be a no-op or verify mount is working
  • Log: "Files available via volume mount at /workspace"

• Implement downloadFiles():

  • Since Docker uses volume mounts, files are already in local worktree
  • This method can be a no-op or verify changes
  • Return DownloadResult with filesDownloaded: 0 (no transfer needed)

• Implement destroy(instanceId: string):

  • Get container: const container = docker.getContainer(instanceId)
  • Stop container: await container.stop({ t: 10 }) (10 second timeout)
  • Remove container: await container.remove({ force: true })
  • Handle errors gracefully (container already stopped/removed)

• Implement getHealth(instanceId: string):

  • Get container: const container = docker.getContainer(instanceId)
  • Inspect container: const info = await container.inspect()
  • Check info.State.Running
  • Return SandboxHealthCheck with status

Security Considerations:

• Validate instanceId to prevent injection (alphanumeric + hyphens only)
• Sanitize commands using same patterns from file:src/e2b/sandbox-manager.ts
• Use NetworkMode: 'none' by default to prevent network access
• Drop all capabilities except minimal required for file operations
• Use SecurityOpt: ['no-new-privileges'] to prevent privilege escalation

Platform-Specific Handling:

• Windows path conversion:

  private normalizePathForDocker(localPath: string): string {
    if (process.platform === 'win32') {
      // Convert C:\Users\... to /c/Users/...
      return localPath.replace(/\\/g, '/').replace(/^([A-Z]):/, (_, drive) => `/${drive.toLowerCase()}`);
    }
    return localPath;
  }

• Check for WSL2 on Windows:

  private async checkWSL2(): Promise<boolean> {
    if (process.platform !== 'win32') return true;
    try {
      execSync('wsl --status', { stdio: 'pipe' });
      return true;
    } catch {
      return false;
    }
  }

3.3 Register Docker Provider

Update file:src/e2b/providers/registry.ts:

• Auto-register Docker provider:

  import { DockerProvider } from './docker-provider.js';
  providerRegistry.register(new DockerProvider());

Phase 4: Docker Infrastructure Files

4.1 Create Dockerfile

Create file:docker/Dockerfile:

FROM node:20-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    curl \
    python3 \
    python3-pip \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Install Claude Code CLI
RUN npm install -g @anthropic-ai/claude-code

# Create workspace directory
WORKDIR /workspace

# Keep container running
ENTRYPOINT ["tail", "-f", "/dev/null"]

4.2 Create Docker Compose File

Create file:docker/docker-compose.yml:

version: '3.8'

services:
  claude-code:
    build:
      context: .
      dockerfile: Dockerfile
    image: claude-code:latest
    container_name: parallel-cc-sandbox
    volumes:
      - ../:/workspace:rw
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    network_mode: none
    security_opt:
      - no-new-privileges
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
      - FOWNER
      - SETGID
      - SETUID
    mem_limit: 4g
    cpus: 2

4.3 Create Docker Ignore File

Create file:docker/.dockerignore:

node_modules
.git
dist
build
coverage
.next
__pycache__
*.pyc
.env*
*.log

4.4 Create Docker README

Create file:docker/README.md:

• Document Docker image build process
• Provide usage examples:
  • Building the image: docker build -t claude-code:latest .
  • Running with docker-compose: docker-compose up -d
  • Using with parallel-cc: parallel-cc sandbox-run --provider docker
• Document resource limits and security settings
• Troubleshooting section (Docker not running, WSL2 issues on Windows)

Phase 5: CLI Integration

5.1 Update sandbox-run Command

Update file:src/cli.ts (around line 1354):

• Add --provider option:

  .option('--provider <name>', 'Sandbox provider: docker, e2b (default: auto-detect)', 'auto')

• Add Docker-specific options:

  .option('--docker-image <image>', 'Docker image to use (default: claude-code:latest)')
  .option('--docker-network <mode>', 'Docker network mode: none, bridge, host (default: none)')
  .option('--docker-memory <limit>', 'Memory limit (e.g., 4g, 2048m)', '4g')
  .option('--docker-cpus <count>', 'CPU limit (default: 2)', '2')

• Update action handler:

  async (options) => {
    // Get provider
    let provider: SandboxProvider;
    if (options.provider === 'auto') {
      provider = await providerRegistry.getDefault();
    } else {
      provider = providerRegistry.get(options.provider);
      if (!provider) {
        throw new Error(`Provider '${options.provider}' not found`);
      }
    }
    
    // Check availability
    const available = await provider.isAvailable();
    if (!available) {
      throw new Error(`Provider '${provider.name}' is not available`);
    }
    
    // Build config
    const config: SandboxConfig = {
      sessionId: generateSessionId(),
      worktreePath: options.repo,
      timeoutMinutes: options.timeout,
      providerOptions: {
        // Docker-specific
        image: options.dockerImage,
        network: options.dockerNetwork,
        memory: options.dockerMemory,
        cpus: parseInt(options.dockerCpus),
        // E2B-specific
        template: options.e2bTemplate
      }
    };
    
    // Create sandbox
    const instance = await provider.create(config);
    
    // Execute command
    for await (const output of provider.execute(instance.id, command)) {
      process.stdout.write(output);
    }
    
    // Cleanup
    await provider.destroy(instance.id);
  }

5.2 Update doctor Command

Update file:src/cli.ts doctor command (around line 200):

• Add Docker availability check:

  // Check Docker
  try {
    execSync('docker info', { stdio: 'pipe' });
    console.log(chalk.green('✓ Docker: Available'));
    
    // Check Docker version
    const version = execSync('docker --version', { encoding: 'utf-8' }).trim();
    console.log(`  ${version}`);
  } catch {
    console.log(chalk.yellow('✗ Docker: Not available'));
    console.log('  Install: https://docs.docker.com/get-docker/');
  }
  
  // Check WSL2 on Windows
  if (process.platform === 'win32') {
    try {
      execSync('wsl --status', { stdio: 'pipe' });
      console.log(chalk.green('✓ WSL2: Available'));
    } catch {
      console.log(chalk.yellow('✗ WSL2: Not available (required for Docker on Windows)'));
      console.log('  Install: https://docs.microsoft.com/en-us/windows/wsl/install');
    }
  }

• Add provider availability check:

  // Check available providers
  const providers = await providerRegistry.getAvailable();
  console.log(`\nAvailable Sandbox Providers: ${providers.length}`);
  for (const provider of providers) {
    console.log(chalk.green(`  ✓ ${provider.name} (v${provider.version})`));
  }

Phase 6: Testing

6.1 Create Docker Provider Tests

Create file:tests/e2b/docker-provider.test.ts:

• Mock dockerode module

• Test suite structure (follow patterns from file:tests/e2b/sandbox-manager.test.ts):

  • describe('DockerProvider')
    • describe('isAvailable') - Test Docker detection
    • describe('create') - Test container creation with various configs
    • describe('execute') - Test command execution and streaming
    • describe('uploadFiles') - Test no-op behavior (volume mounts)
    • describe('downloadFiles') - Test no-op behavior (volume mounts)
    • describe('destroy') - Test container cleanup
    • describe('getHealth') - Test health checks
    • describe('platform-specific') - Test Windows path conversion, WSL2 checks
    • describe('security') - Test input validation, capability dropping
    • describe('error handling') - Test Docker daemon not running, image not found, etc.

• Mock Docker container lifecycle:

  const mockContainer = {
    id: 'test-container-123',
    start: vi.fn().mockResolvedValue(undefined),
    stop: vi.fn().mockResolvedValue(undefined),
    remove: vi.fn().mockResolvedValue(undefined),
    inspect: vi.fn().mockResolvedValue({ State: { Running: true } }),
    exec: vi.fn().mockResolvedValue(mockExec)
  };

• Test resource limits (memory, CPU)

• Test network isolation modes

• Test security options (capabilities, no-new-privileges)

6.2 Create Provider Registry Tests

Create file:tests/e2b/provider-registry.test.ts:

• Test provider registration
• Test provider retrieval by name
• Test listing providers
• Test getting available providers (with mocked isAvailable())
• Test default provider selection logic
• Test error handling (provider not found, no providers available)

6.3 Create Integration Tests

Create file:tests/e2b/docker-integration.test.ts:

• Mark as integration test (skip in CI if Docker not available)
• Test full workflow:
  1. Create Docker container
  2. Execute simple command (e.g., echo "Hello")
  3. Verify output
  4. Cleanup container
• Test volume mounting (create file in container, verify in host)
• Test network isolation (verify no network access with network: 'none')
• Test resource limits (verify container respects memory/CPU limits)

6.4 Update Existing Tests

Update file:tests/e2b/sandbox-manager.test.ts:

• Ensure E2B tests still pass after refactoring
• Add tests for E2B provider adapter

Phase 7: Documentation

7.1 Update README

Update file:README.md:

• Add Docker provider section
• Document --provider flag
• Add Docker installation instructions
• Add platform-specific notes (Windows/WSL2, macOS/Docker Desktop, Linux/Docker Engine)

7.2 Create Docker Provider Documentation

Create file:docs/docker-provider.md:

• Overview of Docker provider
• Installation and setup
• Configuration options
• Security considerations
• Troubleshooting guide
• Comparison with E2B provider

7.3 Update SANDBOX_INTEGRATION_PLAN.md

Update file:SANDBOX_INTEGRATION_PLAN.md:

• Mark Docker provider as implemented
• Update implementation status
• Add lessons learned

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI
    participant Registry
    participant DockerProvider
    participant Docker
    participant Container

    User->>CLI: sandbox-run --provider docker
    CLI->>Registry: getProvider('docker')
    Registry-->>CLI: DockerProvider instance
    CLI->>DockerProvider: isAvailable()
    DockerProvider->>Docker: docker info
    Docker-->>DockerProvider: daemon running
    DockerProvider-->>CLI: true
    CLI->>DockerProvider: create(config)
    DockerProvider->>Docker: createContainer(options)
    Docker->>Container: create with volume mount
    Docker-->>DockerProvider: container ID
    DockerProvider-->>CLI: SandboxInstance
    CLI->>DockerProvider: execute(id, command)
    DockerProvider->>Container: exec command
    Container-->>DockerProvider: stream output
    DockerProvider-->>CLI: yield output chunks
    CLI->>User: display output
    CLI->>DockerProvider: destroy(id)
    DockerProvider->>Container: stop & remove
    Container-->>DockerProvider: cleanup complete
    DockerProvider-->>CLI: success

Loading

File Structure

src/
├── e2b/
│   ├── providers/
│   │   ├── types.ts              # NEW: Provider interface & types
│   │   ├── registry.ts           # NEW: Provider registry
│   │   ├── e2b-provider.ts       # NEW: E2B adapter
│   │   └── docker-provider.ts    # NEW: Docker implementation
│   ├── sandbox-manager.ts        # EXISTING: Keep for E2B internals
│   ├── file-sync.ts              # EXISTING: Reuse for E2B
│   ├── claude-runner.ts          # EXISTING: Reuse for E2B
│   └── ...
├── types.ts                      # UPDATE: Add docker to ExecutionMode
└── cli.ts                        # UPDATE: Add --provider flag

docker/
├── Dockerfile                    # NEW: Claude Code image
├── docker-compose.yml            # NEW: Local testing
├── .dockerignore                 # NEW: Exclude patterns
└── README.md                     # NEW: Docker docs

tests/
└── e2b/
    ├── docker-provider.test.ts   # NEW: Unit tests
    ├── provider-registry.test.ts # NEW: Registry tests
    ├── docker-integration.test.ts # NEW: Integration tests
    └── sandbox-manager.test.ts   # UPDATE: E2B adapter tests

Acceptance Criteria Verification

• ✅ Container creation works - Implemented in DockerProvider.create()
• ✅ File mounting works correctly - Volume mounts configured in container creation
• ✅ Command execution with output streaming - Implemented with async generators in execute()
• ✅ Proper cleanup (stop and remove) - Implemented in destroy()
• ✅ Works on macOS, Linux, and Windows - Platform-specific path handling and WSL2 checks
• ✅ Integration tests pass - Comprehensive test suite created

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently has E2B-specific sandbox integration (v1.0) without provider abstraction. The `SandboxManager` in `file:src/e2b/sandbox-manager.ts` is tightly coupled to E2B SDK. The ticket depends on issues #30 (SandboxProvider interface) and #32 (Provider registry) which are not yet implemented. The existing E2B implementation provides excellent patterns for file sync (`file:src/e2b/file-sync.ts`), command execution (`file:src/e2b/claude-runner.ts`), and security (input sanitization, path validation). No Docker-related files or provider abstraction exists yet.

## Approach

The implementation requires a multi-phase approach: (1) Create the provider abstraction layer first (SandboxProvider interface, types, and registry) since dependencies #30 and #32 don't exist, (2) Refactor existing E2B code to implement the new interface, (3) Implement DockerProvider using `dockerode` library following the established patterns, (4) Create Docker infrastructure files (Dockerfile, docker-compose.yml), and (5) Add comprehensive tests. This approach ensures backward compatibility while enabling the multi-provider architecture outlined in `file:SANDBOX_INTEGRATION_PLAN.md`.

## Implementation Steps

### Phase 1: Provider Abstraction Layer (Dependencies #30 & #32)

#### 1.1 Create Provider Interface and Types

Create `file:src/e2b/providers/types.ts`:

- Define `SandboxProvider` interface with methods:
  - `name: string` - Provider identifier (e.g., 'docker', 'e2b')
  - `version: string` - Provider version
  - `isAvailable(): Promise<boolean>` - Check if provider can be used
  - `create(config: SandboxConfig): Promise<SandboxInstance>` - Create sandbox
  - `execute(instanceId: string, command: string): AsyncGenerator<string>` - Execute command with streaming
  - `uploadFiles(instanceId: string, files: FileList): Promise<void>` - Upload files
  - `downloadFiles(instanceId: string, localPath: string): Promise<DownloadResult>` - Download changed files
  - `destroy(instanceId: string): Promise<void>` - Terminate sandbox
  - `getHealth(instanceId: string): Promise<SandboxHealthCheck>` - Health check

- Define `SandboxConfig` interface:
  - `sessionId: string`
  - `worktreePath: string`
  - `timeoutMinutes?: number`
  - `providerOptions?: Record<string, unknown>` - Provider-specific options

- Define `SandboxInstance` interface:
  - `id: string` - Sandbox/container ID
  - `provider: string` - Provider name
  - `status: SandboxStatus` - Current status
  - `createdAt: Date`
  - `metadata?: Record<string, unknown>`

- Define `FileList` type for file operations
- Define `ExecutionChunk` type for streaming output

#### 1.2 Create Provider Registry

Create `file:src/e2b/providers/registry.ts`:

- Implement `ProviderRegistry` class:
  - `register(provider: SandboxProvider): void` - Register a provider
  - `get(name: string): SandboxProvider | null` - Get provider by name
  - `list(): string[]` - List available provider names
  - `getAvailable(): Promise<SandboxProvider[]>` - Get all available providers (checks `isAvailable()`)
  - `getDefault(): Promise<SandboxProvider>` - Get default provider based on platform/config

- Create singleton instance: `export const providerRegistry = new ProviderRegistry()`

- Add provider selection logic:
  - Check `PARALLEL_CC_SANDBOX_PROVIDER` environment variable
  - Fall back to platform-specific defaults (Docker for Windows, E2B if API key exists, etc.)

#### 1.3 Update Type Definitions

Update `file:src/types.ts`:

- Change `ExecutionMode` from `'local' | 'e2b'` to `'local' | 'e2b' | 'docker'`
- Add `sandbox_provider` field to `Session` interface (nullable string)
- Keep backward compatibility with existing E2B fields

### Phase 2: Refactor E2B to Use Provider Interface

#### 2.1 Create E2B Provider Adapter

Create `file:src/e2b/providers/e2b-provider.ts`:

- Implement `E2BProvider` class that implements `SandboxProvider`
- Wrap existing `SandboxManager` functionality:
  - `create()` → calls `SandboxManager.createSandbox()`
  - `execute()` → delegates to `executeClaudeInSandbox()` from `file:src/e2b/claude-runner.ts`
  - `uploadFiles()` → uses `uploadToSandbox()` from `file:src/e2b/file-sync.ts`
  - `downloadFiles()` → uses `downloadChangedFiles()` from `file:src/e2b/file-sync.ts`
  - `destroy()` → calls `SandboxManager.terminateSandbox()`
  - `getHealth()` → calls `SandboxManager.monitorSandboxHealth()`

- Implement `isAvailable()`:
  - Check for `E2B_API_KEY` environment variable
  - Validate API key format

- Keep existing `SandboxManager` class for internal E2B operations
- Maintain all security features (input sanitization, timeout enforcement)

#### 2.2 Register E2B Provider

Update `file:src/e2b/providers/registry.ts`:

- Auto-register E2B provider on module load:
  ```typescript
  import { E2BProvider } from './e2b-provider.js';
  providerRegistry.register(new E2BProvider());
  ```

### Phase 3: Implement Docker Provider

#### 3.1 Install Dependencies

Add to `file:package.json`:
```json
{
  "dependencies": {
    "dockerode": "^4.0.2"
  },
  "devDependencies": {
    "@types/dockerode": "^3.3.31"
  }
}
```

#### 3.2 Create Docker Provider Implementation

Create `file:src/e2b/providers/docker-provider.ts`:

**Core Implementation:**

- Implement `DockerProvider` class that implements `SandboxProvider`:
  - `name = 'docker'`
  - `version = '1.0.0'`
  - `defaultImage = 'claude-code:latest'` (configurable via `PARALLEL_CC_DOCKER_IMAGE`)

- Implement `isAvailable()`:
  - Use `child_process.execSync('docker info', { stdio: 'pipe' })`
  - Return `true` if Docker daemon is running, `false` otherwise
  - Catch errors gracefully (Docker not installed, daemon not running)

- Implement `create(config: SandboxConfig)`:
  - Extract Docker-specific options from `config.providerOptions`:
    - `image` (default: `claude-code:latest`)
    - `network` (default: `none` for isolation)
    - `memory` (default: `4g`)
    - `cpus` (default: `2`)
  - Create container using `dockerode`:
    ```typescript
    const container = await docker.createContainer({
      Image: image,
      Cmd: ['/bin/bash'],
      Tty: true,
      AttachStdin: true,
      AttachStdout: true,
      AttachStderr: true,
      OpenStdin: true,
      HostConfig: {
        NetworkMode: network,
        Memory: parseMemory(memory),
        CpuQuota: cpus * 100000,
        Binds: [`${config.worktreePath}:/workspace:rw`],
        SecurityOpt: ['no-new-privileges'],
        CapDrop: ['ALL'],
        CapAdd: ['CHOWN', 'DAC_OVERRIDE', 'FOWNER', 'SETGID', 'SETUID'] // Minimal caps for file operations
      },
      WorkingDir: '/workspace',
      Env: [
        `ANTHROPIC_API_KEY=${process.env.ANTHROPIC_API_KEY}`,
        `HOME=/workspace`
      ]
    });
    ```
  - Start container: `await container.start()`
  - Return `SandboxInstance` with container ID

- Implement `execute(instanceId: string, command: string)`:
  - Get container: `const container = docker.getContainer(instanceId)`
  - Create exec instance:
    ```typescript
    const exec = await container.exec({
      Cmd: ['/bin/bash', '-c', command],
      AttachStdout: true,
      AttachStderr: true,
      Tty: false
    });
    ```
  - Start exec and stream output:
    ```typescript
    const stream = await exec.start({ Detach: false, Tty: false });
    // Use async generator to yield output line by line
    for await (const chunk of stream) {
      yield chunk.toString('utf-8');
    }
    ```

- Implement `uploadFiles()`:
  - Since Docker uses volume mounts, files are already accessible
  - This method can be a no-op or verify mount is working
  - Log: "Files available via volume mount at /workspace"

- Implement `downloadFiles()`:
  - Since Docker uses volume mounts, files are already in local worktree
  - This method can be a no-op or verify changes
  - Return `DownloadResult` with `filesDownloaded: 0` (no transfer needed)

- Implement `destroy(instanceId: string)`:
  - Get container: `const container = docker.getContainer(instanceId)`
  - Stop container: `await container.stop({ t: 10 })` (10 second timeout)
  - Remove container: `await container.remove({ force: true })`
  - Handle errors gracefully (container already stopped/removed)

- Implement `getHealth(instanceId: string)`:
  - Get container: `const container = docker.getContainer(instanceId)`
  - Inspect container: `const info = await container.inspect()`
  - Check `info.State.Running`
  - Return `SandboxHealthCheck` with status

**Security Considerations:**

- Validate `instanceId` to prevent injection (alphanumeric + hyphens only)
- Sanitize commands using same patterns from `file:src/e2b/sandbox-manager.ts`
- Use `NetworkMode: 'none'` by default to prevent network access
- Drop all capabilities except minimal required for file operations
- Use `SecurityOpt: ['no-new-privileges']` to prevent privilege escalation

**Platform-Specific Handling:**

- Windows path conversion:
  ```typescript
  private normalizePathForDocker(localPath: string): string {
    if (process.platform === 'win32') {
      // Convert C:\Users\... to /c/Users/...
      return localPath.replace(/\\/g, '/').replace(/^([A-Z]):/, (_, drive) => `/${drive.toLowerCase()}`);
    }
    return localPath;
  }
  ```

- Check for WSL2 on Windows:
  ```typescript
  private async checkWSL2(): Promise<boolean> {
    if (process.platform !== 'win32') return true;
    try {
      execSync('wsl --status', { stdio: 'pipe' });
      return true;
    } catch {
      return false;
    }
  }
  ```

#### 3.3 Register Docker Provider

Update `file:src/e2b/providers/registry.ts`:

- Auto-register Docker provider:
  ```typescript
  import { DockerProvider } from './docker-provider.js';
  providerRegistry.register(new DockerProvider());
  ```

### Phase 4: Docker Infrastructure Files

#### 4.1 Create Dockerfile

Create `file:docker/Dockerfile`:

```dockerfile
FROM node:20-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    curl \
    python3 \
    python3-pip \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Install Claude Code CLI
RUN npm install -g @anthropic-ai/claude-code

# Create workspace directory
WORKDIR /workspace

# Keep container running
ENTRYPOINT ["tail", "-f", "/dev/null"]
```

#### 4.2 Create Docker Compose File

Create `file:docker/docker-compose.yml`:

```yaml
version: '3.8'

services:
  claude-code:
    build:
      context: .
      dockerfile: Dockerfile
    image: claude-code:latest
    container_name: parallel-cc-sandbox
    volumes:
      - ../:/workspace:rw
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    network_mode: none
    security_opt:
      - no-new-privileges
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
      - FOWNER
      - SETGID
      - SETUID
    mem_limit: 4g
    cpus: 2
```

#### 4.3 Create Docker Ignore File

Create `file:docker/.dockerignore`:

```
node_modules
.git
dist
build
coverage
.next
__pycache__
*.pyc
.env*
*.log
```

#### 4.4 Create Docker README

Create `file:docker/README.md`:

- Document Docker image build process
- Provide usage examples:
  - Building the image: `docker build -t claude-code:latest .`
  - Running with docker-compose: `docker-compose up -d`
  - Using with parallel-cc: `parallel-cc sandbox-run --provider docker`
- Document resource limits and security settings
- Troubleshooting section (Docker not running, WSL2 issues on Windows)

### Phase 5: CLI Integration

#### 5.1 Update sandbox-run Command

Update `file:src/cli.ts` (around line 1354):

- Add `--provider` option:
  ```typescript
  .option('--provider <name>', 'Sandbox provider: docker, e2b (default: auto-detect)', 'auto')
  ```

- Add Docker-specific options:
  ```typescript
  .option('--docker-image <image>', 'Docker image to use (default: claude-code:latest)')
  .option('--docker-network <mode>', 'Docker network mode: none, bridge, host (default: none)')
  .option('--docker-memory <limit>', 'Memory limit (e.g., 4g, 2048m)', '4g')
  .option('--docker-cpus <count>', 'CPU limit (default: 2)', '2')
  ```

- Update action handler:
  ```typescript
  async (options) => {
    // Get provider
    let provider: SandboxProvider;
    if (options.provider === 'auto') {
      provider = await providerRegistry.getDefault();
    } else {
      provider = providerRegistry.get(options.provider);
      if (!provider) {
        throw new Error(`Provider '${options.provider}' not found`);
      }
    }
    
    // Check availability
    const available = await provider.isAvailable();
    if (!available) {
      throw new Error(`Provider '${provider.name}' is not available`);
    }
    
    // Build config
    const config: SandboxConfig = {
      sessionId: generateSessionId(),
      worktreePath: options.repo,
      timeoutMinutes: options.timeout,
      providerOptions: {
        // Docker-specific
        image: options.dockerImage,
        network: options.dockerNetwork,
        memory: options.dockerMemory,
        cpus: parseInt(options.dockerCpus),
        // E2B-specific
        template: options.e2bTemplate
      }
    };
    
    // Create sandbox
    const instance = await provider.create(config);
    
    // Execute command
    for await (const output of provider.execute(instance.id, command)) {
      process.stdout.write(output);
    }
    
    // Cleanup
    await provider.destroy(instance.id);
  }
  ```

#### 5.2 Update doctor Command

Update `file:src/cli.ts` doctor command (around line 200):

- Add Docker availability check:
  ```typescript
  // Check Docker
  try {
    execSync('docker info', { stdio: 'pipe' });
    console.log(chalk.green('✓ Docker: Available'));
    
    // Check Docker version
    const version = execSync('docker --version', { encoding: 'utf-8' }).trim();
    console.log(`  ${version}`);
  } catch {
    console.log(chalk.yellow('✗ Docker: Not available'));
    console.log('  Install: https://docs.docker.com/get-docker/');
  }
  
  // Check WSL2 on Windows
  if (process.platform === 'win32') {
    try {
      execSync('wsl --status', { stdio: 'pipe' });
      console.log(chalk.green('✓ WSL2: Available'));
    } catch {
      console.log(chalk.yellow('✗ WSL2: Not available (required for Docker on Windows)'));
      console.log('  Install: https://docs.microsoft.com/en-us/windows/wsl/install');
    }
  }
  ```

- Add provider availability check:
  ```typescript
  // Check available providers
  const providers = await providerRegistry.getAvailable();
  console.log(`\nAvailable Sandbox Providers: ${providers.length}`);
  for (const provider of providers) {
    console.log(chalk.green(`  ✓ ${provider.name} (v${provider.version})`));
  }
  ```

### Phase 6: Testing

#### 6.1 Create Docker Provider Tests

Create `file:tests/e2b/docker-provider.test.ts`:

- Mock `dockerode` module
- Test suite structure (follow patterns from `file:tests/e2b/sandbox-manager.test.ts`):
  - `describe('DockerProvider')`
    - `describe('isAvailable')` - Test Docker detection
    - `describe('create')` - Test container creation with various configs
    - `describe('execute')` - Test command execution and streaming
    - `describe('uploadFiles')` - Test no-op behavior (volume mounts)
    - `describe('downloadFiles')` - Test no-op behavior (volume mounts)
    - `describe('destroy')` - Test container cleanup
    - `describe('getHealth')` - Test health checks
    - `describe('platform-specific')` - Test Windows path conversion, WSL2 checks
    - `describe('security')` - Test input validation, capability dropping
    - `describe('error handling')` - Test Docker daemon not running, image not found, etc.

- Mock Docker container lifecycle:
  ```typescript
  const mockContainer = {
    id: 'test-container-123',
    start: vi.fn().mockResolvedValue(undefined),
    stop: vi.fn().mockResolvedValue(undefined),
    remove: vi.fn().mockResolvedValue(undefined),
    inspect: vi.fn().mockResolvedValue({ State: { Running: true } }),
    exec: vi.fn().mockResolvedValue(mockExec)
  };
  ```

- Test resource limits (memory, CPU)
- Test network isolation modes
- Test security options (capabilities, no-new-privileges)

#### 6.2 Create Provider Registry Tests

Create `file:tests/e2b/provider-registry.test.ts`:

- Test provider registration
- Test provider retrieval by name
- Test listing providers
- Test getting available providers (with mocked `isAvailable()`)
- Test default provider selection logic
- Test error handling (provider not found, no providers available)

#### 6.3 Create Integration Tests

Create `file:tests/e2b/docker-integration.test.ts`:

- Mark as integration test (skip in CI if Docker not available)
- Test full workflow:
  1. Create Docker container
  2. Execute simple command (e.g., `echo "Hello"`)
  3. Verify output
  4. Cleanup container
- Test volume mounting (create file in container, verify in host)
- Test network isolation (verify no network access with `network: 'none'`)
- Test resource limits (verify container respects memory/CPU limits)

#### 6.4 Update Existing Tests

Update `file:tests/e2b/sandbox-manager.test.ts`:

- Ensure E2B tests still pass after refactoring
- Add tests for E2B provider adapter

### Phase 7: Documentation

#### 7.1 Update README

Update `file:README.md`:

- Add Docker provider section
- Document `--provider` flag
- Add Docker installation instructions
- Add platform-specific notes (Windows/WSL2, macOS/Docker Desktop, Linux/Docker Engine)

#### 7.2 Create Docker Provider Documentation

Create `file:docs/docker-provider.md`:

- Overview of Docker provider
- Installation and setup
- Configuration options
- Security considerations
- Troubleshooting guide
- Comparison with E2B provider

#### 7.3 Update SANDBOX_INTEGRATION_PLAN.md

Update `file:SANDBOX_INTEGRATION_PLAN.md`:

- Mark Docker provider as implemented
- Update implementation status
- Add lessons learned

## Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant CLI
    participant Registry
    participant DockerProvider
    participant Docker
    participant Container

    User->>CLI: sandbox-run --provider docker
    CLI->>Registry: getProvider('docker')
    Registry-->>CLI: DockerProvider instance
    CLI->>DockerProvider: isAvailable()
    DockerProvider->>Docker: docker info
    Docker-->>DockerProvider: daemon running
    DockerProvider-->>CLI: true
    CLI->>DockerProvider: create(config)
    DockerProvider->>Docker: createContainer(options)
    Docker->>Container: create with volume mount
    Docker-->>DockerProvider: container ID
    DockerProvider-->>CLI: SandboxInstance
    CLI->>DockerProvider: execute(id, command)
    DockerProvider->>Container: exec command
    Container-->>DockerProvider: stream output
    DockerProvider-->>CLI: yield output chunks
    CLI->>User: display output
    CLI->>DockerProvider: destroy(id)
    DockerProvider->>Container: stop & remove
    Container-->>DockerProvider: cleanup complete
    DockerProvider-->>CLI: success
```

## File Structure

```
src/
├── e2b/
│   ├── providers/
│   │   ├── types.ts              # NEW: Provider interface & types
│   │   ├── registry.ts           # NEW: Provider registry
│   │   ├── e2b-provider.ts       # NEW: E2B adapter
│   │   └── docker-provider.ts    # NEW: Docker implementation
│   ├── sandbox-manager.ts        # EXISTING: Keep for E2B internals
│   ├── file-sync.ts              # EXISTING: Reuse for E2B
│   ├── claude-runner.ts          # EXISTING: Reuse for E2B
│   └── ...
├── types.ts                      # UPDATE: Add docker to ExecutionMode
└── cli.ts                        # UPDATE: Add --provider flag

docker/
├── Dockerfile                    # NEW: Claude Code image
├── docker-compose.yml            # NEW: Local testing
├── .dockerignore                 # NEW: Exclude patterns
└── README.md                     # NEW: Docker docs

tests/
└── e2b/
    ├── docker-provider.test.ts   # NEW: Unit tests
    ├── provider-registry.test.ts # NEW: Registry tests
    ├── docker-integration.test.ts # NEW: Integration tests
    └── sandbox-manager.test.ts   # UPDATE: E2B adapter tests
```

## Acceptance Criteria Verification

- ✅ Container creation works - Implemented in `DockerProvider.create()`
- ✅ File mounting works correctly - Volume mounts configured in container creation
- ✅ Command execution with output streaming - Implemented with async generators in `execute()`
- ✅ Proper cleanup (stop and remove) - Implemented in `destroy()`
- ✅ Works on macOS, Linux, and Windows - Platform-specific path handling and WSL2 checks
- ✅ Integration tests pass - Comprehensive test suite created

---

Execution Information

Branch: main
Commit: 136df60

New Plan

Observations

The codebase currently has E2B-specific sandbox integration (v1.0-v2.0) without provider abstraction. The SandboxManager in src/e2b/sandbox-manager.ts is tightly coupled to E2B SDK. The SANDBOX_INTEGRATION_PLAN.md outlines a comprehensive multi-provider architecture for v1.5+ that includes Docker, Native, E2B, Daytona, and Cloudflare providers. The existing E2B implementation provides excellent patterns for file sync (src/e2b/file-sync.ts), command execution (src/e2b/claude-runner.ts), and security (input sanitization, path validation). No Docker-related files or provider abstraction exists yet. The ticket version is updated to v2.5+ indicating this is a later phase implementation.

Approach

The implementation requires a multi-phase approach: (1) Create the provider abstraction layer first (SandboxProvider interface, types, and registry) since the architecture plan specifies this foundation, (2) Implement DockerProvider using dockerode library following the established patterns from E2B implementation, (3) Create Docker infrastructure files (Dockerfile, docker-compose.yml), (4) Add comprehensive tests, and (5) Integrate with CLI. This approach ensures backward compatibility with existing E2B code while enabling the multi-provider architecture outlined in SANDBOX_INTEGRATION_PLAN.md.

Implementation Steps

Phase 1: Provider Abstraction Layer (Dependencies #30 & #32)

1.1 Create Provider Interface and Types

Create file:src/e2b/providers/types.ts:

• Define SandboxProvider interface with methods:

  • name: string - Provider identifier (e.g., 'docker', 'e2b')
  • version: string - Provider version
  • isAvailable(): Promise<boolean> - Check if provider can be used
  • create(config: SandboxConfig): Promise<SandboxInstance> - Create sandbox
  • execute(instanceId: string, command: string): AsyncGenerator<string> - Execute command with streaming
  • uploadFiles(instanceId: string, files: FileList): Promise<void> - Upload files
  • downloadFiles(instanceId: string, localPath: string): Promise<DownloadResult> - Download changed files
  • destroy(instanceId: string): Promise<void> - Terminate sandbox
  • getHealth(instanceId: string): Promise<SandboxHealthCheck> - Health check

• Define SandboxConfig interface:

  • sessionId: string
  • worktreePath: string
  • timeoutMinutes?: number
  • providerOptions?: Record<string, unknown> - Provider-specific options

• Define SandboxInstance interface:

  • id: string - Sandbox/container ID
  • provider: string - Provider name
  • status: SandboxStatus - Current status
  • createdAt: Date
  • metadata?: Record<string, unknown>

• Define FileList type for file operations

• Define ExecutionChunk type for streaming output

1.2 Create Provider Registry

Create file:src/e2b/providers/registry.ts:

• Implement ProviderRegistry class:

  • register(provider: SandboxProvider): void - Register a provider
  • get(name: string): SandboxProvider | null - Get provider by name
  • list(): string[] - List available provider names
  • getAvailable(): Promise<SandboxProvider[]> - Get all available providers (checks isAvailable())
  • getDefault(): Promise<SandboxProvider> - Get default provider based on platform/config

• Create singleton instance: export const providerRegistry = new ProviderRegistry()

• Add provider selection logic:

  • Check PARALLEL_CC_SANDBOX_PROVIDER environment variable
  • Fall back to platform-specific defaults (Docker for Windows, E2B if API key exists, etc.)

1.3 Update Type Definitions

Update file:src/types.ts:

• Change ExecutionMode from 'local' | 'e2b' to 'local' | 'e2b' | 'docker'
• Add sandbox_provider field to Session interface (nullable string)
• Keep backward compatibility with existing E2B fields

Phase 2: Implement Docker Provider

2.1 Install Dependencies

Add to file:package.json:

{
  "dependencies": {
    "dockerode": "^4.0.2"
  },
  "devDependencies": {
    "@types/dockerode": "^3.3.31"
  }
}

2.2 Create Docker Provider Implementation

Create src/sandbox/providers/docker.ts:

Core Implementation:

• Implement DockerProvider class that implements SandboxProvider:

  • name = 'docker'
  • version = '1.0.0'
  • defaultImage = 'claude-code:latest' (configurable via PARALLEL_CC_DOCKER_IMAGE)

• Implement isAvailable():

  • Use child_process.execSync('docker info', { stdio: 'pipe' })
  • Return true if Docker daemon is running, false otherwise
  • Catch errors gracefully (Docker not installed, daemon not running)

• Implement create(config: SandboxConfig):

  • Extract Docker-specific options from config.providerOptions:
    • image (default: claude-code:latest)
    • network (default: none for isolation)
    • memory (default: 4g)
    • cpus (default: 2)
  • Create container using dockerode:

    const container = await docker.createContainer({
      Image: image,
      Cmd: ['/bin/bash'],
      Tty: true,
      AttachStdin: true,
      AttachStdout: true,
      AttachStderr: true,
      OpenStdin: true,
      HostConfig: {
        NetworkMode: network,
        Memory: parseMemory(memory),
        CpuQuota: cpus * 100000,
        Binds: [`${config.worktreePath}:/workspace:rw`],
        SecurityOpt: ['no-new-privileges'],
        CapDrop: ['ALL'],
        CapAdd: ['CHOWN', 'DAC_OVERRIDE', 'FOWNER', 'SETGID', 'SETUID'] // Minimal caps for file operations
      },
      WorkingDir: '/workspace',
      Env: [
        `ANTHROPIC_API_KEY=${process.env.ANTHROPIC_API_KEY}`,
        `HOME=/workspace`
      ]
    });

  • Start container: await container.start()
  • Return SandboxInstance with container ID

• Implement execute(instanceId: string, command: string):

  • Get container: const container = docker.getContainer(instanceId)
  • Create exec instance:

    const exec = await container.exec({
      Cmd: ['/bin/bash', '-c', command],
      AttachStdout: true,
      AttachStderr: true,
      Tty: false
    });

  • Start exec and stream output:

    const stream = await exec.start({ Detach: false, Tty: false });
    // Use async generator to yield output line by line
    for await (const chunk of stream) {
      yield chunk.toString('utf-8');
    }

• Implement uploadFiles():

  • Since Docker uses volume mounts, files are already accessible
  • This method can be a no-op or verify mount is working
  • Log: "Files available via volume mount at /workspace"

• Implement downloadFiles():

  • Since Docker uses volume mounts, files are already in local worktree
  • This method can be a no-op or verify changes
  • Return DownloadResult with filesDownloaded: 0 (no transfer needed)

• Implement destroy(instanceId: string):

  • Get container: const container = docker.getContainer(instanceId)
  • Stop container: await container.stop({ t: 10 }) (10 second timeout)
  • Remove container: await container.remove({ force: true })
  • Handle errors gracefully (container already stopped/removed)

• Implement getHealth(instanceId: string):

  • Get container: const container = docker.getContainer(instanceId)
  • Inspect container: const info = await container.inspect()
  • Check info.State.Running
  • Return SandboxHealthCheck with status

Security Considerations:

• Validate instanceId to prevent injection (alphanumeric + hyphens only)
• Sanitize commands using same patterns from file:src/e2b/sandbox-manager.ts
• Use NetworkMode: 'none' by default to prevent network access
• Drop all capabilities except minimal required for file operations
• Use SecurityOpt: ['no-new-privileges'] to prevent privilege escalation

Platform-Specific Handling:

• Windows path conversion:

  private normalizePathForDocker(localPath: string): string {
    if (process.platform === 'win32') {
      // Convert C:\Users\... to /c/Users/...
      return localPath.replace(/\\/g, '/').replace(/^([A-Z]):/, (_, drive) => `/${drive.toLowerCase()}`);
    }
    return localPath;
  }

• Check for WSL2 on Windows:

  private async checkWSL2(): Promise<boolean> {
    if (process.platform !== 'win32') return true;
    try {
      execSync('wsl --status', { stdio: 'pipe' });
      return true;
    } catch {
      return false;
    }
  }

2.3 Register Docker Provider

Create src/sandbox/providers/index.ts:

• Auto-register Docker provider on module load:

  import { DockerProvider } from './docker.js';
  import { providerRegistry } from '../registry.js';
  
  providerRegistry.register(new DockerProvider());

Phase 3: Docker Infrastructure Files

3.1 Create Dockerfile

Create docker/Dockerfile:

FROM node:20-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    curl \
    python3 \
    python3-pip \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Install Claude Code CLI
RUN npm install -g @anthropic-ai/claude-code

# Create workspace directory
WORKDIR /workspace

# Keep container running
ENTRYPOINT ["tail", "-f", "/dev/null"]

3.2 Create Docker Compose File

Create docker/docker-compose.yml:

version: '3.8'

services:
  claude-code:
    build:
      context: .
      dockerfile: Dockerfile
    image: claude-code:latest
    container_name: parallel-cc-sandbox
    volumes:
      - ../:/workspace:rw
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    network_mode: none
    security_opt:
      - no-new-privileges
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
      - FOWNER
      - SETGID
      - SETUID
    mem_limit: 4g
    cpus: 2

3.3 Create Docker Ignore File

Create docker/.dockerignore:

node_modules
.git
dist
build
coverage
.next
__pycache__
*.pyc
.env*
*.log

3.4 Create Docker README

Create docker/README.md:

• Document Docker image build process
• Provide usage examples:
  • Building the image: docker build -t claude-code:latest .
  • Running with docker-compose: docker-compose up -d
  • Using with parallel-cc: parallel-cc sandbox-run --provider docker
• Document resource limits and security settings
• Troubleshooting section (Docker not running, WSL2 issues on Windows)

Phase 4: CLI Integration

4.1 Update sandbox-run Command

Update src/cli.ts (around line 1354):

• Add --provider option:

  .option('--provider <name>', 'Sandbox provider: docker, e2b (default: auto-detect)', 'auto')

• Add Docker-specific options:

  .option('--docker-image <image>', 'Docker image to use (default: claude-code:latest)')
  .option('--docker-network <mode>', 'Docker network mode: none, bridge, host (default: none)')
  .option('--docker-memory <limit>', 'Memory limit (e.g., 4g, 2048m)', '4g')
  .option('--docker-cpus <count>', 'CPU limit (default: 2)', '2')

• Update action handler:

  async (options) => {
    // Get provider
    let provider: SandboxProvider;
    if (options.provider === 'auto') {
      provider = await providerRegistry.getDefault();
    } else {
      provider = providerRegistry.get(options.provider);
      if (!provider) {
        throw new Error(`Provider '${options.provider}' not found`);
      }
    }
    
    // Check availability
    const available = await provider.isAvailable();
    if (!available) {
      throw new Error(`Provider '${provider.name}' is not available`);
    }
    
    // Build config
    const config: SandboxConfig = {
      sessionId: generateSessionId(),
      worktreePath: options.repo,
      timeoutMinutes: options.timeout,
      providerOptions: {
        // Docker-specific
        image: options.dockerImage,
        network: options.dockerNetwork,
        memory: options.dockerMemory,
        cpus: parseInt(options.dockerCpus),
        // E2B-specific
        template: options.e2bTemplate
      }
    };
    
    // Create sandbox
    const instance = await provider.create(config);
    
    // Execute command
    for await (const output of provider.execute(instance.id, command)) {
      process.stdout.write(output);
    }
    
    // Cleanup
    await provider.destroy(instance.id);
  }

4.2 Update doctor Command

Update src/cli.ts doctor command (around line 200):

• Add Docker availability check:

  // Check Docker
  try {
    execSync('docker info', { stdio: 'pipe' });
    console.log(chalk.green('✓ Docker: Available'));
    
    // Check Docker version
    const version = execSync('docker --version', { encoding: 'utf-8' }).trim();
    console.log(`  ${version}`);
  } catch {
    console.log(chalk.yellow('✗ Docker: Not available'));
    console.log('  Install: https://docs.docker.com/get-docker/');
  }
  
  // Check WSL2 on Windows
  if (process.platform === 'win32') {
    try {
      execSync('wsl --status', { stdio: 'pipe' });
      console.log(chalk.green('✓ WSL2: Available'));
    } catch {
      console.log(chalk.yellow('✗ WSL2: Not available (required for Docker on Windows)'));
      console.log('  Install: https://docs.microsoft.com/en-us/windows/wsl/install');
    }
  }

• Add provider availability check:

  // Check available providers
  const providers = await providerRegistry.getAvailable();
  console.log(`\nAvailable Sandbox Providers: ${providers.length}`);
  for (const provider of providers) {
    console.log(chalk.green(`  ✓ ${provider.name} (v${provider.version})`));
  }

Phase 5: Testing

5.1 Create Docker Provider Tests

Create tests/sandbox/docker.test.ts:

• Mock dockerode module

• Test suite structure (follow patterns from file:tests/e2b/sandbox-manager.test.ts):

  • describe('DockerProvider')
    • describe('isAvailable') - Test Docker detection
    • describe('create') - Test container creation with various configs
    • describe('execute') - Test command execution and streaming
    • describe('uploadFiles') - Test no-op behavior (volume mounts)
    • describe('downloadFiles') - Test no-op behavior (volume mounts)
    • describe('destroy') - Test container cleanup
    • describe('getHealth') - Test health checks
    • describe('platform-specific') - Test Windows path conversion, WSL2 checks
    • describe('security') - Test input validation, capability dropping
    • describe('error handling') - Test Docker daemon not running, image not found, etc.

• Mock Docker container lifecycle:

  const mockContainer = {
    id: 'test-container-123',
    start: vi.fn().mockResolvedValue(undefined),
    stop: vi.fn().mockResolvedValue(undefined),
    remove: vi.fn().mockResolvedValue(undefined),
    inspect: vi.fn().mockResolvedValue({ State: { Running: true } }),
    exec: vi.fn().mockResolvedValue(mockExec)
  };

• Test resource limits (memory, CPU)

• Test network isolation modes

• Test security options (capabilities, no-new-privileges)

5.2 Create Provider Registry Tests

Create tests/sandbox/registry.test.ts:

• Test provider registration
• Test provider retrieval by name
• Test listing providers
• Test getting available providers (with mocked isAvailable())
• Test default provider selection logic
• Test error handling (provider not found, no providers available)

5.3 Create Integration Tests

Create tests/sandbox/docker-integration.test.ts:

• Mark as integration test (skip in CI if Docker not available)
• Test full workflow:
  1. Create Docker container
  2. Execute simple command (e.g., echo "Hello")
  3. Verify output
  4. Cleanup container
• Test volume mounting (create file in container, verify in host)
• Test network isolation (verify no network access with network: 'none')
• Test resource limits (verify container respects memory/CPU limits)

Phase 6: Documentation

6.1 Update README

Update README.md:

• Add Docker provider section
• Document --provider flag
• Add Docker installation instructions
• Add platform-specific notes (Windows/WSL2, macOS/Docker Desktop, Linux/Docker Engine)

6.2 Create Docker Provider Documentation

Create docs/docker-provider.md:

• Overview of Docker provider
• Installation and setup
• Configuration options
• Security considerations
• Troubleshooting guide
• Comparison with E2B provider

6.3 Update SANDBOX_INTEGRATION_PLAN.md

Update SANDBOX_INTEGRATION_PLAN.md:

• Mark Docker provider as implemented
• Update implementation status
• Add lessons learned

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI
    participant Registry
    participant DockerProvider
    participant Docker
    participant Container

    User->>CLI: sandbox-run --provider docker
    CLI->>Registry: getProvider('docker')
    Registry-->>CLI: DockerProvider instance
    CLI->>DockerProvider: isAvailable()
    DockerProvider->>Docker: docker info
    Docker-->>DockerProvider: daemon running
    DockerProvider-->>CLI: true
    CLI->>DockerProvider: create(config)
    DockerProvider->>Docker: createContainer(options)
    Docker->>Container: create with volume mount
    Docker-->>DockerProvider: container ID
    DockerProvider-->>CLI: SandboxInstance
    CLI->>DockerProvider: execute(id, command)
    DockerProvider->>Container: exec command
    Container-->>DockerProvider: stream output
    DockerProvider-->>CLI: yield output chunks
    CLI->>User: display output
    CLI->>DockerProvider: destroy(id)
    DockerProvider->>Container: stop & remove
    Container-->>DockerProvider: cleanup complete
    DockerProvider-->>CLI: success

Loading

File Structure

src/
├── sandbox/
│   ├── types.ts              # NEW: Provider interface & types
│   ├── registry.ts           # NEW: Provider registry
│   └── providers/
│       ├── index.ts          # NEW: Provider registration
│       └── docker.ts         # NEW: Docker implementation
├── e2b/
│   ├── sandbox-manager.ts    # EXISTING: Keep for E2B internals
│   ├── file-sync.ts          # EXISTING: Reuse for E2B
│   ├── claude-runner.ts      # EXISTING: Reuse for E2B
│   └── ...
├── types.ts                  # UPDATE: Add docker to ExecutionMode
└── cli.ts                    # UPDATE: Add --provider flag

docker/
├── Dockerfile                # NEW: Claude Code image
├── docker-compose.yml        # NEW: Local testing
├── .dockerignore             # NEW: Exclude patterns
└── README.md                 # NEW: Docker docs

tests/
└── sandbox/
    ├── docker.test.ts        # NEW: Unit tests
    ├── registry.test.ts      # NEW: Registry tests
    └── docker-integration.test.ts # NEW: Integration tests

Acceptance Criteria Verification

• ✅ Container creation works - Implemented in DockerProvider.create()
• ✅ File mounting works correctly - Volume mounts configured in container creation
• ✅ Command execution with output streaming - Implemented with async generators in execute()
• ✅ Proper cleanup (stop and remove) - Implemented in destroy()
• ✅ Works on macOS, Linux, and Windows - Platform-specific path handling and WSL2 checks
• ✅ Integration tests pass - Comprehensive test suite created

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently has E2B-specific sandbox integration (v1.0-v2.0) without provider abstraction. The `SandboxManager` in `src/e2b/sandbox-manager.ts` is tightly coupled to E2B SDK. The `SANDBOX_INTEGRATION_PLAN.md` outlines a comprehensive multi-provider architecture for v1.5+ that includes Docker, Native, E2B, Daytona, and Cloudflare providers. The existing E2B implementation provides excellent patterns for file sync (`src/e2b/file-sync.ts`), command execution (`src/e2b/claude-runner.ts`), and security (input sanitization, path validation). No Docker-related files or provider abstraction exists yet. The ticket version is updated to v2.5+ indicating this is a later phase implementation.

## Approach

The implementation requires a multi-phase approach: (1) Create the provider abstraction layer first (SandboxProvider interface, types, and registry) since the architecture plan specifies this foundation, (2) Implement DockerProvider using `dockerode` library following the established patterns from E2B implementation, (3) Create Docker infrastructure files (Dockerfile, docker-compose.yml), (4) Add comprehensive tests, and (5) Integrate with CLI. This approach ensures backward compatibility with existing E2B code while enabling the multi-provider architecture outlined in `SANDBOX_INTEGRATION_PLAN.md`.

## Implementation Steps

### Phase 1: Provider Abstraction Layer (Dependencies #30 & #32)

#### 1.1 Create Provider Interface and Types

Create `file:src/e2b/providers/types.ts`:

- Define `SandboxProvider` interface with methods:
  - `name: string` - Provider identifier (e.g., 'docker', 'e2b')
  - `version: string` - Provider version
  - `isAvailable(): Promise<boolean>` - Check if provider can be used
  - `create(config: SandboxConfig): Promise<SandboxInstance>` - Create sandbox
  - `execute(instanceId: string, command: string): AsyncGenerator<string>` - Execute command with streaming
  - `uploadFiles(instanceId: string, files: FileList): Promise<void>` - Upload files
  - `downloadFiles(instanceId: string, localPath: string): Promise<DownloadResult>` - Download changed files
  - `destroy(instanceId: string): Promise<void>` - Terminate sandbox
  - `getHealth(instanceId: string): Promise<SandboxHealthCheck>` - Health check

- Define `SandboxConfig` interface:
  - `sessionId: string`
  - `worktreePath: string`
  - `timeoutMinutes?: number`
  - `providerOptions?: Record<string, unknown>` - Provider-specific options

- Define `SandboxInstance` interface:
  - `id: string` - Sandbox/container ID
  - `provider: string` - Provider name
  - `status: SandboxStatus` - Current status
  - `createdAt: Date`
  - `metadata?: Record<string, unknown>`

- Define `FileList` type for file operations
- Define `ExecutionChunk` type for streaming output

#### 1.2 Create Provider Registry

Create `file:src/e2b/providers/registry.ts`:

- Implement `ProviderRegistry` class:
  - `register(provider: SandboxProvider): void` - Register a provider
  - `get(name: string): SandboxProvider | null` - Get provider by name
  - `list(): string[]` - List available provider names
  - `getAvailable(): Promise<SandboxProvider[]>` - Get all available providers (checks `isAvailable()`)
  - `getDefault(): Promise<SandboxProvider>` - Get default provider based on platform/config

- Create singleton instance: `export const providerRegistry = new ProviderRegistry()`

- Add provider selection logic:
  - Check `PARALLEL_CC_SANDBOX_PROVIDER` environment variable
  - Fall back to platform-specific defaults (Docker for Windows, E2B if API key exists, etc.)

#### 1.3 Update Type Definitions

Update `file:src/types.ts`:

- Change `ExecutionMode` from `'local' | 'e2b'` to `'local' | 'e2b' | 'docker'`
- Add `sandbox_provider` field to `Session` interface (nullable string)
- Keep backward compatibility with existing E2B fields

### Phase 2: Implement Docker Provider

#### 2.1 Install Dependencies

Add to `file:package.json`:
```json
{
  "dependencies": {
    "dockerode": "^4.0.2"
  },
  "devDependencies": {
    "@types/dockerode": "^3.3.31"
  }
}
```

#### 2.2 Create Docker Provider Implementation

Create `src/sandbox/providers/docker.ts`:

**Core Implementation:**

- Implement `DockerProvider` class that implements `SandboxProvider`:
  - `name = 'docker'`
  - `version = '1.0.0'`
  - `defaultImage = 'claude-code:latest'` (configurable via `PARALLEL_CC_DOCKER_IMAGE`)

- Implement `isAvailable()`:
  - Use `child_process.execSync('docker info', { stdio: 'pipe' })`
  - Return `true` if Docker daemon is running, `false` otherwise
  - Catch errors gracefully (Docker not installed, daemon not running)

- Implement `create(config: SandboxConfig)`:
  - Extract Docker-specific options from `config.providerOptions`:
    - `image` (default: `claude-code:latest`)
    - `network` (default: `none` for isolation)
    - `memory` (default: `4g`)
    - `cpus` (default: `2`)
  - Create container using `dockerode`:
    ```typescript
    const container = await docker.createContainer({
      Image: image,
      Cmd: ['/bin/bash'],
      Tty: true,
      AttachStdin: true,
      AttachStdout: true,
      AttachStderr: true,
      OpenStdin: true,
      HostConfig: {
        NetworkMode: network,
        Memory: parseMemory(memory),
        CpuQuota: cpus * 100000,
        Binds: [`${config.worktreePath}:/workspace:rw`],
        SecurityOpt: ['no-new-privileges'],
        CapDrop: ['ALL'],
        CapAdd: ['CHOWN', 'DAC_OVERRIDE', 'FOWNER', 'SETGID', 'SETUID'] // Minimal caps for file operations
      },
      WorkingDir: '/workspace',
      Env: [
        `ANTHROPIC_API_KEY=${process.env.ANTHROPIC_API_KEY}`,
        `HOME=/workspace`
      ]
    });
    ```
  - Start container: `await container.start()`
  - Return `SandboxInstance` with container ID

- Implement `execute(instanceId: string, command: string)`:
  - Get container: `const container = docker.getContainer(instanceId)`
  - Create exec instance:
    ```typescript
    const exec = await container.exec({
      Cmd: ['/bin/bash', '-c', command],
      AttachStdout: true,
      AttachStderr: true,
      Tty: false
    });
    ```
  - Start exec and stream output:
    ```typescript
    const stream = await exec.start({ Detach: false, Tty: false });
    // Use async generator to yield output line by line
    for await (const chunk of stream) {
      yield chunk.toString('utf-8');
    }
    ```

- Implement `uploadFiles()`:
  - Since Docker uses volume mounts, files are already accessible
  - This method can be a no-op or verify mount is working
  - Log: "Files available via volume mount at /workspace"

- Implement `downloadFiles()`:
  - Since Docker uses volume mounts, files are already in local worktree
  - This method can be a no-op or verify changes
  - Return `DownloadResult` with `filesDownloaded: 0` (no transfer needed)

- Implement `destroy(instanceId: string)`:
  - Get container: `const container = docker.getContainer(instanceId)`
  - Stop container: `await container.stop({ t: 10 })` (10 second timeout)
  - Remove container: `await container.remove({ force: true })`
  - Handle errors gracefully (container already stopped/removed)

- Implement `getHealth(instanceId: string)`:
  - Get container: `const container = docker.getContainer(instanceId)`
  - Inspect container: `const info = await container.inspect()`
  - Check `info.State.Running`
  - Return `SandboxHealthCheck` with status

**Security Considerations:**

- Validate `instanceId` to prevent injection (alphanumeric + hyphens only)
- Sanitize commands using same patterns from `file:src/e2b/sandbox-manager.ts`
- Use `NetworkMode: 'none'` by default to prevent network access
- Drop all capabilities except minimal required for file operations
- Use `SecurityOpt: ['no-new-privileges']` to prevent privilege escalation

**Platform-Specific Handling:**

- Windows path conversion:
  ```typescript
  private normalizePathForDocker(localPath: string): string {
    if (process.platform === 'win32') {
      // Convert C:\Users\... to /c/Users/...
      return localPath.replace(/\\/g, '/').replace(/^([A-Z]):/, (_, drive) => `/${drive.toLowerCase()}`);
    }
    return localPath;
  }
  ```

- Check for WSL2 on Windows:
  ```typescript
  private async checkWSL2(): Promise<boolean> {
    if (process.platform !== 'win32') return true;
    try {
      execSync('wsl --status', { stdio: 'pipe' });
      return true;
    } catch {
      return false;
    }
  }
  ```

#### 2.3 Register Docker Provider

Create `src/sandbox/providers/index.ts`:

- Auto-register Docker provider on module load:
  ```typescript
  import { DockerProvider } from './docker.js';
  import { providerRegistry } from '../registry.js';
  
  providerRegistry.register(new DockerProvider());
  ```

### Phase 3: Docker Infrastructure Files

#### 3.1 Create Dockerfile

Create `docker/Dockerfile`:

```dockerfile
FROM node:20-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    curl \
    python3 \
    python3-pip \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Install Claude Code CLI
RUN npm install -g @anthropic-ai/claude-code

# Create workspace directory
WORKDIR /workspace

# Keep container running
ENTRYPOINT ["tail", "-f", "/dev/null"]
```

#### 3.2 Create Docker Compose File

Create `docker/docker-compose.yml`:

```yaml
version: '3.8'

services:
  claude-code:
    build:
      context: .
      dockerfile: Dockerfile
    image: claude-code:latest
    container_name: parallel-cc-sandbox
    volumes:
      - ../:/workspace:rw
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    network_mode: none
    security_opt:
      - no-new-privileges
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
      - FOWNER
      - SETGID
      - SETUID
    mem_limit: 4g
    cpus: 2
```

#### 3.3 Create Docker Ignore File

Create `docker/.dockerignore`:

```
node_modules
.git
dist
build
coverage
.next
__pycache__
*.pyc
.env*
*.log
```

#### 3.4 Create Docker README

Create `docker/README.md`:

- Document Docker image build process
- Provide usage examples:
  - Building the image: `docker build -t claude-code:latest .`
  - Running with docker-compose: `docker-compose up -d`
  - Using with parallel-cc: `parallel-cc sandbox-run --provider docker`
- Document resource limits and security settings
- Troubleshooting section (Docker not running, WSL2 issues on Windows)

### Phase 4: CLI Integration

#### 4.1 Update sandbox-run Command

Update `src/cli.ts` (around line 1354):

- Add `--provider` option:
  ```typescript
  .option('--provider <name>', 'Sandbox provider: docker, e2b (default: auto-detect)', 'auto')
  ```

- Add Docker-specific options:
  ```typescript
  .option('--docker-image <image>', 'Docker image to use (default: claude-code:latest)')
  .option('--docker-network <mode>', 'Docker network mode: none, bridge, host (default: none)')
  .option('--docker-memory <limit>', 'Memory limit (e.g., 4g, 2048m)', '4g')
  .option('--docker-cpus <count>', 'CPU limit (default: 2)', '2')
  ```

- Update action handler:
  ```typescript
  async (options) => {
    // Get provider
    let provider: SandboxProvider;
    if (options.provider === 'auto') {
      provider = await providerRegistry.getDefault();
    } else {
      provider = providerRegistry.get(options.provider);
      if (!provider) {
        throw new Error(`Provider '${options.provider}' not found`);
      }
    }
    
    // Check availability
    const available = await provider.isAvailable();
    if (!available) {
      throw new Error(`Provider '${provider.name}' is not available`);
    }
    
    // Build config
    const config: SandboxConfig = {
      sessionId: generateSessionId(),
      worktreePath: options.repo,
      timeoutMinutes: options.timeout,
      providerOptions: {
        // Docker-specific
        image: options.dockerImage,
        network: options.dockerNetwork,
        memory: options.dockerMemory,
        cpus: parseInt(options.dockerCpus),
        // E2B-specific
        template: options.e2bTemplate
      }
    };
    
    // Create sandbox
    const instance = await provider.create(config);
    
    // Execute command
    for await (const output of provider.execute(instance.id, command)) {
      process.stdout.write(output);
    }
    
    // Cleanup
    await provider.destroy(instance.id);
  }
  ```

#### 4.2 Update doctor Command

Update `src/cli.ts` doctor command (around line 200):

- Add Docker availability check:
  ```typescript
  // Check Docker
  try {
    execSync('docker info', { stdio: 'pipe' });
    console.log(chalk.green('✓ Docker: Available'));
    
    // Check Docker version
    const version = execSync('docker --version', { encoding: 'utf-8' }).trim();
    console.log(`  ${version}`);
  } catch {
    console.log(chalk.yellow('✗ Docker: Not available'));
    console.log('  Install: https://docs.docker.com/get-docker/');
  }
  
  // Check WSL2 on Windows
  if (process.platform === 'win32') {
    try {
      execSync('wsl --status', { stdio: 'pipe' });
      console.log(chalk.green('✓ WSL2: Available'));
    } catch {
      console.log(chalk.yellow('✗ WSL2: Not available (required for Docker on Windows)'));
      console.log('  Install: https://docs.microsoft.com/en-us/windows/wsl/install');
    }
  }
  ```

- Add provider availability check:
  ```typescript
  // Check available providers
  const providers = await providerRegistry.getAvailable();
  console.log(`\nAvailable Sandbox Providers: ${providers.length}`);
  for (const provider of providers) {
    console.log(chalk.green(`  ✓ ${provider.name} (v${provider.version})`));
  }
  ```

### Phase 5: Testing

#### 5.1 Create Docker Provider Tests

Create `tests/sandbox/docker.test.ts`:

- Mock `dockerode` module
- Test suite structure (follow patterns from `file:tests/e2b/sandbox-manager.test.ts`):
  - `describe('DockerProvider')`
    - `describe('isAvailable')` - Test Docker detection
    - `describe('create')` - Test container creation with various configs
    - `describe('execute')` - Test command execution and streaming
    - `describe('uploadFiles')` - Test no-op behavior (volume mounts)
    - `describe('downloadFiles')` - Test no-op behavior (volume mounts)
    - `describe('destroy')` - Test container cleanup
    - `describe('getHealth')` - Test health checks
    - `describe('platform-specific')` - Test Windows path conversion, WSL2 checks
    - `describe('security')` - Test input validation, capability dropping
    - `describe('error handling')` - Test Docker daemon not running, image not found, etc.

- Mock Docker container lifecycle:
  ```typescript
  const mockContainer = {
    id: 'test-container-123',
    start: vi.fn().mockResolvedValue(undefined),
    stop: vi.fn().mockResolvedValue(undefined),
    remove: vi.fn().mockResolvedValue(undefined),
    inspect: vi.fn().mockResolvedValue({ State: { Running: true } }),
    exec: vi.fn().mockResolvedValue(mockExec)
  };
  ```

- Test resource limits (memory, CPU)
- Test network isolation modes
- Test security options (capabilities, no-new-privileges)

#### 5.2 Create Provider Registry Tests

Create `tests/sandbox/registry.test.ts`:

- Test provider registration
- Test provider retrieval by name
- Test listing providers
- Test getting available providers (with mocked `isAvailable()`)
- Test default provider selection logic
- Test error handling (provider not found, no providers available)

#### 5.3 Create Integration Tests

Create `tests/sandbox/docker-integration.test.ts`:

- Mark as integration test (skip in CI if Docker not available)
- Test full workflow:
  1. Create Docker container
  2. Execute simple command (e.g., `echo "Hello"`)
  3. Verify output
  4. Cleanup container
- Test volume mounting (create file in container, verify in host)
- Test network isolation (verify no network access with `network: 'none'`)
- Test resource limits (verify container respects memory/CPU limits)

### Phase 6: Documentation

#### 6.1 Update README

Update `README.md`:

- Add Docker provider section
- Document `--provider` flag
- Add Docker installation instructions
- Add platform-specific notes (Windows/WSL2, macOS/Docker Desktop, Linux/Docker Engine)

#### 6.2 Create Docker Provider Documentation

Create `docs/docker-provider.md`:

- Overview of Docker provider
- Installation and setup
- Configuration options
- Security considerations
- Troubleshooting guide
- Comparison with E2B provider

#### 6.3 Update SANDBOX_INTEGRATION_PLAN.md

Update `SANDBOX_INTEGRATION_PLAN.md`:

- Mark Docker provider as implemented
- Update implementation status
- Add lessons learned

## Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant CLI
    participant Registry
    participant DockerProvider
    participant Docker
    participant Container

    User->>CLI: sandbox-run --provider docker
    CLI->>Registry: getProvider('docker')
    Registry-->>CLI: DockerProvider instance
    CLI->>DockerProvider: isAvailable()
    DockerProvider->>Docker: docker info
    Docker-->>DockerProvider: daemon running
    DockerProvider-->>CLI: true
    CLI->>DockerProvider: create(config)
    DockerProvider->>Docker: createContainer(options)
    Docker->>Container: create with volume mount
    Docker-->>DockerProvider: container ID
    DockerProvider-->>CLI: SandboxInstance
    CLI->>DockerProvider: execute(id, command)
    DockerProvider->>Container: exec command
    Container-->>DockerProvider: stream output
    DockerProvider-->>CLI: yield output chunks
    CLI->>User: display output
    CLI->>DockerProvider: destroy(id)
    DockerProvider->>Container: stop & remove
    Container-->>DockerProvider: cleanup complete
    DockerProvider-->>CLI: success
```

## File Structure

```
src/
├── sandbox/
│   ├── types.ts              # NEW: Provider interface & types
│   ├── registry.ts           # NEW: Provider registry
│   └── providers/
│       ├── index.ts          # NEW: Provider registration
│       └── docker.ts         # NEW: Docker implementation
├── e2b/
│   ├── sandbox-manager.ts    # EXISTING: Keep for E2B internals
│   ├── file-sync.ts          # EXISTING: Reuse for E2B
│   ├── claude-runner.ts      # EXISTING: Reuse for E2B
│   └── ...
├── types.ts                  # UPDATE: Add docker to ExecutionMode
└── cli.ts                    # UPDATE: Add --provider flag

docker/
├── Dockerfile                # NEW: Claude Code image
├── docker-compose.yml        # NEW: Local testing
├── .dockerignore             # NEW: Exclude patterns
└── README.md                 # NEW: Docker docs

tests/
└── sandbox/
    ├── docker.test.ts        # NEW: Unit tests
    ├── registry.test.ts      # NEW: Registry tests
    └── docker-integration.test.ts # NEW: Integration tests
```

## Acceptance Criteria Verification

- ✅ Container creation works - Implemented in `DockerProvider.create()`
- ✅ File mounting works correctly - Volume mounts configured in container creation
- ✅ Command execution with output streaming - Implemented with async generators in `execute()`
- ✅ Proper cleanup (stop and remove) - Implemented in `destroy()`
- ✅ Works on macOS, Linux, and Windows - Platform-specific path handling and WSL2 checks
- ✅ Integration tests pass - Comprehensive test suite created

---

Execution Information

Branch: main
Commit: 9698ef5