How to add a writable directory for Codex

Some Codex tasks need one supporting folder outside the project, such as notes, generated specs, or a shared fixture directory. Adding that folder as a writable root keeps workspace-write focused on the project while allowing edits in the extra location the task actually needs.

The --add-dir launch flag grants write access to an additional path alongside the primary workspace. The primary workspace comes from the shell's current directory by default, or from -C or --cd when the session is launched with an explicit working root.

Persistent writable roots belong under [sandbox_workspace_write] in ~/.codex/config.toml. They apply only to workspace-write sessions, and protected control directories such as .git, .codex, and .agents remain read-only under the sandbox even when their parent root is writable.

1. Review the installed CLI help for the writable-root flag.

   $ codex --help
   ##### snipped #####
     -C, --cd <DIR>
             Tell the agent to use the specified directory as its working root
   
         --add-dir <DIR>
             Additional directories that should be writable alongside the primary workspace
   ##### snipped #####

   Current OpenAI docs describe the same flag as repeatable, so the option can be passed more than once when several extra paths are needed.

2. Start a workspace-write session with one extra writable directory.

   $ codex --sandbox workspace-write --add-dir /home/user/notes

   Use an absolute path so copied commands, shell history, and launch scripts all point at the same writable boundary.

3. Add more writable directories by repeating the flag.

   $ codex --sandbox workspace-write --add-dir /home/user/notes --add-dir /home/user/specs

   Add only the directories the task needs. If every local path must be writable, use a controlled full-access environment instead of quietly expanding workspace-write.

   Related: How to set Codex sandbox mode

4. Set a different primary workspace with -C when needed.

   $ codex -C /home/user/project --sandbox workspace-write --add-dir /home/user/notes

   -C changes the main working root; --add-dir adds a separate writable path without changing where project instructions and repository context are loaded.

   Related: How to set the working directory for Codex

5. Create the Codex config directory when it does not exist.

   $ mkdir -p ~/.codex

6. Open the user Codex config file.

   $ vi ~/.codex/config.toml

   Use a project .codex/config.toml only when the extra writable roots should apply to one trusted project instead of every local Codex session.

7. Save recurring writable roots in the config file.

   ~/.codex/config.toml

   sandbox_mode = "workspace-write"
   approval_policy = "on-request"
    
   [sandbox_workspace_write]
   writable_roots = ["/home/user/notes", "/home/user/specs"]
   network_access = false

   Saved writable_roots are for sessions that load this config. One-off --add-dir flags still apply only to the command process that includes them.

8. Check the saved writable roots.

   $ cat ~/.codex/config.toml
   sandbox_mode = "workspace-write"
   approval_policy = "on-request"
   
   [sandbox_workspace_write]
   writable_roots = ["/home/user/notes", "/home/user/specs"]
   network_access = false

   Start a new Codex session after editing the file so the saved workspace-write boundary is loaded.