Security Implications of the Workspace-Write Sandbox Mode in the Codex Plugin

The workspace-write sandbox mode grants the Codex runtime unrestricted write access to your repository, exposing the system to risks of arbitrary file modification and privilege escalation unless explicitly invoked via the --write flag.

The openai/codex-plugin-cc repository implements a dual-mode sandbox architecture that defaults to read-only access, but the workspace-write sandbox mode enables full file-system mutations for automated code changes. Understanding how this mode is selected—specifically through the request.write boolean and sandbox option propagation—is critical for securing your development environment against unintended modifications and potential code injection attacks.

How the Workspace-Write Sandbox Mode Works

The Codex plugin determines sandbox permissions through conditional checks that evaluate the request.write flag before initiating a turn.

Sandbox Selection Logic

In codex-companion.mjs at line 491, the plugin evaluates the write request to determine the sandbox type:

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

This ternary operator represents the primary security gate. When request.write evaluates to true—typically via the --write CLI flag—the plugin selects "workspace-write", granting the Codex runtime permission to issue fileChange commands that modify repository files.

Default Read-Only Protection

If no sandbox option is explicitly provided, the plugin enforces a safe default. In codex.mjs at lines 68-69, the code ensures read-only operation:

sandbox: options.sandbox ?? "read-only"

This nullish coalescing operator guarantees that undefined or missing sandbox configurations fall back to "read-only", preventing accidental write operations.

Workspace Root Resolution

Before launching a write-capable turn, the plugin resolves the workspace boundary. At lines 462-463 in codex-companion.mjs, the plugin calls:

resolveWorkspaceRoot(request.cwd)

This function prefers a Git repository root via ensureGitRepository but falls back to the current working directory. This resolution is critical because the workspace-write sandbox restricts file operations to this specific root directory.

Server Communication

When initiating the turn, the selected sandbox mode is forwarded to the Codex app-server. At lines 891-892 in codex-companion.mjs, the runAppServerTurn function propagates the sandbox configuration:

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

This value determines whether the Codex runtime can generate fileChange commands that the plugin subsequently applies to the filesystem.

Security Risks and Threat Models

Enabling the workspace-write sandbox mode introduces several security implications that developers must understand before running automated code generation.

Arbitrary File Modification

In workspace-write mode, Codex can create, delete, or overwrite any file under the resolved workspace root. An attacker who convinces a user to run a task with --write could inject malicious code directly into configuration files, build scripts, or source code. Unlike read-only mode where the runtime can only analyze files, write-capable turns can permanently alter the repository state.

Privilege Escalation

The plugin executes under the same user privileges as the invoking CLI process. When workspace-write mode is active, any Codex-generated file operation inherits these OS-level permissions. A compromised or manipulated Codex process could modify sensitive system files, SSH keys, environment configurations, or executable binaries that the user has access to, effectively operating with the full authority of the invoking user.

Data Exfiltration Vectors

While the sandbox explicitly disables network access (networkAccess: false), preventing direct exfiltration over HTTP, the workspace-write mode enables indirect data theft. A malicious prompt or compromised runtime could copy sensitive files from outside the workspace into a new file within the repository. An attacker could then retrieve this data through a subsequent read-only operation or by accessing the newly created file after the write operation completes.

Limited Execution Containment

The workspace-write sandbox only restricts where Codex can write files—it does not provide process-level isolation. Unlike containerized sandboxes that isolate the runtime from the host system, this mode allows the Codex process direct access to system libraries, environment variables, and the host filesystem structure. Any vulnerability in the Codex runtime itself could potentially escape the intended workspace boundaries and affect the host system.

Workspace Boundary Uncertainty

The resolveWorkspaceRoot function's fallback behavior poses a containment risk. If the current directory is not a Git repository, the function defaults to the current working directory (cwd), which might be the user's home directory or another sensitive location. This means writes could inadvertently affect files outside the intended project scope if the user executes the command from an unexpected directory.

Activating Write Capabilities Safely

Understanding the activation mechanisms helps developers use the workspace-write sandbox mode securely.

Explicit Write Invocation

To enable file modifications, you must explicitly request write access using the --write flag:

codex task --write --prompt "Refactor the authentication module"

This command sets request.write = true, triggering the "workspace-write" sandbox selection at line 491 of codex-companion.mjs. The Codex runtime can now generate fileChange commands that the plugin applies automatically to files under the resolved workspace root.

Default Read-Only Operation

Omitting the write flag guarantees a safe, non-destructive review:

codex review --target src/

Without --write, request.write remains falsy, forcing the sandbox to "read-only" according to the logic in codex-companion.mjs. No fileChange commands will be issued, ensuring the repository remains untouched regardless of the prompt content.

Programmatic API Usage

When using the Node.js API directly, you control the sandbox mode via the sandbox option in runAppServerTurn:

import { runAppServerTurn } from "./plugins/codex/scripts/lib/codex.mjs";

await runAppServerTurn(process.cwd(), {
  prompt: "Add logging to all exported functions",
  sandbox: "workspace-write",   // enables file modifications
  onProgress: console.log,
});

This programmatic approach requires explicit selection of "workspace-write"; any other value (or omission) defaults to read-only behavior as implemented in codex.mjs lines 68-69.

Summary

• The workspace-write sandbox mode is the only configuration in openai/codex-plugin-cc that permits the Codex runtime to modify files under the repository root.
• Security risks include arbitrary file modification, privilege escalation through inherited user permissions, data exfiltration via file copying, and limited process containment without containerization.
• The plugin mitigates risks by defaulting to "read-only" mode in codex.mjs and requiring explicit activation through the --write flag or sandbox: "workspace-write" option.
• Write operations are restricted to the resolved workspace root determined by resolveWorkspaceRoot, though fallback to the current directory can expand the affected scope if not in a Git repository.
• Network access remains disabled (networkAccess: false) even in write mode, preventing direct outbound data transmission but not local file-based exfiltration.

Frequently Asked Questions

What is the difference between workspace-write and read-only sandbox modes?

The read-only sandbox mode restricts the Codex runtime to analyzing and reading files without issuing fileChange commands, ensuring no modifications occur regardless of the prompt. The workspace-write mode, activated via request.write or the --write flag, grants the runtime permission to create, delete, and overwrite files under the resolved workspace root. According to the source code in codex-companion.mjs, this is controlled by a single ternary operator that switches between "workspace-write" and "read-only" based on the request parameters.

How does the plugin prevent accidental file modifications?

The plugin implements defense-in-depth through default-safe configurations. In codex.mjs at lines 68-69, the code uses nullish coalescing (options.sandbox ?? "read-only") to ensure that any undefined or missing sandbox configuration defaults to read-only. Additionally, the CLI requires the explicit --write flag to set request.write = true, making file modifications an intentional opt-in action rather than a default behavior.

Can workspace-write mode access files outside the repository directory?

The sandbox restricts write operations to the workspace root resolved by resolveWorkspaceRoot(request.cwd) at lines 462-463 in codex-companion.mjs. This function attempts to locate a Git repository root via ensureGitRepository, but falls back to the current working directory if no .git directory is found. Consequently, if you execute Codex from your home directory or another non-repository location with --write, the sandbox could potentially modify files in that directory and its subdirectories, not just within a specific project.

Is network access permitted in workspace-write mode?

No, network access remains explicitly disabled even in workspace-write mode. The sandbox configuration includes networkAccess: false, which prevents the Codex runtime from making HTTP requests or establishing network connections during write-capable turns. However, this restriction does not prevent local data exfiltration—an attacker could still use the write capability to copy sensitive files into the workspace for later retrieval through read-only operations or direct access.

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