How the Codex Plugin Handles Sandbox Modes: Read-Only vs Workspace-Write

The Codex plugin controls file system access by passing a sandbox parameter—either "read-only" or "workspace-write"—to the Codex app-server during thread creation, with read-only as the default and workspace-write enabled only when the user explicitly requests write access.

The openai/codex-plugin-cc repository implements a security model that restricts or permits file modifications based on the intended operation. Understanding how the Codex plugin handles sandbox modes is essential for developers integrating Codex into their workflows, as it determines whether AI-generated code can mutate the workspace or remains strictly observational.

Default Read-Only Protection

In plugins/codex/scripts/lib/codex.mjs, the buildThreadParams helper function establishes the baseline security posture. When a caller does not explicitly specify a sandbox value, the function defaults to "read-only" at lines 68-71:

sandbox: params.sandbox ?? "read-only",

This ensures that every Codex thread starts with restricted permissions unless explicitly overridden, preventing accidental file modifications during routine operations.

Explicit Mode Selection via User Intent

The companion script in plugins/codex/scripts/codex-companion.mjs translates user commands into sandbox permissions. When invoking tasks, the script checks the write flag to determine which mode to request at lines 491-492:

sandbox: request.write ? "workspace-write" : "read-only",

Read-only mode prohibits file writes and network access, making it suitable for safe code analysis and automated reviews. Workspace-write mode grants full filesystem permissions, allowing the assistant to edit, create, or delete files under the workspace root for tasks like codex:task --write.

Review Commands Enforce Strict Isolation

Review-related operations explicitly hardcode the read-only restriction. The runAppServerReview function in plugins/codex/scripts/lib/codex.mjs (lines 1010-1013) always passes "read-only" regardless of user preferences:

await startThread(client, cwd, {
  model: options.model,
  sandbox: "read-only",
  ephemeral: true,
  threadName: options.threadName
});

This architectural choice guarantees that code review processes cannot alter the repository state, maintaining audit integrity.

Sandbox Runtime Configuration

When the thread initializes, the Codex app-server interprets the sandbox value to configure the runtime environment:

• "read-only": The process can read workspace files but cannot write or modify them. Network access is disabled in the fixture implementation, making this suitable for safe code analysis and automated reviews.

• "workspace-write": Full filesystem write permissions are granted, enabling code generation and modification tasks that intentionally mutate the repository.

Test Fixture Implementation

The test suite in tests/fake-codex-fixture.mjs demonstrates the expected sandbox object structure consumed by the Codex server. Lines 316-320 construct a mock sandbox descriptor:

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

This fixture validates that the plugin correctly formats sandbox parameters before transmission to the app-server, ensuring consistent behavior between test and production environments.

Summary

• The Codex plugin defaults to "read-only" sandbox mode in buildThreadParams to prevent accidental modifications.
• User commands in codex-companion.mjs toggle between "read-only" and "workspace-write" based on the write flag.
• Review operations explicitly enforce "read-only" mode in runAppServerReview regardless of user preferences.
• The sandbox parameter directly controls filesystem and network permissions in the Codex app-server runtime.
• Test fixtures in fake-codex-fixture.mjs mirror production sandbox structures to validate permission handling.

Frequently Asked Questions

What is the default sandbox mode in the Codex plugin?

The default mode is "read-only", established in the buildThreadParams function within plugins/codex/scripts/lib/codex.mjs. This default applies whenever a thread is created without an explicit sandbox parameter, ensuring safe, non-mutating operations.

How does the plugin prevent file modifications during code reviews?

Review commands invoke runAppServerReview, which hardcodes sandbox: "read-only" in the thread start request. This enforcement occurs in plugins/codex/scripts/lib/codex.mjs at lines 1010-1013 and operates independently of user-specified flags, guaranteeing that review processes remain read-only.

Can network access be enabled in read-only mode?

According to the test fixture in tests/fake-codex-fixture.mjs, read-only mode typically disables network access (networkAccess: false). The sandbox configuration controls both filesystem and network permissions, with read-only environments restricting both capabilities.

What happens when workspace-write mode is activated?

When the write flag is true, codex-companion.mjs passes "workspace-write" to the app-server, granting the Codex runtime full permissions to edit, create, or delete files within the workspace directory. This mode is reserved for intentional code generation tasks that require repository mutation.

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