agent-approvals-security diff

agent-approvals-security.md +241 −15

Details

9By default, the agent runs with network access turned off. Locally, Codex uses an OS-enforced sandbox that limits what it can touch (typically to the current workspace), plus an approval policy that controls when it must stop and ask you before acting.9By default, the agent runs with network access turned off. Locally, Codex uses an OS-enforced sandbox that limits what it can touch (typically to the current workspace), plus an approval policy that controls when it must stop and ask you before acting.

10 10

11For a high-level explanation of how sandboxing works across the Codex app, IDE11For a high-level explanation of how sandboxing works across the Codex app, IDE

~~12extension, and CLI, see [Sandboxing](https://developers.openai.com/codex/concepts/sandboxing).~~12extension, and CLI, see [sandboxing](https://developers.openai.com/codex/concepts/sandboxing).

13For a broader enterprise security overview, see the [Codex security white paper](https://trust.openai.com/?itemUid=382f924d-54f3-43a8-a9df-c39e6c959958&source=click).13For a broader enterprise security overview, see the [Codex security white paper](https://trust.openai.com/?itemUid=382f924d-54f3-43a8-a9df-c39e6c959958&source=click).

14 14

15## Sandbox and approvals15## Sandbox and approvals

24- **Codex cloud**: Runs in isolated OpenAI-managed containers, preventing access to your host system or unrelated data. Uses a two-phase runtime model: setup runs before the agent phase and can access the network to install specified dependencies, then the agent phase runs offline by default unless you enable internet access for that environment. Secrets configured for cloud environments are available only during setup and are removed before the agent phase starts.24- **Codex cloud**: Runs in isolated OpenAI-managed containers, preventing access to your host system or unrelated data. Uses a two-phase runtime model: setup runs before the agent phase and can access the network to install specified dependencies, then the agent phase runs offline by default unless you enable internet access for that environment. Secrets configured for cloud environments are available only during setup and are removed before the agent phase starts.

25- **Codex CLI / IDE extension**: OS-level mechanisms enforce sandbox policies. Defaults include no network access and write permissions limited to the active workspace. You can configure the sandbox, approval policy, and network settings based on your risk tolerance.25- **Codex CLI / IDE extension**: OS-level mechanisms enforce sandbox policies. Defaults include no network access and write permissions limited to the active workspace. You can configure the sandbox, approval policy, and network settings based on your risk tolerance.

26 26

~~27In the `Auto` preset (for example, `--full-auto`), Codex can read files, make edits, and run commands in the working directory automatically.~~27In the `Auto` preset (for example, `--sandbox workspace-write --ask-for-approval on-request`), Codex can read files, make edits, and run commands in the working directory automatically.

28 28

29Codex asks for approval to edit files outside the workspace or to run commands that require network access. If you want to chat or plan without making changes, switch to `read-only` mode with the `/permissions` command.29Codex asks for approval to edit files outside the workspace or to run commands that require network access. If you want to chat or plan without making changes, switch to `read-only` mode with the `/permissions` command.

30 30

31Codex can also elicit approval for app (connector) tool calls that advertise side effects, even when the action isn't a shell command or file change. Destructive app/MCP tool calls always require approval when the tool advertises a destructive annotation, even if it also advertises other hints (for example, read-only hints).31Codex can also elicit approval for app (connector) tool calls that advertise side effects, even when the action isn't a shell command or file change. Destructive app/MCP tool calls always require approval when the tool advertises a destructive annotation, even if it also advertises other hints (for example, read-only hints).

32 32

~~33## Network access [Elevated Risk](https://help.openai.com/articles/20001061)~~33## Network access <ElevatedRiskBadge class="ml-2" />

34 34

35For Codex cloud, see [agent internet access](https://developers.openai.com/codex/cloud/internet-access) to enable full internet access or a domain allow list.35For Codex cloud, see [agent internet access](https://developers.openai.com/codex/cloud/internet-access) to enable full internet access or a domain allow list.

36 36

41network_access = true41network_access = true

42```42```

43 43

44### Network isolation

46Network access is controlled through destination rules that apply to scripts,

47programs, and subprocesses spawned by commands. When command network access is

48already enabled, turn on the `network_proxy` feature to constrain that traffic

49to the network policy you configure.

51```toml

52[features.network_proxy]

53enabled = true

54domains = { "api.openai.com" = "allow", "example.com" = "deny" }

55```

57For a one-off CLI session, use the boolean shorthand when you only need the

58toggle, and the table form when you also set policy options:

60```bash

61codex \

62 -c 'features.network_proxy=true' \

63 -c 'sandbox_workspace_write.network_access=true'

65codex \

66 -c 'features.network_proxy.enabled=true' \

67 -c 'features.network_proxy.domains={ "api.openai.com" = "allow", "example.com" = "deny" }' \

68 -c 'sandbox_workspace_write.network_access=true'

69```

71The feature changes how enabled network access is enforced; it does not grant

72network access by itself. Use `sandbox_workspace_write.network_access` with

73`workspace-write` config to decide whether commands have network access at all:

75- Network off + `network_proxy` on: network stays off, and the feature does nothing.

76- Network on + `network_proxy` off: network stays on with unrestricted direct

77 outbound access.

78- Network on + `network_proxy` on: network stays on, and outbound traffic is

79 constrained by the configured network policy.

81Admin-managed `experimental_network` requirements are separate from the user

82feature toggle. They can configure and start sandboxed networking without

83`features.network_proxy`, but they do not turn on network access when the active

84sandbox keeps it off. See [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration#configure-network-access-requirements)

85for the administrator-side `requirements.toml` shape.

87#### Network policy

89Domain rules are allowlist-first:

91- Exact hosts match only themselves.

92- `*.example.com` matches subdomains such as `api.example.com`, but not

93 `example.com`.

94- `**.example.com` matches both the apex and subdomains.

95- A global `*` allow rule matches any public host that is not denied. Treat `*`

96 as broad network access and prefer scoped rules when you can.

97- `deny` always wins over `allow`, and global `*` is only valid for allow rules.

99#### Local and private destinations

100

101By default, `allow_local_binding = false` blocks loopback, link-local, and

102private destinations:

103

104- Specific exceptions: add an exact local IP literal or `localhost` allow rule

105 when a command needs one local target.

106- Broader access: set `allow_local_binding = true` only when you intentionally

107 want wider local/private reach.

108- Wildcards: wildcard rules do not count as explicit local exceptions.

109- Resolved addresses: hostnames that resolve to local/private IPs stay blocked

110 even if they match the allowlist.

111

112#### DNS rebinding protections

113

114Before allowing a hostname, Codex performs a best-effort DNS and IP

115classification check:

116

117- Lookups that fail or time out are blocked.

118- Hostnames that resolve to non-public addresses are blocked.

119- The check reduces DNS rebinding risk, but it does not eliminate it. Preventing

120 rebinding completely would require pinning resolved IPs through the transport

121 layer.

122

123If hostile DNS is in scope, enforce egress controls at a lower layer too.

124

125#### Dangerous settings

126

127Two settings deliberately widen the trust boundary:

128

129- `dangerously_allow_non_loopback_proxy = true` can expose proxy listeners beyond

130 loopback.

131- `dangerously_allow_all_unix_sockets = true` bypasses the Unix socket allowlist.

132

133Use them only in tightly controlled environments. When Unix socket proxying is

134enabled, listeners stay loopback-only even if non-loopback binding was requested,

135so sandboxed networking does not become a remote bridge into local daemons.

136

137`network_proxy` is off by default. When you enable it:

138

139| Setting | Default | Behavior |

140| -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

141| `enabled` | `false` | Starts sandboxed networking only when command network access is already on. |

142| `domains` | unset | Uses allowlist behavior, so no external destinations are allowed until you add `allow` rules. Supports exact hosts, scoped wildcards, and global `*` allow rules; `deny` always wins. |

143| `unix_sockets` | unset | No Unix socket destinations are allowed until you add explicit `allow` rules. |

144| `allow_local_binding` | `false` | Blocks local and private-network destinations unless you add an exact local IP literal or `localhost` allow rule, or explicitly opt into broader local/private access. |

145| `enable_socks5` | `true` | Exposes SOCKS5 support when policy allows it. |

146| `enable_socks5_udp` | `true` | Allows UDP over SOCKS5 when SOCKS5 is available. |

147| `allow_upstream_proxy` | `true` | Lets sandboxed networking honor an upstream proxy from the environment. |

148| `dangerously_allow_non_loopback_proxy` | `false` | Keeps listener endpoints on loopback unless you deliberately expose them beyond localhost. |

149| `dangerously_allow_all_unix_sockets` | `false` | Keeps Unix socket access allowlist-based unless you deliberately bypass that protection. |

150

44You can also control the [web search tool](https://platform.openai.com/docs/guides/tools-web-search) without granting full network access to spawned commands. Codex defaults to using a web search cache to access results. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](#common-sandbox-and-approval-combinations), web search defaults to live results. Use `--search` or set `web_search = "live"` to allow live browsing, or set it to `"disabled"` to turn the tool off:151You can also control the [web search tool](https://platform.openai.com/docs/guides/tools-web-search) without granting full network access to spawned commands. Codex defaults to using a web search cache to access results. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](#common-sandbox-and-approval-combinations), web search defaults to live results. Use `--search` or set `web_search = "live"` to allow live browsing, or set it to `"disabled"` to turn the tool off:

45 152

46```toml153```toml

73- `<writable_root>/.codex` is protected as read-only when it exists as a directory.180- `<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.181- Protection is recursive, so everything under those paths is read-only.

75 182

183### Deny reads with filesystem profiles

184

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

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

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

188

189```toml

190default_permissions = "workspace"

191

192[permissions.workspace.filesystem]

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

194glob_scan_max_depth = 3

195```

196

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

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

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

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

201`*/*/*.env`.

202

76### Run without approval prompts203### Run without approval prompts

77 204

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

81 208

82If you need Codex to read files, make edits, and run commands with network access without approval prompts, use `--sandbox danger-full-access` (or the `--dangerously-bypass-approvals-and-sandbox` flag). Use caution before doing so.209If you need Codex to read files, make edits, and run commands with network access without approval prompts, use `--sandbox danger-full-access` (or the `--dangerously-bypass-approvals-and-sandbox` flag). Use caution before doing so.

83 210

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 elicitations, `request_permissions` prompts, and skill-script approvals.211For 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.

212

213### Automatic approval reviews

214

215By default, approval requests route to you:

216

217```toml

218approvals_reviewer = "user"

219```

220

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

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

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

224through a reviewer agent before Codex runs the request:

225

226```toml

227approval_policy = "on-request"

228approvals_reviewer = "auto_review"

229```

230

231For the full reviewer lifecycle, trigger conditions, configuration precedence,

232and failure behavior, see

233[Auto-review](https://developers.openai.com/codex/concepts/sandboxing/auto-review).

234

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

236escalations, blocked network requests, `request_permissions` prompts, or

237side-effecting app and MCP tool calls. Actions that stay inside the sandbox

238continue without an extra review step.

239

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

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

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

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

244Prompt-build, review-session, and parse failures fail closed. Timeouts are

245surfaced separately, but the action still does not run.

246

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

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

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

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

251take precedence. For setup details, see

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

253

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

255such as Reviewing, Approved, Denied, Aborted, or Timed out. They can also

256include a risk level and user-authorization assessment for the reviewed

257request.

258

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

260can constrain it with `allowed_approvals_reviewers`.

85 261

86### Common sandbox and approval combinations262### Common sandbox and approval combinations

87 263

89| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |265| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |

90| Auto (preset) | *no flags needed* or `--full-auto` | Codex can read files, make edits, and run commands in the workspace. Codex requires approval to edit outside the workspace or to access network. |266| Auto (preset) | _no flags needed_ or `--sandbox workspace-write --ask-for-approval on-request` | Codex can read files, make edits, and run commands in the workspace. Codex requires approval to edit outside the workspace or to access network. |

91| Safe read-only browsing | `--sandbox read-only --ask-for-approval on-request` | Codex can read files and answer questions. Codex requires approval to make edits, run commands, or access network. |267| Safe read-only browsing | `--sandbox read-only --ask-for-approval on-request` | Codex can read files and answer questions. Codex requires approval to make edits, run commands, or access network. |

93| Automatically edit but ask for approval to run untrusted commands | `--sandbox workspace-write --ask-for-approval untrusted` | Codex can read and edit files but asks for approval before running untrusted commands. |269| Automatically edit but ask for approval to run untrusted commands | `--sandbox workspace-write --ask-for-approval untrusted` | Codex can read and edit files but asks for approval before running untrusted commands. |

~~94| Dangerous full access | `--dangerously-bypass-approvals-and-sandbox` (alias: `--yolo`) | [Elevated Risk](https://help.openai.com/articles/20001061) No sandbox; no approvals *(not recommended)* |~~270| Auto-review mode | `--sandbox workspace-write --ask-for-approval on-request -c approvals_reviewer=auto_review` or `approvals_reviewer = "auto_review"` | Same sandbox boundary as standard on-request mode, but eligible approval requests are reviewed by Auto-review instead of surfacing to the user. |

271| Dangerous full access | `--dangerously-bypass-approvals-and-sandbox` (alias: `--yolo`) | <ElevatedRiskBadge /> No sandbox; no approvals _(not recommended)_ |

95 272

~~96`--full-auto` is a convenience alias for `--sandbox workspace-write --ask-for-approval on-request`.~~273For non-interactive runs, use `codex exec --sandbox workspace-write`; Codex keeps older `codex exec --full-auto` invocations as a deprecated compatibility path and prints a warning.

97 274

98With `--ask-for-approval untrusted`, Codex runs only known-safe read operations automatically. Commands that can mutate state or trigger external execution paths (for example, destructive Git operations or Git output/config-override flags) require approval.275With `--ask-for-approval untrusted`, Codex runs only known-safe read operations automatically. Commands that can mutate state or trigger external execution paths (for example, destructive Git operations or Git output/config-override flags) require approval.

99 276

139 316

140```bash317```bash

141# macOS318# macOS

142codex sandbox macos [--full-auto] [--log-denials] [COMMAND]...319codex sandbox macos [--permissions-profile <name>] [--log-denials] [COMMAND]...

143# Linux320# Linux

144codex sandbox linux [--full-auto] [COMMAND]...321codex sandbox linux [--permissions-profile <name>] [COMMAND]...

322# Windows

323codex sandbox windows [--permissions-profile <name>] [COMMAND]...

145```324```

146 325

147The `sandbox` command is also available as `codex debug`, and the platform helpers have aliases (for example `codex sandbox seatbelt` and `codex sandbox landlock`).326The `sandbox` command is also available as `codex debug`, and the platform helpers have aliases (for example `codex sandbox seatbelt` and `codex sandbox landlock`).

151Codex enforces the sandbox differently depending on your OS:330Codex enforces the sandbox differently depending on your OS:

152 331

153- **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.332- **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.

154- **Linux** uses the bubblewrap pipeline plus `seccomp` by default. `use_legacy_landlock` is available when you need the older path. In managed proxy mode, the default bubblewrap pipeline routes egress through a proxy-only bridge and fails closed if it cannot build valid loopback proxy routes.333- **Linux** uses `bwrap` plus `seccomp` by default.

155- **Windows** uses the Linux sandbox implementation when running in [Windows Subsystem for Linux (WSL)](https://developers.openai.com/codex/windows#windows-subsystem-for-linux). When running natively on Windows, Codex uses a [Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox) implementation.334- **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.

156 335

157If you use the Codex IDE extension on Windows, it supports WSL directly. Set the following in your VS Code settings to keep the agent inside WSL whenever it’s available:336If 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:

158 337

159```json338```json

160{339{

174 353

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

176 355

177When 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.356When 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.

178 357

179In 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.358In 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.

180 359

360### Run Codex in Dev Containers

361

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

363

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

365

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

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

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

369 project can exfiltrate anything available inside the devcontainer, including

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

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

372

373The reference implementation includes:

374

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

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

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

378- persistent mounts for command history and Codex configuration;

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

380

381To try it:

382

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

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

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

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

387

388You can also start the container from the CLI:

389

390```bash

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

392```

393

394The example has three main pieces:

395

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

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

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

399

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

401

402Inside the container, choose one of these modes:

403

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

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

406

181## Version control407## Version control

182 408

183Codex works best with a version control workflow:409Codex works best with a version control workflow:

agent-approvals-security.md Codex Docs, 2026-04-10 18:23 UTC → 2026-05-18 22:01 UTC