Codex does not have one single “permission mode.” Current Codex safety is built from two decisions:
- Approval policy: when should Codex stop and ask?
- Sandbox mode: what can generated commands access?
Treating those as separate controls is the key to configuring Codex safely. A restrictive sandbox can limit damage even when approvals are rare. Frequent approvals do not make an unrestricted environment safe by themselves.
The current Codex configuration reference is the source of truth for the accepted values. This article explains how to turn those values into a working policy.
The short answer
For normal work in a repository, start with:
approval_policy = "on-request"
sandbox_mode = "workspace-write"
This lets Codex read and edit the workspace while keeping broader actions behind an explicit request. Use a read-only sandbox for analysis, and use unrestricted access only inside an environment you intentionally isolated.
Approval policy controls interruptions
approval_policy determines when Codex can surface a request before it continues.
| Policy | What it means | Good fit |
|---|---|---|
untrusted | Treat generated commands conservatively and require trust for more actions | Unfamiliar repositories or exploratory sessions |
on-request | Let Codex request approval when an action needs it | Normal interactive development |
never | Do not surface approval prompts | Non-interactive or tightly controlled automation |
| granular policy | Allow or reject specific prompt categories independently | Managed or carefully tuned environments |
The older on-failure value is deprecated. Do not copy it from old configuration examples.
Granular approvals can independently control categories such as sandbox escalation, rules, MCP elicitations, permission requests, and skill approvals. They are useful when “ask for everything” and “ask for nothing” are both too blunt.
Sandbox mode controls the boundary
sandbox_mode determines which filesystem and network operations command execution can perform.
| Sandbox | Boundary | Good fit |
|---|---|---|
read-only | Commands can inspect but not modify the workspace | Audits, planning, and investigation |
workspace-write | Commands can modify the workspace within configured writable roots | Most implementation tasks |
danger-full-access | The normal sandbox boundary is removed | Disposable or externally isolated environments |
In workspace-write, outbound network access and additional writable roots can be configured separately. That is more precise than granting unrestricted access because one package install or integration needs an exception.
Read the official sandbox documentation before widening the boundary on a shared machine or a repository that contains sensitive material.
Safe combinations for real work
Planning or reviewing unfamiliar code
approval_policy = "untrusted"
sandbox_mode = "read-only"
Use this when you want a dependency audit, architecture explanation, or change plan without file edits. The important property is the read-only boundary, not the number of prompts.
Normal implementation in a repository
approval_policy = "on-request"
sandbox_mode = "workspace-write"
This is the useful middle ground. Codex can edit, test, and format within the project while requesting permission when an action falls outside the current boundary.
Automated checks in a prepared environment
approval_policy = "never"
sandbox_mode = "workspace-write"
This can work for CI or repeatable tasks when the command, repository, credentials, and writable roots are already controlled. never is not a shortcut for trusting unknown commands.
Isolated experiments
approval_policy = "never"
sandbox_mode = "danger-full-access"
Use this combination only when the surrounding machine or container is the real sandbox. A disposable container with limited credentials is a defensible boundary; a daily workstation with broad secrets is not.
Where Codex reads these settings
Your personal defaults live in:
~/.codex/config.toml
A trusted repository can add project-scoped settings at:
.codex/config.toml
The configuration basics document the current precedence, highest first:
- CLI flags and
--configoverrides - Project
.codex/config.tomlfiles, closest directory first - A selected profile
- User configuration
- System configuration
- Built-in defaults
This explains a common source of confusion: editing the user file does not change an active run that was launched with a stronger CLI override.
Project configuration is ignored when the project is untrusted. That prevents a repository from silently loading its own Codex hooks, rules, or settings before you trust it.
Check the active configuration before debugging
In the interactive CLI, use /status to inspect the current session and /permissions to select the permissions that fit the task. When a setting appears to be ignored, check for a CLI flag, a project-level file, or a selected profile before rewriting the user config.
For deeper installation, authentication, configuration, and runtime diagnostics, the current command reference includes:
codex doctor
That is a better first step than deleting configuration or credentials blindly.
Four rules that matter more than the labels
1. Keep credentials outside the repository
Do not paste API keys, access tokens, private certificates, or production secrets into prompts or checked-in configuration. A sandbox limits command access; it does not make exposed credentials harmless.
2. Review scope before granting scope
If a task needs one extra writable directory or network access, grant that capability specifically when possible. Do not jump immediately from workspace access to an unrestricted machine.
3. Separate exploration from execution
Use a read-only pass to understand an unfamiliar change. Then start an implementation pass with a clearly defined workspace boundary. This produces better plans and fewer surprise edits.
4. Let the environment carry the strongest boundary
For high-autonomy work, use a worktree, container, limited service account, or disposable VM. Approval prompts are a user-interface control. Isolation is the stronger technical control.
What this control model looks like in a business workflow
The same separation matters when AI can update customer, finance, support, or operations systems. The interface changes, but the control questions do not:
| Codex control | Business workflow equivalent | Why it matters |
|---|---|---|
| Approval policy | Which proposed actions need a named human decision | High-impact or ambiguous work cannot move forward by habit |
| Sandbox boundary | Which data, tools, and write actions the workflow can access | A useful automation should not inherit more authority than its task requires |
| Status and logs | Source evidence, decision history, and recovery context | Operators need to understand what happened before approving, correcting, or rolling back |
| Isolated environment | A bounded first release with limited users and consequences | Responsibility can expand only after real cases show where the workflow is reliable |
If the operator needs a shared queue to inspect proposed actions, resolve exceptions, and record decisions, the system needs an operator interface. If the work mainly moves information and states between existing systems, it needs an orchestrated workflow. Both should begin with a narrow release and explicit human authority rather than blanket autonomy.
How this connects to the rest of Codex
- For installation and editor setup, use the Codex VS Code extension guide.
- For choosing between direct local work, worktrees, and remote containers, see Codex local versus cloud workflows.
- For shared MCP configuration, use the Codex MCP TOML guide.
- For a practical end-to-end workflow, read the Codex CLI and VS Code integration guide.
Final recommendation
Start with on-request plus workspace-write. Move toward read-only when you need stronger protection, or toward fewer prompts only after you have reduced the environment’s real blast radius.
The right question is not “Which mode is fastest?” It is: “What should this task be allowed to change, and where should a human decision still be required?”