Read-Only vs Workspace-Write Sandbox Modes in Codex: A Technical Comparison

The read-only sandbox mode restricts Codex to file inspection and analysis only, while workspace-write grants the AI runtime permission to create, edit, or delete files in your repository.

The openai/codex-plugin-cc repository implements two distinct security boundaries that determine whether the Codex AI can modify your codebase. Understanding the differences between read-only and workspace-write sandbox modes in Codex is essential for safely delegating code reviews versus automated refactoring tasks through the Claude Code plugin.

How Sandbox Modes Control File System Access

The Codex plugin executes AI tasks through a local app-server, with the sandbox parameter acting as the primary security gate. According to the source code in plugins/codex/scripts/lib/codex.mjs, the system explicitly defaults to restrictive permissions unless explicitly overridden by user intent.

Read-Only Mode (Default)

In plugins/codex/scripts/lib/codex.mjs at lines 68–71, the buildThreadParams function establishes the default security posture:

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

This read-only configuration ensures the Codex runtime can inspect code, execute tests, and generate reviews without any ability to modify files. This mode powers pure analysis commands such as /codex:review and /codex:adversarial-review, providing a guarantee that your repository remains unchanged regardless of the AI's output.

Workspace-Write Mode

When you request Codex to perform tasks that require code changes, the plugin elevates permissions dynamically. In plugins/codex/scripts/codex-companion.mjs at line 491, the executeTaskRun function selects the sandbox based on the write flag:

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

The workspace-write mode grants the Codex runtime full write access to the current workspace. In this configuration, the AI can create new files, edit existing ones, and delete obsolete code. The plugin tracks these modifications through the collectTouchedFiles function, reporting exactly which files the AI altered during execution.

Practical Implementation Examples

When invoking Codex programmatically, you explicitly declare the intended permission level through the sandbox parameter.

To run a security review without write access:

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

To delegate a task that requires file modifications:

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

CLI Commands and Automatic Mode Selection

The plugin automatically maps user commands to the appropriate sandbox mode without requiring manual configuration:

• /codex:review → Uses read-only sandbox for safe code analysis.
• /codex:rescue (or any command with --write flag) → Uses workspace-write sandbox for automated fixes.

This automatic selection ensures that inspection-only operations remain strictly read-only, while rescue and automation commands receive the necessary permissions to apply patches.

Summary

• Read-only is the default sandbox mode in buildThreadParams at plugins/codex/scripts/lib/codex.mjs (lines 68–71), preventing any file modifications during Codex execution.
• Workspace-write activates when request.write is true in executeTaskRun at plugins/codex/scripts/codex-companion.mjs (line 491), allowing the AI to create, edit, and delete files.
• The sandbox choice is the sole distinction between review-only actions (/codex:review) and write-permitted automation (/codex:rescue or --write flag).
• Changes made in workspace-write mode are tracked via collectTouchedFiles and reported as touched files in the output.

Frequently Asked Questions

What is the default sandbox mode in Codex?

The default is read-only, as implemented in plugins/codex/scripts/lib/codex.mjs where buildThreadParams uses the nullish coalescing operator (??) to fall back to "read-only" when no sandbox option is specified. This ensures that Codex cannot accidentally modify your repository unless you explicitly request write access.

Can Codex modify files without workspace-write mode?

No. When running in read-only mode, the Codex runtime is strictly blocked from writing to the file system. Any attempt to create, edit, or delete files will fail, making this mode safe for pure code review and analysis tasks where repository integrity must be preserved.

How do I activate workspace-write mode?

You can activate workspace-write mode by using the --write flag with your Codex command or by running specific automation commands like /codex:rescue. According to the source code in plugins/codex/scripts/codex-companion.mjs, the executeTaskRun function checks request.write and switches from the default "read-only" to "workspace-write" when true.

Is workspace-write safe to use?

Workspace-write is safe when you intend for Codex to modify your codebase, as the plugin tracks all changes through collectTouchedFiles and reports them as touched files. However, you should review the AI's changes before committing them, unlike read-only mode which guarantees zero modifications to your repository.

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