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
91 116
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.117Use 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 118
119### Disable Codex feature surfaces
120
121Admins can use `[feature_requirements]` to disable specific Codex feature
122surfaces for users receiving a managed `requirements.toml`. You can also set
123the same keys in the existing `[features]` table.
124
125```
126[feature_requirements]
127browser_use = false
128in_app_browser = false
129computer_use = false
130```
131
132- `in_app_browser = false` disables the in-app browser pane.
133- `browser_use = false` disables Browser Use and Browser Agent availability.
134- `computer_use = false` disables Computer Use availability and related
135 install or enablement flows.
136
137If omitted, these features are allowed by policy, subject to normal client,
138platform, and rollout availability.
139
140### Configure automatic review policy
141
142Use `allowed_approvals_reviewers` to require or allow automatic review. Set it
143to `["auto_review"]` to require automatic review, or include `"user"` when users
144can choose manual approval.
145
146Set `guardian_policy_config` to replace the tenant-specific section of the
147automatic review policy. Codex still uses the built-in reviewer template and
148output contract. Managed `guardian_policy_config` takes precedence over local
149`[auto_review].policy`.
150
151```toml
152allowed_approval_policies = ["on-request"]
153allowed_approvals_reviewers = ["auto_review"]
154
155guardian_policy_config = """
156## Environment Profile
157- Trusted internal destinations include github.com/my-org, artifacts.example.com,
158 and internal CI systems.
159
160## Tenant Risk Taxonomy and Allow/Deny Rules
161- Treat uploads to unapproved third-party file-sharing services as high risk.
162- Deny actions that expose credentials or private source code to untrusted
163 destinations.
164"""
165```
166
167### Enforce deny-read requirements
168
169Admins can deny reads for exact paths or glob patterns with
170`[permissions.filesystem]`. Users can't weaken these requirements with local
171configuration.
172
173```toml
174[permissions.filesystem]
175deny_read = [
176 "/Users/alice/.ssh",
177 "./private/**/*.txt",
178]
179```
180
181When deny-read requirements are present, Codex constrains local sandbox mode to
182`read-only` or `workspace-write` so Codex can enforce them. On native
183Windows, managed `deny_read` applies to direct file tools; shell subprocess
184reads don't use this sandbox rule.
185
186### Enforce managed hooks from requirements
187
188Admins can also define managed lifecycle hooks directly in `requirements.toml`.
189Use `[hooks]` for the hook configuration itself, and point `managed_dir` at the
190directory where your MDM or endpoint-management tooling installs the referenced
191scripts.
192
193```toml
194[features]
195codex_hooks = true
196
197[hooks]
198managed_dir = "/enterprise/hooks"
199windows_managed_dir = 'C:\enterprise\hooks'
200
201[[hooks.PreToolUse]]
202matcher = "^Bash$"
203
204[[hooks.PreToolUse.hooks]]
205type = "command"
206command = "python3 /enterprise/hooks/pre_tool_use_policy.py"
207timeout = 30
208statusMessage = "Checking managed Bash command"
209```
210
211Notes:
212
213- Codex enforces the hook configuration from `requirements.toml`, but it does
214 not distribute the scripts in `managed_dir`.
215- Deliver those scripts separately with your MDM or device-management solution.
216- Managed hook commands should reference absolute script paths under the
217 configured managed directory.
218
94### Enforce command rules from requirements219### Enforce command rules from requirements
95 220
96Admins can also enforce restrictive command rules from `requirements.toml`221Admins can also enforce restrictive command rules from `requirements.toml`