agent-approvals-security.md Codex Docs, 2026-04-20 06:53 UTC → 2026-04-25 06:37 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).

83 103 

84For a middle ground, `approval_policy = { granular = { ... } }` lets you keep specific approval prompt categories interactive while automatically rejecting others. The granular policy covers sandbox approvals, execpolicy-rule prompts, MCP prompts, `request_permissions` prompts, and skill-script approvals.104For a middle ground, `approval_policy = { granular = { ... } }` lets you keep specific approval prompt categories interactive while automatically rejecting others. The granular policy covers sandbox approvals, execpolicy-rule prompts, MCP prompts, `request_permissions` prompts, and skill-script approvals.

85 105 

86Set `approvals_reviewer = "guardian_subagent"` to route eligible approval reviews through the Guardian reviewer subagent instead of prompting the user directly. Admin requirements can constrain this with `allowed_approvals_reviewers`.106### Automatic approval reviews

107 

108By default, approval requests route to you:

109 

110```toml

111approvals_reviewer = "user"

112```

113 

114Automatic approval reviews apply when approvals are interactive, such as

115`approval_policy = "on-request"` or a granular approval policy. Set

116`approvals_reviewer = "auto_review"` to route eligible approval requests

117through a reviewer agent before Codex runs the request:

118 

119```toml

120approval_policy = "on-request"

121approvals_reviewer = "auto_review"

122```

123 

124The reviewer evaluates only actions that already need approval, such as sandbox

125escalations, network requests, `request_permissions` prompts, or side-effecting

126app and MCP tool calls. Actions that stay inside the sandbox continue without an

127extra review step.

128 

129The reviewer policy checks for data exfiltration, credential probing, persistent

130security weakening, and destructive actions. Low-risk and medium-risk actions

131can proceed when policy allows them. The policy denies critical-risk actions.

132High-risk actions require enough user authorization and no matching deny rule.

133Timeouts, parse failures, and review errors fail closed.

134 

135The [default reviewer policy](https://github.com/openai/codex/blob/main/codex-rs/core/src/guardian/policy.md)

136is in the open-source Codex repository. Enterprises can replace its

137tenant-specific section with `guardian_policy_config` in managed requirements.

138Local `[auto_review].policy` text is also supported, but managed requirements

139take precedence. For setup details, see

140[Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration#configure-automatic-review-policy).

141 

142In the Codex app, these reviews appear as automatic review items with a status such

143as Reviewing, Approved, Denied, Stopped, or Timed out. They can also include a

144risk level for the reviewed request.

145 

146Automatic review uses extra model calls, so it can add to Codex usage. Admins

147can constrain it with `allowed_approvals_reviewers`.

87 148 

88### Common sandbox and approval combinations149### Common sandbox and approval combinations

89 150 

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

154 215 

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.216- **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.217- **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.218- **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 219 

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:220If 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 237 

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

178 239 

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.240When 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 241 

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.242In 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 243 

244### Run Codex in Dev Containers

245 

246If 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.

247 

248Use 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.

249 

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

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

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

253 project can exfiltrate anything available inside the devcontainer, including

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

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

256 

257The reference implementation includes:

258 

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

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

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

262- persistent mounts for command history and Codex configuration;

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

264 

265To try it:

266 

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

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

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

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

271 

272You can also start the container from the CLI:

273 

274```bash

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

276```

277 

278The example has three main pieces:

279 

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

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

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

283 

284The 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.

285 

286Inside the container, choose one of these modes:

287 

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

289- 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.

290 

183## Version control291## Version control

184 292 

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