codex requirements.toml example for admins

The Example (Codex 0.138.0 and Later)

Codex 0.137.0 and earlier ignore allowed_permission_profiles and managed default_permissions; for those fleets use the legacy allowed_sandbox_modes = ["read-only", "workspace-write"] instead. An empty [mcp_servers] table disables every MCP server.

Managed hook commands should reference scripts under managed_dir, and Codex does not distribute them: deliver pre-tool-use.sh with your MDM. To run Failproof from it, the wrapper can call failproofai --hook pre_tool_use --cli codex with the hook payload on stdin. These are the pre-tool command forms failproofai config writes into each agent’s hook file: user scope, except Codex, which it writes to the managed /etc/codex/config.toml when it can run as root. They cover only the pre-tool gate. failproofai config also registers post-tool output redaction, prompt, stop and session events, so keep its install alongside any system entry. Placing them in the system or managed locations below, and keeping them there with MDM, is your configuration rather than a documented Failproof install path; talk to us about a managed deployment.

allowed_approval_policies = ["on-request"]
allowed_web_search_modes = ["cached"]
allow_managed_hooks_only = true

default_permissions = ":workspace"

[allowed_permission_profiles]
":read-only" = true
":workspace" = true
# ":danger-full-access" is omitted, so it is denied.

[permissions.filesystem]
deny_read = ["/**/*.env", "~/.ssh", "~/.aws/credentials"]

[rules]
prefix_rules = [
  { pattern = [{ token = "terraform" }, { token = "destroy" }], decision = "forbidden", justification = "Destroys go through CI." },
  { pattern = [{ token = "git" }, { token = "push" }], decision = "prompt", justification = "Review before pushing." },
  { pattern = [{ token = "rm" }], decision = "prompt", justification = "Confirm deletions." },
]

[mcp_servers.github]
identity = { command = "github-mcp-server" }

[features]
hooks = true

[hooks]
managed_dir = "/opt/company/codex-hooks"
windows_managed_dir = 'C:\company\codex-hooks'

[[hooks.PreToolUse]]
matcher = "^(Bash|apply_patch|mcp__.*)$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "/opt/company/codex-hooks/pre-tool-use.sh"
command_windows = 'C:\company\codex-hooks\pre-tool-use.cmd'
timeout = 30

Known Limits

• Prefix rules match a command’s leading tokens. Users have reported rules not firing for nested shells and scripts (openai/codex #44964).
• A PreToolUse hook that returns permissionDecision: "ask" is marked failed and the tool call continues; return deny to block.
• The matcher above covers shell (Bash), apply_patch (also matchable as Edit or Write) and MCP tools. Hosted tools such as web search do not go through local hooks.
• For admin-managed remote MCP hooks on the cloud orchestrator, a callback error, timeout or malformed response can fail without blocking.

Hook Trust on Developer Machines

Codex 0.129 and later only runs hooks from ~/.codex/hooks.json after a user approves them interactively. Hooks in system configuration run without approval, which is why managed hooks belong in requirements.toml or /etc/codex/config.toml. failproofai config writes a managed block into /etc/codex/config.toml when it can use sudo. Without sudo, and on Windows, its hooks stay in ~/.codex/hooks.json, and failproofai config --status does not count Codex as enforcing until they are approved.