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

> Understand the difference between read-only and workspace-write sandbox modes in the Codex plugin. Learn how each mode handles file modifications for code reviews and automated tasks.

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

---

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

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

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

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

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

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

```