[P5.1] Sandbox provider-awareness (docker/e2b wrap any provider)

[frankbria]

Phase 5 — Cross-cutting. Make the sandbox layer provider-agnostic.

Scope

• lib/sandbox_docker.sh / lib/sandbox_e2b.sh currently wrap the Claude CLI call.
  Generalize the wrapped command to the active adapter's invocation.
• Per-provider credential/auth seeding inside the sandbox (ANTHROPIC_API_KEY for claude,
  OPENAI/CODEX auth for codex, GEMINI auth, GH token for copilot, etc.) — extend the
  existing credential-setup hooks per provider.
• The default ralph-sandbox image bundles claude; document which providers need a
  custom image / extra install (e.g. npm i -g @openai/codex).

Acceptance

• ralph --sandbox docker --provider codex (and e2b) execute the wrapped provider;
  claude path unchanged. Tests for the command-wrap generalization + credential routing.

Depends on: [P3.1].

[coderabbitai]

🔗 Related PRs

#308 - feat(ci): publish ralph-sandbox image to GHCR on release tags (#298) [closed]

---

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

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!

[github-actions]

🏷️ Triage: Enhancement

This issue has been categorized as an enhancement / feature request and labeled enhancement.

Why: [P5.1] is a well-scoped implementation task — make the sandbox layer (lib/sandbox_docker.sh / lib/sandbox_e2b.sh) provider-agnostic so docker/e2b can wrap any provider's CLI, with per-provider credential seeding and image documentation. It includes clear Scope and Acceptance criteria, so no additional information is needed (needs-info not applied).

Not a bug: this is planned forward-looking work, not a defect in existing behavior.

Not a duplicate: it is one phase of the broader multi-provider epic. Sibling phase issues cover different concerns — #312 (P1.1 command-construction seam), #314 (P1.3 provider selection surface), #317 (P3.1 Codex pilot adapter), #324 (P5.2 monitor/status surfacing). This issue uniquely owns the sandbox wrap generalization.

Recommended next steps:

• This work is blocked by its stated dependency [P3.1] ([P3.1] Codex adapter (pilot) — build + parse + capabilities + tests + docs #317) — the first non-Claude adapter must land before the sandbox layer can wrap an arbitrary provider's invocation. Sequence accordingly.
• Per the Acceptance criteria, ensure tests cover both the command-wrap generalization and per-provider credential routing, and verify the existing claude path stays byte-identical (mirrors the golden-args expectation in [P1.1] Command-construction seam: lib/agents/ registry + Claude reference adapter #312).

The existing multi-provider label is retained.

Generated by Issue Triage Assistant for issue #323 · opus48 356.9K · ◷

[coderabbitai]

Coding Plan

Summary

• Introduce a provider adapter interface extension that exposes CLI command names and credential requirements, allowing the sandbox layer to remain provider-agnostic
• Modify the single hardcoded line in wrap_claude_command_for_sandbox() to dynamically query the active provider
• Generalize credential setup functions in both sandbox providers to iterate over provider-declared requirements rather than hardcoding Claude-specific logic
• Add comprehensive tests for each provider's command wrapping and credential routing to ensure the acceptance criteria (ralph --sandbox docker --provider codex) is met

Design Choices

Design Choice 1: Provider Adapter Interface from P3.1

Options Considered:

1. Query a global variable like ACTIVE_PROVIDER and a lookup function for CLI command names
2. Have each adapter export a standardized interface (e.g., get_provider_cli_cmd(), get_provider_credentials_env())
3. Use a provider configuration associative array populated at startup

Chosen Option: 2

Rationale: Adapter-exported functions provide the cleanest abstraction, allowing each provider to define its own CLI command name and required credentials without the sandbox layer needing provider-specific knowledge.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Generalize Command Wrapping

Modify the sandbox layer to dynamically determine the in-sandbox CLI command name based on the active provider adapter, removing the hardcoded "claude" reference.

Task 1: Add Provider CLI Command Query Interface

Define how the sandbox layer queries the active provider for its CLI command name.

• Extend the provider adapter interface (created by P3.1) to export a function like get_provider_sandbox_cmd() that returns the CLI command name expected inside the sandbox (e.g., "claude", "codex", "gemini")
• Each adapter implementation should provide this function, returning the appropriate command name
• Add a fallback in the query function that returns the value of PROVIDER_CODE_CMD (analogous to current CLAUDE_CODE_CMD) if no adapter-specific function exists

Task 2: Update wrap_claude_command_for_sandbox()

Replace the hardcoded command name with a dynamic lookup.

• In ralph_loop.sh, modify wrap_claude_command_for_sandbox() at the line where sandbox_cmd[0]="claude" is set
• Replace the hardcoded string with a call to the provider's sandbox command function
• Rename the function to wrap_provider_command_for_sandbox() to reflect its generalized purpose
• Update all call sites of this function (should be minimal since it's called from the execution loop)

Task 3: Update Sandbox Exec Arg Builders

Ensure the build functions in both sandbox providers handle arbitrary command names correctly.

• In lib/sandbox_docker.sh, verify build_sandbox_exec_args() passes through the command array without Claude-specific assumptions
• In lib/sandbox_e2b.sh, verify build_e2b_exec_args() similarly passes through commands generically
• Both functions already accept "$@" as the command to wrap, so changes should be minimal validation/cleanup

🤖 Prompt for AI agents

This phase generalizes the sandbox command wrapping in `ralph_loop.sh` and both
sandbox provider libraries to remove the hardcoded "claude" CLI command
reference and replace it with a dynamic provider-based lookup.

- In the provider adapter interface (established by P3.1), add a
`get_provider_sandbox_cmd()` function to each adapter that returns the CLI
command name expected inside the sandbox (e.g., "claude", "codex", "gemini").
Include a fallback that returns `PROVIDER_CODE_CMD` if the adapter-specific
function does not exist.
- In `ralph_loop.sh`, locate `wrap_claude_command_for_sandbox()` and find the
line setting `sandbox_cmd[0]="claude"`. Replace the hardcoded `"claude"` string
with a call to `get_provider_sandbox_cmd()`. Rename the function to
`wrap_provider_command_for_sandbox()` and update all call sites accordingly.
- In `lib/sandbox_docker.sh`, review `build_sandbox_exec_args()` to confirm it
passes through the command array (`"$@"`) without any Claude-specific
assumptions; apply minimal cleanup if needed.
- In `lib/sandbox_e2b.sh`, review `build_e2b_exec_args()` similarly and apply
minimal cleanup if needed.

Phase 2: Provider-Aware Credential Seeding

Extend the credential setup mechanisms in both sandbox providers to support multiple AI providers' authentication requirements.

Task 1: Define Provider Credential Requirements Interface

Establish a standardized way for providers to declare their credential needs.

• Extend the provider adapter interface to export credential requirements: environment variable names (e.g., ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, GITHUB_TOKEN) and credential file paths (e.g., ~/.claude/.credentials.json)
• Create a function like get_provider_credential_env_vars() and get_provider_credential_files() in each adapter
• Document the expected format (array of env var names, array of file paths)

Task 2: Extend Docker Credential Setup

Generalize setup_docker_credentials() to seed credentials for any provider.

• Refactor setup_docker_credentials() in lib/sandbox_docker.sh to query the active provider's credential requirements
• For each required env var: check if set, write to the env-file (maintaining the 0600 permission pattern)
• For each required credential file: copy to the sandbox home directory with appropriate permissions
• Maintain backward compatibility: Claude's ANTHROPIC_API_KEY and ~/.claude/.credentials.json handling should work unchanged
• Add provider-specific subdirectory handling in the sandbox home (e.g., .claude/, .codex/, .gemini/)

Task 3: Extend E2B Credential Setup

Generalize E2B credential seeding for multiple providers.

• Refactor setup_e2b_credentials() and _seed_e2b_claude_credentials() in lib/sandbox_e2b.sh
• Rename _seed_e2b_claude_credentials() to _seed_e2b_provider_credentials() or similar
• Query the active provider's credential requirements
• For env vars: pass them to the sandbox at create time via the helper's environment mechanism
• For credential files: seed them via the write-file helper command (maintaining the stdin-based security pattern)
• Ensure the E2B API key handling (E2B_API_KEY) remains separate from provider credentials

Task 4: Credential Routing Logic

Implement the routing that connects provider selection to credential seeding.

• Add a dispatch function that routes to the appropriate credential setup based on ACTIVE_PROVIDER (or equivalent from P3.1)
• Handle the case where multiple credentials might be needed (e.g., a provider using both an API key and OAuth)
• Add clear error messages when required credentials are missing, with actionable guidance per provider

🤖 Prompt for AI agents

This phase generalizes credential seeding in both `lib/sandbox_docker.sh` and
`lib/sandbox_e2b.sh` to support any provider's authentication requirements
rather than Claude-specific hardcoded logic.

- In the provider adapter interface, add `get_provider_credential_env_vars()`
and `get_provider_credential_files()` functions to each adapter. These should
return arrays of required env var names (e.g., `ANTHROPIC_API_KEY`,
`OPENAI_API_KEY`, `GEMINI_API_KEY`, `GITHUB_TOKEN`) and credential file paths
(e.g., `~/.claude/.credentials.json`) respectively. Document the expected return
format (array of env var names, array of file paths).
- In `lib/sandbox_docker.sh`, refactor `setup_docker_credentials()` to:
- Call `get_provider_credential_env_vars()` and iterate over each; check if set
and write to the env-file (maintain 0600 permissions)
- Call `get_provider_credential_files()` and iterate over each; copy to the
sandbox home directory with appropriate permissions
- Add provider-specific subdirectory handling (e.g., `.claude/`, `.codex/`,
`.gemini/`)
- Preserve backward compatibility so Claude's `ANTHROPIC_API_KEY` and
`~/.claude/.credentials.json` continue to work unchanged
- In `lib/sandbox_e2b.sh`, refactor `setup_e2b_credentials()` and rename
`_seed_e2b_claude_credentials()` to `_seed_e2b_provider_credentials()`. Update
to:
  - Query active provider credential requirements via the interface functions
- Pass env vars to the sandbox at create time via the helper's environment
mechanism
- Seed credential files via the `write-file` helper command (maintain
stdin-based security pattern)
  - Keep `E2B_API_KEY` handling separate and unchanged
- Add a dispatch function (routed by `ACTIVE_PROVIDER` or equivalent from P3.1)
that routes to the appropriate credential setup. Handle cases where multiple
credentials are needed. Add clear, actionable error messages when required
credentials are missing.

Phase 3: Documentation and Testing

Document provider-specific requirements and add comprehensive tests for the generalized sandbox behavior.

Task 1: Document Provider Image Requirements

Create documentation for custom sandbox images per provider.

• Update or create documentation (in README, docs/, or CLAUDE.md) explaining which providers need custom Docker images
• Document the default ralph-sandbox image's contents (currently bundles Claude CLI)
• Provide instructions for building custom images with other providers (e.g., npm i -g @openai/codex`` for Codex)
• Document E2B template requirements for each provider

Task 2: Update ralphrc Template

Add configuration examples for provider-specific sandbox settings.

• In templates/ralphrc.template, add commented examples showing sandbox usage with different providers
• Document any new SANDBOX_* variables added for provider credential configuration
• Include examples of custom image configuration per provider

Task 3: Add Command Wrap Generalization Tests

Test that sandbox wrapping works correctly for multiple providers.

• In tests/integration/test_docker_execution.bats, add tests verifying:
  • wrap_provider_command_for_sandbox uses the active provider's CLI command (not hardcoded "claude")
  • Command wrapping works for codex, gemini, copilot providers
  • Host paths are still rewritten correctly for all providers
• In tests/integration/test_e2b_execution.bats, add equivalent tests for E2B wrapping
• Update existing tests that reference the old function name

Task 4: Add Credential Routing Tests

Test provider-specific credential seeding in sandbox environments.

• In tests/unit/test_sandbox_docker.bats, add tests for:
  • OPENAI_API_KEY env var is written to env-file when codex provider is active
  • GEMINI_API_KEY handling for gemini provider
  • GITHUB_TOKEN handling for copilot provider
  • Multiple credentials can be seeded simultaneously
  • Missing required credentials produce actionable error messages
• In tests/unit/test_sandbox_e2b.bats, add equivalent credential seeding tests for E2B
• Test that Claude credential handling remains unchanged (backward compatibility)

🤖 Prompt for AI agents

This phase covers documentation updates and test additions to verify and
communicate the generalized sandbox behavior.

**Documentation:**
- Update or create documentation in README, docs/, or CLAUDE.md explaining which
providers require custom Docker images, the contents of the default
`ralph-sandbox` image (currently bundles Claude CLI), instructions for building
custom images for other providers (e.g., `npm i -g `@openai/codex`` for Codex),
and E2B template requirements per provider.
- In `templates/ralphrc.template`, add commented examples demonstrating sandbox
usage with different providers, document any new `SANDBOX_*` variables, and
include examples of custom image configuration per provider.

**Tests:**
- In `tests/integration/test_docker_execution.bats`:
- Add tests that `wrap_provider_command_for_sandbox` uses the active provider's
CLI command (not hardcoded "claude"), works for codex/gemini/copilot providers,
and correctly rewrites host paths for all providers
- Update existing tests referencing the old function name
`wrap_claude_command_for_sandbox`
- In `tests/integration/test_e2b_execution.bats`: add equivalent E2B wrapping
tests and update old function name references
- In `tests/unit/test_sandbox_docker.bats`: add tests for `OPENAI_API_KEY`
(codex), `GEMINI_API_KEY` (gemini), `GITHUB_TOKEN` (copilot), multiple
simultaneous credentials, and actionable error messages for missing credentials
- In `tests/unit/test_sandbox_e2b.bats`: add equivalent credential seeding tests
for E2B
- In both test files, verify that Claude credential handling remains unchanged
(backward compatibility)

Research

Ralph uses two sandbox providers (Docker and E2B) that execute AI commands in isolated environments. The current implementation is hardcoded to Claude: wrap_claude_command_for_sandbox() in ralph_loop.sh unconditionally sets sandbox_cmd[0]="claude", and credential setup functions (setup_docker_credentials, setup_e2b_credentials) only handle ANTHROPIC_API_KEY and ~/.claude/.credentials.json. Both sandbox providers export build_*_exec_args functions that wrap the command array for execution. This ticket assumes P3.1 has established a provider adapter system that exposes which provider is active and its CLI command name.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase generalizes the sandbox command wrapping in `ralph_loop.sh` and both
sandbox provider libraries to remove the hardcoded "claude" CLI command
reference and replace it with a dynamic provider-based lookup.

- In the provider adapter interface (established by P3.1), add a
`get_provider_sandbox_cmd()` function to each adapter that returns the CLI
command name expected inside the sandbox (e.g., "claude", "codex", "gemini").
Include a fallback that returns `PROVIDER_CODE_CMD` if the adapter-specific
function does not exist.
- In `ralph_loop.sh`, locate `wrap_claude_command_for_sandbox()` and find the
line setting `sandbox_cmd[0]="claude"`. Replace the hardcoded `"claude"` string
with a call to `get_provider_sandbox_cmd()`. Rename the function to
`wrap_provider_command_for_sandbox()` and update all call sites accordingly.
- In `lib/sandbox_docker.sh`, review `build_sandbox_exec_args()` to confirm it
passes through the command array (`"$@"`) without any Claude-specific
assumptions; apply minimal cleanup if needed.
- In `lib/sandbox_e2b.sh`, review `build_e2b_exec_args()` similarly and apply
minimal cleanup if needed.
===============================================================================

Task: 2

This phase generalizes credential seeding in both `lib/sandbox_docker.sh` and
`lib/sandbox_e2b.sh` to support any provider's authentication requirements
rather than Claude-specific hardcoded logic.

- In the provider adapter interface, add `get_provider_credential_env_vars()`
and `get_provider_credential_files()` functions to each adapter. These should
return arrays of required env var names (e.g., `ANTHROPIC_API_KEY`,
`OPENAI_API_KEY`, `GEMINI_API_KEY`, `GITHUB_TOKEN`) and credential file paths
(e.g., `~/.claude/.credentials.json`) respectively. Document the expected return
format (array of env var names, array of file paths).
- In `lib/sandbox_docker.sh`, refactor `setup_docker_credentials()` to:
- Call `get_provider_credential_env_vars()` and iterate over each; check if set
and write to the env-file (maintain 0600 permissions)
- Call `get_provider_credential_files()` and iterate over each; copy to the
sandbox home directory with appropriate permissions
- Add provider-specific subdirectory handling (e.g., `.claude/`, `.codex/`,
`.gemini/`)
- Preserve backward compatibility so Claude's `ANTHROPIC_API_KEY` and
`~/.claude/.credentials.json` continue to work unchanged
- In `lib/sandbox_e2b.sh`, refactor `setup_e2b_credentials()` and rename
`_seed_e2b_claude_credentials()` to `_seed_e2b_provider_credentials()`. Update
to:
  - Query active provider credential requirements via the interface functions
- Pass env vars to the sandbox at create time via the helper's environment
mechanism
- Seed credential files via the `write-file` helper command (maintain
stdin-based security pattern)
  - Keep `E2B_API_KEY` handling separate and unchanged
- Add a dispatch function (routed by `ACTIVE_PROVIDER` or equivalent from P3.1)
that routes to the appropriate credential setup. Handle cases where multiple
credentials are needed. Add clear, actionable error messages when required
credentials are missing.
===============================================================================

Task: 3

This phase covers documentation updates and test additions to verify and
communicate the generalized sandbox behavior.

**Documentation:**
- Update or create documentation in README, docs/, or CLAUDE.md explaining which
providers require custom Docker images, the contents of the default
`ralph-sandbox` image (currently bundles Claude CLI), instructions for building
custom images for other providers (e.g., `npm i -g `@openai/codex`` for Codex),
and E2B template requirements per provider.
- In `templates/ralphrc.template`, add commented examples demonstrating sandbox
usage with different providers, document any new `SANDBOX_*` variables, and
include examples of custom image configuration per provider.

**Tests:**
- In `tests/integration/test_docker_execution.bats`:
- Add tests that `wrap_provider_command_for_sandbox` uses the active provider's
CLI command (not hardcoded "claude"), works for codex/gemini/copilot providers,
and correctly rewrites host paths for all providers
- Update existing tests referencing the old function name
`wrap_claude_command_for_sandbox`
- In `tests/integration/test_e2b_execution.bats`: add equivalent E2B wrapping
tests and update old function name references
- In `tests/unit/test_sandbox_docker.bats`: add tests for `OPENAI_API_KEY`
(codex), `GEMINI_API_KEY` (gemini), `GITHUB_TOKEN` (copilot), multiple
simultaneous credentials, and actionable error messages for missing credentials
- In `tests/unit/test_sandbox_e2b.bats`: add equivalent credential seeding tests
for E2B
- In both test files, verify that Claude credential handling remains unchanged
(backward compatibility)

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!