OpenAI - Codex Docs Changes 2026-04-24 18:20 UTC → 2026-05-01 18:29 UTC

24- **Codex cloud**: Runs in isolated OpenAI-managed containers, preventing access to your host system or unrelated data. Uses a two-phase runtime model: setup runs before the agent phase and can access the network to install specified dependencies, then the agent phase runs offline by default unless you enable internet access for that environment. Secrets configured for cloud environments are available only during setup and are removed before the agent phase starts.24- **Codex cloud**: Runs in isolated OpenAI-managed containers, preventing access to your host system or unrelated data. Uses a two-phase runtime model: setup runs before the agent phase and can access the network to install specified dependencies, then the agent phase runs offline by default unless you enable internet access for that environment. Secrets configured for cloud environments are available only during setup and are removed before the agent phase starts.

25- **Codex CLI / IDE extension**: OS-level mechanisms enforce sandbox policies. Defaults include no network access and write permissions limited to the active workspace. You can configure the sandbox, approval policy, and network settings based on your risk tolerance.25- **Codex CLI / IDE extension**: OS-level mechanisms enforce sandbox policies. Defaults include no network access and write permissions limited to the active workspace. You can configure the sandbox, approval policy, and network settings based on your risk tolerance.

26 26 

27In the `Auto` preset (for example, `--full-auto`), Codex can read files, make edits, and run commands in the working directory automatically.27In the `Auto` preset (for example, `--sandbox workspace-write --ask-for-approval on-request`), Codex can read files, make edits, and run commands in the working directory automatically.

28 28 

29Codex asks for approval to edit files outside the workspace or to run commands that require network access. If you want to chat or plan without making changes, switch to `read-only` mode with the `/permissions` command.29Codex asks for approval to edit files outside the workspace or to run commands that require network access. If you want to chat or plan without making changes, switch to `read-only` mode with the `/permissions` command.

30 30 

150 150 

151| Intent | Flags | Effect |151| Intent | Flags | Effect |

152| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |152| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |

153| Auto (preset) | *no flags needed* or `--full-auto` | Codex can read files, make edits, and run commands in the workspace. Codex requires approval to edit outside the workspace or to access network. |153| Auto (preset) | *no flags needed* or `--sandbox workspace-write --ask-for-approval on-request` | Codex can read files, make edits, and run commands in the workspace. Codex requires approval to edit outside the workspace or to access network. |

154| Safe read-only browsing | `--sandbox read-only --ask-for-approval on-request` | Codex can read files and answer questions. Codex requires approval to make edits, run commands, or access network. |154| Safe read-only browsing | `--sandbox read-only --ask-for-approval on-request` | Codex can read files and answer questions. Codex requires approval to make edits, run commands, or access network. |

155| Read-only non-interactive (CI) | `--sandbox read-only --ask-for-approval never` | Codex can only read files; never asks for approval. |155| Read-only non-interactive (CI) | `--sandbox read-only --ask-for-approval never` | Codex can only read files; never asks for approval. |

156| Automatically edit but ask for approval to run untrusted commands | `--sandbox workspace-write --ask-for-approval untrusted` | Codex can read and edit files but asks for approval before running untrusted commands. |156| Automatically edit but ask for approval to run untrusted commands | `--sandbox workspace-write --ask-for-approval untrusted` | Codex can read and edit files but asks for approval before running untrusted commands. |

157| Dangerous full access | `--dangerously-bypass-approvals-and-sandbox` (alias: `--yolo`) | [Elevated Risk](https://help.openai.com/articles/20001061) No sandbox; no approvals *(not recommended)* |157| Dangerous full access | `--dangerously-bypass-approvals-and-sandbox` (alias: `--yolo`) | [Elevated Risk](https://help.openai.com/articles/20001061) No sandbox; no approvals *(not recommended)* |

158 158 

159`--full-auto` is a convenience alias for `--sandbox workspace-write --ask-for-approval on-request`.159For non-interactive runs, use `codex exec --sandbox workspace-write`; Codex keeps older `codex exec --full-auto` invocations as a deprecated compatibility path and prints a warning.

160 160 

161With `--ask-for-approval untrusted`, Codex runs only known-safe read operations automatically. Commands that can mutate state or trigger external execution paths (for example, destructive Git operations or Git output/config-override flags) require approval.161With `--ask-for-approval untrusted`, Codex runs only known-safe read operations automatically. Commands that can mutate state or trigger external execution paths (for example, destructive Git operations or Git output/config-override flags) require approval.

162 162 

202 202 

203```bash203```bash

204# macOS204# macOS

205codex sandbox macos [--full-auto] [--log-denials] [COMMAND]...205codex sandbox macos [--permissions-profile <name>] [--log-denials] [COMMAND]...

206# Linux206# Linux

207codex sandbox linux [--full-auto] [COMMAND]...207codex sandbox linux [--permissions-profile <name>] [COMMAND]...

208# Windows

209codex sandbox windows [--permissions-profile <name>] [COMMAND]...

208```210```

209 211 

210The `sandbox` command is also available as `codex debug`, and the platform helpers have aliases (for example `codex sandbox seatbelt` and `codex sandbox landlock`).212The `sandbox` command is also available as `codex debug`, and the platform helpers have aliases (for example `codex sandbox seatbelt` and `codex sandbox landlock`).

222- `thread/turns/list` - page through a stored thread's turn history without resuming it.222- `thread/turns/list` - page through a stored thread's turn history without resuming it.

223- `thread/loaded/list` - list the thread ids currently loaded in memory.223- `thread/loaded/list` - list the thread ids currently loaded in memory.

224- `thread/name/set` - set or update a thread's user-facing name for a loaded thread or a persisted rollout; emits `thread/name/updated`.224- `thread/name/set` - set or update a thread's user-facing name for a loaded thread or a persisted rollout; emits `thread/name/updated`.

225- `thread/goal/set` - set the goal for a loaded thread (experimental; requires `capabilities.experimentalApi`); emits `thread/goal/updated`.

226- `thread/goal/get` - read the current goal for a loaded thread (experimental; requires `capabilities.experimentalApi`).

227- `thread/goal/clear` - clear the goal for a loaded thread (experimental; requires `capabilities.experimentalApi`); emits `thread/goal/cleared`.

225- `thread/metadata/update` - patch SQLite-backed stored thread metadata; currently supports persisted `gitInfo`.228- `thread/metadata/update` - patch SQLite-backed stored thread metadata; currently supports persisted `gitInfo`.

226- `thread/archive` - move a thread's log file into the archived directory; returns `{}` on success and emits `thread/archived`.229- `thread/archive` - move a thread's log file into the archived directory; returns `{}` on success and emits `thread/archived`.

227- `thread/unsubscribe` - unsubscribe this connection from thread turn/item events. If this was the last subscriber, the server unloads the thread after a no-subscriber inactivity grace period and emits `thread/closed`.230- `thread/unsubscribe` - unsubscribe this connection from thread turn/item events. If this was the last subscriber, the server unloads the thread after a no-subscriber inactivity grace period and emits `thread/closed`.

242- `command/exec/terminate` - stop a running `command/exec` session.245- `command/exec/terminate` - stop a running `command/exec` session.

243- `command/exec/outputDelta` (notify) - emitted for base64-encoded stdout/stderr chunks from a streaming `command/exec` session.246- `command/exec/outputDelta` (notify) - emitted for base64-encoded stdout/stderr chunks from a streaming `command/exec` session.

244- `model/list` - list available models (set `includeHidden: true` to include entries with `hidden: true`) with effort options, optional `upgrade`, and `inputModalities`.247- `model/list` - list available models (set `includeHidden: true` to include entries with `hidden: true`) with effort options, optional `upgrade`, and `inputModalities`.

248- `modelProvider/capabilities/read` - read provider capability bounds for model/provider combinations (experimental; requires `capabilities.experimentalApi`).

245- `experimentalFeature/list` - list feature flags with lifecycle stage metadata and cursor pagination.249- `experimentalFeature/list` - list feature flags with lifecycle stage metadata and cursor pagination.

246- `experimentalFeature/enablement/set` - patch in-memory runtime enablement for supported feature keys such as `apps` and `plugins`.250- `experimentalFeature/enablement/set` - patch in-memory runtime enablement for supported feature keys such as `apps` and `plugins`.

247- `collaborationMode/list` - list collaboration mode presets (experimental, no pagination).251- `collaborationMode/list` - list collaboration mode presets (experimental, no pagination).

248- `skills/list` - list skills for one or more `cwd` values (supports `forceReload` and optional `perCwdExtraUserRoots`).252- `skills/list` - list skills for one or more `cwd` values (supports `forceReload` and optional `perCwdExtraUserRoots`).

249- `skills/changed` (notify) - emitted when watched local skill files change.253- `skills/changed` (notify) - emitted when watched local skill files change.

250- `marketplace/add` - add a remote plugin marketplace and persist it into the user's marketplace config.254- `marketplace/add` - add a remote plugin marketplace and persist it into the user's marketplace config.

255- `marketplace/upgrade` - refresh a configured Git marketplace, or all configured Git marketplaces when you omit the marketplace name.

251- `plugin/list` - list discovered plugin marketplaces and plugin state, including install/auth policy metadata, marketplace load errors, featured plugin ids, and local, Git, or remote plugin source metadata.256- `plugin/list` - list discovered plugin marketplaces and plugin state, including install/auth policy metadata, marketplace load errors, featured plugin ids, and local, Git, or remote plugin source metadata.

252- `plugin/read` - read one plugin by marketplace path or remote marketplace name and plugin name, including bundled skills, apps, and MCP server names when those details are available.257- `plugin/read` - read one plugin by marketplace path or remote marketplace name and plugin name, including bundled skills, apps, and MCP server names when those details are available.

253- `plugin/install` - install a plugin from a marketplace path or remote marketplace name.258- `plugin/install` - install a plugin from a marketplace path or remote marketplace name.

265- `feedback/upload` - submit a feedback report (classification + optional reason/logs + conversation id, plus optional `extraLogFiles` attachments).270- `feedback/upload` - submit a feedback report (classification + optional reason/logs + conversation id, plus optional `extraLogFiles` attachments).

266- `config/read` - fetch the effective configuration on disk after resolving configuration layering.271- `config/read` - fetch the effective configuration on disk after resolving configuration layering.

267- `externalAgentConfig/detect` - detect external-agent artifacts that can be migrated with `includeHome` and optional `cwds`; each detected item includes `cwd` (`null` for home).272- `externalAgentConfig/detect` - detect external-agent artifacts that can be migrated with `includeHome` and optional `cwds`; each detected item includes `cwd` (`null` for home).

268- `externalAgentConfig/import` - apply selected external-agent migration items by passing explicit `migrationItems` with `cwd` (`null` for home); plugin imports emit `externalAgentConfig/import/completed`.273- `externalAgentConfig/import` - apply selected external-agent migration items by passing explicit `migrationItems` with `cwd` (`null` for home). Supported item types include config, skills, `AGENTS.md`, plugins, MCP server config, subagents, hooks, commands, and sessions; plugin imports emit `externalAgentConfig/import/completed`.

269- `config/value/write` - write a single configuration key/value to the user's `config.toml` on disk.274- `config/value/write` - write a single configuration key/value to the user's `config.toml` on disk.

270- `config/batchWrite` - apply configuration edits atomically to the user's `config.toml` on disk.275- `config/batchWrite` - apply configuration edits atomically to the user's `config.toml` on disk.

271- `configRequirements/read` - fetch requirements from `requirements.toml` and/or MDM, including allow-lists, pinned `featureRequirements`, and residency/network requirements (or `null` if you haven't set any up).276- `configRequirements/read` - fetch requirements from `requirements.toml` and/or MDM, including allow-lists, pinned `featureRequirements`, and residency/network requirements (or `null` if you haven't set any up).

30 30 

31![Codex app Appearance settings showing theme selection, color controls, and font options](/images/codex/app/theme-selection-light.webp)31![Codex app Appearance settings showing theme selection, color controls, and font options](/images/codex/app/theme-selection-light.webp)

32 32 

33### Codex pets

34 

35 Codex pets are optional animated companions for the app. In **Settings**,

36choose **Pets** to select a built-in pet or refresh custom pets from your

37local Codex home. Type `/pet` in the composer, use **Wake Pet** or **Tuck Away Pet** in Settings, or

38 press <kbd>Cmd+K</kbd> or <kbd>Ctrl+K</kbd> and run the same commands to

39 toggle the floating overlay.

40 

41 The overlay keeps active Codex work visible while you use other apps. It

42 shows the active thread, reflects whether Codex is running, waiting for

43 input, or ready for review, and pairs that state with a short progress

44 prompt so you can glance at what changed without reopening the thread.

45 

461/8

47 

48CodexI found a tiny loose thread in settings. Want me to tug it?

49 

50To create your own pet, install the `hatch-pet` skill:

51 

52```text

53$skill-installer hatch-pet

54```

55 

56Reload skills from the command menu. Press <kbd>Cmd+K</kbd> or <kbd>Ctrl+K</kbd>,

57choose **Force Reload Skills**, then ask the skill to create a pet:

58 

59```text

60$hatch-pet create a new pet inspired by my recent projects

61```

62 

33## Git63## Git

34 64 

35Use Git settings to standardize branch naming and choose whether Codex uses force65Use Git settings to standardize branch naming and choose whether Codex uses force

46## Browser use76## Browser use

47 77 

48Use these settings to install or enable the bundled Browser plugin and manage78Use these settings to install or enable the bundled Browser plugin and manage

49allowlisted and blocklisted websites. Codex asks before using a website79allowed and blocked websites. Codex asks before using a website unless you've

50unless you’ve allowlisted it. Removing a site from the blocklist lets Codex ask80allowed it. Removing a site from the blocked list lets Codex ask

51again before using it in the browser.81again before using it in the browser.

52 82 

53See [In-app browser](https://developers.openai.com/codex/app/browser) for browser preview, comment, and83See [In-app browser](https://developers.openai.com/codex/app/browser) for browser preview, comment, and

58On macOS, check your Computer Use settings to review desktop-app access and related88On macOS, check your Computer Use settings to review desktop-app access and related

59preferences after setup. To revoke system-level access, update Screen Recording89preferences after setup. To revoke system-level access, update Screen Recording

60or Accessibility permissions in macOS Privacy & Security settings. The feature90or Accessibility permissions in macOS Privacy & Security settings. The feature

61isn’t available in the European Economic Area, the United Kingdom, or Switzerland91isn't available in the EEA, the United Kingdom, or Switzerland at launch.

62at launch.

63 92 

64## Personalization93## Personalization

65 94 

254 254 

255## Slash commands255## Slash commands

256 256 

257Slash commands give you quick access to specialized workflows like `/review`, `/fork`, or your own reusable prompts. Codex ships with a curated set of built-ins, and you can create custom ones for team-specific tasks or personal shortcuts.257Slash commands give you quick access to specialized workflows like `/review`, `/fork`, `/side`, or your own reusable prompts. Codex ships with a curated set of built-ins, and you can create custom ones for team-specific tasks or personal shortcuts.

258 258 

259See the [slash commands guide](https://developers.openai.com/codex/guides/slash-commands) to browse the catalog of built-ins, learn how to author custom commands, and understand where they live on disk.259See the [slash commands guide](https://developers.openai.com/codex/guides/slash-commands) to browse the catalog of built-ins, learn how to author custom commands, and understand where they live on disk.

260 260 

20| `--dangerously-bypass-approvals-and-sandbox, --yolo` | `boolean` | Run every command without approvals or sandboxing. Only use inside an externally hardened environment. |20| `--dangerously-bypass-approvals-and-sandbox, --yolo` | `boolean` | Run every command without approvals or sandboxing. Only use inside an externally hardened environment. |

21| `--disable` | `feature` | Force-disable a feature flag (translates to `-c features.<name>=false`). Repeatable. |21| `--disable` | `feature` | Force-disable a feature flag (translates to `-c features.<name>=false`). Repeatable. |

22| `--enable` | `feature` | Force-enable a feature flag (translates to `-c features.<name>=true`). Repeatable. |22| `--enable` | `feature` | Force-enable a feature flag (translates to `-c features.<name>=true`). Repeatable. |

23| `--full-auto` | `boolean` | Shortcut for low-friction local work: sets `--ask-for-approval on-request` and `--sandbox workspace-write`. |

24| `--image, -i` | `path[,path...]` | Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag. |23| `--image, -i` | `path[,path...]` | Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag. |

25| `--model, -m` | `string` | Override the model set in configuration (for example `gpt-5.4`). |24| `--model, -m` | `string` | Override the model set in configuration (for example `gpt-5.4`). |

26| `--no-alt-screen` | `boolean` | Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run). |25| `--no-alt-screen` | `boolean` | Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run). |

118 117 

119Key118Key

120 119 

121`--full-auto`

122 

123Type / Values

124 

125`boolean`

126 

127Details

128 

129Shortcut for low-friction local work: sets `--ask-for-approval on-request` and `--sandbox workspace-write`.

130 

131Key

132 

133`--image, -i`120`--image, -i`

134 121 

135Type / Values122Type / Values

268| [`codex cloud`](https://developers.openai.com/codex/cli/reference#codex-cloud) | Experimental | Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: `codex cloud-tasks`. |255| [`codex cloud`](https://developers.openai.com/codex/cli/reference#codex-cloud) | Experimental | Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: `codex cloud-tasks`. |

269| [`codex completion`](https://developers.openai.com/codex/cli/reference#codex-completion) | Stable | Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell. |256| [`codex completion`](https://developers.openai.com/codex/cli/reference#codex-completion) | Stable | Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell. |

270| [`codex debug app-server send-message-v2`](https://developers.openai.com/codex/cli/reference#codex-debug-app-server-send-message-v2) | Experimental | Debug app-server by sending a single V2 message through the built-in test client. |257| [`codex debug app-server send-message-v2`](https://developers.openai.com/codex/cli/reference#codex-debug-app-server-send-message-v2) | Experimental | Debug app-server by sending a single V2 message through the built-in test client. |

258| [`codex debug models`](https://developers.openai.com/codex/cli/reference#codex-debug-models) | Experimental | Print the raw model catalog Codex sees, including an option to inspect only the bundled catalog. |

271| [`codex exec`](https://developers.openai.com/codex/cli/reference#codex-exec) | Stable | Run Codex non-interactively. Alias: `codex e`. Stream results to stdout or JSONL and optionally resume previous sessions. |259| [`codex exec`](https://developers.openai.com/codex/cli/reference#codex-exec) | Stable | Run Codex non-interactively. Alias: `codex e`. Stream results to stdout or JSONL and optionally resume previous sessions. |

272| [`codex execpolicy`](https://developers.openai.com/codex/cli/reference#codex-execpolicy) | Experimental | Evaluate execpolicy rule files and see whether a command would be allowed, prompted, or blocked. |260| [`codex execpolicy`](https://developers.openai.com/codex/cli/reference#codex-execpolicy) | Experimental | Evaluate execpolicy rule files and see whether a command would be allowed, prompted, or blocked. |

273| [`codex features`](https://developers.openai.com/codex/cli/reference#codex-features) | Stable | List feature flags and persistently enable or disable them in `config.toml`. |261| [`codex features`](https://developers.openai.com/codex/cli/reference#codex-features) | Stable | List feature flags and persistently enable or disable them in `config.toml`. |

278| [`codex mcp-server`](https://developers.openai.com/codex/cli/reference#codex-mcp-server) | Experimental | Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex. |266| [`codex mcp-server`](https://developers.openai.com/codex/cli/reference#codex-mcp-server) | Experimental | Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex. |

279| [`codex plugin marketplace`](https://developers.openai.com/codex/cli/reference#codex-plugin-marketplace) | Experimental | Add, upgrade, or remove plugin marketplaces from Git or local sources. |267| [`codex plugin marketplace`](https://developers.openai.com/codex/cli/reference#codex-plugin-marketplace) | Experimental | Add, upgrade, or remove plugin marketplaces from Git or local sources. |

280| [`codex resume`](https://developers.openai.com/codex/cli/reference#codex-resume) | Stable | Continue a previous interactive session by ID or resume the most recent conversation. |268| [`codex resume`](https://developers.openai.com/codex/cli/reference#codex-resume) | Stable | Continue a previous interactive session by ID or resume the most recent conversation. |

281| [`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox) | Experimental | Run arbitrary commands inside Codex-provided macOS seatbelt or Linux bubblewrap sandboxes. |269| [`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox) | Experimental | Run arbitrary commands inside Codex-provided macOS, Linux, or Windows sandboxes. |

270| [`codex update`](https://developers.openai.com/codex/cli/reference#codex-update) | Stable | Check for and apply a Codex CLI update when the installed release supports self-update. |

282 271 

283Key272Key

284 273 

366 355 

367Key356Key

368 357 

358[`codex debug models`](https://developers.openai.com/codex/cli/reference#codex-debug-models)

359 

360Maturity

361 

362Experimental

363 

364Details

365 

366Print the raw model catalog Codex sees, including an option to inspect only the bundled catalog.

367 

368Key

369 

369[`codex exec`](https://developers.openai.com/codex/cli/reference#codex-exec)370[`codex exec`](https://developers.openai.com/codex/cli/reference#codex-exec)

370 371 

371Maturity372Maturity

494 495 

495Details496Details

496 497 

497Run arbitrary commands inside Codex-provided macOS seatbelt or Linux bubblewrap sandboxes.498Run arbitrary commands inside Codex-provided macOS, Linux, or Windows sandboxes.

499 

500Key

501 

502[`codex update`](https://developers.openai.com/codex/cli/reference#codex-update)

503 

504Maturity

505 

506Stable

507 

508Details

509 

510Check for and apply a Codex CLI update when the installed release supports self-update.

498 511 

499Expand to view all512Expand to view all

500 513 

502 515 

503### `codex` (interactive)516### `codex` (interactive)

504 517 

505Running `codex` with no subcommand launches the interactive terminal UI (TUI). The agent accepts the global flags above plus image attachments. Web search defaults to cached mode; use `--search` to switch to live browsing and `--full-auto` to let Codex run most commands without prompts.518Running `codex` with no subcommand launches the interactive terminal UI (TUI). The agent accepts the global flags above plus image attachments. Web search defaults to cached mode; use `--search` to switch to live browsing. For low-friction local work, use `--sandbox workspace-write --ask-for-approval on-request`.

506 519 

507Use `--remote ws://host:port` or `--remote wss://host:port` to connect the TUI to an app server started with `codex app-server --listen ws://IP:PORT`. Add `--remote-auth-token-env <ENV_VAR>` when the server requires a bearer token for WebSocket authentication. See [Codex CLI features](https://developers.openai.com/codex/cli/features#connect-the-tui-to-a-remote-app-server) for setup examples and authentication guidance.520Use `--remote ws://host:port` or `--remote wss://host:port` to connect the TUI to an app server started with `codex app-server --listen ws://IP:PORT`. Add `--remote-auth-token-env <ENV_VAR>` when the server requires a bearer token for WebSocket authentication. See [Codex CLI features](https://developers.openai.com/codex/cli/features#connect-the-tui-to-a-remote-app-server) for setup examples and authentication guidance.

508 521 

665 678 

666This debug flow initializes with `experimentalApi: true`, starts a thread, sends a turn, and streams server notifications. Use it to reproduce and inspect app-server protocol behavior locally.679This debug flow initializes with `experimentalApi: true`, starts a thread, sends a turn, and streams server notifications. Use it to reproduce and inspect app-server protocol behavior locally.

667 680 

681### `codex debug models`

682 

683Print the raw model catalog Codex sees as JSON.

684 

685| Key | Type / Values | Details |

686| --- | --- | --- |

687| `--bundled` | `boolean` | Skip refresh and print only the model catalog bundled with the current Codex binary. |

688 

689Key

690 

691`--bundled`

692 

693Type / Values

694 

695`boolean`

696 

697Details

698 

699Skip refresh and print only the model catalog bundled with the current Codex binary.

700 

701Use `--bundled` when you want to inspect only the catalog bundled with the current binary, without refreshing from the remote models endpoint.

702 

668### `codex apply`703### `codex apply`

669 704 

670Apply the most recent diff from a Codex cloud task to your local repository. You must authenticate and have access to the task.705Apply the most recent diff from a Codex cloud task to your local repository. You must authenticate and have access to the task.

872| `--color` | `always | never | auto` | Control ANSI color in stdout. |907| `--color` | `always | never | auto` | Control ANSI color in stdout. |

873| `--dangerously-bypass-approvals-and-sandbox, --yolo` | `boolean` | Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner. |908| `--dangerously-bypass-approvals-and-sandbox, --yolo` | `boolean` | Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner. |

874| `--ephemeral` | `boolean` | Run without persisting session rollout files to disk. |909| `--ephemeral` | `boolean` | Run without persisting session rollout files to disk. |

875| `--full-auto` | `boolean` | Apply the low-friction automation preset (`workspace-write` sandbox and `on-request` approvals). |910| `--full-auto` | `boolean` | Deprecated compatibility flag. Prefer `--sandbox workspace-write`; Codex prints a warning when this flag is used. |

911| `--ignore-rules` | `boolean` | Do not load user or project execpolicy `.rules` files for this run. |

912| `--ignore-user-config` | `boolean` | Do not load `$CODEX_HOME/config.toml`. Authentication still uses `CODEX_HOME`. |

876| `--image, -i` | `path[,path...]` | Attach images to the first message. Repeatable; supports comma-separated lists. |913| `--image, -i` | `path[,path...]` | Attach images to the first message. Repeatable; supports comma-separated lists. |

877| `--json, --experimental-json` | `boolean` | Print newline-delimited JSON events instead of formatted text. |914| `--json, --experimental-json` | `boolean` | Print newline-delimited JSON events instead of formatted text. |

878| `--model, -m` | `string` | Override the configured model for this run. |915| `--model, -m` | `string` | Override the configured model for this run. |

944 981 

945Details982Details

946 983 

947Apply the low-friction automation preset (`workspace-write` sandbox and `on-request` approvals).984Deprecated compatibility flag. Prefer `--sandbox workspace-write`; Codex prints a warning when this flag is used.

985 

986Key

987 

988`--ignore-rules`

989 

990Type / Values

991 

992`boolean`

993 

994Details

995 

996Do not load user or project execpolicy `.rules` files for this run.

997 

998Key

999 

1000`--ignore-user-config`

1001 

1002Type / Values

1003 

1004`boolean`

1005 

1006Details

1007 

1008Do not load `$CODEX_HOME/config.toml`. Authentication still uses `CODEX_HOME`.

948 1009 

949Key1010Key

950 1011 

1543 1604 

1544| Key | Type / Values | Details |1605| Key | Type / Values | Details |

1545| --- | --- | --- |1606| --- | --- | --- |

1607| `--allow-unix-socket` | `path` | Allow the sandboxed command to bind or connect Unix sockets rooted at this path. Repeat to allow multiple paths. |

1608| `--cd, -C` | `DIR` | Working directory used for profile resolution and command execution. Requires `--permissions-profile`. |

1546| `--config, -c` | `key=value` | Pass configuration overrides into the sandboxed run (repeatable). |1609| `--config, -c` | `key=value` | Pass configuration overrides into the sandboxed run (repeatable). |

1547| `--full-auto` | `boolean` | Grant write access to the current workspace and `/tmp` without approvals. |1610| `--include-managed-config` | `boolean` | Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`. |

1611| `--log-denials` | `boolean` | Capture macOS sandbox denials with `log stream` while the command runs and print them after exit. |

1612| `--permissions-profile` | `NAME` | Apply a named permissions profile from the active configuration stack. |

1548| `COMMAND...` | `var-args` | Shell command to execute under macOS Seatbelt. Everything after `--` is forwarded. |1613| `COMMAND...` | `var-args` | Shell command to execute under macOS Seatbelt. Everything after `--` is forwarded. |

1549 1614 

1550Key1615Key

1551 1616 

1617`--allow-unix-socket`

1618 

1619Type / Values

1620 

1621`path`

1622 

1623Details

1624 

1625Allow the sandboxed command to bind or connect Unix sockets rooted at this path. Repeat to allow multiple paths.

1626 

1627Key

1628 

1629`--cd, -C`

1630 

1631Type / Values

1632 

1633`DIR`

1634 

1635Details

1636 

1637Working directory used for profile resolution and command execution. Requires `--permissions-profile`.

1638 

1639Key

1640 

1552`--config, -c`1641`--config, -c`

1553 1642 

1554Type / Values1643Type / Values

1561 1650 

1562Key1651Key

1563 1652 

1564`--full-auto`1653`--include-managed-config`

1654 

1655Type / Values

1656 

1657`boolean`

1658 

1659Details

1660 

1661Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.

1662 

1663Key

1664 

1665`--log-denials`

1565 1666 

1566Type / Values1667Type / Values

1567 1668 

1569 1670 

1570Details1671Details

1571 1672 

1572Grant write access to the current workspace and `/tmp` without approvals.1673Capture macOS sandbox denials with `log stream` while the command runs and print them after exit.

1674 

1675Key

1676 

1677`--permissions-profile`

1678 

1679Type / Values

1680 

1681`NAME`

1682 

1683Details

1684 

1685Apply a named permissions profile from the active configuration stack.

1573 1686 

1574Key1687Key

1575 1688 

1587 1700 

1588| Key | Type / Values | Details |1701| Key | Type / Values | Details |

1589| --- | --- | --- |1702| --- | --- | --- |

1703| `--cd, -C` | `DIR` | Working directory used for profile resolution and command execution. Requires `--permissions-profile`. |

1590| `--config, -c` | `key=value` | Configuration overrides applied before launching the sandbox (repeatable). |1704| `--config, -c` | `key=value` | Configuration overrides applied before launching the sandbox (repeatable). |

1591| `--full-auto` | `boolean` | Grant write access to the current workspace and `/tmp` inside the Landlock sandbox. |1705| `--include-managed-config` | `boolean` | Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`. |

1706| `--permissions-profile` | `NAME` | Apply a named permissions profile from the active configuration stack. |

1592| `COMMAND...` | `var-args` | Command to execute under Landlock + seccomp. Provide the executable after `--`. |1707| `COMMAND...` | `var-args` | Command to execute under Landlock + seccomp. Provide the executable after `--`. |

1593 1708 

1594Key1709Key

1595 1710 

1711`--cd, -C`

1712 

1713Type / Values

1714 

1715`DIR`

1716 

1717Details

1718 

1719Working directory used for profile resolution and command execution. Requires `--permissions-profile`.

1720 

1721Key

1722 

1596`--config, -c`1723`--config, -c`

1597 1724 

1598Type / Values1725Type / Values

1605 1732 

1606Key1733Key

1607 1734 

1608`--full-auto`1735`--include-managed-config`

1609 1736 

1610Type / Values1737Type / Values

1611 1738 

1613 1740 

1614Details1741Details

1615 1742 

1616Grant write access to the current workspace and `/tmp` inside the Landlock sandbox.1743Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.

1744 

1745Key

1746 

1747`--permissions-profile`

1748 

1749Type / Values

1750 

1751`NAME`

1752 

1753Details

1754 

1755Apply a named permissions profile from the active configuration stack.

1617 1756 

1618Key1757Key

1619 1758 

1627 1766 

1628Command to execute under Landlock + seccomp. Provide the executable after `--`.1767Command to execute under Landlock + seccomp. Provide the executable after `--`.

1629 1768 

1769#### Windows

1770 

1771| Key | Type / Values | Details |

1772| --- | --- | --- |

1773| `--cd, -C` | `DIR` | Working directory used for profile resolution and command execution. Requires `--permissions-profile`. |

1774| `--config, -c` | `key=value` | Configuration overrides applied before launching the sandbox (repeatable). |

1775| `--include-managed-config` | `boolean` | Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`. |

1776| `--permissions-profile` | `NAME` | Apply a named permissions profile from the active configuration stack. |

1777| `COMMAND...` | `var-args` | Command to execute under the native Windows sandbox. Provide the executable after `--`. |

1778 

1779Key

1780 

1781`--cd, -C`

1782 

1783Type / Values

1784 

1785`DIR`

1786 

1787Details

1788 

1789Working directory used for profile resolution and command execution. Requires `--permissions-profile`.

1790 

1791Key

1792 

1793`--config, -c`

1794 

1795Type / Values

1796 

1797`key=value`

1798 

1799Details

1800 

1801Configuration overrides applied before launching the sandbox (repeatable).

1802 

1803Key

1804 

1805`--include-managed-config`

1806 

1807Type / Values

1808 

1809`boolean`

1810 

1811Details

1812 

1813Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.

1814 

1815Key

1816 

1817`--permissions-profile`

1818 

1819Type / Values

1820 

1821`NAME`

1822 

1823Details

1824 

1825Apply a named permissions profile from the active configuration stack.

1826 

1827Key

1828 

1829`COMMAND...`

1830 

1831Type / Values

1832 

1833`var-args`

1834 

1835Details

1836 

1837Command to execute under the native Windows sandbox. Provide the executable after `--`.

1838 

1839### `codex update`

1840 

1841Check for and apply a Codex CLI update when the installed release supports self-update. Debug builds print a message telling you to install a release build instead.

1842 

1630## Flag combinations and safety tips1843## Flag combinations and safety tips

1631 1844 

1632- Set `--full-auto` for unattended local work, but avoid combining it with `--dangerously-bypass-approvals-and-sandbox` unless you are inside a dedicated sandbox VM.1845- Use `--sandbox workspace-write` for unattended local work that can stay inside the workspace, and avoid `--dangerously-bypass-approvals-and-sandbox` unless you are inside a dedicated sandbox VM.

1633- When you need to grant Codex write access to more directories, prefer `--add-dir` rather than forcing `--sandbox danger-full-access`.1846- When you need to grant Codex write access to more directories, prefer `--add-dir` rather than forcing `--sandbox danger-full-access`.

1634- Pair `--json` with `--output-last-message` in CI to capture machine-readable progress and a final natural-language summary.1847- Pair `--json` with `--output-last-message` in CI to capture machine-readable progress and a final natural-language summary.

1635 1848 

37| [`/feedback`](#send-feedback-with-feedback) | Send logs to the Codex maintainers. | Report issues or share diagnostics with support. |37| [`/feedback`](#send-feedback-with-feedback) | Send logs to the Codex maintainers. | Report issues or share diagnostics with support. |

38| [`/init`](#generate-agentsmd-with-init) | Generate an `AGENTS.md` scaffold in the current directory. | Capture persistent instructions for the repository or subdirectory you're working in. |38| [`/init`](#generate-agentsmd-with-init) | Generate an `AGENTS.md` scaffold in the current directory. | Capture persistent instructions for the repository or subdirectory you're working in. |

39| [`/logout`](#sign-out-with-logout) | Sign out of Codex. | Clear local credentials when using a shared machine. |39| [`/logout`](#sign-out-with-logout) | Sign out of Codex. | Clear local credentials when using a shared machine. |

40| [`/mcp`](#list-mcp-tools-with-mcp) | List configured Model Context Protocol (MCP) tools. | Check which external tools Codex can call during the session. |40| [`/mcp`](#list-mcp-tools-with-mcp) | List configured Model Context Protocol (MCP) tools. | Check which external tools Codex can call during the session; add `verbose` for server details. |

41| [`/mention`](#highlight-files-with-mention) | Attach a file to the conversation. | Point Codex at specific files or folders you want it to inspect next. |41| [`/mention`](#highlight-files-with-mention) | Attach a file to the conversation. | Point Codex at specific files or folders you want it to inspect next. |

42| [`/model`](#set-the-active-model-with-model) | Choose the active model (and reasoning effort, when available). | Switch between general-purpose models (`gpt-4.1-mini`) and deeper reasoning models before running a task. |42| [`/model`](#set-the-active-model-with-model) | Choose the active model (and reasoning effort, when available). | Switch between general-purpose models (`gpt-4.1-mini`) and deeper reasoning models before running a task. |

43| [`/fast`](#toggle-fast-mode-with-fast) | Toggle Fast mode for supported models. | Turn Fast mode on or off, or check whether the current thread is using it. |43| [`/fast`](#toggle-fast-mode-with-fast) | Toggle Fast mode for supported models. | Turn Fast mode on or off, or check whether the current thread is using it. |

46| [`/ps`](#check-background-terminals-with-ps) | Show experimental background terminals and their recent output. | Check long-running commands without leaving the main transcript. |46| [`/ps`](#check-background-terminals-with-ps) | Show experimental background terminals and their recent output. | Check long-running commands without leaving the main transcript. |

47| [`/stop`](#stop-background-terminals-with-stop) | Stop all background terminals. | Cancel background terminal work started by the current session. |47| [`/stop`](#stop-background-terminals-with-stop) | Stop all background terminals. | Cancel background terminal work started by the current session. |

48| [`/fork`](#fork-the-current-conversation-with-fork) | Fork the current conversation into a new thread. | Branch the active session to explore a new approach without losing the current transcript. |48| [`/fork`](#fork-the-current-conversation-with-fork) | Fork the current conversation into a new thread. | Branch the active session to explore a new approach without losing the current transcript. |

49| [`/side`](#start-a-side-conversation-with-side) | Start an ephemeral side conversation. | Ask a focused follow-up without disrupting the main thread's transcript. |

49| [`/resume`](#resume-a-saved-conversation-with-resume) | Resume a saved conversation from your session list. | Continue work from a previous CLI session without starting over. |50| [`/resume`](#resume-a-saved-conversation-with-resume) | Resume a saved conversation from your session list. | Continue work from a previous CLI session without starting over. |

50| [`/new`](#start-a-new-conversation-with-new) | Start a new conversation inside the same CLI session. | Reset the chat context without leaving the CLI when you want a fresh prompt in the same repo. |51| [`/new`](#start-a-new-conversation-with-new) | Start a new conversation inside the same CLI session. | Reset the chat context without leaving the CLI when you want a fresh prompt in the same repo. |

51| [`/quit`](#exit-the-cli-with-quit-or-exit) | Exit the CLI. | Leave the session immediately. |52| [`/quit`](#exit-the-cli-with-quit-or-exit) | Exit the CLI. | Leave the session immediately. |

54| [`/debug-config`](#inspect-config-layers-with-debug-config) | Print config layer and requirements diagnostics. | Debug precedence and policy requirements, including experimental network constraints. |55| [`/debug-config`](#inspect-config-layers-with-debug-config) | Print config layer and requirements diagnostics. | Debug precedence and policy requirements, including experimental network constraints. |

55| [`/statusline`](#configure-footer-items-with-statusline) | Configure TUI status-line fields interactively. | Pick and reorder footer items (model/context/limits/git/tokens/session) and persist in config.toml. |56| [`/statusline`](#configure-footer-items-with-statusline) | Configure TUI status-line fields interactively. | Pick and reorder footer items (model/context/limits/git/tokens/session) and persist in config.toml. |

56| [`/title`](#configure-terminal-title-items-with-title) | Configure terminal window or tab title fields interactively. | Pick and reorder title items such as project, status, thread, branch, model, and task progress. |57| [`/title`](#configure-terminal-title-items-with-title) | Configure terminal window or tab title fields interactively. | Pick and reorder title items such as project, status, thread, branch, model, and task progress. |

58| [`/keymap`](#remap-tui-shortcuts-with-keymap) | Remap TUI keyboard shortcuts. | Inspect and persist custom shortcut bindings in `config.toml`. |

57 59 

58`/quit` and `/exit` both exit the CLI. Use them only after you have saved or60`/quit` and `/exit` both exit the CLI. Use them only after you have saved or

59committed any important work.61committed any important work.

199Available title items include app name, project, spinner, status, thread, git201Available title items include app name, project, spinner, status, thread, git

200branch, model, and task progress.202branch, model, and task progress.

201 203 

204### Remap TUI shortcuts with `/keymap`

205 

206Use `/keymap` to inspect, update, and persist keyboard shortcut bindings for the TUI.

207 

2081. Type `/keymap`.

2092. Pick the shortcut context and action you want to change.

2103. Enter the new binding or remove the existing one.

211 

212Expected: Codex updates the active keymap and writes the custom binding to `tui.keymap` in `config.toml`.

213 

214Key bindings use names such as `ctrl-a`, `shift-enter`, and `page-down`. Context-specific bindings override `tui.keymap.global`; an empty binding list unbinds the action.

215 

202### Check background terminals with `/ps`216### Check background terminals with `/ps`

203 217 

2041. Type `/ps`.2181. Type `/ps`.

268If you need to fork a saved session instead of the current one, run282If you need to fork a saved session instead of the current one, run

269`codex fork` in your terminal to open the session picker.283`codex fork` in your terminal to open the session picker.

270 284 

285### Start a side conversation with `/side`

286 

287Use `/side` to start an ephemeral fork from the current conversation without switching away from the main task.

288 

2891. Type `/side` to open a side conversation.

2902. Optionally add inline text, for example `/side Check whether this plan has an obvious risk`.

2913. Return to the parent thread after the focused detour finishes.

292 

293Expected: Codex opens a side conversation whose transcript is separate from the parent thread. While you are in side mode, the TUI continues to show parent-thread status so you can see whether the main task is still running.

294 

295`/side` is unavailable inside another side conversation and during review mode.

296 

271### Generate `AGENTS.md` with `/init`297### Generate `AGENTS.md` with `/init`

272 298 

2731. Run `/init` in the directory where you want Codex to look for persistent instructions.2991. Run `/init` in the directory where you want Codex to look for persistent instructions.

292 318 

293Expected: You see the configured Model Context Protocol (MCP) tools Codex can call in this session.319Expected: You see the configured Model Context Protocol (MCP) tools Codex can call in this session.

294 320 

321Use `/mcp verbose` to include detailed server diagnostics. If you pass anything other than `verbose`, Codex shows the command usage.

322 

295### Browse apps with `/apps`323### Browse apps with `/apps`

296 324 

2971. Type `/apps`.3251. Type `/apps`.

145- `never`: Codex doesn't stop for approval prompts.145- `never`: Codex doesn't stop for approval prompts.

146 146 

147Full access means using `sandbox_mode = "danger-full-access"` together with147Full access means using `sandbox_mode = "danger-full-access"` together with

148`approval_policy = "never"`. By contrast, `--full-auto` is the lower-risk local148`approval_policy = "never"`. By contrast, the lower-risk local automation

149automation preset: `sandbox_mode = "workspace-write"` and149preset is `sandbox_mode = "workspace-write"` together with

150`approval_policy = "on-request"`.150`approval_policy = "on-request"`, or the matching CLI flags

151`--sandbox workspace-write --ask-for-approval on-request`.

151 152 

152If you need Codex to work across more than one directory, writable roots let153If you need Codex to work across more than one directory, writable roots let

153you extend the places it can modify without removing the sandbox entirely. If154you extend the places it can modify without removing the sandbox entirely. If

90 90 

91## Hooks (experimental)91## Hooks (experimental)

92 92 

93Codex can also load lifecycle hooks from `hooks.json` files that sit next to93Codex can also load lifecycle hooks from either `hooks.json` files or inline

94active config layers.94`[hooks]` tables in `config.toml` files that sit next to active config layers.

95 95 

96In practice, the two most useful locations are:96In practice, the two most useful locations are:

97 97 

98- `~/.codex/hooks.json`98- `~/.codex/hooks.json`

99- `~/.codex/config.toml`

99- `<repo>/.codex/hooks.json`100- `<repo>/.codex/hooks.json`

101- `<repo>/.codex/config.toml`

100 102 

101Project-local hooks load only when the project `.codex/` layer is trusted.103Project-local hooks load only when the project `.codex/` layer is trusted.

102User-level hooks remain independent of project trust.104User-level hooks remain independent of project trust.

108codex_hooks = true110codex_hooks = true

109```111```

110 112 

113Inline TOML hooks use the same event structure as `hooks.json`:

114 

115```toml

116[[hooks.PreToolUse]]

117matcher = "^Bash$"

118 

119[[hooks.PreToolUse.hooks]]

120type = "command"

121command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'

122timeout = 30

123statusMessage = "Checking Bash command"

124```

125 

126If a single layer contains both `hooks.json` and inline `[hooks]`, Codex loads

127both and warns. Prefer one representation per layer.

128 

111For the current event list, input fields, output behavior, and limitations, see129For the current event list, input fields, output behavior, and limitations, see

112[Hooks](https://developers.openai.com/codex/hooks).130[Hooks](https://developers.openai.com/codex/hooks).

113 131 

178 196 

179The auth command receives no `stdin` and must print the token to stdout. Codex trims surrounding whitespace, treats an empty token as an error, and refreshes proactively at `refresh_interval_ms`; set `refresh_interval_ms = 0` to refresh only after an authentication retry. Don't combine `[model_providers.<id>.auth]` with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.197The auth command receives no `stdin` and must print the token to stdout. Codex trims surrounding whitespace, treats an empty token as an error, and refreshes proactively at `refresh_interval_ms`; set `refresh_interval_ms = 0` to refresh only after an authentication retry. Don't combine `[model_providers.<id>.auth]` with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.

180 198 

199### Amazon Bedrock provider

200 

201Codex includes a built-in `amazon-bedrock` model provider. Set it directly as

202`model_provider`; unlike custom providers, this built-in provider supports only

203the nested AWS profile and region overrides.

204 

205```toml

206model_provider = "amazon-bedrock"

207model = "<bedrock-model-id>"

208 

209[model_providers.amazon-bedrock.aws]

210profile = "default"

211region = "eu-central-1"

212```

213 

214If you omit `profile`, Codex uses the standard AWS credential chain. Set

215`region` to the supported Bedrock region that should handle requests.

216 

181## OSS mode (local providers)217## OSS mode (local providers)

182 218 

183Codex can run against a local "open source" provider (for example, Ollama or LM Studio) when you pass `--oss`. If you pass `--oss` without specifying a provider, Codex uses `oss_provider` as the default.219Codex can run against a local "open source" provider (for example, Ollama or LM Studio) when you pass `--oss`. If you pass `--oss` without specifying a provider, Codex uses `oss_provider` as the default.

267"""303"""

268```304```

269 305 

306### Named permission profiles

307 

308Set `default_permissions` to reuse a sandbox profile by name. Codex includes

309the built-in profiles `:read-only`, `:workspace`, and `:danger-no-sandbox`:

310 

311```toml

312default_permissions = ":workspace"

313```

314 

315For custom profiles, point `default_permissions` at a name you define under

316`[permissions.<name>]`:

317 

318```toml

319default_permissions = "workspace"

320 

321[permissions.workspace.filesystem]

322":project_roots" = { "." = "write", "**/*.env" = "none" }

323glob_scan_max_depth = 3

324 

325[permissions.workspace.network]

326enabled = true

327mode = "limited"

328 

329[permissions.workspace.network.domains]

330"api.openai.com" = "allow"

331```

332 

333Use built-in names with a leading colon. Custom names don't use a leading

334colon and must have matching `permissions` tables.

335 

270Need the complete key list (including profile-scoped overrides and requirements constraints)? See [Configuration Reference](https://developers.openai.com/codex/config-reference) and [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration).336Need the complete key list (including profile-scoped overrides and requirements constraints)? See [Configuration Reference](https://developers.openai.com/codex/config-reference) and [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration).

271 337 

272In workspace-write mode, some environments keep `.git/` and `.codex/`338In workspace-write mode, some environments keep `.git/` and `.codex/`

69 69 

70For mode-by-mode behavior (including protected `.git`/`.codex` paths and network defaults), see [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).70For mode-by-mode behavior (including protected `.git`/`.codex` paths and network defaults), see [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).

71 71 

72#### Permission profiles

73 

74Use a named permission profile when you want one reusable filesystem or network policy across sessions:

75 

76```toml

77default_permissions = ":workspace"

78```

79 

80Built-in profiles include `:read-only`, `:workspace`, and `:danger-no-sandbox`. For custom filesystem or network rules, define `[permissions.<name>]` tables and set `default_permissions` to that name.

81 

72#### Windows sandbox mode82#### Windows sandbox mode

73 83 

74When running Codex natively on Windows, set the native sandbox mode to `elevated` in the `windows` table. Use `unelevated` only if you don't have administrator permissions or if elevated setup fails.84When running Codex natively on Windows, set the native sandbox mode to `elevated` in the `windows` table. Use `unelevated` only if you don't have administrator permissions or if elevated setup fails.

111 121 

112You can override this later in an active session with `/personality` or per thread/turn when using the app-server APIs.122You can override this later in an active session with `/personality` or per thread/turn when using the app-server APIs.

113 123 

124#### TUI keymap

125 

126Customize terminal shortcuts under `tui.keymap`. Context-specific bindings override `tui.keymap.global`, and an empty list unbinds the action.

127 

128```toml

129[tui.keymap.global]

130open_transcript = "ctrl-t"

131 

132[tui.keymap.composer]

133submit = ["enter", "ctrl-m"]

134```

135 

114#### Command environment136#### Command environment

115 137 

116Control which environment variables Codex forwards to spawned commands.138Control which environment variables Codex forwards to spawned commands.

148| Key | Default | Maturity | Description |170| Key | Default | Maturity | Description |

149| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |171| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |

150| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |172| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |

151| `codex_hooks` | false | Under development | Enable lifecycle hooks from `hooks.json`. See [Hooks](https://developers.openai.com/codex/hooks). |173| `codex_hooks` | true | Stable | Enable lifecycle hooks from `hooks.json` or inline `[hooks]`. See [Hooks](https://developers.openai.com/codex/hooks). |

152| `fast_mode` | true | Stable | Enable Fast mode selection and the `service_tier = "fast"` path |174| `fast_mode` | true | Stable | Enable Fast mode selection and the `service_tier = "fast"` path |

153| `memories` | false | Stable | Enable [Memories](https://developers.openai.com/codex/memories) |175| `memories` | false | Stable | Enable [Memories](https://developers.openai.com/codex/memories) |

154| `multi_agent` | true | Stable | Enable subagent collaboration tools |176| `multi_agent` | true | Stable | Enable subagent collaboration tools |

42| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |42| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |

43| `commit_attribution` | `string` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. |43| `commit_attribution` | `string` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. |

44| `compact_prompt` | `string` | Inline override for the history compaction prompt. |44| `compact_prompt` | `string` | Inline override for the history compaction prompt. |

45| `default_permissions` | `string` | Name of the default permissions profile to apply to sandboxed tool calls. |45| `default_permissions` | `string` | Name of the default permissions profile to apply to sandboxed tool calls. Built-ins are `:read-only`, `:workspace`, and `:danger-no-sandbox`; custom profile names require matching `[permissions.<name>]` tables. |

46| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |46| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |

47| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |47| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |

48| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |48| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |

49| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |49| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |

50| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |50| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |

51| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` (under development; off by default). |51| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config. |

52| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |52| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |

53| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |53| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |

54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |

70| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |70| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |

71| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |71| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |

72| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |72| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |

73| `hooks` | `table` | Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events. |

73| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |74| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |

74| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |75| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |

75| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |76| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |

102| `memories.max_rollout_age_days` | `number` | Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`. |103| `memories.max_rollout_age_days` | `number` | Maximum age of threads considered for memory generation. Defaults to `30` and is clamped to `0`-`90`. |

103| `memories.max_rollouts_per_startup` | `number` | Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`. |104| `memories.max_rollouts_per_startup` | `number` | Maximum rollout candidates processed per startup pass. Defaults to `16` and is capped at `128`. |

104| `memories.max_unused_days` | `number` | Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`. |105| `memories.max_unused_days` | `number` | Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`. |

106| `memories.min_rate_limit_remaining_percent` | `number` | Minimum remaining percentage required in Codex rate-limit windows before memory generation starts. Defaults to `25` and is clamped to `0`-`100`. |

105| `memories.min_rollout_idle_hours` | `number` | Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`. |107| `memories.min_rollout_idle_hours` | `number` | Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`. |

106| `memories.use_memories` | `boolean` | When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`. |108| `memories.use_memories` | `boolean` | When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`. |

107| `model` | `string` | Model to use (e.g., `gpt-5.5`). |109| `model` | `string` | Model to use (e.g., `gpt-5.5`). |

131| `model_providers.<id>.stream_max_retries` | `number` | Retry count for SSE streaming interruptions (default: 5). |133| `model_providers.<id>.stream_max_retries` | `number` | Retry count for SSE streaming interruptions (default: 5). |

132| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |134| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |

133| `model_providers.<id>.wire_api` | `responses` | Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted. |135| `model_providers.<id>.wire_api` | `responses` | Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted. |

136| `model_providers.amazon-bedrock.aws.profile` | `string` | AWS profile name used by the built-in `amazon-bedrock` provider. |

137| `model_providers.amazon-bedrock.aws.region` | `string` | AWS region used by the built-in `amazon-bedrock` provider. |

134| `model_reasoning_effort` | `minimal | low | medium | high | xhigh` | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |138| `model_reasoning_effort` | `minimal | low | medium | high | xhigh` | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |

135| `model_reasoning_summary` | `auto | concise | detailed | none` | Select reasoning summary detail or disable summaries entirely. |139| `model_reasoning_summary` | `auto | concise | detailed | none` | Select reasoning summary detail or disable summaries entirely. |

136| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |140| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |

216| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |220| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |

217| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |221| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |

218| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |222| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |

223| `tool_suggest.disabled_tools` | `array<table>` | Disable suggestions for specific discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |

219| `tool_suggest.discoverables` | `array<table>` | Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |224| `tool_suggest.discoverables` | `array<table>` | Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`. |

220| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |225| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |

221| `tools.web_search` | `boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }` | Optional web search tool configuration. The legacy boolean form is still accepted, but the object form lets you set search context size, allowed domains, and approximate user location. |226| `tools.web_search` | `boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }` | Optional web search tool configuration. The legacy boolean form is still accepted, but the object form lets you set search context size, allowed domains, and approximate user location. |

222| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |227| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

223| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |228| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |

224| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |229| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |

230| `tui.keymap.<context>.<action>` | `string | array<string>` | Keyboard shortcut binding for a TUI action. Supported contexts include `global`, `chat`, `composer`, `editor`, `pager`, `list`, and `approval`; context-specific bindings override `tui.keymap.global`. |

231| `tui.keymap.<context>.<action> = []` | `empty array` | Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, or `page-down`. |

225| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |232| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |

226| `tui.notification_condition` | `unfocused | always` | Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`. |233| `tui.notification_condition` | `unfocused | always` | Control whether TUI notifications fire only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`. |

227| `tui.notification_method` | `auto | osc9 | bel` | Notification method for terminal notifications (default: auto). |234| `tui.notification_method` | `auto | osc9 | bel` | Notification method for terminal notifications (default: auto). |

629 636 

630Details637Details

631 638 

632Name of the default permissions profile to apply to sandboxed tool calls.639Name of the default permissions profile to apply to sandboxed tool calls. Built-ins are `:read-only`, `:workspace`, and `:danger-no-sandbox`; custom profile names require matching `[permissions.<name>]` tables.

633 640 

634Key641Key

635 642 

701 708 

702Details709Details

703 710 

704Enable lifecycle hooks loaded from `hooks.json` (under development; off by default).711Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config.

705 712 

706Key713Key

707 714 

957 964 

958Key965Key

959 966 

967`hooks`

968 

969Type / Values

970 

971`table`

972 

973Details

974 

975Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events.

976 

977Key

978 

960`instructions`979`instructions`

961 980 

962Type / Values981Type / Values

1341 1360 

1342Key1361Key

1343 1362 

1363`memories.min_rate_limit_remaining_percent`

1364 

1365Type / Values

1366 

1367`number`

1368 

1369Details

1370 

1371Minimum remaining percentage required in Codex rate-limit windows before memory generation starts. Defaults to `25` and is clamped to `0`-`100`.

1372 

1373Key

1374 

1344`memories.min_rollout_idle_hours`1375`memories.min_rollout_idle_hours`

1345 1376 

1346Type / Values1377Type / Values

1689 1720 

1690Key1721Key

1691 1722 

1723`model_providers.amazon-bedrock.aws.profile`

1724 

1725Type / Values

1726 

1727`string`

1728 

1729Details

1730 

1731AWS profile name used by the built-in `amazon-bedrock` provider.

1732 

1733Key

1734 

1735`model_providers.amazon-bedrock.aws.region`

1736 

1737Type / Values

1738 

1739`string`

1740 

1741Details

1742 

1743AWS region used by the built-in `amazon-bedrock` provider.

1744 

1745Key

1746 

1692`model_reasoning_effort`1747`model_reasoning_effort`

1693 1748 

1694Type / Values1749Type / Values

2709 2764 

2710Key2765Key

2711 2766 

2767`tool_suggest.disabled_tools`

2768 

2769Type / Values

2770 

2771`array<table>`

2772 

2773Details

2774 

2775Disable suggestions for specific discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.

2776 

2777Key

2778 

2712`tool_suggest.discoverables`2779`tool_suggest.discoverables`

2713 2780 

2714Type / Values2781Type / Values

2781 2848 

2782Key2849Key

2783 2850 

2851`tui.keymap.<context>.<action>`

2852 

2853Type / Values

2854 

2855`string | array<string>`

2856 

2857Details

2858 

2859Keyboard shortcut binding for a TUI action. Supported contexts include `global`, `chat`, `composer`, `editor`, `pager`, `list`, and `approval`; context-specific bindings override `tui.keymap.global`.

2860 

2861Key

2862 

2863`tui.keymap.<context>.<action> = []`

2864 

2865Type / Values

2866 

2867`empty array`

2868 

2869Details

2870 

2871Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, or `page-down`.

2872 

2873Key

2874 

2784`tui.model_availability_nux.<model>`2875`tui.model_availability_nux.<model>`

2785 2876 

2786Type / Values2877Type / Values

2953| `allowed_web_search_modes` | `array<string>` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |3044| `allowed_web_search_modes` | `array<string>` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |

2954| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |3045| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |

2955| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. |3046| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. |

3047| `features.browser_use` | `boolean` | Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability. |

3048| `features.computer_use` | `boolean` | Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows. |

3049| `features.in_app_browser` | `boolean` | Set to `false` in `requirements.toml` to disable the in-app browser pane. |

2956| `guardian_policy_config` | `string` | Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored. |3050| `guardian_policy_config` | `string` | Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored. |

3051| `hooks` | `table` | Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`. |

3052| `hooks.<Event>` | `array<table>` | Matcher groups for a hook event such as `PreToolUse`, `PostToolUse`, `PermissionRequest`, `SessionStart`, `UserPromptSubmit`, or `Stop`. |

3053| `hooks.<Event>[].hooks` | `array<table>` | Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped. |

3054| `hooks.managed_dir` | `string (absolute path)` | Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks. |

3055| `hooks.windows_managed_dir` | `string (absolute path)` | Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks. |

2957| `mcp_servers` | `table` | Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled. |3056| `mcp_servers` | `table` | Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled. |

2958| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |3057| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |

2959| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |3058| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |

2960| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. |3059| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. |

2961| `permissions.filesystem.deny_read` | `array<string>` | Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config. |3060| `permissions.filesystem.deny_read` | `array<string>` | Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config. |

3061| `remote_sandbox_config` | `array<table>` | Host-specific sandbox requirements. The first entry whose `hostname_patterns` match the resolved host name overrides top-level `allowed_sandbox_modes` for that requirements source. Host-specific entries currently override sandbox modes only. |

3062| `remote_sandbox_config[].allowed_sandbox_modes` | `array<string>` | Allowed sandbox modes to apply when this host-specific entry matches. |

3063| `remote_sandbox_config[].hostname_patterns` | `array<string>` | Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character. |

2962| `rules` | `table` | Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. |3064| `rules` | `table` | Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. |

2963| `rules.prefix_rules` | `array<table>` | List of enforced prefix rules. Each rule must include `pattern` and `decision`. |3065| `rules.prefix_rules` | `array<table>` | List of enforced prefix rules. Each rule must include `pattern` and `decision`. |

2964| `rules.prefix_rules[].decision` | `prompt | forbidden` | Required. Requirements rules can only prompt or forbid (not allow). |3066| `rules.prefix_rules[].decision` | `prompt | forbidden` | Required. Requirements rules can only prompt or forbid (not allow). |

3041 3143 

3042Key3144Key

3043 3145 

3146`features.browser_use`

3147 

3148Type / Values

3149 

3150`boolean`

3151 

3152Details

3153 

3154Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability.

3155 

3156Key

3157 

3158`features.computer_use`

3159 

3160Type / Values

3161 

3162`boolean`

3163 

3164Details

3165 

3166Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows.

3167 

3168Key

3169 

3170`features.in_app_browser`

3171 

3172Type / Values

3173 

3174`boolean`

3175 

3176Details

3177 

3178Set to `false` in `requirements.toml` to disable the in-app browser pane.

3179 

3180Key

3181 

3044`guardian_policy_config`3182`guardian_policy_config`

3045 3183 

3046Type / Values3184Type / Values

3053 3191 

3054Key3192Key

3055 3193 

3194`hooks`

3195 

3196Type / Values

3197 

3198`table`

3199 

3200Details

3201 

3202Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`.

3203 

3204Key

3205 

3206`hooks.<Event>`

3207 

3208Type / Values

3209 

3210`array<table>`

3211 

3212Details

3213 

3214Matcher groups for a hook event such as `PreToolUse`, `PostToolUse`, `PermissionRequest`, `SessionStart`, `UserPromptSubmit`, or `Stop`.

3215 

3216Key

3217 

3218`hooks.<Event>[].hooks`

3219 

3220Type / Values

3221 

3222`array<table>`

3223 

3224Details

3225 

3226Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped.

3227 

3228Key

3229 

3230`hooks.managed_dir`

3231 

3232Type / Values

3233 

3234`string (absolute path)`

3235 

3236Details

3237 

3238Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks.

3239 

3240Key

3241 

3242`hooks.windows_managed_dir`

3243 

3244Type / Values

3245 

3246`string (absolute path)`

3247 

3248Details

3249 

3250Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks.

3251 

3252Key

3253 

3056`mcp_servers`3254`mcp_servers`

3057 3255 

3058Type / Values3256Type / Values

3113 3311 

3114Key3312Key

3115 3313 

3314`remote_sandbox_config`

3315 

3316Type / Values

3317 

3318`array<table>`

3319 

3320Details

3321 

3322Host-specific sandbox requirements. The first entry whose `hostname_patterns` match the resolved host name overrides top-level `allowed_sandbox_modes` for that requirements source. Host-specific entries currently override sandbox modes only.

3323 

3324Key

3325 

3326`remote_sandbox_config[].allowed_sandbox_modes`

3327 

3328Type / Values

3329 

3330`array<string>`

3331 

3332Details

3333 

3334Allowed sandbox modes to apply when this host-specific entry matches.

3335 

3336Key

3337 

3338`remote_sandbox_config[].hostname_patterns`

3339 

3340Type / Values

3341 

3342`array<string>`

3343 

3344Details

3345 

3346Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character.

3347 

3348Key

3349 

3116`rules`3350`rules`

3117 3351 

3118Type / Values3352Type / Values

130# - workspace-write130# - workspace-write

131# - danger-full-access (no sandbox; extremely risky)131# - danger-full-access (no sandbox; extremely risky)

132sandbox_mode = "read-only"132sandbox_mode = "read-only"

133# Named permissions profile to apply by default. Required before using [permissions.<name>].133# Named permissions profile to apply by default. Built-ins:

134# default_permissions = "workspace"134# :read-only | :workspace | :danger-no-sandbox

135# Use a custom name such as "workspace" only when you also define [permissions.workspace].

136# default_permissions = ":workspace"

135 137 

136# Example filesystem profile. Use `"none"` to deny reads for exact paths or138# Example filesystem profile. Use `"none"` to deny reads for exact paths or

137# glob patterns. On platforms that need pre-expanded glob matches, set139# glob patterns. On platforms that need pre-expanded glob matches, set

358# You can also add custom .tmTheme files under $CODEX_HOME/themes.360# You can also add custom .tmTheme files under $CODEX_HOME/themes.

359# theme = "catppuccin-mocha"361# theme = "catppuccin-mocha"

360 362 

363# Custom key bindings. Context-specific bindings override [tui.keymap.global].

364# Use [] to unbind an action.

365# [tui.keymap.global]

366# open_transcript = "ctrl-t"

367# open_external_editor = []

368#

369# [tui.keymap.composer]

370# submit = ["enter", "ctrl-m"]

371 

361# Internal tooltip state keyed by model slug. Usually managed by Codex.372# Internal tooltip state keyed by model slug. Usually managed by Codex.

362# [tui.model_availability_nux]373# [tui.model_availability_nux]

363# "gpt-5.4" = 1374# "gpt-5.4" = 1

407# use_memories = true418# use_memories = true

408# disable_on_external_context = false # legacy alias: no_memories_if_mcp_or_web_search419# disable_on_external_context = false # legacy alias: no_memories_if_mcp_or_web_search

409 420 

421################################################################################

422# Lifecycle hooks can be configured here inline or in a sibling hooks.json.

423################################################################################

424 

425# [hooks]

426# [[hooks.PreToolUse]]

427# matcher = "^Bash$"

428#

429# [[hooks.PreToolUse.hooks]]

430# type = "command"

431# command = 'python3 "/absolute/path/to/pre_tool_use_policy.py"'

432# timeout = 30

433# statusMessage = "Checking Bash command"

434 

410################################################################################435################################################################################

411# Define MCP servers under this table. Leave empty to disable.436# Define MCP servers under this table. Leave empty to disable.

412################################################################################437################################################################################

454# - openai479# - openai

455# - ollama480# - ollama

456# - lmstudio481# - lmstudio

482# - amazon-bedrock

457# These IDs are reserved. Use a different ID for custom providers.483# These IDs are reserved. Use a different ID for custom providers.

458 484 

459[model_providers]485[model_providers]

460 486 

487# --- Example: built-in Amazon Bedrock provider options ---

488# model_provider = "amazon-bedrock"

489# model = "<bedrock-model-id>"

490# [model_providers.amazon-bedrock.aws]

491# profile = "default"

492# region = "eu-central-1"

493 

461# --- Example: OpenAI data residency with explicit base URL or headers ---494# --- Example: OpenAI data residency with explicit base URL or headers ---

462# [model_providers.openaidr]495# [model_providers.openaidr]

463# name = "OpenAI Data Residency"496# name = "OpenAI Data Residency"

528# { type = "connector", id = "gmail" },561# { type = "connector", id = "gmail" },

529# { type = "plugin", id = "figma@openai-curated" },562# { type = "plugin", id = "figma@openai-curated" },

530# ]563# ]

564# disabled_tools = [

565# { type = "plugin", id = "slack@openai-curated" },

566# { type = "connector", id = "connector_googlecalendar" },

567# ]

531 568 

532################################################################################569################################################################################

533# Profiles (named presets)570# Profiles (named presets)

139 139 

140Codex Admins can deploy admin-enforced `requirements.toml` policies from the Codex [Policies page](https://chatgpt.com/codex/settings/policies).140Codex Admins can deploy admin-enforced `requirements.toml` policies from the Codex [Policies page](https://chatgpt.com/codex/settings/policies).

141 141 

142Use this page when you want to apply different local Codex constraints to different groups without distributing device-level files first. The managed policy uses the same `requirements.toml` format described in [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration), so you can define allowed approval policies, sandbox modes, web search behavior, MCP server allowlists, feature pins, and restrictive command rules.142Use this page when you want to apply different local Codex constraints to different groups without distributing device-level files first. The managed policy uses the same `requirements.toml` format described in [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration), so you can define allowed approval policies, sandbox modes, web search behavior, MCP server allowlists, feature pins, and restrictive command rules. To disable Browser Use, the in-app browser, or Computer Use, see [Pin feature flags](https://developers.openai.com/codex/enterprise/managed-configuration#pin-feature-flags).

143 143 

144![Codex policies and configurations page](/images/codex/enterprise/policies_and_configurations_page.png)144![Codex policies and configurations page](/images/codex/enterprise/policies_and_configurations_page.png)

145 145 

166allowed_approval_policies = ["on-request"]166allowed_approval_policies = ["on-request"]

167```167```

168 168 

169Example: disable Browser Use, the in-app browser, and Computer Use:

170 

171```toml

172[features]

173browser_use = false

174in_app_browser = false

175computer_use = false

176```

177 

169Example: add a restrictive command rule when you want admins to block or gate specific commands:178Example: add a restrictive command rule when you want admins to block or gate specific commands:

170 179 

171```toml180```toml

7 7 

8## Admin-enforced requirements (requirements.toml)8## Admin-enforced requirements (requirements.toml)

9 9 

10Requirements constrain security-sensitive settings (approval policy, approvals reviewer, automatic review policy, sandbox mode, web search mode, and optionally which MCP servers users can enable). When resolving configuration (for example from `config.toml`, profiles, or CLI config overrides), if a value conflicts with an enforced rule, Codex falls back to a compatible value and notifies the user. If you configure an `mcp_servers` allowlist, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex disables it.10Requirements constrain security-sensitive settings (approval policy, approvals reviewer, automatic review policy, sandbox mode, web search mode, managed hooks, and optionally which MCP servers users can enable). When resolving configuration (for example from `config.toml`, profiles, or CLI config overrides), if a value conflicts with an enforced rule, Codex falls back to a compatible value and notifies the user. If you configure an `mcp_servers` allowlist, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex disables it.

11 11 

12Requirements can also constrain [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) via the `[features]` table in `requirements.toml`. Note that features aren't always security-sensitive, but enterprises can pin values if desired. Omitted keys remain unconstrained.12Requirements can also constrain [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) via the `[features]` table in `requirements.toml`. Note that features aren't always security-sensitive, but enterprises can pin values if desired. Omitted keys remain unconstrained.

13 13 

72allowed_sandbox_modes = ["read-only", "workspace-write"]72allowed_sandbox_modes = ["read-only", "workspace-write"]

73```73```

74 74 

75### Override sandbox requirements by host

76 

77Use `[[remote_sandbox_config]]` when one managed policy should apply different

78sandbox requirements on different hosts. For example, you can keep a stricter

79default for laptops while allowing workspace writes on matching devboxes or CI

80runners. Host-specific entries currently override `allowed_sandbox_modes` only:

81 

82```toml

83allowed_sandbox_modes = ["read-only"]

84 

85[[remote_sandbox_config]]

86hostname_patterns = ["*.devbox.example.com", "runner-??.ci.example.com"]

87allowed_sandbox_modes = ["read-only", "workspace-write"]

88```

89 

90Codex compares each `hostname_patterns` entry against the best-effort resolved

91host name. It prefers the fully qualified domain name when available and falls

92back to the local host name. Matching is case-insensitive; `*` matches any

93sequence of characters, and `?` matches one character.

94 

95The first matching `[[remote_sandbox_config]]` entry wins within the same

96requirements source. If no entry matches, Codex keeps the top-level

97`allowed_sandbox_modes`. Hostname matching is for policy selection only; don't

98treat it as authenticated device proof.

99 

75You can also constrain web search mode:100You can also constrain web search mode:

76 101 

77```toml102```toml

81`allowed_web_search_modes = []` allows only `"disabled"`.106`allowed_web_search_modes = []` allows only `"disabled"`.

82For example, `allowed_web_search_modes = ["cached"]` prevents live web search even in `danger-full-access` sessions.107For example, `allowed_web_search_modes = ["cached"]` prevents live web search even in `danger-full-access` sessions.

83 108 

84You can also pin [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags):109### Pin feature flags

85 110 

86```111You can also pin [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) for users

112receiving a managed `requirements.toml`:

113 

114```toml

87[features]115[features]

88personality = true116personality = true

89unified_exec = false117unified_exec = false

118 

119# Disable specific Codex feature surfaces when needed.

120browser_use = false

121in_app_browser = false

122computer_use = false

90```123```

91 124 

92Use the canonical feature keys from `config.toml`'s `[features]` table. Codex normalizes the resulting feature set to meet these pins and rejects conflicting writes to `config.toml` or profile-scoped feature settings.125Use the canonical feature keys from `config.toml`'s `[features]` table. Codex normalizes the resulting feature set to meet these pins and rejects conflicting writes to `config.toml` or profile-scoped feature settings.

93 126 

127- `in_app_browser = false` disables the in-app browser pane.

128- `browser_use = false` disables Browser Use and Browser Agent availability.

129- `computer_use = false` disables Computer Use availability and related

130 install or enablement flows.

131 

132If omitted, these features are allowed by policy, subject to normal client,

133platform, and rollout availability.

134 

94### Configure automatic review policy135### Configure automatic review policy

95 136 

96Use `allowed_approvals_reviewers` to require or allow automatic review. Set it137Use `allowed_approvals_reviewers` to require or allow automatic review. Set it

137Windows, managed `deny_read` applies to direct file tools; shell subprocess178Windows, managed `deny_read` applies to direct file tools; shell subprocess

138reads don't use this sandbox rule.179reads don't use this sandbox rule.

139 180 

181### Enforce managed hooks from requirements

182 

183Admins can also define managed lifecycle hooks directly in `requirements.toml`.

184Use `[hooks]` for the hook configuration itself, and point `managed_dir` at the

185directory where your MDM or endpoint-management tooling installs the referenced

186scripts.

187 

188```toml

189[features]

190codex_hooks = true

191 

192[hooks]

193managed_dir = "/enterprise/hooks"

194windows_managed_dir = 'C:\enterprise\hooks'

195 

196[[hooks.PreToolUse]]

197matcher = "^Bash$"

198 

199[[hooks.PreToolUse.hooks]]

200type = "command"

201command = "python3 /enterprise/hooks/pre_tool_use_policy.py"

202timeout = 30

203statusMessage = "Checking managed Bash command"

204```

205 

206Notes:

207 

208- Codex enforces the hook configuration from `requirements.toml`, but it does

209 not distribute the scripts in `managed_dir`.

210- Deliver those scripts separately with your MDM or device-management solution.

211- Managed hook commands should reference absolute script paths under the

212 configured managed directory.

213 

140### Enforce command rules from requirements214### Enforce command rules from requirements

141 215 

142Admins can also enforce restrictive command rules from `requirements.toml`216Admins can also enforce restrictive command rules from `requirements.toml`

84Fine-tune how Codex runs by setting the action inputs that map to `codex exec` options:84Fine-tune how Codex runs by setting the action inputs that map to `codex exec` options:

85 85 

86- `prompt` or `prompt-file` (choose one): Inline instructions or a repository path to Markdown or text with your task. Consider storing prompts in `.github/codex/prompts/`.86- `prompt` or `prompt-file` (choose one): Inline instructions or a repository path to Markdown or text with your task. Consider storing prompts in `.github/codex/prompts/`.

87- `codex-args`: Extra CLI flags. Provide a JSON array (for example `["--full-auto"]`) or a shell string (`--full-auto --sandbox danger-full-access`) to allow edits, streaming, or MCP configuration.87- `codex-args`: Extra CLI flags. Provide a JSON array (for example `["--json"]`) or a shell string (`--sandbox workspace-write --json`) to allow edits, streaming, or MCP configuration.

88- `model` and `effort`: Pick the Codex agent configuration you want; leave empty for defaults.88- `model` and `effort`: Pick the Codex agent configuration you want; leave empty for defaults.

89- `sandbox`: Match the sandbox mode (`workspace-write`, `read-only`, `danger-full-access`) to the permissions Codex needs during the run.89- `sandbox`: Match the sandbox mode (`workspace-write`, `read-only`, `danger-full-access`) to the permissions Codex needs during the run.

90- `output-file`: Save the final Codex message to disk so later steps can upload or diff it.90- `output-file`: Save the final Codex message to disk so later steps can upload or diff it.

1# Hooks1# Hooks

2 2 

3Experimental. Hooks are under active development. Windows support temporarily

4disabled.

5 

6Hooks are an extensibility framework for Codex. They allow3Hooks are an extensibility framework for Codex. They allow

7you to inject your own scripts into the agentic loop, enabling features such as:4you to inject your own scripts into the agentic loop, enabling features such as:

8 5 

23 20 

24- Matching hooks from multiple files all run.21- Matching hooks from multiple files all run.

25- Multiple matching command hooks for the same event are launched concurrently,22- Multiple matching command hooks for the same event are launched concurrently,

26 so one hook can’t prevent another matching hook from starting.23 so one hook cannot prevent another matching hook from starting.

27- `PreToolUse`, `PermissionRequest`, `PostToolUse`, `UserPromptSubmit`, and24- `PreToolUse`, `PermissionRequest`, `PostToolUse`, `UserPromptSubmit`, and

28 `Stop` run at turn scope.25 `Stop` run at turn scope.

29- Hooks are currently disabled on Windows.

30 26 

31## Where Codex looks for hooks27## Where Codex looks for hooks

32 28 

33Codex discovers `hooks.json` next to active config layers.29Codex discovers hooks next to active config layers in either of these forms:

30 

31- `hooks.json`

32- inline `[hooks]` tables inside `config.toml`

34 33 

35In practice, the two most useful locations are:34Installed plugins can also bundle lifecycle config through their plugin

35manifest or a default `hooks/hooks.json` file. See [Build

36plugins](https://developers.openai.com/codex/plugins/build#bundled-mcp-servers-and-lifecycle-config) for the

37plugin packaging rules.

38 

39In practice, the four most useful locations are:

36 40 

37- `~/.codex/hooks.json`41- `~/.codex/hooks.json`

42- `~/.codex/config.toml`

38- `<repo>/.codex/hooks.json`43- `<repo>/.codex/hooks.json`

44- `<repo>/.codex/config.toml`

39 45 

40If more than one `hooks.json` file exists, Codex loads all matching hooks.46If more than one hook source exists, Codex loads all matching hooks.

41Higher-precedence config layers don’t replace lower-precedence hooks.47Higher-precedence config layers do not replace lower-precedence hooks.

48If a single layer contains both `hooks.json` and inline `[hooks]`, Codex

49merges them and warns at startup. Prefer one representation per layer.

42 50 

43Project-local hooks load only when the project `.codex/` layer is trusted. In51Project-local hooks load only when the project `.codex/` layer is trusted. In

44untrusted projects, Codex still loads user and system hooks from their own52untrusted projects, Codex still loads user and system hooks from their own

131Notes:139Notes:

132 140 

133- `timeout` is in seconds.141- `timeout` is in seconds.

134- `timeoutSec` is also accepted as an alias.

135- If `timeout` is omitted, Codex uses `600` seconds.142- If `timeout` is omitted, Codex uses `600` seconds.

136- `statusMessage` is optional.143- `statusMessage` is optional.

137- Commands run with the session `cwd` as their working directory.144- Commands run with the session `cwd` as their working directory.

139 relative path such as `.codex/hooks/...`. Codex may be started from a146 relative path such as `.codex/hooks/...`. Codex may be started from a

140 subdirectory, and a git-root-based path keeps the hook location stable.147 subdirectory, and a git-root-based path keeps the hook location stable.

141 148 

149Equivalent inline TOML in `config.toml`:

150 

151```toml

152[features]

153codex_hooks = true

154 

155[[hooks.PreToolUse]]

156matcher = "^Bash$"

157 

158[[hooks.PreToolUse.hooks]]

159type = "command"

160command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'

161timeout = 30

162statusMessage = "Checking Bash command"

163 

164[[hooks.PostToolUse]]

165matcher = "^Bash$"

166 

167[[hooks.PostToolUse.hooks]]

168type = "command"

169command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/post_tool_use_review.py"'

170timeout = 30

171statusMessage = "Reviewing Bash output"

172```

173 

174## Managed hooks from `requirements.toml`

175 

176Enterprise-managed requirements can also define hooks inline under `[hooks]`.

177This is useful when admins want to enforce the hook configuration while

178delivering the actual scripts through MDM or another device-management system.

179 

180```toml

181[features]

182codex_hooks = true

183 

184[hooks]

185managed_dir = "/enterprise/hooks"

186windows_managed_dir = 'C:\enterprise\hooks'

187 

188[[hooks.PreToolUse]]

189matcher = "^Bash$"

190 

191[[hooks.PreToolUse.hooks]]

192type = "command"

193command = "python3 /enterprise/hooks/pre_tool_use_policy.py"

194timeout = 30

195statusMessage = "Checking managed Bash command"

196```

197 

198Notes for managed hooks:

199 

200- `managed_dir` is used on macOS and Linux.

201- `windows_managed_dir` is used on Windows.

202- Codex does not distribute the scripts in `managed_dir`; your enterprise

203 tooling must install and update them separately.

204- Managed hook commands should use absolute script paths under the configured

205 managed directory.

206 

142## Matcher patterns207## Matcher patterns

143 208 

144The `matcher` field is a regex string that filters when hooks fire. Use `"*"`,209The `matcher` field is a regex string that filters when hooks fire. Use `"*"`,

149 214 

150| Event | What `matcher` filters | Notes |215| Event | What `matcher` filters | Notes |

151| --- | --- | --- |216| --- | --- | --- |

152| `PermissionRequest` | tool name | Current Codex runtime only emits `Bash`. |217| `PermissionRequest` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |

153| `PostToolUse` | tool name | Current Codex runtime only emits `Bash`. |218| `PostToolUse` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |

154| `PreToolUse` | tool name | Current Codex runtime only emits `Bash`. |219| `PreToolUse` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |

155| `SessionStart` | start source | Current runtime values are `startup` and `resume`. |220| `SessionStart` | start source | Current runtime values are `startup`, `resume`, and `clear` |

156| `UserPromptSubmit` | not supported | Any configured `matcher` is ignored for this event. |221| `UserPromptSubmit` | not supported | Any configured `matcher` is ignored for this event |

157| `Stop` | not supported | Any configured `matcher` is ignored for this event. |222| `Stop` | not supported | Any configured `matcher` is ignored for this event |

223 

224\*For `apply_patch`, matchers can also use `Edit` or `Write`.

158 225 

159Examples:226Examples:

160 227 

161- `Bash`228- `Bash`

162- `startup|resume`229- `^apply_patch$`

163- `Edit|Write`230- `Edit|Write`

164 231- `mcp__filesystem__read_file`

165That last example is still a valid regex, but current Codex `PreToolUse` and232- `mcp__filesystem__.*`

166`PostToolUse` events only emit `Bash`, so it won’t match anything today.233- `startup|resume|clear`

167 234 

168## Common input fields235## Common input fields

169 236 

242 309 

243### PreToolUse310### PreToolUse

244 311 

245Work in progress312`PreToolUse` can intercept Bash, file edits performed through `apply_patch`,

246 313and MCP tool calls. It is still a guardrail rather than a complete enforcement

247Currently `PreToolUse` only supports Bash tool interception. The model can314boundary because Codex can often perform equivalent work through another

248still work around this by writing its own script to disk and then running that315supported tool path.