Codex Harness Integration#

Codex is integrated as a first-class harness in Agenta, on architectural parity with Claude and Pi. It runs inside the SandboxAgentBackend and is delivered via the Agent Client Protocol (ACP) over local, Daytona, and E2B sandboxes. The full integration landed in PR #5509 1 and shipped in v0.108.0 2. Sandbox support tracking is in issue #5502 3.

Key Entry Points#

1

SDK Layer (Python)#

CodexAgentTemplate (in dtos.py) defines Codex's configuration model. It exposes tool_specs, harness_permissions, and three wiring methods 1:

• wire_harness_mode() — returns an optional ACP session mode override (agent, read-only, or agent-full-access)
• wire_harness_files() — delegates to codex_settings.py to render config.toml
• wire_tools() — declares an empty built-in list; all tools arrive via MCP

codex_settings.py renders configuration in two layers 1:

• Layer 1 — passes the author's approval_policy and sandbox_mode through verbatim
• Layer 2 — derives sandbox_mode = "read-only" from a read-only filesystem boundary for reinforcement

capabilities.py advertises the curated Codex model list: gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-5.2 — all under the OpenAI provider only, with user HTTP MCP servers supported but no built-in MCP servers 1.

sandbox_agent.py adds Codex to its supported_harnesses frozenset 1.

Runner Layer (TypeScript)#

Four new TypeScript modules in services/runner/src/engines/sandbox_agent/ handle Codex-specific execution 1:

• codex-mode.ts — session mode resolution and application
• codex-assets.ts — credential provisioning and SQLite home redirection
• codex-acp-patch.ts — build-time approval preset patching
• executable-tools.ts — two-layer tool gating

run-turn.ts (modified) wires the buildExecutableToolGate for Codex, handles Codex's dot-notation MCP tool names (e.g., mcp.agenta-tools.discover_tools), and records gate decisions as "codex-acp-permission" for warm approval parking 1.

Design Decisions#

1. File-Free Managed Authentication (D-002)#

Instead of writing auth.json to disk (which creates security and cleanup risks on durable Daytona object storage), the SDK renders a model_providers block in config.toml pointing to env_key = "OPENAI_API_KEY". Codex reads the key from the daemon's process environment at request time 1. For subscription mode, only auth.json is symlinked into the runner-owned home to prevent operator config leakage 1.

2. Approval Preset Patching (D-008 Amendment)#

The codex-acp bridge hardcodes approvalPolicy: "never" in its agent-full-access preset, silently disabling all permission gates. codex-acp-patch.ts patches this to "on-request" at build time — applied to both the runner image and the Daytona snapshot — enabling warm approval parking (the turn stays alive and resumes when the user approves), matching Claude's behavior. The patch is idempotent and fails the image build loudly if its anchor drifts 1.

3. Durable Home + In-VM SQLite#

CODEX_HOME = <cwd>/.codex stays on the durable mount so native sessions and resume survive sandbox replacement. CODEX_SQLITE_HOME is redirected to an ephemeral in-VM directory because geesefs cannot support SQLite's write-ahead logging 1.

4. Two-Layer Tool Gating#

Tool execution is enforced at both the harness's native ACP gate (now enabled via the approval patch) and the runner's loopback MCP seam gate. Execution grants prevent double-prompting: one approval satisfies both layers. Gate verdicts are allow, deny, or pendingApproval (which parks the turn) 1.

Test Coverage#

Tests are stratified across unit, integration, and live QA:

SDK unit tests 1:

• test_codex_settings_layers.py — Layer 1/2 config rendering, managed vs. subscription auth, TOML formatting
• test_capabilities_codex.py — capability declarations
• test_wire_contract.py — wire contract validation including Codex fixtures

Runner unit tests 1:

• executable-tools.test.ts — tool gate decision matrix (allow/deny/ask), MCP envelope unwrapping, cold replay
• sandbox-agent-codex-assets.test.ts — credential provisioning, SQLite redirection, symlink idempotency
• codex-acp-patch.test.ts — patch idempotence and anchor validation
• codex-mode.test.ts — mode resolution and error handling
• session-keepalive-approval.test.ts — warm approval parking across turns

Integration test 1:

• test_codex_tool_replay.py — replays a real gpt-5.6-luna MCP tool invocation against the recorded codex-agenta-tools-call.json fixture

The post-rebase suite passes 731 SDK agent unit tests and 1477 runner tests (96 files) 1. Live QA covered the full approval matrix: {local, daytona} × {allow, deny, ask-warm, ask-cold}, achieving 20/20 on local and green across all Daytona cells 1.

Known Issues#

• Runner /health endpoint doesn't list Codex as a harness 4
• Subscription auth fails on turns after the first when the durable cwd is on the object store 5
• Daytona snapshot may ship an older Codex than the runner pin 6