collaborating-with-codex

MANDATORY: ALWAYS run codex_bridge.py in the background. When invoking codex_bridge.py via the Bash tool, you MUST set run_in_background: true. Codex calls typically block for 60-120 seconds. Running them in the foreground freezes the entire conversation. Never omit this flag. No exceptions.

Sandbox policy: --sandbox read-only is rejected at the argparse layer. When --sandbox workspace-write is requested, the bridge first probes bubblewrap by calling bwrap --unshare-user --unshare-net --unshare-pid --ro-bind / / true (result cached for 5 minutes at /tmp/codex_bridge_bwrap_probe.<uid>). If the probe fails — typically bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted on Ubuntu 24.04+ with restricted unprivileged user namespaces, or in containers without CAP_NET_ADMIN — the bridge auto-downgrades to danger-full-access and writes a warning to stderr with the fix command (sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0). Set CODEX_BRIDGE_SKIP_BWRAP_PROBE=1 to bypass the probe when you know the host is fine. The default danger-full-access mode never runs the probe.

Workflow

Every delegation follows the same four steps. The recipe blocks below are variations on this spine.