Codex / Configuration
Codex permissions
Learn how to migrate Codex permission profiles for file system, network, path, glob, Unix socket and old sandbox settings.
What does permission configuration solve?
Codex permissions use profiles to describe the local access boundaries of a session. It is more granular than setting sandbox_mode alone and can simultaneously express file system readable and writable ranges, network access rules, Unix socket exceptions, and reusable workspace roots.
If you just choose a simple mode, you can continue to use read-only, workspace-write, or danger-full-access. If the team needs fine-grained rules such as "this project is writable, these directories are read-only, .env is never readable, and only access to specified domain names are allowed", permission profiles should be used.
File system permissions
File system entries use read, write, deny. More specific entries override broader entries; deny takes precedence over write, and write takes precedence over read on the same path.
The above configuration sets the minimum platform path required to run the tool as read-only, making the workspace root writable, while keeping the .devcontainer read-only and disabling reading of any .env files. This is more suitable for long-term team configurations than "the entire project is writable and readable".
[permissions.project-edit.filesystem]
":minimal" = "read"
[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
".devcontainer" = "read"
"**/*.env" = "deny"| access level | meaning | Typical uses |
|---|---|---|
| read | The command is allowed to read files and column directories, but not create, modify, rename, or delete them. | Documentation, dependent source code, shared libraries, read-only reference materials. |
| write | Allows reading and modifying files under the path, including creation, renaming and deletion. | The current project workspace, the generated output directory, and the subprojects that need to be edited are specified. |
| deny | Deny both reads and writes, used to poach sensitive subpaths from wider authorizations. | .env, keys, private configurations, irrelevant repositories. |
Supported path forms
The permission profile supports built-in path aliases, absolute paths, and home relative paths. :workspace_roots can write nested subpaths, and the subpaths must remain within the workspace root.
[permissions.audit.filesystem]
":root" = "read"
[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
"docs" = "read"
"generated" = "deny"| path form | meaning | Whether to support subpaths |
|---|---|---|
| :root | File system root directory. Use only if broad read coverage is truly required. | Only . |
| :minimal | The platforms and runtime paths required to run common tools. | Only . |
| :workspace_roots | The current session workspace roots and workspace roots defined by the profile. | support |
| :tmpdir / :slash_tmp | System temporary directory or /tmp. | Only . |
| /absolute/path | Platform absolute path, such as /path for macOS/Linux or C:\path for Windows. | support |
| ~/path | The path under the current user's home; Windows also supports ~\work. | support |
Use deny to protect sensitive files
When the location of sensitive files is not fixed, using deny glob is more practical than listing exact path. Globs placed under :workspace_roots will be interpreted relative to each valid workspace root.
deny glob is mainly used to deny reading. The read/write glob is less portable across different platform sandboxes, so read and write authorization preferentially uses exact path or subtree rules.
On Linux, WSL and native Windows, unbounded ** deny-read may need to be pre-expanded before the sandbox is started. glob_scan_max_depth controls the scan depth. The higher the value, the more scanning work is done before starting.
[permissions.project-edit.filesystem]
glob_scan_max_depth = 3
[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"Reuse workspace roots
When a profile always needs to handle multiple directories at the same time, reusable workspace roots can be declared in the profile. When activated, the :workspace_roots rule applies to both runtime roots and profile roots.
This is suitable for scenarios where monorepo plus shared libraries, front-end and back-end repository joint debugging, and document and product repositories are modified together. Do not use parent traversal such as ../other-repo; the official policy will reject nested sub-paths that leave the workspace root.
[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = trueNetwork permissions
Set enabled = true in the profile to allow the network. After the network is opened, the default is full network behavior, so most profiles should continue to define domain name rules.
exact host only matches itself, *.example.com only matches subdomains, and **.example.com matches both apex and subdomains. deny takes precedence over allow and is used to exclude advertising, tracking, production, or sensitive endpoints.
Network proxy listening settings such as proxy_url, socks_url, enable_socks5, etc. are usually left at default unless you are integrating with a specific runtime. dangerously_* network keys are special escape hatches and are not suitable for ordinary local development.
[permissions.project-edit.network]
enabled = true
[permissions.project-edit.network.domains]
"example.com" = "allow"
"*.example.com" = "allow"
"**.example.com" = "allow"
"ads.example.com" = "deny"Local and private network
Codex protects local/private network targets by default, reducing the risk of DNS rebinding and mistaken access to local services. If you really need to access local services, give priority to allowing localhost or IP literal.
Set allow_local_binding = true only if the profile must access an allowlisted host that resolves to a local or private address. Generic domain name rules should not be treated as exceptions for local access.
[permissions.project-edit.network]
enabled = true
allow_local_binding = true
[permissions.project-edit.network.domains]
"localhost" = "allow"
"127.0.0.1" = "allow"Unix sockets
Unix socket is suitable for local tools such as Docker, but it is also a powerful entry point and should be enabled with caution. Socket paths can be explicitly allowed or denied.
Denied sockets are removed from the effective allowlist. When the Unix socket proxy is enabled, the listening endpoint should still maintain loopback to avoid exposing local capabilities as a remote entry.
[permissions.project-edit.network.unix_sockets]
"/var/run/docker.sock" = "allow"
"/tmp/old.sock" = "deny"Migrate from old setup
Permission profiles are suitable to replace the old sandbox_mode + sandbox_workspace_write combination, especially if you want to reuse a set of profiles that describe both file system and network behavior. It is recommended to use one system at a time, do not mix them.
| target | Recommended starting point | Description |
|---|---|---|
| Read-only workflow | :read-only or custom read-only profile | Only open the necessary reading range, suitable for reviewing and understanding the code. |
| Workspace editing | :workspace or custom project-edit profile | Write the project through :workspace_roots and only open the necessary cache/temporary directories. |
| Unlimited local execution | :danger-full-access | Use only if you clearly require the widest access model and the external environment is isolated. |
Corporate constraints still take precedence
A permission profile describes a user's local default posture, but organization-managed requirements can still add restrictions that cannot be relaxed by user configuration.
Study Checklist
Put the content on this page into real tasks and use the five dimensions of entry, context, permissions, verification and team rules to check whether you have truly mastered it.
Study Checklist
After reading this page, do not just remember the concept name. You should be able to place "Codex permissions" back into a real Codex engineering workflow: where the task starts, what context the system loads, which actions need approval, how the result is verified, and how to roll back when it fails.
If this is a configuration or reference page, be specific about where the configuration is placed, whether it will be submitted, whether it contains sensitive information, whether it will extend the default permissions, and how to troubleshoot the settings that actually took effect in the event of a failure.
- Be able to describe in your own words the specific problem this page solves, rather than just reciting the title.
- Able to write a minimal example task with goals, scope, prohibitions, and acceptance criteria.
- Be able to determine which information should be put into the current prompt and which should be captured as project rules or configurations.
- Be able to explain which long-term rules should go into AGENTS.md, and which runtime behavior should be handled by config.toml, permission profile, skills and MCP.
- Ability to check diffs, command output, test results, screenshots or PR notes after a task is completed instead of just trusting the natural language summary.
If this page is used for team training, ask learners to complete a small task with Codex: read and explain first, submit a plan, make the smallest useful change, and close with real verification commands plus human diff review.
Codex practical notes
Fill in the most overlooked execution details of Codex usage around local environments, privilege escalation, remote entry, automation failures, and rollbacks.
Codex Practical Notes
This page affects the default behavior of Codex. Before configuring, determine whether it will expand file writing, network access, tool invocation, or silent execution capabilities, and retain audit and rollback methods for the team.
When handling tasks related to "Codex permissions", always confirm the current Git status and working directory first. Codex can make changes quickly, but it does not automatically know which uncommitted edits came from the user, which files are off limits, or which commands may affect production.
- Prioritize using low-risk branches or working trees for local tasks, and review them with git diff after completion.
- When it comes to installation dependencies, networking, databases, deployment, push, deletion, and reset, Codex must first be asked to explain the impact before approval.
- Results generated by remote or collaborative portals must also be confirmed back to PR, CI, build logs and test evidence.
- Automated tasks must define failure output and exit conditions in advance to avoid Codex repeatedly trying in the wrong direction.
Think of Codex as an engineering teammate who can execute commands, rather than an assistant who can only write text. The closer you get to a real system, the greater the need for clear boundaries, evidence, and rollbacks.