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

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:

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

To start a thread that may write files:

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:

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

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}