enterprise/managed-configuration.md +348 −0 added
1# Managed configuration
2
3Enterprise admins can control local Codex behavior in two ways:
4
5- **Requirements**: admin-enforced constraints that users can't override.
6- **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.
7
8## Admin-enforced requirements (requirements.toml)
9
10Requirements 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
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
14For the exact key list, see the [`requirements.toml` section in Configuration Reference](https://developers.openai.com/codex/config-reference#requirementstoml).
15
16### Locations and precedence
17
18Codex applies requirements layers in this order (earlier wins per field):
19
201. Cloud-managed requirements (ChatGPT Business or Enterprise)
212. macOS managed preferences (MDM) via `com.openai.codex:requirements_toml_base64`
223. System `requirements.toml` (`/etc/codex/requirements.toml` on Unix systems, including Linux/macOS, or `%ProgramData%\OpenAI\Codex\requirements.toml` on Windows)
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.
25
26For backwards compatibility, Codex also interprets legacy `managed_config.toml` fields `approval_policy` and `sandbox_mode` as requirements (allowing only that single value).
27
28### Cloud-managed requirements
29
30When you sign in with ChatGPT on a Business or Enterprise plan, Codex can also fetch admin-enforced requirements from the Codex service. This is another source of `requirements.toml`-compatible requirements. This applies across Codex surfaces, including the CLI, App, and IDE Extension.
31
32#### Configure cloud-managed requirements
33
34Go to the [Codex managed-config page](https://chatgpt.com/codex/settings/managed-configs).
35
36Create a new managed requirements file using the same format and keys as `requirements.toml`.
37
38```toml
39enforce_residency = "us"
40allowed_approval_policies = ["on-request"]
41allowed_sandbox_modes = ["read-only", "workspace-write"]
42
43[rules]
44prefix_rules = [
45 { pattern = [{ any_of = ["bash", "sh", "zsh"] }], decision = "prompt", justification = "Require explicit approval for shell entrypoints" },
46]
47```
48
49Save the configuration. Once saved, the updated managed requirements apply immediately for matching users.
50For more examples, see [Example requirements.toml](#example-requirementstoml).
51
52#### Assign requirements to groups
53
54Admins can configure different managed requirements for different user groups, and also set a default fallback requirements policy.
55
56If a user matches more than one group-specific rule, the first matching rule applies. Codex doesn't fill unset fields from later matching group rules.
57
58For example, if the first matching group rule sets only `allowed_sandbox_modes = ["read-only"]` and a later matching group rule sets `allowed_approval_policies = ["on-request"]`, Codex applies only the first matching group rule and doesn't fill `allowed_approval_policies` from the later rule.
59
60#### How Codex applies cloud-managed requirements locally
61
62When a user starts Codex and signs in with ChatGPT on a Business or Enterprise plan, Codex applies managed requirements on a best-effort basis. Codex first checks for a valid, unexpired local managed requirements cache entry and uses it if available. If the cache is missing, expired, corrupted, or doesn't match the current auth identity, Codex attempts to fetch managed requirements from the service (with retries) and writes a new signed cache entry on success. If no valid cached entry is available and the fetch fails or times out, Codex continues without the managed requirements layer.
63
64After cache resolution, Codex enforces managed requirements as part of the normal requirements layering described above.
65
66### Example requirements.toml
67
68This example blocks `--ask-for-approval never` and `--sandbox danger-full-access` (including `--yolo`):
69
70```toml
71allowed_approval_policies = ["untrusted", "on-request"]
72allowed_sandbox_modes = ["read-only", "workspace-write"]
73```
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 dev boxes 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`. Host name matching is for policy selection only; don't
98treat it as authenticated device proof.
99
100You can also constrain web search mode:
101
102```toml
103allowed_web_search_modes = ["cached"] # "disabled" remains implicitly allowed
104```
105
106`allowed_web_search_modes = []` allows only `"disabled"`.
107For example, `allowed_web_search_modes = ["cached"]` prevents live web search even in `danger-full-access` sessions.
108
109### Configure network access requirements
110
111Use `[experimental_network]` in `requirements.toml` when administrators should
112define network access requirements centrally. These requirements are separate
113from the user `features.network_proxy` toggle: they can configure sandboxed
114networking without that feature flag, but they do not grant command network
115access when the active sandbox keeps networking off.
116
117```toml
118experimental_network.enabled = true
119experimental_network.dangerously_allow_all_unix_sockets = true
120experimental_network.allow_local_binding = true
121experimental_network.allowed_domains = [
122 "api.openai.com",
123 "*.example.com",
124]
125experimental_network.denied_domains = [
126 "blocked.example.com",
127 "*.exfil.example.com",
128]
129```
130
131Use `experimental_network.managed_allowed_domains_only = true` only when you
132also define administrator-owned `allowed_domains` and want that allowlist to be
133exclusive. If it is `true` without managed allow rules, user-added domain allow
134rules do not remain effective.
135
136The domain syntax, local/private destination rules, deny-over-allow behavior,
137and DNS rebinding limitations are the same as the sandboxed networking behavior
138described in [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security#network-isolation).
139
140### Pin feature flags
141
142You can also pin [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) for users
143receiving a managed `requirements.toml`:
144
145```toml
146[features]
147personality = true
148unified_exec = false
149
150# Disable specific Codex feature surfaces when needed.
151browser_use = false
152in_app_browser = false
153computer_use = false
154```
155
156Use 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.
157
158<a id="disable-codex-feature-surfaces"></a>
159
160- `in_app_browser = false` disables the in-app browser pane.
161- `browser_use = false` disables Browser Use and Browser Agent availability.
162- `computer_use = false` disables Computer Use availability and related
163 install or setup flows.
164
165If omitted, these features are allowed by policy, subject to normal client,
166platform, and rollout availability.
167
168### Configure automatic review policy
169
170Use `allowed_approvals_reviewers` to require or allow automatic review. Set it
171to `["auto_review"]` to require automatic review, or include `"user"` when users
172can choose manual approval.
173
174Set `guardian_policy_config` to replace the tenant-specific section of the
175automatic review policy. Codex still uses the built-in reviewer template and
176output contract. Managed `guardian_policy_config` takes precedence over local
177`[auto_review].policy`.
178
179```toml
180allowed_approval_policies = ["on-request"]
181allowed_approvals_reviewers = ["auto_review"]
182
183guardian_policy_config = """
184## Environment Profile
185- Trusted internal destinations include github.com/my-org, artifacts.example.com,
186 and internal CI systems.
187
188## Tenant Risk Taxonomy and Allow/Deny Rules
189- Treat uploads to unapproved third-party file-sharing services as high risk.
190- Deny actions that expose credentials or private source code to untrusted
191 destinations.
192"""
193```
194
195### Enforce deny-read requirements
196
197Admins can deny reads for exact paths or glob patterns with
198`[permissions.filesystem]`. Users can't weaken these requirements with local
199configuration.
200
201```toml
202[permissions.filesystem]
203deny_read = [
204 "/Users/alice/.ssh",
205 "./private/**/*.txt",
206]
207```
208
209When deny-read requirements are present, Codex constrains local sandbox mode to
210`read-only` or `workspace-write` so Codex can enforce them. On native
211Windows, managed `deny_read` applies to direct file tools; shell subprocess
212reads don't use this sandbox rule.
213
214### Enforce managed hooks from requirements
215
216Admins can also define managed lifecycle hooks directly in `requirements.toml`.
217Use `[hooks]` for the hook configuration itself, and point `managed_dir` at the
218directory where your MDM or endpoint-management tooling installs the referenced
219scripts.
220
221To enforce managed hooks even for users who disabled hooks locally, pin
222`[features].hooks = true` alongside `[hooks]`.
223
224```toml
225[features]
226hooks = true
227
228[hooks]
229managed_dir = "/enterprise/hooks"
230windows_managed_dir = 'C:\enterprise\hooks'
231
232[[hooks.PreToolUse]]
233matcher = "^Bash$"
234
235[[hooks.PreToolUse.hooks]]
236type = "command"
237command = "python3 /enterprise/hooks/pre_tool_use_policy.py"
238timeout = 30
239statusMessage = "Checking managed Bash command"
240```
241
242Notes:
243
244- Codex enforces the hook configuration from `requirements.toml`, but it does
245 not distribute the scripts in `managed_dir`.
246- Deliver those scripts separately with your MDM or device-management solution.
247- Managed hook commands should reference absolute script paths under the
248 configured managed directory.
249
250### Enforce command rules from requirements
251
252Admins can also enforce restrictive command rules from `requirements.toml`
253using a `[rules]` table. These rules merge with regular `.rules` files, and the
254most restrictive decision still wins.
255
256Unlike `.rules`, requirements rules must specify `decision`, and that decision
257must be `"prompt"` or `"forbidden"` (not `"allow"`).
258
259```toml
260[rules]
261prefix_rules = [
262 { pattern = [{ token = "rm" }], decision = "forbidden", justification = "Use git clean -fd instead." },
263 { pattern = [{ token = "git" }, { any_of = ["push", "commit"] }], decision = "prompt", justification = "Require review before mutating history." },
264]
265```
266
267To 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`:
268
269```toml
270[mcp_servers.docs]
271identity = { command = "codex-mcp" }
272
273[mcp_servers.remote]
274identity = { url = "https://example.com/mcp" }
275```
276
277If `mcp_servers` is present but empty, Codex disables all MCP servers.
278
279## Managed defaults (`managed_config.toml`)
280
281Managed 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.
282
283Make sure your managed defaults meet your requirements; Codex rejects disallowed values.
284
285### Precedence and layering
286
287Codex assembles the effective configuration in this order (top overrides bottom):
288
289- Managed preferences (macOS MDM; highest precedence)
290- `managed_config.toml` (system/managed file)
291- `config.toml` (user's base configuration)
292
293CLI `--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.
294
295Cloud-managed requirements affect the requirements layer (not managed defaults). See the Admin-enforced requirements section above for precedence.
296
297### Locations
298
299- Linux/macOS (Unix): `/etc/codex/managed_config.toml`
300- Windows/non-Unix: `~/.codex/managed_config.toml`
301
302If the file is missing, Codex skips the managed layer.
303
304### macOS managed preferences (MDM)
305
306On macOS, admins can push a device profile that provides base64-encoded TOML payloads at:
307
308- Preference domain: `com.openai.codex`
309- Keys:
310 - `config_toml_base64` (managed defaults)
311 - `requirements_toml_base64` (requirements)
312
313Codex parses these "managed preferences" payloads as TOML. For managed defaults (`config_toml_base64`), managed preferences have the highest precedence. For requirements (`requirements_toml_base64`), precedence follows the cloud-managed requirements order described above. The same requirements-side `[features]` table works in `requirements_toml_base64`; use canonical feature keys there as well.
314
315### MDM setup workflow
316
317Codex honors standard macOS MDM payloads, so you can distribute settings with tooling like `Jamf Pro`, `Fleet`, or `Kandji`. A lightweight deployment looks like:
318
3191. Build the managed payload TOML and encode it with `base64` (no wrapping).
3202. Drop the string into your MDM profile under the `com.openai.codex` domain at `config_toml_base64` (managed defaults) or `requirements_toml_base64` (requirements).
3213. Push the profile, then ask users to restart Codex and confirm the startup config summary reflects the managed values.
3224. When revoking or changing policy, update the managed payload; the CLI reads the refreshed preference the next time it launches.
323
324Avoid embedding secrets or high-churn dynamic values in the payload. Treat the managed TOML like any other MDM setting under change control.
325
326### Example managed_config.toml
327
328```toml
329# Set conservative defaults
330approval_policy = "on-request"
331sandbox_mode = "workspace-write"
332
333[sandbox_workspace_write]
334network_access = false # keep network disabled unless explicitly allowed
335
336[otel]
337environment = "prod"
338exporter = "otlp-http" # point at your collector
339log_user_prompt = false # keep prompts redacted
340# exporter details live under exporter tables; see Monitoring and telemetry above
341```
342
343### Recommended guardrails
344
345- Prefer `workspace-write` with approvals for most users; reserve full access for controlled containers.
346- Keep `network_access = false` unless your security review allows a collector or domains required by your workflows.
347- Use managed configuration to pin OTel settings (exporter, environment), but keep `log_user_prompt = false` unless your policy explicitly allows storing prompt contents.
348- Periodically audit diffs between local `config.toml` and managed policy to catch drift; managed layers should win over local flags and files.