Codex Plugin Sandbox Modes and Approval Policies for Delegated Tasks Explained

The Codex plugin enforces sandbox modes ("read-only" or "workspace-write") and an approval policy ("never") to control file access and human oversight for delegated tasks.

When you delegate work to the Codex plugin, you need precise control over what the task can touch and whether it needs a human green light. This article breaks down the sandbox modes and approval policies implemented in the openai/codex-plugin-cc repository, showing exactly how they protect your workspace while enabling automation.

Sandbox Modes: Controlling File Access

The sandbox mode determines whether a delegated task can read only or also modify files in your workspace. In plugins/codex/scripts/lib/codex.mjs, the code applies this setting when constructing Codex requests.

Read-Only Sandbox (Default)

The "read-only" sandbox is the safest option. Tasks can inspect code, analyze configurations, and generate responses without any file modifications.

// plugins/codex/scripts/lib/codex.mjs
const options = {
  sandbox: options.sandbox ?? "read-only",  // default fallback
  approvalPolicy: options.approvalPolicy ?? "never",
};

Use this mode for code review, documentation generation, or any task where you want guarantees that your files remain untouched.

Workspace-Write Sandbox

The "workspace-write" sandbox grants read and write permissions to the workspace. This enables automated refactoring, code generation, and file updates.

The companion script plugins/codex/scripts/codex-companion.mjs selects this mode dynamically based on request flags:

// When a write flag is present, use workspace-write
sandbox: request.write ? "workspace-write" : "read-only"

Advanced Sandbox Configuration

Test fixtures reveal a more granular sandbox object structure. In tests/fake-codex-fixture.mjs, the sandbox can include type descriptors, access levels, and network controls:

// tests/fake-codex-fixture.mjs
send({
  id: message.id,
  result: {
    sandbox: {
      type: "readOnly",
      access: { type: "fullAccess" },
      networkAccess: false,
    },
    // ...
  },
});

This advanced format suggests future extensibility for fine-grained permission control.

Approval Policies: Governing Human Oversight

The approval policy controls whether tasks execute immediately or await human review. Currently, only one policy is implemented in the source code.

The "Never" Policy (Default)

The "never" policy means tasks run without any human intervention. In plugins/codex/scripts/lib/codex.mjs, this is the hardcoded default:

approvalPolicy: options.approvalPolicy ?? "never"

The same default appears in test fixtures, confirming this is the production behavior:

// tests/fake-codex-fixture.mjs
approvalPolicy: "never"

This design suits fully automated pipelines where latency matters and trust is established through sandboxing rather than manual gates.

Complete Configuration Examples

Writable Sandbox with Explicit Policy

Request a task that can modify files and runs immediately:

const request = {
  model: "gpt-5.4",
  sandbox: "workspace-write",    // allow file modifications
  approvalPolicy: "never",       // skip human approval
  prompt: "Refactor all utility functions to use async/await"
};

const response = await codex.run(request);

Minimal Configuration (Defaults)

Rely on safe defaults for read-only analysis:

const request = {
  model: "gpt-5.4",
  // sandbox defaults to "read-only"
  // approvalPolicy defaults to "never"
  prompt: "Analyze this codebase for security issues"
};

const response = await codex.run(request);

Key Source Files

File	Purpose
plugins/codex/scripts/lib/codex.mjs	Core logic setting default sandbox ("read-only") and approval policy ("never")
plugins/codex/scripts/codex-companion.mjs	Companion script selecting sandbox mode based on request write flag
tests/fake-codex-fixture.mjs	Test fixture demonstrating sandbox object structure and policy values

Summary

• Sandbox modes determine file access: "read-only" (default, safe) or "workspace-write" (allows modifications)
• Approval policy is fixed at "never" for immediate execution without human review
• Defaults are enforced in codex.mjs using nullish coalescing (??) operators
• The companion script dynamically selects sandbox mode based on request flags
• Advanced sandbox objects in test fixtures hint at future permission granularity

Frequently Asked Questions

What is the default sandbox mode for Codex plugin delegated tasks?

The default sandbox mode is "read-only". In plugins/codex/scripts/lib/codex.mjs, the code uses options.sandbox ?? "read-only" to fall back to read-only access when no sandbox value is provided.

Can I allow a delegated task to modify files in my workspace?

Yes. Set sandbox: "workspace-write" in your request. The codex-companion.mjs script automatically selects this mode when the request includes a write flag.

Does the Codex plugin support manual approval before task execution?

Currently, no. The only implemented approval policy is "never", which executes tasks immediately. The default is hardcoded in codex.mjs as options.approvalPolicy ?? "never".

Where can I see how sandbox settings are validated in tests?

The file tests/fake-codex-fixture.mjs contains concrete sandbox objects used in simulated responses, including the type: "readOnly" structure with access and networkAccess fields.

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