Read-Only vs Workspace-Write Sandbox Modes in the Codex Plugin: A Complete Guide

The read-only sandbox mode blocks all file modifications and is used for code reviews, while workspace-write mode grants Codex permission to create, edit, and delete files in your repository when performing automated tasks.

The openai/codex-plugin-cc repository integrates Codex with Claude Code through a local app-server architecture. When you invoke Codex commands, the plugin configures a sandbox environment that strictly controls filesystem access, determining whether Codex can only inspect code or actively modify it.

What Are Sandbox Modes in the Codex Plugin?

Sandbox modes are security boundaries defined in the plugin's source code that dictate the filesystem permissions available to the Codex runtime. These modes are passed to the app-server when initiating a task or review thread.

The plugin supports two distinct modes:

• read-only: Restricts Codex to viewing files only
• workspace-write: Permits file creation, modification, and deletion

Read-Only Sandbox Mode (Default)

The read-only mode is the default security posture for the Codex plugin. When a thread is created via buildThreadParams in plugins/codex/scripts/lib/codex.mjs (lines 68-71), the sandbox parameter defaults to "read-only" unless explicitly overridden:

// plugins/codex/scripts/lib/codex.mjs (lines 68-71)
sandbox: options.sandbox ?? "read-only"

In this mode, the Codex runtime can inspect repository contents, run tests, and generate review comments, but any attempt to write or modify files is blocked at the filesystem level.

Use Cases for Read-Only Mode

This mode powers pure inspection commands:

• /codex:review – Analyzes pull requests without modifying code
• /codex:adversarial-review – Performs security-focused code analysis

Workspace-Write Sandbox Mode

The workspace-write mode elevates permissions to allow file modifications. The plugin selects this mode in executeTaskRun within plugins/codex/scripts/codex-companion.mjs (line 491), using a ternary expression that checks the write flag:

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

When activated, Codex receives write access to the current workspace directory. This enables automated refactoring, bug fixes, and file generation. After execution, the plugin identifies modified files through the collectTouchedFiles function and reports them as touched files in the output.

Activation Triggers

Workspace-write mode activates automatically when:

• Using the /codex:rescue command
• Running any task with the --write flag
• Explicitly requesting code modifications through the task interface

Code Examples: Configuring Each Mode

When invoking the Codex runtime directly through runAppServerTurn, you specify the sandbox mode explicitly:

Read-only configuration (safe for reviews):

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 configuration (for automated modifications):

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 is the default sandbox mode set in buildThreadParams that prevents any file modifications, making it safe for code reviews and security analysis.
• Workspace-write is activated via the write flag check in executeTaskRun, allowing Codex to modify files and create new content.
• The mode selection happens automatically based on command type: review commands use read-only, while rescue and write-flagged tasks use workspace-write.
• Modified files in workspace-write mode are tracked through collectTouchedFiles and reported back to the user.

Frequently Asked Questions

How do I switch between read-only and workspace-write modes in the Codex plugin?

You do not manually configure the sandbox mode. The plugin automatically selects read-only for review commands (/codex:review) and workspace-write for task commands that include the --write flag or use /codex:rescue. The logic in executeTaskRun at line 491 of plugins/codex/scripts/codex-companion.mjs handles this determination based on the request.write boolean.

What happens if Codex attempts to write files while in read-only sandbox mode?

The Codex runtime receives a filesystem permission denial. Since the sandbox is enforced at the app-server level, any write operations attempted by Codex in read-only mode are blocked before they can modify repository contents, ensuring safe execution of review-only operations.

Which CLI commands trigger workspace-write sandbox mode automatically?

The /codex:rescue command and any task invocation using the --write flag trigger workspace-write mode. These commands are designed for automation scenarios where Codex must modify code to fix bugs, refactor implementations, or generate new files, as opposed to the inspection-only /codex:review command.

Where is the default sandbox mode defined in the source code?

The default read-only mode is defined in plugins/codex/scripts/lib/codex.mjs at lines 68-71 within the buildThreadParams function. The code uses the nullish coalescing operator (??) to default to "read-only" when no specific sandbox option is provided:

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

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