Approvals

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
unless-trusted
never
on-failure

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:

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 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:

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:

Accept once

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

Accept for session

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

Accept and add to policy

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

Decline

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

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.

Get Started

Core Concepts

Configuration

Features

Advanced Usage

Approval policies

Approval prompts

Command execution approval

File change approval

Approval decisions

Execpolicy rules

Rule structure

Decision levels

Pattern matching

Host executables

Testing rules

Checking rules

Configuration

Per-project configuration

Convenience flags

Full-auto mode

YOLO mode (dangerous)

Approval prompts in app-server

Command approval request

Client response

Best practices

Start with on-request

Build execpolicy rules incrementally

Review policy suggestions

Use unless-trusted for sensitive work

Test rules before deploying

Document justifications

Advanced: Network approval

Troubleshooting

Next steps

Sandboxing

Non-interactive mode

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Features

Advanced Usage

Documentation Index

​Approval policies

​Approval prompts

​Command execution approval

​File change approval

​Approval decisions

​Execpolicy rules

​Rule structure

​Decision levels

​Pattern matching

​Host executables

​Testing rules

​Checking rules

​Configuration

​Per-project configuration

​Convenience flags

​Full-auto mode

​YOLO mode (dangerous)

​Approval prompts in app-server

​Command approval request

​Client response

​Best practices

Start with on-request

Build execpolicy rules incrementally

Review policy suggestions

Use unless-trusted for sensitive work

Test rules before deploying

Document justifications

​Advanced: Network approval

​Troubleshooting

​Next steps

Sandboxing

Non-interactive mode

Build docs developers (and LLMs) love

Approval policies

Approval prompts

Command execution approval

File change approval

Approval decisions

Execpolicy rules

Rule structure

Decision levels

Pattern matching

Host executables

Testing rules

Checking rules

Configuration

Per-project configuration

Convenience flags

Full-auto mode

YOLO mode (dangerous)

Approval prompts in app-server

Command approval request

Client response

Best practices

Advanced: Network approval

Troubleshooting

Next steps