Codex CLI v0.170 and when a permissions profile loses to sandbox_mode

Codex Published:

v0.170.0 fixes child threads losing sandbox restrictions, and the docs now explain permission profiles. Here is when sandbox_mode makes a profile silently ignored.

Verified on Nov 23, 2026 Verified with Codex CLI v0.170.0 These tools change quickly. Please also check the latest official documentation. How articles are researched and verified
Contents
  1. The lost sandbox restrictions fixed in v0.170.0
  2. Writing a permission profile
  3. A leftover sandbox_mode makes default_permissions ignored
  4. Filesystem rules and the deny pitfall
  5. Summary

Codex CLI v0.170.0 is the release that fixes sandbox restrictions being lost. The failure was in the permissive direction, so there is no reason to defer it.

The documentation was updated alongside it, adding an explanation of permission profiles and filesystem rules. Read it and you find something important: the conditions under which a profile you wrote is ignored outright. Without knowing them, there is no way to tell why your configuration does nothing.

KEY POINT

What you will learn

  • What the "lost sandbox restrictions" fixed in v0.170.0 actually was
  • How to write a permission profile, and how the three built-ins differ
  • When a leftover sandbox_mode makes default_permissions ignored

The lost sandbox restrictions fixed in v0.170.0

The release note reads:

Fixed permission updates and child threads losing existing sandbox restrictions.

Permission updates and child threads were dropping restrictions that were already in force. For child threads, the docs state the intended behaviour plainly:

Subagents inherit your current sandbox policy.

The CLI wording is more specific: "Subagents inherit the parent turn's current sandbox and approval settings, including changes made with /permissions". Changes you make with /permissions are meant to carry over, and a custom agent file cannot override them — "Set sandbox and approval controls on the parent session. Custom agent instructions can ask an agent to avoid edits, but they don't create a separate read-only sandbox."

So before v0.170.0, the inheritance the documentation promises did not always hold. Windows sandbox permission preservation was fixed in the same release.

The rest of the release covers MCP OAuth credential races during cancellation, login and logout, oversized WebSocket requests falling back to HTTP, and experimental support for identically named MCP servers across environments.

Writing a permission profile

A profile is a named policy combining filesystem rules with network rules. You declare it under [permissions.<name>] and select it with the top-level default_permissions.

# ~/.codex/config.toml

default_permissions = "project-edit"

[permissions.project-edit]
description = "Project editing with OpenAI API access."
extends = ":workspace"

[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = true

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
"docs" = "read"
"generated" = "deny"

There are three built-in profiles.

NameWhat the docs say
:read-only"keeps local command execution read-only"
:workspace"allows writes inside the active workspace roots and system temp directories"
:danger-full-access"removes local sandbox restrictions" — for when that breadth is intentional

extends is constrained: "A profile can extend :read-only, :workspace, or another named profile. It cannot extend :danger-full-access", and unknown parents and inheritance cycles are rejected too. The docs also state a preference: "Prefer extending a built-in profile over starting from scratch so baseline protections carry forward."

Extending :workspace keeps .git, .agents, .codex and .aws under a workspace root read-only unless you override them explicitly. In the CLI, /permissions opens the picker for switching profiles.

Profiles are still Beta

The documentation opens with "Beta. Permission profiles are under active development and may change." Check that notice before building this into production workflows. Supported platforms are "macOS, Linux, WSL, and native Windows".

A leftover sandbox_mode makes default_permissions ignored

This is the easiest thing to miss. The docs state that the two systems do not combine:

Permission profiles do not compose with the older sandbox settings.

And they say which one wins:

If sandbox_mode appears in any loaded config file, you pass --sandbox, or the selected config profile sets sandbox_mode, Codex uses those older sandbox settings instead of default_permissions.

The older settings take precedence. Note "any loaded config file" — a sandbox_mode left in a system-level file, or in the config profile you selected, does the same thing. If default_permissions appears to do nothing, look for sandbox_mode and [sandbox_workspace_write] first and remove them.

There is one exception, for managed deployments: "Managed allowed_permission_profiles is the exception: it makes Codex use permission profiles." Even then, the guidance is to remove the older settings first.

The migration advice is blunt: "Use one system or the other for a session, not both." Start from :read-only for read-only work, and from :workspace or a custom profile writing through :workspace_roots for editing. For the older settings, see Codex approval_policy versus sandbox_mode; for widening writes, see writable_roots and letting Codex write outside the workspace.

Filesystem rules and the deny pitfall

[permissions.<name>.filesystem] maps paths to access values. The values are read, write and deny; "More specific entries override broader entries", and for the same path the order is deny > write > read.

Paths accept special tokens.

PathMeaningSubpaths
:rootThe filesystem root. only
:minimalPlatform and runtime paths needed by common tools. only
:workspace_rootsThe session's workspace roots plus any the profile addsYes
:tmpdirThe $TMPDIR location, when one is available. only
:slash_tmpThe /tmp folder, if it exists. only
/absolute/path, ~/pathAn absolute path, or one under your home directoryYes

An empty table fails safe, not open: "Missing or empty filesystem tables keep filesystem access restricted and emit a startup warning."

A deny glob is a snapshot taken when the process starts

A glob such as "**/*.env" = "deny" carries a platform-dependent limit:

On Linux, WSL, and native Windows with MXC or elevated, deny-read glob matches are enumerated when each sandboxed process starts.

Files created afterwards are not added to that process's deny list. A long-running shell, script, watcher or dev server can read a .env created after it started. The snapshot lasts "the sandboxed process's lifetime, not the whole Codex session".

Also, read and write globs are "less portable on Linux, WSL, and native Windows sandboxing", so the docs steer you to subtree rules such as "docs/**" = "read" or exact paths. Using an unbounded ** for a deny requires glob_scan_max_depth set to at least 1.

Summary

  • v0.170.0 fixes permission updates and child threads losing existing sandbox restrictions; the docs define the intent as "Subagents inherit your current sandbox policy"
  • Declare a profile under [permissions.<name>] and select it with default_permissions. The built-ins are :read-only, :workspace and :danger-full-access
  • A sandbox_mode left in any loaded config file makes default_permissions ignored. The two systems do not combine, and the older one wins
  • An empty filesystem table stays restricted and warns at startup. A deny glob is expanded when the sandboxed process starts, so later files escape it
  • Profiles are Beta and the specification may change

FAQ

I set default_permissions and nothing happened. Why?
Check whether sandbox_mode is still present anywhere. The docs say: "If sandbox_mode appears in any loaded config file, you pass --sandbox, or the selected config profile sets sandbox_mode, Codex uses those older sandbox settings instead of default_permissions." The older settings win.
What are the built-in permission profiles?
Three: :read-only, :workspace and :danger-full-access. extends accepts :read-only, :workspace or another named profile; :danger-full-access, unknown parents and inheritance cycles are rejected.
Are permission profiles stable?
No. The documentation opens with "Beta. Permission profiles are under active development and may change."

Primary sources

This article was drafted by AI from official documentation and reviewed by the site operator before publishing. Found a mistake? Let us know via the contact page.