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

> Discover the sandbox and approval policies for running OpenAI Codex. Learn how default read-only filesystems and automatic approval ensure secure execution.

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

---

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

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

```json
{
  "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):

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

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

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

```js
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`.