DEV Community

aicoding-guide
aicoding-guide

Posted on Originally published at aicoding-guide.com

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

Originally published at https://aicoding-guide.com.

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"
Enter fullscreen mode Exit fullscreen mode

There are three built-in profiles.

Name What 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.

Path Meaning Subpaths
:root The filesystem root . only
:minimal Platform and runtime paths needed by common tools . only
:workspace_roots The session's workspace roots plus any the profile adds Yes
:tmpdir The $TMPDIR location, when one is available . only
:slash_tmp The /tmp folder, if it exists . only
/absolute/path, ~/path An absolute path, or one under your home directory Yes

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

Top comments (0)