enterprise/managed-configuration.md +888 −491
4 4
5Managed configuration lets enterprise admins set supported requirements and defaults for ChatGPT Work and Codex. Requirements constrain what users and tasks can do. Defaults provide starting values. Support depends on the product, client version, and execution environment.5Managed configuration lets enterprise admins set supported requirements and defaults for ChatGPT Work and Codex. Requirements constrain what users and tasks can do. Defaults provide starting values. Support depends on the product, client version, and execution environment.
6 6
77For Work with local access and dots, supported Global policy governs the shared cloud orchestrator when managed policy is enabled; applicable local execution requirements govern the connected computer. Work cloud containers retain existing Work Cloud policies, and supported device controls still apply to local execution. Codex keeps its existing configuration behavior. Managed configuration does not grant a workspace seat or feature access. Use [Roles and workspace permissions](https://learn.chatgpt.com/docs/enterprise/roles-and-workspace-permissions) for those controls.Start in **Agent security** in the Admin Console for supported cloud-managed
8settings. Use the settings controls for common tasks, or select **Edit as TOML**
9to inspect, copy, or edit the configuration text. Both views edit the same policy;
10TOML also exposes supported fields without a dedicated control. You don't need to
11distribute a local file to use cloud-managed settings. Authentication restrictions and
12device-managed deployments have separate [local setup](#manage-authentication-locally).
8 13
9Enterprise admins can control supported local client behavior with:14Enterprise admins can control supported local client behavior with:
10 15
16 21
17See [Agent Security](https://learn.chatgpt.com/docs/enterprise/agent-security) for the Global baseline, environment overrides, and orchestrator and executor field lists.22See [Agent Security](https://learn.chatgpt.com/docs/enterprise/agent-security) for the Global baseline, environment overrides, and orchestrator and executor field lists.
18 23
1924<a id="agent-security-and-work-sync"></a>## Configure a policy in Agent security
25
26Where Agent security is enabled, workspace owners, workspace admins, and members
27with Codex admin permissions can manage policies. Access to the policy editor
28doesn't grant members access to the features that a policy controls.
29
30Use **Workspace default** for the workspace baseline. Use **Overrides** when
31specific users, groups, or roles need different settings. An audience override
32selects who receives a policy; an environment setting selects where supported
33execution controls apply.
34
351. Open **Admin Console** > **Agent security** and select **Workspace default** or
36 the policy you want to edit under **Overrides**.
371. Open **Requirements** to set enforced limits, or **Defaults** to set starting
38 values that members can change within those limits.
391. Keep approval, web search, and other agent-wide settings in **Global**. Where
40 available, use **Add environment settings** in the relevant card to add
41 **Local Environments** or **Codex Cloud Environments** for supported execution
42 settings. An empty environment document inherits settings from Global; it doesn't copy or
43 pin the current baseline.
441. Use the controls described in this guide. For advanced fields, select
45 **Edit as TOML** and edit the appropriate scope's `requirements.toml` or
46 `config.toml`. Select **Use settings controls** to return to the visual editor.
471. Review validation messages, then select **Save changes**. Applying a rule in
48 a rule editor updates the draft; it doesn't save the policy by itself.
491. Check policy selection and the supported client behavior as described in
50 [Confirm the admin and employee experience](#confirm-the-admin-and-employee-experience).
51
52Environment editors and supported fields depend on the workspace and policy.
53See [Where settings apply](https://learn.chatgpt.com/docs/enterprise/agent-security#where-settings-apply)
54before moving a Global setting into an environment. A setting in Global doesn't
55necessarily apply to every product or execution path.
56
57### Copy or reuse a configuration
58
59The visual editor doesn't replace TOML. Select **Edit as TOML** to copy a
60configuration, keep a reference copy, or reuse settings in another policy.
61Select **Use settings controls** to switch back to the visual editor.
62
631. Open the source policy and select **Edit as TOML**.
641. Choose the scope you want to copy: **Global** or an available environment tab.
65 Copy the text from **Requirements** (`requirements.toml`), **Defaults**
66 (`config.toml`), or both, depending on what you want to reuse.
671. Open the destination policy, select **Edit as TOML**, and choose the matching
68 scope. Paste requirements into `requirements.toml` and defaults into
69 `config.toml`. Review existing destination settings before replacing text;
70 keep unrelated settings that should still apply.
711. Review validation messages and the destination policy's targets and priority,
72 then select **Save changes**. Confirm the resulting client behavior before
73 relying on the copied policy.
74
75The copied text contains the authored settings for that policy and scope. It doesn't include assignments, policy order, other environment documents, or the
76effective configuration combined from other policies and device settings.
77Copy environment settings separately when needed. Switching views or copying
78text doesn't save a policy change.
79
80Try the example below: change a setting, then select **Edit as TOML** to see its
81configuration. Switch back with **Use settings controls** to keep experimenting.
82
83
84
85> Illustration: Interactive example of Agent security settings and their TOML representation. The initial requirements allow on-request approvals, read-only sandboxing, and disabled web search. Change a sample setting and select Edit as TOML to see the corresponding field; Use settings controls returns to the same sample choices. This example does not change workspace policies.
86
87
88
89### Choose the right control
90
91| Task | Where to configure it | What it changes |
92| ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
93| [Restrict browser and native-app access](#control-browser-and-computer-use) | **Requirements** > **Desktop feature availability**, **Site rules**, and **App rules** | Controls which supported desktop capabilities are available and which sites or apps they can access. |
94| [Limit approval, sandbox, or web search choices](#set-approval-sandbox-and-web-search-guardrails) | **Requirements** > **Policy guardrails** | Restricts the choices available to supported clients. |
95| [Set starting approval, permission, search, or tool behavior](#set-configuration-defaults) | **Defaults** | Sets values members can change within enforced requirements. |
96| [Restrict command network destinations](#configure-network-access) | **Requirements** > **Network use controls** | Applies managed networking rules to supported command traffic. It isn't a workspace-wide internet switch. |
97| [Configure plugins and managed hooks](#configure-plugins-and-managed-hooks) | **Edit as TOML** | Lets you configure supported policy fields that have no dedicated visual control. |
98| [Restrict login methods or workspaces before sign-in](#manage-authentication-locally) | Local system requirements or macOS MDM | Applies authentication restrictions before cloud policy is loaded. |
99
100## Control browser and Computer Use
101
102Use **Agent security** in the Admin Console to manage browser and native-app access
103for supported desktop clients. Start with the UI controls. The TOML examples below
104provide a configuration reference for file-based policy delivery and settings that
105need the TOML editor.
106
107Browser Use controls agent-driven activity in a browser. Computer Use controls
108agent-driven activity in native desktop apps. Settings for the built-in browser
109pane are separate from Browser Use. See [browser sessions and existing
110sign-ins](https://learn.chatgpt.com/docs/enterprise/chatgpt-work-local-security#browser-sessions-and-existing-sign-ins)
111for the differences between browser paths.
112
113### Before you begin
114
115Use an account with permission to manage Agent Security policies. Confirm which
116people receive the policy and which client versions and operating systems you need
117to support. Review [Agent Security](https://learn.chatgpt.com/docs/enterprise/agent-security) for policy
118assignments, Global settings, and supported environment overrides.
119
120Use **Requirements** for limits users can't override. **Defaults** set starting
121values within those limits. Allowing a site or app doesn't install a plugin, grant
122operating-system permissions, sign a user in, or approve an action that still
123requires review.
124
125Under **Desktop feature availability**, review **Browser use**, **External browser
126use**, and **Computer use**. **Force off** disables the corresponding feature; an
127allow rule for a site or app doesn't override it. Review **Full CDP access**
128separately; **Block user opt-in** prevents users from enabling it.
129
130These desktop controls don't configure the hosted Work Cloud browser. Manage
131**Cloud browser use** and **Cloud network access** separately under
132**Admin Console > Permissions & roles > Workspace capabilities > Cloud computer capabilities**.
133See [how Agent Security applies to Work Cloud](https://learn.chatgpt.com/docs/enterprise/agent-security#how-agent-security-applies-to-work-cloud).
134
135### Configure browser access
136
137{/* Preserve the console label "Auto-approve requests". */}
138{/* vale Microsoft.Auto = NO */}
139
1401. Open **Admin Console > Agent security**. Use **Workspace default** for the
141 workspace baseline, or open the relevant policy under **Overrides**. In
142 **Requirements**, go to **Desktop browser controls**.
1431. In **Site rules**, open the **Default** row's actions and choose **Edit Default**.
144 For access limited to approved sites, set **Site access** to **Block**, then
145 choose **Apply rule**. The **Default** row supplies values that a matching site
146 rule leaves at **Use default rule**.
1471. Choose **Add site rule**. In **Site or pattern**, enter an origin: a scheme,
148 hostname, and optional port. For example, `https://example.com` is valid;
149 `https://example.com/files` isn't. Don't include a path, query, or fragment.
150 HTTP and HTTPS are different origins. Specify the port when it differs from
151 the scheme's default.
1521. Set **Site access** and review **Downloads**, **Uploads**, and **Debug/CDP**.
153 Choose **Allow** or **Block** as appropriate, or leave a setting at **Use default
154 rule**. **Debug/CDP** controls full Chrome DevTools Protocol access for browser
155 debugging. **Allow** lets normal policy and approval checks continue.
1561. Review **Auto-review**, **Always allow**, and **Approval duration** for the site.
157 **Approval duration** offers **This turn** and **This thread**. Review **Browser
158 history**, **Save site approvals**, and **Auto-approve requests** in **Desktop
159 browser controls** as well.
1601. Choose **Add rule**, review validation messages, and select **Save changes**.
161 Test an allowed site and a blocked site on a supported client that receives the policy. Test
162 uploads, downloads, and other restricted actions separately.
20 163
21164<span{/* vale Microsoft.Auto = YES */}
22 id="agent-security-and-local-computer-access"
23 data-localization-body-anchor
24/>
25 165
26## Agent Security and Local computer access with Work Cloud
27 166
28Use Agent Security in the Admin Console to manage policies and configuration. It replaces Policies & Configuration. Agent Security will be available to everyone, independently of Local computer access with Work Cloud. Existing policies, assignments, and ordering are preserved. Review your existing policies in Agent Security. Local computer access with Work Cloud is a separate opt-in. See [Agent Security](https://learn.chatgpt.com/docs/enterprise/agent-security) for migration guidance.
29 167
30168Before moving policy automation to **Agent Security**:> Illustration: Agent Security site-rule editor with site access, transfers, debugging, and approval controls.
31 169
321. Identify affected integrations. Inventory Terraform configurations and scripts that update policies, and record which policies they manage.
33 170
341. Use the policy API to manage Global settings. To manage Local or Codex Cloud settings, use the Agent Security UI. Existing Global API workflows remain available after migration. Test your scripts and Terraform integrations, and confirm that policy assignments and ordering are unchanged.
35 171
361721. Make any required changes and test the automation. Verify that an intended update reaches the correct Agent Security policy and that the resulting controls are enforced.Disabling automatic review for browser actions sends those actions to the user for
173approval instead. It doesn't disable model safety monitoring.
37 174
38175Policy migration does not grant local computer access for Work or dots. Reviewing or creating policies is recommended before rollout, but the confirmation flow does not require policy creation to enable access. Before enabling **Allow local computer access**, review the migrated baseline or create a cloud baseline if your policies are currently delivered only through MDM. If `enforce_residency` is enabled in any cloud policy, **Allow local computer access** is disabled for both Work and dots. This safeguard does not configure workspace residency or, by itself, disable Work Cloud or dots.When several origin patterns match, the most restrictive value wins for each
176setting. Local configuration can't relax a managed denial. Managed network denies
177and exclusive allowlists also apply to browser tools. See the [browser policy
178fields](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml) for origin patterns
179and approval behavior.
39 180
40181Environment overrides vary supported settings within a policy. Within a given policy, the order from highest to lowest is OS-specific environment override → all-OS environment override → Global. A higher-priority policy still wins over a lower-priority policy, even when the lower-priority policy is more specific. Some requirements have field-specific merge rules. Confirm which override editors and fields are available for your workspace.Computer Use can also operate a browser as a native app. Browser Use site and
182capability rules don't apply to that path. Review native-app access separately;
183see the [browser security
184boundaries](https://learn.chatgpt.com/docs/enterprise/chatgpt-work-local-security#browser-sessions-and-existing-sign-ins).
41 185
42186When managed policy and remote hooks are enabled, Work Cloud with local access and dots use admin-managed remote MCP hooks on the cloud orchestrator. Configure `mcp_tool` handlers in Global `requirements.toml`. Work Cloud without local access and personal accounts do not use these enterprise hooks. Command/shell, prompt, and agent handlers; hooks from local configuration, plugins, or local directories; environment-scoped hooks; and `SessionEnd` MCP hooks are not supported with cloud orchestration, even when tools execute locally. When both orchestration and execution are local, existing supported hooks continue to work in local-only Work and Codex threads. Admins can still configure supported managed hooks in Agent Security for those workflows. Before relying on these hooks, test callback connectivity, required events, and failure behavior. An explicit supported denial can block an action, but a `PreToolUse` callback error, timeout, or malformed response can fail the hook without blocking the tool. MCP hooks do not provide a complete Compliance API audit trail. See the [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference).### Configure native-app access
43 187
44188## Configure plugin marketplaces and defaults1. In **Requirements**, go to **Desktop app controls > App rules**.
1891. Use the **Default** row's actions to configure access for apps without a matching
190 rule. To limit Computer Use to approved apps, block access by default and add
191 allow rules for those apps.
1921. Choose **Add app rule**. In the **Edit rule** dialog, select **macOS bundle ID**,
193 **Windows AUMID**, or **Windows executable** from **App**. Enter the exact **App
194 identifier** for a bundle ID or Application User Model ID (AUMID). For **Windows
195 executable**, enter **Publisher name** and **Product name**; **Binary name** is
196 optional. Use verified app identity information, not a display name or file path.
1971. Set **App access** for the rule, then choose **Add rule**. Review **Save app
198 approvals** under **Desktop app controls**, review validation messages, and
199 select **Save changes**. Disabling saved approvals still permits approvals for the current
200 session; allowing saved approvals doesn't approve an app.
2011. Test an allowed app and a blocked app on each supported operating system in
202 your deployment. Confirm that operating-system permissions still apply and that users must still provide required approvals.
45 203
46Define local or Git marketplaces and plugin defaults in system `config.toml`
47or the supported configuration defaults in **Agent Security**.
48These settings are defaults, not enforced policy.
49 204
50See [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference) for configuration keys,
51[Configuration precedence](https://learn.chatgpt.com/docs/config-file/config-basic#configuration-precedence)
52for overrides, and [repo plugin settings](https://developers.openai.com/plugins/build/plugins#enable-or-disable-a-plugin-for-a-repo)
53for project-level configuration. [Workspace GitHub import and
54sync](https://learn.chatgpt.com/docs/enterprise/plugin-management) is separate.
55 205
56206## Admin-enforced requirements (requirements.toml)> Illustration: Agent Security native-app rule editor showing macOS bundle ID, app identifier, and app access.
57 207
58Requirements constrain security-sensitive settings (approval policy, approvals reviewer, automatic review policy, sandbox mode, permission profiles, web search mode, managed hooks, which MCP servers users can enable, and which plugin marketplace sources they can use). When resolving configuration (for example from `config.toml`, [profile files](https://learn.chatgpt.com/docs/config-file/config-advanced#profiles), or CLI config overrides), if a value conflicts with an enforced rule, the local client falls back to a compatible value and notifies the user. If you configure an `mcp_servers` allowlist, the client enables an MCP server only when both its name and identity match an approved entry; otherwise, the client disables it.
59 208
60Requirements can also constrain [feature flags](https://learn.chatgpt.com/docs/config-file/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.
61 209
62210For Codex 0.138.0 or later, prefer [permission profiles](https://learn.chatgpt.com/docs/permissions)See the [Computer Use policy
63211with `allowed_permission_profiles` and managed `default_permissions`. Usefields](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml) for Windows identity
64212`allowed_sandbox_modes` only for legacy deployments that still configurerequirements and [locked-use restrictions](#restrict-locked-computer-use) for
65213`sandbox_mode`.managed Macs.
66 214
67215For the exact key list, see the [`requirements.toml` section in Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml).### Check the effective policy
68 216
69217### Migrate the retired `untrusted` approval policyIf an allowed site or app is still blocked, check other matching rules, policy
70218 assignments and priority, device requirements, and user configuration. An allow
71219Codex and ChatGPT Work no longer support `approval_policy = "untrusted"`.rule in one source doesn't bypass another applicable denial. See [requirements
72220Remove it from managed defaults, legacy `managed_config.toml`, and any user,locations and precedence](#locations-and-precedence).
73project, profile, or startup configuration that sets it.
74 221
75222For interactive, read-only use, select `approval_policy = "on-request"` with aIf a setting has no effect, verify that the client, operating system, and policy
76223read-only sandbox or permission profile allowed by your managed requirements.delivery path support it. Pay particular attention to Work Cloud with local
77224Commands allowed by that sandbox can run without approval.computer access: some fields have partial support or require validation. See
225[Work compatibility in the Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference).
78 226
79227To keep stricter command approvals, omit an explicit `approval_policy`, setCheck [workspace permissions](https://learn.chatgpt.com/docs/enterprise/roles-and-workspace-permissions)
80228`trust_level = "untrusted"` in the project's entry in user-leveland [plugin controls](https://learn.chatgpt.com/docs/enterprise/apps-and-connectors) separately when a user
81229`~/.codex/config.toml`, and keep `untrusted` in `allowed_approval_policies`.can't access the feature or required plugin.
82This also disables project-local configuration. Setting `on-request` explicitly
83overrides that policy. See
84[Migrate from the retired `untrusted` approval policy](https://learn.chatgpt.com/docs/agent-approvals-security#migrate-from-the-retired-untrusted-approval-policy)
85for examples and security tradeoffs.
86 230
87231### Locations and precedence### TOML configuration reference
88 232
89233For local execution, requirements are applied from lower to higher priority as follows. This ordering also applies to local steps in Local computer access with Work Cloud:The following examples describe the same policy intent for `requirements.toml`.
234Use them when managing policy through files or the TOML editor. You don't need to
235edit a local file to use the controls available in Agent Security.
90 236
912371. System `requirements.toml` (`/etc/codex/requirements.toml` on Unix systems,This browser example denies access by default, allows `https://example.com`, blocks
92238 including Linux and macOS, or `%ProgramData%\OpenAI\Codex\requirements.toml`uploads and full CDP access there, and limits site-access approval to the current
93239 on Windows).turn:
942. Agent Security requirements delivered in the cloud config bundle.
953. Legacy `managed_config.toml` fields that the local client reinterprets as requirements.
964. macOS managed preferences (MDM) delivered through
97 `com.openai.codex:requirements_toml_base64`.
98
99Higher-precedence layers override ordinary scalar and list values from lower
100layers. Tables merge by key, while requirements such as rules, hooks, and
101filesystem restrictions have field-specific composition behavior. Use the
102[`requirements.toml` reference](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml)
103for the current schema instead of assuming that every field merges the same
104way.
105
106For backward compatibility, supported local clients reinterpret the legacy
107`approval_policy`, `approvals_reviewer`, and `sandbox_mode` fields as
108requirements. This conversion adds compatibility choices where necessary; use
109`requirements.toml` for explicit allowlists.
110 240
241```toml
242[browser_use]
243allow_history_access = false
244allow_global_persistent_approval = false
111 245
246[browser_use.default_origin_policy]
247access = "deny"
112 248
249[browser_use.origins."https://example.com"]
250access = "allow"
251uploads = "deny"
252downloads = "allow"
253full_cdp_access = "deny"
254persistent_approval = false
255access_approval_lifetime = "turn"
256```
113 257
114258### Precedence for Local computer access with Work CloudTo disable automatic review for browser actions, set
259`browser_use.disable_auto_review = true`, or set `auto_review = "deny"` on an
260origin policy to restrict it for that origin.
115 261
116262For Work with local access and dots, distinguish Global orchestrator policy from execution policy. Applicable local requirements govern the connected computer. Work cloud containers and dots cloud computers use their own execution configuration and requirements, rather than the managed environment bundle used by other executors.To enable [Site tools](https://learn.chatgpt.com/docs/webmcp) for an eligible Enterprise workspace,
263set `browser_use.allow_webmcp = true`. This managed opt-in applies to the
264desktop app's built-in browser. Setting it to `false` or omitting it leaves
265normal feature availability checks in place; `false` does not enforce a block.
266User preferences and site permissions still apply.
117 267
118268For local execution, MDM and legacy managed-device requirements rank above Agent Security. The device's system requirements file ranks below Agent Security. Within each policy, resolve OS-specific environment overrides before all-OS environment overrides, then Global. Policy priority wins over specificity across policies.This native-app example allows Calculator on macOS, denies other apps by default,
269and prevents app approvals from persisting across sessions:
119 270
120271| Control | Local Work without sync and local Codex | Local computer access with Work Cloud |```toml
121272| ----------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |[computer_use]
122273| Enterprise requirements | Follow the local requirements order above. | Apply to local executors. Work cloud containers retain existing Work Cloud policies. |default_app_access = "deny"
123274| Device execution restrictions | Enforced by supported local controls. | Follow the local requirements order above, including MDM and legacy requirements above Agent Security. |allow_persistent_approval = false
124| Environment overrides | Use the configuration model for the relevant product. | Within one policy: OS-specific environment override, then all-OS environment override, then Global. A lower-priority policy cannot win through specificity. |
125 275
126276Requirements impose constraints, while configuration defaults supply starting values. For Work with local access and dots, supported Global policy applies through the shared cloud orchestrator when managed policy is enabled. Applicable local `requirements.toml` requirements govern execution on a connected computer. Work cloud containers and dots cloud computers use their own execution configuration and requirements, rather than the managed environment bundle used by other executor types. Local execution restrictions do not automatically apply to these cloud computers. Review cloud capability permissions and test local and cloud execution separately.[computer_use.macos.bundle_ids]
277"com.apple.calculator" = "allow"
278```
127 279
128280Keep orchestrator controls, including approvals and web search, in Global. Use the dedicated Allowed approval policies and Allowed web search modes controls where available, and TOML for other supported fields. See the [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference) for the field list and execution scope.Windows policies can identify packaged apps with `computer_use.windows.aumids` or
281executables with `computer_use.windows.exes`. Executable rules require
282`publisher_name`, `product_name`, and `access`; `binary_name` is optional.
129 283
130284### Network policy precedence and runtime limitsFor all supported fields and values, use the
285[`requirements.toml` reference](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml).
286To disable a capability rather than restrict individual sites or apps, see
287[Pin feature flags](#pin-feature-flags).
131 288
132289Within a given policy, the order from highest to lowest is OS-specific environment override → all-OS environment override → Global. A higher-priority policy still wins over a lower-priority policy, even when the lower-priority policy is more specific. Some requirements have field-specific merge rules. The runtime then enforces the resolved requirements. Consider the field-specific network cases below separately from policy priority.### Other desktop controls
133 290
134291These examples compare environment and Global settings within the same policy, with managed networking already configured and no higher-priority policy changing the values. They describe field-specific merge and runtime behavior.The following desktop controls cover feature availability, Locked Use, Appshots, and device remote control. Use dedicated settings for feature availability and Locked Use; configure Appshots and device remote control with **Edit as TOML**. For destination restrictions on desktop-app traffic, see [Control desktop app network destinations](#control-desktop-app-network-destinations).
135 292
136293#### Set different domain access by environment#### Pin feature flags
137 294
138295For the same domain rule within a policy, an admin environment override can allow a domain denied in Global or deny a domain allowed in Global. Without an environment override, the Global rule is inherited. Other effective Deny rules or access controls can still block a request.For desktop features exposed in Agent security, open **Global** > **Requirements** > **Desktop feature availability**. Set **In-app browser**, **Browser use**,
296**External browser use**, or **Computer use** to **Force off** to disable that
297capability, then select **Save changes**. For **Full CDP access**, choose
298**Block user opt-in** to prevent users from enabling it. Allowing a feature doesn't override its product, platform, or rollout availability.
139 299
140300**How domain rules combine**For other supported [feature flags](https://learn.chatgpt.com/docs/config-file/config-basic#feature-flags),
301use **Edit as TOML** and the Global `requirements.toml` document, or a supported
302local requirements source. The following examples include both runtime and
303desktop-specific feature pins:
141 304
142305| Global rule | Environment rule | Domain-policy result |```toml
143306| ------------- | ---------------- | --------------------------------------------------------------------- |[features]
144307| Deny | Allow | Allowed by the environment override, subject to the conditions below. |hooks = true
145308| Allow | Deny | Blocked in that environment. |unified_exec = false
146| Allow | Allow | Allowed by these domain rules. |
147| Deny | Deny | Blocked by these domain rules. |
148| Allow or Deny | No override | Inherits the Global rule. |
149 309
150310These outcomes compare the same domain key within one policy, with no higher-priority policy changing the result. A higher-priority value replaces the same key. Other inherited keys remain. An Allow does not bypass a different matching Deny, such as an inherited wildcard. An empty environment map does not clear inherited rules.# Disable surface-specific features when needed.
311browser_use = false
312browser_use_full_cdp_access = false
313browser_use_external = false
314in_app_browser = false
315in_app_updates = false
316computer_use = false
317```
151 318
152319**Example:** Deny `packages.example.com` in Global and allow it in Development. Development can permit it under the conditions above. Production inherits the Global Deny unless overridden.Use the canonical feature keys from `config.toml`'s `[features]` table for
320runtime features. The local runtime normalizes recognized features to meet these
321pins and rejects conflicting writes to `config.toml` or profile file feature
322settings.
153 323
154324Confirm the deployed executor supports these merge rules. Coverage for regular managed executors still needs validation.A managed `unified_exec = false` keeps command execution available, but disables
325resumable processes and the `write_stdin` tool. User configuration can't disable
326this feature.
155 327
156328Orchestrator limits. Managed HTTP/SOCKS listener ports and non-loopback proxy listeners are unsupported by the cloud runtime; socket-rule support depends on the execution path. A local-execution setting in the table below is not a supported Orchestrator configuration.<a id="disable-codex-feature-surfaces"></a>
157 329
158330#### Other network runtime limits- `in_app_browser = false` disables the built-in browser pane.
331- `in_app_updates = false` disables the ChatGPT desktop app's own updater on
332 restart, where supported. It doesn't affect external package deployment or
333 extend support for older app versions. For setup and rollout guidance, see
334 [Manage app updates](https://learn.chatgpt.com/docs/enterprise/manage-app-updates).
335- `browser_use = false` disables supported Browser Use capabilities. External
336 Browser Use and native-app Computer Use have separate controls.
337- `browser_use_full_cdp_access = false` disables full CDP access in the local
338 runtime, including Browser Developer mode, and prevents the ChatGPT desktop
339 app from enabling the corresponding setting.
340- `browser_use_external = false` disables agent-driven Browser Use through
341 supported browser extensions.
342- `computer_use = false` disables native-app Computer Use, including operating
343 a browser as a native app, along with Record & Replay and related install or
344 setup flows.
345
346**Disabling Browser Use alone does not block every browser path.** Native-app
347Computer Use can still operate a browser when that capability and app access are
348allowed; Browser Use site and capability rules do not apply to that path. To
349block it, set **Computer use** to **Force off** (`computer_use = false`), or
350[deny the browser app in App rules](#configure-native-app-access) if other native
351apps should remain available. Review **External browser use** and **In-app
352browser** separately. See [browser sessions and existing
353sign-ins](https://learn.chatgpt.com/docs/enterprise/chatgpt-work-local-security#browser-sessions-and-existing-sign-ins)
354for the controls that apply to each path.
159 355
160356All field names below are under `experimental_network` in `requirements.toml`. The arrows show a Global value followed by an environment value within the same policy. These local-execution cases do not establish Orchestrator support for the same settings.If you omit these keys, policy allows the features, subject to normal client,
357platform, and rollout availability.
161 358
162359| **Setting and attempted override** | **Runtime behavior** | **Admin action** |#### Restrict locked computer use
163| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
164| domains: deny → allow | The environment Allow replaces the same Global domain key on supported paths. Other matching Deny rules still apply. | Test both allowed and blocked requests on the deployed executor. |
165| `managed_allowed_domains_only`: true → false | Do not infer exclusivity behavior from domain-key composition. With effective `enabled = true` and `managed_allowed_domains_only = true`, ordinary commands need effective Allow entries. | Review effective settings and inherited Allow entries. A deny-only policy does not allow the rest of the internet. |
166| `allow_local_binding`: false → true | On the supported Codex Cloud proxy path, an explicit false can prevent upstream-proxy access. A supported higher-priority Cloud override can change it. | Check the source of the effective value and executor support. Do not apply the Cloud default to Local. |
167 360
168361Proxy activation, exclusivity, upstream-proxy behavior, and Unix-socket rules have executor-specific behavior. Do not generalize domain-key composition to these settings. Verify the effective values and test the deployed runtime. For Codex Cloud local/private connectivity, see [Configure network access requirements](#configure-network-access-requirements).To prevent users from enabling [Locked Use](https://learn.chatgpt.com/docs/computer-use#locked-use)
362on a managed Mac, open **Global** > **Requirements** > **Desktop app controls**,
363set **Allow use while locked** to **Disabled**, and select **Save changes**.
364This setting doesn't turn off Locked Use on a Mac where it's already enabled.
169 365
170366#### Verify behavior before rolloutThe equivalent requirement for the TOML editor or device-managed delivery is:
171 367
172368Test the actual destinations, local listeners, proxy behavior, and socket paths your workflows use. Check an action that should succeed and one that should be blocked in each affected environment. Check that the deployed runtime version supports each setting you use.```toml
369[computer_use]
370allow_locked_computer_use = false
371```
173 372
174373### Cloud-managed requirementsThis requirement removes the controls for enabling Locked Use. It doesn't
374turn off Locked Use if it's already enabled. If you omit it, normal product
375availability and the user's local setting still apply.
175 376
176377When a user signs in with ChatGPT on a supported plan, supported local clients#### Disable Appshots
177can receive admin-enforced requirements associated with the workspace. This is
178a delivery channel for `requirements.toml`-compatible policy. It doesn't grant
179workspace access or replace workspace RBAC. Authentication requirements must be
180[managed locally](#manage-authentication-locally).
181 378
182379Open **Agent Security** in the Admin Console to review and manage cloudAppshots let supported clients include application snapshots. To disable them
183380requirements. Use the migrated global baseline for existing policies. Forfor cloud-managed users, open **Edit as TOML** in Agent security and set the
184381example, this policy limitstop-level `allow_appshots` field in Global `requirements.toml`. For device-managed
185382approval and sandbox choices and prompts before a supported shell entry pointdeployments, use the applicable local requirements source:
186runs:
187 383
188```toml384```toml
189385allowed_approval_policies = ["on-request"]allow_appshots = false
190allowed_sandbox_modes = ["read-only", "workspace-write"]
191
192[rules]
193prefix_rules = [
194 { pattern = [{ any_of = ["bash", "sh", "zsh"] }], decision = "prompt", justification = "Require explicit approval for shell entry points" },
195]
196```386```
197 387
198388Check that every managed client version supports the keys you select. Assign the policy to the intended users or groups and verify that it takes effect on their supported clients. UseWhere Appshots are available, `allow_appshots = false` disables them. If you
199389the configuration reference for the current schema and the administrationomit the key, requirements don't constrain Appshots, and normal product
200390surface for current assignment behavior.availability checks apply. App-server clients that read effective requirements
391through `configRequirements/read` receive the same restriction as
392`allowAppshots`; an omitted or `null` `allowAppshots` value doesn't disable
393Appshots.
201 394
202395The service selects the enterprise-managed requirement layers that apply to the#### Disable device remote control
203signed-in identity. The local client evaluates those layers with the other
204requirements sources described in [Locations and precedence](#locations-and-precedence).
205Use the current administration surface for workspace-side creation and
206assignment. Don't rely on a copied group-matching algorithm; the administration
207service owns that behavior and can change it independently of the local
208requirements format.
209 396
210397For supported keys and examples, seeTo disable [device remote control](https://learn.chatgpt.com/docs/remote-connections#pick-up-work-from-another-device)
211398[Example requirements.toml](#example-requirementstoml) and thefor cloud-managed users, use **Edit as TOML** in Agent security and set the
212399[`requirements.toml` reference](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml).top-level `allow_remote_control` field in Global `requirements.toml`. You can
400also set `allow_remote_control` in a supported local requirements source:
213 401
214402#### How local clients apply cloud-managed requirements```toml
403allow_remote_control = false
404```
215 405
216406The local loading and cache behavior below describes supported local clients. It does not establish when a changed cloud policy takes effect in an already-running task using Local computer access with Work Cloud. Verify the effective policy before relying on a changed restriction.Where device remote control is supported, `allow_remote_control = false`
407disables it. If you omit the key, requirements don't constrain device remote
408control, and normal product availability checks apply. This requirement doesn't
409disable SSH remote connections.
217 410
218411When a user starts a supported local client and signs in with ChatGPT on a## Set approvals and execution permissions
219supported plan, the client first checks for a valid, identity-matched cache
220entry. If no valid entry is available, the client fetches the applicable bundle
221with retries and writes a signed cache entry on success. If the request fails or
222times out and no valid cache is available, the cloud config bundle load returns
223an error rather than silently starting without the cloud-managed requirements
224layer.
225 412
226413After cache resolution, the client composes the cloud requirements with theUse this section to set approval behavior, permission boundaries, and starting defaults. Begin with [Policy guardrails](#set-approval-sandbox-and-web-search-guardrails) and [Defaults](#set-configuration-defaults). The later tasks explain TOML requirements for reviewer enforcement, custom permission profiles, filesystem restrictions, host overrides, and command rules.
227other requirements layers described above. A background refresh can update the
228cache for a later start; it doesn't replace the requirements already loaded
229into the current process.
230 414
231415### Confirm the admin and employee experience### Admin-enforced requirements (requirements.toml)
232 416
233417Assign a person to own each managed policy, record which users or groups shouldRequirements constrain security-sensitive settings (approval policy, approvals reviewer, automatic review policy, sandbox mode, permission profiles, web search mode, managed hooks, which MCP servers users can enable, and which plugin marketplace sources they can use). When resolving configuration (for example from `config.toml`, [profile files](https://learn.chatgpt.com/docs/config-file/config-advanced#profiles), or CLI config overrides), if a value conflicts with an enforced rule, the local client falls back to a compatible value and notifies the user. If you configure an `mcp_servers` allowlist, the client enables an MCP server only when both its name and identity match an approved entry; otherwise, the client disables it.
234receive it, and document the business reason for any filesystem, network,
235approval, or permission-profile restriction.
236 418
237419Test an allowed workflow and a blocked workflow with a user who has the intended permissions. Check the effective settings in the supported client. A workspace role or group alone does not enforce a local runtime restriction.Requirements can also constrain [feature flags](https://learn.chatgpt.com/docs/config-file/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.
238 420
239421### Manage authentication locallyFor Codex 0.138.0 or later, prefer [permission profiles](https://learn.chatgpt.com/docs/permissions)
422with `allowed_permission_profiles` and managed `default_permissions`. Use
423`allowed_sandbox_modes` only for legacy deployments that still configure
424`sandbox_mode`.
240 425
241426Set `allowed_login_methods`, `allowed_chatgpt_workspaces`,For the exact key list, see the [`requirements.toml` section in Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml).
242`cli_auth_credentials_store`, and `chatgpt_base_url` in the local system
243`requirements.toml` or macOS MDM requirements. Codex ignores these four fields
244in cloud-managed requirements. Local authentication requirements apply before
245credentials load and before Codex retrieves cloud policy.
246 427
247428To require ChatGPT login to an approved workspace and store credentials in the### Set approval, sandbox, and web search guardrails
248429OS credential store, use:
430Use **Requirements** > **Policy guardrails** to limit supported client choices.
431These controls constrain configuration; they don't select the starting value.
432Set the starting value separately under **Defaults**.
433
4341. In **Global**, open **Approval policies** and select the allowed approval
435 styles. For example, **Ask when needed** allows the agent to request approval
436 for actions such as sandbox escalation. **Never ask** prevents approval
437 requests; it doesn't grant unrestricted execution.
4381. Open **Sandbox modes** to limit legacy sandbox choices. **Read-only** restricts
439 writes, **Workspace write** permits writes within the workspace and configured
440 writable roots, and **Full access** removes filesystem sandboxing. Use
441 [permission-profile requirements](#control-available-permission-profiles) for
442 deployments that use permission profiles instead of `sandbox_mode`.
4431. In **Global**, open **Web search modes** to limit web search. Choose **Cached**
444 to permit cached search without live search, or **Disabled** to turn off web
445 search. Web search restrictions are separate from command network rules.
4461. Review the allowed choices and corresponding defaults, then select
447 **Save changes**.
448
449Leaving a requirement unset imposes no limit under that policy. Other
450applicable policies still apply. The **Ask for untrusted commands** option
451corresponds to `untrusted` in the requirements allowlist; it doesn't restore the
452retired explicit `approval_policy = "untrusted"` setting. Follow the migration
453guidance below for that case.
454
455To constrain web search, use **Global** > **Requirements** > **Policy guardrails** > **Web search modes**. The equivalent TOML is:
249 456
250```toml457```toml
251458allowed_login_methods = ["chatgpt"]allowed_web_search_modes = ["cached"] # "disabled" remains implicitly allowed
252allowed_chatgpt_workspaces = ["00000000-0000-0000-0000-000000000000"]
253cli_auth_credentials_store = "keyring"
254```459```
255 460
256461`allowed_login_methods` accepts `chatgpt`, `api`, or both. If omitted, this setting`allowed_web_search_modes = []` allows only `"disabled"`.
257462doesn't restrict login methods. If set, the list must contain at least one method.For example, `allowed_web_search_modes = ["cached"]` prevents live web search even in `danger-full-access` sessions.
258`api` permits API authentication, including Amazon Bedrock.
259The workspace restriction also applies to
260[Codex access tokens](https://learn.chatgpt.com/docs/enterprise/access-tokens).
261 463
262464User-configured `forced_login_method` and `forced_chatgpt_workspace_id` must### Set configuration defaults
263follow the requirements. When a user selects a workspace, it must also appear
264in the managed workspace allowlist. If no workspaces match, ChatGPT login is
265unavailable. API authentication remains available when permitted. If no login method
266is available, Codex refuses to start.
267 465
268466See the [requirements reference](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml)Defaults give members a starting configuration. They don't enforce a
269467for credential storage modes and service URL configuration.restriction or grant access to a workspace capability.
468
4691. Open the policy's **Defaults** card. Keep agent-wide defaults in **Global**;
470 use an available environment tab for supported execution defaults.
4711. Under **Command execution**, choose the starting **Approval policy** and
472 **Approval reviewer**, and the applicable **Sandbox mode** or **Default
473 permissions**. The reviewer determines who reviews approval requests by
474 default; the approval policy determines when requests can occur.
4751. Under **Web search**, choose the starting **Web search** mode and **Web search
476 context**. Under **Apps and tools**, review **Apps/connectors**, **Open-world
477 tools**, and **Destructive tools** for supported app tools.
4781. Confirm the defaults meet your **Requirements**, then select **Save changes**.
479
480Use **Edit as TOML** for supported defaults without visual controls, such as
481plugin marketplace configuration. These cloud defaults use [normal configuration
482precedence](https://learn.chatgpt.com/docs/config-file/config-basic#configuration-precedence). They differ
483from the [legacy `managed_config.toml` precedence](#precedence-and-layering),
484which places managed defaults above local configuration at startup.
270 485
271### Example requirements.toml486### Example requirements.toml
272 487
281`trust_level = "untrusted"`; it does not make `approval_policy = "untrusted"` a496`trust_level = "untrusted"`; it does not make `approval_policy = "untrusted"` a
282supported explicit setting.497supported explicit setting.
283 498
284499### Disable Appshots### Migrate the retired `untrusted` approval policy
285 500
286501To disable Appshots for managed users, set the top-level `allow_appshots` requirement:Codex and ChatGPT Work no longer support `approval_policy = "untrusted"`.
502Remove it from managed defaults, legacy `managed_config.toml`, and any user,
503project, profile, or startup configuration that sets it.
287 504
288505```tomlFor interactive, read-only use, select `approval_policy = "on-request"` with a
289506allow_appshots = falseread-only sandbox or permission profile allowed by your managed requirements.
290507```Commands allowed by that sandbox can run without approval.
291 508
292509Where Appshots are available, `allow_appshots = false` disables them. If youTo keep stricter command approvals, omit an explicit `approval_policy`, set
293510omit the key, requirements don't constrain Appshots, and normal product`trust_level = "untrusted"` in the project's entry in user-level
294511availability checks apply. App-server clients that read effective requirements`~/.codex/config.toml`, and keep `untrusted` in `allowed_approval_policies`.
295512through `configRequirements/read` receive the same restriction asThis also disables project-local configuration. Setting `on-request` explicitly
296513`allowAppshots`; an omitted or `null` `allowAppshots` value doesn't disableoverrides that policy. See
297514Appshots.[Migrate from the retired `untrusted` approval policy](https://learn.chatgpt.com/docs/agent-approvals-security#migrate-from-the-retired-untrusted-approval-policy)
515for examples and security tradeoffs.
298 516
299517### Disable device remote control### Configure automatic review policy
300 518
301519To disable [device remote control](https://learn.chatgpt.com/docs/remote-connections#pick-up-work-from-another-device)To make automatic review the default, use **Global** > **Defaults** > **Command execution** > **Approval reviewer**. A default lets users choose
302520for managed users, set the top-level `allow_remote_control` requirement:another permitted reviewer. To require automatic review or supply your
521organization's review instructions, use **Edit as TOML** and edit Global
522`requirements.toml` instead. These requirements are separate from the browser's
523automatic-review controls.
524
525Use `allowed_approvals_reviewers` to require or allow automatic review. Set it
526to `["auto_review"]` to require automatic review, or include `"user"` when users
527can choose manual approval.
528
529Set `guardian_policy_config` to replace the tenant-specific section of the
530automatic review policy. The local runtime still uses the built-in reviewer
531template and output contract. Managed `guardian_policy_config` takes precedence
532over local `[auto_review].policy`.
303 533
304```toml534```toml
305535allow_remote_control = falseallowed_approval_policies = ["on-request"]
306536```allowed_approvals_reviewers = ["auto_review"]
307 537
308538Where device remote control is supported, `allow_remote_control = false`guardian_policy_config = """
309539disables it. If you omit the key, requirements don't constrain device remote## Environment Profile
310540control, and normal product availability checks apply. This requirement doesn't- Trusted internal destinations include github.com/my-org, artifacts.example.com,
311541disable SSH remote connections. and internal CI systems.
542
543## Tenant Risk Taxonomy and Allow/Deny Rules
544- Treat uploads to unapproved third-party file-sharing services as high risk.
545- Deny actions that expose credentials or private source code to untrusted
546 destinations.
547"""
548```
312 549
313### Control available permission profiles550### Control available permission profiles
314 551
552Use **Defaults** > **Command execution** > **Default permissions** to choose the built-in profile users start with. To enforce which profiles users can select or to define
553custom profiles, use **Edit as TOML** and configure `requirements.toml` for the
554applicable Global or supported execution environment scope. Choosing a default
555alone doesn't restrict the available profiles.
556
315Use `allowed_permission_profiles` to control which built-in and custom557Use `allowed_permission_profiles` to control which built-in and custom
316[permission profiles](https://learn.chatgpt.com/docs/permissions) users can select. This is the558[permission profiles](https://learn.chatgpt.com/docs/permissions) users can select. This is the
317permission-profile counterpart to `allowed_sandbox_modes`; use the allowlist that559permission-profile counterpart to `allowed_sandbox_modes`; use the allowlist that
425a loaded config or requirements source. Define custom profiles in managed667a loaded config or requirements source. Define custom profiles in managed
426requirements to control their behavior centrally.668requirements to control their behavior centrally.
427 669
670### Enforce deny-read requirements
671
672Use **Edit as TOML** to add filesystem restrictions to the applicable Global or
673supported execution environment `requirements.toml`. These restrictions block
674reads of sensitive paths; a read-only default by itself doesn't hide files.
675
676Admins can deny reads for exact paths or glob patterns with
677`[permissions.filesystem]`. Users can't weaken these requirements with local
678configuration.
679
680```toml
681[permissions.filesystem]
682deny_read = [
683 # values can be absolute paths...
684 "/**/*.env",
685 # ...or relative to $HOME/%USERPROFILE% using `~`.
686 "~/.ssh",
687 # But relative paths starting with `./` are not allowed.
688]
689```
690
691When deny-read requirements are present, the local runtime rejects full-access
692permissions and keeps local execution in a read-only or workspace sandbox so it
693can enforce them. On native Windows, managed `deny_read` applies to direct file
694tools; shell subprocess reads don't use this sandbox rule.
695
428### Override sandbox requirements by host696### Override sandbox requirements by host
429 697
698Use **Edit as TOML** in Agent security to author host-specific requirements.
699Environment controls select an execution environment; host patterns select
700matching machines within the supported runtime.
701
430Use `[[remote_sandbox_config]]` when one managed policy should apply different702Use `[[remote_sandbox_config]]` when one managed policy should apply different
431sandbox requirements on different hosts. For example, you can keep a stricter703sandbox requirements on different hosts. For example, you can keep a stricter
432default for laptops while allowing workspace writes on matching dev boxes or CI704default for laptops while allowing workspace writes on matching dev boxes or CI
450`allowed_sandbox_modes`. Host name matching is for policy selection only; don't722`allowed_sandbox_modes`. Host name matching is for policy selection only; don't
451treat it as authenticated device proof.723treat it as authenticated device proof.
452 724
453725You can also constrain web search mode:### Enforce command rules from requirements
726
727Use **Edit as TOML** in Agent security to add command rules and MCP server
728restrictions to Global `requirements.toml`. Command rules specify approval or denial
729decisions for matching commands; MCP restrictions limit which server identities
730the client can enable. The **Approval policies** control doesn't author either
731of these rule sets.
732
733Admins can also enforce restrictive command rules from `requirements.toml`
734using a `[rules]` table. These rules merge with regular `.rules` files, and the
735most restrictive decision still wins.
736
737Unlike `.rules`, requirements rules must specify `decision`, and that decision
738must be `"prompt"` or `"forbidden"` (not `"allow"`).
454 739
455```toml740```toml
456741allowed_web_search_modes = ["cached"] # "disabled" remains implicitly allowed[rules]
742prefix_rules = [
743 { pattern = [{ token = "rm" }], decision = "forbidden", justification = "Use git clean -fd instead." },
744 { pattern = [{ token = "git" }, { any_of = ["push", "commit"] }], decision = "prompt", justification = "Require review before mutating history." },
745]
457```746```
458 747
459748`allowed_web_search_modes = []` allows only `"disabled"`.To restrict which MCP servers a local client can enable, add an `mcp_servers`
460749For example, `allowed_web_search_modes = ["cached"]` prevents live web search even in `danger-full-access` sessions.approved list. For stdio servers, match on `command`; for streamable HTTP
750servers, match on `url`:
751
752```toml
753[mcp_servers.docs]
754identity = { command = "codex-mcp" }
755
756[mcp_servers.remote]
757identity = { url = "https://example.com/mcp" }
758```
759
760The string form of `identity.command` matches only the configured `command`. It
761doesn't inspect `args`, `cwd`, `env`, or `env_vars`.
762
763To constrain a complete stdio invocation, match the executable and each
764positional argument:
765
766```toml
767[mcp_servers.internal.identity]
768command = { executable = "/usr/local/bin/codex-mcp", args = [
769 { match = "exact", value = "serve" },
770 { match = "prefix", value = "--workspace=" },
771] }
772```
773
774The executable, argument count, and argument order must match. Argument and URL
775rules support `exact`, `prefix`, and full-value `regex` matching. Structured
776command rules still don't inspect `cwd`, `env`, or `env_vars`. Plugin-bundled
777MCP servers use the same identity shapes under
778`plugins.<plugin>.mcp_servers.<server>`.
779
780If `mcp_servers` is present but empty, the local client disables all MCP servers.
781
782## Configure network access
783
784Command networking and desktop-app networking use different controls. Start with **Network use controls** for supported command traffic, review the environment and runtime limits, then use the separate desktop-app requirements if needed. Browser site rules remain in [Control browser and Computer Use](#control-browser-and-computer-use).
461 785
462### Configure network access requirements786### Configure network access requirements
463 787
469 you have tested it in your environment.793 you have tested it in your environment.
470</WarningTip>794</WarningTip>
471 795
796Use **Requirements** > **Network use controls** to manage supported command
797networking in Agent security. Configure a shared baseline in **Global**, or an
798available **Local Environments** or **Codex Cloud Environments** tab for
799environment-specific execution settings.
800
8011. Set **Managed networking** to **On** to apply domain rules to managed command
802 traffic. Adding domain rules alone doesn't activate the managed proxy.
8031. Under **Network rules**, select **Add network rule**. Enter a **Domain** such
804 as `api.openai.com` or `**.example.com`, without a URL scheme or path. Choose
805 **Allow** or **Deny** under **Access**, then select **Save rule** to update the
806 draft. Repeat for other destinations.
8071. Set **Only allow domains added by admins** to **On** if user settings and
808 per-domain approvals must not expand the managed allowlist. Include the
809 required Allow entries; a deny-only list doesn't allow other destinations.
8101. Review **Allow local network access** for workflows that need local listeners
811 or private destinations. Direct local connections may bypass the proxy's
812 domain rules. Review the Codex Cloud connectivity limits below before changing
813 this setting.
8141. Review inherited rules and validation messages, then select **Save changes**.
815 Test a request that should succeed and one that should be blocked in every
816 affected execution environment.
817
818Setting **Managed networking** to **Off** clears that scope's authored network
819rules and stores an explicit off value; it doesn't disable internet access.
820**Not set** removes that scope's authored network settings so applicable policy
821or runtime defaults can apply. Removing environment settings can reveal inherited
822Global rules. Use **Edit as TOML** for advanced network fields or existing legacy
823domain lists that the visual editor can't represent.
824
472Use `[experimental_network]` in `requirements.toml` when administrators should825Use `[experimental_network]` in `requirements.toml` when administrators should
473define network access requirements centrally. These requirements are separate826define network access requirements centrally. These requirements are separate
474from the user `features.network_proxy` toggle: they can configure sandbox827from the user `features.network_proxy` toggle: they can configure sandbox
525 878
526A managed command allowlist applies to commands using the managed proxy. Where policy permits full sandbox escalation and it is approved, that execution can bypass the command proxy. A narrow network grant is different from full sandbox escalation. Configure enforced approval and sandbox requirements for the intended boundary, and test both ordinary and escalated commands.879A managed command allowlist applies to commands using the managed proxy. Where policy permits full sandbox escalation and it is approved, that execution can bypass the command proxy. A narrow network grant is different from full sandbox escalation. Configure enforced approval and sandbox requirements for the intended boundary, and test both ordinary and escalated commands.
527 880
528881> **No effective allowed destinations:** When **Manage Networking** and **Only allow domains added by admins** are On, ordinary managed commands need effective allowed destinations. If no Allow entries are configured or inherited, those commands have no allowed destinations. A deny-only policy does not implicitly allow the rest of the internet. Add required Allow entries and check inherited rules before saving. This restriction applies to the managed command proxy, not every tool or approved full sandbox escalation.> **No effective allowed destinations:** When **Managed networking** and **Only allow domains added by admins** are On, ordinary managed commands need effective allowed destinations. If no Allow entries are configured or inherited, those commands have no allowed destinations. A deny-only policy does not implicitly allow the rest of the internet. Add required Allow entries and check inherited rules before saving. This restriction applies to the managed command proxy, not every tool or approved full sandbox escalation.
529 882
530> **Codex Cloud local/private connectivity:** An explicit Off value for local/private connectivity can prevent Codex Cloud from reaching its upstream proxy, even when the destination domain is allowed. Check the final `allow_local_binding` value and identify which policy or setting supplies it. On the supported Cloud proxy path, this defaults to true only when no applicable requirement, selected network profile, or proxy feature setting supplies a value. An inherited false still counts as an explicit setting. Where supported, set a higher-priority Cloud override to change this value for Codex Cloud without changing the Global value used by Local. This does not add domain Allow entries. Verify executor support before relying on the override. Do not apply this Cloud default to Local.883> **Codex Cloud local/private connectivity:** An explicit Off value for local/private connectivity can prevent Codex Cloud from reaching its upstream proxy, even when the destination domain is allowed. Check the final `allow_local_binding` value and identify which policy or setting supplies it. On the supported Cloud proxy path, this defaults to true only when no applicable requirement, selected network profile, or proxy feature setting supplies a value. An inherited false still counts as an explicit setting. Where supported, set a higher-priority Cloud override to change this value for Codex Cloud without changing the Global value used by Local. This does not add domain Allow entries. Verify executor support before relying on the override. Do not apply this Cloud default to Local.
531 884
532885Empty environment requirements inherit Global. Manage Networking Off is not the Cloud environment Internet access Off switch. See [Configure networking in the UI](https://learn.chatgpt.com/docs/enterprise/agent-security#configure-networking-in-the-ui).When environment requirements are empty, Global requirements apply. **Managed networking** set to
886**Off** is separate from the Cloud environment's Internet access setting. See
887[Agent Security execution controls](https://learn.chatgpt.com/docs/enterprise/agent-security#execution-controls-executor)
888for details about execution scope.
889
890### Network policy precedence and runtime limits
891
892Within a given policy, the order from highest to lowest is OS-specific environment override → all-OS environment override → Global. A higher-priority policy still wins over a lower-priority policy, even when the lower-priority policy is more specific. Some requirements have field-specific merge rules. The runtime then enforces the resolved requirements. Consider the field-specific network cases below separately from policy priority.
893
894These examples compare environment and Global settings within the same policy, with managed networking already configured and no higher-priority policy changing the values. They describe field-specific merge and runtime behavior.
895
896#### Set different domain access by environment
897
898For the same domain rule within a policy, an admin environment override can allow a domain denied in Global or deny a domain allowed in Global. Without an environment override, the Global rule is inherited. Other effective Deny rules or access controls can still block a request.
899
900**How domain rules combine**
901
902| Global rule | Environment rule | Domain-policy result |
903| ------------- | ---------------- | --------------------------------------------------------------------- |
904| Deny | Allow | Allowed by the environment override, subject to the conditions below. |
905| Allow | Deny | Blocked in that environment. |
906| Allow | Allow | Allowed by these domain rules. |
907| Deny | Deny | Blocked by these domain rules. |
908| Allow or Deny | No override | Inherits the Global rule. |
909
910These outcomes compare the same domain key within one policy, with no higher-priority policy changing the result. A higher-priority value replaces the same key. Other inherited keys remain. An Allow does not bypass a different matching Deny, such as an inherited wildcard. An empty environment map does not clear inherited rules.
911
912**Example:** Deny `packages.example.com` in Global and allow it in Development. Development can permit it under the conditions above. Production inherits the Global Deny unless overridden.
913
914Confirm the deployed executor supports these merge rules. Coverage for regular managed executors still needs validation.
915
916Orchestrator limits. Managed HTTP/SOCKS listener ports and non-loopback proxy listeners are unsupported by the cloud runtime; socket-rule support depends on the execution path. A local-execution setting in the table below is not a supported Orchestrator configuration.
917
918#### Other network runtime limits
919
920All field names below are under `experimental_network` in `requirements.toml`. The arrows show a Global value followed by an environment value within the same policy. These local-execution cases do not establish Orchestrator support for the same settings.
921
922| **Setting and attempted override** | **Runtime behavior** | **Admin action** |
923| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
924| domains: deny → allow | The environment Allow replaces the same Global domain key on supported paths. Other matching Deny rules still apply. | Test both allowed and blocked requests on the deployed executor. |
925| `managed_allowed_domains_only`: true → false | Do not infer exclusivity behavior from domain-key composition. With effective `enabled = true` and `managed_allowed_domains_only = true`, ordinary commands need effective Allow entries. | Review effective settings and inherited Allow entries. A deny-only policy does not allow the rest of the internet. |
926| `allow_local_binding`: false → true | On the supported Codex Cloud proxy path, an explicit false can prevent upstream-proxy access. A supported higher-priority Cloud override can change it. | Check the source of the effective value and executor support. Do not apply the Cloud default to Local. |
927
928Proxy activation, exclusivity, upstream-proxy behavior, and Unix-socket rules have executor-specific behavior. Do not generalize domain-key composition to these settings. Verify the effective values and test the deployed runtime. For Codex Cloud local/private connectivity, see [Configure network access requirements](#configure-network-access-requirements).
929
930#### Verify behavior before rollout
931
932Test the actual destinations, local listeners, proxy behavior, and socket paths your workflows use. Check an action that should succeed and one that should be blocked in each affected environment. Check that the deployed runtime version supports each setting you use.
533 933
534### Control desktop app network destinations934### Control desktop app network destinations
535 935
936Use **Edit as TOML** in Agent security to configure these desktop-specific
937requirements in Global. The **Network use controls** UI manages command
938networking, which is a separate policy.
939
536Use `[application.network]` in `requirements.toml` to restrict the desktop940Use `[application.network]` in `requirements.toml` to restrict the desktop
537app's network destinations. With `enabled = true`, external requests must use941app's network destinations. With `enabled = true`, external requests must use
538HTTPS or WSS and match an exact domain with an `"allow"` value in942HTTPS or WSS and match an exact domain with an `"allow"` value in
544doesn't impose destination restrictions on native modules or spawned processes,948doesn't impose destination restrictions on native modules or spawned processes,
545and it doesn't govern Work Cloud execution.949and it doesn't govern Work Cloud execution.
546 950
547951### Control browser and Computer Use## Configure plugins and managed hooks
548 952
549953Use the `[browser_use]` and `[computer_use]` tables in `requirements.toml` toFor these tasks, use **Edit as TOML** in Agent security or a supported local configuration source. Marketplace defaults, enforced plugin restrictions, and managed hooks have different purposes; choose the task that matches the policy you need.
550restrict supported desktop clients. Validate the policy on the client versions
551and operating systems in your deployment. A configured allow rule doesn't
552install a plugin, grant an operating-system permission, or approve an action
553that still requires review.
554 954
555955For browser access, configure an origin policy. An origin includes the scheme,### Configure plugin marketplaces and defaults
556host, and optional port, such as `https://example.com` or
557`https://*.example.com:8443`. Don't include a path, query, or fragment. Unlike
558command-network domain rules, browser origin rules distinguish HTTP from HTTPS
559and match the port.
560 956
561957This example restricts browser access to an approved site and prevents uploadsUse **Agent security** > **Edit as TOML** to define local or Git marketplaces and
562958and full Chrome DevTools Protocol (CDP) access there:plugin defaults in the Global `config.toml` document. You can also distribute
959these settings in system `config.toml`. They provide starting marketplace and
960plugin configuration, not enforced policy. To limit which sources members can
961use, configure [marketplace source requirements](#restrict-plugin-marketplace-sources).
563 962
564963```tomlSee [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference) for configuration keys,
565964[browser_use][Configuration precedence](https://learn.chatgpt.com/docs/config-file/config-basic#configuration-precedence)
566965allow_history_access = falsefor overrides, and [repo plugin settings](https://developers.openai.com/plugins/build/plugins#enable-or-disable-a-plugin-for-a-repo)
567966allow_global_persistent_approval = falsefor project-level configuration. [Workspace GitHub import and
967sync](https://learn.chatgpt.com/docs/enterprise/plugin-management) is separate.
568 968
569969[browser_use.default_origin_policy]### Control plugin availability
570access = "deny"
571 970
572971[browser_use.origins."https://example.com"]Use **Edit as TOML** in Agent security for enforced plugin feature settings in
573972access = "allow"Global `requirements.toml`, or distribute them through local requirements for
574973uploads = "deny"device-managed clients. **Defaults** > **Apps and tools** > **Apps/connectors**
575974downloads = "allow"sets app-tool defaults; it isn't the enforced `features.plugins` switch. For
576975full_cdp_access = "deny"workspace plugin permissions, see [Apps and connectors](https://learn.chatgpt.com/docs/enterprise/apps-and-connectors).
577976persistent_approval = false
578977access_approval_lifetime = "turn"To turn off plugins in supported local clients, set `features.plugins` to
978`false` in `requirements.toml`:
979
980```toml
981features.plugins = false
579```982```
580 983
581984Matching origin rules are resolved per field. A matching deny wins. Otherwise,This setting also applies when users sign in to Codex with an API key. See the
582985the default origin policy supplies fields that matching rules don't specify.[`features.plugins`
583986Local configuration can add restrictions but can't relax a managed deny.reference](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml) for the
584987Network denies and exclusive managed network allowlists still apply.supported configuration.
585 988
586989Set `browser_use.disable_auto_review = true` to disable automatic approval### Restrict plugin marketplace sources
587review for browser actions, or set `auto_review = "deny"` on an origin policy
588to restrict it for that origin. This controls approval handling; it doesn't
589disable model safety monitoring.
590 990
591991To enable [Site tools](https://learn.chatgpt.com/docs/webmcp) for an eligible Enterprise workspace,Use **Edit as TOML** to configure marketplace source requirements in Global
592992set `browser_use.allow_webmcp = true`. This managed opt-in applies to the`requirements.toml`, or deliver them through local requirements. These rules
593993desktop app's built-in browser. Setting it to `false` or omitting it leaveslimit which local or Git sources users can add and use. They are separate from
594994normal feature availability checks in place; `false` does not enforce a block.the [marketplace defaults](#configure-plugin-marketplaces-and-defaults).
595User preferences and site permissions still apply.
596 995
597996For native apps, set a default access policy and identify permitted apps. ForTo restrict plugin marketplace sources, set
598997example, this macOS policy allows Calculator and prevents saved approvals:`restrict_to_allowed_sources = true` and define one or more source rules:
599 998
600```toml999```toml
6011000[computer_use][marketplaces]
6021001default_app_access = "deny"restrict_to_allowed_sources = true
603allow_persistent_approval = false
604 1002
6051003[computer_use.macos.bundle_ids][marketplaces.allowed_sources.company_plugins]
6061004"com.apple.calculator" = "allow"source = "git"
1005url = "https://github.com/example/company-plugins.git"
1006ref = "main"
1007
1008[marketplaces.allowed_sources.internal_git]
1009source = "host_pattern"
1010host_pattern = '^git\.example\.com$'
1011
1012[marketplaces.allowed_sources.local_plugins]
1013source = "local"
1014path = "/opt/company/codex-plugins"
1015```
1016
1017Git rules match the normalized repository URL and, when present, an exact
1018`ref`. Host patterns are regular expressions matched against the lowercase Git
1019host; use `^` and `$` for a whole-host match. Local rules require an absolute,
1020normalized path. See the [`requirements.toml` reference](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml)
1021for the full schema and merge behavior.
1022
1023These requirements reject unmatched marketplace add, plugin install, and
1024configured Git marketplace refresh operations. They also filter configured
1025marketplaces and their plugins at runtime.
1026
1027The OpenAI-curated Git marketplaces, including the API-key catalog, must also
1028match the source allowlist. To allow them, include the following Git source
1029without a `ref` constraint:
1030
1031```toml
1032[marketplaces.allowed_sources.openai_curated]
1033source = "git"
1034url = "https://github.com/openai/plugins.git"
607```1035```
608 1036
6091037Windows policies can identify packaged apps withTo exclude the curated catalogs, omit that source and ensure no broader host
6101038`computer_use.windows.aumids` or executables withrule allows it. Bundled plugins and remotely installed workspace plugins are
6111039`computer_use.windows.exes`. Executable rules require `publisher_name`,separate from this curated Git source policy.
6121040`product_name`, and `access`; `binary_name` is optional. Use the app's verified
6131041identity rather than its display name alone.These source restrictions apply only where a local client supports plugin
1042marketplace operations: ChatGPT and Codex in the desktop app, and Codex CLI.
1043They don't control plugin use in ChatGPT on the web or mobile, and they don't
1044add plugins to the IDE extension.
1045
1046### Enforce managed hooks from requirements
1047
1048Managed hooks run administrator-defined actions at supported task or tool
1049events. Use **Edit as TOML** in Agent security to configure them in Global
1050`requirements.toml`; the settings controls don't include a dedicated hook editor. The execution paths below determine which hook types can run.
614 1051
6151052See the [configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml)When managed policy and remote hooks are enabled, Work Cloud with local access and dots use admin-managed remote MCP hooks on the cloud orchestrator. Configure `mcp_tool` handlers in Global `requirements.toml`. Work Cloud without local access and personal accounts do not use these enterprise hooks. Command/shell, prompt, and agent handlers; hooks from local configuration, plugins, or local directories; environment-scoped hooks; and `SessionEnd` MCP hooks are not supported with cloud orchestration, even when tools execute locally. When both orchestration and execution are local, existing supported hooks continue to work in local-only Work and Codex threads. Admins can still configure supported managed hooks in Agent Security for those workflows.
6161053for the complete fields and [locked-use restrictions](#restrict-locked-computer-use)
6171054for managed macOS devices.Before relying on these hooks, test callback connectivity, required events, and failure behavior. An explicit supported denial can block an action, but a `PreToolUse` callback error, timeout, or malformed response can fail the hook without blocking the tool. MCP hooks do not provide a complete Compliance API audit trail. The following script and directory examples retain their Codex scope.
618 1055
6191056### Pin feature flagsAdmins can also define managed lifecycle hooks directly in `requirements.toml`.
1057Use `[hooks]` for the hook configuration itself, and point `managed_dir` at the
1058directory where your MDM or endpoint-management tooling installs the referenced
1059scripts.
620 1060
6211061You can also pin [feature flags](https://learn.chatgpt.com/docs/config-file/config-basic#feature-flags) for usersTo enforce managed hooks even for users who turned hooks off locally, pin
6221062receiving a managed `requirements.toml`:`[features].hooks = true` alongside `[hooks]`. To skip user, project, session,
1063and plugin hooks while still allowing managed hooks, set
1064`allow_managed_hooks_only = true`.
623 1065
624```toml1066```toml
1067allow_managed_hooks_only = true
1068
625[features]1069[features]
626hooks = true1070hooks = true
627unified_exec = false
628 1071
6291072# Disable surface-specific features when needed.[hooks]
6301073browser_use = falsemanaged_dir = "/enterprise/hooks"
6311074browser_use_full_cdp_access = falsewindows_managed_dir = 'C:\enterprise\hooks'
632browser_use_external = false
633in_app_browser = false
634in_app_updates = false
635computer_use = false
636```
637 1075
6381076Use the canonical feature keys from `config.toml`'s `[features]` table for[[hooks.PreToolUse]]
6391077runtime features. The local runtime normalizes recognized features to meet thesematcher = "^Bash$"
640pins and rejects conflicting writes to `config.toml` or profile file feature
641settings.
642 1078
6431079A managed `unified_exec = false` keeps command execution available, but disables[[hooks.PreToolUse.hooks]]
6441080resumable processes and the `write_stdin` tool. User configuration can't disabletype = "command"
6451081this feature.command = "python3 /enterprise/hooks/pre_tool_use_policy.py"
1082command_windows = 'py -3 C:\enterprise\hooks\pre_tool_use_policy.py'
1083timeout = 30
1084statusMessage = "Checking managed Bash command"
1085```
646 1086
6471087<a id="disable-codex-feature-surfaces"></a>Notes:
648 1088
6491089- `in_app_browser = false` disables the built-in browser pane.- The local runtime enforces the hook configuration from `requirements.toml`,
6501090- `in_app_updates = false` disables the ChatGPT desktop app's own updater on but it doesn't distribute the scripts in `managed_dir`.
6511091 restart, where supported. It doesn't affect external package deployment or- Deliver those scripts with your MDM or device-management solution.
6521092 extend support for older app versions. For setup and rollout guidance, see- Managed hook commands should reference absolute script paths under the
6531093 [Manage app updates](https://learn.chatgpt.com/docs/enterprise/manage-app-updates). configured managed directory.
6541094- `browser_use = false` disables Computer Use in browsers and Browser Agent availability.- `allow_managed_hooks_only = true` skips hooks from user, project, session, and
6551095- `browser_use_full_cdp_access = false` disables full CDP access in the local plugin sources, but still loads hooks from `requirements.toml` and other
6561096 runtime, including Browser Developer mode, and prevents the ChatGPT desktop managed config layers.
657 app from enabling the corresponding setting.
658- `browser_use_external = false` disables external Browser Use.
659- `computer_use = false` disables Computer Use, Record & Replay, and related
660 install or setup flows.
661 1097
6621098If you omit these keys, policy allows the features, subject to normal client,## Understand policy scope and precedence
663platform, and rollout availability.
664 1099
6651100### Restrict locked computer useUse this section to check where a policy applies, how requirements combine, how clients receive cloud-managed settings, and how to verify the result.
666 1101
6671102To prevent users from enabling [Locked Use](https://learn.chatgpt.com/docs/computer-use#locked-use)For Work with local access and dots, supported Global policy governs the shared cloud orchestrator when managed policy is enabled; applicable local execution requirements govern the connected computer. Work cloud containers retain existing Work Cloud policies, and supported device controls still apply to local execution. Codex keeps its existing configuration behavior. Managed configuration does not grant a workspace seat or feature access. Use [Roles and workspace permissions](https://learn.chatgpt.com/docs/enterprise/roles-and-workspace-permissions) for those controls.
668on a managed Mac, add this requirement:
669 1103
6701104```toml<a id="agent-security-and-work-sync"></a>
671[computer_use]
672allow_locked_computer_use = false
673```
674 1105
6751106This requirement removes the controls for enabling Locked Use. It doesn't<span
6761107turn off Locked Use if it's already enabled. If you omit it, normal product id="agent-security-and-local-computer-access"
6771108availability and the user's local setting still apply. data-localization-body-anchor
1109/>
678 1110
6791111### Configure automatic review policy### Agent Security and Local computer access with Work Cloud
680 1112
6811113Use `allowed_approvals_reviewers` to require or allow automatic review. Set itUse Agent Security in the Admin Console to manage policies and configuration. It replaces Policies & Configuration. Agent Security is available in the Admin Console, independently of Local computer access with Work Cloud. Existing policies, assignments, and ordering are preserved. Review your existing policies in Agent Security. Local computer access with Work Cloud is a separate opt-in. See [Agent Security](https://learn.chatgpt.com/docs/enterprise/agent-security) for migration guidance.
682to `["auto_review"]` to require automatic review, or include `"user"` when users
683can choose manual approval.
684 1114
6851115Set `guardian_policy_config` to replace the tenant-specific section of theBefore moving policy automation to **Agent Security**:
686automatic review policy. The local runtime still uses the built-in reviewer
687template and output contract. Managed `guardian_policy_config` takes precedence
688over local `[auto_review].policy`.
689 1116
6901117```toml1. Identify affected integrations. Inventory Terraform configurations and scripts that update policies, and record which policies they manage.
691allowed_approval_policies = ["on-request"]
692allowed_approvals_reviewers = ["auto_review"]
693 1118
6941119guardian_policy_config = """1. Use the policy API to manage Global settings. To manage Local or Codex Cloud settings, use the Agent Security UI. Existing Global API workflows remain available after migration. Test your scripts and Terraform integrations, and confirm that policy assignments and ordering are unchanged.
695## Environment Profile
696- Trusted internal destinations include github.com/my-org, artifacts.example.com,
697 and internal CI systems.
698 1120
6991121## Tenant Risk Taxonomy and Allow/Deny Rules1. Make any required changes and test the automation. Verify that an intended update reaches the correct Agent Security policy and that the resulting controls are enforced.
700- Treat uploads to unapproved third-party file-sharing services as high risk.
701- Deny actions that expose credentials or private source code to untrusted
702 destinations.
703"""
704```
705 1122
7061123### Enforce deny-read requirementsPolicy migration does not grant local computer access for Work or dots. Reviewing or creating policies is recommended before rollout, but the confirmation flow does not require policy creation to enable access. Before enabling **Allow local computer access**, review the migrated baseline or create a cloud baseline if your policies are currently delivered only through MDM. If `enforce_residency` is enabled in any cloud policy, **Allow local computer access** is disabled for both Work and dots. This safeguard does not configure workspace residency or, by itself, disable Work Cloud or dots.
707 1124
7081125Admins can deny reads for exact paths or glob patterns withEnvironment overrides vary supported settings within a policy. Within a given policy, the order from highest to lowest is OS-specific environment override → all-OS environment override → Global. A higher-priority policy still wins over a lower-priority policy, even when the lower-priority policy is more specific. Some requirements have field-specific merge rules. Confirm which override editors and fields are available for your workspace.
709`[permissions.filesystem]`. Users can't weaken these requirements with local
710configuration.
711 1126
7121127```tomlWhen managed policy and remote hooks are enabled, Work Cloud with local access and dots use admin-managed remote MCP hooks on the cloud orchestrator. Configure `mcp_tool` handlers in Global `requirements.toml`. Work Cloud without local access and personal accounts do not use these enterprise hooks. Command/shell, prompt, and agent handlers; hooks from local configuration, plugins, or local directories; environment-scoped hooks; and `SessionEnd` MCP hooks are not supported with cloud orchestration, even when tools execute locally. When both orchestration and execution are local, existing supported hooks continue to work in local-only Work and Codex threads. Admins can still configure supported managed hooks in Agent Security for those workflows. Before relying on these hooks, test callback connectivity, required events, and failure behavior. An explicit supported denial can block an action, but a `PreToolUse` callback error, timeout, or malformed response can fail the hook without blocking the tool. MCP hooks do not provide a complete Compliance API audit trail. See the [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference).
713[permissions.filesystem]
714deny_read = [
715 # values can be absolute paths...
716 "/**/*.env",
717 # ...or relative to $HOME/%USERPROFILE% using `~`.
718 "~/.ssh",
719 # But relative paths starting with `./` are not allowed.
720]
721```
722 1128
7231129When deny-read requirements are present, the local runtime rejects full-access### Locations and precedence
7241130permissions and keeps local execution in a read-only or workspace sandbox so it
7251131can enforce them. On native Windows, managed `deny_read` applies to direct fileFor local execution, requirements are applied from lower to higher priority as follows. This ordering also applies to local steps in Local computer access with Work Cloud:
726tools; shell subprocess reads don't use this sandbox rule.
727 1132
7281133### Enforce managed hooks from requirements1. System `requirements.toml` (`/etc/codex/requirements.toml` on Unix systems,
1134 including Linux and macOS, or `%ProgramData%\OpenAI\Codex\requirements.toml`
1135 on Windows).
11362. Agent Security requirements delivered in the cloud config bundle.
11373. Legacy `managed_config.toml` fields that the local client reinterprets as requirements.
11384. macOS managed preferences (MDM) delivered through
1139 `com.openai.codex:requirements_toml_base64`.
729 1140
7301141When managed policy and remote hooks are enabled, Work Cloud with local access and dots use admin-managed remote MCP hooks on the cloud orchestrator. Configure `mcp_tool` handlers in Global `requirements.toml`. Work Cloud without local access and personal accounts do not use these enterprise hooks. Command/shell, prompt, and agent handlers; hooks from local configuration, plugins, or local directories; environment-scoped hooks; and `SessionEnd` MCP hooks are not supported with cloud orchestration, even when tools execute locally. When both orchestration and execution are local, existing supported hooks continue to work in local-only Work and Codex threads. Admins can still configure supported managed hooks in Agent Security for those workflows.Higher-precedence layers override ordinary scalar and list values from lower
1142layers. Tables merge by key, while requirements such as rules, hooks, and
1143filesystem restrictions have field-specific composition behavior. Use the
1144[`requirements.toml` reference](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml)
1145for the current schema instead of assuming that every field merges the same
1146way.
731 1147
7321148Before relying on these hooks, test callback connectivity, required events, and failure behavior. An explicit supported denial can block an action, but a `PreToolUse` callback error, timeout, or malformed response can fail the hook without blocking the tool. MCP hooks do not provide a complete Compliance API audit trail. The following script and directory examples retain their Codex scope.For backward compatibility, supported local clients reinterpret the legacy
1149`approval_policy`, `approvals_reviewer`, and `sandbox_mode` fields as
1150requirements. This conversion adds compatibility choices where necessary; use
1151`requirements.toml` for explicit allowlists.
733 1152
734Admins can also define managed lifecycle hooks directly in `requirements.toml`.
735Use `[hooks]` for the hook configuration itself, and point `managed_dir` at the
736directory where your MDM or endpoint-management tooling installs the referenced
737scripts.
738 1153
739To enforce managed hooks even for users who turned hooks off locally, pin
740`[features].hooks = true` alongside `[hooks]`. To skip user, project, session,
741and plugin hooks while still allowing managed hooks, set
742`allow_managed_hooks_only = true`.
743 1154
744```toml
745allow_managed_hooks_only = true
746 1155
7471156[features]### Precedence for Local computer access with Work Cloud
748hooks = true
749 1157
7501158[hooks]For Work with local access and dots, distinguish Global orchestrator policy from execution policy. Applicable local requirements govern the connected computer. Work cloud containers and dots cloud computers use their own execution configuration and requirements, rather than the managed environment bundle used by other executors.
751managed_dir = "/enterprise/hooks"
752windows_managed_dir = 'C:\enterprise\hooks'
753 1159
7541160[[hooks.PreToolUse]]For local execution, MDM and legacy managed-device requirements rank above Agent Security. The device's system requirements file ranks below Agent Security. Within each policy, resolve OS-specific environment overrides before all-OS environment overrides, then Global. Policy priority wins over specificity across policies.
755matcher = "^Bash$"
756 1161
7571162[[hooks.PreToolUse.hooks]]| Control | Local Work without sync and local Codex | Local computer access with Work Cloud |
7581163type = "command"| ----------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
7591164command = "python3 /enterprise/hooks/pre_tool_use_policy.py"| Enterprise requirements | Follow the local requirements order above. | Apply to local executors. Work cloud containers retain existing Work Cloud policies. |
7601165command_windows = 'py -3 C:\enterprise\hooks\pre_tool_use_policy.py'| Device execution restrictions | Enforced by supported local controls. | Follow the local requirements order above, including MDM and legacy requirements above Agent Security. |
7611166timeout = 30| Environment overrides | Use the configuration model for the relevant product. | Within one policy: OS-specific environment override, then all-OS environment override, then Global. A lower-priority policy cannot win through specificity. |
762statusMessage = "Checking managed Bash command"
763```
764 1167
7651168Notes:Requirements impose constraints, while configuration defaults supply starting values. For Work with local access and dots, supported Global policy applies through the shared cloud orchestrator when managed policy is enabled. Applicable local `requirements.toml` requirements govern execution on a connected computer. Work cloud containers and dots cloud computers use their own execution configuration and requirements, rather than the managed environment bundle used by other executor types. Local execution restrictions do not automatically apply to these cloud computers. Review cloud capability permissions and test local and cloud execution separately.
766 1169
7671170- The local runtime enforces the hook configuration from `requirements.toml`,Keep orchestrator controls, including approvals and web search, in Global. Use the dedicated Allowed approval policies and Allowed web search modes controls where available, and TOML for other supported fields. See the [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference) for the field list and execution scope.
768 but it doesn't distribute the scripts in `managed_dir`.
769- Deliver those scripts with your MDM or device-management solution.
770- Managed hook commands should reference absolute script paths under the
771 configured managed directory.
772- `allow_managed_hooks_only = true` skips hooks from user, project, session, and
773 plugin sources, but still loads hooks from `requirements.toml` and other
774 managed config layers.
775 1171
7761172### Enforce command rules from requirements### Cloud-managed requirements
777 1173
7781174Admins can also enforce restrictive command rules from `requirements.toml`When a user signs in with ChatGPT on a supported plan, supported local clients
7791175using a `[rules]` table. These rules merge with regular `.rules` files, and thecan receive admin-enforced requirements associated with the workspace. This is
7801176most restrictive decision still wins.a delivery channel for `requirements.toml`-compatible policy. It doesn't grant
1177workspace access or replace workspace RBAC. Authentication requirements must be
1178[managed locally](#manage-authentication-locally).
781 1179
7821180Unlike `.rules`, requirements rules must specify `decision`, and that decisionConfigure common requirements with the [Agent security
7831181must be `"prompt"` or `"forbidden"` (not `"allow"`).controls](#configure-a-policy-in-agent-security). For a policy that allows only
1182on-request approvals and read-only or workspace-write sandboxes, use **Approval
1183policies** and **Sandbox modes** under **Policy guardrails**. To also prompt before
1184a supported shell entry point runs, use **Edit as TOML** to add the `[rules]`
1185table to Global `requirements.toml`.
1186
1187The complete TOML equivalent is:
784 1188
785```toml1189```toml
1190allowed_approval_policies = ["on-request"]
1191allowed_sandbox_modes = ["read-only", "workspace-write"]
1192
786[rules]1193[rules]
787prefix_rules = [1194prefix_rules = [
7881195 { pattern = [{ token = "rm" }], decision = "forbidden", justification = "Use git clean -fd instead." }, { pattern = [{ any_of = ["bash", "sh", "zsh"] }], decision = "prompt", justification = "Require explicit approval for shell entry points" },
789 { pattern = [{ token = "git" }, { any_of = ["push", "commit"] }], decision = "prompt", justification = "Require review before mutating history." },
790]1196]
791```1197```
792 1198
7931199To restrict which MCP servers a local client can enable, add an `mcp_servers`Check that every managed client version supports the keys you select. Assign the policy to the intended users or groups and verify that it takes effect on their supported clients. Use
7941200approved list. For stdio servers, match on `command`; for streamable HTTPthe configuration reference for the current schema and the administration
7951201servers, match on `url`:surface for current assignment behavior.
796
797```toml
798[mcp_servers.docs]
799identity = { command = "codex-mcp" }
800 1202
8011203[mcp_servers.remote]The service selects the enterprise-managed requirement layers that apply to the
8021204identity = { url = "https://example.com/mcp" }signed-in identity. The local client evaluates those layers with the other
8031205```requirements sources described in [Locations and precedence](#locations-and-precedence).
1206Use the current administration surface for workspace-side creation and
1207assignment. Don't rely on a copied group-matching algorithm; the administration
1208service owns that behavior and can change it independently of the local
1209requirements format.
804 1210
8051211The string form of `identity.command` matches only the configured `command`. ItFor supported keys and examples, see
8061212doesn't inspect `args`, `cwd`, `env`, or `env_vars`.[Example requirements.toml](#example-requirementstoml) and the
1213[`requirements.toml` reference](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml).
807 1214
8081215To constrain a complete stdio invocation, match the executable and each#### How local clients apply cloud-managed requirements
809positional argument:
810 1216
8111217```tomlThe local loading and cache behavior below describes supported local clients. It does not establish when a changed cloud policy takes effect in an already-running task using Local computer access with Work Cloud. Verify the effective policy before relying on a changed restriction.
812[mcp_servers.internal.identity]
813command = { executable = "/usr/local/bin/codex-mcp", args = [
814 { match = "exact", value = "serve" },
815 { match = "prefix", value = "--workspace=" },
816] }
817```
818 1218
8191219The executable, argument count, and argument order must match. Argument and URLWhen a user starts a supported local client and signs in with ChatGPT on a
8201220rules support `exact`, `prefix`, and full-value `regex` matching. Structuredsupported plan, the client first checks for a valid, identity-matched cache
8211221command rules still don't inspect `cwd`, `env`, or `env_vars`. Plugin-bundledentry. If no valid entry is available, the client fetches the applicable bundle
8221222MCP servers use the same identity shapes underwith retries and writes a signed cache entry on success. If the request fails or
8231223`plugins.<plugin>.mcp_servers.<server>`.times out and no valid cache is available, the cloud config bundle load returns
1224an error rather than silently starting without the cloud-managed requirements
1225layer.
824 1226
8251227If `mcp_servers` is present but empty, the local client disables all MCP servers.After cache resolution, the client composes the cloud requirements with the
1228other requirements layers described above. A background refresh updates the
1229cached bundle and makes it available to subsequent configuration loads. This
1230doesn't guarantee that an already-running task immediately uses a changed policy.
1231Some desktop settings require an app restart; follow any restart prompt and
1232verify the effective settings before relying on the change.
826 1233
8271234### Control plugin availability### Confirm the admin and employee experience
828 1235
8291236To turn off plugins in supported local clients, set `features.plugins` toAssign a person to own each managed policy, record which users or groups should
8301237`false` in `requirements.toml`:receive it, and document the business reason for any filesystem, network,
1238approval, or permission-profile restriction.
831 1239
8321240```tomlTest an allowed workflow and a blocked workflow with a user who has the intended permissions. Check the effective settings in the supported client. A workspace role or group alone does not enforce a local runtime restriction.
833features.plugins = false
834```
835 1241
8361242This setting also applies when users sign in to Codex with an API key. See theUse **Test policies** in Agent security to check which policies match a member,
8371243[`features.plugins`group, or role selection. In an editable session, this checks the current draft
8381244reference](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml) for thewithout saving it. The result shows policy selection, not the final merged
8391245supported configuration.configuration or whether a client enforces a restriction. After saving, test
1246the allowed and blocked workflows on each relevant client and execution path.
840 1247
8411248### Restrict plugin marketplace sources## Deploy device-managed configuration
842 1249
8431250To restrict plugin marketplace sources, setUse local system requirements or MDM for authentication restrictions and device-managed policies. The legacy `managed_config.toml` mechanism has different startup precedence from Agent security **Defaults**. The MDM workflow covers both requirements and legacy defaults.
844`restrict_to_allowed_sources = true` and define one or more source rules:
845 1251
8461252```toml### Manage authentication locally
847[marketplaces]
848restrict_to_allowed_sources = true
849 1253
8501254[marketplaces.allowed_sources.company_plugins]Set `allowed_login_methods`, `allowed_chatgpt_workspaces`,
8511255source = "git"`cli_auth_credentials_store`, and `chatgpt_base_url` in the local system
8521256url = "https://github.com/example/company-plugins.git"`requirements.toml` or macOS MDM requirements. Codex ignores these four fields
8531257ref = "main"in cloud-managed requirements. Local authentication requirements apply before
1258credentials load and before Codex retrieves cloud policy.
854 1259
8551260[marketplaces.allowed_sources.internal_git]To require ChatGPT login to an approved workspace and store credentials in the
8561261source = "host_pattern"OS credential store, use:
857host_pattern = '^git\.example\.com$'
858 1262
8591263[marketplaces.allowed_sources.local_plugins]```toml
8601264source = "local"allowed_login_methods = ["chatgpt"]
8611265path = "/opt/company/codex-plugins"allowed_chatgpt_workspaces = ["00000000-0000-0000-0000-000000000000"]
1266cli_auth_credentials_store = "keyring"
862```1267```
863 1268
8641269Git rules match the normalized repository URL and, when present, an exact`allowed_login_methods` accepts `chatgpt`, `api`, or both. If omitted, this setting
8651270`ref`. Host patterns are regular expressions matched against the lowercase Gitdoesn't restrict login methods. If set, the list must contain at least one method.
8661271host; use `^` and `$` for a whole-host match. Local rules require an absolute,`api` permits API authentication, including Amazon Bedrock.
8671272normalized path. See the [`requirements.toml` reference](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml)The workspace restriction also applies to
8681273for the full schema and merge behavior.[Codex access tokens](https://learn.chatgpt.com/docs/enterprise/access-tokens).
869
870These requirements reject unmatched marketplace add, plugin install, and
871configured Git marketplace refresh operations. They also filter configured
872marketplaces and their plugins at runtime.
873
874The OpenAI-curated Git marketplaces, including the API-key catalog, must also
875match the source allowlist. To allow them, include the following Git source
876without a `ref` constraint:
877 1274
8781275```tomlUser-configured `forced_login_method` and `forced_chatgpt_workspace_id` must
8791276[marketplaces.allowed_sources.openai_curated]follow the requirements. When a user selects a workspace, it must also appear
8801277source = "git"in the managed workspace allowlist. If no workspaces match, ChatGPT login is
8811278url = "https://github.com/openai/plugins.git"unavailable. API authentication remains available when permitted. If no login method
8821279```is available, Codex refuses to start.
883 1280
8841281To exclude the curated catalogs, omit that source and ensure no broader hostSee the [requirements reference](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml)
8851282rule allows it. Bundled plugins and remotely installed workspace plugins arefor credential storage modes and service URL configuration.
886separate from this curated Git source policy.
887 1283
8881284These source restrictions apply only where a local client supports plugin### Managed defaults (`managed_config.toml`)
889marketplace operations: ChatGPT and Codex in the desktop app, and Codex CLI.
890They don't control plugin use in ChatGPT on the web or mobile, and they don't
891add plugins to the IDE extension.
892 1285
8931286## Managed defaults (`managed_config.toml`)Use [Agent security Defaults](#set-configuration-defaults) for supported
1287cloud-managed starting values. This section covers the legacy device-managed
1288`managed_config.toml` mechanism and its different startup precedence. Editing
1289**Defaults** in Agent security doesn't deploy a `managed_config.toml` file to
1290members' devices.
894 1291
895Managed defaults set the configuration a supported local client starts with. At1292Managed defaults set the configuration a supported local client starts with. At
896startup, they override the user's local `config.toml` and any CLI `--config`1293startup, they override the user's local `config.toml` and any CLI `--config`
910Make sure your managed defaults meet your requirements; the local runtime1307Make sure your managed defaults meet your requirements; the local runtime
911rejects disallowed values.1308rejects disallowed values.
912 1309
9131310### Precedence and layering#### Precedence and layering
914 1311
915The local runtime assembles the effective configuration in this order (top1312The local runtime assembles the effective configuration in this order (top
916overrides bottom):1313overrides bottom):
925not the legacy ordering above. Cloud `requirements.toml` uses1322not the legacy ordering above. Cloud `requirements.toml` uses
926[requirements precedence](#locations-and-precedence).1323[requirements precedence](#locations-and-precedence).
927 1324
9281325### Locations#### Locations
929 1326
930- Linux/macOS (Unix): `/etc/codex/managed_config.toml`1327- Linux/macOS (Unix): `/etc/codex/managed_config.toml`
931- Windows/non-Unix: `~/.codex/managed_config.toml`1328- Windows/non-Unix: `~/.codex/managed_config.toml`
932 1329
933If the file is missing, the local runtime skips the managed layer.1330If the file is missing, the local runtime skips the managed layer.
934 1331
1332#### Example managed_config.toml
1333
1334```toml
1335# Set conservative defaults
1336approval_policy = "on-request"
1337sandbox_mode = "workspace-write"
1338
1339[sandbox_workspace_write]
1340network_access = false # keep network disabled unless explicitly allowed
1341
1342[otel]
1343environment = "prod"
1344exporter = "otlp-http" # point at your collector
1345log_user_prompt = false # keep prompts redacted
1346# exporter details live under exporter tables; see Monitoring and telemetry above
1347```
1348
1349#### Recommended guardrails
1350
1351- Prefer `workspace-write` with approvals for most users; reserve full access for controlled containers.
1352- Keep `network_access = false` unless your security review allows a collector or domains required by your workflows.
1353- Use managed configuration to pin OTel settings (exporter, environment), but keep `log_user_prompt = false` unless your policy explicitly allows storing prompt contents.
1354- Periodically audit diffs between local `config.toml` and managed policy to catch drift; managed layers should win over local flags and files.
1355
935### macOS managed preferences (MDM)1356### macOS managed preferences (MDM)
936 1357
937On macOS, admins can push a device profile that provides base64-encoded TOML payloads at:1358On macOS, admins can push a device profile that provides base64-encoded TOML payloads at:
944The local runtime parses these "managed preferences" payloads as TOML. For1365The local runtime parses these "managed preferences" payloads as TOML. For
945managed defaults (`config_toml_base64`), managed preferences have the highest1366managed defaults (`config_toml_base64`), managed preferences have the highest
946precedence. For requirements (`requirements_toml_base64`), precedence follows1367precedence. For requirements (`requirements_toml_base64`), precedence follows
9471368the cloud-managed requirements order described above. The samethe [requirements order](#locations-and-precedence). The same
948requirements-side `[features]` table works in `requirements_toml_base64`; use1369requirements-side `[features]` table works in `requirements_toml_base64`; use
949canonical feature keys there as well.1370canonical feature keys there as well.
950 1371
9511372### MDM setup workflow#### MDM setup workflow
952 1373
953The local runtime honors standard macOS MDM payloads, so you can distribute1374The local runtime honors standard macOS MDM payloads, so you can distribute
954settings with tooling like `Jamf Pro`, `Fleet`, or `Kandji`. A lightweight1375settings with tooling like `Jamf Pro`, `Fleet`, or `Kandji`. A lightweight
962 reads the refreshed preference the next time it launches.1383 reads the refreshed preference the next time it launches.
963 1384
964Avoid embedding secrets or high-churn dynamic values in the payload. Treat the managed TOML like any other MDM setting under change control.1385Avoid embedding secrets or high-churn dynamic values in the payload. Treat the managed TOML like any other MDM setting under change control.
965
966### Example managed_config.toml
967
968```toml
969# Set conservative defaults
970approval_policy = "on-request"
971sandbox_mode = "workspace-write"
972
973[sandbox_workspace_write]
974network_access = false # keep network disabled unless explicitly allowed
975
976[otel]
977environment = "prod"
978exporter = "otlp-http" # point at your collector
979log_user_prompt = false # keep prompts redacted
980# exporter details live under exporter tables; see Monitoring and telemetry above
981```
982
983### Recommended guardrails
984
985- Prefer `workspace-write` with approvals for most users; reserve full access for controlled containers.
986- Keep `network_access = false` unless your security review allows a collector or domains required by your workflows.
987- Use managed configuration to pin OTel settings (exporter, environment), but keep `log_user_prompt = false` unless your policy explicitly allows storing prompt contents.
988- Periodically audit diffs between local `config.toml` and managed policy to catch drift; managed layers should win over local flags and files.