From ff9d7c34c552595be38826443e50d745a0977133 Mon Sep 17 00:00:00 2001 From: Ubuntu Date: Tue, 12 May 2026 12:55:27 +0000 Subject: [PATCH] docs: add troubleshooting for bwrap sandbox failures on restricted hosts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document the bwrap loopback failure mode that surfaces on VPS / LXC / capability-restricted hosts (apply_patch + shell sandbox refuse to write). Covers root cause (Codex sandboxer cannot init network namespace), two workarounds (host-side sysctl unprivileged_userns_clone, codex-side bypass via config.toml), and notes that codex-companion.mjs hard-codes the per-turn sandbox to workspace-write — relevant when relying on a config.toml-level danger-full-access override. --- README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/README.md b/README.md index feeed04..d589c81 100644 --- a/README.md +++ b/README.md @@ -173,6 +173,63 @@ See: - Very long jobs can hit the wrapper timeout. - You should still review diffs before committing anything. +## Troubleshooting + +### `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted` + +Symptom: Codex tasks launched via `codex-task` complete with a status of +`completed` but the wrapper summary reads something like +`I couldn't create : apply_patch failed, shell commands failed at sandbox +startup, and the fallback MCP write was rejected`. + +The Codex CLI logs show: + +```text +bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted +``` + +Cause: Codex uses [bubblewrap](https://github.com/containers/bubblewrap) +(`bwrap`) to sandbox shell execution. On some hosts — VPS, restricted LXC +containers, kernels with `kernel.unprivileged_userns_clone=0`, hosts with +network capabilities dropped — `bwrap` cannot set up its loopback namespace, +which breaks both shell commands and `apply_patch` inside the Codex turn. + +This is not an issue with `claude-code-codex-task` itself — the wrapper's +launch / poll / result lifecycle still works correctly; only the Codex +worker's filesystem writes fail. + +Two fixes: + +1. **Host side** (preferred when possible): + + ```bash + sudo sysctl -w kernel.unprivileged_userns_clone=1 + echo 'kernel.unprivileged_userns_clone=1' | sudo tee /etc/sysctl.d/99-userns.conf + ``` + + Some hosting providers disallow this; check with your provider before + relying on it. + +2. **Bypass Codex sandbox** (acceptable when the host itself is already an + isolated sandbox): + + In `~/.codex/config.toml`: + + ```toml + approval_policy = "never" + sandbox_mode = "danger-full-access" + ``` + + Note that the upstream `codex-companion.mjs` task command currently + hard-codes the per-turn sandbox to `workspace-write` regardless of this + config (see [openai/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)), + so on broken-`bwrap` hosts you may also need to patch the companion script + to pass `danger-full-access` for write turns, or run Codex outside the + companion with `codex exec --dangerously-bypass-approvals-and-sandbox`. + + **Only use this on hosts where you accept that Codex can read and write + anywhere your user can.** Never enable this on a personal workstation. + ## Security Read `install.sh` before running it.