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

> Understand the key differences between Codex read-only and workspace-write sandbox modes. Learn how each mode impacts file system access for code reviews and rescue tasks.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: deep-dive
- Published: 2026-07-30

---

**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:

```javascript
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:

```javascript
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:

```javascript
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:

```javascript
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.