Mitchell Foutz All writing

Sandboxing Codex CLI with bubblewrap on WSL

A probe on 2026-08-30 showed Codex CLI, started with --sandbox read-only, reading a file at an absolute path outside its working directory and listing the root of an unrelated repository. The codex-sandbox wrapper in agent-controls runs Codex in a bubblewrap mount namespace that holds only the configured root containing the current directory. Paths outside that root, other than a fixed set of system and configured paths, do not exist for the Codex process.

Published
2026-10-28 (draft)
Topic
Agent engineering
Source
darblinko/agent-controls
Revision
fb209b2
Codex CLI version in the probe
Not recorded

The 2026-08-30 probe: read-only mode left reads open

The header of bin/codex-sandbox records the probe. Codex was started in read-only mode. It read a file at an arbitrary absolute path outside its --cd directory, and it listed the root of an unrelated repository.

The repository draws two conclusions from that result. The --sandbox read-only policy restricts writes and leaves reads open. The project trust settings in Codex's config.toml govern approval prompts and do not set a filesystem scope.

The threat model adds an inference: under the read-only policy, any file the user can read can become part of a Codex prompt, and a prompt leaves the machine. The threat model labels this T3.

The record has gaps. The Codex CLI version used in the probe was not recorded. The record states the outcome; it does not include the command line, the transcript or the paths used. Codex behavior may have changed since that date. Codex was not run for this article. The threat model gives a reproduction procedure whose outcome depends on the installed Codex version.

Inference: the wrapper's boundary does not depend on how a given Codex version applies its own policy, because a path that is not mounted in the namespace does not exist for any process inside it.

Mount layout inside the namespace

The wrapper reads sandbox.conf, finds the configured root that contains the current directory, and starts bubblewrap with the layout below. Only that root is bound. The other configured roots are absent for that session. tool and state paths from the config are bound in every session.

Path inside the namespaceStateLine
/usr, /etcRead-only bind218, 222
/bin, /sbin, /lib, /lib64Read-only bind when the host has the path (--ro-bind-try)219 to 221
Target of /etc/resolv.conf when it lies outside /etcRead-only bind of that one file, for DNS223 to 228
/proc, /devNew procfs and new /dev229
/tmp, /home, $HOME, /mntEmpty tmpfs222, 229
tool pathsRead-only bind275
state paths, for example $HOME/.codexRead-write bind, created when missing109 to 111, 276
The matched rw rootRead-write bind241 to 242
The matched ro rootRead-only bind243 to 244
An ro root with a subtree listRead-only binds of the listed subtrees that exist; the rest of the root, .git included, is absent248 to 254
.env* and mask matches in the bound root/dev/null bound read-only over each file198 to 214, 278 to 280
NetworkHost network namespace kept (--share-net)289
Other namespacesNew (--unshare-all)289

The bubblewrap arguments

base_args builds the fixed part of the command. main appends the tool, state and root binds, the /dev/null masks, the environment changes and the namespace flags.

  bwrap_args=(--ro-bind /usr /usr)
  for dir in /bin /sbin /lib /lib64; do
    bwrap_args+=(--ro-bind-try "$dir" "$dir")
  done
  bwrap_args+=(--ro-bind /etc /etc --tmpfs /mnt)
  # /etc/resolv.conf is often a symlink into /mnt/wsl or /run; bind its target
  # alone so DNS works while the rest of /mnt and /run stays absent.
  resolv=$(readlink -f /etc/resolv.conf 2>/dev/null || true)
  if [[ -n $resolv && $resolv != /etc/* ]]; then
    bwrap_args+=(--ro-bind-try "$resolv" "$resolv")
  fi
  bwrap_args+=(--proc /proc --dev /dev --tmpfs /tmp --tmpfs /home --tmpfs "$HOME")
  ...
  bwrap_args+=("${env_args[@]}" --unsetenv WSL_INTEROP --unsetenv WSLENV)
  bwrap_args+=(--unshare-all --share-net --die-with-parent --chdir "$cwd" "$codex_bin" "$@")
Excerpt from bin/codex-sandbox, lines 218 to 229 and 288 to 289.

Bubblewrap applies the mount operations in the order given. The empty tmpfs on $HOME is mounted first. The binds of the root, tool and state paths that lie under $HOME are placed on top of it, and the /dev/null overmounts come last.

The README's dry run prints the full command, one argument per line. The output below comes from a throwaway home directory with the config shown. Arguments are joined per operation, and the throwaway path is written as $HOME.

# $HOME/.config/agent-controls/sandbox.conf
rw ~/src/my-app
ro ~/src/vendor-library
ro ~/src/governed-repo docs src tools
tool ~/tools/node
state ~/.codex
unsetenv GH_TOKEN
mask *.pem

$ cd $HOME/src/my-app
$ CODEX_SANDBOX_DRY_RUN=1 codex-sandbox exec "list the files"
bwrap
  --ro-bind /usr /usr
  --ro-bind-try /bin /bin
  --ro-bind-try /sbin /sbin
  --ro-bind-try /lib /lib
  --ro-bind-try /lib64 /lib64
  --ro-bind /etc /etc
  --tmpfs /mnt
  --ro-bind-try <resolv.conf target> <resolv.conf target>
  --proc /proc
  --dev /dev
  --tmpfs /tmp
  --tmpfs /home
  --tmpfs $HOME
  --ro-bind $HOME/tools/node $HOME/tools/node
  --bind $HOME/.codex $HOME/.codex
  --bind $HOME/src/my-app $HOME/src/my-app
  --ro-bind /dev/null $HOME/src/my-app/certs/server.pem
  --ro-bind /dev/null $HOME/src/my-app/api/.env.local
  --ro-bind /dev/null $HOME/src/my-app/.env
  --unsetenv GH_TOKEN
  --unsetenv WSL_INTEROP
  --unsetenv WSLENV
  --unshare-all --share-net --die-with-parent
  --chdir $HOME/src/my-app
  $HOME/tools/node/bin/codex exec "list the files"

Only $HOME/src/my-app appears. vendor-library and governed-repo are configured roots and are not bound in this session. Started from $HOME/src/governed-repo, the same config binds docs, src and tools read-only and turns exec into exec --skip-git-repo-check, because that root's .git is absent.

Refusal outside every root

The wrapper decides whether to start before it builds any bubblewrap argument. find_root compares the physical current directory (pwd -P) with every configured root and returns the longest root that contains it. Roots are resolved with readlink -f when the config is read, so a symbolic link to a directory is compared by its target.

When no root matches, the wrapper prints the configured roots and exits 1. No namespace is created and Codex does not start:

$ cd $HOME/elsewhere && codex-sandbox exec x
codex-sandbox: $HOME/elsewhere is outside every configured root ($HOME/src/my-app $HOME/src/vendor-library $HOME/src/governed-repo); cd into one, or set CODEX_UNCONFINED=1 to bypass

Four further checks stop the wrapper with exit 1:

  1. The current directory is inside a subtree root but outside its listed subtrees. Started in governed-repo/confidential, the message was ... is inside $HOME/src/governed-repo but outside its bound subtrees: docs src tools.
  2. The Codex executable, or the target of its symbolic link, is outside every bound path. A tool line for its install directory fixes this.
  3. The config names / as a root, gives subtrees to an rw root, or gives a subtree that is absolute or contains ...
  4. The config file is missing, has an unknown keyword or a relative path, or leaves no usable root.

A configured root that is not a directory is skipped with a warning; the remaining roots still apply.

What a process inside the namespace sees

For this article the wrapper was also run outside dry-run mode, in the throwaway home directory from the previous section, with the stand-in Codex from the test suite. The stand-in runs its first argument as a shell command. Results on 2026-10-28:

Inference: cat .env fails instead of returning an empty file because bubblewrap's --ro-bind does not grant device access on the mount it creates, so the /dev/null device node cannot be opened there. The threat model states the observed result: reads of a masked file fail.

Tests by area

tests/test_codex_sandbox.py has 23 test functions. One is parametrized over 4 config errors, so pytest collects 26 cases. 21 cases call the wrapper with CODEX_SANDBOX_DRY_RUN=1 and check the bwrap argument list. 5 cases start the stand-in Codex in a real namespace and check what it can reach. The grouping into areas below is mine.

AreaWhat the cases check
Root selection and bindingAn rw root is bound read-write and set as the working directory. An ro root is bound read-only. The longest matching root wins. In a namespace: a file outside the root does not exist, a write to an ro root fails, a write to an rw root succeeds.
Config errorsUnknown keyword, relative path, setenv with one argument, / as a root, missing config file.
Subtree rootsOnly the listed subtrees are bound and exec gets --skip-git-repo-check. Refusal in an unlisted subdirectory. Subtrees on an rw root and subtrees containing .. are rejected.
Secret file masking.env and .env.local are masked and copies under node_modules and .venv are skipped. mask *.pem adds a pattern. In a namespace: the content of .env does not reach standard output.
Empty HOME and /tmp, WSL routestmpfs on /tmp, /home and $HOME. tmpfs on /mnt, WSL_INTEROP and WSLENV unset, no bind sourced from /init, /run, /mnt or /. In a namespace: a planted .ssh is absent from $HOME, /mnt holds nothing other than wsl, and /init is absent.
Startup refusalsRefusal outside every root. Refusal when the Codex executable is outside every bound path.
Codex binary lookup and bypassCODEX_UNCONFINED=1 runs the binary directly. The PATH lookup skips the wrapper itself.
State, tool and environment linesA state directory is created and bound read-write, a tool path is bound read-only, setenv expands ~/, unsetenv is passed through.

The repository's suite collects 72 cases in 4 files: 26 for the sandbox, 28 for the review gate, 13 for claude_profile and 5 link checks. The README's figure of 67 control tests excludes the link checks. On 2026-10-28 all 72 passed in a local run on the WSL2 machine used for this article (as reported from that run; docs/data.json line 19 at fb209b2 records "of 72 in tests/, all pass"), and none was skipped, so the 5 namespace cases ran. The namespace cases skip where bubblewrap cannot create a namespace. CI installs bubblewrap on Ubuntu 24.04 and turns off the AppArmor restriction on unprivileged user namespaces so that they run there.

Threats addressed and not addressed

The threat model covers a Linux or WSL2 workstation where Codex runs as the developer's own user and, without controls, can read every file that user can read. The rows below are its entries for codex-sandbox.

ThreatAddressedMechanism or reason
T1: reads outside the working rootYesOnly the configured root containing the current directory is bound. The wrapper refuses to start outside every root.
T1: reads of dotfiles in $HOMEYes/tmp, /home and $HOME are empty tmpfs mounts. Only tool and state paths are bound back.
T1: partial access to a governed repositoryYesro <root> <subtree>... binds the listed subtrees only. .git is absent, so history of unlisted directories is unreachable.
T2: .env files inside the rootYesRegular files named .env* or matching a mask pattern are overmounted with /dev/null, except inside the five pruned directories listed under Masking below.
T2: credentials in environment variablesNamed onesunsetenv lines remove the variables they name.
Writes to a reference repositoryYesro roots are read-only binds.
WSL: Windows drives, the interop socketYes/mnt is an empty tmpfs and /run is absent, except for the resolv.conf target when it lies under one of them. /init is absent. WSL_INTEROP and WSLENV are unset.
WSL: Windows executables through binfmt_miscUntested/init is absent. The effect depends on the interop handler's registration flags, which were not checked.
Network egressNoThe network is shared because the Codex API needs it. Anything in the bound root can be sent anywhere the machine can reach.
Environment variables in generalNoThe calling shell's environment passes through, except WSL_INTEROP, WSLENV and unsetenv entries.
Secrets under other namesNoMasking matches regular file names at start. Other names, files created after launch, symbolic links and files in the pruned directories are not masked.
Everything that is boundNoThe root, every tool path and every state path are visible. ~/.codex, which holds Codex's own credentials, is usually a read-write state path. /etc is bound read-only in full.
BypassNoCODEX_UNCONFINED=1, or the real Codex binary run by its absolute path, skips the namespace.
Other agentsNoClaude Code is not confined by this wrapper. It has its own permission system.
Malicious local user, kernel or bubblewrap exploits, compromised Codex binaryOut of scopeListed as out of scope for the repository as a whole.

Limits

WSL

Codex's own sandbox modes

What bubblewrap does not isolate in this configuration

Masking

Bypass and setup

Run it

Requirements from the README: bash 4.4 or later, git, Python 3.10 or later, uv, and bubblewrap. The test suite needs no Codex install; it uses a stand-in.

git clone https://github.com/darblinko/agent-controls
cd agent-controls
uvx pytest -q

mkdir -p ~/.config/agent-controls
cp examples/sandbox.conf ~/.config/agent-controls/sandbox.conf   # edit roots and tool paths
cd $HOME/project                                                 # a configured root
CODEX_SANDBOX_DRY_RUN=1 /path/to/agent-controls/bin/codex-sandbox exec "list the files"

The dry run, like a real run, needs a Codex executable: the next codex on PATH or CODEX_BIN, inside a tool path from the config. The README installs the wrapper as a codex link placed before the real Codex on PATH. The repository's landing page is at darblinko.github.io/agent-controls, and the source, threat model and tests are in darblinko/agent-controls.