agent-approvals-security.md +125 −13
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
1212extension, and CLI, see [Sandboxing](https://developers.openai.com/codex/concepts/sandboxing).extension, 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
2727In the `Auto` preset (for example, `--full-auto`), Codex can read files, make edits, and run commands in the working directory automatically.In 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
3333## Network access [Elevated Risk](https://help.openai.com/articles/20001061)## 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
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).
81 101
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.102If 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 103
84104For 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.For 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.
105
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`.
85 148
86### Common sandbox and approval combinations149### Common sandbox and approval combinations
87 150
88| Intent | Flags | Effect |151| Intent | Flags | Effect |
89| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |152| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
90153| 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. || 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. |154| 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. |
92| Read-only non-interactive (CI) | `--sandbox read-only --ask-for-approval never` | Codex can only read files; never asks for approval. |155| Read-only non-interactive (CI) | `--sandbox read-only --ask-for-approval never` | Codex can only read files; never asks for approval. |
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. |156| 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. |
94157| Dangerous full access | `--dangerously-bypass-approvals-and-sandbox` (alias: `--yolo`) | [Elevated Risk](https://help.openai.com/articles/20001061) No sandbox; no approvals *(not recommended)* || Dangerous full access | `--dangerously-bypass-approvals-and-sandbox` (alias: `--yolo`) | <ElevatedRiskBadge /> No sandbox; no approvals _(not recommended)_ |
95 158
96159`--full-auto` is a convenience alias for `--sandbox workspace-write --ask-for-approval on-request`.For 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 160
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.161With `--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 162
139 202
140```bash203```bash
141# macOS204# macOS
142205codex sandbox macos [--full-auto] [--log-denials] [COMMAND]...codex sandbox macos [--permissions-profile <name>] [--log-denials] [COMMAND]...
143# Linux206# Linux
144207codex sandbox linux [--full-auto] [COMMAND]...codex sandbox linux [--permissions-profile <name>] [COMMAND]...
208# Windows
209codex sandbox windows [--permissions-profile <name>] [COMMAND]...
145```210```
146 211
147The `sandbox` command is also available as `codex debug`, and the platform helpers have aliases (for example `codex sandbox seatbelt` and `codex sandbox landlock`).212The `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:216Codex enforces the sandbox differently depending on your OS:
152 217
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.218- **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.
154219- **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.- **Linux** uses `bwrap` plus `seccomp` by default.
155220- **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.- **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 221
157222If 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:If 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 223
159```json224```json
160{225{
174 239
175See the [Windows setup guide](https://developers.openai.com/codex/windows#windows-sandbox) for details.240See the [Windows setup guide](https://developers.openai.com/codex/windows#windows-sandbox) for details.
176 241
177242When 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.When 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 243
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.244In 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 245
246### Run Codex in Dev Containers
247
248If 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.
249
250Use 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.
251
252Devcontainers provide substantial protection, but they do not prevent every
253 attack. If you run Codex with `--sandbox danger-full-access` or
254 `--dangerously-bypass-approvals-and-sandbox` inside the container, a malicious
255 project can exfiltrate anything available inside the devcontainer, including
256 Codex credentials. Use this pattern only with trusted repositories, and
257 monitor Codex activity as you would in any other elevated environment.
258
259The reference implementation includes:
260
261- an Ubuntu 24.04 base image with Codex and common development tools installed;
262- an allowlist-driven firewall profile for outbound access;
263- VS Code settings and extension recommendations for reopening the workspace in a container;
264- persistent mounts for command history and Codex configuration;
265- `bubblewrap`, so Codex can still use its Linux sandbox when the container grants the needed capabilities.
266
267To try it:
268
2691. Install Visual Studio Code and the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
2702. Copy the Codex example `.devcontainer` setup into your repository, or start from the Codex repository directly.
2713. In VS Code, run **Dev Containers: Open Folder in Container...** and select `.devcontainer/devcontainer.secure.json`.
2724. After the container starts, open a terminal and run `codex`.
273
274You can also start the container from the CLI:
275
276```bash
277devcontainer up --workspace-folder . --config .devcontainer/devcontainer.secure.json
278```
279
280The example has three main pieces:
281
282- `.devcontainer/devcontainer.secure.json` controls container settings, capabilities, mounts, environment variables, and VS Code extensions.
283- `.devcontainer/Dockerfile.secure` defines the Ubuntu-based image and installed tools.
284- `.devcontainer/init-firewall.sh` applies the outbound network policy.
285
286The 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.
287
288Inside the container, choose one of these modes:
289
290- Keep Codex's Linux sandbox enabled if the Dev Container profile grants the capabilities needed for `bwrap` to create the inner sandbox.
291- 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.
292
181## Version control293## Version control
182 294
183Codex works best with a version control workflow:295Codex works best with a version control workflow: