# Workspace-Write vs Read-Only Sandbox Modes in Codex

> Understand workspace-write versus read-only sandbox modes in Codex. Learn how read-only restricts file changes while workspace-write allows AI to edit, create, and delete files in your repository.

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

---

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

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

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

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

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