A coding agent can inspect a project without letting its shell commands change unrelated files. Codex sandbox mode defines that local filesystem and network boundary, with workspace editing available when the task needs to change project files.

Approval policy controls whether a command can request access beyond the sandbox. An approved escalation can cross the normal boundary, and sandbox restrictions on local commands do not apply automatically to external MCP servers or prevent readable project data from reaching a model provider.

An installed Codex CLI can load a saved sandbox mode for new sessions while existing sessions retain their active permissions. The shell commands use Linux or macOS paths; operating-system support is still required to enforce the selected boundary.

Related: How to set Codex approval policy
Related: How to add a writable directory for Codex

Steps to set Codex sandbox mode:

  1. Choose the sandbox mode for the project's filesystem access.

    read-only permits inspection without filesystem writes. workspace-write permits edits in the active workspace and temporary directories, while protecting locations such as the project's .git, .agents, .codex, and .aws. danger-full-access removes the local filesystem and network sandbox while retaining the operating-system user's permissions.

    Full access exposes every file and network destination available to the current user. It belongs only in an intentionally isolated environment.

    Related: How to add a writable directory for Codex

  2. Create the user configuration directory if it does not exist. 
    $ mkdir -p "${CODEX_HOME:-$HOME/.codex}"

    The default directory is ~/.codex. An explicit CODEX_HOME selects a different configuration home.

  3. Open the active user configuration file in a text editor. 
    $ nano "${CODEX_HOME:-$HOME/.codex}/config.toml"

    The file is normally ~/.codex/config.toml; the editor creates it if it is missing. Another text editor can open the same path.

    If the configuration already uses default_permissions or [permissions] profiles, stop before adding sandbox_mode. A selected permission profile can take precedence over the legacy sandbox setting. Those profiles may contain security restrictions that a single sandbox mode cannot preserve; retain them and arrange a deliberate profile change with their owner rather than deleting them to make this setting load.

  4. Set the top-level sandbox mode to workspace-write.
    config.toml
    sandbox_mode = "workspace-write"

    An existing top-level sandbox_mode line is replaced in place. If the key is missing, its unindented line belongs before the first table header such as [history] or [sandbox_workspace_write]; in an empty file it can be the first line. A key below a table header belongs to that table. Never append a second copy of the key or duplicate a table header.

    The other mode names from the first step can replace workspace-write. Existing approval, network, provider, and other settings stay as they are. Without an explicit network setting, workspace-write disables command network access by default.

  5. Save config.toml in the editor.

    In nano, Ctrl+O followed by Enter writes the file to its current path.

  6. Close the editor after saving the file.

    In nano, Ctrl+X returns to the shell.

  7. Start a fresh Codex process from your project directory. 
    $ codex

    A new session loads the saved default. A resumed session may retain different permissions. No --sandbox, --profile, or -c override is needed for this check.

    Related: How to set the working directory for Codex
    Related: How to start a Codex interactive session

  8. Confirm that the new session reports the selected sandbox mode with /status. 
    /status
##### snipped #####
  Permissions:         Workspace (Ask for approval)
##### snipped #####

    Workspace corresponds to the saved workspace-write choice. The approval text reflects the existing approval policy and can differ. A different mode, a configuration error, or a policy rejection means the saved choice has not taken effect as intended; command-line overrides, a selected profile, trusted project configuration, or managed requirements can change or constrain the result.

    The displayed permissions identify the resolved policy; they do not prove operating-system enforcement. Sandbox-launch or namespace errors must be resolved before relying on that boundary, even if the displayed mode matches.

Share this guide