permissions.<name>.filesystem

People have been asking for a way to keep Codex out of .env files since the early releases. Issue #2847 collected 91 comments asking for a .codexignore, and #5237 documented Codex running List .. above the launch directory. Named permission profiles are the answer that shipped: a [permissions.<name>] table in config.toml with filesystem rules inside.

Values

Each key under filesystem is an absolute path or a special token, mapped to "read", "write", or "deny" (config reference). The ":workspace_roots" token holds workspace-relative rules: "." means the root itself, and glob subpaths like "**/*.env" work. One housekeeping key sits alongside the path rules: glob_scan_max_depth, a number that must be at least 1, capping how deep deny-read globs expand on platforms that snapshot matches before the sandbox starts.

default_permissions = "no-secrets"

[permissions.no-secrets]
description = "Workspace access, secrets denied"
extends = ":workspace"

[permissions.no-secrets.filesystem]
glob_scan_max_depth = 4
"/etc" = "read"

[permissions.no-secrets.filesystem.":workspace_roots"]
"**/*.env" = "deny"
"**/*.pem" = "deny"

Profiles inherit through extends: another named profile, :read-only, or :workspace. Setting it to :danger-full-access, an undefined parent, or a cycle gets rejected.

When to change it

1. Secrets in the repo. Deny **/*.env, **/*.pem, and key files under ":workspace_roots" and Codex can still edit code without reading credentials. This is the fix the #2847 crowd waited for.
2. Codex wandering upstream. If you have watched it read parent directories from a subfolder (the #5237 complaint), a profile scoped to workspace roots pins it down.
3. Monorepo with an off-limits subtree — deny that absolute path in one line.

Gotchas

• Don’t combine default_permissions with sandbox_mode or [sandbox_workspace_write]. The reference says to pick one approach.
• Deny-read globs get expanded before sandbox startup on some platforms. The docs don’t name which platforms this hits, and there’s no published glob_scan_max_depth default to fall back on. They also say nothing about whether a file created mid-session gets covered. Test on your OS before trusting it with real secrets.
• The docs mention a :minimal special token as a valid filesystem key but never define what it grants.

Related settings

• default_permissions picks which profile applies to sandboxed tool calls.
• permissions.<name>.network does the same job for domains and sockets.
• sandbox_mode covers the three built-in modes if you don’t need custom rules.