Codex permissions define which files local commands can read or change and where they can connect. Beta permission profiles and the older sandbox_mode settings are alternative configuration systems, not two layers of the same stack. Approval policy remains separate: it controls when approval is required or refused, while approvals_reviewer selects human or automatic review where available.
For the wider file-handling workflow, compare chat attachments with agent workspace access.
How Codex permissions work
Codex permissions govern what local commands can read, write and reach over the network during a coding session. The current system, documented as Beta and in active development, uses permission profiles that bundle filesystem rules and network rules into a single named configuration. The official permissions documentation describes the current built-in profiles, custom profile syntax, path scope and configuration-layer behaviour.
A permission profile defines the filesystem and command-network boundary for local commands. Approval policy separately determines when approval is required and whether an action can be escalated. Where supported, approvals_reviewer determines who reviews an eligible request.
The effective workspace for a session comprises the current runtime workspace roots plus any roots deliberately added by a profile. This is not universally the same as the current working directory or the repository root. The runtime determines which paths are initially visible, and a profile can extend or restrict that set.
Permission profiles, legacy settings and approvals
Two configuration systems define the command boundary, while approval policy governs eligible review:
| Question | Control | What it decides |
|---|---|---|
| Which filesystem and command-network rules define the boundary? | Beta permission profile, or legacy sandbox_mode | Use one configuration model for the session rather than stacking both |
| Is this path or network destination inside the selected Beta profile? | Permission profile | Read, write, deny and command-network scope |
| When is approval required or escalation refused? | Approval policy | Whether an action needs approval and can be escalated |
| Who reviews an eligible escalation? | approvals_reviewer | Human or automatic review, where available |
The selected configuration defines the technical boundary around local commands. The Codex sandbox documentation covers legacy modes, platform enforcement and spawned-command inheritance. For a full explanation of those boundaries, understand the Codex sandbox boundary.
Beta permission profiles define filesystem and command-network scope directly. Approval policy still applies: an action can require approval even inside the sandbox, and not every blocked action is eligible for escalation. The reviewer setting changes who evaluates an eligible request, not the boundary itself.
A Git worktree isolates a branch and checkout for parallel coding work, but it is not a filesystem security boundary. The worktree documentation describes its purpose as enabling parallel development, not as a containment mechanism.
Built-in profiles and effective workspace roots
The current built-in profiles, as of 12 September 2026, are:
- :read-only: command writes are blocked and command-network access is disabled. The name does not confine reads to the workspace; check explicit read restrictions.
- :workspace: commands can write to active workspace roots and system temporary locations, with protected subdirectories kept read-only. Command-network access is disabled by default. Reads are not automatically limited to the workspace.
- :danger-full-access: commands can read and write anywhere the operating system permits and can access the network. This profile removes the filesystem and network constraints that the other profiles impose.
These colon-prefixed profile names are distinct from the legacy sandbox-mode names. They belong to different configuration systems and should not be conflated. A profile is a named bundle of rules; a sandbox mode is a legacy setting that controls the technical boundary.
Custom profiles can express specific read, write, deny and network scope. For example, a profile might grant read access to a project directory, write access to a build output directory, deny access to a credentials directory, and permit network access to a specific package registry domain. The exact syntax and precedence rules are documented in the official permissions reference and should be checked before configuring access because the feature is in active development.
Filesystem and command-network decisions
Filesystem rules use path matching. A more specific filesystem path can override a broader path rule. When two rules match at the same level of specificity, the resolution is conservative: deny takes precedence over write, and write takes precedence over read. If a deny rule and a read rule both match the same path at equal specificity, the deny wins.
For example, if a profile grants read access to a project directory and a deny rule targets a secrets subdirectory within it, the deny rule is more specific and takes effect for that subdirectory. If both a deny and a write rule target the same output directory at the same specificity, the deny wins.
Command-network access is a separate surface from web search, connectors, MCP servers, the in-app browser, computer use and cloud execution. A local permission profile governs only local commands. Enabling command networking does not by itself start the documented managed-network proxy. Domain filtering requires both command networking and the active proxy path; without that proxy, domain rules do not constrain direct command traffic.
When designing permissions around the wider agent harness, consider that a coding agent may interact with multiple surfaces. The agent harness overview explains how these surfaces relate and why a single permission profile does not cover all of them.
When an action can be reviewed, denied or refused
The approvals and security documentation describes how approval policy interacts with the sandbox and permission boundaries. The key points:
- Being inside the sandbox boundary does not guarantee prompt-free execution; approval policy and other controls still apply.
- An action that falls outside the scope may be denied outright if the approval policy is set to refuse.
- An action outside the scope may become eligible for review if approval policy permits escalation.
- An approval prompt is not guaranteed for every blocked action. The policy determines the outcome.
- The
approvals_reviewersetting selects human or automatic review where available. It does not widen the boundary or establish that an action is safe.
Read the exact scope shown by an approval prompt. An approval may cover one action, a session or a supported command prefix, depending on the current interface and policy. None of those outcomes is an absolute statement that the action is safe.
How to diagnose a permission-denied or blocked task
When a task is blocked, the cause may lie in any of several layers. The following decision path helps isolate the issue:
- Identify the exact failed action and resource. What command was attempted, what path or domain was targeted, and what was the error message?
- Decide which layer is responsible. Is the issue sandbox scope, a permission rule, approval policy, host operating-system access, or network policy?
- Confirm which configuration layer supplies the active rule. Check whether a managed policy, a project-level profile or a session-level override is in effect.
- Narrow the requested exception to the task. If the fix is to add a path or domain, use the narrowest match that solves the immediate task rather than a broad wildcard.
- Retry on recoverable material. If the blocked action was non-destructive, retry after the configuration change. If it was destructive or irreversible, assess whether the task can be redesigned.
- Verify what changed in effective access. After the fix, confirm that the intended action now succeeds and that no unintended paths or domains were opened.
Plan the access a task actually needs
Use this table to map a task to the narrowest permission decision before configuring a profile:
For example, if reading /project/config/app.yaml is blocked but editing source works, inspect the loaded read rule rather than broadening write access. If Codex proposes an edit outside the project, verify the target path and the applicable deny, review or allow outcome before approving it.
| Task | Resource needed | Smallest useful access | Verify |
|---|---|---|---|
| Read configuration | /project/config/app.yaml | Read the required file | Effective rule and observed read |
| Write build output | /project/dist/ | Write only to the intended output directory | Output appears in the expected location |
| Fetch a package | registry.example.com | Command networking plus a domain rule through the active managed proxy | Required request works; unrelated destination remains blocked |
| Read a shared library | /shared/libs/ | A narrow read rule if current scope excludes it | Read works; writes remain blocked |
| Use a secret | Intentionally restricted credential | Keep the deny; use an approved secret-injection route | Task works without exposing the credential file |
These are synthetic examples. Test with non-sensitive resources, then configure the exact paths your task requires. Keep credential locations restricted and avoid broad allow rules.
How to reduce prompt fatigue without removing the boundary
Repeated approval prompts can slow a workflow, but the response should be to narrow the rules, not to remove the boundary. Practical approaches:
- Use a task-specific workspace root. If a task only needs access to one directory, scope the profile to that directory rather than the entire repository.
- Add a narrowly matched rule. If a specific domain or path is needed for a bounded task, add a rule that matches only that target.
- Keep approval policy and reviewer choice separate. Choose when review is needed, then use human or automatic review where supported. OpenAI's automatic approval review documentation explains the reviewer setting and its limits.
- Use read-focused automation for inspection tasks. For tasks that need no edits, use a read-only profile to block writes. Other rules or actions may still prompt or deny.
- Isolate disposable work in a verified environment. For experiments that need broader access, use a separately isolated environment whose boundary has been verified, rather than expanding the primary workspace.
See how to turn these controls into day-to-day AI use rules for a broader framework.
If you are working with Claude Code rather than Codex, the permission model differs in terminology and evaluation order. You can compare Claude Code permission controls to understand the parallels and distinctions.
Documents placed in a Codex-accessible workspace
Granting Codex access to a reference directory answers where it can work. Choosing which outside documents belong there is a separate decision. .mdSiren checks incoming versions for supported prompt-injection and document-borne risks, returns Approved, Needs review or Quarantine, and keeps the current eligible Approved copy ready for retrieval and reuse.
An accepted replacement needs its own check; .mdSiren stops supplying the earlier copy while the replacement is pending or held. These retrieval controls apply to files supplied through .mdSiren, not every file Codex can reach.
Pro API access lets authorised agents submit documents, check status and retrieve eligible Approved exact versions under scoped account permissions. See the document checkpoint, or Coming soon. Decisions cover the reported checks, and Quarantine is a document-handling state—not an operating-system restriction.
What bypassing Codex permissions changes
If repeated prompts or a blocked build are slowing you down, identify the exact capability the task needs. A narrow path rule, a one-time approval or an isolated test environment may resolve it without opening unrelated files and services.
An effective no-check, full-access configuration can remove command-boundary and approval protections and materially expand the possible impact of a mistake or a malicious instruction in a document. Depending on the host environment, the consequences can include:
- Commands can read and write any file the operating system permits, including credentials, keys and unrelated private data.
- Codex's command-network restrictions are removed; host and network controls may still block destinations.
- No approval prompt appears for out-of-bound actions, so a mistake or an injected instruction can proceed without human review.
- The separation between an enforced boundary and a review decision is lost.
Identify the specific blocked capability and add the narrowest rule or root that resolves the task. This preserves the boundary for everything else.
Frequently asked questions
What are Codex permissions?
Codex permissions govern which local files commands can read or change and which network destinations they can reach. Beta permission profiles configure the command sandbox as an alternative to legacy sandbox settings. Approval policy controls when approval is required; the reviewer setting controls who evaluates eligible requests.
Why is Codex asking for approval?
An approval prompt can appear when an eligible action falls outside the active scope and the approval policy permits review. Read the scope carefully: the available decision may apply once, for the session or to a supported command prefix. A prompt is not proof that the action is unsafe, and approval is not proof that it is safe.
How do workspace roots affect Codex file access?
Under a Beta permission profile, effective file access comes from its workspace roots, added roots and read, write or deny rules. This is different from the legacy workspace-write setting, whose name limits writes rather than promising that reads are confined to the project. Check which system is active before drawing a conclusion.
Can I let Codex use a second directory without granting broad access?
Yes. You can add a specific directory as a read-only or read-write root in a custom profile. The rule should match the narrowest path that the task requires. This extends access to that directory without opening the entire filesystem or removing other deny rules.
What is the difference between Codex permissions and the sandbox?
Beta permission profiles and legacy sandbox settings are alternative ways to configure the local command boundary. Approval policy separately determines whether an eligible action outside that boundary can be reviewed or is refused. Do not stack the two configuration models in one mental picture.
Should I bypass or disable Codex permissions?
Disabling permissions or using an unrestricted profile removes protections that can limit mistakes and hostile instructions. Identify the specific blocked capability and grant the smallest bounded access that solves the task. This keeps the boundary intact for everything else and preserves review for genuinely out-of-scope actions.
