Project work sometimes reaches into a separate notes folder without needing write access to the rest of your home directory. A Codex permission profile can add that folder as a writable root while keeping unrelated locations outside the write boundary.
The primary workspace supplies the project context; an extra root allows supporting files to be edited without moving that context. A profile extending :workspace retains its baseline protections, including read-only control directories such as .git, .codex, and .agents inside workspace roots.
Permission profiles require a recent Codex CLI and remain a beta feature. A named configuration file makes the extra directory available on recurring launches that select it, without changing the default for other sessions. The project and supporting folder must already exist, and your operating-system account must have write access to both.
Steps to add a writable directory for Codex:
- Resolve the absolute paths of your project and supporting notes directory.
$ realpath "$HOME/projects/example-app" "$HOME/notes" /home/user/projects/example-app /home/user/notes
The paths shown are examples. Substitute your own existing directories here and use their printed absolute paths in the configuration and commands below. The extra root should name the intended folder rather than a broad parent such as your home directory.
- Open ~/.codex/project-notes.config.toml in your text editor.
If the file does not exist, create it at that exact location. If CODEX_HOME is set, the active file is project-notes.config.toml inside that directory instead. This is a named configuration layer selected with --profile project-notes; the base config.toml remains in place.
Permission profiles do not compose with legacy sandbox_mode or [sandbox_workspace_write] settings. If these occur in any loaded user, selected-profile, system, or trusted project configuration, resolve that conflict before using this method; deleting an existing policy can widen access for other sessions. A --sandbox or --approve-for-me launch also selects legacy sandbox behavior. See OpenAI's permission-profile documentation for migration details.
- Save a backup copy of an existing project-notes.config.toml under an unused filename.
A new file needs no backup. An unused backup name protects earlier backups; the remaining edits belong in project-notes.config.toml.
- Set the top-level default_permissions key to "project-notes" before the first table header in project-notes.config.toml.
- project-notes.config.toml
default_permissions = "project-notes"
If the key already exists at the top level, replace its value instead of adding another key. This selects the permission policy only for launches using this configuration layer. Setting it in the base user config.toml would instead change the default for other projects.
- Add the workspace-based permission definition at the end of project-notes.config.toml if [permissions.project-notes] is absent.
- project-notes.config.toml
[permissions.project-notes] extends = ":workspace"
If this section already extends :workspace, keep it and its other settings. If the name already identifies a different policy in any loaded layer, choose an unused permission name in default_permissions, both section headers, and the verification command's -P value instead of replacing its inheritance or restrictions. Permission profiles are separate from the configuration file selected by --profile.
- Add your notes directory to the workspace_roots table for project-notes in project-notes.config.toml.
The added directory and its descendants become writable to sandboxed commands using this policy. Existing sensitive notes remain exposed to modification or deletion, so grant only the folder the work needs.
- project-notes.config.toml
[permissions.project-notes.workspace_roots] "/home/user/notes" = true
If the section is absent, append this block at the end of the file. If it exists, insert only the path line inside that section before the next table header. The quoted path must be your notes directory's absolute path. If that exact path key already exists, set its value to true rather than duplicating it. Other root entries and permission rules stay in place.
- Save project-notes.config.toml in your text editor.
The file must contain only one definition of each key and table. Existing sessions retain their settings. Removing just the newly added root entry later reverses this grant without removing other roots.
- Start a fresh Codex session with the saved configuration layer and your project directory.
$ codex --profile project-notes -C /home/user/projects/example-app
The project path must be your own absolute path. The extra directory is saved in the named layer, so future launches with --profile project-notes reuse it without changing the primary workspace.
- Verify write access to your notes directory from another terminal with the saved configuration.
$ codex sandbox \ --profile project-notes \ -P project-notes \ --include-managed-config \ -C /home/user/projects/example-app \ -- mktemp /home/user/notes/codex.XXXXXX /home/user/notes/codex.pJfqGW
This runs a command under the selected permission policy without a model request or sign-in. Here --profile loads the named configuration file, while -P selects its permission profile. The project and notes paths must match your own directories. The --include-managed-config flag keeps administrator requirements in the check. Success returns a newly created empty file; a permission error means the extra root is not writable under that policy. TOML errors must be corrected before continuing. Trusted project overrides and managed requirements can affect normal sessions; an approved escalation uses separate controls.
- Remove only the temporary file whose exact path the write check returned.
$ rm /home/user/notes/codex.pJfqGW
The filename must be the one returned on your machine; no wildcard or existing note is needed. The saved writable root remains available for subsequent launches with --profile project-notes.