# Codex Sandbox Modes Explained: `read-only` vs `workspace-write` in the OpenAI Codex Plugin

> Understand the OpenAI Codex Plugin's sandbox modes. Learn how read-only blocks file modifications while workspace-write allows full repository access, controlling Codex's ability to inspect or alter code.

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

---

**`read-only` sandbox mode blocks all file modifications, while `workspace-write` grants full write access to the repository—this single configuration switch determines whether Codex can only inspect code or actively change it.**

The OpenAI Codex plugin for Claude Code orchestrates Codex runs through a local app-server, using **sandbox modes** as the security boundary between safe code review and autonomous code modification. Understanding how these modes work—and where they are enforced in the source code—is essential for safely delegating tasks to AI agents.

---

## How Sandbox Modes Are Defined

The plugin supports two mutually exclusive sandbox configurations that control filesystem access at the runtime level:

| Sandbox mode | Default? | Write access? | Typical use case |
|-------------|----------|-------------|----------------|
| `read-only` | Yes | No | Code review, test analysis, adversarial audits |
| `workspace-write` | No | Yes | Bug fixes, refactoring, file creation, automated rescue tasks |

The sandbox is not a mere suggestion—it is passed directly to the Codex app-server, which enforces these permissions at the process level.

---

## `read-only`: The Safe Default for Inspection Tasks

The **read-only** sandbox is the plugin's default setting, hardcoded in the thread-creation helper to prevent accidental modifications.

In `plugins/codex/scripts/lib/codex.mjs` at lines 68-71, the `buildThreadParams` function establishes this default:

```javascript
// plugins/codex/scripts/lib/codex.mjs (lines 68-71)
{
  sandbox: options.sandbox ?? "read-only",
  // ... other thread parameters
}

```

When operating in `read-only` mode, Codex can:

- Read any file in the repository
- Execute tests and analyze outputs
- Generate review comments and suggestions
- Produce detailed reports on code quality

However, any attempt to write, delete, or modify files is blocked by the sandbox. This mode powers commands like `/codex:review` and `/codex:adversarial-review`, where the goal is understanding code without changing it.

---

## `workspace-write`: Permission to Modify Code

The **workspace-write** sandbox is explicitly selected when the user requests a task that may alter the repository. This conditional selection happens in `plugins/codex/scripts/codex-companion.mjs` at line 491:

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

```

In this mode, Codex receives full write access to the current workspace. The plugin tracks these modifications through `collectTouchedFiles`, which reports exactly which files were created, edited, or deleted during the run.

Use `workspace-write` for:

- `/codex:rescue` commands that fix failing builds
- Refactoring operations requested with the `--write` flag
- Adding new files or removing obsolete code
- Automated bug fixes and patch generation

---

## Practical Code Examples

### Running a Pure Review (Read-Only)

```javascript
await runAppServerTurn(cwd, {
  model: "gpt-5.4",
  sandbox: "read-only",   // enforced default—no file writes possible
  prompt: "Please review the changes in this PR."
});

```

### Delegating a Modification Task (Workspace-Write)

```javascript
await runAppServerTurn(cwd, {
  model: "gpt-5.4",
  sandbox: "workspace-write",   // explicit grant for file modifications
  prompt: "Fix the failing test and commit the patch."
});

```

The CLI abstracts this choice through command semantics:

- `/codex:review` → automatically uses **read-only**
- `/codex:rescue …` or any `--write` flagged command → automatically uses **workspace-write**

---

## Security and Workflow Implications

The sandbox mode is the **only** mechanism distinguishing review-only from write-allowed operations. This design provides two critical guarantees:

1. **Defense in depth:** Even if Codex generates code that would modify files, the `read-only` sandbox prevents execution at the system level.
2. **Explicit consent:** The `workspace-write` mode requires an affirmative signal—either the `--write` flag or a rescue-style command—ensuring users consciously authorize changes.

According to the OpenAI Codex plugin source code, the `collectTouchedFiles` utility only operates meaningfully in `workspace-write` mode; in `read-only` mode, it returns empty results since the filesystem remains unchanged.

---

## Summary

- **`read-only`** (default): Codex can inspect code but never modify it—safe for reviews and analysis.
- **`workspace-write`** (opt-in): Codex can create, edit, and delete files—required for rescue tasks and automated fixes.
- **Configuration location**: Default set in `plugins/codex/scripts/lib/codex.mjs`; override logic in `plugins/codex/scripts/codex-companion.mjs` at line 491.
- **CLI mapping**: Review commands use `read-only`; rescue and `--write` commands use `workspace-write`.

---

## Frequently Asked Questions

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

The Codex runtime receives a permission error from the sandbox layer. The plugin continues execution, but no files are modified, and `collectTouchedFiles` returns an empty set. The user sees any generated suggestions as output without automatic application.

### Can I override the default `read-only` sandbox for custom commands?

Yes. Any task run with the `--write` flag triggers the conditional in `codex-companion.mjs` line 491, selecting `workspace-write`. Plugin developers can also pass `sandbox: "workspace-write"` directly to `buildThreadParams` when constructing custom thread parameters.

### Does `workspace-write` allow access outside the current workspace?

No. The sandbox confines write operations to the current working directory (the workspace). The Codex runtime cannot escape this boundary to modify system files or other repositories, even in `workspace-write` mode.