Sandbox and Approval Policies Applied When Running Codex: A Technical Deep Dive

Codex runs every request inside a sandboxed environment with a default "read-only" filesystem restriction and a hard-coded "never" approval policy that bypasses manual human review.

In the openai/codex-plugin-cc repository, the sandbox and approval policies applied when running Codex are defined in the core thread-management library. These security parameters determine whether the AI can modify your workspace and whether generated plans require explicit user sign-off before execution.

Default Sandbox and Approval Configuration

The canonical settings reside in plugins/codex/scripts/lib/codex.mjs, specifically within the buildThreadParams and buildResumeParams helper functions. According to lines 66-69, both functions apply identical security defaults:

• sandbox: "read-only" — restricts the AI to reading files only
• approvalPolicy: "never" — automatically executes plans without pausing for human approval

// plugins/codex/scripts/lib/codex.mjs
function buildThreadParams(cwd, options = {}) {
  return {
    cwd,
    model: options.model ?? null,
    approvalPolicy: options.approvalPolicy ?? "never",
    sandbox: options.sandbox ?? "read-only",
    serviceName: SERVICE_NAME,
    ephemeral: options.ephemeral ?? true,
  };
}

function buildResumeParams(threadId, cwd, options = {}) {
  return {
    threadId,
    cwd,
    model: options.model ?? null,
    approvalPolicy: options.approvalPolicy ?? "never",
    sandbox: options.sandbox ?? "read-only",
  };
}

These defaults ensure that, unless explicitly overridden, every Codex thread starts with minimal filesystem access and no manual approval gates.

Sandbox Object Structure and Network Access

While the plugin uses string aliases like "read-only", the actual payload transmitted to the Codex backend follows a structured schema. The test fixtures in tests/fake-codex-fixture.mjs (lines 316 and 350) reveal the concrete object shape sent to the service:

{
  "type": "readOnly",
  "access": { "type": "fullAccess" },
  "networkAccess": false
}

This structure confirms that the default sandbox not only restricts write operations but also disables network access entirely, creating an isolated execution environment.

Dynamic Sandbox Escalation for Write Operations

When the plugin detects that a request requires file modifications, it dynamically escalates the sandbox from "read-only" to "workspace-write". This logic is implemented in plugins/codex/scripts/codex-companion.mjs (lines 491-492):

// plugins/codex/scripts/codex-companion.mjs
sandbox: request.write ? "workspace-write" : "read-only"

This conditional check ensures that write permissions are granted only when the specific operation demands it, maintaining the principle of least privilege for all other requests.

Practical Code Examples

Running Codex with Default Read-Only Restrictions

To start a thread using the default security posture, omit the sandbox and approval parameters:

import { CodexAppServerClient } from "./app-server.mjs";

const client = new CodexAppServerClient();
await client.startThread({
  cwd: process.cwd(),
  // Defaults to sandbox: "read-only", approvalPolicy: "never"
});

This configuration prevents the model from creating or modifying files and executes immediately without approval prompts.

Enabling Workspace Write Access

Explicitly permit file modifications by overriding the sandbox setting:

await client.startThread({
  cwd: process.cwd(),
  sandbox: "workspace-write",      // Allow file creation and modification
  approvalPolicy: "never",         // Continue auto-execution
});

Use this when you need Codex to generate new files or update existing code in your workspace.

Overriding the Approval Policy

While the current codebase hard-codes "never" as the only implemented policy, the API accepts custom values for future extensibility:

await client.startThread({
  cwd: process.cwd(),
  sandbox: "read-only",
  approvalPolicy: "manual",   // Reserved for future implementation
});

As implemented in openai/codex-plugin-cc, this will still execute without pause, but the parameter structure supports future policy additions.

Core Implementation Files

File	Purpose
plugins/codex/scripts/lib/codex.mjs	Defines buildThreadParams and buildResumeParams; sets default sandbox and approval policy values (lines 66-69).
plugins/codex/scripts/codex-companion.mjs	Contains logic to escalate sandbox to "workspace-write" when request.write is true (lines 491-492).
plugins/codex/scripts/lib/app-server.mjs	Provides CodexAppServerClient to send thread start/resume payloads to the Codex service.
tests/fake-codex-fixture.mjs	Contains example sandbox object schemas showing the concrete payload structure (lines 316, 350).

Summary

• Default sandbox: "read-only" is applied unless the operation requires writes, defined in buildThreadParams and buildResumeParams.
• Default approval policy: Hard-coded to "never", meaning Codex executes plans automatically without human intervention.
• Dynamic escalation: The companion script upgrades the sandbox to "workspace-write" only when request.write is detected.
• Network isolation: The underlying sandbox object disables network access by default (networkAccess: false).
• Override capability: Callers can pass custom sandbox and approvalPolicy values via the options parameter, though the current implementation primarily respects the "read-only" and "never" defaults.

Frequently Asked Questions

What is the default sandbox mode when running Codex?

The default sandbox mode is "read-only", as defined in plugins/codex/scripts/lib/codex.mjs. This setting restricts the AI to reading files only and prevents any modifications to the workspace unless explicitly overridden.

How does Codex handle file write operations?

When a write operation is required, the system detects this via the request.write flag in plugins/codex/scripts/codex-companion.mjs and automatically switches the sandbox parameter from "read-only" to "workspace-write", granting temporary write permissions for that specific request.

Can I configure Codex to require manual approval before executing plans?

Currently, the approval policy is hard-coded to "never" throughout the openai/codex-plugin-cc library. While the API structure supports passing custom approvalPolicy values to buildThreadParams, the existing implementation does not pause for manual review regardless of the parameter value.

Where are the sandbox and approval policies defined in the source code?

The policies are defined in plugins/codex/scripts/lib/codex.mjs within the buildThreadParams and buildResumeParams functions (lines 66-69). The default values are set there, while dynamic sandbox escalation logic lives in plugins/codex/scripts/codex-companion.mjs.

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