Approvals

Control when Codex requires human oversight for sensitive operations

The approval system gives you fine-grained control over when Codex can execute commands, modify files, or perform other sensitive operations without human oversight.

Approval policies

Codex supports four approval policies that determine when to prompt for permission:

on-request

On-request (recommended default):

• Prompts when the agent needs to escape the sandbox
• Auto-approves operations that stay within sandbox boundaries
• Balances safety and productivity

codex --ask-for-approval on-request "install dependencies"

Use for: General development work

unless-trusted

Unless-trusted:

• Always prompts for approval
• Skips prompts only for commands covered by execpolicy rules
• Maximum oversight

codex --ask-for-approval unless-trusted "make changes"

Use for: Sensitive codebases, production systems

never

Never:

• Never prompts for approval
• Auto-approves all operations (within sandbox limits)
• Fastest, least safe

codex --ask-for-approval never "run tests"

Use for: Sandboxed environments, trusted automation

on-failure

On-failure:

• Runs commands in sandbox first
• Only prompts if sandbox execution fails
• Optimistic execution

codex --ask-for-approval on-failure "build project"

Use for: Commands likely to succeed in sandbox

Approval prompts

When approval is required, you’ll see an interactive prompt with details about the operation:

Command execution approval

┌─ Command Approval Required ────────────────────────────┐
│ codex wants to run:                                    │
│   npm install express cors dotenv                      │
│                                                        │
│ Working directory: /Users/me/project                   │
│ Reason: Package installation requires network access   │
│                                                        │
│ Suggested rule: ["npm", "install"]                     │
│                                                        │
│ [a] Accept once                                        │
│ [s] Accept for session                                 │
│ [p] Accept and add to policy                           │
│ [d] Decline                                            │
│ [c] Cancel turn                                        │
└────────────────────────────────────────────────────────┘

File change approval

┌─ File Change Approval Required ────────────────────────┐
│ codex wants to modify:                                 │
│   • src/auth.ts (edit)                                 │
│   • src/middleware/rate-limit.ts (create)              │
│   • tests/auth.test.ts (edit)                          │
│                                                        │
│ Reason: Changes to authentication system               │
│                                                        │
│ [a] Accept                                             │
│ [d] Decline                                            │
└────────────────────────────────────────────────────────┘

Approval decisions

When prompted, you can choose from several approval levels:

1. Accept once

   Approve this specific operation only. The next similar operation will require approval again.

2. Accept for session

   Approve this operation and automatically approve identical operations for the rest of this session. Resets when you restart Codex.

3. Accept and add to policy

   Approve this operation and add an execpolicy rule so similar commands never require approval again (persists across sessions).

4. Decline

   Reject this operation. The agent will receive an error and may try an alternative approach.

5. Cancel turn

   Abort the entire current operation. The agent stops processing your request.

Execpolicy rules

Execpolicy is Codex’s policy engine for defining which commands are trusted. Rules are written in Starlark syntax and stored in .codex/execpolicy/ files.

Rule structure

# Allow npm install without approval
prefix_rule(
    pattern = ["npm", "install"],
    decision = "allow",
    justification = "Package installation is routine and safe in sandbox"
)

# Always prompt for git push
prefix_rule(
    pattern = ["git", "push"],
    decision = "prompt",
    justification = "Pushing code requires review"
)

# Forbid rm -rf
prefix_rule(
    pattern = ["rm", "-rf"],
    decision = "forbidden",
    justification = "Use git clean or individual file removal instead"
)

Decision levels

• allow - Auto-approve matching commands (no prompt)
• prompt - Always prompt for approval
• forbidden - Never allow (show justification to agent)

Pattern matching

Patterns match command prefixes in order:

# Matches: cargo test
# Matches: cargo test --all
# Doesn't match: cargo build
prefix_rule(
    pattern = ["cargo", "test"]
)

# Alternatives using lists
prefix_rule(
    pattern = ["git", ["pull", "fetch"]]
)
# Matches: git pull
# Matches: git fetch
# Doesn't match: git push

Host executables

Constrain which absolute paths can match basename rules:

host_executable(
    name = "git",
    paths = [
        "/usr/bin/git",
        "/opt/homebrew/bin/git"
    ]
)

With this definition:

• /usr/bin/git status can match ["git", "status"] rules
• /usr/local/bin/git status cannot (not in allowed paths)

Testing rules

Add inline tests to validate your rules:

prefix_rule(
    pattern = ["npm", "run", ["dev", "start"]],
    decision = "allow",
    # These should match
    match = [
        ["npm", "run", "dev"],
        "npm run start"
    ],
    # These should not match
    not_match = [
        ["npm", "run", "build"],
        "npm install"
    ]
)

Checking rules

Test a command against your policies:

codex execpolicy check \
  --rules ~/.codex/execpolicy/default.rules \
  --pretty \
  npm install express

Output:

{
  "matchedRules": [
    {
      "prefixRuleMatch": {
        "matchedPrefix": ["npm", "install"],
        "decision": "allow",
        "justification": "Package installation is routine and safe in sandbox"
      }
    }
  ],
  "decision": "allow"
}

Configuration

Configure approval behavior in ~/.codex/config.toml:

# Global approval policy
approval_policy = "on-request"  # never | on-request | unless-trusted | on-failure

# Execpolicy files to load
[execpolicy]
user_rules = [
  "~/.codex/execpolicy/default.rules",
  "~/.codex/execpolicy/project-specific.rules"
]

Per-project configuration

Create project-specific rules in your repository:

# Project root
.codex/
  execpolicy/
    rules.star  # Project-specific rules

Codex automatically loads rules from .codex/execpolicy/ in your working directory.

Convenience flags

Codex provides shortcuts for common approval configurations:

Full-auto mode

Combines --ask-for-approval on-request with --sandbox workspace-write:

codex --full-auto "set up development environment"

This is ideal for:

• Sandboxed CI/CD environments
• Development tasks in trusted directories
• Quick prototyping

YOLO mode (dangerous)

Completely bypasses approvals and sandboxing:

codex --yolo "install system packages"

NEVER use --yolo on untrusted inputs or in production. This disables all safety checks. Only use in externally sandboxed environments.

Approval prompts in app-server

When using the app-server API, approval requests are JSON-RPC requests that clients must respond to:

Command approval request

{
  "method": "item/commandExecution/requestApproval",
  "id": 42,
  "params": {
    "threadId": "thr_123",
    "turnId": "turn_456",
    "itemId": "cmd_789",
    "command": ["npm", "install", "express"],
    "cwd": "/Users/me/project",
    "reason": "Package installation requires network access",
    "proposedExecpolicyAmendment": {
      "prefix": ["npm", "install"]
    }
  }
}

Client response

{
  "id": 42,
  "result": {
    "decision": "accept"  // accept | acceptForSession | acceptWithExecpolicyAmendment | decline | cancel
  }
}

Best practices

Start with on-request

Provides good balance between safety and usability

Build execpolicy rules incrementally

Add rules as you approve common operations

Review policy suggestions

Carefully examine suggested rules before accepting

Use unless-trusted for sensitive work

Maximum oversight for production or critical systems

Test rules before deploying

Use codex execpolicy check to validate rules

Document justifications

Add clear justifications to help future you understand rules

Advanced: Network approval

Codex can prompt for network access on a per-host basis:

┌─ Network Access Required ──────────────────────────────┐
│ codex wants to connect to:                             │
│   registry.npmjs.org                                   │
│                                                        │
│ [a] Accept once                                        │
│ [s] Accept for session                                 │
│ [p] Allow this host permanently                        │
│ [d] Decline                                            │
└────────────────────────────────────────────────────────┘

Network approvals integrate with the same decision levels as command approvals.

Troubleshooting

Approval prompts not appearing

Check your approval policy:

codex -c approval_policy=unless-trusted "test"

Or verify config:

# ~/.codex/config.toml
approval_policy = "unless-trusted"

Too many approval prompts

Build execpolicy rules to auto-approve trusted commands:

• Accept with [p] when prompted to create rules
• Manually write rules in .codex/execpolicy/
• Use --ask-for-approval on-request instead of unless-trusted

Policy rules not matching

Test your rules explicitly:

codex execpolicy check --rules ~/.codex/execpolicy/default.rules npm install

Check pattern syntax and ensure prefixes match exactly.

Session approvals reset too quickly

Session approvals only last for the current thread. Use execpolicy rules for persistent approvals across sessions.

Next steps

Sandboxing

Understand how sandboxing complements approvals

Non-interactive mode

Use approvals in automation