[Phase 4.B] E2BAgentAdapter: cloud execution in isolated Linux VM

[frankbria]

Overview

Implement E2BAgentAdapter so that --engine cloud runs the CodeFrame agent inside a full Linux VM via the E2B SDK, enabling long-running, fully isolated execution without touching the local filesystem.

Motivation

Some tasks are too risky or too slow to run on the local filesystem:

• Tasks that modify many files across the repo
• Tasks needing specific OS-level dependencies
• Parallel tasks where each needs a full clean environment
• CI-grade isolation without spinning up Docker

E2B provides on-demand Linux sandboxes via API with up to 1-hour execution windows.

Deliverables

codeframe/adapters/e2b/adapter.py

class E2BAgentAdapter:
    """Runs CodeFrame's ReAct agent loop inside an E2B sandbox."""
    
    def execute(self, task: Task, context: TaskContext) -> AgentResult:
        # 1. Create E2B sandbox
        # 2. Upload workspace files (with credential scanning — no secrets)
        # 3. Install codeframe in sandbox
        # 4. Run ReactAgent inside sandbox
        # 5. Download changed files
        # 6. Return AgentResult

CLI

• --engine cloud on cf work start and cf work batch run
• Requires E2B_API_KEY in environment (validated at startup)

Budget tracking

• Track E2B sandbox-minutes per task and per batch
• cf work show <id> displays cloud execution cost
• Configurable timeout (default: 30 min, max: 60 min)

Credential scanning

• Before upload, scan for .env, secrets, API keys
• Refuse upload if credential patterns detected
• Log what was and wasn't uploaded

ExecutionContext integration

• IsolationLevel.CLOUD routes through this adapter
• context.workspace_path points to the downloaded results directory post-execution

Acceptance Criteria

• E2BAgentAdapter in codeframe/adapters/e2b/adapter.py
• --engine cloud flag wired in CLI and runtime
• E2B_API_KEY validated before execution starts
• Workspace upload with credential scanning
• Changed files downloaded and applied to local repo
• Timeout management (configurable, max 60 min)
• Budget/cost tracked and displayed in cf work show
• Tests with E2B sandbox mocked

Dependencies

• Depends on: [Phase 4.B] ExecutionContext abstraction: local | worktree | e2b-sandbox #532 (ExecutionContext abstraction)

Track

Phase 4.B — Execution Environment Layer

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

The codebase has a clean, well-layered adapter architecture. Engines are registered in file:codeframe/core/engine_registry.py via VALID_ENGINES, EXTERNAL_ENGINES, and BUILTIN_ENGINES frozensets, with factory functions get_external_adapter / get_builtin_adapter. The AgentAdapter protocol in file:codeframe/core/adapters/agent_adapter.py defines the run() interface all adapters must satisfy. API key validation for engines like codex is done at the CLI layer in file:codeframe/cli/app.py before the run record is created. The e2b SDK is not currently in pyproject.toml and must be added. There is no existing work show command.

Approach

Treat cloud as a new external engine (like claude-code) that routes through get_external_adapter. This keeps all engine-dispatch logic in the registry and avoids touching the builtin path. The adapter lives at file:codeframe/adapters/e2b/adapter.py (matching the ticket spec), with a thin shim in the existing adapters directory. Budget/cost is stored in the existing run_engine_log table via engine_stats, and a new work show command surfaces it.

---

Implementation Steps

1. Add e2b SDK dependency

In file:pyproject.toml, add e2b>=0.17.0 (or the latest stable version) to the dependencies list. Verify the exact package name is e2b on PyPI before finalising.

---

2. Create the E2B adapter package

Create the directory codeframe/adapters/e2b/ with an __init__.py that re-exports E2BAgentAdapter.

---

3. Implement codeframe/adapters/e2b/credential_scanner.py

Create a standalone module responsible for scanning files before upload. It should:

• Define a list of high-risk filename patterns: .env, .env.*, *.pem, *.key, id_rsa, credentials, secrets.*, etc.
• Define regex patterns for common secret formats: AKIA[0-9A-Z]{16} (AWS), sk-[a-zA-Z0-9]{48} (OpenAI), ghp_[a-zA-Z0-9]{36} (GitHub), generic API_KEY=, SECRET=, PASSWORD= assignments.
• Expose a scan_path(root: Path) -> ScanResult function that walks the directory tree, checks filenames against the blocklist, and samples file content against the regex patterns.
• ScanResult should carry: blocked_files: list[str], scanned_count: int, is_clean: bool.
• Log every file that was included and every file that was excluded with its reason.

---

4. Implement codeframe/adapters/e2b/adapter.py

Create E2BAgentAdapter implementing the AgentAdapter protocol from file:codeframe/core/adapters/agent_adapter.py.

class E2BAgentAdapter:
    name = "cloud"

    def __init__(self, timeout_minutes: int = 30) -> None: ...

    @classmethod
    def requirements(cls) -> dict[str, str]:
        return {"E2B_API_KEY": "E2B API key for cloud sandbox execution"}

    def run(
        self,
        task_id: str,
        prompt: str,
        workspace_path: Path,
        on_event: Callable[[AgentEvent], None] | None = None,
    ) -> AgentResult: ...

The run() method should follow this sequence:

sequenceDiagram
    participant CLI
    participant E2BAgentAdapter
    participant CredentialScanner
    participant E2BSandbox
    participant LocalFS

    CLI->>E2BAgentAdapter: run(task_id, prompt, workspace_path)
    E2BAgentAdapter->>CredentialScanner: scan_path(workspace_path)
    CredentialScanner-->>E2BAgentAdapter: ScanResult
    alt is_clean == False
        E2BAgentAdapter-->>CLI: AgentResult(status="failed", error="Credential scan failed")
    end
    E2BAgentAdapter->>E2BSandbox: Sandbox.create(timeout=timeout_s)
    E2BAgentAdapter->>E2BSandbox: Upload clean workspace files
    E2BAgentAdapter->>E2BSandbox: pip install codeframe (or copy package)
    E2BAgentAdapter->>E2BSandbox: Run ReactAgent via codeframe CLI inside sandbox
    loop Stream stdout
        E2BSandbox-->>E2BAgentAdapter: output line
        E2BAgentAdapter->>CLI: on_event(AgentEvent(type="output", ...))
    end
    E2BAgentAdapter->>E2BSandbox: Download changed files (git diff)
    E2BSandbox-->>E2BAgentAdapter: changed file contents
    E2BAgentAdapter->>LocalFS: Apply changed files to workspace_path
    E2BAgentAdapter->>E2BSandbox: sandbox.close()
    E2BAgentAdapter-->>CLI: AgentResult(status, modified_files, token_usage with sandbox_minutes)

Loading

Key implementation details:

• Use e2b.Sandbox (the E2B Python SDK's main class).
• Enforce timeout_minutes clamped to [1, 60]; convert to seconds for the SDK.
• Track wall-clock time from sandbox creation to close; store as sandbox_minutes in AdapterTokenUsage.cost_usd (or extend AgentResult with a metadata dict — see step 6).
• After the agent run inside the sandbox, run git diff --name-only HEAD inside the sandbox to identify changed files, then download each via sandbox.filesystem.read().
• Apply downloaded content to the local workspace_path files.
• Emit on_event progress events for: sandbox created, upload complete, agent started, agent output lines, download complete.

---

5. Register cloud in the engine registry

In file:codeframe/core/engine_registry.py:

• Add "cloud" to VALID_ENGINES and EXTERNAL_ENGINES.
• In get_external_adapter(), add an elif engine == "cloud": branch that imports and returns E2BAgentAdapter(timeout_minutes=kwargs.get("timeout_minutes", 30)).
• In _get_adapter_class(), add the corresponding elif engine == "cloud": branch.

---

6. Track sandbox budget in AgentResult / engine_stats

The existing AdapterTokenUsage in file:codeframe/core/adapters/agent_adapter.py has a cost_usd field. Use this to store the E2B cost estimate (sandbox-minutes × E2B rate). The engine_stats.record_run() in file:codeframe/core/engine_stats.py already persists tokens_used and duration_ms per run — duration_ms naturally captures sandbox wall-clock time.

To surface sandbox-minutes specifically, add a cloud_metadata: dict | None = None field to AgentResult (defaulting to None so no existing code breaks). E2BAgentAdapter populates it with {"sandbox_minutes": float, "cost_usd_estimate": float}.

---

7. Wire E2B_API_KEY validation in the CLI

In file:codeframe/cli/app.py, in the work_start function's API key validation block (around line 2370), add a branch:

elif engine == "cloud":
    from codeframe.cli.validators import require_e2b_api_key
    require_e2b_api_key()

Add the same check in batch_run (around line 3641).

In file:codeframe/cli/validators.py (or wherever require_anthropic_api_key lives), add require_e2b_api_key() that checks os.getenv("E2B_API_KEY") and raises typer.Exit(1) with a clear message if absent.

Also update the --engine help strings in both work_start and batch_run to include cloud.

---

8. Add configurable timeout option to work start and batch run

In file:codeframe/cli/app.py, add a new --cloud-timeout option (type int, default 30, help text noting max 60 min) to both work_start and batch_run. Pass it through runtime.execute_agent() → get_external_adapter("cloud", timeout_minutes=cloud_timeout).

Update execute_agent() in file:codeframe/core/runtime.py to accept and forward a cloud_timeout_minutes: int = 30 parameter, passing it as a kwarg to get_external_adapter.

---

9. Add cf work show <id> command

In file:codeframe/cli/app.py, add a new @work_app.command("show") function work_show(task_id: str, ...). It should:

• Look up the most recent run for the task via runtime.get_latest_run().
• Display run metadata: task title, run ID, status, started/completed timestamps, duration.
• Query engine_stats.get_run_log(workspace, limit=1) filtered to the run's ID to retrieve engine, duration_ms, tokens_used.
• If engine == "cloud", display a Cloud Execution Cost section showing sandbox minutes and estimated cost (retrieved from the run log or a new cloud_run_metadata table — see step 10).

---

10. Persist cloud-specific metadata

Add a new SQLite table cloud_run_metadata (created in the workspace schema migration) with columns: run_id TEXT PRIMARY KEY, sandbox_minutes REAL, cost_usd_estimate REAL, files_uploaded INT, files_downloaded INT, credential_scan_blocked INT, created_at TEXT.

Create codeframe/adapters/e2b/budget.py with:

• record_cloud_run(workspace, run_id, sandbox_minutes, cost_usd, files_uploaded, files_downloaded, scan_blocked) — inserts into cloud_run_metadata.
• get_cloud_run(workspace, run_id) -> dict | None — retrieves the record.

Call record_cloud_run() from E2BAgentAdapter.run() after the sandbox closes (passing the workspace via a constructor parameter or via a post-run callback).

work_show queries get_cloud_run() and renders the cost table using rich.table.Table.

---

11. Update codeframe/core/adapters/__init__.py

Add E2BAgentAdapter to the imports and __all__ list in file:codeframe/core/adapters/__init__.py, following the same pattern as ClaudeCodeAdapter.

---

Summary of files to create/modify

File	Action
pyproject.toml	Add e2b>=0.17.0 dependency
codeframe/adapters/e2b/__init__.py	Create (re-export E2BAgentAdapter)
codeframe/adapters/e2b/credential_scanner.py	Create
codeframe/adapters/e2b/adapter.py	Create (E2BAgentAdapter)
codeframe/adapters/e2b/budget.py	Create (cloud metadata persistence)
codeframe/core/engine_registry.py	Add "cloud" to sets and factory
codeframe/core/adapters/agent_adapter.py	Add cloud_metadata field to AgentResult
codeframe/core/adapters/__init__.py	Export E2BAgentAdapter
codeframe/core/runtime.py	Add cloud_timeout_minutes param to execute_agent
codeframe/cli/app.py	Add --engine cloud, --cloud-timeout, work show, E2B key validation
codeframe/cli/validators.py	Add require_e2b_api_key()
Workspace schema migration	Add cloud_run_metadata table

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a clean, well-layered adapter architecture. Engines are registered in `file:codeframe/core/engine_registry.py` via `VALID_ENGINES`, `EXTERNAL_ENGINES`, and `BUILTIN_ENGINES` frozensets, with factory functions `get_external_adapter` / `get_builtin_adapter`. The `AgentAdapter` protocol in `file:codeframe/core/adapters/agent_adapter.py` defines the `run()` interface all adapters must satisfy. API key validation for engines like `codex` is done at the CLI layer in `file:codeframe/cli/app.py` before the run record is created. The `e2b` SDK is **not** currently in `pyproject.toml` and must be added. There is no existing `work show` command.

## Approach

Treat `cloud` as a new **external engine** (like `claude-code`) that routes through `get_external_adapter`. This keeps all engine-dispatch logic in the registry and avoids touching the builtin path. The adapter lives at `file:codeframe/adapters/e2b/adapter.py` (matching the ticket spec), with a thin shim in the existing adapters directory. Budget/cost is stored in the existing `run_engine_log` table via `engine_stats`, and a new `work show` command surfaces it.

---

## Implementation Steps

### 1. Add `e2b` SDK dependency

In `file:pyproject.toml`, add `e2b>=0.17.0` (or the latest stable version) to the `dependencies` list. Verify the exact package name is `e2b` on PyPI before finalising.

---

### 2. Create the E2B adapter package

Create the directory `codeframe/adapters/e2b/` with an `__init__.py` that re-exports `E2BAgentAdapter`.

---

### 3. Implement `codeframe/adapters/e2b/credential_scanner.py`

Create a standalone module responsible for scanning files before upload. It should:

- Define a list of high-risk filename patterns: `.env`, `.env.*`, `*.pem`, `*.key`, `id_rsa`, `credentials`, `secrets.*`, etc.
- Define regex patterns for common secret formats: `AKIA[0-9A-Z]{16}` (AWS), `sk-[a-zA-Z0-9]{48}` (OpenAI), `ghp_[a-zA-Z0-9]{36}` (GitHub), generic `API_KEY=`, `SECRET=`, `PASSWORD=` assignments.
- Expose a `scan_path(root: Path) -> ScanResult` function that walks the directory tree, checks filenames against the blocklist, and samples file content against the regex patterns.
- `ScanResult` should carry: `blocked_files: list[str]`, `scanned_count: int`, `is_clean: bool`.
- Log every file that was included and every file that was excluded with its reason.

---

### 4. Implement `codeframe/adapters/e2b/adapter.py`

Create `E2BAgentAdapter` implementing the `AgentAdapter` protocol from `file:codeframe/core/adapters/agent_adapter.py`.

```
class E2BAgentAdapter:
    name = "cloud"

    def __init__(self, timeout_minutes: int = 30) -> None: ...

    @classmethod
    def requirements(cls) -> dict[str, str]:
        return {"E2B_API_KEY": "E2B API key for cloud sandbox execution"}

    def run(
        self,
        task_id: str,
        prompt: str,
        workspace_path: Path,
        on_event: Callable[[AgentEvent], None] | None = None,
    ) -> AgentResult: ...
```

The `run()` method should follow this sequence:

```mermaid
sequenceDiagram
    participant CLI
    participant E2BAgentAdapter
    participant CredentialScanner
    participant E2BSandbox
    participant LocalFS

    CLI->>E2BAgentAdapter: run(task_id, prompt, workspace_path)
    E2BAgentAdapter->>CredentialScanner: scan_path(workspace_path)
    CredentialScanner-->>E2BAgentAdapter: ScanResult
    alt is_clean == False
        E2BAgentAdapter-->>CLI: AgentResult(status="failed", error="Credential scan failed")
    end
    E2BAgentAdapter->>E2BSandbox: Sandbox.create(timeout=timeout_s)
    E2BAgentAdapter->>E2BSandbox: Upload clean workspace files
    E2BAgentAdapter->>E2BSandbox: pip install codeframe (or copy package)
    E2BAgentAdapter->>E2BSandbox: Run ReactAgent via codeframe CLI inside sandbox
    loop Stream stdout
        E2BSandbox-->>E2BAgentAdapter: output line
        E2BAgentAdapter->>CLI: on_event(AgentEvent(type="output", ...))
    end
    E2BAgentAdapter->>E2BSandbox: Download changed files (git diff)
    E2BSandbox-->>E2BAgentAdapter: changed file contents
    E2BAgentAdapter->>LocalFS: Apply changed files to workspace_path
    E2BAgentAdapter->>E2BSandbox: sandbox.close()
    E2BAgentAdapter-->>CLI: AgentResult(status, modified_files, token_usage with sandbox_minutes)
```

Key implementation details:
- Use `e2b.Sandbox` (the E2B Python SDK's main class).
- Enforce `timeout_minutes` clamped to `[1, 60]`; convert to seconds for the SDK.
- Track wall-clock time from sandbox creation to close; store as `sandbox_minutes` in `AdapterTokenUsage.cost_usd` (or extend `AgentResult` with a metadata dict — see step 6).
- After the agent run inside the sandbox, run `git diff --name-only HEAD` inside the sandbox to identify changed files, then download each via `sandbox.filesystem.read()`.
- Apply downloaded content to the local `workspace_path` files.
- Emit `on_event` progress events for: sandbox created, upload complete, agent started, agent output lines, download complete.

---

### 5. Register `cloud` in the engine registry

In `file:codeframe/core/engine_registry.py`:

- Add `"cloud"` to `VALID_ENGINES` and `EXTERNAL_ENGINES`.
- In `get_external_adapter()`, add an `elif engine == "cloud":` branch that imports and returns `E2BAgentAdapter(timeout_minutes=kwargs.get("timeout_minutes", 30))`.
- In `_get_adapter_class()`, add the corresponding `elif engine == "cloud":` branch.

---

### 6. Track sandbox budget in `AgentResult` / `engine_stats`

The existing `AdapterTokenUsage` in `file:codeframe/core/adapters/agent_adapter.py` has a `cost_usd` field. Use this to store the E2B cost estimate (sandbox-minutes × E2B rate). The `engine_stats.record_run()` in `file:codeframe/core/engine_stats.py` already persists `tokens_used` and `duration_ms` per run — `duration_ms` naturally captures sandbox wall-clock time.

To surface sandbox-minutes specifically, add a `cloud_metadata: dict | None = None` field to `AgentResult` (defaulting to `None` so no existing code breaks). `E2BAgentAdapter` populates it with `{"sandbox_minutes": float, "cost_usd_estimate": float}`.

---

### 7. Wire `E2B_API_KEY` validation in the CLI

In `file:codeframe/cli/app.py`, in the `work_start` function's API key validation block (around line 2370), add a branch:

```
elif engine == "cloud":
    from codeframe.cli.validators import require_e2b_api_key
    require_e2b_api_key()
```

Add the same check in `batch_run` (around line 3641).

In `file:codeframe/cli/validators.py` (or wherever `require_anthropic_api_key` lives), add `require_e2b_api_key()` that checks `os.getenv("E2B_API_KEY")` and raises `typer.Exit(1)` with a clear message if absent.

Also update the `--engine` help strings in both `work_start` and `batch_run` to include `cloud`.

---

### 8. Add configurable timeout option to `work start` and `batch run`

In `file:codeframe/cli/app.py`, add a new `--cloud-timeout` option (type `int`, default `30`, help text noting max 60 min) to both `work_start` and `batch_run`. Pass it through `runtime.execute_agent()` → `get_external_adapter("cloud", timeout_minutes=cloud_timeout)`.

Update `execute_agent()` in `file:codeframe/core/runtime.py` to accept and forward a `cloud_timeout_minutes: int = 30` parameter, passing it as a kwarg to `get_external_adapter`.

---

### 9. Add `cf work show <id>` command

In `file:codeframe/cli/app.py`, add a new `@work_app.command("show")` function `work_show(task_id: str, ...)`. It should:

- Look up the most recent run for the task via `runtime.get_latest_run()`.
- Display run metadata: task title, run ID, status, started/completed timestamps, duration.
- Query `engine_stats.get_run_log(workspace, limit=1)` filtered to the run's ID to retrieve `engine`, `duration_ms`, `tokens_used`.
- If `engine == "cloud"`, display a **Cloud Execution Cost** section showing sandbox minutes and estimated cost (retrieved from the run log or a new `cloud_run_metadata` table — see step 10).

---

### 10. Persist cloud-specific metadata

Add a new SQLite table `cloud_run_metadata` (created in the workspace schema migration) with columns: `run_id TEXT PRIMARY KEY`, `sandbox_minutes REAL`, `cost_usd_estimate REAL`, `files_uploaded INT`, `files_downloaded INT`, `credential_scan_blocked INT`, `created_at TEXT`.

Create `codeframe/adapters/e2b/budget.py` with:
- `record_cloud_run(workspace, run_id, sandbox_minutes, cost_usd, files_uploaded, files_downloaded, scan_blocked)` — inserts into `cloud_run_metadata`.
- `get_cloud_run(workspace, run_id) -> dict | None` — retrieves the record.

Call `record_cloud_run()` from `E2BAgentAdapter.run()` after the sandbox closes (passing the workspace via a constructor parameter or via a post-run callback).

`work_show` queries `get_cloud_run()` and renders the cost table using `rich.table.Table`.

---

### 11. Update `codeframe/core/adapters/__init__.py`

Add `E2BAgentAdapter` to the imports and `__all__` list in `file:codeframe/core/adapters/__init__.py`, following the same pattern as `ClaudeCodeAdapter`.

---

### Summary of files to create/modify

| File | Action |
|---|---|
| `pyproject.toml` | Add `e2b>=0.17.0` dependency |
| `codeframe/adapters/e2b/__init__.py` | Create (re-export `E2BAgentAdapter`) |
| `codeframe/adapters/e2b/credential_scanner.py` | Create |
| `codeframe/adapters/e2b/adapter.py` | Create (`E2BAgentAdapter`) |
| `codeframe/adapters/e2b/budget.py` | Create (cloud metadata persistence) |
| `codeframe/core/engine_registry.py` | Add `"cloud"` to sets and factory |
| `codeframe/core/adapters/agent_adapter.py` | Add `cloud_metadata` field to `AgentResult` |
| `codeframe/core/adapters/__init__.py` | Export `E2BAgentAdapter` |
| `codeframe/core/runtime.py` | Add `cloud_timeout_minutes` param to `execute_agent` |
| `codeframe/cli/app.py` | Add `--engine cloud`, `--cloud-timeout`, `work show`, E2B key validation |
| `codeframe/cli/validators.py` | Add `require_e2b_api_key()` |
| Workspace schema migration | Add `cloud_run_metadata` table |

---

Execution Information

Branch: main
Commit: 7d5caab

---

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

🔗 Related PRs

#363 - feat: wire ReactAgent into runtime with --engine react CLI flag [merged]
#429 - feat(core): Agent Adapter protocol definition [merged]
#437 - feat(adapters): Codex engine adapter with app-server JSON-RPC protocol [merged]
#451 - feat(engines): add Kilocode engine adapter (#417) [merged]
#514 - docs(roadmap): restructure Phase 4 with execution environment layer [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 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!