agent-approvals-security.md Codex Docs, 2026-04-18 18:18 UTC → 2026-04-22 18:29 UTC

73- `<writable_root>/.codex` is protected as read-only when it exists as a directory.73- `<writable_root>/.codex` is protected as read-only when it exists as a directory.

74- Protection is recursive, so everything under those paths is read-only.74- Protection is recursive, so everything under those paths is read-only.

75 75 

76### Deny reads with filesystem profiles

77 

78Named permission profiles can also deny reads for exact paths or glob patterns.

79This is useful when a workspace should stay writable but specific sensitive

80files, such as local environment files, must stay unreadable:

81 

82```toml

83default_permissions = "workspace"

84 

85[permissions.workspace.filesystem]

86":project_roots" = { "." = "write", "**/*.env" = "none" }

87glob_scan_max_depth = 3

88```

89 

90Use `"none"` for paths or globs that Codex shouldn't read. The sandbox policy

91evaluates globs for local macOS and Linux command execution. On platforms that

92pre-expand glob matches before the sandbox starts, set `glob_scan_max_depth` for

93unbounded `**` patterns, or list explicit depths such as `*.env`, `*/*.env`, and

94`*/*/*.env`.

95 

76### Run without approval prompts96### Run without approval prompts

77 97 

78You can disable approval prompts with `--ask-for-approval never` or `-a never` (shorthand).98You can disable approval prompts with `--ask-for-approval never` or `-a never` (shorthand).

153Codex enforces the sandbox differently depending on your OS:173Codex enforces the sandbox differently depending on your OS:

154 174 

155- **macOS** uses Seatbelt policies and runs commands using `sandbox-exec` with a profile (`-p`) that corresponds to the `--sandbox` mode you selected. When restricted read access enables platform defaults, Codex appends a curated macOS platform policy (instead of broadly allowing `/System`) to preserve common tool compatibility.175- **macOS** uses Seatbelt policies and runs commands using `sandbox-exec` with a profile (`-p`) that corresponds to the `--sandbox` mode you selected. When restricted read access enables platform defaults, Codex appends a curated macOS platform policy (instead of broadly allowing `/System`) to preserve common tool compatibility.

156- **Linux** uses the `bwrap` pipeline plus `seccomp` by default. `use_legacy_landlock` is available when you need the older path. In managed proxy mode, the default `bwrap` pipeline routes egress through a proxy-only bridge and fails closed if it can’t build valid local proxy routes.176- **Linux** uses `bwrap` plus `seccomp` by default.

157- **Windows** uses the Linux sandbox implementation when running in [Windows Subsystem for Linux 2 (WSL2)](https://developers.openai.com/codex/windows#windows-subsystem-for-linux). WSL1 was supported through Codex `0.114`; starting in `0.115`, the Linux sandbox moved to `bwrap`, so WSL1 is no longer supported. When running natively on Windows, Codex uses a [Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox) implementation.177- **Windows** uses the Linux sandbox implementation when running in [Windows Subsystem for Linux 2 (WSL2)](https://developers.openai.com/codex/windows#windows-subsystem-for-linux). WSL1 was supported through Codex `0.114`; starting in `0.115`, the Linux sandbox moved to `bwrap`, so WSL1 is no longer supported. When running natively on Windows, Codex uses a [Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox) implementation.

158 178 

159If you use the Codex IDE extension on Windows, it supports WSL2 directly. Set the following in your VS Code settings to keep the agent inside WSL2 whenever it's available:179If you use the Codex IDE extension on Windows, it supports WSL2 directly. Set the following in your VS Code settings to keep the agent inside WSL2 whenever it's available:

176 196 

177See the [Windows setup guide](https://developers.openai.com/codex/windows#windows-sandbox) for details.197See the [Windows setup guide](https://developers.openai.com/codex/windows#windows-sandbox) for details.

178 198 

179When you run Linux in a containerized environment such as Docker, the sandbox may not work if the host or container configuration doesn’t support the required `Landlock` and `seccomp` features.199When you run Linux in a containerized environment such as Docker, the sandbox may not work if the host or container configuration blocks the namespace, setuid `bwrap`, or `seccomp` operations that Codex needs.

180 200 

181In that case, configure your Docker container to provide the isolation you need, then run `codex` with `--sandbox danger-full-access` (or the `--dangerously-bypass-approvals-and-sandbox` flag) inside the container.201In that case, configure your Docker container to provide the isolation you need, then run `codex` with `--sandbox danger-full-access` (or the `--dangerously-bypass-approvals-and-sandbox` flag) inside the container.

182 202 

203### Run Codex in Dev Containers

204 

205If your host cannot run the Linux sandbox directly, or if your organization already standardizes on containerized development, run Codex with Dev Containers and let Docker provide the outer isolation boundary. This works with Visual Studio Code Dev Containers and compatible tools.

206 

207Use the [Codex secure devcontainer example](https://github.com/openai/codex/tree/main/.devcontainer) as a reference implementation. The example installs Codex, common development tools, `bubblewrap`, and firewall-based outbound controls.

208 

209Devcontainers provide substantial protection, but they do not prevent every

210 attack. If you run Codex with `--sandbox danger-full-access` or

211 `--dangerously-bypass-approvals-and-sandbox` inside the container, a malicious

212 project can exfiltrate anything available inside the devcontainer, including

213 Codex credentials. Use this pattern only with trusted repositories, and

214 monitor Codex activity as you would in any other elevated environment.

215 

216The reference implementation includes:

217 

218- an Ubuntu 24.04 base image with Codex and common development tools installed;

219- an allowlist-driven firewall profile for outbound access;

220- VS Code settings and extension recommendations for reopening the workspace in a container;

221- persistent mounts for command history and Codex configuration;

222- `bubblewrap`, so Codex can still use its Linux sandbox when the container grants the needed capabilities.

223 

224To try it:

225 

2261. Install Visual Studio Code and the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).

2272. Copy the Codex example `.devcontainer` setup into your repository, or start from the Codex repository directly.

2283. In VS Code, run **Dev Containers: Open Folder in Container…** and select `.devcontainer/devcontainer.secure.json`.

2294. After the container starts, open a terminal and run `codex`.

230 

231You can also start the container from the CLI:

232 

233```bash

234devcontainer up --workspace-folder . --config .devcontainer/devcontainer.secure.json

235```

236 

237The example has three main pieces:

238 

239- `.devcontainer/devcontainer.secure.json` controls container settings, capabilities, mounts, environment variables, and VS Code extensions.

240- `.devcontainer/Dockerfile.secure` defines the Ubuntu-based image and installed tools.

241- `.devcontainer/init-firewall.sh` applies the outbound network policy.

242 

243The reference firewall is intentionally a starting point. If you depend on domain allowlisting for isolation, implement DNS rebinding and DNS refresh protections that fit your environment, such as TTL-aware refreshes or a DNS-aware firewall.

244 

245Inside the container, choose one of these modes:

246 

247- Keep Codex's Linux sandbox enabled if the Dev Container profile grants the capabilities needed for `bwrap` to create the inner sandbox.

248- If the container is your intended security boundary, run Codex with `--sandbox danger-full-access` inside the container so Codex does not try to create a second sandbox layer.

249 

183## Version control250## Version control

184 251 

185Codex works best with a version control workflow:252Codex works best with a version control workflow: