security.md +22 −161
1# Codex Security1# Codex Security
2 2
3How to securely operate and manage Codex agents
4
5Codex helps protect your code and data and reduces the risk of misuse.3Codex helps protect your code and data and reduces the risk of misuse.
6 4
7By 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.5By 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.
15 13
16Codex uses different sandbox modes depending on where you run it:14Codex uses different sandbox modes depending on where you run it:
17 15
1816- **Codex cloud**: Runs in isolated OpenAI-managed containers, preventing access to your host system or unrelated data. You can expand access intentionally (for example, to install dependencies or allow specific domains) when needed. Network access is always enabled during the setup phase, which runs before the agent has access to your code.- **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.
19- **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.17- **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.
20 18
21In the `Auto` preset (for example, `--full-auto`), Codex can read files, make edits, and run commands in the working directory automatically.19In the `Auto` preset (for example, `--full-auto`), Codex can read files, make edits, and run commands in the working directory automatically.
22 20
23Codex 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.21Codex 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.
24 22
2523Codex 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.Codex 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).
26 24
27## Network access [Elevated Risk](https://help.openai.com/articles/20001061)25## Network access [Elevated Risk](https://help.openai.com/articles/20001061)
28 26
75 73
76If 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.74If 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.
77 75
76For a middle ground, `approval_policy = { reject = { ... } }` lets you auto-reject specific approval prompt categories (sandbox escalation, execpolicy-rule prompts, or MCP elicitations) while keeping other prompts interactive.
77
78### Common sandbox and approval combinations78### Common sandbox and approval combinations
79 79
80| Intent | Flags | Effect |80| Intent | Flags | Effect |
91 91
92#### Configuration in `config.toml`92#### Configuration in `config.toml`
93 93
94For the broader configuration workflow, see [Config basics](https://developers.openai.com/codex/config-basic), [Advanced Config](https://developers.openai.com/codex/config-advanced#approval-policies-and-sandbox-modes), and the [Configuration Reference](https://developers.openai.com/codex/config-reference).
95
94```96```
95# Always ask for approval mode97# Always ask for approval mode
96approval_policy = "untrusted"98approval_policy = "untrusted"
97sandbox_mode = "read-only"99sandbox_mode = "read-only"
100allow_login_shell = false # optional hardening: disallow login shells for shell-based tools
98 101
99# Optional: Allow network in workspace-write mode102# Optional: Allow network in workspace-write mode
100[sandbox_workspace_write]103[sandbox_workspace_write]
101network_access = true104network_access = true
105
106# Optional: granular approval prompt auto-rejection
107# approval_policy = { reject = { sandbox_approval = true, rules = false, mcp_elicitations = false } }
102```108```
103 109
104You can also save presets as profiles, then select them with `codex --profile <name>`:110You can also save presets as profiles, then select them with `codex --profile <name>`:
130 136
131Codex enforces the sandbox differently depending on your OS:137Codex enforces the sandbox differently depending on your OS:
132 138
133139- **macOS** uses Seatbelt policies and runs commands using `sandbox-exec` with a profile (`-p`) that corresponds to the `--sandbox` mode you selected.- **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.
134140- **Linux** uses `Landlock` plus `seccomp` by default. You can opt into the alternative Linux sandbox pipeline with `features.use_linux_sandbox_bwrap = true` (or `-c use_linux_sandbox_bwrap=true`).- **Linux** uses `Landlock` plus `seccomp` by default. You can opt into the alternative Linux sandbox pipeline with `features.use_linux_sandbox_bwrap = true` (or `-c use_linux_sandbox_bwrap=true`). In managed proxy mode, the bwrap pipeline routes egress through a proxy-only bridge and fails closed if it cannot build valid loopback proxy routes; landlock-only flows do not use that bridge behavior.
135141- **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, you can enable an [experimental sandbox](https://developers.openai.com/codex/windows#windows-experimental-sandbox) implementation.- **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.
136 142
137If 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:143If 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:
138 144
144 150
145This ensures the IDE extension inherits Linux sandbox semantics for commands, approvals, and filesystem access even when the host OS is Windows. Learn more in the [Windows setup guide](https://developers.openai.com/codex/windows).151This ensures the IDE extension inherits Linux sandbox semantics for commands, approvals, and filesystem access even when the host OS is Windows. Learn more in the [Windows setup guide](https://developers.openai.com/codex/windows).
146 152
147153The native Windows sandbox is experimental and has important limitations. For example, it can’t prevent writes in directories where the `Everyone` SID already has write permissions (for example, world-writable folders). See the [Windows setup guide](https://developers.openai.com/codex/windows#windows-experimental-sandbox) for details and mitigation steps.When running natively on Windows, configure the native sandbox mode in `config.toml`:
154
155```
156[windows]
157sandbox = "unelevated" # or "elevated"
158```
159
160See the [Windows setup guide](https://developers.openai.com/codex/windows#windows-sandbox) for details.
148 161
149When 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.162When 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.
150 163
230 243
231## Managed configuration244## Managed configuration
232 245
233246Enterprise admins can control local Codex behavior in two ways:Enterprise admins can configure Codex security settings for their workspace in [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration). See that page for setup and policy details.
234
235- **Requirements**: admin-enforced constraints that users can’t override.
236- **Managed defaults**: starting values applied when Codex launches. Users can still change settings during a session; Codex reapplies managed defaults the next time it starts.
237
238### Admin-enforced requirements (requirements.toml)
239
240Requirements constrain security-sensitive settings (approval policy, sandbox mode, web search mode, and optionally which MCP servers you can enable). If a user explicitly selects a disallowed value (via `config.toml`, CLI flags, profiles, or in-session UI), Codex rejects the change. If a value isn’t explicitly set and the default conflicts with requirements, Codex falls back to a requirements-compliant default. If you configure an `mcp_servers` approved list, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex turns it off.
241
242#### Locations
243
244- Linux/macOS (Unix): `/etc/codex/requirements.toml`
245- macOS MDM: preference domain `com.openai.codex`, key `requirements_toml_base64`
246
247#### Cloud requirements (Business and Enterprise)
248
249When you sign in with ChatGPT on a Business or Enterprise plan, Codex can also
250fetch admin-enforced requirements from the Codex service. This applies across
251Codex surfaces, including the TUI, `codex exec`, and `codex app-server`.
252
253Cloud requirements are currently best-effort. If the fetch fails or times out,
254Codex continues without the cloud layer.
255
256Requirements layer in this order (higher wins):
257
258- macOS managed preferences (MDM; highest precedence)
259- Cloud requirements (ChatGPT Business or Enterprise)
260- `/etc/codex/requirements.toml`
261
262Cloud requirements only fill unset requirement fields, so higher-precedence
263managed layers still win when both specify the same constraint.
264
265For backwards compatibility, Codex also interprets legacy `managed_config.toml` fields `approval_policy` and `sandbox_mode` as requirements (allowing only that single value).
266
267#### Example requirements.toml
268
269This example blocks `--ask-for-approval never` and `--sandbox danger-full-access` (including `--yolo`):
270
271```
272allowed_approval_policies = ["untrusted", "on-request"]
273allowed_sandbox_modes = ["read-only", "workspace-write"]
274```
275
276You can also constrain web search mode:
277
278```
279allowed_web_search_modes = ["cached"] # "disabled" remains implicitly allowed
280```
281
282`allowed_web_search_modes = []` effectively allows only `"disabled"`.
283For example, `allowed_web_search_modes = ["cached"]` prevents live web search even in `danger-full-access` sessions.
284
285#### Enforce command rules from requirements
286
287Admins can also enforce restrictive command rules from `requirements.toml`
288using a `[rules]` table. These rules merge with regular `.rules` files, and the
289most restrictive decision still wins.
290
291Unlike `.rules`, requirements rules must specify `decision`, and that decision
292must be `"prompt"` or `"forbidden"` (not `"allow"`).
293
294```
295[rules]
296prefix_rules = [
297 { pattern = [{ token = "rm" }], decision = "forbidden", justification = "Use git clean -fd instead." },
298 { pattern = [{ token = "git" }, { any_of = ["push", "commit"] }], decision = "prompt", justification = "Require review before mutating history." },
299]
300```
301
302To restrict which MCP servers Codex can enable, add an `mcp_servers` approved list. For stdio servers, match on `command`; for streamable HTTP servers, match on `url`:
303
304```
305[mcp_servers.docs]
306identity = { command = "codex-mcp" }
307
308[mcp_servers.remote]
309identity = { url = "https://example.com/mcp" }
310```
311
312If `mcp_servers` is present but empty, Codex disables all MCP servers.
313
314### Managed defaults (managed\_config.toml)
315
316Managed defaults merge on top of a user’s local `config.toml` and take precedence over any CLI `--config` overrides, setting the starting values when Codex launches. Users can still change those settings during a session; Codex reapplies managed defaults the next time it starts.
317
318Make sure your managed defaults meet your requirements; Codex rejects disallowed values.
319
320#### Precedence and layering
321
322Codex assembles the effective configuration in this order (top overrides bottom):
323
324- Managed preferences (macOS MDM; highest precedence)
325- `managed_config.toml` (system/managed file)
326- `config.toml` (user’s base configuration)
327
328CLI `--config key=value` overrides apply to the base, but managed layers override them. This means each run starts from the managed defaults even if you provide local flags.
329
330Cloud requirements affect the requirements layer (not managed defaults). See
331[Admin-enforced requirements](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml)
332for their precedence.
333
334#### Locations
335
336- Linux/macOS (Unix): `/etc/codex/managed_config.toml`
337- Windows/non-Unix: `~/.codex/managed_config.toml`
338
339If the file is missing, Codex skips the managed layer.
340
341#### macOS managed preferences (MDM)
342
343On macOS, admins can push a device profile that provides base64-encoded TOML payloads at:
344
345- Preference domain: `com.openai.codex`
346- Keys:
347 - `config_toml_base64` (managed defaults)
348 - `requirements_toml_base64` (requirements)
349
350Codex parses these “managed preferences” payloads as TOML and applies them with the highest precedence.
351
352### MDM setup workflow
353
354Codex honors standard macOS MDM payloads, so you can distribute settings with tooling like `Jamf Pro`, `Fleet`, or `Kandji`. A lightweight deployment looks like:
355
3561. Build the managed payload TOML and encode it with `base64` (no wrapping).
3572. Drop the string into your MDM profile under the `com.openai.codex` domain at `config_toml_base64` (managed defaults) or `requirements_toml_base64` (requirements).
3583. Push the profile, then ask users to restart Codex and confirm the startup config summary reflects the managed values.
3594. When revoking or changing policy, update the managed payload; the CLI reads the refreshed preference the next time it launches.
360
361Avoid embedding secrets or high-churn dynamic values in the payload. Treat the managed TOML like any other MDM setting under change control.
362
363### Example managed\_config.toml
364
365```
366# Set conservative defaults
367approval_policy = "on-request"
368sandbox_mode = "workspace-write"
369
370[sandbox_workspace_write]
371network_access = false # keep network disabled unless explicitly allowed
372
373[otel]
374environment = "prod"
375exporter = "otlp-http" # point at your collector
376log_user_prompt = false # keep prompts redacted
377# exporter details live under exporter tables; see Monitoring and telemetry above
378```
379
380### Recommended guardrails
381
382- Prefer `workspace-write` with approvals for most users; reserve full access for controlled containers.
383- Keep `network_access = false` unless your security review allows a collector or domains required by your workflows.
384- Use managed configuration to pin OTel settings (exporter, environment), but keep `log_user_prompt = false` unless your policy explicitly allows storing prompt contents.
385- Periodically audit diffs between local `config.toml` and managed policy to catch drift; managed layers should win over local flags and files.