enterprise/managed-configuration.md Codex Docs, 2026-04-12 06:38 UTC → 2026-05-07 20:02 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 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.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 11 

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

13 13 

19 19 

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

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

223. 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)

23 23 

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

25 25 

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

73```73```

74 74 

75### Override sandbox requirements by host

76 

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

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

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

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

81 

82```toml

83allowed_sandbox_modes = ["read-only"]

84 

85[[remote_sandbox_config]]

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

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

88```

89 

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

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

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

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

94 

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

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

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

98treat it as authenticated device proof.

99 

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

76 101 

77```toml102```toml

81`allowed_web_search_modes = []` allows only `"disabled"`.106`allowed_web_search_modes = []` allows only `"disabled"`.

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

83 108 

84You can also pin [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags):109### Pin feature flags

85 110 

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

112receiving a managed `requirements.toml`:

113 

114```toml

87[features]115[features]

88personality = true116personality = true

89unified_exec = false117unified_exec = false

118 

119# Disable specific Codex feature surfaces when needed.

120browser_use = false

121in_app_browser = false

122computer_use = false

90```123```

91 124 

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

93 126 

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

128 

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

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

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

132 install or enablement flows.

133 

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

135platform, and rollout availability.

136 

137### Configure automatic review policy

138 

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

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

141can choose manual approval.

142 

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

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

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

146`[auto_review].policy`.

147 

148```toml

149allowed_approval_policies = ["on-request"]

150allowed_approvals_reviewers = ["auto_review"]

151 

152guardian_policy_config = """

153## Environment Profile

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

155 and internal CI systems.

156 

157## Tenant Risk Taxonomy and Allow/Deny Rules

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

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

160 destinations.

161"""

162```

163 

164### Enforce deny-read requirements

165 

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

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

168configuration.

169 

170```toml

171[permissions.filesystem]

172deny_read = [

173 "/Users/alice/.ssh",

174 "./private/**/*.txt",

175]

176```

177 

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

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

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

181reads don't use this sandbox rule.

182 

183### Enforce managed hooks from requirements

184 

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

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

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

188scripts.

189 

190```toml

191[features]

192codex_hooks = true

193 

194[hooks]

195managed_dir = "/enterprise/hooks"

196windows_managed_dir = 'C:\enterprise\hooks'

197 

198[[hooks.PreToolUse]]

199matcher = "^Bash$"

200 

201[[hooks.PreToolUse.hooks]]

202type = "command"

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

204timeout = 30

205statusMessage = "Checking managed Bash command"

206```

207 

208Notes:

209 

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

211 not distribute the scripts in `managed_dir`.

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

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

214 configured managed directory.

215 

94### Enforce command rules from requirements216### Enforce command rules from requirements

95 217 

96Admins can also enforce restrictive command rules from `requirements.toml`218Admins can also enforce restrictive command rules from `requirements.toml`