# What Sandbox Modes Are Available in Codex and When to Use Each

> Explore Codex sandbox modes: read-only for safe analysis and workspace-write for development. Learn when to use each mode for your tasks.

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

---

**Codex provides two sandbox modes—`read-only` for safe analysis tasks and `workspace-write` for development workflows that require file modifications—selected via the `sandbox` parameter in thread configuration.**

The **openai/codex-plugin-cc** repository implements a security model that isolates every model request inside a sandbox. Understanding what **sandbox modes are available in Codex** is essential for configuring appropriate permissions based on whether your workflow requires read-only analysis or active file manipulation.

## Read-Only Mode

The **`read-only`** sandbox mode grants the model permission to read files from the repository while strictly prohibiting modifications. In this mode, Codex cannot write new files, edit existing ones, or access the network.

Use this mode for analysis-only tasks such as code review, static analysis, documentation generation, or any workflow where the model must inspect the workspace without altering it. According to the source code in `plugins/codex/scripts/lib/codex.mjs`, this is the default mode applied when the `sandbox` parameter is omitted in `buildThreadParams` and `buildResumeParams`.

## Workspace-Write Mode

The **`workspace-write`** sandbox mode provides the model with full write access to the workspace file system within the repository. This mode also allows the model to request network access when needed, enabling operations like fetching dependencies or calling external APIs during development tasks.

Enable this mode only when explicitly allowing modifications, such as when implementing features, fixing bugs, or performing automated refactors. The companion script in `plugins/codex/scripts/codex-companion.mjs` switches to this mode when the incoming request includes a `write` flag.

## How Sandbox Selection Works Internally

Codex receives the sandbox setting via the `sandbox` field in thread start and resume parameters. The default configuration logic resides in `buildThreadParams` and `buildResumeParams` within `plugins/codex/scripts/lib/codex.mjs`, where the runtime defaults to `"read-only"` when no sandbox value is specified.

When the companion script processes a request, it dynamically selects the appropriate mode based on the payload. As implemented in `plugins/codex/scripts/codex-companion.mjs`, the logic checks for the presence of a `write` property: if `request.write` is truthy, it selects `"workspace-write"`; otherwise, it remains in `"read-only"`.

The test suite in `tests/fake-codex-fixture.mjs` demonstrates the granular sandbox configuration object that the runtime expects, including properties such as `access.type` and `networkAccess`.

## Configuring Sandbox Modes in Practice

The following examples demonstrate how to initialize threads with different security postures.

To start a thread that can only read files:

```javascript
await codexClient.startThread({
  cwd: "/my/project",
  sandbox: "read-only",               // default, explicitly set for clarity
  approvalPolicy: "never"
});

```

To start a thread that may write files:

```javascript
await codexClient.startThread({
  cwd: "/my/project",
  sandbox: "workspace-write",         // give the model permission to modify the repo
  approvalPolicy: "once"              // optional: ask for user approval before writing
});

```

The internal selection logic in the companion script shows how the mode is determined dynamically:

```javascript
// Inside codex-companion.mjs – choosing sandbox based on request
const sandbox = request.write ? "workspace-write" : "read-only";
send({ id: message.id, result: { /* other fields */, sandbox } });

```

For testing purposes, the runtime accepts a detailed sandbox object structure:

```javascript
// Detailed sandbox object used by the runtime (from test fixture)
const sandbox = {
  type: "readOnly",
  access: { type: "fullAccess" },
  networkAccess: false
};

```

## Summary

- **openai/codex-plugin-cc** provides two distinct **sandbox modes available in Codex**: `read-only` and `workspace-write`.
- **`read-only`** is the default mode set in `buildThreadParams` and `buildResumeParams` within `plugins/codex/scripts/lib/codex.mjs`, suitable for analysis tasks without file modifications.
- **`workspace-write`** enables full file system access and network requests, activated when the companion script detects a `write` flag in the request payload.
- Always match the sandbox mode to your workflow requirements: use `read-only` for safe inspection and `workspace-write` for active development tasks.

## Frequently Asked Questions

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

The default sandbox mode is **`read-only`**. According to the implementation in `plugins/codex/scripts/lib/codex.mjs`, the `buildThreadParams` and `buildResumeParams` functions default to `"read-only"` when the `sandbox` field is not explicitly provided in the thread configuration.

### Can Codex access the network in read-only mode?

No. In **`read-only`** mode, Codex has no network access whatsoever. This restriction ensures that analysis-only workflows cannot make external requests. Network access is only available in **`workspace-write`** mode, and even then it may require explicit configuration depending on the runtime environment.

### How do I enable write access for Codex?

To enable write access, set the `sandbox` parameter to **`"workspace-write"`** when starting a thread. Internally, the companion script in `plugins/codex/scripts/codex-companion.mjs` checks for a `write` flag in the request payload to determine whether to activate this mode, allowing the model to create, modify, and delete files within the workspace.

### Where is the sandbox configuration validated?

The sandbox configuration is defined and processed in multiple locations within the repository. The default values and thread parameter construction reside in `plugins/codex/scripts/lib/codex.mjs`, while the runtime selection logic executes in `plugins/codex/scripts/codex-companion.mjs`. The expected structure is documented in `tests/fake-codex-fixture.mjs`, which demonstrates the full configuration object including `access.type` and `networkAccess` properties.