rules.md Codex Docs, 2026-02-19 20:37 UTC → 2026-05-13 00:57 UTC

1# Rules1# Rules

2 2 

3Control which commands Codex can run outside the sandbox

4 

5Use rules to control which commands Codex can run outside the sandbox.3Use rules to control which commands Codex can run outside the sandbox.

6 4 

7Rules are experimental and may change.5Rules are experimental and may change.

8 6 

9## Create a rules file7## Create a rules file

10 8 

111. Create a `.rules` file under `./codex/rules/` (for example, `~/.codex/rules/default.rules`).91. Create a `.rules` file under a `rules/` folder next to an active config layer (for example, `~/.codex/rules/default.rules`).

122. Add a rule. This example prompts before allowing `gh pr view` to run outside the sandbox.102. Add a rule. This example prompts before allowing `gh pr view` to run outside the sandbox.

13 11 

14 ```python12 ```python

36 ],34 ],

37 )35 )

38 ```36 ```

37 

393. Restart Codex.383. Restart Codex.

40 39 

41Codex scans `rules/` under every [Team Config](https://developers.openai.com/codex/enterprise/admin-setup#team-config) location at startup. When you add a command to the allow list in the TUI, Codex writes to the user layer at `~/.codex/rules/default.rules` so future runs can skip the prompt.40Codex scans `rules/` under every active config layer at startup, including [Team Config](https://developers.openai.com/codex/enterprise/admin-setup#team-config) locations and the user layer at `~/.codex/rules/`. Project-local rules under `<repo>/.codex/rules/` load only when the project `.codex/` layer is trusted.

41 

42When you add a command to the allow list in the TUI, Codex writes to the user layer at `~/.codex/rules/default.rules` so future runs can skip the prompt.

42 43 

43When Smart approvals are enabled (the default), Codex may propose a44When Smart approvals are enabled (the default), Codex may propose a

44`prefix_rule` for you during escalation requests. Review the suggested prefix45`prefix_rule` for you during escalation requests. Review the suggested prefix

45carefully before accepting it.46carefully before accepting it.

46 47 

47Admins can also enforce restrictive `prefix_rule` entries from48Admins can also enforce restrictive `prefix_rule` entries from

48[`requirements.toml`](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml).49[`requirements.toml`](https://developers.openai.com/codex/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml).

49 50 

50## Understand rule fields51## Understand rule fields

51 52 

58 - `allow`: Run the command outside the sandbox without prompting.59 - `allow`: Run the command outside the sandbox without prompting.

59 - `prompt`: Prompt before each matching invocation.60 - `prompt`: Prompt before each matching invocation.

60 - `forbidden`: Block the request without prompting.61 - `forbidden`: Block the request without prompting.

61- `justification` **(optional)**: A non-empty, human-readable reason for the rule. Codex may surface it in approval prompts or rejection messages. When you use `forbidden`, include a recommended alternative in the justification when appropriate (for example, `"Use \`rg` instead of `grep`.”`).62- `justification` **(optional)**: A non-empty, human-readable reason for the rule. Codex may surface it in approval prompts or rejection messages. When you use `forbidden`, include a recommended alternative in the justification when appropriate (for example, `"Use \`rg\` instead of \`grep\`."`).

62- `match` and `not_match` **(defaults to `[]`)**: Examples that Codex validates when it loads your rules. Use these to catch mistakes before a rule takes effect.63- `match` and `not_match` **(defaults to `[]`)**: Examples that Codex validates when it loads your rules. Use these to catch mistakes before a rule takes effect.

63 64 

64When Codex considers a command to run, it compares the command's argument list to `pattern`. Internally, Codex treats the command as a list of arguments (like what `execvp(3)` receives).65When Codex considers a command to run, it compares the command's argument list to `pattern`. Internally, Codex treats the command as a list of arguments (like what `execvp(3)` receives).