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

> Understand the key differences between read-only and workspace-write sandbox modes in Codex. Learn how each mode impacts AI file access and modification for improved code analysis and safety.

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

---

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

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

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

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

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