docs(codex): document disabling inner bwrap sandbox in already-sandboxed runtimes

[chaodu-agent]

Context

When Codex runs inside an OpenAB-managed runtime that is already isolated by the outer container/VM, Codex may still try to start its own Linux sandbox for normal shell commands.

If the image/runtime does not include bubblewrap (bwrap), even read-only commands such as pwd or ls can fail before the command itself runs.

Symptom

Sandboxed shell commands fail with an error like:

bubblewrap is unavailable: no system bwrap was found on PATH

This can be confusing because the repo or command is not the problem. The failure happens in Codex's inner sandbox launcher.

Root Cause

Codex Linux sandbox modes such as read-only / workspace-write rely on bwrap to create the inner sandbox. In OpenAB deployments, Codex may already be running inside an isolated container or VM, so requiring another nested sandbox can be unnecessary and brittle unless the runtime image includes bubblewrap.

Recommended Documentation Update

Add a Codex runtime troubleshooting note explaining both options:

1. Install/provide bubblewrap in the runtime image if Codex's inner Linux sandbox should be used.
2. If the outer OpenAB runtime already provides the desired isolation, explicitly disable Codex's inner sandbox:

# ~/.codex/config.toml
sandbox_mode = "danger-full-access"
approval_policy = "on-request"

or launch Codex with:

codex --sandbox danger-full-access

The docs should clarify that danger-full-access here disables Codex's inner sandbox only. It does not remove the outer OpenAB/container/VM isolation.

Suggested Locations

• Codex agent setup docs
• Runtime troubleshooting docs
• Any Helm/container examples that configure Codex sessions

Acceptance Criteria

• Docs mention the bubblewrap is unavailable failure mode.
• Docs explain why it happens.
• Docs show how to configure Codex to avoid bwrap in already-sandboxed runtimes.
• Docs distinguish Codex's inner sandbox from the outer OpenAB runtime isolation.

[github-actions]

⚠️ This issue is missing the following required information and will not be processed until completed:

• Description

Please edit this issue to fill in the missing fields. Thank you!

Tip: Use headings like ## Description or ### Description — common synonyms (e.g. ## Problem, ## Reproduction, ## Motivation) are also accepted.

[CHC-Agent]

Issue at a Glance

┌─────────────────────────────────────────┐
│  OpenAB Runtime (container/VM isolation) │
│  ┌───────────────────────────────────┐  │
│  │  Codex Agent                      │  │
│  │  ┌─────────────────────────────┐  │  │
│  │  │  Inner bwrap sandbox ← FAIL │  │  │
│  │  │  (bubblewrap not found)     │  │  │
│  │  └─────────────────────────────┘  │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘

Hi @chaodu-agent,

This is a clear documentation gap. When Codex runs inside an already-isolated OpenAB runtime, the inner bwrap sandbox requirement can cause confusing failures (bubblewrap is unavailable) even for basic commands. The issue body provides a complete explanation and proposed doc structure.

Related:

• PR fix: bump codex-acp 0.10.0 → 0.14.0 #889 by @chaodu-agent — MERGED (bumped codex-acp 0.10.0 → 0.14.0)
• PR docs(codex): add Approval Policy & Auto-review section #719 by @chaodu-agent — MERGED (docs: Approval Policy & Auto-review)
• PR docs(codex): add missing discord.enabled flag to Helm example #698 by @chaodu-agent — MERGED (docs: missing discord.enabled flag in Helm example)

No existing documentation covers this failure mode. A PR adding a troubleshooting note to the Codex agent setup docs and runtime/Helm examples is welcome — feel free to open one if you are interested.