Codex CLI configuration guide: instruction files, MCP, permissions

Codex reads AGENTS.md natively: ~/.codex/AGENTS.md (or AGENTS.override.md) first, then one file per directory from the git root down to your working directory, up to 32 KiB. Everything else lives in ~/.codex/config.toml (or a trusted project's .codex/config.toml): MCP servers under [mcp_servers.<name>], sandbox_mode (read-only, workspace-write, danger-full-access) and approval_policy (on-request or never). Command allow/forbid lists are .rules files. Sign in with ChatGPT to use your plan, or use an API key.

Codex CLI at a glance

Exact file paths

Using a shared AGENTS.md with Codex CLI

Native: nothing to do. Use AGENTS.override.md for temporary local overrides. See one AGENTS.md for every agent, or generate one with the AGENTS.md generator.

Copy-paste examples

Read CLAUDE.md too (fallback names)

File: ~/.codex/config.toml

project_doc_fallback_filenames = ["CLAUDE.md"]
project_doc_max_bytes = 65536

MCP server

File: ~/.codex/config.toml

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

PreToolUse hook output that denies a command

File: stdout of a .codex/hooks.json command

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by hook."
  }
}

Safe permissions preset

Safe Codex setup: workspace sandbox, no network, forbidden commands

File: ~/.codex/config.toml + ~/.codex/rules/default.rules

# ~/.codex/config.toml
sandbox_mode = "workspace-write"     # edits only inside the workspace
approval_policy = "on-request"       # ask before leaving the sandbox

[sandbox_workspace_write]
network_access = false               # no network for model-run commands

# ~/.codex/rules/default.rules  (separate file; test with `codex execpolicy check`)
prefix_rule(pattern = ["rm", ["-rf", "-fr"]], decision = "forbidden",
            justification = "No recursive deletes. Ask the user instead.")
prefix_rule(pattern = ["git", "push", ["--force", "-f", "--force-with-lease"]], decision = "forbidden",
            justification = "Never force-push.")
prefix_rule(pattern = ["git", "push"], decision = "prompt", justification = "Review before pushing.")
prefix_rule(pattern = ["git", "reset", "--hard"], decision = "forbidden")
prefix_rule(pattern = ["terraform", "destroy"], decision = "forbidden")
prefix_rule(pattern = ["kubectl", "delete"], decision = "prompt")

The config and the rules are two separate files (shown together here). Rules match command prefixes exactly: git push origin main --force does not match ["git", "push", "--force"]. Per the docs, rules govern commands that run outside the sandbox; inside workspace-write, sandboxed commands can still change workspace files without a prompt, so keep work committed. With network_access = false, a sandboxed psql … DROP TABLE cannot reach a remote database.

Gotchas

• approval_policy = "untrusted" is retired and can stop Codex from starting; remove it. Use on-request (interactive) or never (non-interactive).
• Codex includes at most one instruction file per directory and stops at 32 KiB by default. Raise project_doc_max_bytes or split files.
• Nested AGENTS.md files only load for directories between the repo root and the launch directory. Start Codex in the subfolder (codex --cd services/payments) to pick up its file.
• .codex/config.toml in a repo (MCP servers, settings) is only loaded once you trust the project.
• --yolo / danger-full-access removes the sandbox entirely. Only use it inside a disposable container or VM.

FAQ

Sources

Checked against these official pages on 2026-10-12. Cells marked "Not documented" mean we could not find the behaviour in these docs; it may still exist.

• Custom instructions with AGENTS.md
• Configuration reference
• Agent approvals & security
• Sandbox
• Rules
• MCP
• Skills
• Hooks
• Authentication