Codex Sandbox Modes Explained: `read-only` vs `workspace-write` in the OpenAI Codex Plugin

read-only sandbox mode blocks all file modifications, while workspace-write grants full write access to the repository—this single configuration switch determines whether Codex can only inspect code or actively change it.

The OpenAI Codex plugin for Claude Code orchestrates Codex runs through a local app-server, using sandbox modes as the security boundary between safe code review and autonomous code modification. Understanding how these modes work—and where they are enforced in the source code—is essential for safely delegating tasks to AI agents.

---

How Sandbox Modes Are Defined

The plugin supports two mutually exclusive sandbox configurations that control filesystem access at the runtime level:

Sandbox mode	Default?	Write access?	Typical use case
read-only	Yes	No	Code review, test analysis, adversarial audits
workspace-write	No	Yes	Bug fixes, refactoring, file creation, automated rescue tasks

The sandbox is not a mere suggestion—it is passed directly to the Codex app-server, which enforces these permissions at the process level.

---

read-only: The Safe Default for Inspection Tasks

The read-only sandbox is the plugin's default setting, hardcoded in the thread-creation helper to prevent accidental modifications.

In plugins/codex/scripts/lib/codex.mjs at lines 68-71, the buildThreadParams function establishes this default:

// plugins/codex/scripts/lib/codex.mjs (lines 68-71)
{
  sandbox: options.sandbox ?? "read-only",
  // ... other thread parameters
}

When operating in read-only mode, Codex can:

• Read any file in the repository
• Execute tests and analyze outputs
• Generate review comments and suggestions
• Produce detailed reports on code quality

However, any attempt to write, delete, or modify files is blocked by the sandbox. This mode powers commands like /codex:review and /codex:adversarial-review, where the goal is understanding code without changing it.

---

workspace-write: Permission to Modify Code

The workspace-write sandbox is explicitly selected when the user requests a task that may alter the repository. This conditional selection happens in plugins/codex/scripts/codex-companion.mjs at line 491:

// plugins/codex/scripts/codex-companion.mjs (line 491)
sandbox: request.write ? "workspace-write" : "read-only",

In this mode, Codex receives full write access to the current workspace. The plugin tracks these modifications through collectTouchedFiles, which reports exactly which files were created, edited, or deleted during the run.

Use workspace-write for:

• /codex:rescue commands that fix failing builds
• Refactoring operations requested with the --write flag
• Adding new files or removing obsolete code
• Automated bug fixes and patch generation

---

Practical Code Examples

Running a Pure Review (Read-Only)

await runAppServerTurn(cwd, {
  model: "gpt-5.4",
  sandbox: "read-only",   // enforced default—no file writes possible
  prompt: "Please review the changes in this PR."
});

Delegating a Modification Task (Workspace-Write)

await runAppServerTurn(cwd, {
  model: "gpt-5.4",
  sandbox: "workspace-write",   // explicit grant for file modifications
  prompt: "Fix the failing test and commit the patch."
});

The CLI abstracts this choice through command semantics:

• /codex:review → automatically uses read-only
• /codex:rescue … or any --write flagged command → automatically uses workspace-write

---

Security and Workflow Implications

The sandbox mode is the only mechanism distinguishing review-only from write-allowed operations. This design provides two critical guarantees:

1. Defense in depth: Even if Codex generates code that would modify files, the read-only sandbox prevents execution at the system level.
2. Explicit consent: The workspace-write mode requires an affirmative signal—either the --write flag or a rescue-style command—ensuring users consciously authorize changes.

According to the OpenAI Codex plugin source code, the collectTouchedFiles utility only operates meaningfully in workspace-write mode; in read-only mode, it returns empty results since the filesystem remains unchanged.

---

Summary

• read-only (default): Codex can inspect code but never modify it—safe for reviews and analysis.
• workspace-write (opt-in): Codex can create, edit, and delete files—required for rescue tasks and automated fixes.
• Configuration location: Default set in plugins/codex/scripts/lib/codex.mjs; override logic in plugins/codex/scripts/codex-companion.mjs at line 491.
• CLI mapping: Review commands use read-only; rescue and --write commands use workspace-write.

---

Frequently Asked Questions

What happens if Codex tries to write files in read-only mode?

The Codex runtime receives a permission error from the sandbox layer. The plugin continues execution, but no files are modified, and collectTouchedFiles returns an empty set. The user sees any generated suggestions as output without automatic application.

Can I override the default read-only sandbox for custom commands?

Yes. Any task run with the --write flag triggers the conditional in codex-companion.mjs line 491, selecting workspace-write. Plugin developers can also pass sandbox: "workspace-write" directly to buildThreadParams when constructing custom thread parameters.

Does workspace-write allow access outside the current workspace?

No. The sandbox confines write operations to the current working directory (the workspace). The Codex runtime cannot escape this boundary to modify system files or other repositories, even in workspace-write mode.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}