CDX-301b · Module 1

File Access Patterns & Boundaries

3 min read

Codex file access is governed by the sandbox mode. In workspace-write mode, Codex can read any file on the filesystem but can only write within the project directory. In read-only mode, Codex can read but cannot write anywhere. In no-sandbox mode, Codex has the same filesystem permissions as your user account. Understanding these boundaries is critical because Codex will attempt to read configuration files, dependency caches, and system files during normal operation — and the sandbox determines whether those reads succeed.

File access patterns in practice go beyond the sandbox boundary. Codex reads files to build context: package.json for dependencies, tsconfig.json for compiler settings, .env files for environment structure (though not secrets if properly configured). It writes files during code generation, refactoring, and test creation. The danger zone is when Codex reads sensitive files — SSH keys, .env with secrets, credential stores — and includes that content in its context, which is then sent to the API. The sandbox prevents writes, but it does not prevent reads of sensitive data.

Mitigate read-side risks by structuring your project so sensitive files live outside the project directory. Credentials in ~/.config/ or /etc/ are readable but less likely to be contextually relevant. Better yet, use a secrets manager and reference secrets by name in environment variables. Codex sees the variable name, not the value, unless it runs a command that echoes the value.

# File access matrix by sandbox mode

                    workspace-write    read-only    no-sandbox
Read project files       YES              YES           YES
Write project files      YES              NO            YES
Read outside project     YES              YES           YES
Write outside project    NO               NO            YES
Read ~/.ssh/             YES (danger)     YES (danger)  YES (danger)
Read .env                YES (danger)     YES (danger)  YES (danger)
Write /etc/              NO               NO            YES (danger)

# Mitigation: never store secrets in the project directory
# Mitigation: use AGENTS.md rule "never read or display .env contents"

Do This

  • Store secrets outside the project directory in a proper secrets manager
  • Add AGENTS.md rules that explicitly forbid reading sensitive files
  • Use workspace-write mode as the default — it prevents the most dangerous writes
  • Audit which files Codex reads during a session using /status or session logs

Avoid This

  • Store .env files with real secrets in the project directory
  • Assume the sandbox prevents Codex from reading sensitive files — it only restricts writes
  • Use no-sandbox mode on a machine with production credentials
  • Forget that Codex sends file contents to the API — sensitive reads become API transmissions