# How the Codex Plugin Handles Sandbox Modes: Read-Only vs Workspace-Write

> Discover how the Codex plugin manages sandbox modes read-only vs workspace-write. Learn how file system access is controlled and secured by default.

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

---

**The Codex plugin controls file system access by passing a `sandbox` parameter—either `"read-only"` or `"workspace-write"`—to the Codex app-server during thread creation, with read-only as the default and workspace-write enabled only when the user explicitly requests write access.**

The openai/codex-plugin-cc repository implements a security model that restricts or permits file modifications based on the intended operation. Understanding how the Codex plugin handles sandbox modes is essential for developers integrating Codex into their workflows, as it determines whether AI-generated code can mutate the workspace or remains strictly observational.

## Default Read-Only Protection

In `plugins/codex/scripts/lib/codex.mjs`, the `buildThreadParams` helper function establishes the baseline security posture. When a caller does not explicitly specify a sandbox value, the function defaults to `"read-only"` at lines 68-71:

```javascript
sandbox: params.sandbox ?? "read-only",

```

This ensures that every Codex thread starts with restricted permissions unless explicitly overridden, preventing accidental file modifications during routine operations.

## Explicit Mode Selection via User Intent

The companion script in `plugins/codex/scripts/codex-companion.mjs` translates user commands into sandbox permissions. When invoking tasks, the script checks the `write` flag to determine which mode to request at lines 491-492:

```javascript
sandbox: request.write ? "workspace-write" : "read-only",

```

**Read-only mode** prohibits file writes and network access, making it suitable for safe code analysis and automated reviews. **Workspace-write mode** grants full filesystem permissions, allowing the assistant to edit, create, or delete files under the workspace root for tasks like `codex:task --write`.

## Review Commands Enforce Strict Isolation

Review-related operations explicitly hardcode the read-only restriction. The `runAppServerReview` function in `plugins/codex/scripts/lib/codex.mjs` (lines 1010-1013) always passes `"read-only"` regardless of user preferences:

```javascript
await startThread(client, cwd, {
  model: options.model,
  sandbox: "read-only",
  ephemeral: true,
  threadName: options.threadName
});

```

This architectural choice guarantees that code review processes cannot alter the repository state, maintaining audit integrity.

## Sandbox Runtime Configuration

When the thread initializes, the Codex app-server interprets the `sandbox` value to configure the runtime environment:

- **`"read-only"`**: The process can read workspace files but cannot write or modify them. Network access is disabled in the fixture implementation, making this suitable for safe code analysis and automated reviews.

- **`"workspace-write"`**: Full filesystem write permissions are granted, enabling code generation and modification tasks that intentionally mutate the repository.

## Test Fixture Implementation

The test suite in `tests/fake-codex-fixture.mjs` demonstrates the expected sandbox object structure consumed by the Codex server. Lines 316-320 construct a mock sandbox descriptor:

```javascript
sandbox: {
  type: "readOnly",
  access: { type: "fullAccess" },
  networkAccess: false
}

```

This fixture validates that the plugin correctly formats sandbox parameters before transmission to the app-server, ensuring consistent behavior between test and production environments.

## Summary

- The Codex plugin defaults to `"read-only"` sandbox mode in `buildThreadParams` to prevent accidental modifications.
- User commands in `codex-companion.mjs` toggle between `"read-only"` and `"workspace-write"` based on the `write` flag.
- Review operations explicitly enforce `"read-only"` mode in `runAppServerReview` regardless of user preferences.
- The sandbox parameter directly controls filesystem and network permissions in the Codex app-server runtime.
- Test fixtures in `fake-codex-fixture.mjs` mirror production sandbox structures to validate permission handling.

## Frequently Asked Questions

### What is the default sandbox mode in the Codex plugin?

The default mode is `"read-only"`, established in the `buildThreadParams` function within `plugins/codex/scripts/lib/codex.mjs`. This default applies whenever a thread is created without an explicit sandbox parameter, ensuring safe, non-mutating operations.

### How does the plugin prevent file modifications during code reviews?

Review commands invoke `runAppServerReview`, which hardcodes `sandbox: "read-only"` in the thread start request. This enforcement occurs in `plugins/codex/scripts/lib/codex.mjs` at lines 1010-1013 and operates independently of user-specified flags, guaranteeing that review processes remain read-only.

### Can network access be enabled in read-only mode?

According to the test fixture in `tests/fake-codex-fixture.mjs`, read-only mode typically disables network access (`networkAccess: false`). The sandbox configuration controls both filesystem and network permissions, with read-only environments restricting both capabilities.

### What happens when workspace-write mode is activated?

When the `write` flag is true, `codex-companion.mjs` passes `"workspace-write"` to the app-server, granting the Codex runtime full permissions to edit, create, or delete files within the workspace directory. This mode is reserved for intentional code generation tasks that require repository mutation.