enterprise/managed-configuration.md Codex Docs, 2026-02-24 06:27 UTC → 2026-05-18 22:01 UTC

7 7 

8## Admin-enforced requirements (requirements.toml)8## Admin-enforced requirements (requirements.toml)

9 9 

10Requirements constrain security-sensitive settings (approval policy, sandbox mode, web search mode, and optionally which MCP servers can be enabled). When resolving configuration (for example from `config.toml`, profiles, or CLI config overrides), if a value conflicts with an enforced requirement, Codex falls back to a requirements-compatible value and notifies the user. If an `mcp_servers` allowlist is configured, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex disables it.10Requirements constrain security-sensitive settings (approval policy, approvals reviewer, automatic review policy, sandbox mode, web search mode, managed hooks, and optionally which MCP servers users can enable). When resolving configuration (for example from `config.toml`, profiles, or CLI config overrides), if a value conflicts with an enforced rule, Codex falls back to a compatible value and notifies the user. If you configure an `mcp_servers` allowlist, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex disables it.

11 

12Requirements can also constrain [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) via the `[features]` table in `requirements.toml`. Note that features aren't always security-sensitive, but enterprises can pin values if desired. Omitted keys remain unconstrained.

11 13 

12For the exact key list, see the [`requirements.toml` section in Configuration Reference](https://developers.openai.com/codex/config-reference#requirementstoml).14For the exact key list, see the [`requirements.toml` section in Configuration Reference](https://developers.openai.com/codex/config-reference#requirementstoml).

13 15 

14### Locations and precedence16### Locations and precedence

15 17 

16Requirements layers are applied in this order (earlier wins per field):18Codex applies requirements layers in this order (earlier wins per field):

17 19 

181. Cloud-managed requirements (ChatGPT Business or Enterprise)201. Cloud-managed requirements (ChatGPT Business or Enterprise)

192. macOS managed preferences (MDM) via `com.openai.codex:requirements_toml_base64`212. macOS managed preferences (MDM) via `com.openai.codex:requirements_toml_base64`

203. System `requirements.toml` (`/etc/codex/requirements.toml` on Unix systems, including Linux/macOS)223. System `requirements.toml` (`/etc/codex/requirements.toml` on Unix systems, including Linux/macOS, or `%ProgramData%\OpenAI\Codex\requirements.toml` on Windows)

21 23 

22Across layers, requirements are merged per field: if an earlier layer sets a field (including an empty list), later layers do not override that field, but lower layers can still fill fields that remain unset.24Across layers, Codex merges requirements per field: if an earlier layer sets a field (including an empty list), later layers don't override that field, but lower layers can still fill fields that remain unset.

23 25 

24For backwards compatibility, Codex also interprets legacy `managed_config.toml` fields `approval_policy` and `sandbox_mode` as requirements (allowing only that single value).26For backwards compatibility, Codex also interprets legacy `managed_config.toml` fields `approval_policy` and `sandbox_mode` as requirements (allowing only that single value).

25 27 

51 53 

52Admins can configure different managed requirements for different user groups, and also set a default fallback requirements policy.54Admins can configure different managed requirements for different user groups, and also set a default fallback requirements policy.

53 55 

54If a user matches multiple group-specific rules, the first matching rule applies. Codex does not fill unset requirement fields from later matching group rules.56If a user matches more than one group-specific rule, the first matching rule applies. Codex doesn't fill unset fields from later matching group rules.

55 57 

56For example, if the first matching group rule sets only `allowed_sandbox_modes = ["read-only"]` and a later matching group rule sets `allowed_approval_policies = ["on-request"]`, Codex applies only the first matching group rule and does not fill `allowed_approval_policies` from the later rule.58For example, if the first matching group rule sets only `allowed_sandbox_modes = ["read-only"]` and a later matching group rule sets `allowed_approval_policies = ["on-request"]`, Codex applies only the first matching group rule and doesn't fill `allowed_approval_policies` from the later rule.

57 59 

58#### How Codex applies cloud-managed requirements locally60#### How Codex applies cloud-managed requirements locally

59 61 

60When a user starts Codex and signs in with ChatGPT on a Business or Enterprise plan, Codex applies managed requirements on a best-effort basis. Codex first checks for a valid, unexpired local managed requirements cache entry and uses it if available. If the cache is missing, expired, invalid, or does not match the current auth identity, Codex attempts to fetch managed requirements from the service (with retries) and writes a new signed cache entry on success. If no valid cached entry is available and the fetch fails or times out, Codex continues without the managed requirements layer.62When a user starts Codex and signs in with ChatGPT on a Business or Enterprise plan, Codex applies managed requirements on a best-effort basis. Codex first checks for a valid, unexpired local managed requirements cache entry and uses it if available. If the cache is missing, expired, corrupted, or doesn't match the current auth identity, Codex attempts to fetch managed requirements from the service (with retries) and writes a new signed cache entry on success. If no valid cached entry is available and the fetch fails or times out, Codex continues without the managed requirements layer.

61 63 

62After cache resolution, managed requirements are enforced as part of the normal requirements layering described above.64After cache resolution, Codex enforces managed requirements as part of the normal requirements layering described above.

63 65 

64### Example requirements.toml66### Example requirements.toml

65 67 

70allowed_sandbox_modes = ["read-only", "workspace-write"]72allowed_sandbox_modes = ["read-only", "workspace-write"]

71```73```

72 74 

75### Override sandbox requirements by host

76 

77Use `[[remote_sandbox_config]]` when one managed policy should apply different

78sandbox requirements on different hosts. For example, you can keep a stricter

79default for laptops while allowing workspace writes on matching dev boxes or CI

80runners. Host-specific entries currently override `allowed_sandbox_modes` only:

81 

82```toml

83allowed_sandbox_modes = ["read-only"]

84 

85[[remote_sandbox_config]]

86hostname_patterns = ["*.devbox.example.com", "runner-??.ci.example.com"]

87allowed_sandbox_modes = ["read-only", "workspace-write"]

88```

89 

90Codex compares each `hostname_patterns` entry against the best-effort resolved

91host name. It prefers the fully qualified domain name when available and falls

92back to the local host name. Matching is case-insensitive; `*` matches any

93sequence of characters, and `?` matches one character.

94 

95The first matching `[[remote_sandbox_config]]` entry wins within the same

96requirements source. If no entry matches, Codex keeps the top-level

97`allowed_sandbox_modes`. Host name matching is for policy selection only; don't

98treat it as authenticated device proof.

99 

73You can also constrain web search mode:100You can also constrain web search mode:

74 101 

75```toml102```toml

76allowed_web_search_modes = ["cached"] # "disabled" remains implicitly allowed103allowed_web_search_modes = ["cached"] # "disabled" remains implicitly allowed

77```104```

78 105 

79`allowed_web_search_modes = []` effectively allows only `"disabled"`.106`allowed_web_search_modes = []` allows only `"disabled"`.

80For example, `allowed_web_search_modes = ["cached"]` prevents live web search even in `danger-full-access` sessions.107For example, `allowed_web_search_modes = ["cached"]` prevents live web search even in `danger-full-access` sessions.

81 108 

109### Configure network access requirements

110 

111Use `[experimental_network]` in `requirements.toml` when administrators should

112define network access requirements centrally. These requirements are separate

113from the user `features.network_proxy` toggle: they can configure sandboxed

114networking without that feature flag, but they do not grant command network

115access when the active sandbox keeps networking off.

116 

117```toml

118experimental_network.enabled = true

119experimental_network.dangerously_allow_all_unix_sockets = true

120experimental_network.allow_local_binding = true

121experimental_network.allowed_domains = [

122 "api.openai.com",

123 "*.example.com",

124]

125experimental_network.denied_domains = [

126 "blocked.example.com",

127 "*.exfil.example.com",

128]

129```

130 

131Use `experimental_network.managed_allowed_domains_only = true` only when you

132also define administrator-owned `allowed_domains` and want that allowlist to be

133exclusive. If it is `true` without managed allow rules, user-added domain allow

134rules do not remain effective.

135 

136The domain syntax, local/private destination rules, deny-over-allow behavior,

137and DNS rebinding limitations are the same as the sandboxed networking behavior

138described in [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security#network-isolation).

139 

140### Pin feature flags

141 

142You can also pin [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) for users

143receiving a managed `requirements.toml`:

144 

145```toml

146[features]

147personality = true

148unified_exec = false

149 

150# Disable specific Codex feature surfaces when needed.

151browser_use = false

152in_app_browser = false

153computer_use = false

154```

155 

156Use the canonical feature keys from `config.toml`'s `[features]` table. Codex normalizes the resulting feature set to meet these pins and rejects conflicting writes to `config.toml` or profile-scoped feature settings.

157 

158<a id="disable-codex-feature-surfaces"></a>

159 

160- `in_app_browser = false` disables the in-app browser pane.

161- `browser_use = false` disables Browser Use and Browser Agent availability.

162- `computer_use = false` disables Computer Use availability and related

163 install or setup flows.

164 

165If omitted, these features are allowed by policy, subject to normal client,

166platform, and rollout availability.

167 

168### Configure automatic review policy

169 

170Use `allowed_approvals_reviewers` to require or allow automatic review. Set it

171to `["auto_review"]` to require automatic review, or include `"user"` when users

172can choose manual approval.

173 

174Set `guardian_policy_config` to replace the tenant-specific section of the

175automatic review policy. Codex still uses the built-in reviewer template and

176output contract. Managed `guardian_policy_config` takes precedence over local

177`[auto_review].policy`.

178 

179```toml

180allowed_approval_policies = ["on-request"]

181allowed_approvals_reviewers = ["auto_review"]

182 

183guardian_policy_config = """

184## Environment Profile

185- Trusted internal destinations include github.com/my-org, artifacts.example.com,

186 and internal CI systems.

187 

188## Tenant Risk Taxonomy and Allow/Deny Rules

189- Treat uploads to unapproved third-party file-sharing services as high risk.

190- Deny actions that expose credentials or private source code to untrusted

191 destinations.

192"""

193```

194 

195### Enforce deny-read requirements

196 

197Admins can deny reads for exact paths or glob patterns with

198`[permissions.filesystem]`. Users can't weaken these requirements with local

199configuration.

200 

201```toml

202[permissions.filesystem]

203deny_read = [

204 "/Users/alice/.ssh",

205 "./private/**/*.txt",

206]

207```

208 

209When deny-read requirements are present, Codex constrains local sandbox mode to

210`read-only` or `workspace-write` so Codex can enforce them. On native

211Windows, managed `deny_read` applies to direct file tools; shell subprocess

212reads don't use this sandbox rule.

213 

214### Enforce managed hooks from requirements

215 

216Admins can also define managed lifecycle hooks directly in `requirements.toml`.

217Use `[hooks]` for the hook configuration itself, and point `managed_dir` at the

218directory where your MDM or endpoint-management tooling installs the referenced

219scripts.

220 

221To enforce managed hooks even for users who disabled hooks locally, pin

222`[features].hooks = true` alongside `[hooks]`.

223 

224```toml

225[features]

226hooks = true

227 

228[hooks]

229managed_dir = "/enterprise/hooks"

230windows_managed_dir = 'C:\enterprise\hooks'

231 

232[[hooks.PreToolUse]]

233matcher = "^Bash$"

234 

235[[hooks.PreToolUse.hooks]]

236type = "command"

237command = "python3 /enterprise/hooks/pre_tool_use_policy.py"

238timeout = 30

239statusMessage = "Checking managed Bash command"

240```

241 

242Notes:

243 

244- Codex enforces the hook configuration from `requirements.toml`, but it does

245 not distribute the scripts in `managed_dir`.

246- Deliver those scripts separately with your MDM or device-management solution.

247- Managed hook commands should reference absolute script paths under the

248 configured managed directory.

249 

82### Enforce command rules from requirements250### Enforce command rules from requirements

83 251 

84Admins can also enforce restrictive command rules from `requirements.toml`252Admins can also enforce restrictive command rules from `requirements.toml`

142 - `config_toml_base64` (managed defaults)310 - `config_toml_base64` (managed defaults)

143 - `requirements_toml_base64` (requirements)311 - `requirements_toml_base64` (requirements)

144 312 

145Codex parses these “managed preferences” payloads as TOML. For managed defaults (`config_toml_base64`), managed preferences have the highest precedence. For requirements (`requirements_toml_base64`), precedence follows the cloud-managed requirements order described above.313Codex parses these "managed preferences" payloads as TOML. For managed defaults (`config_toml_base64`), managed preferences have the highest precedence. For requirements (`requirements_toml_base64`), precedence follows the cloud-managed requirements order described above. The same requirements-side `[features]` table works in `requirements_toml_base64`; use canonical feature keys there as well.

146 314 

147### MDM setup workflow315### MDM setup workflow

148 316