[v2.5] Add --provider CLI flag to sandbox run

[frankbria]

Overview

Add a `--provider` flag to the `sandbox-run` command to allow users to choose which sandbox provider to use.

Usage

# Explicit provider selection
parallel-cc sandbox-run --provider e2b --repo . --prompt "Long task"
parallel-cc sandbox-run --provider native --repo . --prompt "Quick fix"
parallel-cc sandbox-run --provider docker --repo . --prompt "Cross-platform test"

# Use default provider (from config or auto-selected)
parallel-cc sandbox-run --repo . --prompt "Task"

# List available providers
parallel-cc providers list
parallel-cc providers status  # Show which are available

Provider Selection Priority

1. CLI flag (`--provider `)
2. Environment variable (`PARALLEL_CC_PROVIDER`)
3. Project config (`.parallel-cc.json`)
4. User config (`~/.parallel-cc/config.json`)
5. Auto-selection based on task characteristics

Configuration

// .parallel-cc.json (project-level)
{
  "sandbox": {
    "defaultProvider": "native"
  }
}

// ~/.parallel-cc/config.json (user-level)
{
  "sandbox": {
    "defaultProvider": "e2b",
    "providers": {
      "e2b": {
        "template": "anthropic-claude-code"
      }
    }
  }
}

Environment Variables

export PARALLEL_CC_PROVIDER=docker
export PARALLEL_CC_E2B_TEMPLATE=my-template
export PARALLEL_CC_DOCKER_IMAGE=claude-code:latest

Files to Modify

• `src/cli.ts` - Add `--provider` flag
• `src/e2b/sandbox-manager.ts` - Use provider from registry
• New: `src/config.ts` - Configuration loading

Acceptance Criteria

• `--provider` flag works correctly
• Environment variable fallback works
• Config file loading works
• Invalid provider gives clear error
• `providers list` command shows available providers
• Backward compatible (default to E2B if no flag)

Dependencies

• Depends on [v2.5] Add provider registry and factory pattern #32 (Provider registry)

[traycerai]

Plan

Observations

The codebase currently has a hardcoded E2B-only sandbox implementation in v1.0. The SandboxManager class in file:src/e2b/sandbox-manager.ts is tightly coupled to E2B SDK. The CLI uses Commander.js framework and the sandbox-run command (lines 1351-1924 in file:src/cli.ts) directly instantiates SandboxManager with E2B-specific configuration. There's no provider abstraction layer, configuration loading system, or provider registry yet. The task depends on issue #32 (Provider registry) which hasn't been implemented.

Approach

Since the provider registry (#32) is a dependency that doesn't exist yet, the implementation will create a minimal provider abstraction layer alongside the configuration system. The approach focuses on adding the --provider flag and configuration loading while maintaining 100% backward compatibility with existing E2B workflows. The provider selection will follow the specified priority chain (CLI → env → config → default), with E2B as the default to ensure no breaking changes. The implementation will be structured to easily integrate with a full provider registry when #32 is completed.

Implementation Steps

1. Create Configuration System

Create file:src/config.ts to handle configuration loading with the priority chain:

• Define SandboxConfig interface with defaultProvider and provider-specific settings
• Implement loadConfig() function that merges configurations from multiple sources in priority order:
  1. CLI flags (passed as parameters)
  2. Environment variables (PARALLEL_CC_PROVIDER, PARALLEL_CC_E2B_TEMPLATE, etc.)
  3. Project config (.parallel-cc.json in repo root)
  4. User config (~/.parallel-cc/config.json)
  5. Default values (E2B for backward compatibility)
• Use Node.js fs module to read JSON config files with error handling for missing files
• Implement environment variable parsing with proper type conversion
• Export helper functions: getProviderConfig(providerName), getDefaultProvider()

2. Create Provider Registry Foundation

Create file:src/providers/registry.ts as a minimal registry to support the CLI flag:

• Define ProviderInfo interface with fields: name, displayName, available, description
• Create ProviderRegistry class with methods:
  • register(name, info) - Register a provider
  • get(name) - Get provider info
  • list() - List all registered providers
  • isAvailable(name) - Check if provider is available (API keys, dependencies)
• Pre-register E2B provider with availability check (E2B_API_KEY present)
• Add placeholder registrations for native, docker providers (marked as unavailable with "Coming in v2.5" message)
• Export singleton instance providerRegistry

3. Update CLI with Provider Flag

Modify file:src/cli.ts in the sandbox-run command section (around line 1352):

• Add .option('--provider <name>', 'Sandbox provider (e2b, native, docker)', 'e2b') to the command definition
• Update the action handler to:
  • Load configuration using loadConfig() with CLI options
  • Resolve provider name from config (respecting priority chain)
  • Validate provider exists in registry using providerRegistry.get()
  • Check provider availability using providerRegistry.isAvailable()
  • Show clear error if provider is invalid or unavailable
  • Pass provider-specific config to SandboxManager constructor
• Maintain existing E2B logic as default path (no breaking changes)

4. Add Provider Management Commands

Add new CLI commands in file:src/cli.ts after the existing sandbox commands:

providers list command:

• Use providerRegistry.list() to get all providers
• Display table with columns: Provider, Status, Description
• Show availability status (✓ Available, ✗ Unavailable, ⚠ Missing API key)
• Use chalk for colored output matching existing CLI style

providers status command:

• Show detailed status for each provider
• For E2B: check E2B_API_KEY, show template from config
• For native/docker: show "Coming in v2.5" message
• Display current default provider from configuration
• Show configuration sources (which config file is being used)

5. Update SandboxManager for Provider Support

Modify file:src/e2b/sandbox-manager.ts to accept provider configuration:

• Update constructor to accept optional providerName parameter (default: 'e2b')
• Add validation to ensure only 'e2b' is supported in v2.5 (throw error for others)
• Update error messages to mention provider name for clarity
• Add comment indicating this will be refactored when full provider registry is implemented
• No functional changes to existing E2B logic

6. Add Configuration File Examples

Create example configuration files in file:config/ directory:

config/.parallel-cc.example.json (project-level):

{
  "sandbox": {
    "defaultProvider": "native",
    "providers": {
      "e2b": {
        "template": "anthropic-claude-code",
        "timeoutMinutes": 60
      }
    }
  }
}

config/user-config.example.json (user-level):

{
  "sandbox": {
    "defaultProvider": "e2b",
    "providers": {
      "e2b": {
        "template": "anthropic-claude-code"
      }
    }
  }
}

7. Update Type Definitions

Modify file:src/types.ts to add configuration types:

• Add ProviderName type: 'e2b' | 'native' | 'docker' | 'daytona' | 'cloudflare'
• Add ProviderConfig interface for provider-specific settings
• Add SandboxConfigFile interface matching the JSON structure
• Add ConfigSource type to track where config came from
• Export these types for use in config.ts and cli.ts

8. Update Documentation

Update file:README.md with new provider flag usage:

• Add examples showing --provider flag usage
• Document environment variables (PARALLEL_CC_PROVIDER, etc.)
• Explain configuration file locations and priority
• Add section on provider availability and v2.5 roadmap
• Update existing sandbox-run examples to show optional --provider flag

9. Add Tests

Create test files for new functionality:

file:tests/config.test.ts:

• Test configuration loading from different sources
• Test priority chain (CLI > env > project > user > default)
• Test missing config files (should not error)
• Test invalid JSON handling
• Test environment variable parsing

file:tests/providers/registry.test.ts:

• Test provider registration
• Test provider availability checks
• Test listing providers
• Test getting provider info
• Test invalid provider names

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

• Add tests for provider validation
• Test error messages for unsupported providers
• Ensure backward compatibility (no provider specified = E2B)

10. Backward Compatibility Verification

Ensure existing workflows continue to work:

• Test parallel-cc sandbox-run --repo . --prompt "task" (no provider flag) defaults to E2B
• Verify all existing E2B-specific flags still work (--template, --auth-method, etc.)
• Confirm no changes to database schema or session tracking
• Test that existing E2B sessions can be queried with sandbox-status, sandbox-logs, etc.
• Validate that error messages remain clear and actionable

Configuration Priority Flow

flowchart TD
    A[sandbox-run command] --> B{--provider flag?}
    B -->|Yes| C[Use CLI provider]
    B -->|No| D{PARALLEL_CC_PROVIDER env?}
    D -->|Yes| E[Use env provider]
    D -->|No| F{.parallel-cc.json exists?}
    F -->|Yes| G[Use project config]
    F -->|No| H{~/.parallel-cc/config.json exists?}
    H -->|Yes| I[Use user config]
    H -->|No| J[Use default: e2b]
    
    C --> K[Validate provider]
    E --> K
    G --> K
    I --> K
    J --> K
    
    K --> L{Provider available?}
    L -->|Yes| M[Create sandbox]
    L -->|No| N[Show error with setup instructions]

Loading

Provider Selection Priority Table

Priority	Source	Example	Override
1 (Highest)	CLI Flag	--provider e2b	All others
2	Environment Variable	PARALLEL_CC_PROVIDER=docker	Config files
3	Project Config	.parallel-cc.json	User config
4	User Config	~/.parallel-cc/config.json	Default
5 (Lowest)	Default	e2b	None

Files to Create

• file:src/config.ts - Configuration loading system
• file:src/providers/registry.ts - Provider registry foundation
• file:config/.parallel-cc.example.json - Project config example
• file:config/user-config.example.json - User config example
• file:tests/config.test.ts - Configuration tests
• file:tests/providers/registry.test.ts - Registry tests

Files to Modify

• file:src/cli.ts - Add --provider flag and provider commands
• file:src/e2b/sandbox-manager.ts - Accept provider parameter
• file:src/types.ts - Add configuration types
• file:README.md - Document new features
• file:tests/e2b/sandbox-manager.test.ts - Add provider validation tests

Environment Variables

Variable	Purpose	Example
PARALLEL_CC_PROVIDER	Default provider	e2b, native, docker
PARALLEL_CC_E2B_TEMPLATE	E2B sandbox template	anthropic-claude-code
PARALLEL_CC_DOCKER_IMAGE	Docker image (future)	claude-code:latest

Acceptance Criteria Mapping

• ✅ --provider flag works correctly → Step 3
• ✅ Environment variable fallback works → Step 1 (priority chain)
• ✅ Config file loading works → Step 1 (loadConfig function)
• ✅ Invalid provider gives clear error → Step 3 (validation)
• ✅ providers list command shows available providers → Step 4
• ✅ Backward compatible (default to E2B if no flag) → Steps 3, 5, 10

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently has a hardcoded E2B-only sandbox implementation in v1.0. The `SandboxManager` class in `file:src/e2b/sandbox-manager.ts` is tightly coupled to E2B SDK. The CLI uses Commander.js framework and the `sandbox-run` command (lines 1351-1924 in `file:src/cli.ts`) directly instantiates `SandboxManager` with E2B-specific configuration. There's no provider abstraction layer, configuration loading system, or provider registry yet. The task depends on issue #32 (Provider registry) which hasn't been implemented.

## Approach

Since the provider registry (#32) is a dependency that doesn't exist yet, the implementation will create a minimal provider abstraction layer alongside the configuration system. The approach focuses on adding the `--provider` flag and configuration loading while maintaining 100% backward compatibility with existing E2B workflows. The provider selection will follow the specified priority chain (CLI → env → config → default), with E2B as the default to ensure no breaking changes. The implementation will be structured to easily integrate with a full provider registry when #32 is completed.

## Implementation Steps

### 1. Create Configuration System

Create `file:src/config.ts` to handle configuration loading with the priority chain:

- Define `SandboxConfig` interface with `defaultProvider` and provider-specific settings
- Implement `loadConfig()` function that merges configurations from multiple sources in priority order:
  1. CLI flags (passed as parameters)
  2. Environment variables (`PARALLEL_CC_PROVIDER`, `PARALLEL_CC_E2B_TEMPLATE`, etc.)
  3. Project config (`.parallel-cc.json` in repo root)
  4. User config (`~/.parallel-cc/config.json`)
  5. Default values (E2B for backward compatibility)
- Use Node.js `fs` module to read JSON config files with error handling for missing files
- Implement environment variable parsing with proper type conversion
- Export helper functions: `getProviderConfig(providerName)`, `getDefaultProvider()`

### 2. Create Provider Registry Foundation

Create `file:src/providers/registry.ts` as a minimal registry to support the CLI flag:

- Define `ProviderInfo` interface with fields: `name`, `displayName`, `available`, `description`
- Create `ProviderRegistry` class with methods:
  - `register(name, info)` - Register a provider
  - `get(name)` - Get provider info
  - `list()` - List all registered providers
  - `isAvailable(name)` - Check if provider is available (API keys, dependencies)
- Pre-register E2B provider with availability check (E2B_API_KEY present)
- Add placeholder registrations for `native`, `docker` providers (marked as unavailable with "Coming in v2.5" message)
- Export singleton instance `providerRegistry`

### 3. Update CLI with Provider Flag

Modify `file:src/cli.ts` in the `sandbox-run` command section (around line 1352):

- Add `.option('--provider <name>', 'Sandbox provider (e2b, native, docker)', 'e2b')` to the command definition
- Update the action handler to:
  - Load configuration using `loadConfig()` with CLI options
  - Resolve provider name from config (respecting priority chain)
  - Validate provider exists in registry using `providerRegistry.get()`
  - Check provider availability using `providerRegistry.isAvailable()`
  - Show clear error if provider is invalid or unavailable
  - Pass provider-specific config to `SandboxManager` constructor
- Maintain existing E2B logic as default path (no breaking changes)

### 4. Add Provider Management Commands

Add new CLI commands in `file:src/cli.ts` after the existing sandbox commands:

**`providers list` command:**
- Use `providerRegistry.list()` to get all providers
- Display table with columns: Provider, Status, Description
- Show availability status (✓ Available, ✗ Unavailable, ⚠ Missing API key)
- Use `chalk` for colored output matching existing CLI style

**`providers status` command:**
- Show detailed status for each provider
- For E2B: check E2B_API_KEY, show template from config
- For native/docker: show "Coming in v2.5" message
- Display current default provider from configuration
- Show configuration sources (which config file is being used)

### 5. Update SandboxManager for Provider Support

Modify `file:src/e2b/sandbox-manager.ts` to accept provider configuration:

- Update constructor to accept optional `providerName` parameter (default: 'e2b')
- Add validation to ensure only 'e2b' is supported in v2.5 (throw error for others)
- Update error messages to mention provider name for clarity
- Add comment indicating this will be refactored when full provider registry is implemented
- No functional changes to existing E2B logic

### 6. Add Configuration File Examples

Create example configuration files in `file:config/` directory:

**`config/.parallel-cc.example.json`** (project-level):
```json
{
  "sandbox": {
    "defaultProvider": "native",
    "providers": {
      "e2b": {
        "template": "anthropic-claude-code",
        "timeoutMinutes": 60
      }
    }
  }
}
```

**`config/user-config.example.json`** (user-level):
```json
{
  "sandbox": {
    "defaultProvider": "e2b",
    "providers": {
      "e2b": {
        "template": "anthropic-claude-code"
      }
    }
  }
}
```

### 7. Update Type Definitions

Modify `file:src/types.ts` to add configuration types:

- Add `ProviderName` type: `'e2b' | 'native' | 'docker' | 'daytona' | 'cloudflare'`
- Add `ProviderConfig` interface for provider-specific settings
- Add `SandboxConfigFile` interface matching the JSON structure
- Add `ConfigSource` type to track where config came from
- Export these types for use in config.ts and cli.ts

### 8. Update Documentation

Update `file:README.md` with new provider flag usage:

- Add examples showing `--provider` flag usage
- Document environment variables (PARALLEL_CC_PROVIDER, etc.)
- Explain configuration file locations and priority
- Add section on provider availability and v2.5 roadmap
- Update existing sandbox-run examples to show optional `--provider` flag

### 9. Add Tests

Create test files for new functionality:

**`file:tests/config.test.ts`:**
- Test configuration loading from different sources
- Test priority chain (CLI > env > project > user > default)
- Test missing config files (should not error)
- Test invalid JSON handling
- Test environment variable parsing

**`file:tests/providers/registry.test.ts`:**
- Test provider registration
- Test provider availability checks
- Test listing providers
- Test getting provider info
- Test invalid provider names

**Update `file:tests/e2b/sandbox-manager.test.ts`:**
- Add tests for provider validation
- Test error messages for unsupported providers
- Ensure backward compatibility (no provider specified = E2B)

### 10. Backward Compatibility Verification

Ensure existing workflows continue to work:

- Test `parallel-cc sandbox-run --repo . --prompt "task"` (no provider flag) defaults to E2B
- Verify all existing E2B-specific flags still work (`--template`, `--auth-method`, etc.)
- Confirm no changes to database schema or session tracking
- Test that existing E2B sessions can be queried with `sandbox-status`, `sandbox-logs`, etc.
- Validate that error messages remain clear and actionable

## Configuration Priority Flow

```mermaid
flowchart TD
    A[sandbox-run command] --> B{--provider flag?}
    B -->|Yes| C[Use CLI provider]
    B -->|No| D{PARALLEL_CC_PROVIDER env?}
    D -->|Yes| E[Use env provider]
    D -->|No| F{.parallel-cc.json exists?}
    F -->|Yes| G[Use project config]
    F -->|No| H{~/.parallel-cc/config.json exists?}
    H -->|Yes| I[Use user config]
    H -->|No| J[Use default: e2b]
    
    C --> K[Validate provider]
    E --> K
    G --> K
    I --> K
    J --> K
    
    K --> L{Provider available?}
    L -->|Yes| M[Create sandbox]
    L -->|No| N[Show error with setup instructions]
```

## Provider Selection Priority Table

| Priority | Source | Example | Override |
|----------|--------|---------|----------|
| 1 (Highest) | CLI Flag | `--provider e2b` | All others |
| 2 | Environment Variable | `PARALLEL_CC_PROVIDER=docker` | Config files |
| 3 | Project Config | `.parallel-cc.json` | User config |
| 4 | User Config | `~/.parallel-cc/config.json` | Default |
| 5 (Lowest) | Default | `e2b` | None |

## Files to Create

- `file:src/config.ts` - Configuration loading system
- `file:src/providers/registry.ts` - Provider registry foundation
- `file:config/.parallel-cc.example.json` - Project config example
- `file:config/user-config.example.json` - User config example
- `file:tests/config.test.ts` - Configuration tests
- `file:tests/providers/registry.test.ts` - Registry tests

## Files to Modify

- `file:src/cli.ts` - Add `--provider` flag and provider commands
- `file:src/e2b/sandbox-manager.ts` - Accept provider parameter
- `file:src/types.ts` - Add configuration types
- `file:README.md` - Document new features
- `file:tests/e2b/sandbox-manager.test.ts` - Add provider validation tests

## Environment Variables

| Variable | Purpose | Example |
|----------|---------|---------|
| `PARALLEL_CC_PROVIDER` | Default provider | `e2b`, `native`, `docker` |
| `PARALLEL_CC_E2B_TEMPLATE` | E2B sandbox template | `anthropic-claude-code` |
| `PARALLEL_CC_DOCKER_IMAGE` | Docker image (future) | `claude-code:latest` |

## Acceptance Criteria Mapping

- ✅ `--provider` flag works correctly → Step 3
- ✅ Environment variable fallback works → Step 1 (priority chain)
- ✅ Config file loading works → Step 1 (loadConfig function)
- ✅ Invalid provider gives clear error → Step 3 (validation)
- ✅ `providers list` command shows available providers → Step 4
- ✅ Backward compatible (default to E2B if no flag) → Steps 3, 5, 10

---

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.

[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]
#7 - Fix sandbox-run command database schema mismatch [merged]
#11 - feat: Use anthropic-claude-code E2B template with fallback installation [merged]
#44 - feat(e2b): add configurable git identity for sandbox commits [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]

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

Previous Plan

Observations

The codebase currently has a hardcoded E2B-only sandbox implementation in v1.0. The SandboxManager class in file:src/e2b/sandbox-manager.ts is tightly coupled to E2B SDK. The CLI uses Commander.js framework and the sandbox-run command (lines 1351-1924 in file:src/cli.ts) directly instantiates SandboxManager with E2B-specific configuration. There's no provider abstraction layer, configuration loading system, or provider registry yet. The task depends on issue #32 (Provider registry) which hasn't been implemented.

Approach

Since the provider registry (#32) is a dependency that doesn't exist yet, the implementation will create a minimal provider abstraction layer alongside the configuration system. The approach focuses on adding the --provider flag and configuration loading while maintaining 100% backward compatibility with existing E2B workflows. The provider selection will follow the specified priority chain (CLI → env → config → default), with E2B as the default to ensure no breaking changes. The implementation will be structured to easily integrate with a full provider registry when #32 is completed.

Implementation Steps

1. Create Configuration System

Create file:src/config.ts to handle configuration loading with the priority chain:

• Define SandboxConfig interface with defaultProvider and provider-specific settings
• Implement loadConfig() function that merges configurations from multiple sources in priority order:
  1. CLI flags (passed as parameters)
  2. Environment variables (PARALLEL_CC_PROVIDER, PARALLEL_CC_E2B_TEMPLATE, etc.)
  3. Project config (.parallel-cc.json in repo root)
  4. User config (~/.parallel-cc/config.json)
  5. Default values (E2B for backward compatibility)
• Use Node.js fs module to read JSON config files with error handling for missing files
• Implement environment variable parsing with proper type conversion
• Export helper functions: getProviderConfig(providerName), getDefaultProvider()

2. Create Provider Registry Foundation

Create file:src/providers/registry.ts as a minimal registry to support the CLI flag:

• Define ProviderInfo interface with fields: name, displayName, available, description
• Create ProviderRegistry class with methods:
  • register(name, info) - Register a provider
  • get(name) - Get provider info
  • list() - List all registered providers
  • isAvailable(name) - Check if provider is available (API keys, dependencies)
• Pre-register E2B provider with availability check (E2B_API_KEY present)
• Add placeholder registrations for native, docker providers (marked as unavailable with "Coming in v1.5" message)
• Export singleton instance providerRegistry

3. Update CLI with Provider Flag

Modify file:src/cli.ts in the sandbox-run command section (around line 1352):

• Add .option('--provider <name>', 'Sandbox provider (e2b, native, docker)', 'e2b') to the command definition
• Update the action handler to:
  • Load configuration using loadConfig() with CLI options
  • Resolve provider name from config (respecting priority chain)
  • Validate provider exists in registry using providerRegistry.get()
  • Check provider availability using providerRegistry.isAvailable()
  • Show clear error if provider is invalid or unavailable
  • Pass provider-specific config to SandboxManager constructor
• Maintain existing E2B logic as default path (no breaking changes)

4. Add Provider Management Commands

Add new CLI commands in file:src/cli.ts after the existing sandbox commands:

providers list command:

• Use providerRegistry.list() to get all providers
• Display table with columns: Provider, Status, Description
• Show availability status (✓ Available, ✗ Unavailable, ⚠ Missing API key)
• Use chalk for colored output matching existing CLI style

providers status command:

• Show detailed status for each provider
• For E2B: check E2B_API_KEY, show template from config
• For native/docker: show "Coming in v1.5" message
• Display current default provider from configuration
• Show configuration sources (which config file is being used)

5. Update SandboxManager for Provider Support

Modify file:src/e2b/sandbox-manager.ts to accept provider configuration:

• Update constructor to accept optional providerName parameter (default: 'e2b')
• Add validation to ensure only 'e2b' is supported in v1.0 (throw error for others)
• Update error messages to mention provider name for clarity
• Add comment indicating this will be refactored when full provider registry is implemented
• No functional changes to existing E2B logic

6. Add Configuration File Examples

Create example configuration files in file:config/ directory:

config/.parallel-cc.example.json (project-level):

{
  "sandbox": {
    "defaultProvider": "e2b",
    "providers": {
      "e2b": {
        "template": "anthropic-claude-code",
        "timeoutMinutes": 60
      }
    }
  }
}

config/user-config.example.json (user-level):

{
  "sandbox": {
    "defaultProvider": "e2b",
    "providers": {
      "e2b": {
        "template": "anthropic-claude-code"
      }
    }
  }
}

7. Update Type Definitions

Modify file:src/types.ts to add configuration types:

• Add ProviderName type: 'e2b' | 'native' | 'docker' | 'daytona' | 'cloudflare'
• Add ProviderConfig interface for provider-specific settings
• Add SandboxConfigFile interface matching the JSON structure
• Add ConfigSource type to track where config came from
• Export these types for use in config.ts and cli.ts

8. Update Documentation

Update file:README.md with new provider flag usage:

• Add examples showing --provider flag usage
• Document environment variables (PARALLEL_CC_PROVIDER, etc.)
• Explain configuration file locations and priority
• Add section on provider availability and v1.5 roadmap
• Update existing sandbox-run examples to show optional --provider flag

9. Add Tests

Create test files for new functionality:

file:tests/config.test.ts:

• Test configuration loading from different sources
• Test priority chain (CLI > env > project > user > default)
• Test missing config files (should not error)
• Test invalid JSON handling
• Test environment variable parsing

file:tests/providers/registry.test.ts:

• Test provider registration
• Test provider availability checks
• Test listing providers
• Test getting provider info
• Test invalid provider names

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

• Add tests for provider validation
• Test error messages for unsupported providers
• Ensure backward compatibility (no provider specified = E2B)

10. Backward Compatibility Verification

Ensure existing workflows continue to work:

• Test parallel-cc sandbox-run --repo . --prompt "task" (no provider flag) defaults to E2B
• Verify all existing E2B-specific flags still work (--template, --auth-method, etc.)
• Confirm no changes to database schema or session tracking
• Test that existing E2B sessions can be queried with sandbox-status, sandbox-logs, etc.
• Validate that error messages remain clear and actionable

Configuration Priority Flow

flowchart TD
    A[sandbox-run command] --> B{--provider flag?}
    B -->|Yes| C[Use CLI provider]
    B -->|No| D{PARALLEL_CC_PROVIDER env?}
    D -->|Yes| E[Use env provider]
    D -->|No| F{.parallel-cc.json exists?}
    F -->|Yes| G[Use project config]
    F -->|No| H{~/.parallel-cc/config.json exists?}
    H -->|Yes| I[Use user config]
    H -->|No| J[Use default: e2b]
    
    C --> K[Validate provider]
    E --> K
    G --> K
    I --> K
    J --> K
    
    K --> L{Provider available?}
    L -->|Yes| M[Create sandbox]
    L -->|No| N[Show error with setup instructions]

Loading

Provider Selection Priority Table

Priority	Source	Example	Override
1 (Highest)	CLI Flag	--provider e2b	All others
2	Environment Variable	PARALLEL_CC_PROVIDER=docker	Config files
3	Project Config	.parallel-cc.json	User config
4	User Config	~/.parallel-cc/config.json	Default
5 (Lowest)	Default	e2b	None

Files to Create

• file:src/config.ts - Configuration loading system
• file:src/providers/registry.ts - Provider registry foundation
• file:config/.parallel-cc.example.json - Project config example
• file:config/user-config.example.json - User config example
• file:tests/config.test.ts - Configuration tests
• file:tests/providers/registry.test.ts - Registry tests

Files to Modify

• file:src/cli.ts - Add --provider flag and provider commands
• file:src/e2b/sandbox-manager.ts - Accept provider parameter
• file:src/types.ts - Add configuration types
• file:README.md - Document new features
• file:tests/e2b/sandbox-manager.test.ts - Add provider validation tests

Environment Variables

Variable	Purpose	Example
PARALLEL_CC_PROVIDER	Default provider	e2b, native, docker
PARALLEL_CC_E2B_TEMPLATE	E2B sandbox template	anthropic-claude-code
PARALLEL_CC_DOCKER_IMAGE	Docker image (future)	claude-code:latest

Acceptance Criteria Mapping

• ✅ --provider flag works correctly → Step 3
• ✅ Environment variable fallback works → Step 1 (priority chain)
• ✅ Config file loading works → Step 1 (loadConfig function)
• ✅ Invalid provider gives clear error → Step 3 (validation)
• ✅ providers list command shows available providers → Step 4
• ✅ Backward compatible (default to E2B if no flag) → Steps 3, 5, 10

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently has a hardcoded E2B-only sandbox implementation in v1.0. The `SandboxManager` class in `file:src/e2b/sandbox-manager.ts` is tightly coupled to E2B SDK. The CLI uses Commander.js framework and the `sandbox-run` command (lines 1351-1924 in `file:src/cli.ts`) directly instantiates `SandboxManager` with E2B-specific configuration. There's no provider abstraction layer, configuration loading system, or provider registry yet. The task depends on issue #32 (Provider registry) which hasn't been implemented.

## Approach

Since the provider registry (#32) is a dependency that doesn't exist yet, the implementation will create a minimal provider abstraction layer alongside the configuration system. The approach focuses on adding the `--provider` flag and configuration loading while maintaining 100% backward compatibility with existing E2B workflows. The provider selection will follow the specified priority chain (CLI → env → config → default), with E2B as the default to ensure no breaking changes. The implementation will be structured to easily integrate with a full provider registry when #32 is completed.

## Implementation Steps

### 1. Create Configuration System

Create `file:src/config.ts` to handle configuration loading with the priority chain:

- Define `SandboxConfig` interface with `defaultProvider` and provider-specific settings
- Implement `loadConfig()` function that merges configurations from multiple sources in priority order:
  1. CLI flags (passed as parameters)
  2. Environment variables (`PARALLEL_CC_PROVIDER`, `PARALLEL_CC_E2B_TEMPLATE`, etc.)
  3. Project config (`.parallel-cc.json` in repo root)
  4. User config (`~/.parallel-cc/config.json`)
  5. Default values (E2B for backward compatibility)
- Use Node.js `fs` module to read JSON config files with error handling for missing files
- Implement environment variable parsing with proper type conversion
- Export helper functions: `getProviderConfig(providerName)`, `getDefaultProvider()`

### 2. Create Provider Registry Foundation

Create `file:src/providers/registry.ts` as a minimal registry to support the CLI flag:

- Define `ProviderInfo` interface with fields: `name`, `displayName`, `available`, `description`
- Create `ProviderRegistry` class with methods:
  - `register(name, info)` - Register a provider
  - `get(name)` - Get provider info
  - `list()` - List all registered providers
  - `isAvailable(name)` - Check if provider is available (API keys, dependencies)
- Pre-register E2B provider with availability check (E2B_API_KEY present)
- Add placeholder registrations for `native`, `docker` providers (marked as unavailable with "Coming in v1.5" message)
- Export singleton instance `providerRegistry`

### 3. Update CLI with Provider Flag

Modify `file:src/cli.ts` in the `sandbox-run` command section (around line 1352):

- Add `.option('--provider <name>', 'Sandbox provider (e2b, native, docker)', 'e2b')` to the command definition
- Update the action handler to:
  - Load configuration using `loadConfig()` with CLI options
  - Resolve provider name from config (respecting priority chain)
  - Validate provider exists in registry using `providerRegistry.get()`
  - Check provider availability using `providerRegistry.isAvailable()`
  - Show clear error if provider is invalid or unavailable
  - Pass provider-specific config to `SandboxManager` constructor
- Maintain existing E2B logic as default path (no breaking changes)

### 4. Add Provider Management Commands

Add new CLI commands in `file:src/cli.ts` after the existing sandbox commands:

**`providers list` command:**
- Use `providerRegistry.list()` to get all providers
- Display table with columns: Provider, Status, Description
- Show availability status (✓ Available, ✗ Unavailable, ⚠ Missing API key)
- Use `chalk` for colored output matching existing CLI style

**`providers status` command:**
- Show detailed status for each provider
- For E2B: check E2B_API_KEY, show template from config
- For native/docker: show "Coming in v1.5" message
- Display current default provider from configuration
- Show configuration sources (which config file is being used)

### 5. Update SandboxManager for Provider Support

Modify `file:src/e2b/sandbox-manager.ts` to accept provider configuration:

- Update constructor to accept optional `providerName` parameter (default: 'e2b')
- Add validation to ensure only 'e2b' is supported in v1.0 (throw error for others)
- Update error messages to mention provider name for clarity
- Add comment indicating this will be refactored when full provider registry is implemented
- No functional changes to existing E2B logic

### 6. Add Configuration File Examples

Create example configuration files in `file:config/` directory:

**`config/.parallel-cc.example.json`** (project-level):
```json
{
  "sandbox": {
    "defaultProvider": "e2b",
    "providers": {
      "e2b": {
        "template": "anthropic-claude-code",
        "timeoutMinutes": 60
      }
    }
  }
}
```

**`config/user-config.example.json`** (user-level):
```json
{
  "sandbox": {
    "defaultProvider": "e2b",
    "providers": {
      "e2b": {
        "template": "anthropic-claude-code"
      }
    }
  }
}
```

### 7. Update Type Definitions

Modify `file:src/types.ts` to add configuration types:

- Add `ProviderName` type: `'e2b' | 'native' | 'docker' | 'daytona' | 'cloudflare'`
- Add `ProviderConfig` interface for provider-specific settings
- Add `SandboxConfigFile` interface matching the JSON structure
- Add `ConfigSource` type to track where config came from
- Export these types for use in config.ts and cli.ts

### 8. Update Documentation

Update `file:README.md` with new provider flag usage:

- Add examples showing `--provider` flag usage
- Document environment variables (PARALLEL_CC_PROVIDER, etc.)
- Explain configuration file locations and priority
- Add section on provider availability and v1.5 roadmap
- Update existing sandbox-run examples to show optional `--provider` flag

### 9. Add Tests

Create test files for new functionality:

**`file:tests/config.test.ts`:**
- Test configuration loading from different sources
- Test priority chain (CLI > env > project > user > default)
- Test missing config files (should not error)
- Test invalid JSON handling
- Test environment variable parsing

**`file:tests/providers/registry.test.ts`:**
- Test provider registration
- Test provider availability checks
- Test listing providers
- Test getting provider info
- Test invalid provider names

**Update `file:tests/e2b/sandbox-manager.test.ts`:**
- Add tests for provider validation
- Test error messages for unsupported providers
- Ensure backward compatibility (no provider specified = E2B)

### 10. Backward Compatibility Verification

Ensure existing workflows continue to work:

- Test `parallel-cc sandbox-run --repo . --prompt "task"` (no provider flag) defaults to E2B
- Verify all existing E2B-specific flags still work (`--template`, `--auth-method`, etc.)
- Confirm no changes to database schema or session tracking
- Test that existing E2B sessions can be queried with `sandbox-status`, `sandbox-logs`, etc.
- Validate that error messages remain clear and actionable

## Configuration Priority Flow

```mermaid
flowchart TD
    A[sandbox-run command] --> B{--provider flag?}
    B -->|Yes| C[Use CLI provider]
    B -->|No| D{PARALLEL_CC_PROVIDER env?}
    D -->|Yes| E[Use env provider]
    D -->|No| F{.parallel-cc.json exists?}
    F -->|Yes| G[Use project config]
    F -->|No| H{~/.parallel-cc/config.json exists?}
    H -->|Yes| I[Use user config]
    H -->|No| J[Use default: e2b]
    
    C --> K[Validate provider]
    E --> K
    G --> K
    I --> K
    J --> K
    
    K --> L{Provider available?}
    L -->|Yes| M[Create sandbox]
    L -->|No| N[Show error with setup instructions]
```

## Provider Selection Priority Table

| Priority | Source | Example | Override |
|----------|--------|---------|----------|
| 1 (Highest) | CLI Flag | `--provider e2b` | All others |
| 2 | Environment Variable | `PARALLEL_CC_PROVIDER=docker` | Config files |
| 3 | Project Config | `.parallel-cc.json` | User config |
| 4 | User Config | `~/.parallel-cc/config.json` | Default |
| 5 (Lowest) | Default | `e2b` | None |

## Files to Create

- `file:src/config.ts` - Configuration loading system
- `file:src/providers/registry.ts` - Provider registry foundation
- `file:config/.parallel-cc.example.json` - Project config example
- `file:config/user-config.example.json` - User config example
- `file:tests/config.test.ts` - Configuration tests
- `file:tests/providers/registry.test.ts` - Registry tests

## Files to Modify

- `file:src/cli.ts` - Add `--provider` flag and provider commands
- `file:src/e2b/sandbox-manager.ts` - Accept provider parameter
- `file:src/types.ts` - Add configuration types
- `file:README.md` - Document new features
- `file:tests/e2b/sandbox-manager.test.ts` - Add provider validation tests

## Environment Variables

| Variable | Purpose | Example |
|----------|---------|---------|
| `PARALLEL_CC_PROVIDER` | Default provider | `e2b`, `native`, `docker` |
| `PARALLEL_CC_E2B_TEMPLATE` | E2B sandbox template | `anthropic-claude-code` |
| `PARALLEL_CC_DOCKER_IMAGE` | Docker image (future) | `claude-code:latest` |

## Acceptance Criteria Mapping

- ✅ `--provider` flag works correctly → Step 3
- ✅ Environment variable fallback works → Step 1 (priority chain)
- ✅ Config file loading works → Step 1 (loadConfig function)
- ✅ Invalid provider gives clear error → Step 3 (validation)
- ✅ `providers list` command shows available providers → Step 4
- ✅ Backward compatible (default to E2B if no flag) → Steps 3, 5, 10

---

Execution Information

Branch: main
Commit: 136df60

New Plan

Observations

The codebase currently has a hardcoded E2B-only sandbox implementation in v1.0. The SandboxManager class in file:src/e2b/sandbox-manager.ts is tightly coupled to E2B SDK. The CLI uses Commander.js framework and the sandbox-run command (lines 1351-1924 in file:src/cli.ts) directly instantiates SandboxManager with E2B-specific configuration. There's no provider abstraction layer, configuration loading system, or provider registry yet. The task depends on issue #32 (Provider registry) which hasn't been implemented.

Approach

Since the provider registry (#32) is a dependency that doesn't exist yet, the implementation will create a minimal provider abstraction layer alongside the configuration system. The approach focuses on adding the --provider flag and configuration loading while maintaining 100% backward compatibility with existing E2B workflows. The provider selection will follow the specified priority chain (CLI → env → config → default), with E2B as the default to ensure no breaking changes. The implementation will be structured to easily integrate with a full provider registry when #32 is completed.

Implementation Steps

1. Create Configuration System

Create file:src/config.ts to handle configuration loading with the priority chain:

• Define SandboxConfig interface with defaultProvider and provider-specific settings
• Implement loadConfig() function that merges configurations from multiple sources in priority order:
  1. CLI flags (passed as parameters)
  2. Environment variables (PARALLEL_CC_PROVIDER, PARALLEL_CC_E2B_TEMPLATE, etc.)
  3. Project config (.parallel-cc.json in repo root)
  4. User config (~/.parallel-cc/config.json)
  5. Default values (E2B for backward compatibility)
• Use Node.js fs module to read JSON config files with error handling for missing files
• Implement environment variable parsing with proper type conversion
• Export helper functions: getProviderConfig(providerName), getDefaultProvider()

2. Create Provider Registry Foundation

Create file:src/providers/registry.ts as a minimal registry to support the CLI flag:

• Define ProviderInfo interface with fields: name, displayName, available, description
• Create ProviderRegistry class with methods:
  • register(name, info) - Register a provider
  • get(name) - Get provider info
  • list() - List all registered providers
  • isAvailable(name) - Check if provider is available (API keys, dependencies)
• Pre-register E2B provider with availability check (E2B_API_KEY present)
• Add placeholder registrations for native, docker providers (marked as unavailable with "Coming in v2.5" message)
• Export singleton instance providerRegistry

3. Update CLI with Provider Flag

Modify file:src/cli.ts in the sandbox-run command section (around line 1352):

• Add .option('--provider <name>', 'Sandbox provider (e2b, native, docker)', 'e2b') to the command definition
• Update the action handler to:
  • Load configuration using loadConfig() with CLI options
  • Resolve provider name from config (respecting priority chain)
  • Validate provider exists in registry using providerRegistry.get()
  • Check provider availability using providerRegistry.isAvailable()
  • Show clear error if provider is invalid or unavailable
  • Pass provider-specific config to SandboxManager constructor
• Maintain existing E2B logic as default path (no breaking changes)

4. Add Provider Management Commands

Add new CLI commands in file:src/cli.ts after the existing sandbox commands:

providers list command:

• Use providerRegistry.list() to get all providers
• Display table with columns: Provider, Status, Description
• Show availability status (✓ Available, ✗ Unavailable, ⚠ Missing API key)
• Use chalk for colored output matching existing CLI style

providers status command:

• Show detailed status for each provider
• For E2B: check E2B_API_KEY, show template from config
• For native/docker: show "Coming in v2.5" message
• Display current default provider from configuration
• Show configuration sources (which config file is being used)

5. Update SandboxManager for Provider Support

Modify file:src/e2b/sandbox-manager.ts to accept provider configuration:

• Update constructor to accept optional providerName parameter (default: 'e2b')
• Add validation to ensure only 'e2b' is supported in v2.5 (throw error for others)
• Update error messages to mention provider name for clarity
• Add comment indicating this will be refactored when full provider registry is implemented
• No functional changes to existing E2B logic

6. Add Configuration File Examples

Create example configuration files in file:config/ directory:

config/.parallel-cc.example.json (project-level):

{
  "sandbox": {
    "defaultProvider": "native",
    "providers": {
      "e2b": {
        "template": "anthropic-claude-code",
        "timeoutMinutes": 60
      }
    }
  }
}

config/user-config.example.json (user-level):

{
  "sandbox": {
    "defaultProvider": "e2b",
    "providers": {
      "e2b": {
        "template": "anthropic-claude-code"
      }
    }
  }
}

7. Update Type Definitions

Modify file:src/types.ts to add configuration types:

• Add ProviderName type: 'e2b' | 'native' | 'docker' | 'daytona' | 'cloudflare'
• Add ProviderConfig interface for provider-specific settings
• Add SandboxConfigFile interface matching the JSON structure
• Add ConfigSource type to track where config came from
• Export these types for use in config.ts and cli.ts

8. Update Documentation

Update file:README.md with new provider flag usage:

• Add examples showing --provider flag usage
• Document environment variables (PARALLEL_CC_PROVIDER, etc.)
• Explain configuration file locations and priority
• Add section on provider availability and v2.5 roadmap
• Update existing sandbox-run examples to show optional --provider flag

9. Add Tests

Create test files for new functionality:

file:tests/config.test.ts:

• Test configuration loading from different sources
• Test priority chain (CLI > env > project > user > default)
• Test missing config files (should not error)
• Test invalid JSON handling
• Test environment variable parsing

file:tests/providers/registry.test.ts:

• Test provider registration
• Test provider availability checks
• Test listing providers
• Test getting provider info
• Test invalid provider names

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

• Add tests for provider validation
• Test error messages for unsupported providers
• Ensure backward compatibility (no provider specified = E2B)

10. Backward Compatibility Verification

Ensure existing workflows continue to work:

• Test parallel-cc sandbox-run --repo . --prompt "task" (no provider flag) defaults to E2B
• Verify all existing E2B-specific flags still work (--template, --auth-method, etc.)
• Confirm no changes to database schema or session tracking
• Test that existing E2B sessions can be queried with sandbox-status, sandbox-logs, etc.
• Validate that error messages remain clear and actionable

Configuration Priority Flow

flowchart TD
    A[sandbox-run command] --> B{--provider flag?}
    B -->|Yes| C[Use CLI provider]
    B -->|No| D{PARALLEL_CC_PROVIDER env?}
    D -->|Yes| E[Use env provider]
    D -->|No| F{.parallel-cc.json exists?}
    F -->|Yes| G[Use project config]
    F -->|No| H{~/.parallel-cc/config.json exists?}
    H -->|Yes| I[Use user config]
    H -->|No| J[Use default: e2b]
    
    C --> K[Validate provider]
    E --> K
    G --> K
    I --> K
    J --> K
    
    K --> L{Provider available?}
    L -->|Yes| M[Create sandbox]
    L -->|No| N[Show error with setup instructions]

Loading

Provider Selection Priority Table

Priority	Source	Example	Override
1 (Highest)	CLI Flag	--provider e2b	All others
2	Environment Variable	PARALLEL_CC_PROVIDER=docker	Config files
3	Project Config	.parallel-cc.json	User config
4	User Config	~/.parallel-cc/config.json	Default
5 (Lowest)	Default	e2b	None

Files to Create

• file:src/config.ts - Configuration loading system
• file:src/providers/registry.ts - Provider registry foundation
• file:config/.parallel-cc.example.json - Project config example
• file:config/user-config.example.json - User config example
• file:tests/config.test.ts - Configuration tests
• file:tests/providers/registry.test.ts - Registry tests

Files to Modify

• file:src/cli.ts - Add --provider flag and provider commands
• file:src/e2b/sandbox-manager.ts - Accept provider parameter
• file:src/types.ts - Add configuration types
• file:README.md - Document new features
• file:tests/e2b/sandbox-manager.test.ts - Add provider validation tests

Environment Variables

Variable	Purpose	Example
PARALLEL_CC_PROVIDER	Default provider	e2b, native, docker
PARALLEL_CC_E2B_TEMPLATE	E2B sandbox template	anthropic-claude-code
PARALLEL_CC_DOCKER_IMAGE	Docker image (future)	claude-code:latest

Acceptance Criteria Mapping

• ✅ --provider flag works correctly → Step 3
• ✅ Environment variable fallback works → Step 1 (priority chain)
• ✅ Config file loading works → Step 1 (loadConfig function)
• ✅ Invalid provider gives clear error → Step 3 (validation)
• ✅ providers list command shows available providers → Step 4
• ✅ Backward compatible (default to E2B if no flag) → Steps 3, 5, 10

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently has a hardcoded E2B-only sandbox implementation in v1.0. The `SandboxManager` class in `file:src/e2b/sandbox-manager.ts` is tightly coupled to E2B SDK. The CLI uses Commander.js framework and the `sandbox-run` command (lines 1351-1924 in `file:src/cli.ts`) directly instantiates `SandboxManager` with E2B-specific configuration. There's no provider abstraction layer, configuration loading system, or provider registry yet. The task depends on issue #32 (Provider registry) which hasn't been implemented.

## Approach

Since the provider registry (#32) is a dependency that doesn't exist yet, the implementation will create a minimal provider abstraction layer alongside the configuration system. The approach focuses on adding the `--provider` flag and configuration loading while maintaining 100% backward compatibility with existing E2B workflows. The provider selection will follow the specified priority chain (CLI → env → config → default), with E2B as the default to ensure no breaking changes. The implementation will be structured to easily integrate with a full provider registry when #32 is completed.

## Implementation Steps

### 1. Create Configuration System

Create `file:src/config.ts` to handle configuration loading with the priority chain:

- Define `SandboxConfig` interface with `defaultProvider` and provider-specific settings
- Implement `loadConfig()` function that merges configurations from multiple sources in priority order:
  1. CLI flags (passed as parameters)
  2. Environment variables (`PARALLEL_CC_PROVIDER`, `PARALLEL_CC_E2B_TEMPLATE`, etc.)
  3. Project config (`.parallel-cc.json` in repo root)
  4. User config (`~/.parallel-cc/config.json`)
  5. Default values (E2B for backward compatibility)
- Use Node.js `fs` module to read JSON config files with error handling for missing files
- Implement environment variable parsing with proper type conversion
- Export helper functions: `getProviderConfig(providerName)`, `getDefaultProvider()`

### 2. Create Provider Registry Foundation

Create `file:src/providers/registry.ts` as a minimal registry to support the CLI flag:

- Define `ProviderInfo` interface with fields: `name`, `displayName`, `available`, `description`
- Create `ProviderRegistry` class with methods:
  - `register(name, info)` - Register a provider
  - `get(name)` - Get provider info
  - `list()` - List all registered providers
  - `isAvailable(name)` - Check if provider is available (API keys, dependencies)
- Pre-register E2B provider with availability check (E2B_API_KEY present)
- Add placeholder registrations for `native`, `docker` providers (marked as unavailable with "Coming in v2.5" message)
- Export singleton instance `providerRegistry`

### 3. Update CLI with Provider Flag

Modify `file:src/cli.ts` in the `sandbox-run` command section (around line 1352):

- Add `.option('--provider <name>', 'Sandbox provider (e2b, native, docker)', 'e2b')` to the command definition
- Update the action handler to:
  - Load configuration using `loadConfig()` with CLI options
  - Resolve provider name from config (respecting priority chain)
  - Validate provider exists in registry using `providerRegistry.get()`
  - Check provider availability using `providerRegistry.isAvailable()`
  - Show clear error if provider is invalid or unavailable
  - Pass provider-specific config to `SandboxManager` constructor
- Maintain existing E2B logic as default path (no breaking changes)

### 4. Add Provider Management Commands

Add new CLI commands in `file:src/cli.ts` after the existing sandbox commands:

**`providers list` command:**
- Use `providerRegistry.list()` to get all providers
- Display table with columns: Provider, Status, Description
- Show availability status (✓ Available, ✗ Unavailable, ⚠ Missing API key)
- Use `chalk` for colored output matching existing CLI style

**`providers status` command:**
- Show detailed status for each provider
- For E2B: check E2B_API_KEY, show template from config
- For native/docker: show "Coming in v2.5" message
- Display current default provider from configuration
- Show configuration sources (which config file is being used)

### 5. Update SandboxManager for Provider Support

Modify `file:src/e2b/sandbox-manager.ts` to accept provider configuration:

- Update constructor to accept optional `providerName` parameter (default: 'e2b')
- Add validation to ensure only 'e2b' is supported in v2.5 (throw error for others)
- Update error messages to mention provider name for clarity
- Add comment indicating this will be refactored when full provider registry is implemented
- No functional changes to existing E2B logic

### 6. Add Configuration File Examples

Create example configuration files in `file:config/` directory:

**`config/.parallel-cc.example.json`** (project-level):
```json
{
  "sandbox": {
    "defaultProvider": "native",
    "providers": {
      "e2b": {
        "template": "anthropic-claude-code",
        "timeoutMinutes": 60
      }
    }
  }
}
```

**`config/user-config.example.json`** (user-level):
```json
{
  "sandbox": {
    "defaultProvider": "e2b",
    "providers": {
      "e2b": {
        "template": "anthropic-claude-code"
      }
    }
  }
}
```

### 7. Update Type Definitions

Modify `file:src/types.ts` to add configuration types:

- Add `ProviderName` type: `'e2b' | 'native' | 'docker' | 'daytona' | 'cloudflare'`
- Add `ProviderConfig` interface for provider-specific settings
- Add `SandboxConfigFile` interface matching the JSON structure
- Add `ConfigSource` type to track where config came from
- Export these types for use in config.ts and cli.ts

### 8. Update Documentation

Update `file:README.md` with new provider flag usage:

- Add examples showing `--provider` flag usage
- Document environment variables (PARALLEL_CC_PROVIDER, etc.)
- Explain configuration file locations and priority
- Add section on provider availability and v2.5 roadmap
- Update existing sandbox-run examples to show optional `--provider` flag

### 9. Add Tests

Create test files for new functionality:

**`file:tests/config.test.ts`:**
- Test configuration loading from different sources
- Test priority chain (CLI > env > project > user > default)
- Test missing config files (should not error)
- Test invalid JSON handling
- Test environment variable parsing

**`file:tests/providers/registry.test.ts`:**
- Test provider registration
- Test provider availability checks
- Test listing providers
- Test getting provider info
- Test invalid provider names

**Update `file:tests/e2b/sandbox-manager.test.ts`:**
- Add tests for provider validation
- Test error messages for unsupported providers
- Ensure backward compatibility (no provider specified = E2B)

### 10. Backward Compatibility Verification

Ensure existing workflows continue to work:

- Test `parallel-cc sandbox-run --repo . --prompt "task"` (no provider flag) defaults to E2B
- Verify all existing E2B-specific flags still work (`--template`, `--auth-method`, etc.)
- Confirm no changes to database schema or session tracking
- Test that existing E2B sessions can be queried with `sandbox-status`, `sandbox-logs`, etc.
- Validate that error messages remain clear and actionable

## Configuration Priority Flow

```mermaid
flowchart TD
    A[sandbox-run command] --> B{--provider flag?}
    B -->|Yes| C[Use CLI provider]
    B -->|No| D{PARALLEL_CC_PROVIDER env?}
    D -->|Yes| E[Use env provider]
    D -->|No| F{.parallel-cc.json exists?}
    F -->|Yes| G[Use project config]
    F -->|No| H{~/.parallel-cc/config.json exists?}
    H -->|Yes| I[Use user config]
    H -->|No| J[Use default: e2b]
    
    C --> K[Validate provider]
    E --> K
    G --> K
    I --> K
    J --> K
    
    K --> L{Provider available?}
    L -->|Yes| M[Create sandbox]
    L -->|No| N[Show error with setup instructions]
```

## Provider Selection Priority Table

| Priority | Source | Example | Override |
|----------|--------|---------|----------|
| 1 (Highest) | CLI Flag | `--provider e2b` | All others |
| 2 | Environment Variable | `PARALLEL_CC_PROVIDER=docker` | Config files |
| 3 | Project Config | `.parallel-cc.json` | User config |
| 4 | User Config | `~/.parallel-cc/config.json` | Default |
| 5 (Lowest) | Default | `e2b` | None |

## Files to Create

- `file:src/config.ts` - Configuration loading system
- `file:src/providers/registry.ts` - Provider registry foundation
- `file:config/.parallel-cc.example.json` - Project config example
- `file:config/user-config.example.json` - User config example
- `file:tests/config.test.ts` - Configuration tests
- `file:tests/providers/registry.test.ts` - Registry tests

## Files to Modify

- `file:src/cli.ts` - Add `--provider` flag and provider commands
- `file:src/e2b/sandbox-manager.ts` - Accept provider parameter
- `file:src/types.ts` - Add configuration types
- `file:README.md` - Document new features
- `file:tests/e2b/sandbox-manager.test.ts` - Add provider validation tests

## Environment Variables

| Variable | Purpose | Example |
|----------|---------|---------|
| `PARALLEL_CC_PROVIDER` | Default provider | `e2b`, `native`, `docker` |
| `PARALLEL_CC_E2B_TEMPLATE` | E2B sandbox template | `anthropic-claude-code` |
| `PARALLEL_CC_DOCKER_IMAGE` | Docker image (future) | `claude-code:latest` |

## Acceptance Criteria Mapping

- ✅ `--provider` flag works correctly → Step 3
- ✅ Environment variable fallback works → Step 1 (priority chain)
- ✅ Config file loading works → Step 1 (loadConfig function)
- ✅ Invalid provider gives clear error → Step 3 (validation)
- ✅ `providers list` command shows available providers → Step 4
- ✅ Backward compatible (default to E2B if no flag) → Steps 3, 5, 10

---

Execution Information

Branch: main
Commit: 9698ef5