Codex managed configuration: requirements.toml vs defaults

Codex gives admins three levers with different strength. Requirements in requirements.toml are enforced and cannot be overridden by users. Configuration defaults in config.toml can be changed by users. Legacy managed defaults are starting values reapplied at launch. Choose by whether a setting is a guardrail or a convenience.

The three mechanisms

From OpenAI's managed configuration documentation:

1. Requirements: admin enforced constraints. When a user config conflicts, the client falls back to a compatible value and notifies the user.
2. Configuration defaults: system or cloud managed config.toml settings that users can override.
3. Legacy managed defaults in managed_config.toml: applied at client launch, changeable during a run, and reapplied at the next start.

Where files live

• System requirements: /etc/codex/requirements.toml on Unix, and %ProgramData%\OpenAI\Codex\requirements.toml on Windows.
• Managed defaults: /etc/codex/managed_config.toml on Unix.
• macOS MDM: the com.openai.codex domain with base64 keys for requirements and config.
• Cloud: Agent Security in the admin console.

Precedence

For requirements, lowest to highest: system file, cloud requirements, legacy fields reinterpreted as requirements, then macOS MDM. Higher layers override scalar and list values, tables merge by key, and rules, hooks and filesystem restrictions have field specific merging.

For defaults, highest first: macOS managed preferences, managed_config.toml, then the user's config.toml. Command line overrides apply to the base layer, so managed defaults still win.

What you can pin

The docs list keys for allowed approval policies, allowed sandbox modes, allowed permission profiles, web search modes, approvals reviewers, managed hooks (including an option to allow managed hooks only), command prefix rules, an MCP server identity allowlist, plugin marketplace sources, feature flags, network and browser settings, and deny-read paths. Login keys such as allowed login methods and allowed ChatGPT workspaces are honored only from local requirements or MDM, not cloud requirements.

For recent releases the page recommends permission profiles over the allowed sandbox modes key. Also remove the retired untrusted approval policy from managed configs.

Cloud delivery caveats

Cloud requirements go to signed-in users on supported plans, and clients cache them. If a fetch fails and no valid cache exists, the load returns an error rather than starting without the cloud layer. Cloud delivery does not grant workspace access or replace workspace role controls.

A rollout approach

1. Decide the few things that must hold: sandbox limits, approval ceiling, network, MCP allowlist.
2. Put them in requirements, not defaults.
3. Test on one machine with a deliberately conflicting user config.
4. Document the fallback behavior, since users will see their settings replaced.

Quick check

Sources

• Managed configuration

Last reviewed: 19 October 2026.