Filesystem Isolation & Mount Points

Filesystem isolation in Codex operates differently in local and cloud modes. Locally, the sandbox restricts write access to the project directory while allowing reads across the filesystem. In cloud microVMs, the project directory is mounted as a copy-on-write overlay — changes are captured as a diff against the base image and applied to the original files only after the session completes successfully. This means a failed or aborted cloud session leaves the original files untouched.

Mount point configuration controls what the microVM can see. By default, only the project directory and declared dependencies are mounted. System directories, home directory files, and other projects are not available. This is more restrictive than local mode, where Codex can read (but not write) anything your user account can access. The trade-off is explicit: cloud mode trades filesystem visibility for stronger isolation. If Codex needs a file outside the project directory in cloud mode, you must declare it in the configuration.

# Filesystem visibility comparison

Local mode (workspace-write):
  Read:  entire filesystem (user permissions)
  Write: project directory only
  Temp:  /tmp (writable)
  Home:  ~/.codex/ (writable for config)

Cloud mode (microVM):
  Read:  project directory + declared mounts only
  Write: project directory (copy-on-write overlay)
  Temp:  /tmp inside VM (ephemeral)
  Home:  not available unless mounted

# Declaring additional mounts for cloud mode
# config.toml:
# [cloud]
# additional_mounts = [
#   { source = "~/.npmrc", target = "~/.npmrc", readonly = true },
#   { source = "~/.ssh/known_hosts", target = "~/.ssh/known_hosts", readonly = true },
# ]

1. Identify external dependencies List files outside the project that Codex needs: .npmrc, SSH known_hosts, global configs. Each requires an explicit mount declaration in cloud mode.
2. Test write boundaries Ask Codex to write a file outside the project directory. In workspace-write mode, verify it fails. In no-sandbox mode, verify it succeeds (then stop using no-sandbox).
3. Leverage copy-on-write Use cloud mode for risky refactoring. If the result is good, apply the diff. If not, discard with zero risk to your working tree.