Workspace-Write vs Read-Only Sandbox Modes in Codex

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

The openai/codex-plugin-cc repository implements security boundaries that control file system access during AI execution. When the Codex plugin for Claude Code delegates tasks to the local Codex app-server, it must specify whether the runtime should operate in read-only or workspace-write mode. Understanding the difference between these workspace-write and read-only sandbox modes in Codex is essential for safely running automated reviews versus code-changing automation tasks.

How Sandbox Modes Are Configured

The Codex plugin selects the sandbox mode by passing a sandbox parameter to the runAppServerTurn function. This value propagates through the thread creation logic and ultimately gates all file system operations during the AI runtime.

Default Read-Only Behavior

In plugins/codex/scripts/lib/codex.mjs, the buildThreadParams helper establishes the default security posture. Lines 68-71 implement the fallback logic:

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

This means that unless explicitly overridden, every Codex session starts with restricted permissions. The runtime can read repository files, execute tests, and analyze code structure, but any attempt to write or modify the filesystem is blocked.

Conditional Write Access

When you request a task that requires code changes, the plugin switches modes. In plugins/codex/scripts/codex-companion.mjs at line 491, the executeTaskRun function evaluates the request:

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

This expression checks whether the user invoked the command with a write flag (such as --write or via rescue commands), dynamically upgrading the sandbox from the default restriction to full workspace access.

Read-Only Sandbox Mode

The read-only sandbox is the safest option for inspection-only workflows. It guarantees that Codex will never alter your repository state, making it ideal for code reviews and security audits.

Implementation Details

As implemented in buildThreadParams, the read-only mode requires no explicit configuration—it is the default value applied when the sandbox option is undefined. The Codex runtime receives these constraints before processing any user prompts.

Use Cases and Commands

This mode powers the review-specific CLI commands:

• /codex:review – Generates PR feedback without touching files
• /codex:adversarial-review – Security-focused analysis with zero write permissions

// Running a 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 Sandbox Mode

The workspace-write sandbox removes file system restrictions, allowing Codex to perform automated refactoring, bug fixes, and file generation. Changes are tracked and reported back to the user as touched files.

How Write Access Is Granted

When executeTaskRun detects a write-enabled request, it explicitly sets sandbox: "workspace-write". This signals the Codex app-server to mount the workspace with write permissions, enabling the AI to modify any file within the repository boundary.

Change Tracking and Touched Files

After execution completes, the plugin calls collectTouchedFiles to identify which files were created, modified, or deleted during the session. This audit trail ensures you know exactly what changed before accepting the AI's work.

Use Cases and Commands

Write mode activates for automation tasks:

• /codex:rescue – Automated bug fixing and recovery
• Any command with --write flag – Explicit user consent for file modifications

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

Key Differences Between Workspace-Write and Read-Only Modes

Feature	Read-Only Sandbox	Workspace-Write Sandbox
File Permissions	Read and execute only	Full create, edit, delete access
Default State	Yes (lines 68-71 in codex.mjs)	No (requires explicit write flag)
Primary Commands	/codex:review, /codex:adversarial-review	/codex:rescue, --write tasks
Change Reporting	N/A (no changes possible)	Reported via collectTouchedFiles
Safety Level	High – guaranteed immutable	Medium – requires user review

Summary

• Read-only is the default sandbox mode in openai/codex-plugin-cc, enforced by buildThreadParams when no override is specified.
• Workspace-write is explicitly selected in executeTaskRun when the user requests write-enabled operations via the --write flag or rescue commands.
• Read-only mode guarantees repository safety for code reviews and adversarial analysis.
• Workspace-write mode enables automation but requires validation through the collectTouchedFiles reporting mechanism.

Frequently Asked Questions

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

The Codex runtime will block the operation. When running in read-only sandbox mode, the file system is mounted with restricted permissions, causing any write attempts to fail silently or return permission errors to the AI, which then reports that it cannot modify the code.

Can I switch sandbox modes mid-conversation?

No. The sandbox mode is determined at the start of each task execution in executeTaskRun (line 491 of codex-companion.mjs). To change from read-only to workspace-write, you must issue a new command with the appropriate write flag (such as --write or /codex:rescue).

How do I know which files Codex modified in workspace-write mode?

The plugin automatically tracks modifications through the collectTouchedFiles function. After a workspace-write session completes, the CLI displays a list of created, edited, and deleted files, allowing you to review changes before committing them to your repository.

Is workspace-write mode dangerous to use?

While less restrictive than read-only, workspace-write mode is designed to be safe through transparency. The AI can only modify files within the current working directory, and all changes are reported immediately. However, you should still review the collectTouchedFiles output before accepting automated changes, especially in production codebases.

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