Skip to content

docs(codex): troubleshoot bubblewrap unavailable in sandboxed runtimes#917

Merged
thepagent merged 4 commits into
mainfrom
docs/codex-bwrap-unavailable-908
May 24, 2026
Merged

docs(codex): troubleshoot bubblewrap unavailable in sandboxed runtimes#917
thepagent merged 4 commits into
mainfrom
docs/codex-bwrap-unavailable-908

Conversation

@chaodu-agent
Copy link
Copy Markdown
Collaborator

@chaodu-agent chaodu-agent commented May 24, 2026

Summary

Codex's Linux sandbox relies on bubblewrap (bwrap) for inner namespace isolation. This PR:

  1. Installs bubblewrap in Dockerfile.codex — aligns with Dockerfile.claude which already includes it. The official OpenAB Codex image now ships with bwrap out of the box.

  2. Documents how to disable the inner sandbox — for users who prefer not to use it (e.g., when the outer OpenAB runtime already provides container/VM isolation), the troubleshooting section in docs/codex.md explains how to set sandbox_mode = "danger-full-access" via config.toml, CLI flag, or Helm values.

The inner sandbox is available by default but not mandatory. Users can opt out with a config change.

Changes

  • Dockerfile.codex: add bubblewrap to apt-get install
  • docs/codex.md: add troubleshooting entry for bubblewrap is unavailable with disable instructions

What was tested

  • Verified Dockerfile syntax
  • Confirmed docs render correctly

Closes #908

https://discord.com/channels/1491295327620169908/1491365150664560881/1508104743560417371

…xed runtimes

When Codex runs inside an already-isolated OpenAB runtime without bubblewrap
installed, its inner sandbox fails with 'bubblewrap is unavailable'. Document
both resolution options: installing bwrap or disabling the inner sandbox.

Closes #908
@chaodu-agent chaodu-agent added the documentation Improvements or additions to documentation label May 24, 2026
@chaodu-agent chaodu-agent requested a review from thepagent as a code owner May 24, 2026 13:37
@chaodu-agent chaodu-agent added the documentation Improvements or additions to documentation label May 24, 2026
@github-actions github-actions Bot added the closing-soon PR missing Discord Discussion URL — will auto-close in 3 days label May 24, 2026
@chaodu-agent

This comment has been minimized.

@github-actions github-actions Bot added pending-maintainer and removed closing-soon PR missing Discord Discussion URL — will auto-close in 3 days labels May 24, 2026
@chaodu-agent

This comment has been minimized.

@chaodu-agent

This comment has been minimized.

@github-actions github-actions Bot added the closing-soon PR missing Discord Discussion URL — will auto-close in 3 days label May 24, 2026
@chaodu-agent

This comment has been minimized.

@github-actions github-actions Bot removed the closing-soon PR missing Discord Discussion URL — will auto-close in 3 days label May 24, 2026
@chaodu-agent
Copy link
Copy Markdown
Collaborator Author

LGTM ✅ — Clear troubleshooting documentation for a real pain point.

What This PR Does

Documents the bubblewrap is unavailable failure that occurs when Codex runs inside an already-isolated OpenAB runtime without bwrap installed. Provides the recommended solution: disable the inner sandbox since the outer runtime already provides isolation.

How It Works

Adds a new troubleshooting entry to docs/codex.md with config.toml, CLI, and Helm examples. Clearly distinguishes Codex inner sandbox from outer OpenAB runtime isolation.

Findings

# Severity Finding Location
1 🟢 Inner/outer sandbox distinction clearly explained with safety disclaimer docs/codex.md
2 🟢 Config coverage: config.toml, CLI flag, and Helm examples docs/codex.md
3 🟢 Non-privileged container reminder reinforces security model docs/codex.md

All findings addressed. PR is ready to merge.

@github-actions github-actions Bot added closing-soon PR missing Discord Discussion URL — will auto-close in 3 days and removed closing-soon PR missing Discord Discussion URL — will auto-close in 3 days labels May 24, 2026
Aligns with Dockerfile.claude which already includes bubblewrap.
This resolves the 'bubblewrap is unavailable' error at runtime.
@github-actions github-actions Bot added closing-soon PR missing Discord Discussion URL — will auto-close in 3 days and removed closing-soon PR missing Discord Discussion URL — will auto-close in 3 days labels May 24, 2026
@thepagent thepagent merged commit 2d95233 into main May 24, 2026
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation pending-maintainer

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

2 participants