7 7
8## Admin-enforced requirements (requirements.toml)8## Admin-enforced requirements (requirements.toml)
9 9
1010Requirements constrain security-sensitive settings (approval policy, sandbox mode, web search mode, and optionally which MCP servers users can enable). When resolving configuration (for example from `config.toml`, profiles, or CLI config overrides), if a value conflicts with an enforced rule, Codex falls back to a compatible value and notifies the user. If you configure an `mcp_servers` allowlist, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex disables it.Requirements constrain security-sensitive settings (approval policy, approvals reviewer, automatic review policy, sandbox mode, web search mode, managed hooks, and optionally which MCP servers users can enable). When resolving configuration (for example from `config.toml`, profiles, or CLI config overrides), if a value conflicts with an enforced rule, Codex falls back to a compatible value and notifies the user. If you configure an `mcp_servers` allowlist, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex disables it.
11 11
12Requirements can also constrain [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) via the `[features]` table in `requirements.toml`. Note that features aren't always security-sensitive, but enterprises can pin values if desired. Omitted keys remain unconstrained.12Requirements can also constrain [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) via the `[features]` table in `requirements.toml`. Note that features aren't always security-sensitive, but enterprises can pin values if desired. Omitted keys remain unconstrained.
13 13
19 19
201. Cloud-managed requirements (ChatGPT Business or Enterprise)201. Cloud-managed requirements (ChatGPT Business or Enterprise)
212. macOS managed preferences (MDM) via `com.openai.codex:requirements_toml_base64`212. macOS managed preferences (MDM) via `com.openai.codex:requirements_toml_base64`
22223. System `requirements.toml` (`/etc/codex/requirements.toml` on Unix systems, including Linux/macOS)3. System `requirements.toml` (`/etc/codex/requirements.toml` on Unix systems, including Linux/macOS, or `%ProgramData%\OpenAI\Codex\requirements.toml` on Windows)
23 23
24Across layers, Codex merges requirements per field: if an earlier layer sets a field (including an empty list), later layers don't override that field, but lower layers can still fill fields that remain unset.24Across layers, Codex merges requirements per field: if an earlier layer sets a field (including an empty list), later layers don't override that field, but lower layers can still fill fields that remain unset.
25 25
72allowed_sandbox_modes = ["read-only", "workspace-write"]72allowed_sandbox_modes = ["read-only", "workspace-write"]
73```73```
74 74
75### Override sandbox requirements by host
76
77Use `[[remote_sandbox_config]]` when one managed policy should apply different
78sandbox requirements on different hosts. For example, you can keep a stricter
79default for laptops while allowing workspace writes on matching devboxes or CI
80runners. Host-specific entries currently override `allowed_sandbox_modes` only:
81
82```toml
83allowed_sandbox_modes = ["read-only"]
84
85[[remote_sandbox_config]]
86hostname_patterns = ["*.devbox.example.com", "runner-??.ci.example.com"]
87allowed_sandbox_modes = ["read-only", "workspace-write"]
88```
89
90Codex compares each `hostname_patterns` entry against the best-effort resolved
91host name. It prefers the fully qualified domain name when available and falls
92back to the local host name. Matching is case-insensitive; `*` matches any
93sequence of characters, and `?` matches one character.
94
95The first matching `[[remote_sandbox_config]]` entry wins within the same
96requirements source. If no entry matches, Codex keeps the top-level
97`allowed_sandbox_modes`. Hostname matching is for policy selection only; don't
98treat it as authenticated device proof.
99
75You can also constrain web search mode:100You can also constrain web search mode:
76 101
77```toml102```toml
81`allowed_web_search_modes = []` allows only `"disabled"`.106`allowed_web_search_modes = []` allows only `"disabled"`.
82For example, `allowed_web_search_modes = ["cached"]` prevents live web search even in `danger-full-access` sessions.107For example, `allowed_web_search_modes = ["cached"]` prevents live web search even in `danger-full-access` sessions.
83 108
84109You can also pin [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags):### Pin feature flags
85 110
86111```You can also pin [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) for users
112receiving a managed `requirements.toml`:
113
114```toml
87[features]115[features]
88personality = true116personality = true
89unified_exec = false117unified_exec = false
118
119# Disable specific Codex feature surfaces when needed.
120browser_use = false
121in_app_browser = false
122computer_use = false
90```123```
91 124
92Use the canonical feature keys from `config.toml`'s `[features]` table. Codex normalizes the resulting feature set to meet these pins and rejects conflicting writes to `config.toml` or profile-scoped feature settings.125Use the canonical feature keys from `config.toml`'s `[features]` table. Codex normalizes the resulting feature set to meet these pins and rejects conflicting writes to `config.toml` or profile-scoped feature settings.
93 126
127- `in_app_browser = false` disables the in-app browser pane.
128- `browser_use = false` disables Browser Use and Browser Agent availability.
129- `computer_use = false` disables Computer Use availability and related
130 install or enablement flows.
131
132If omitted, these features are allowed by policy, subject to normal client,
133platform, and rollout availability.
134
135### Configure automatic review policy
136
137Use `allowed_approvals_reviewers` to require or allow automatic review. Set it
138to `["auto_review"]` to require automatic review, or include `"user"` when users
139can choose manual approval.
140
141Set `guardian_policy_config` to replace the tenant-specific section of the
142automatic review policy. Codex still uses the built-in reviewer template and
143output contract. Managed `guardian_policy_config` takes precedence over local
144`[auto_review].policy`.
145
146```toml
147allowed_approval_policies = ["on-request"]
148allowed_approvals_reviewers = ["auto_review"]
149
150guardian_policy_config = """
151## Environment Profile
152- Trusted internal destinations include github.com/my-org, artifacts.example.com,
153 and internal CI systems.
154
155## Tenant Risk Taxonomy and Allow/Deny Rules
156- Treat uploads to unapproved third-party file-sharing services as high risk.
157- Deny actions that expose credentials or private source code to untrusted
158 destinations.
159"""
160```
161
162### Enforce deny-read requirements
163
164Admins can deny reads for exact paths or glob patterns with
165`[permissions.filesystem]`. Users can't weaken these requirements with local
166configuration.
167
168```toml
169[permissions.filesystem]
170deny_read = [
171 "/Users/alice/.ssh",
172 "./private/**/*.txt",
173]
174```
175
176When deny-read requirements are present, Codex constrains local sandbox mode to
177`read-only` or `workspace-write` so Codex can enforce them. On native
178Windows, managed `deny_read` applies to direct file tools; shell subprocess
179reads don't use this sandbox rule.
180
181### Enforce managed hooks from requirements
182
183Admins can also define managed lifecycle hooks directly in `requirements.toml`.
184Use `[hooks]` for the hook configuration itself, and point `managed_dir` at the
185directory where your MDM or endpoint-management tooling installs the referenced
186scripts.
187
188```toml
189[features]
190codex_hooks = true
191
192[hooks]
193managed_dir = "/enterprise/hooks"
194windows_managed_dir = 'C:\enterprise\hooks'
195
196[[hooks.PreToolUse]]
197matcher = "^Bash$"
198
199[[hooks.PreToolUse.hooks]]
200type = "command"
201command = "python3 /enterprise/hooks/pre_tool_use_policy.py"
202timeout = 30
203statusMessage = "Checking managed Bash command"
204```
205
206Notes:
207
208- Codex enforces the hook configuration from `requirements.toml`, but it does
209 not distribute the scripts in `managed_dir`.
210- Deliver those scripts separately with your MDM or device-management solution.
211- Managed hook commands should reference absolute script paths under the
212 configured managed directory.
213
94### Enforce command rules from requirements214### Enforce command rules from requirements
95 215
96Admins can also enforce restrictive command rules from `requirements.toml`216Admins can also enforce restrictive command rules from `requirements.toml`