[v2.5] Implement NativeProvider using srt CLI

[frankbria]

Overview

Implement a native sandbox provider using Anthropic's srt (sandbox runtime) CLI tool. This enables free, local sandboxing without cloud costs.

What is srt?

The srt CLI is Anthropic's sandboxing tool that uses:

• macOS: Seatbelt sandboxing
• Linux: bubblewrap (bwrap)

It provides secure, isolated execution environments on the local machine.

Implementation

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

export class NativeProvider implements SandboxProvider {
  readonly name = 'native';
  readonly version = '1.0.0';
  
  static async isAvailable(): Promise<boolean> {
    // Check if srt CLI is installed
    try {
      execSync('srt --version', { stdio: 'pipe' });
      return true;
    } catch {
      return false;
    }
  }
  
  async create(config: SandboxConfig): Promise<SandboxInstance> {
    // Create sandbox using srt
    // srt create --name <name> --workdir <path>
  }
  
  async execute(instanceId: string, command: string): AsyncGenerator<string> {
    // Execute in sandbox
    // srt exec <instanceId> -- <command>
  }
  
  // ... implement remaining interface methods
}

Key Differences from E2B

Aspect	E2B	Native (srt)
Startup	~150ms	Instant
Cost	$0.10/hr	Free
Isolation	Full VM	OS-level sandbox
Timeout	1 hour max	Unlimited
Network	Full access	Configurable
Resources	Cloud scale	Local machine

Use Cases

• Quick tasks (<5 min)
• Development/testing
• Offline work
• Cost-conscious users

Files to Create

• src/e2b/providers/native-provider.ts
• tests/e2b/native-provider.test.ts

Acceptance Criteria

• Works on macOS with Seatbelt
• Works on Linux with bubblewrap
• File upload/download works
• Command execution with output streaming
• Proper cleanup on destroy
• 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]
#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 a v1.0 E2B-specific sandbox implementation with SandboxManager, file-sync, and claude-runner modules tightly coupled to the E2B SDK. The v1.5 multi-provider architecture is planned but not yet implemented. The SandboxProvider interface and provider registry (dependencies #30 and #32) don't exist yet. The Anthropic srt CLI tool provides OS-level sandboxing via Seatbelt (macOS) or bubblewrap (Linux), configured through JSON settings files, and wraps commands with security boundaries.

Approach

This implementation follows Phase 2 of the v1.5 roadmap, creating the NativeProvider using Anthropic's srt CLI. Since dependencies #30 and #32 are not yet implemented, the plan assumes they will be completed first and provides the NativeProvider implementation that conforms to the planned SandboxProvider interface. The NativeProvider will differ significantly from E2BProvider by executing locally without file upload/download, using srt to wrap Claude Code execution with configurable security policies, and providing instant startup with zero cloud costs.

Implementation Steps

1. Prerequisites Verification

Dependency Check:

• Verify that SandboxProvider interface exists in file:src/e2b/providers/types.ts or similar location (from issue [v2.5] Define SandboxProvider interface and types #30)
• Verify that provider registry exists in file:src/e2b/providers/registry.ts or similar (from issue [v2.5] Add provider registry and factory pattern #32)
• If these don't exist, this implementation must wait for issues [v2.5] Define SandboxProvider interface and types #30 and [v2.5] Add provider registry and factory pattern #32 to be completed first

Interface Requirements:
The SandboxProvider interface should define (based on file:SANDBOX_INTEGRATION_PLAN.md lines 687-702):

• create(config: SandboxConfig): Promise<SandboxInstance>
• destroy(instanceId: string): Promise<void>
• uploadFiles(instanceId: string, files: FileList): Promise<UploadResult> (no-op for native)
• downloadFiles(instanceId: string): Promise<FileList> (no-op for native)
• execute(instanceId: string, command: string): AsyncGenerator<OutputChunk>
• isRunning(instanceId: string): Promise<boolean>
• getMetrics(instanceId: string): Promise<SandboxMetrics>

2. Create NativeProvider Implementation

File: file:src/e2b/providers/native-provider.ts

Core Structure:

export class NativeProvider implements SandboxProvider {
  readonly name = 'native';
  readonly version = '1.0.0';
  
  private activeSandboxes: Map<string, NativeSandboxInstance>;
  private logger: Logger;
  private srtPath: string;
  
  constructor(logger: Logger, config?: NativeProviderConfig)
  
  static async isAvailable(): Promise<boolean>
  async create(config: SandboxConfig): Promise<SandboxInstance>
  async destroy(instanceId: string): Promise<void>
  async execute(instanceId: string, command: string): AsyncGenerator<OutputChunk>
  async isRunning(instanceId: string): Promise<boolean>
  async getMetrics(instanceId: string): Promise<SandboxMetrics>
  
  // Native-specific (no-ops)
  async uploadFiles(): Promise<UploadResult>
  async downloadFiles(): Promise<FileList>
}

Key Implementation Details:

1. Platform Detection (static method):

   • Check process.platform for macOS or Linux
   • Verify srt CLI is installed via execSync('srt --version')
   • On Linux, verify bwrap is available
   • Return false on Windows or if dependencies missing

2. Sandbox Creation:

   • Generate unique instance ID (e.g., native-${Date.now()}-${randomBytes(4).toString('hex')})
   • Create srt configuration file in temp directory
   • Configuration should include:
     • network.allowedDomains: From config or defaults (github.com, api.anthropic.com, registry.npmjs.org)
     • filesystem.allowWrite: Worktree path only
     • filesystem.denyRead: Sensitive paths (~/.ssh, ~/.aws, ~/.gnupg)
   • Store instance metadata (worktree path, config path, created timestamp)
   • Return NativeSandboxInstance with instance ID

3. Command Execution:

   • Build srt command: srt --settings ${configPath} -- ${command}
   • Use spawn() with stdio: 'pipe' for streaming output
   • Yield output chunks as AsyncGenerator<OutputChunk>
   • Handle process exit codes and errors
   • Apply same prompt sanitization as file:src/e2b/sandbox-manager.ts (lines 39-57)

4. File Operations (no-ops):

   • uploadFiles(): Return success immediately (files already local)
   • downloadFiles(): Return empty file list (no sync needed)

5. Cleanup:

   • Delete srt config file from temp directory
   • Remove instance from tracking map
   • No process to kill (srt wraps each command execution)

3. Create Native Sandbox Instance Type

File: file:src/e2b/providers/native-provider.ts (same file)

interface NativeSandboxInstance extends SandboxInstance {
  instanceId: string;
  worktreePath: string;
  srtConfigPath: string;
  createdAt: Date;
  status: SandboxStatus;
}

4. Create srt Configuration Builder

Helper Function in NativeProvider:

private async createSrtConfig(
  worktreePath: string,
  config: NativeProviderConfig
): Promise<string>

Configuration Structure (based on srt documentation):

{
  "network": {
    "allowedDomains": ["github.com", "api.anthropic.com", "*.npmjs.org"],
    "deniedDomains": []
  },
  "filesystem": {
    "allowWrite": ["/path/to/worktree", "/path/to/worktree/.git"],
    "denyRead": [
      "~/.ssh",
      "~/.aws", 
      "~/.gnupg",
      "~/.config/gh"
    ],
    "denyWrite": []
  }
}

Security Considerations:

• Expand ~ to actual home directory path
• On Linux, convert glob patterns to literal paths (Linux bubblewrap doesn't support globs)
• Validate all paths to prevent directory traversal
• Write config to temp file with restrictive permissions (0600)

5. Integrate with Existing CLI

File: file:src/cli/index.ts or sandbox command handler

Modifications:

• Add --provider native option to sandbox-run command
• Check NativeProvider.isAvailable() before allowing native provider selection
• Provide helpful error messages:
  • Windows: "Native sandboxing not supported on Windows. Use --provider docker or --provider e2b"
  • Missing srt: "srt CLI not found. Install with: npm install -g @anthropic-ai/sandbox-runtime"
  • Missing bwrap (Linux): "bubblewrap not found. Install with: apt-get install bubblewrap"

6. Create Configuration Types

File: file:src/e2b/providers/types.ts (or wherever provider types are defined)

export interface NativeProviderConfig {
  allowedDomains?: string[];
  allowWritePaths?: string[];
  denyReadPaths?: string[];
  srtPath?: string; // Custom srt binary path
}

export interface NativeSandboxConfig extends SandboxConfig {
  provider: 'native';
  worktreePath: string;
  nativeConfig?: NativeProviderConfig;
}

7. Create Tests

File: file:tests/e2b/native-provider.test.ts

Test Coverage:

1. Platform Detection Tests:

   • isAvailable() returns true on macOS with srt installed
   • isAvailable() returns true on Linux with srt and bwrap installed
   • isAvailable() returns false on Windows
   • isAvailable() returns false when srt not installed

2. Sandbox Creation Tests:

   • Creates sandbox with unique instance ID
   • Generates srt config file with correct permissions
   • Tracks sandbox in internal state
   • Applies default configuration when not provided
   • Applies custom configuration when provided

3. Command Execution Tests:

   • Executes simple commands successfully
   • Streams output as AsyncGenerator
   • Handles command failures gracefully
   • Sanitizes prompts to prevent shell injection
   • Respects filesystem restrictions (write to allowed paths only)
   • Respects network restrictions (access to allowed domains only)

4. Cleanup Tests:

   • Removes srt config file on destroy
   • Removes instance from tracking
   • Handles cleanup errors gracefully

5. Integration Tests:

   • Full lifecycle: create → execute → destroy
   • Multiple concurrent sandboxes
   • Execute Claude Code with actual prompt (if srt available)

Test Pattern (follow existing pattern from file:tests/e2b/sandbox-manager.test.ts):

• Mock execSync and spawn for unit tests
• Use vi.mock() for external dependencies
• Create mock logger with vi.fn()
• Use beforeEach and afterEach for cleanup
• Target >85% coverage

8. Update Documentation

File: file:docs/E2B_GUIDE.md or create file:docs/NATIVE_PROVIDER_GUIDE.md

Content:

• Installation instructions for srt CLI
• Platform-specific setup (macOS vs Linux)
• Configuration options and examples
• Security model explanation
• Comparison with E2B provider
• Troubleshooting common issues

9. Add Environment Variable Support

Environment Variables:

PARALLEL_CC_NATIVE_ALLOWED_DOMAINS=github.com,api.anthropic.com
PARALLEL_CC_NATIVE_ALLOW_WRITE_PATHS=.,.git
PARALLEL_CC_NATIVE_DENY_READ_PATHS=~/.ssh,~/.aws,~/.gnupg
PARALLEL_CC_NATIVE_SRT_PATH=/custom/path/to/srt

Implementation:

• Read from environment in NativeProvider constructor
• Merge with config parameter (config takes precedence)
• Document in file:SANDBOX_INTEGRATION_PLAN.md (lines 96-100)

10. Error Handling

Error Scenarios:

1. srt not installed:

   • Detect in isAvailable()
   • Provide installation command in error message

2. bubblewrap not installed (Linux):

   • Detect in isAvailable()
   • Provide installation command: sudo apt-get install bubblewrap

3. Permission denied:

   • Catch EACCES errors when creating config file
   • Suggest checking temp directory permissions

4. Command execution timeout:

   • Implement timeout mechanism (default: 1 hour like E2B)
   • Kill process and clean up on timeout

5. Sandbox violation:

   • Parse srt violation logs (macOS only)
   • Log violations for debugging
   • Continue execution (violations are logged, not fatal)

Architecture Diagram

sequenceDiagram
    participant CLI as CLI (sandbox-run)
    participant NP as NativeProvider
    participant SRT as srt CLI
    participant Claude as Claude Code
    participant FS as Local Filesystem

    CLI->>NP: create(config)
    NP->>NP: Generate instance ID
    NP->>FS: Write srt-settings.json
    NP-->>CLI: Return SandboxInstance

    CLI->>NP: execute(instanceId, command)
    NP->>NP: Build srt command
    NP->>SRT: spawn srt --settings config.json -- claude ...
    SRT->>Claude: Execute with security boundaries
    Claude->>FS: Read/Write (restricted)
    Claude-->>SRT: Output stream
    SRT-->>NP: Output chunks
    NP-->>CLI: Yield OutputChunk (AsyncGenerator)

    CLI->>NP: destroy(instanceId)
    NP->>FS: Delete srt-settings.json
    NP->>NP: Remove from tracking
    NP-->>CLI: Success

Loading

Key Differences from E2BProvider

Aspect	E2BProvider	NativeProvider
Startup	150ms (cloud VM)	Instant (local process)
File Sync	Upload/download via tarball	No sync (already local)
Isolation	Full VM	OS-level sandbox
Network	Full access	Configurable allowlist
Cost	$0.10/hr	Free
Cleanup	Kill remote sandbox	Delete config file
Platform	Any (cloud)	macOS, Linux only

Dependencies

NPM Package:

• @anthropic-ai/sandbox-runtime (peer dependency, not bundled)

System Dependencies:

• macOS: srt CLI (uses Seatbelt)
• Linux: srt CLI + bubblewrap

Code Dependencies:

• SandboxProvider interface (issue [v2.5] Define SandboxProvider interface and types #30)
• Provider registry (issue [v2.5] Add provider registry and factory pattern #32)
• Existing types from file:src/types.ts
• Logger from file:src/logger.ts

Success Criteria

• ✅ NativeProvider.isAvailable() correctly detects platform support
• ✅ Creates sandbox with unique instance ID and srt config
• ✅ Executes Claude Code commands with security boundaries
• ✅ Streams output in real-time via AsyncGenerator
• ✅ Respects filesystem restrictions (write only to worktree)
• ✅ Respects network restrictions (access only allowed domains)
• ✅ Cleans up config files on destroy
• ✅ Works on macOS with Seatbelt
• ✅ Works on Linux with bubblewrap
• ✅ Fails gracefully on Windows with helpful error
• ✅ Test coverage >85%
• ✅ Integration tests pass with real srt CLI (when available)

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently has a v1.0 E2B-specific sandbox implementation with `SandboxManager`, `file-sync`, and `claude-runner` modules tightly coupled to the E2B SDK. The v1.5 multi-provider architecture is planned but not yet implemented. The `SandboxProvider` interface and provider registry (dependencies #30 and #32) don't exist yet. The Anthropic `srt` CLI tool provides OS-level sandboxing via Seatbelt (macOS) or bubblewrap (Linux), configured through JSON settings files, and wraps commands with security boundaries.

## Approach

This implementation follows Phase 2 of the v1.5 roadmap, creating the NativeProvider using Anthropic's srt CLI. Since dependencies #30 and #32 are not yet implemented, the plan assumes they will be completed first and provides the NativeProvider implementation that conforms to the planned `SandboxProvider` interface. The NativeProvider will differ significantly from E2BProvider by executing locally without file upload/download, using srt to wrap Claude Code execution with configurable security policies, and providing instant startup with zero cloud costs.

## Implementation Steps

### 1. Prerequisites Verification

**Dependency Check:**
- Verify that `SandboxProvider` interface exists in `file:src/e2b/providers/types.ts` or similar location (from issue #30)
- Verify that provider registry exists in `file:src/e2b/providers/registry.ts` or similar (from issue #32)
- If these don't exist, this implementation must wait for issues #30 and #32 to be completed first

**Interface Requirements:**
The `SandboxProvider` interface should define (based on `file:SANDBOX_INTEGRATION_PLAN.md` lines 687-702):
- `create(config: SandboxConfig): Promise<SandboxInstance>`
- `destroy(instanceId: string): Promise<void>`
- `uploadFiles(instanceId: string, files: FileList): Promise<UploadResult>` (no-op for native)
- `downloadFiles(instanceId: string): Promise<FileList>` (no-op for native)
- `execute(instanceId: string, command: string): AsyncGenerator<OutputChunk>`
- `isRunning(instanceId: string): Promise<boolean>`
- `getMetrics(instanceId: string): Promise<SandboxMetrics>`

### 2. Create NativeProvider Implementation

**File:** `file:src/e2b/providers/native-provider.ts`

**Core Structure:**
```typescript
export class NativeProvider implements SandboxProvider {
  readonly name = 'native';
  readonly version = '1.0.0';
  
  private activeSandboxes: Map<string, NativeSandboxInstance>;
  private logger: Logger;
  private srtPath: string;
  
  constructor(logger: Logger, config?: NativeProviderConfig)
  
  static async isAvailable(): Promise<boolean>
  async create(config: SandboxConfig): Promise<SandboxInstance>
  async destroy(instanceId: string): Promise<void>
  async execute(instanceId: string, command: string): AsyncGenerator<OutputChunk>
  async isRunning(instanceId: string): Promise<boolean>
  async getMetrics(instanceId: string): Promise<SandboxMetrics>
  
  // Native-specific (no-ops)
  async uploadFiles(): Promise<UploadResult>
  async downloadFiles(): Promise<FileList>
}
```

**Key Implementation Details:**

1. **Platform Detection** (static method):
   - Check `process.platform` for macOS or Linux
   - Verify `srt` CLI is installed via `execSync('srt --version')`
   - On Linux, verify `bwrap` is available
   - Return `false` on Windows or if dependencies missing

2. **Sandbox Creation**:
   - Generate unique instance ID (e.g., `native-${Date.now()}-${randomBytes(4).toString('hex')}`)
   - Create srt configuration file in temp directory
   - Configuration should include:
     - `network.allowedDomains`: From config or defaults (github.com, api.anthropic.com, registry.npmjs.org)
     - `filesystem.allowWrite`: Worktree path only
     - `filesystem.denyRead`: Sensitive paths (~/.ssh, ~/.aws, ~/.gnupg)
   - Store instance metadata (worktree path, config path, created timestamp)
   - Return `NativeSandboxInstance` with instance ID

3. **Command Execution**:
   - Build srt command: `srt --settings ${configPath} -- ${command}`
   - Use `spawn()` with stdio: 'pipe' for streaming output
   - Yield output chunks as `AsyncGenerator<OutputChunk>`
   - Handle process exit codes and errors
   - Apply same prompt sanitization as `file:src/e2b/sandbox-manager.ts` (lines 39-57)

4. **File Operations** (no-ops):
   - `uploadFiles()`: Return success immediately (files already local)
   - `downloadFiles()`: Return empty file list (no sync needed)

5. **Cleanup**:
   - Delete srt config file from temp directory
   - Remove instance from tracking map
   - No process to kill (srt wraps each command execution)

### 3. Create Native Sandbox Instance Type

**File:** `file:src/e2b/providers/native-provider.ts` (same file)

```typescript
interface NativeSandboxInstance extends SandboxInstance {
  instanceId: string;
  worktreePath: string;
  srtConfigPath: string;
  createdAt: Date;
  status: SandboxStatus;
}
```

### 4. Create srt Configuration Builder

**Helper Function in NativeProvider:**

```typescript
private async createSrtConfig(
  worktreePath: string,
  config: NativeProviderConfig
): Promise<string>
```

**Configuration Structure** (based on srt documentation):
```json
{
  "network": {
    "allowedDomains": ["github.com", "api.anthropic.com", "*.npmjs.org"],
    "deniedDomains": []
  },
  "filesystem": {
    "allowWrite": ["/path/to/worktree", "/path/to/worktree/.git"],
    "denyRead": [
      "~/.ssh",
      "~/.aws", 
      "~/.gnupg",
      "~/.config/gh"
    ],
    "denyWrite": []
  }
}
```

**Security Considerations:**
- Expand `~` to actual home directory path
- On Linux, convert glob patterns to literal paths (Linux bubblewrap doesn't support globs)
- Validate all paths to prevent directory traversal
- Write config to temp file with restrictive permissions (0600)

### 5. Integrate with Existing CLI

**File:** `file:src/cli/index.ts` or sandbox command handler

**Modifications:**
- Add `--provider native` option to `sandbox-run` command
- Check `NativeProvider.isAvailable()` before allowing native provider selection
- Provide helpful error messages:
  - Windows: "Native sandboxing not supported on Windows. Use --provider docker or --provider e2b"
  - Missing srt: "srt CLI not found. Install with: npm install -g @anthropic-ai/sandbox-runtime"
  - Missing bwrap (Linux): "bubblewrap not found. Install with: apt-get install bubblewrap"

### 6. Create Configuration Types

**File:** `file:src/e2b/providers/types.ts` (or wherever provider types are defined)

```typescript
export interface NativeProviderConfig {
  allowedDomains?: string[];
  allowWritePaths?: string[];
  denyReadPaths?: string[];
  srtPath?: string; // Custom srt binary path
}

export interface NativeSandboxConfig extends SandboxConfig {
  provider: 'native';
  worktreePath: string;
  nativeConfig?: NativeProviderConfig;
}
```

### 7. Create Tests

**File:** `file:tests/e2b/native-provider.test.ts`

**Test Coverage:**

1. **Platform Detection Tests:**
   - `isAvailable()` returns true on macOS with srt installed
   - `isAvailable()` returns true on Linux with srt and bwrap installed
   - `isAvailable()` returns false on Windows
   - `isAvailable()` returns false when srt not installed

2. **Sandbox Creation Tests:**
   - Creates sandbox with unique instance ID
   - Generates srt config file with correct permissions
   - Tracks sandbox in internal state
   - Applies default configuration when not provided
   - Applies custom configuration when provided

3. **Command Execution Tests:**
   - Executes simple commands successfully
   - Streams output as AsyncGenerator
   - Handles command failures gracefully
   - Sanitizes prompts to prevent shell injection
   - Respects filesystem restrictions (write to allowed paths only)
   - Respects network restrictions (access to allowed domains only)

4. **Cleanup Tests:**
   - Removes srt config file on destroy
   - Removes instance from tracking
   - Handles cleanup errors gracefully

5. **Integration Tests:**
   - Full lifecycle: create → execute → destroy
   - Multiple concurrent sandboxes
   - Execute Claude Code with actual prompt (if srt available)

**Test Pattern** (follow existing pattern from `file:tests/e2b/sandbox-manager.test.ts`):
- Mock `execSync` and `spawn` for unit tests
- Use `vi.mock()` for external dependencies
- Create mock logger with `vi.fn()`
- Use `beforeEach` and `afterEach` for cleanup
- Target >85% coverage

### 8. Update Documentation

**File:** `file:docs/E2B_GUIDE.md` or create `file:docs/NATIVE_PROVIDER_GUIDE.md`

**Content:**
- Installation instructions for srt CLI
- Platform-specific setup (macOS vs Linux)
- Configuration options and examples
- Security model explanation
- Comparison with E2B provider
- Troubleshooting common issues

### 9. Add Environment Variable Support

**Environment Variables:**
```bash
PARALLEL_CC_NATIVE_ALLOWED_DOMAINS=github.com,api.anthropic.com
PARALLEL_CC_NATIVE_ALLOW_WRITE_PATHS=.,.git
PARALLEL_CC_NATIVE_DENY_READ_PATHS=~/.ssh,~/.aws,~/.gnupg
PARALLEL_CC_NATIVE_SRT_PATH=/custom/path/to/srt
```

**Implementation:**
- Read from environment in NativeProvider constructor
- Merge with config parameter (config takes precedence)
- Document in `file:SANDBOX_INTEGRATION_PLAN.md` (lines 96-100)

### 10. Error Handling

**Error Scenarios:**

1. **srt not installed:**
   - Detect in `isAvailable()`
   - Provide installation command in error message

2. **bubblewrap not installed (Linux):**
   - Detect in `isAvailable()`
   - Provide installation command: `sudo apt-get install bubblewrap`

3. **Permission denied:**
   - Catch EACCES errors when creating config file
   - Suggest checking temp directory permissions

4. **Command execution timeout:**
   - Implement timeout mechanism (default: 1 hour like E2B)
   - Kill process and clean up on timeout

5. **Sandbox violation:**
   - Parse srt violation logs (macOS only)
   - Log violations for debugging
   - Continue execution (violations are logged, not fatal)

## Architecture Diagram

```mermaid
sequenceDiagram
    participant CLI as CLI (sandbox-run)
    participant NP as NativeProvider
    participant SRT as srt CLI
    participant Claude as Claude Code
    participant FS as Local Filesystem

    CLI->>NP: create(config)
    NP->>NP: Generate instance ID
    NP->>FS: Write srt-settings.json
    NP-->>CLI: Return SandboxInstance

    CLI->>NP: execute(instanceId, command)
    NP->>NP: Build srt command
    NP->>SRT: spawn srt --settings config.json -- claude ...
    SRT->>Claude: Execute with security boundaries
    Claude->>FS: Read/Write (restricted)
    Claude-->>SRT: Output stream
    SRT-->>NP: Output chunks
    NP-->>CLI: Yield OutputChunk (AsyncGenerator)

    CLI->>NP: destroy(instanceId)
    NP->>FS: Delete srt-settings.json
    NP->>NP: Remove from tracking
    NP-->>CLI: Success
```

## Key Differences from E2BProvider

| Aspect | E2BProvider | NativeProvider |
|--------|-------------|----------------|
| **Startup** | 150ms (cloud VM) | Instant (local process) |
| **File Sync** | Upload/download via tarball | No sync (already local) |
| **Isolation** | Full VM | OS-level sandbox |
| **Network** | Full access | Configurable allowlist |
| **Cost** | $0.10/hr | Free |
| **Cleanup** | Kill remote sandbox | Delete config file |
| **Platform** | Any (cloud) | macOS, Linux only |

## Dependencies

**NPM Package:**
- `@anthropic-ai/sandbox-runtime` (peer dependency, not bundled)

**System Dependencies:**
- macOS: srt CLI (uses Seatbelt)
- Linux: srt CLI + bubblewrap

**Code Dependencies:**
- `SandboxProvider` interface (issue #30)
- Provider registry (issue #32)
- Existing types from `file:src/types.ts`
- Logger from `file:src/logger.ts`

## Success Criteria

- ✅ `NativeProvider.isAvailable()` correctly detects platform support
- ✅ Creates sandbox with unique instance ID and srt config
- ✅ Executes Claude Code commands with security boundaries
- ✅ Streams output in real-time via AsyncGenerator
- ✅ Respects filesystem restrictions (write only to worktree)
- ✅ Respects network restrictions (access only allowed domains)
- ✅ Cleans up config files on destroy
- ✅ Works on macOS with Seatbelt
- ✅ Works on Linux with bubblewrap
- ✅ Fails gracefully on Windows with helpful error
- ✅ Test coverage >85%
- ✅ Integration tests pass with real srt CLI (when available)

---

Execution Information

Branch: main
Commit: 136df60

---

💡 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.