When to Use the workspace-write Sandbox Mode with the Codex Plugin

Enable workspace-write sandbox mode when your Codex skill must create, modify, or generate files within the temporary workspace, such as during code generation, build processes, or automated testing.

The openai/codex-plugin-cc repository implements a sandboxed execution environment that isolates Codex skills from the host system. By default, the sandbox operates in read-only mode, but you can escalate permissions to workspace-write when your skill needs to mutate files in the temporary workspace created for each job.

What Is the workspace-write Sandbox Mode?

The sandbox mode controls file-system access permissions for Codex skills. According to the source code in plugins/codex/scripts/lib/workspace.mjs, the sandbox configuration parses the skill's manifest and sets up appropriate flags. The default configuration restricts the skill to read-only access, while workspace-write explicitly grants write permissions to the temporary workspace directory.

When workspace-write is enabled, the skill can create new files, modify existing ones, and delete artifacts within the workspace boundaries. This mode remains confined to the temporary workspace and does not grant access to the broader host file system.

When to Enable workspace-write

You should configure workspace-write in your skill manifest when the execution logic involves any of the following file-mutation scenarios:

• Generating or modifying source files. When your skill creates new modules, applies patches, or updates configuration files, it requires write access to persist these changes for subsequent compilation or review steps.

• Running build tools that emit artifacts. Tools like npm run build, webpack, or make write compiled assets, bundles, and binaries to the workspace. Without write permissions, these build processes will fail with permission errors.

• Saving intermediate results. Skills that cache data between steps, write logs for debugging, or serialize temporary state need a writable workspace to persist information across the job lifecycle.

• Performing code refactoring or automatic fixes. When implementing lint auto-fixes, inserting type annotations, or transforming code, the skill must write the modified files back to the workspace, as demonstrated in skills like plugins/codex/skills/codex-result-handling/SKILL.md.

• Testing code that writes files. Unit tests or integration tests that create temporary files, generate coverage reports, or produce output artifacts require write access to complete successfully.

How the Sandbox Mode Is Configured

The permission model is implemented in plugins/codex/scripts/lib/workspace.mjs. This module reads the skill manifest and configures the sandbox flags accordingly.

The skill manifest, typically located at .claude-plugin/plugin.json, declares the required sandbox mode using the sandbox field. If omitted, the system defaults to read-only restrictions.

File operations within the sandbox are handled by plugins/codex/scripts/lib/fs.mjs, which respects the write permissions granted by the workspace-write configuration.

Configuration Examples

To request write permissions, declare the sandbox mode in your skill manifest:

{
  "name": "my-refactor-skill",
  "version": "1.0.0",
  "sandbox": "workspace-write",
  "commands": ["refactor"]
}

Inside plugins/codex/scripts/lib/workspace.mjs, the configuration logic parses this manifest and sets the write flag:

function configureSandbox(manifest) {
  const sandboxMode = manifest.sandbox || 'read-only';
  const writeEnabled = sandboxMode === 'workspace-write';
  return { writeEnabled };
}

When implementing a skill that writes files, you can use the file system helpers provided in the context:

export async function refactor(context) {
  // Write a new file to the workspace
  await context.fs.writeFile('src/generated.ts', generatedCode);
  
  // Run a build step that produces output files
  await context.runCommand('npm', ['run', 'build']);
}

Summary

• The workspace-write sandbox mode grants Codex skills permission to create, modify, and delete files within the temporary job workspace.
• Enable this mode when running build tools, generating code, performing automated fixes, or executing tests that produce output files.
• Configure the mode by setting "sandbox": "workspace-write" in the skill manifest (.claude-plugin/plugin.json).
• The sandbox configuration is processed in plugins/codex/scripts/lib/workspace.mjs, with file operations handled by plugins/codex/scripts/lib/fs.mjs.
• For read-only analysis and inspection tasks, use the default read-only mode to minimize security exposure.

Frequently Asked Questions

What is the default sandbox mode if I do not specify workspace-write?

If the skill manifest does not declare a sandbox field, the system defaults to read-only mode. In this state, the skill can read files from the workspace but cannot create, modify, or delete any content, as enforced by the logic in plugins/codex/scripts/lib/workspace.mjs.

Can I write to directories outside the temporary workspace with workspace-write mode?

No. The workspace-write mode restricts all write operations to the temporary workspace directory created for the specific job. It does not grant access to the host file system or other directories outside the sandbox boundaries.

Is workspace-write required for running package managers like npm install?

Yes. If your skill needs to install dependencies or modify node_modules, you must enable workspace-write because package managers write files to the workspace. The default read-only mode will block these operations and cause the command to fail.

How does the skill know if write permissions are enabled?

The skill implementation interacts with the file system through the context object provided by the sandbox. When workspace-write is configured, context.fs.writeFile and similar methods from plugins/codex/scripts/lib/fs.mjs execute successfully. In read-only mode, these operations throw permission errors.

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