Workspace‑Write vs. Read‑Only Sandbox Modes in the Codex Plugin for Claude Code

Read‑only mode blocks all file modifications for safe code reviews, while workspace‑write mode grants Codex full write access to apply code changes.

The openai/codex-plugin-cc repository implements two distinct sandbox execution modes that control how the Codex runtime interacts with your workspace. These modes are the core mechanism that distinguishes inspection‑only operations from automated code modifications.

How Sandbox Modes Are Selected

The plugin determines which sandbox to use at two critical points in the execution flow:

1. Default initialization — In plugins/codex/scripts/lib/codex.mjs at lines 68‑71, the buildThreadParams helper supplies "read-only" as the fallback:

// plugins/codex/scripts/lib/codex.mjs#L68-L71
sandbox: options.sandbox ?? "read-only"

2. Task‑time override — In plugins/codex/scripts/codex-companion.mjs at line 491, the executeTaskRun function switches to "workspace-write" when the user explicitly requests a write‑enabled operation:

// plugins/codex/scripts/codex-companion.mjs#L491
sandbox: request.write ? "workspace-write" : "read-only"

Read‑Only Mode: Safe Inspection Without Side Effects

When Codex runs in read‑only mode, the runtime is restricted to pure read operations. This mode provides guaranteed immutability — the Codex process can inspect files, analyze code structure, run tests, and generate reviews, but any attempt to create, modify, or delete files is blocked at the sandbox level.

This mode is automatically selected for:

• /codex:review commands
• /codex:adversarial-review operations
• Any task where the --write flag is absent

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

Workspace‑Write Mode: Automated Code Modification

The workspace-write sandbox lifts all write restrictions, granting Codex the ability to create, edit, and delete files within the workspace. After execution, the plugin identifies modified files through collectTouchedFiles and surfaces them as touched files in the response.

This mode is activated for:

• /codex:rescue automation commands
• Any task invoked with the --write flag
• Explicit user requests for code generation or refactoring

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

Side‑by‑Side Comparison

Aspect	Read‑Only	Workspace‑Write
File system access	Read only	Read and write
Use case	Code review, analysis	Bug fixes, refactoring, file generation
CLI trigger	/codex:review	/codex:rescue or --write flag
Safety guarantee	Zero modifications	Changes tracked as touched files
Source location	Default in buildThreadParams	Conditional in executeTaskRun

Security and Workflow Implications

The sandbox choice is the sole enforcement mechanism separating review‑only from write‑allowed actions. This design provides:

• Defense in depth: Even if Codex generates code that attempts file operations, the read‑only sandbox blocks execution at the system level.
• Explicit opt‑in: Users must intentionally request write mode through flags or specific commands.
• Auditability: Write operations emit collectTouchedFiles metadata for change tracking.

Summary

• Read‑only sandbox is the default safety mode that permits inspection without risk of repository modification.
• Workspace‑write sandbox enables full automation by granting Codex permission to apply code changes directly.
• The mode selection happens in codex.mjs (default) and codex-companion.mjs (task‑time override) based on the write flag.
• CLI commands map cleanly: review operations stay read‑only, rescue and --write tasks elevate to workspace‑write.

Frequently Asked Questions

How do I know which sandbox mode Codex is using?

The sandbox mode is visible in the plugin's internal runAppServerTurn calls. End users can infer the mode from the command: /codex:review always uses read‑only, while /codex:rescue or any --write invocation uses workspace‑write.

Can Codex accidentally write files in read‑only mode?

No. The sandbox restriction is enforced at the runtime level, below the application layer. Even if Codex generates code containing file write operations, the underlying execution environment blocks those syscalls.

What happens to files modified in workspace‑write mode?

The plugin's collectTouchedFiles mechanism tracks all changes. After task completion, modified files are reported back to the user for review, ensuring visibility into exactly what Codex altered.

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