enterprise/managed-configuration diff

enterprise/managed-configuration.md +211 −0 added

Details

1# Managed configuration

3Enterprise admins can control local Codex behavior in two ways:

5- **Requirements**: admin-enforced constraints that users can't override.

6- **Managed defaults**: starting values applied when Codex launches. Users can still change settings during a session; Codex reapplies managed defaults the next time it starts.

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

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.

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.

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

16### Locations and precedence

18Codex applies requirements layers in this order (earlier wins per field):

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

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

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

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.

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

28### Cloud-managed requirements

30When you sign in with ChatGPT on a Business or Enterprise plan, Codex can also fetch admin-enforced requirements from the Codex service. This is another source of `requirements.toml`-compatible requirements. This applies across Codex surfaces, including the CLI, App, and IDE Extension.

32#### Configure cloud-managed requirements

34Go to the [Codex managed-config page](https://chatgpt.com/codex/settings/managed-configs).

36Create a new managed requirements file using the same format and keys as `requirements.toml`.

38```toml

39enforce_residency = "us"

40allowed_approval_policies = ["on-request"]

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

43[rules]

44prefix_rules = [

45 { pattern = [{ any_of = ["bash", "sh", "zsh"] }], decision = "prompt", justification = "Require explicit approval for shell entrypoints" },

46]

47```

49Save the configuration. Once saved, the updated managed requirements apply immediately for matching users.

50For more examples, see [Example requirements.toml](#example-requirementstoml).

52#### Assign requirements to groups

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

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.

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.

60#### How Codex applies cloud-managed requirements locally

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.

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

66### Example requirements.toml

68This example blocks `--ask-for-approval never` and `--sandbox danger-full-access` (including `--yolo`):

70```toml

71allowed_approval_policies = ["untrusted", "on-request"]

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

73```

75You can also constrain web search mode:

77```toml

78allowed_web_search_modes = ["cached"] # "disabled" remains implicitly allowed

79```

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

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

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

86```

87[features]

88personality = true

89unified_exec = false

90```

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.

94### Enforce deny-read requirements

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

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

98configuration.

100```toml

101[permissions.filesystem]

102deny_read = [

103 "/Users/alice/.ssh",

104 "./private/**/*.txt",

105]

106```

107

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

109`read-only` or `workspace-write` so the requirement can be enforced. On native

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

111reads don’t use this sandbox requirement.

112

113### Enforce command rules from requirements

114

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

116using a `[rules]` table. These rules merge with regular `.rules` files, and the

117most restrictive decision still wins.

118

119Unlike `.rules`, requirements rules must specify `decision`, and that decision

120must be `"prompt"` or `"forbidden"` (not `"allow"`).

121

122```toml

123[rules]

124prefix_rules = [

125 { pattern = [{ token = "rm" }], decision = "forbidden", justification = "Use git clean -fd instead." },

126 { pattern = [{ token = "git" }, { any_of = ["push", "commit"] }], decision = "prompt", justification = "Require review before mutating history." },

127]

128```

129

130To restrict which MCP servers Codex can enable, add an `mcp_servers` approved list. For stdio servers, match on `command`; for streamable HTTP servers, match on `url`:

131

132```toml

133[mcp_servers.docs]

134identity = { command = "codex-mcp" }

135

136[mcp_servers.remote]

137identity = { url = "https://example.com/mcp" }

138```

139

140If `mcp_servers` is present but empty, Codex disables all MCP servers.

141

142## Managed defaults (`managed_config.toml`)

143

144Managed defaults merge on top of a user's local `config.toml` and take precedence over any CLI `--config` overrides, setting the starting values when Codex launches. Users can still change those settings during a session; Codex reapplies managed defaults the next time it starts.

145

146Make sure your managed defaults meet your requirements; Codex rejects disallowed values.

147

148### Precedence and layering

149

150Codex assembles the effective configuration in this order (top overrides bottom):

151

152- Managed preferences (macOS MDM; highest precedence)

153- `managed_config.toml` (system/managed file)

154- `config.toml` (user's base configuration)

155

156CLI `--config key=value` overrides apply to the base, but managed layers override them. This means each run starts from the managed defaults even if you provide local flags.

157

158Cloud-managed requirements affect the requirements layer (not managed defaults). See the Admin-enforced requirements section above for precedence.

159

160### Locations

161

162- Linux/macOS (Unix): `/etc/codex/managed_config.toml`

163- Windows/non-Unix: `~/.codex/managed_config.toml`

164

165If the file is missing, Codex skips the managed layer.

166

167### macOS managed preferences (MDM)

168

169On macOS, admins can push a device profile that provides base64-encoded TOML payloads at:

170

171- Preference domain: `com.openai.codex`

172- Keys:

173 - `config_toml_base64` (managed defaults)

174 - `requirements_toml_base64` (requirements)

175

176Codex 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.

177

178### MDM setup workflow

179

180Codex honors standard macOS MDM payloads, so you can distribute settings with tooling like `Jamf Pro`, `Fleet`, or `Kandji`. A lightweight deployment looks like:

181

1821. Build the managed payload TOML and encode it with `base64` (no wrapping).

1832. Drop the string into your MDM profile under the `com.openai.codex` domain at `config_toml_base64` (managed defaults) or `requirements_toml_base64` (requirements).

1843. Push the profile, then ask users to restart Codex and confirm the startup config summary reflects the managed values.

1854. When revoking or changing policy, update the managed payload; the CLI reads the refreshed preference the next time it launches.

186

187Avoid embedding secrets or high-churn dynamic values in the payload. Treat the managed TOML like any other MDM setting under change control.

188

189### Example managed_config.toml

190

191```toml

192# Set conservative defaults

193approval_policy = "on-request"

194sandbox_mode = "workspace-write"

195

196[sandbox_workspace_write]

197network_access = false # keep network disabled unless explicitly allowed

198

199[otel]

200environment = "prod"

201exporter = "otlp-http" # point at your collector

202log_user_prompt = false # keep prompts redacted

203# exporter details live under exporter tables; see Monitoring and telemetry above

204```

205

206### Recommended guardrails

207

208- Prefer `workspace-write` with approvals for most users; reserve full access for controlled containers.

209- Keep `network_access = false` unless your security review allows a collector or domains required by your workflows.

210- Use managed configuration to pin OTel settings (exporter, environment), but keep `log_user_prompt = false` unless your policy explicitly allows storing prompt contents.

211- Periodically audit diffs between local `config.toml` and managed policy to catch drift; managed layers should win over local flags and files.

enterprise/managed-configuration.md Codex Docs, 2026-02-23 18:27 UTC → 2026-04-23 12:28 UTC