security.md +22 −159
13 13
14Codex uses different sandbox modes depending on where you run it:14Codex uses different sandbox modes depending on where you run it:
15 15
1616- **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.
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.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.
18 18
19In 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.
20 20
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.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.
22 22
2323Codex 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).
24 24
25## Network access [Elevated Risk](https://help.openai.com/articles/20001061)25## Network access [Elevated Risk](https://help.openai.com/articles/20001061)
26 26
73 73
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.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.
75 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
76### Common sandbox and approval combinations78### Common sandbox and approval combinations
77 79
78| Intent | Flags | Effect |80| Intent | Flags | Effect |
89 91
90#### Configuration in `config.toml`92#### Configuration in `config.toml`
91 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
92```96```
93# Always ask for approval mode97# Always ask for approval mode
94approval_policy = "untrusted"98approval_policy = "untrusted"
95sandbox_mode = "read-only"99sandbox_mode = "read-only"
100allow_login_shell = false # optional hardening: disallow login shells for shell-based tools
96 101
97# Optional: Allow network in workspace-write mode102# Optional: Allow network in workspace-write mode
98[sandbox_workspace_write]103[sandbox_workspace_write]
99network_access = true104network_access = true
105
106# Optional: granular approval prompt auto-rejection
107# approval_policy = { reject = { sandbox_approval = true, rules = false, mcp_elicitations = false } }
100```108```
101 109
102You 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>`:
128 136
129Codex enforces the sandbox differently depending on your OS:137Codex enforces the sandbox differently depending on your OS:
130 138
131139- **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.
132140- **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.
133141- **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.
134 142
135If 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:
136 144
142 150
143This 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).
144 152
145153The 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.
146 161
147When 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.
148 163
228 243
229## Managed configuration244## Managed configuration
230 245
231246Enterprise 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.
232
233- **Requirements**: admin-enforced constraints that users can’t override.
234- **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.
235
236### Admin-enforced requirements (requirements.toml)
237
238Requirements 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.
239
240#### Locations
241
242- Linux/macOS (Unix): `/etc/codex/requirements.toml`
243- macOS MDM: preference domain `com.openai.codex`, key `requirements_toml_base64`
244
245#### Cloud requirements (Business and Enterprise)
246
247When you sign in with ChatGPT on a Business or Enterprise plan, Codex can also
248fetch admin-enforced requirements from the Codex service. This applies across
249Codex surfaces, including the TUI, `codex exec`, and `codex app-server`.
250
251Cloud requirements are currently best-effort. If the fetch fails or times out,
252Codex continues without the cloud layer.
253
254Requirements layer in this order (higher wins):
255
256- macOS managed preferences (MDM; highest precedence)
257- Cloud requirements (ChatGPT Business or Enterprise)
258- `/etc/codex/requirements.toml`
259
260Cloud requirements only fill unset requirement fields, so higher-precedence
261managed layers still win when both specify the same constraint.
262
263For backwards compatibility, Codex also interprets legacy `managed_config.toml` fields `approval_policy` and `sandbox_mode` as requirements (allowing only that single value).
264
265#### Example requirements.toml
266
267This example blocks `--ask-for-approval never` and `--sandbox danger-full-access` (including `--yolo`):
268
269```
270allowed_approval_policies = ["untrusted", "on-request"]
271allowed_sandbox_modes = ["read-only", "workspace-write"]
272```
273
274You can also constrain web search mode:
275
276```
277allowed_web_search_modes = ["cached"] # "disabled" remains implicitly allowed
278```
279
280`allowed_web_search_modes = []` effectively allows only `"disabled"`.
281For example, `allowed_web_search_modes = ["cached"]` prevents live web search even in `danger-full-access` sessions.
282
283#### Enforce command rules from requirements
284
285Admins can also enforce restrictive command rules from `requirements.toml`
286using a `[rules]` table. These rules merge with regular `.rules` files, and the
287most restrictive decision still wins.
288
289Unlike `.rules`, requirements rules must specify `decision`, and that decision
290must be `"prompt"` or `"forbidden"` (not `"allow"`).
291
292```
293[rules]
294prefix_rules = [
295 { pattern = [{ token = "rm" }], decision = "forbidden", justification = "Use git clean -fd instead." },
296 { pattern = [{ token = "git" }, { any_of = ["push", "commit"] }], decision = "prompt", justification = "Require review before mutating history." },
297]
298```
299
300To 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`:
301
302```
303[mcp_servers.docs]
304identity = { command = "codex-mcp" }
305
306[mcp_servers.remote]
307identity = { url = "https://example.com/mcp" }
308```
309
310If `mcp_servers` is present but empty, Codex disables all MCP servers.
311
312### Managed defaults (managed\_config.toml)
313
314Managed 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.
315
316Make sure your managed defaults meet your requirements; Codex rejects disallowed values.
317
318#### Precedence and layering
319
320Codex assembles the effective configuration in this order (top overrides bottom):
321
322- Managed preferences (macOS MDM; highest precedence)
323- `managed_config.toml` (system/managed file)
324- `config.toml` (user’s base configuration)
325
326CLI `--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.
327
328Cloud requirements affect the requirements layer (not managed defaults). See
329[Admin-enforced requirements](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml)
330for their precedence.
331
332#### Locations
333
334- Linux/macOS (Unix): `/etc/codex/managed_config.toml`
335- Windows/non-Unix: `~/.codex/managed_config.toml`
336
337If the file is missing, Codex skips the managed layer.
338
339#### macOS managed preferences (MDM)
340
341On macOS, admins can push a device profile that provides base64-encoded TOML payloads at:
342
343- Preference domain: `com.openai.codex`
344- Keys:
345 - `config_toml_base64` (managed defaults)
346 - `requirements_toml_base64` (requirements)
347
348Codex parses these “managed preferences” payloads as TOML and applies them with the highest precedence.
349
350### MDM setup workflow
351
352Codex honors standard macOS MDM payloads, so you can distribute settings with tooling like `Jamf Pro`, `Fleet`, or `Kandji`. A lightweight deployment looks like:
353
3541. Build the managed payload TOML and encode it with `base64` (no wrapping).
3552. Drop the string into your MDM profile under the `com.openai.codex` domain at `config_toml_base64` (managed defaults) or `requirements_toml_base64` (requirements).
3563. Push the profile, then ask users to restart Codex and confirm the startup config summary reflects the managed values.
3574. When revoking or changing policy, update the managed payload; the CLI reads the refreshed preference the next time it launches.
358
359Avoid embedding secrets or high-churn dynamic values in the payload. Treat the managed TOML like any other MDM setting under change control.
360
361### Example managed\_config.toml
362
363```
364# Set conservative defaults
365approval_policy = "on-request"
366sandbox_mode = "workspace-write"
367
368[sandbox_workspace_write]
369network_access = false # keep network disabled unless explicitly allowed
370
371[otel]
372environment = "prod"
373exporter = "otlp-http" # point at your collector
374log_user_prompt = false # keep prompts redacted
375# exporter details live under exporter tables; see Monitoring and telemetry above
376```
377
378### Recommended guardrails
379
380- Prefer `workspace-write` with approvals for most users; reserve full access for controlled containers.
381- Keep `network_access = false` unless your security review allows a collector or domains required by your workflows.
382- Use managed configuration to pin OTel settings (exporter, environment), but keep `log_user_prompt = false` unless your policy explicitly allows storing prompt contents.
383- Periodically audit diffs between local `config.toml` and managed policy to catch drift; managed layers should win over local flags and files.