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.
flowchart TB
shell["codex ... in a configured root"] --> wrapper["codex-sandbox"]
conf[("sandbox.conf")] --> wrapper
wrapper -->|"cwd outside every root"| refuse["exit 1, no namespace"]
wrapper -->|"cwd inside a root"| ns
subgraph ns["bubblewrap namespace, host network shared"]
direction TB
rw["read-write: the matched rw root, state paths"]
ro["read-only: /usr /bin /sbin /lib /lib64 /etc, tool paths, the matched ro root or its listed subtrees"]
fresh["new mounts: /proc, /dev; empty tmpfs on /tmp, /home, $HOME, /mnt"]
masked["over /dev/null: .env* and mask matches in the root, pruned dirs excepted"]
rw ~~~ ro ~~~ fresh ~~~ masked
end
subgraph gone["absent from the namespace"]
direction TB
other["other roots and repositories"]
sub["unlisted subtrees and .git of a subtree root"]
dot["dotfiles in $HOME"]
wsl["/init, Windows drives under /mnt, /run except a resolv.conf target"]
other ~~~ sub ~~~ dot ~~~ wsl
end
ns ~~~ gone
| Path inside the namespace | State | Line |
|---|---|---|
/usr, /etc | Read-only bind | 218, 222 |
/bin, /sbin, /lib, /lib64 | Read-only bind when the host has the path (--ro-bind-try) | 219 to 221 |
Target of /etc/resolv.conf when it lies outside /etc | Read-only bind of that one file, for DNS | 223 to 228 |
/proc, /dev | New procfs and new /dev | 229 |
/tmp, /home, $HOME, /mnt | Empty tmpfs | 222, 229 |
tool paths | Read-only bind | 275 |
state paths, for example $HOME/.codex | Read-write bind, created when missing | 109 to 111, 276 |
The matched rw root | Read-write bind | 241 to 242 |
The matched ro root | Read-only bind | 243 to 244 |
An ro root with a subtree list | Read-only binds of the listed subtrees that exist; the rest of the root, .git included, is absent | 248 to 254 |
.env* and mask matches in the bound root | /dev/null bound read-only over each file | 198 to 214, 278 to 280 |
| Network | Host network namespace kept (--share-net) | 289 |
| Other namespaces | New (--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" "$@")
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:
- 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. - The Codex executable, or the target of its symbolic link, is outside every bound path. A
toolline for its install directory fixes this. - The config names
/as a root, gives subtrees to anrwroot, or gives a subtree that is absolute or contains... - 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:
catof a file outside the root:No such file or directory, exit 1.cat .envin the root:Permission denied, exit 1.ls -l .envlists the name as a character device. The file's name stays visible; its content does not.ls -A /: 11 entries:bin dev etc home lib lib64 mnt proc sbin tmp usr./runand/initare absent.ls -A $HOME:.codex,srcandtools, the boundstatepath and the parents of the bound root andtoolpath. A planted$HOME/.ssh/id_testdid not exist.ls -A /mnt:wslonly, the parent of the bound resolv.conf target.- With
WSL_INTEROP,WSLENVandGH_TOKENset in the calling environment, all three were unset inside. A fourth variable, with nounsetenvline, passed through. - In a subtree root,
ls -Alisteddocs src tools, andtouch docs/xfailed withRead-only file system. /proclisted 4 process IDs inside the namespace and 196 on the host in the same run. The process kept the caller's user ID.
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.
| Area | What the cases check |
|---|---|
| Root selection and binding | An 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 errors | Unknown keyword, relative path, setenv with one argument, / as a root, missing config file. |
| Subtree roots | Only 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 routes | tmpfs 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 refusals | Refusal outside every root. Refusal when the Codex executable is outside every bound path. |
| Codex binary lookup and bypass | CODEX_UNCONFINED=1 runs the binary directly. The PATH lookup skips the wrapper itself. |
| State, tool and environment lines | A 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.
| Threat | Addressed | Mechanism or reason |
|---|---|---|
| T1: reads outside the working root | Yes | Only the configured root containing the current directory is bound. The wrapper refuses to start outside every root. |
T1: reads of dotfiles in $HOME | Yes | /tmp, /home and $HOME are empty tmpfs mounts. Only tool and state paths are bound back. |
| T1: partial access to a governed repository | Yes | ro <root> <subtree>... binds the listed subtrees only. .git is absent, so history of unlisted directories is unreachable. |
T2: .env files inside the root | Yes | Regular 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 variables | Named ones | unsetenv lines remove the variables they name. |
| Writes to a reference repository | Yes | ro roots are read-only binds. |
| WSL: Windows drives, the interop socket | Yes | /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_misc | Untested | /init is absent. The effect depends on the interop handler's registration flags, which were not checked. |
| Network egress | No | The 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 general | No | The calling shell's environment passes through, except WSL_INTEROP, WSLENV and unsetenv entries. |
| Secrets under other names | No | Masking 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 bound | No | The 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. |
| Bypass | No | CODEX_UNCONFINED=1, or the real Codex binary run by its absolute path, skips the namespace. |
| Other agents | No | Claude Code is not confined by this wrapper. It has its own permission system. |
| Malicious local user, kernel or bubblewrap exploits, compromised Codex binary | Out of scope | Listed as out of scope for the repository as a whole. |
Limits
WSL
- The Windows drives are hidden by the tmpfs on
/mnt. The resolv.conf target is bound back as one read-only file so that DNS resolves. If that target lies under/runon another setup, that one path under/runexists in the namespace. - The test for WSL entry points checks that
/initis absent and that/mntholds nothing besideswsl. No test runs a Windows executable from inside the namespace. - Inference (untested): if the WSL interop handler is registered with the binfmt_misc
Fflag, the kernel keeps the interpreter open from registration, and an absent/initwould not by itself stop a Windows executable placed in the bound root from reaching it. The unsetWSL_INTEROPand the absent/runwould then be the remaining barriers. The registration flags were not checked for this article. The threat model lists the same question as untested.
Codex's own sandbox modes
- The probe covered
--sandbox read-only. The repository records nothing about the other Codex sandbox modes. - The wrapper passes Codex's arguments through unchanged, except that it adds
--skip-git-repo-checktoexecin a subtree root. A--sandboxflag therefore still applies, inside the namespace. The repository has no test of Codex's own sandbox running inside bubblewrap. - The Codex CLI version in the probe is unknown, so the probe does not show whether current versions still read outside the working directory in read-only mode.
What bubblewrap does not isolate in this configuration
- The network:
--share-netkeeps the host network namespace. - The user: the process runs with the caller's user ID, and writes in an
rwroot or astatepath land on the host. - System calls and resources: the argument list has no
--seccompfilter and sets no CPU or memory limit. - The terminal: the argument list has no
--new-session, whichbwrap --helpdescribes as "Create a new terminal session", so Codex keeps the caller's controlling terminal. Whether the running kernel permits terminal input injection was not checked. - The kernel and bubblewrap themselves, which the threat model places out of scope.
Masking
- Masks are computed once, at start, from file names. A secret in a differently named file, a file created later, or a symbolic link stays readable.
- The search for masked files prunes
node_modules,.git,.venv,venvand__pycache__. A.envfile inside one of them is not masked. In the 2026-10-28 run,node_modules/pkg/.envwas readable inside the namespace. The script header, the threat model and the README list the pruned directories. - Masks apply to the bound root only.
toolandstatepaths are not searched.
Bypass and setup
CODEX_UNCONFINED=1is checked before the config is read, so it works from any directory. Run from outside every root with it set, the stand-in Codex could see/init.- The wrapper confines Codex only when it is the
codexfound first onPATH. The real binary run by its absolute path is not confined. - The namespace needs unprivileged user namespaces. Ubuntu 24.04 restricts them through AppArmor by default.
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.