Read-Only vs Workspace-Write Sandbox Modes in Codex: Key Differences Explained

The read-only sandbox mode restricts Codex to read-only file system access for safe code reviews, while workspace-write permits file modifications for rescue tasks and automated edits.

The OpenAI Codex plugin for Claude Code controls file system permissions through sandbox modes that determine whether the AI can only inspect code or actively modify it. These modes are defined in the openai/codex-plugin-cc repository and are selected automatically based on whether you are running a review command or a write-enabled task.

What Are Sandbox Modes?

Sandbox modes in Codex act as security boundaries that limit what the AI runtime can do within your repository. When you invoke Codex through commands like /codex:review or /codex:rescue, the plugin specifies a sandbox mode that dictates file system permissions according to the implementation in plugins/codex/scripts/codex-companion.mjs.

How Read-Only Sandbox Mode Works

Implementation and Default Behavior

The read-only sandbox is the default security mode. In plugins/codex/scripts/lib/codex.mjs at lines 68-71, the buildThreadParams helper sets the sandbox explicitly:

sandbox: options.sandbox ?? "read-only"

This ensures that unless explicitly overridden, Codex operates with restricted permissions that prevent any file system mutations.

Capabilities and Use Cases

In read-only mode, the Codex runtime can inspect files, analyze code structure, run tests, and generate review comments, but any attempt to write or modify files is blocked by the sandbox. This mode powers commands such as:

• /codex:review
• /codex:adversarial-review

Use this mode when you need AI analysis without risk of accidental file modifications.

How Workspace-Write Sandbox Mode Works

Granting Write Access

The workspace-write sandbox lifts read-only restrictions and grants the Codex runtime full write access to the current workspace. The plugin selects this mode in plugins/codex/scripts/codex-companion.mjs at line 491 using the expression:

request.write ? "workspace-write" : "read-only"

This logic checks whether the user invoked a command with the --write flag or requested a task that explicitly requires file modifications.

Tracking Modified Files

When operating in workspace-write mode, Codex can create, edit, or delete files. The plugin tracks these changes through the collectTouchedFiles function and reports them back as touched files in the task output. This enables automation commands such as:

• /codex:rescue
• Any task run with the --write flag

Code Examples

Running a Read-Only Review

To execute a pure code review without write permissions:

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

Executing a Write-Enabled Task

To delegate tasks that modify files, such as bug fixes or refactoring:

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

Summary

• Read-only mode is the default sandbox that prevents all file modifications, making it safe for code reviews and analysis tasks as implemented in buildThreadParams.
• Workspace-write mode grants full write permissions when the write flag is set, enabling Codex to apply code changes and create new files via executeTaskRun.
• The plugin automatically selects the appropriate mode based on whether you use review commands (read-only) or rescue/automation commands with the --write flag (workspace-write).
• File changes in workspace-write mode are tracked via collectTouchedFiles and reported as touched files in the task results.

Frequently Asked Questions

Can I switch from read-only to workspace-write mode during an active session?

No, the sandbox mode is determined at task initialization. According to the source code in buildThreadParams and executeTaskRun, the mode is set when the thread is created and cannot be changed mid-execution. To change modes, you must start a new command with the appropriate flags, such as adding --write to enable workspace-write.

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

The Codex runtime respects the sandbox boundaries enforced by the app-server. When operating in read-only mode, any file write operations attempted by the AI are blocked at the sandbox level, preventing accidental modifications while still allowing full code inspection and analysis.

How does the plugin track which files Codex modifies in workspace-write mode?

The plugin implements collectTouchedFiles to monitor file system changes during workspace-write operations. This function captures all created, modified, or deleted files during the task execution and reports them in the task output, giving you visibility into exactly what the AI changed in your workspace.

Is workspace-write mode safe to use on production code?

While workspace-write mode is designed for automation and rescue tasks according to the openai/codex-plugin-cc source, you should treat it as a powerful editing tool that can directly modify your codebase. Always review the touched files output before committing changes, and use read-only mode first if you only need analysis without modifications.

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