OpenAI - Codex Docs Changes 2026-03-20 00:35 UTC → 2026-04-16 00:46 UTC

9By default, the agent runs with network access turned off. Locally, Codex uses an OS-enforced sandbox that limits what it can touch (typically to the current workspace), plus an approval policy that controls when it must stop and ask you before acting.9By default, the agent runs with network access turned off. Locally, Codex uses an OS-enforced sandbox that limits what it can touch (typically to the current workspace), plus an approval policy that controls when it must stop and ask you before acting.

10 10 

11For a high-level explanation of how sandboxing works across the Codex app, IDE11For a high-level explanation of how sandboxing works across the Codex app, IDE

12extension, and CLI, see [Sandboxing](https://developers.openai.com/codex/concepts/sandboxing).12extension, and CLI, see [sandboxing](https://developers.openai.com/codex/concepts/sandboxing).

13For a broader enterprise security overview, see the [Codex security white paper](https://trust.openai.com/?itemUid=382f924d-54f3-43a8-a9df-c39e6c959958&source=click).13For a broader enterprise security overview, see the [Codex security white paper](https://trust.openai.com/?itemUid=382f924d-54f3-43a8-a9df-c39e6c959958&source=click).

14 14 

15## Sandbox and approvals15## Sandbox and approvals

81 81 

82If you need Codex to read files, make edits, and run commands with network access without approval prompts, use `--sandbox danger-full-access` (or the `--dangerously-bypass-approvals-and-sandbox` flag). Use caution before doing so.82If you need Codex to read files, make edits, and run commands with network access without approval prompts, use `--sandbox danger-full-access` (or the `--dangerously-bypass-approvals-and-sandbox` flag). Use caution before doing so.

83 83 

84For a middle ground, `approval_policy = { granular = { ... } }` lets you keep specific approval prompt categories interactive while automatically rejecting others. The granular policy covers sandbox approvals, execpolicy-rule prompts, MCP elicitations, `request_permissions` prompts, and skill-script approvals.84For a middle ground, `approval_policy = { granular = { ... } }` lets you keep specific approval prompt categories interactive while automatically rejecting others. The granular policy covers sandbox approvals, execpolicy-rule prompts, MCP prompts, `request_permissions` prompts, and skill-script approvals.

85 

86Set `approvals_reviewer = "guardian_subagent"` to route eligible approval reviews through the Guardian reviewer subagent instead of prompting the user directly. Admin requirements can constrain this with `allowed_approvals_reviewers`.

85 87 

86### Common sandbox and approval combinations88### Common sandbox and approval combinations

87 89 

151Codex enforces the sandbox differently depending on your OS:153Codex enforces the sandbox differently depending on your OS:

152 154 

153- **macOS** uses Seatbelt policies and runs commands using `sandbox-exec` with a profile (`-p`) that corresponds to the `--sandbox` mode you selected. When restricted read access enables platform defaults, Codex appends a curated macOS platform policy (instead of broadly allowing `/System`) to preserve common tool compatibility.155- **macOS** uses Seatbelt policies and runs commands using `sandbox-exec` with a profile (`-p`) that corresponds to the `--sandbox` mode you selected. When restricted read access enables platform defaults, Codex appends a curated macOS platform policy (instead of broadly allowing `/System`) to preserve common tool compatibility.

154- **Linux** uses the bubblewrap pipeline plus `seccomp` by default. `use_legacy_landlock` is available when you need the older path. In managed proxy mode, the default bubblewrap pipeline routes egress through a proxy-only bridge and fails closed if it cannot build valid loopback proxy routes.156- **Linux** uses the `bwrap` pipeline plus `seccomp` by default. `use_legacy_landlock` is available when you need the older path. In managed proxy mode, the default `bwrap` pipeline routes egress through a proxy-only bridge and fails closed if it can’t build valid local proxy routes.

155- **Windows** uses the Linux sandbox implementation when running in [Windows Subsystem for Linux (WSL)](https://developers.openai.com/codex/windows#windows-subsystem-for-linux). When running natively on Windows, Codex uses a [Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox) implementation.157- **Windows** uses the Linux sandbox implementation when running in [Windows Subsystem for Linux 2 (WSL2)](https://developers.openai.com/codex/windows#windows-subsystem-for-linux). WSL1 was supported through Codex `0.114`; starting in `0.115`, the Linux sandbox moved to `bwrap`, so WSL1 is no longer supported. When running natively on Windows, Codex uses a [Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox) implementation.

156 158 

157If you use the Codex IDE extension on Windows, it supports WSL directly. Set the following in your VS Code settings to keep the agent inside WSL whenever it’s available:159If you use the Codex IDE extension on Windows, it supports WSL2 directly. Set the following in your VS Code settings to keep the agent inside WSL2 whenever it's available:

158 160 

159```json161```json

160{162{

18 18 

19 [Download for macOS](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)19 [Download for macOS](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)

20 20 

21 Need a different operating system?

22 

23 [Download for Windows](https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi)

24 

21 [Get notified for Linux](https://openai.com/form/codex-app/)25 [Get notified for Linux](https://openai.com/form/codex-app/)

222. Open Codex and sign in262. Open Codex and sign in

23 27 

40- Build a classic Snake game in this repo.44- Build a classic Snake game in this repo.

41- Find and fix bugs in my codebase with minimal, high-confidence changes.45- Find and fix bugs in my codebase with minimal, high-confidence changes.

42 46 

43 If you need more inspiration, check out the [explore section](https://developers.openai.com/codex/explore).47 If you need more inspiration, explore [Codex use cases](https://developers.openai.com/codex/use-cases).

44 If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).48 If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).

45 49 

46---50---

207- `thread/unarchive` - restore an archived thread rollout back into the active sessions directory; returns the restored `thread` and emits `thread/unarchived`.207- `thread/unarchive` - restore an archived thread rollout back into the active sessions directory; returns the restored `thread` and emits `thread/unarchived`.

208- `thread/status/changed` - notification emitted when a loaded thread's runtime `status` changes.208- `thread/status/changed` - notification emitted when a loaded thread's runtime `status` changes.

209- `thread/compact/start` - trigger conversation history compaction for a thread; returns `{}` immediately while progress streams via `turn/*` and `item/*` notifications.209- `thread/compact/start` - trigger conversation history compaction for a thread; returns `{}` immediately while progress streams via `turn/*` and `item/*` notifications.

210- `thread/shellCommand` - run a user-initiated shell command against a thread. This runs outside the sandbox with full access and doesn't inherit the thread sandbox policy.

211- `thread/backgroundTerminals/clean` - stop all running background terminals for a thread (experimental; requires `capabilities.experimentalApi`).

210- `thread/rollback` - drop the last N turns from the in-memory context and persist a rollback marker; returns the updated `thread`.212- `thread/rollback` - drop the last N turns from the in-memory context and persist a rollback marker; returns the updated `thread`.

211- `turn/start` - add user input to a thread and begin Codex generation; responds with the initial `turn` and streams events. For `collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode."213- `turn/start` - add user input to a thread and begin Codex generation; responds with the initial `turn` and streams events. For `collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode."

212- `turn/steer` - append user input to the active in-flight turn for a thread; returns the accepted `turnId`.214- `turn/steer` - append user input to the active in-flight turn for a thread; returns the accepted `turnId`.

213- `turn/interrupt` - request cancellation of an in-flight turn; success is `{}` and the turn ends with `status: "interrupted"`.215- `turn/interrupt` - request cancellation of an in-flight turn; success is `{}` and the turn ends with `status: "interrupted"`.

214- `review/start` - kick off the Codex reviewer for a thread; emits `enteredReviewMode` and `exitedReviewMode` items.216- `review/start` - kick off the Codex reviewer for a thread; emits `enteredReviewMode` and `exitedReviewMode` items.

215- `command/exec` - run a single command under the server sandbox without starting a thread/turn.217- `command/exec` - run a single command under the server sandbox without starting a thread/turn.

216- `command/exec/write` - write stdin bytes to a running `command/exec` session or close stdin.218- `command/exec/write` - write `stdin` bytes to a running `command/exec` session or close `stdin`.

217- `command/exec/resize` - resize a running PTY-backed `command/exec` session.219- `command/exec/resize` - resize a running PTY-backed `command/exec` session.

218- `command/exec/terminate` - terminate a running `command/exec` session.220- `command/exec/terminate` - stop a running `command/exec` session.

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

220- `experimentalFeature/list` - list feature flags with lifecycle stage metadata and cursor pagination.222- `experimentalFeature/list` - list feature flags with lifecycle stage metadata and cursor pagination.

221- `collaborationMode/list` - list collaboration mode presets (experimental, no pagination).223- `collaborationMode/list` - list collaboration mode presets (experimental, no pagination).

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

223- `plugin/list` - list discovered plugin marketplaces and plugin state, including install/auth policy metadata.225- `plugin/list` - list discovered plugin marketplaces and plugin state, including install/auth policy metadata, marketplace errors, featured plugin ids, and the development-only `forceRemoteSync` option.

224- `plugin/read` - read one plugin by marketplace path and plugin name, including bundled skills, apps, and MCP server names.226- `plugin/read` - read one plugin by marketplace path and plugin name, including bundled skills, apps, and MCP server names.

227- `plugin/install` - install a plugin from a marketplace path.

228- `plugin/uninstall` - uninstall an installed plugin.

225- `app/list` - list available apps (connectors) with pagination plus accessibility/enabled metadata.229- `app/list` - list available apps (connectors) with pagination plus accessibility/enabled metadata.

226- `skills/config/write` - enable or disable skills by path.230- `skills/config/write` - enable or disable skills by path.

227- `mcpServer/oauth/login` - start an OAuth login for a configured MCP server; returns an authorization URL and emits `mcpServer/oauthLogin/completed` on completion.231- `mcpServer/oauth/login` - start an OAuth login for a configured MCP server; returns an authorization URL and emits `mcpServer/oauthLogin/completed` on completion.

228- `tool/requestUserInput` - prompt the user with 1-3 short questions for a tool call (experimental); questions can set `isOther` for a free-form option.232- `tool/requestUserInput` - prompt the user with 1-3 short questions for a tool call (experimental); questions can set `isOther` for a free-form option.

229- `config/mcpServer/reload` - reload MCP server configuration from disk and queue a refresh for loaded threads.233- `config/mcpServer/reload` - reload MCP server configuration from disk and queue a refresh for loaded threads.

230- `mcpServerStatus/list` - list MCP servers, tools, resources, and auth status (cursor + limit pagination).234- `mcpServerStatus/list` - list MCP servers, tools, resources, and auth status (cursor + limit pagination). Use `detail: "full"` for full data or `detail: "toolsAndAuthOnly"` to omit resources.

235- `mcpServer/resource/read` - read a single MCP resource through an initialized MCP server.

231- `windowsSandbox/setupStart` - start Windows sandbox setup for `elevated` or `unelevated` mode; returns quickly and later emits `windowsSandbox/setupCompleted`.236- `windowsSandbox/setupStart` - start Windows sandbox setup for `elevated` or `unelevated` mode; returns quickly and later emits `windowsSandbox/setupCompleted`.

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

233- `config/read` - fetch the effective configuration on disk after resolving configuration layering.238- `config/read` - fetch the effective configuration on disk after resolving configuration layering.

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

235- `externalAgentConfig/import` - apply selected external-agent migration items by passing explicit `migrationItems` with `cwd` (`null` for home).240- `externalAgentConfig/import` - apply selected external-agent migration items by passing explicit `migrationItems` with `cwd` (`null` for home).

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

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

454`thread/unsubscribe` removes the current connection's subscription to a thread. The response status is one of:459`thread/unsubscribe` removes the current connection's subscription to a thread. The response status is one of:

455 460 

456- `unsubscribed` when the connection was subscribed and is now removed.461- `unsubscribed` when the connection was subscribed and is now removed.

457- `notSubscribed` when the connection was not subscribed to that thread.462- `notSubscribed` when the connection wasn't subscribed to that thread.

458- `notLoaded` when the thread is not loaded.463- `notLoaded` when the thread isn't loaded.

459 464 

460If this was the last subscriber, the server unloads the thread and emits a `thread/status/changed` transition to `notLoaded` plus `thread/closed`.465If this was the last subscriber, the server unloads the thread and emits a `thread/status/changed` transition to `notLoaded` plus `thread/closed`.

461 466 

502{ "id": 25, "result": {} }507{ "id": 25, "result": {} }

503```508```

504 509 

510### Run a thread shell command

511 

512Use `thread/shellCommand` for user-initiated shell commands that belong to a thread. The request returns immediately with `{}` while progress streams through standard `turn/*` and `item/*` notifications.

513 

514This API runs outside the sandbox with full access and doesn't inherit the thread sandbox policy. Clients should expose it only for explicit user-initiated commands.

515 

516If the thread already has an active turn, the command runs as an auxiliary action on that turn and its formatted output is injected into the turn's message stream. If the thread is idle, app-server starts a standalone turn for the shell command.

517 

518```json

519{ "method": "thread/shellCommand", "id": 26, "params": { "threadId": "thr_b", "command": "git status --short" } }

520{ "id": 26, "result": {} }

521```

522 

523### Clean background terminals

524 

525Use `thread/backgroundTerminals/clean` to stop all running background terminals associated with a thread. This method is experimental and requires `capabilities.experimentalApi = true`.

526 

527```json

528{ "method": "thread/backgroundTerminals/clean", "id": 27, "params": { "threadId": "thr_b" } }

529{ "id": 27, "result": {} }

530```

531 

505### Roll back recent turns532### Roll back recent turns

506 533 

507Use `thread/rollback` to remove the last `numTurns` entries from the in-memory context and persist a rollback marker in the rollout log. The returned `thread` includes `turns` populated after the rollback.534Use `thread/rollback` to remove the last `numTurns` entries from the in-memory context and persist a rollback marker in the rollout log. The returned `thread` includes `turns` populated after the rollback.

508 535 

509```json536```json

510{ "method": "thread/rollback", "id": 26, "params": { "threadId": "thr_b", "numTurns": 1 } }537{ "method": "thread/rollback", "id": 28, "params": { "threadId": "thr_b", "numTurns": 1 } }

511{ "id": 26, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes", "ephemeral": false } } }538{ "id": 28, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes", "ephemeral": false } } }

512```539```

513 540 

514## Turns541## Turns

1155 1182 

1156### Detect and import external agent config1183### Detect and import external agent config

1157 1184 

1158Use `externalAgentConfig/detect` to discover migratable external-agent artifacts, then pass the selected entries to `externalAgentConfig/import`.1185Use `externalAgentConfig/detect` to discover external-agent artifacts that can be migrated, then pass the selected entries to `externalAgentConfig/import`.

1159 1186 

1160Detection example:1187Detection example:

1161 1188 

1195{ "id": 64, "result": {} }1222{ "id": 64, "result": {} }

1196```1223```

1197 1224 

1198Supported `itemType` values are `AGENTS_MD`, `CONFIG`, `SKILLS`, and `MCP_SERVER_CONFIG`. Detection returns only items that still have work to do. For example, AGENTS migration is skipped when `AGENTS.md` already exists and is non-empty, and skill imports do not overwrite existing skill directories.1225Supported `itemType` values are `AGENTS_MD`, `CONFIG`, `SKILLS`, and `MCP_SERVER_CONFIG`. Detection returns only items that still have work to do. For example, AGENTS migration is skipped when `AGENTS.md` already exists and is non-empty, and skill imports don’t overwrite existing skill directories.

1199 1226 

1200## Auth endpoints1227## Auth endpoints

1201 1228 

1# Windows1# Windows

2 2 

3The [Codex app for Windows](https://apps.microsoft.com/detail/9plm9xgg6vks?hl=en-US&gl=US) gives you one interface for3The [Codex app for Windows](https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi) gives you one interface for

4working across projects, running parallel agent threads, and reviewing results.4working across projects, running parallel agent threads, and reviewing results.

5It runs natively on Windows using PowerShell and the5It runs natively on Windows using PowerShell and the

6[Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox), or you can configure it to6[Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox), or you can configure it to

7run in [Windows Subsystem for Linux (WSL)](#windows-subsystem-for-linux-wsl).7run in [Windows Subsystem for Linux 2 (WSL2)](#windows-subsystem-for-linux-wsl).

8 8 

9![Codex app for Windows showing a project sidebar, active thread, and review pane](/images/codex/windows/codex-windows-light.webp)9![Codex app for Windows showing a project sidebar, active thread, and review pane](/images/codex/windows/codex-windows-light.webp)

10 10 

11## Download and update the Codex app11## Download and update the Codex app

12 12 

13Download the Codex app from the13Download the Codex app from the

14[Microsoft Store](https://apps.microsoft.com/detail/9plm9xgg6vks?hl=en-US&gl=US).14[Microsoft Store](https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi).

15 15 

16Then follow the [quickstart](https://developers.openai.com/codex/quickstart?setup=app) to get started.16Then follow the [quickstart](https://developers.openai.com/codex/quickstart?setup=app) to get started.

17 17 

30 30 

31## Native sandbox31## Native sandbox

32 32 

33The Codex app on Windows supports a native [Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox) when the agent runs in PowerShell, and uses Linux sandboxing when you run the agent in [Windows Subsystem for Linux (WSL)](#windows-subsystem-for-linux-wsl). To apply sandbox protections in either mode, set sandbox permissions to **Default permissions** in the Composer before sending messages to Codex.33The Codex app on Windows supports a native [Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox) when the agent runs in PowerShell, and uses Linux sandboxing when you run the agent in [Windows Subsystem for Linux 2 (WSL2)](#windows-subsystem-for-linux-wsl). To apply sandbox protections in either mode, set sandbox permissions to **Default permissions** in the Composer before sending messages to Codex.

34 34 

35Running Codex in full access mode means Codex is not limited to your project35Running Codex in full access mode means Codex is not limited to your project

36 directory and might perform unintentional destructive actions that can lead to36 directory and might perform unintentional destructive actions that can lead to

71 71 

72By default, the Codex app uses the Windows-native agent. That means the agent72By default, the Codex app uses the Windows-native agent. That means the agent

73runs commands in PowerShell. The app can still work with projects that live in73runs commands in PowerShell. The app can still work with projects that live in

74Windows Subsystem for Linux (WSL) by using the `wsl` CLI when needed.74Windows Subsystem for Linux 2 (WSL2) by using the `wsl` CLI when needed.

75 75 

76If you want to add a project from the WSL filesystem, click **Add new project**76If you want to add a project from the WSL filesystem, click **Add new project**

77or press <kbd>Ctrl</kbd>+<kbd>O</kbd>, then type `\\wsl$\` into the File77or press <kbd>Ctrl</kbd>+<kbd>O</kbd>, then type `\\wsl$\` into the File

83`/mnt/<drive>/...`. This setup is more reliable than opening projects83`/mnt/<drive>/...`. This setup is more reliable than opening projects

84directly from the WSL filesystem.84directly from the WSL filesystem.

85 85 

86If you want the agent itself to run in WSL, open **[Settings](codex://settings)**,86If you want the agent itself to run in WSL2, open **[Settings](codex://settings)**,

87switch the agent from Windows native to WSL, and **restart the app**. The87switch the agent from Windows native to WSL, and **restart the app**. The

88change doesn't take effect until you restart. Your projects should remain in88change doesn't take effect until you restart. Your projects should remain in

89place after restart.89place after restart.

90 90 

91WSL1 was supported through Codex `0.114`. Starting in Codex `0.115`, the Linux

92sandbox moved to `bubblewrap`, so WSL1 is no longer supported.

93 

91![Codex app settings showing the agent selector with Windows native and WSL options](/images/codex/windows/wsl-select-light.webp)94![Codex app settings showing the agent selector with Windows native and WSL options](/images/codex/windows/wsl-select-light.webp)

92 95 

93You configure the integrated terminal independently from the agent. See96You configure the integrated terminal independently from the agent. See

181`%USERPROFILE%\.codex`.184`%USERPROFILE%\.codex`.

182 185 

183If you also run the Codex CLI inside WSL, the CLI uses the Linux home186If you also run the Codex CLI inside WSL, the CLI uses the Linux home

184directory by default, so it does not automatically share configuration, cached187directory by default, so it doesn't automatically share configuration, cached

185auth, or session history with the Windows app.188auth, or session history with the Windows app.

186 189 

187To share them, use one of these approaches:190To share them, use one of these approaches:

203 206 

204### Git isn't detected for projects opened from `\\wsl$`207### Git isn't detected for projects opened from `\\wsl$`

205 208 

206For now, if you want to use the Windows-native agent with a project that is209For now, if you want to use the Windows-native agent with a project also

207also accessible from WSL, the most reliable workaround is to store the project210accessible from WSL, the most reliable workaround is to store the project

208on the native Windows drive and access it in WSL through `/mnt/<drive>/...`.211on the native Windows drive and access it in WSL through `/mnt/<drive>/...`.

209 212 

210### Cmder is not listed in the open dialog213### `Cmder` isn't listed in the open dialog

211 214 

212If Cmder is installed but doesn’t show in Codex’s open dialog, add it to the215If `Cmder` is installed but doesn't show in Codex's open dialog, add it to the

213Windows Start Menu: right-click Cmder and choose **Add to Start**, then restart216Windows Start Menu: right-click `Cmder` and choose **Add to Start**, then

214Codex or reboot.217restart Codex or reboot.

44 npm i -g @openai/codex@latestCopy44 npm i -g @openai/codex@latestCopy

45 45 

46The Codex CLI is available on macOS and Linux. Windows support is46The Codex CLI is available on macOS and Linux. Windows support is

47experimental. For the best Windows experience, use Codex in a WSL workspace47experimental. For the best Windows experience, use Codex in a WSL2 workspace

48and follow our [Windows setup guide](https://developers.openai.com/codex/windows).48and follow our [Windows setup guide](https://developers.openai.com/codex/windows).

49 49 

50If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).50If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).

69 69 

70Launch a Codex Cloud task, choose environments, and apply the resulting diffs without leaving your terminal.](https://developers.openai.com/codex/cli/features#working-with-codex-cloud)[### Scripting Codex70Launch a Codex Cloud task, choose environments, and apply the resulting diffs without leaving your terminal.](https://developers.openai.com/codex/cli/features#working-with-codex-cloud)[### Scripting Codex

71 71 

72Automate repeatable workflows by scripting Codex with the `exec` command.](https://developers.openai.com/codex/sdk#using-codex-cli-programmatically)[### Model Context Protocol72Automate repeatable workflows by scripting Codex with the `exec` command.](https://developers.openai.com/codex/noninteractive)[### Model Context Protocol

73 73 

74Give Codex access to additional third-party tools and context with Model Context Protocol (MCP).](https://developers.openai.com/codex/mcp)[### Approval modes74Give Codex access to additional third-party tools and context with Model Context Protocol (MCP).](https://developers.openai.com/codex/mcp)[### Approval modes

75 75 

44 44 

45Each resumed run keeps the original transcript, plan history, and approvals, so Codex can use prior context while you supply new instructions. Override the working directory with `--cd` or add extra roots with `--add-dir` if you need to steer the environment before resuming.45Each resumed run keeps the original transcript, plan history, and approvals, so Codex can use prior context while you supply new instructions. Override the working directory with `--cd` or add extra roots with `--add-dir` if you need to steer the environment before resuming.

46 46 

47## Connect the TUI to a remote app server

48 

49Remote TUI mode lets you run the Codex app server on one machine and use the Codex terminal UI from another machine. This is useful when the code, credentials, or execution environment live on a remote host, but you want the local interactive TUI experience.

50 

51Start the app server on the machine that should own the workspace and run commands:

52 

53```bash

54codex app-server --listen ws://127.0.0.1:4500

55```

56 

57Then connect from the machine running the TUI:

58 

59```bash

60codex --remote ws://127.0.0.1:4500

61```

62 

63For access from another machine, bind the app server to a reachable interface, for example:

64 

65```bash

66codex app-server --listen ws://0.0.0.0:4500

67```

68 

69`--remote` accepts explicit `ws://host:port` and `wss://host:port` addresses only. For plain WebSocket connections, prefer local-host addresses or SSH port forwarding. If you expose the listener beyond the local host, configure authentication before real remote use and put authenticated non-local connections behind TLS.

70 

71Codex supports these WebSocket authentication modes for remote TUI connections:

72 

73- **No WebSocket auth**: Best for local-host listeners or SSH port-forwarded connections. Codex can start non-local listeners without auth, but logs a warning and the startup banner reminds you to configure auth before real remote use.

74- **Capability token**: Store a shared token in a file on the app-server host, start the server with `--ws-auth capability-token --ws-token-file /abs/path/to/token`, then set the same token in an environment variable on the TUI host and pass `--remote-auth-token-env <ENV_VAR>`.

75- **Signed bearer token**: Store an HMAC shared secret in a file on the app-server host, start the server with `--ws-auth signed-bearer-token --ws-shared-secret-file /abs/path/to/secret`, and have the TUI send a signed JWT bearer token through `--remote-auth-token-env <ENV_VAR>`. The shared secret must be at least 32 bytes. Signed tokens use HS256 and must include `exp`; Codex also validates `nbf`, `iss`, and `aud` when those claims or server options are present.

76 

77To create a capability token on the app-server host, generate a random token file with permissions that only your user can read:

78 

79```bash

80TOKEN_FILE="$HOME/.codex/codex-app-server-token"

81install -d -m 700 "$(dirname "$TOKEN_FILE")"

82openssl rand -base64 32 > "$TOKEN_FILE"

83chmod 600 "$TOKEN_FILE"

84```

85 

86Treat the token file like a password, and regenerate it if it leaks.

87 

88Then start the app server with that token file. For example, with a capability token behind a TLS proxy:

89 

90```bash

91# Remote host

92TOKEN_FILE="$HOME/.codex/codex-app-server-token"

93codex app-server \

94 --listen ws://0.0.0.0:4500 \

95 --ws-auth capability-token \

96 --ws-token-file "$TOKEN_FILE"

97 

98# TUI host

99export CODEX_REMOTE_AUTH_TOKEN="$(ssh devbox 'cat ~/.codex/codex-app-server-token')"

100codex --remote wss://codex-devbox.example.com:4500 \

101 --remote-auth-token-env CODEX_REMOTE_AUTH_TOKEN

102```

103 

104The TUI sends remote auth tokens as `Authorization: Bearer <token>` during the WebSocket handshake. Codex only sends those tokens over `wss://` URLs or `ws://` URLs whose host is `localhost`, `127.0.0.1`, or `::1`, so put non-local remote listeners behind TLS if clients need to authenticate over the network.

105 

47## Models and reasoning106## Models and reasoning

48 107 

49For most tasks in Codex, `gpt-5.4` is the recommended model. It brings the108For most tasks in Codex, `gpt-5.4` is the recommended model. It brings the

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`. |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. |24| `--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-codex`). |25| `--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). |26| `--no-alt-screen` | `boolean` | Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run). |

27| `--oss` | `boolean` | Use the local open source model provider (equivalent to `-c model_provider="oss"`). Validates that Ollama is running. |27| `--oss` | `boolean` | Use the local open source model provider (equivalent to `-c model_provider="oss"`). Validates that Ollama is running. |

28| `--profile, -p` | `string` | Configuration profile name to load from `~/.codex/config.toml`. |28| `--profile, -p` | `string` | Configuration profile name to load from `~/.codex/config.toml`. |

29| `--remote` | `ws://host:port | wss://host:port` | Connect the interactive TUI to a remote app-server WebSocket endpoint. Supported for `codex`, `codex resume`, and `codex fork`; other subcommands reject remote mode. |

30| `--remote-auth-token-env` | `ENV_VAR` | Read a bearer token from this environment variable and send it when connecting with `--remote`. Requires `--remote`; tokens are only sent over `wss://` URLs or `ws://` URLs whose host is `localhost`, `127.0.0.1`, or `::1`. |

29| `--sandbox, -s` | `read-only | workspace-write | danger-full-access` | Select the sandbox policy for model-generated shell commands. |31| `--sandbox, -s` | `read-only | workspace-write | danger-full-access` | Select the sandbox policy for model-generated shell commands. |

30| `--search` | `boolean` | Enable live web search (sets `web_search = "live"` instead of the default `"cached"`). |32| `--search` | `boolean` | Enable live web search (sets `web_search = "live"` instead of the default `"cached"`). |

31| `PROMPT` | `string` | Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message. |33| `PROMPT` | `string` | Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message. |

148 150 

149Details151Details

150 152 

151Override the model set in configuration (for example `gpt-5-codex`).153Override the model set in configuration (for example `gpt-5.4`).

152 154 

153Key155Key

154 156 

188 190 

189Key191Key

190 192 

193`--remote`

194 

195Type / Values

196 

197`ws://host:port | wss://host:port`

198 

199Details

200 

201Connect the interactive TUI to a remote app-server WebSocket endpoint. Supported for `codex`, `codex resume`, and `codex fork`; other subcommands reject remote mode.

202 

203Key

204 

205`--remote-auth-token-env`

206 

207Type / Values

208 

209`ENV_VAR`

210 

211Details

212 

213Read a bearer token from this environment variable and send it when connecting with `--remote`. Requires `--remote`; tokens are only sent over `wss://` URLs or `ws://` URLs whose host is `localhost`, `127.0.0.1`, or `::1`.

214 

215Key

216 

191`--sandbox, -s`217`--sandbox, -s`

192 218 

193Type / Values219Type / Values

251| [`codex mcp`](https://developers.openai.com/codex/cli/reference#codex-mcp) | Experimental | Manage Model Context Protocol servers (list, add, remove, authenticate). |277| [`codex mcp`](https://developers.openai.com/codex/cli/reference#codex-mcp) | Experimental | Manage Model Context Protocol servers (list, add, remove, authenticate). |

252| [`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. |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. |

253| [`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. |279| [`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. |

254| [`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox) | Experimental | Run arbitrary commands inside Codex-provided macOS seatbelt or Linux sandboxes (Landlock by default, optional bubblewrap pipeline). |280| [`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox) | Experimental | Run arbitrary commands inside Codex-provided macOS seatbelt or Linux bubblewrap sandboxes. |

255 281 

256Key282Key

257 283 

455 481 

456Details482Details

457 483 

458Run arbitrary commands inside Codex-provided macOS seatbelt or Linux sandboxes (Landlock by default, optional bubblewrap pipeline).484Run arbitrary commands inside Codex-provided macOS seatbelt or Linux bubblewrap sandboxes.

459 485 

460Expand to view all486Expand to view all

461 487 

465 491 

466Running `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.492Running `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.

467 493 

494Use `--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.

495 

468### `codex app-server`496### `codex app-server`

469 497 

470Launch the Codex app server locally. This is primarily for development and debugging and may change without notice.498Launch the Codex app server locally. This is primarily for development and debugging and may change without notice.

471 499 

472| Key | Type / Values | Details |500| Key | Type / Values | Details |

473| --- | --- | --- |501| --- | --- | --- |

474| `--listen` | `stdio:// | ws://IP:PORT` | Transport listener URL. `ws://` is experimental and intended for development/testing. |502| `--listen` | `stdio:// | ws://IP:PORT` | Transport listener URL. Use `ws://IP:PORT` to expose a WebSocket endpoint for remote clients. |

503| `--ws-audience` | `string` | Expected `aud` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`. |

504| `--ws-auth` | `capability-token | signed-bearer-token` | Authentication mode for app-server WebSocket clients. If omitted, WebSocket auth is disabled; non-local listeners warn during startup. |

505| `--ws-issuer` | `string` | Expected `iss` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`. |

506| `--ws-max-clock-skew-seconds` | `number` | Clock skew allowance when validating signed bearer token `exp` and `nbf` claims. Requires `--ws-auth signed-bearer-token`. |

507| `--ws-shared-secret-file` | `absolute path` | File containing the HMAC shared secret used to validate signed JWT bearer tokens. Required with `--ws-auth signed-bearer-token`. |

508| `--ws-token-file` | `absolute path` | File containing the shared capability token. Required with `--ws-auth capability-token`. |

475 509 

476Key510Key

477 511 

483 517 

484Details518Details

485 519 

486Transport listener URL. `ws://` is experimental and intended for development/testing.520Transport listener URL. Use `ws://IP:PORT` to expose a WebSocket endpoint for remote clients.

521 

522Key

523 

524`--ws-audience`

525 

526Type / Values

527 

528`string`

529 

530Details

531 

532Expected `aud` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.

533 

534Key

535 

536`--ws-auth`

537 

538Type / Values

539 

540`capability-token | signed-bearer-token`

541 

542Details

543 

544Authentication mode for app-server WebSocket clients. If omitted, WebSocket auth is disabled; non-local listeners warn during startup.

545 

546Key

547 

548`--ws-issuer`

549 

550Type / Values

551 

552`string`

553 

554Details

555 

556Expected `iss` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.

557 

558Key

559 

560`--ws-max-clock-skew-seconds`

561 

562Type / Values

563 

564`number`

565 

566Details

567 

568Clock skew allowance when validating signed bearer token `exp` and `nbf` claims. Requires `--ws-auth signed-bearer-token`.

569 

570Key

571 

572`--ws-shared-secret-file`

573 

574Type / Values

575 

576`absolute path`

577 

578Details

579 

580File containing the HMAC shared secret used to validate signed JWT bearer tokens. Required with `--ws-auth signed-bearer-token`.

581 

582Key

583 

584`--ws-token-file`

585 

586Type / Values

587 

588`absolute path`

589 

590Details

591 

592File containing the shared capability token. Required with `--ws-auth capability-token`.

487 593 

488`codex app-server --listen stdio://` keeps the default JSONL-over-stdio behavior. `--listen ws://IP:PORT` enables WebSocket transport (experimental). If you generate schemas for client bindings, add `--experimental` to include gated fields and methods.594`codex app-server --listen stdio://` keeps the default JSONL-over-stdio behavior. `--listen ws://IP:PORT` enables WebSocket transport for app-server clients. The server accepts `ws://` listen URLs; use TLS termination or a secure proxy when clients connect with `wss://`. If you generate schemas for client bindings, add `--experimental` to include gated fields and methods.

489 595 

490### `codex app`596### `codex app`

491 597 

22| [`/sandbox-add-read-dir`](#grant-sandbox-read-access-with-sandbox-add-read-dir) | Grant sandbox read access to an extra directory (Windows only). | Unblock commands that need to read an absolute directory path outside the current readable roots. |22| [`/sandbox-add-read-dir`](#grant-sandbox-read-access-with-sandbox-add-read-dir) | Grant sandbox read access to an extra directory (Windows only). | Unblock commands that need to read an absolute directory path outside the current readable roots. |

23| [`/agent`](#switch-agent-threads-with-agent) | Switch the active agent thread. | Inspect or continue work in a spawned subagent thread. |23| [`/agent`](#switch-agent-threads-with-agent) | Switch the active agent thread. | Inspect or continue work in a spawned subagent thread. |

24| [`/apps`](#browse-apps-with-apps) | Browse apps (connectors) and insert them into your prompt. | Attach an app as `$app-slug` before asking Codex to use it. |24| [`/apps`](#browse-apps-with-apps) | Browse apps (connectors) and insert them into your prompt. | Attach an app as `$app-slug` before asking Codex to use it. |

25| [`/clear`](#clear-the-terminal-and-start-a-new-chat-with-clear) | Clear the terminal and start a fresh chat. | Reset the visible UI and conversation together when you want a clean slate. |25| [`/plugins`](#browse-plugins-with-plugins) | Browse installed and discoverable plugins. | Inspect plugin tools, install suggested plugins, or manage plugin availability. |

26| [`/clear`](#clear-the-terminal-and-start-a-new-chat-with-clear) | Clear the terminal and start a fresh chat. | Reset the visible UI and conversation together when you want a fresh start. |

26| [`/compact`](#keep-transcripts-lean-with-compact) | Summarize the visible conversation to free tokens. | Use after long runs so Codex retains key points without blowing the context window. |27| [`/compact`](#keep-transcripts-lean-with-compact) | Summarize the visible conversation to free tokens. | Use after long runs so Codex retains key points without blowing the context window. |

27| [`/copy`](#copy-the-latest-response-with-copy) | Copy the latest completed Codex output. | Grab the latest finished response or plan text without manually selecting it. |28| [`/copy`](#copy-the-latest-response-with-copy) | Copy the latest completed Codex output. | Grab the latest finished response or plan text without manually selecting it. |

28| [`/diff`](#review-changes-with-diff) | Show the Git diff, including files Git isn't tracking yet. | Review Codex's edits before you commit or run tests. |29| [`/diff`](#review-changes-with-diff) | Show the Git diff, including files Git isn't tracking yet. | Review Codex's edits before you commit or run tests. |

38| [`/plan`](#switch-to-plan-mode-with-plan) | Switch to plan mode and optionally send a prompt. | Ask Codex to propose an execution plan before implementation work starts. |39| [`/plan`](#switch-to-plan-mode-with-plan) | Switch to plan mode and optionally send a prompt. | Ask Codex to propose an execution plan before implementation work starts. |

39| [`/personality`](#set-a-communication-style-with-personality) | Choose a communication style for responses. | Make Codex more concise, more explanatory, or more collaborative without changing your instructions. |40| [`/personality`](#set-a-communication-style-with-personality) | Choose a communication style for responses. | Make Codex more concise, more explanatory, or more collaborative without changing your instructions. |

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

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

41| [`/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. |43| [`/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. |

42| [`/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. |44| [`/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. |

43| [`/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. |45| [`/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. |

46| [`/status`](#inspect-the-session-with-status) | Display session configuration and token usage. | Confirm the active model, approval policy, writable roots, and remaining context capacity. |48| [`/status`](#inspect-the-session-with-status) | Display session configuration and token usage. | Confirm the active model, approval policy, writable roots, and remaining context capacity. |

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

48| [`/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. |50| [`/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. |

51| [`/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. |

49 52 

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

51committed any important work.54committed any important work.

177limits, git branch, token counters, session id, current directory/project root,180limits, git branch, token counters, session id, current directory/project root,

178and Codex version.181and Codex version.

179 182 

183### Configure terminal title items with `/title`

184 

1851. Type `/title`.

1862. Use the picker to toggle and reorder items, then confirm.

187 

188Expected: The terminal window or tab title updates immediately and persists to

189`tui.terminal_title` in `config.toml`.

190 

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

192branch, model, and task progress.

193 

180### Check background terminals with `/ps`194### Check background terminals with `/ps`

181 195 

1821. Type `/ps`.1961. Type `/ps`.

187 201 

188Background terminals appear when `unified_exec` is in use; otherwise, the list may be empty.202Background terminals appear when `unified_exec` is in use; otherwise, the list may be empty.

189 203 

204### Stop background terminals with `/stop`

205 

2061. Type `/stop`.

2072. Confirm if Codex asks before stopping the listed terminals.

208 

209Expected: Codex stops all background terminals for the current session. `/clean`

210is still available as an alias for `/stop`.

211 

190### Keep transcripts lean with `/compact`212### Keep transcripts lean with `/compact`

191 213 

1921. After a long exchange, type `/compact`.2141. After a long exchange, type `/compact`.

217Expected: Codex starts a fresh conversation in the same CLI session, so you239Expected: Codex starts a fresh conversation in the same CLI session, so you

218can switch tasks without leaving your terminal.240can switch tasks without leaving your terminal.

219 241 

220Unlike `/clear`, `/new` does not clear the current terminal view first.242Unlike `/clear`, `/new` doesn't clear the current terminal view first.

221 243 

222### Resume a saved conversation with `/resume`244### Resume a saved conversation with `/resume`

223 245 

270Expected: Codex inserts the app mention into the composer as `$app-slug`, so292Expected: Codex inserts the app mention into the composer as `$app-slug`, so

271you can immediately ask Codex to use it.293you can immediately ask Codex to use it.

272 294 

295### Browse plugins with `/plugins`

296 

2971. Type `/plugins`.

2982. Pick a plugin from the list to inspect its capabilities or available actions.

299 

300Expected: Codex opens the plugin browser so you can review installed plugins and

301discoverable plugins that your configuration allows.

302 

273### Switch agent threads with `/agent`303### Switch agent threads with `/agent`

274 304 

2751. Type `/agent` and press Enter.3051. Type `/agent` and press Enter.

16 16 

17Download and start building with Codex.17Download and start building with Codex.

18 18 

19 Get started](https://developers.openai.com/codex/quickstart) [### Explore19 Get started](https://developers.openai.com/codex/quickstart) [### Explore use cases

20 20 

21Get inspirations on what you can build with Codex.21Get inspiration on what you can build with Codex.

22 22 

23 Learn more](https://developers.openai.com/codex/explore) [### Community23 Learn more](https://developers.openai.com/codex/use-cases) [### Community

24 24 

25Read community posts, explore meetups, and connect with Codex builders.25Read community posts, explore meetups, and connect with Codex builders.

26 26 

54Skills are often the best fit for reusable workflows because they support richer instructions, scripts, and references while staying reusable across tasks.54Skills are often the best fit for reusable workflows because they support richer instructions, scripts, and references while staying reusable across tasks.

55Skills are loaded and visible to the agent (at least their metadata), so Codex can discover and choose them implicitly. This keeps rich workflows available without bloating context up front.55Skills are loaded and visible to the agent (at least their metadata), so Codex can discover and choose them implicitly. This keeps rich workflows available without bloating context up front.

56 56 

57Use skill folders to author and iterate on workflows locally. If a plugin

58already exists for the workflow, install it first to reuse a proven setup. When

59you want to distribute your own workflow across teams or bundle it with app

60integrations, package it as a [plugin](https://developers.openai.com/codex/plugins/build). Skills remain the

61authoring format; plugins are the installable distribution unit.

62 

57A skill is typically a `SKILL.md` file plus optional scripts, references, and assets.63A skill is typically a `SKILL.md` file plus optional scripts, references, and assets.

58 64 

59- my-skill/65- my-skill/

87 93 

88Skills can be global (in your user directory, for you as a developer) or repo-specific (checked into `.agents/skills`, for your team). Put repo skills in `.agents/skills` when the workflow applies to that project; use your user directory for skills you want across all repos.94Skills can be global (in your user directory, for you as a developer) or repo-specific (checked into `.agents/skills`, for your team). Put repo skills in `.agents/skills` when the workflow applies to that project; use your user directory for skills you want across all repos.

89 95 

90| Layer | Global | repo |96| Layer | Global | Repo |

91| :----- | :--------------------- | :--------------------------------------------- |97| :----- | :--------------------- | :--------------------------------------------- |

92| AGENTS | `~/.codex/AGENTS.md` | `AGENTS.md` in repo root or nested directories |98| AGENTS | `~/.codex/AGENTS.md` | `AGENTS.md` in repo root or nested directories |

93| Skills | `$HOME/.agents/skills` | `.agents/skills` in repo |99| Skills | `$HOME/.agents/skills` | `.agents/skills` in repo |

145Build in this order:151Build in this order:

146 152 

1471. [Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md) so Codex follows your repo conventions. Add pre-commit hooks and linters to enforce those rules.1531. [Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md) so Codex follows your repo conventions. Add pre-commit hooks and linters to enforce those rules.

1482. [Skills](https://developers.openai.com/codex/skills) so you never have the same conversation twice. Skills can include a `scripts/` directory with CLI scripts or pair with [MCP](https://developers.openai.com/codex/mcp) for external systems.1542. Install a [plugin](https://developers.openai.com/codex/plugins) when a reusable workflow already exists. Otherwise, create a [skill](https://developers.openai.com/codex/skills) and package it as a plugin when you want to share it.

1493. [MCP](https://developers.openai.com/codex/mcp) when workflows need external systems (Linear, GitHub, docs servers, design tools).1553. [MCP](https://developers.openai.com/codex/mcp) when workflows need external systems (Linear, GitHub, docs servers, design tools).

1504. [Subagents](https://developers.openai.com/codex/subagents) when you're ready to delegate noisy or specialized tasks to subagents.1564. [Subagents](https://developers.openai.com/codex/subagents) when you're ready to delegate noisy or specialized tasks to subagents.

1# Sandboxing – Codex1# Sandbox

2 2 

3Sandboxing is the boundary that lets Codex act autonomously without giving it3The sandbox is the boundary that lets Codex act autonomously without giving it

4unrestricted access to your machine. When Codex runs local commands in the4unrestricted access to your machine. When Codex runs local commands in the

5**Codex app**, **IDE extension**, or **CLI**, those commands run inside a5**Codex app**, **IDE extension**, or **CLI**, those commands run inside a

6constrained environment instead of running with full access by default.6constrained environment instead of running with full access by default.

21those commands inherit the same sandbox boundaries.21those commands inherit the same sandbox boundaries.

22 22 

23Codex uses platform-native enforcement on each OS. The implementation differs23Codex uses platform-native enforcement on each OS. The implementation differs

24between macOS, Linux, WSL, and native Windows, but the idea is the same across24between macOS, Linux, WSL2, and native Windows, but the idea is the same across

25surfaces: give the agent a bounded place to work so routine tasks can run25surfaces: give the agent a bounded place to work so routine tasks can run

26autonomously inside clear limits.26autonomously inside clear limits.

27 27 

28## Why it matters28## Why it matters

29 29 

30Sandboxing reduces approval fatigue. Instead of asking you to confirm every30The sandbox reduces approval fatigue. Instead of asking you to confirm every

31low-risk command, Codex can read files, make edits, and run routine project31low-risk command, Codex can read files, make edits, and run routine project

32commands within the boundary you already approved.32commands within the boundary you already approved.

33 33 

34It also gives you a clearer trust model for agentic work. You are not just34It also gives you a clearer trust model for agentic work. You aren't just

35trusting the agent's intentions; you are trusting that the agent is operating35trusting the agent's intentions; you are trusting that the agent is operating

36inside enforced limits. That makes it easier to let Codex work independently36inside enforced limits. That makes it easier to let Codex work independently

37while still knowing when it will stop and ask for help.37while still knowing when it will stop and ask for help.

38 38 

39## Getting started

40 

41Codex applies sandboxing automatically when you use the default permissions

42mode.

43 

44### Prerequisites

45 

46On **macOS**, sandboxing works out of the box using the built-in Seatbelt

47framework.

48 

49On **Windows**, Codex uses the native [Windows

50sandbox](https://developers.openai.com/codex/windows#windows-sandbox) when you run in PowerShell and the

51Linux sandbox implementation when you run in WSL2.

52 

53On **Linux and WSL2**, install `bubblewrap` with your package manager first:

54 

55```bash

56sudo apt install bubblewrap

57```

58 

59```bash

60sudo dnf install bubblewrap

61```

62 

63Codex uses the first `bwrap` executable it finds on `PATH`. If no `bwrap`

64executable is available, Codex falls back to a bundled helper, but that helper

65requires support for unprivileged user namespace creation. Installing the

66distribution package that provides `bwrap` keeps this setup reliable.

67 

68Codex surfaces a startup warning when `bwrap` is missing or when the helper

69can't create the needed user namespace. On distributions that restrict this

70AppArmor setting, you can enable it with:

71 

72```bash

73sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

74```

75 

39## How you control it76## How you control it

40 77 

41Most people start with the permissions controls in the product.78Most people start with the permissions controls in the product.

62 99 

63At a high level, the common sandbox modes are:100At a high level, the common sandbox modes are:

64 101 

65- `read-only`: Codex can inspect files, but it cannot edit files or run102- `read-only`: Codex can inspect files, but it can't edit files or run

66 commands without approval.103 commands without approval.

67- `workspace-write`: Codex can read files, edit within the workspace, and run104- `workspace-write`: Codex can read files, edit within the workspace, and run

68 routine local commands inside that boundary. This is the default low-friction105 routine local commands inside that boundary. This is the default low-friction

73 110 

74The common approval policies are:111The common approval policies are:

75 112 

76- `untrusted`: Codex asks before running commands that are not in its trusted113- `untrusted`: Codex asks before running commands that aren't in its trusted

77 set.114 set.

78- `on-request`: Codex works inside the sandbox by default and asks when it115- `on-request`: Codex works inside the sandbox by default and asks when it

79 needs to go beyond that boundary.116 needs to go beyond that boundary.

80- `never`: Codex does not stop for approval prompts.117- `never`: Codex doesn't stop for approval prompts.

81 118 

82Full access means using `sandbox_mode = "danger-full-access"` together with119Full access means using `sandbox_mode = "danger-full-access"` together with

83`approval_policy = "never"`. By contrast, `--full-auto` is the lower-risk local120`approval_policy = "never"`. By contrast, `--full-auto` is the lower-risk local

87If you need Codex to work across more than one directory, writable roots let124If you need Codex to work across more than one directory, writable roots let

88you extend the places it can modify without removing the sandbox entirely. If125you extend the places it can modify without removing the sandbox entirely. If

89you need a broader or narrower trust boundary, adjust the default sandbox mode126you need a broader or narrower trust boundary, adjust the default sandbox mode

90and approval policy instead of relying on ad hoc exceptions.127and approval policy instead of relying on one-off exceptions.

128 

129For reusable permission sets, set `default_permissions` to a named profile and

130define `[permissions.<name>.filesystem]` or `[permissions.<name>.network]`.

131Managed network profiles use map tables such as

132`[permissions.<name>.network.domains]` and

133`[permissions.<name>.network.unix_sockets]` for domain and socket rules.

91 134 

92When a workflow needs a specific exception, use [rules](https://developers.openai.com/codex/rules). Rules135When a workflow needs a specific exception, use [rules](https://developers.openai.com/codex/rules). Rules

93let you allow, prompt, or forbid command prefixes outside the sandbox, which is136let you allow, prompt, or forbid command prefixes outside the sandbox, which is

15Define profiles under `[profiles.<name>]` in `config.toml`, then run `codex --profile <name>`:15Define profiles under `[profiles.<name>]` in `config.toml`, then run `codex --profile <name>`:

16 16 

17```toml17```toml

18model = "gpt-5-codex"18model = "gpt-5.4"

19approval_policy = "on-request"19approval_policy = "on-request"

20model_catalog_json = "/Users/me/.codex/model-catalogs/default.json"20model_catalog_json = "/Users/me/.codex/model-catalogs/default.json"

21 21 

88 88 

89Relative paths inside a project config (for example, `model_instructions_file`) are resolved relative to the `.codex/` folder that contains the `config.toml`.89Relative paths inside a project config (for example, `model_instructions_file`) are resolved relative to the `.codex/` folder that contains the `config.toml`.

90 90 

91## Hooks (experimental)

92 

93Codex can also load lifecycle hooks from `hooks.json` files that sit next to

94active config layers.

95 

96In practice, the two most useful locations are:

97 

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

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

100 

101Turn hooks on with:

102 

103```toml

104[features]

105codex_hooks = true

106```

107 

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

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

110 

91## Agent roles (`[agents]` in `config.toml`)111## Agent roles (`[agents]` in `config.toml`)

92 112 

93For subagent role configuration (`[agents]` in `config.toml`), see [Subagents](https://developers.openai.com/codex/subagents).113For subagent role configuration (`[agents]` in `config.toml`), see [Subagents](https://developers.openai.com/codex/subagents).

107 127 

108## Custom model providers128## Custom model providers

109 129 

110A model provider defines how Codex connects to a model (base URL, wire API, and optional HTTP headers).130A model provider defines how Codex connects to a model (base URL, wire API, authentication, and optional HTTP headers). Custom providers can't reuse the reserved built-in provider IDs: `openai`, `ollama`, and `lmstudio`.

111 131 

112Define additional providers and point `model_provider` at them:132Define additional providers and point `model_provider` at them:

113 133 

114```toml134```toml

115model = "gpt-5.1"135model = "gpt-5.4"

116model_provider = "proxy"136model_provider = "proxy"

117 137 

118[model_providers.proxy]138[model_providers.proxy]

120base_url = "http://proxy.example.com"140base_url = "http://proxy.example.com"

121env_key = "OPENAI_API_KEY"141env_key = "OPENAI_API_KEY"

122 142 

123[model_providers.ollama]143[model_providers.local_ollama]

124name = "Ollama"144name = "Ollama"

125base_url = "http://localhost:11434/v1"145base_url = "http://localhost:11434/v1"

126 146 

138env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }158env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }

139```159```

140 160 

161Use command-backed authentication when a provider needs Codex to fetch bearer tokens from an external credential helper:

162 

163```toml

164[model_providers.proxy]

165name = "OpenAI using LLM proxy"

166base_url = "https://proxy.example.com/v1"

167wire_api = "responses"

168 

169[model_providers.proxy.auth]

170command = "/usr/local/bin/fetch-codex-token"

171args = ["--audience", "codex"]

172timeout_ms = 5000

173refresh_interval_ms = 300000

174```

175 

176The 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`.

177 

141## OSS mode (local providers)178## OSS mode (local providers)

142 179 

143Codex 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.180Codex 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.

156env_key = "AZURE_OPENAI_API_KEY"193env_key = "AZURE_OPENAI_API_KEY"

157query_params = { api-version = "2025-04-01-preview" }194query_params = { api-version = "2025-04-01-preview" }

158wire_api = "responses"195wire_api = "responses"

159 

160[model_providers.openai]

161request_max_retries = 4196request_max_retries = 4

162stream_max_retries = 10197stream_max_retries = 10

163stream_idle_timeout_ms = 300000198stream_idle_timeout_ms = 300000

164```199```

165 200 

201To change the base URL for the built-in OpenAI provider, use `openai_base_url`; don't create `[model_providers.openai]`, because you can't override built-in provider IDs.

202 

166## ChatGPT customers using data residency203## ChatGPT customers using data residency

167 204 

168Projects created with [data residency](https://help.openai.com/en/articles/9903489-data-residency-and-inference-residency-for-chatgpt) enabled can create a model provider to update the base_url with the [correct prefix](https://platform.openai.com/docs/guides/your-data#which-models-and-features-are-eligible-for-data-residency).205Projects created with [data residency](https://help.openai.com/en/articles/9903489-data-residency-and-inference-residency-for-chatgpt) enabled can create a model provider to update the base_url with the [correct prefix](https://platform.openai.com/docs/guides/your-data#which-models-and-features-are-eligible-for-data-residency).

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

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

150| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |150| `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). |

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

152| `multi_agent` | true | Stable | Enable subagent collaboration tools |153| `multi_agent` | true | Stable | Enable subagent collaboration tools |

153| `personality` | true | Stable | Enable personality selection controls |154| `personality` | true | Stable | Enable personality selection controls |

166 167 

167Omit feature keys to keep their defaults.168Omit feature keys to keep their defaults.

168 169 

170For the current lifecycle hooks MVP, see [Hooks](https://developers.openai.com/codex/hooks).

171 

169### Enabling features172### Enabling features

170 173 

171- In `config.toml`, add `feature_name = true` under `[features]`.174- In `config.toml`, add `feature_name = true` under `[features]`.

24| `approval_policy.granular.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface. |24| `approval_policy.granular.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface. |

25| `approval_policy.granular.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are allowed to surface. |25| `approval_policy.granular.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are allowed to surface. |

26| `approval_policy.granular.skill_approval` | `boolean` | When `true`, skill-script approval prompts are allowed to surface. |26| `approval_policy.granular.skill_approval` | `boolean` | When `true`, skill-script approval prompts are allowed to surface. |

27| `approvals_reviewer` | `user | guardian_subagent` | Select who reviews eligible approval prompts. Defaults to `user`; `guardian_subagent` routes supported reviews through the Guardian reviewer subagent. |

27| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |28| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |

28| `apps._default.enabled` | `boolean` | Default app enabled state for all apps unless overridden per app. |29| `apps._default.enabled` | `boolean` | Default app enabled state for all apps unless overridden per app. |

29| `apps._default.open_world_enabled` | `boolean` | Default allow/deny for app tools with `open_world_hint = true`. |30| `apps._default.open_world_enabled` | `boolean` | Default allow/deny for app tools with `open_world_hint = true`. |

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

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

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

50| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` (under development; off by default). |

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

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

51| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default). |53| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default). |

90| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |92| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |

91| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |93| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |

92| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |94| `mcp_servers.<id>.url` | `string` | Endpoint for an MCP streamable HTTP server. |

93| `model` | `string` | Model to use (e.g., `gpt-5-codex`). |95| `model` | `string` | Model to use (e.g., `gpt-5.4`). |

94| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |96| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |

95| `model_catalog_json` | `string (path)` | Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile. |97| `model_catalog_json` | `string (path)` | Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile. |

96| `model_context_window` | `number` | Context window tokens available to the active model. |98| `model_context_window` | `number` | Context window tokens available to the active model. |

97| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |99| `model_instructions_file` | `string (path)` | Replacement for built-in instructions instead of `AGENTS.md`. |

98| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |100| `model_provider` | `string` | Provider id from `model_providers` (default: `openai`). |

101| `model_providers.<id>` | `table` | Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden. |

102| `model_providers.<id>.auth` | `table` | Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`. |

103| `model_providers.<id>.auth.args` | `array<string>` | Arguments passed to the token command. |

104| `model_providers.<id>.auth.command` | `string` | Command to run when Codex needs a bearer token. The command must print the token to stdout. |

105| `model_providers.<id>.auth.cwd` | `string (path)` | Working directory for the token command. |

106| `model_providers.<id>.auth.refresh_interval_ms` | `number` | How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry. |

107| `model_providers.<id>.auth.timeout_ms` | `number` | Maximum token command runtime in milliseconds (default: 5000). |

99| `model_providers.<id>.base_url` | `string` | API base URL for the model provider. |108| `model_providers.<id>.base_url` | `string` | API base URL for the model provider. |

100| `model_providers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables when present. |109| `model_providers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables when present. |

101| `model_providers.<id>.env_key` | `string` | Environment variable supplying the provider API key. |110| `model_providers.<id>.env_key` | `string` | Environment variable supplying the provider API key. |

144| `permissions.<name>.filesystem.":project_roots".<subpath>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself. |153| `permissions.<name>.filesystem.":project_roots".<subpath>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself. |

145| `permissions.<name>.filesystem.<path>` | `"read" | "write" | "none" | table` | Grant direct access for a path or special token, or scope nested entries under that root. |154| `permissions.<name>.filesystem.<path>` | `"read" | "write" | "none" | table` | Grant direct access for a path or special token, or scope nested entries under that root. |

146| `permissions.<name>.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |155| `permissions.<name>.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |

147| `permissions.<name>.network.allow_unix_sockets` | `array<string>` | Allowlist of Unix socket paths permitted through the managed proxy. |

148| `permissions.<name>.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |156| `permissions.<name>.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |

149| `permissions.<name>.network.allowed_domains` | `array<string>` | Allowlist of domains permitted through the managed proxy. |

150| `permissions.<name>.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |157| `permissions.<name>.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |

151| `permissions.<name>.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |158| `permissions.<name>.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |

152| `permissions.<name>.network.denied_domains` | `array<string>` | Denylist of domains blocked by the managed proxy. |159| `permissions.<name>.network.domains` | `map<string, allow | deny>` | Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values. |

153| `permissions.<name>.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener when this permissions profile enables the managed network proxy. |160| `permissions.<name>.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener when this permissions profile enables the managed network proxy. |

154| `permissions.<name>.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |161| `permissions.<name>.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |

155| `permissions.<name>.network.enabled` | `boolean` | Enable network access for this named permissions profile. |162| `permissions.<name>.network.enabled` | `boolean` | Enable network access for this named permissions profile. |

156| `permissions.<name>.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |163| `permissions.<name>.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |

157| `permissions.<name>.network.proxy_url` | `string` | HTTP proxy endpoint used when this permissions profile enables the managed network proxy. |164| `permissions.<name>.network.proxy_url` | `string` | HTTP proxy endpoint used when this permissions profile enables the managed network proxy. |

158| `permissions.<name>.network.socks_url` | `string` | SOCKS5 proxy endpoint used by this permissions profile. |165| `permissions.<name>.network.socks_url` | `string` | SOCKS5 proxy endpoint used by this permissions profile. |

166| `permissions.<name>.network.unix_sockets` | `map<string, allow | none>` | Unix socket rules for the managed proxy. Use socket paths as keys, with `allow` or `none` values. |

159| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |167| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |

160| `plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default. |168| `plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default. |

161| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |169| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |

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

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

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

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

198| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |207| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |

199| `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. |208| `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. |

200| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |209| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

205| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |214| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |

206| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |215| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |

207| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |216| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |

217| `tui.terminal_title` | `array<string> | null` | Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates. |

208| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |218| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |

209| `web_search` | `disabled | cached | live` | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. |219| `web_search` | `disabled | cached | live` | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. |

210| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |220| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

381 391 

382Key392Key

383 393 

394`approvals_reviewer`

395 

396Type / Values

397 

398`user | guardian_subagent`

399 

400Details

401 

402Select who reviews eligible approval prompts. Defaults to `user`; `guardian_subagent` routes supported reviews through the Guardian reviewer subagent.

403 

404Key

405 

384`apps._default.destructive_enabled`406`apps._default.destructive_enabled`

385 407 

386Type / Values408Type / Values

645 667 

646Key668Key

647 669 

670`features.codex_hooks`

671 

672Type / Values

673 

674`boolean`

675 

676Details

677 

678Enable lifecycle hooks loaded from `hooks.json` (under development; off by default).

679 

680Key

681 

648`features.enable_request_compression`682`features.enable_request_compression`

649 683 

650Type / Values684Type / Values

1181 1215 

1182Details1216Details

1183 1217 

1184Model to use (e.g., `gpt-5-codex`).1218Model to use (e.g., `gpt-5.4`).

1185 1219 

1186Key1220Key

1187 1221 

1245 1279 

1246Key1280Key

1247 1281 

1282`model_providers.<id>`

1283 

1284Type / Values

1285 

1286`table`

1287 

1288Details

1289 

1290Custom provider definition. Built-in provider IDs (`openai`, `ollama`, and `lmstudio`) are reserved and cannot be overridden.

1291 

1292Key

1293 

1294`model_providers.<id>.auth`

1295 

1296Type / Values

1297 

1298`table`

1299 

1300Details

1301 

1302Command-backed bearer token configuration for a custom provider. Do not combine with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.

1303 

1304Key

1305 

1306`model_providers.<id>.auth.args`

1307 

1308Type / Values

1309 

1310`array<string>`

1311 

1312Details

1313 

1314Arguments passed to the token command.

1315 

1316Key

1317 

1318`model_providers.<id>.auth.command`

1319 

1320Type / Values

1321 

1322`string`

1323 

1324Details

1325 

1326Command to run when Codex needs a bearer token. The command must print the token to stdout.

1327 

1328Key

1329 

1330`model_providers.<id>.auth.cwd`

1331 

1332Type / Values

1333 

1334`string (path)`

1335 

1336Details

1337 

1338Working directory for the token command.

1339 

1340Key

1341 

1342`model_providers.<id>.auth.refresh_interval_ms`

1343 

1344Type / Values

1345 

1346`number`

1347 

1348Details

1349 

1350How often Codex proactively refreshes the token in milliseconds (default: 300000). Set to `0` to refresh only after an authentication retry.

1351 

1352Key

1353 

1354`model_providers.<id>.auth.timeout_ms`

1355 

1356Type / Values

1357 

1358`number`

1359 

1360Details

1361 

1362Maximum token command runtime in milliseconds (default: 5000).

1363 

1364Key

1365 

1248`model_providers.<id>.base_url`1366`model_providers.<id>.base_url`

1249 1367 

1250Type / Values1368Type / Values

1821 1939 

1822Key1940Key

1823 1941 

1824`permissions.<name>.network.allow_unix_sockets`

1825 

1826Type / Values

1827 

1828`array<string>`

1829 

1830Details

1831 

1832Allowlist of Unix socket paths permitted through the managed proxy.

1833 

1834Key

1835 

1836`permissions.<name>.network.allow_upstream_proxy`1942`permissions.<name>.network.allow_upstream_proxy`

1837 1943 

1838Type / Values1944Type / Values

1845 1951 

1846Key1952Key

1847 1953 

1848`permissions.<name>.network.allowed_domains`

1849 

1850Type / Values

1851 

1852`array<string>`

1853 

1854Details

1855 

1856Allowlist of domains permitted through the managed proxy.

1857 

1858Key

1859 

1860`permissions.<name>.network.dangerously_allow_all_unix_sockets`1954`permissions.<name>.network.dangerously_allow_all_unix_sockets`

1861 1955 

1862Type / Values1956Type / Values

1881 1975 

1882Key1976Key

1883 1977 

1884`permissions.<name>.network.denied_domains`1978`permissions.<name>.network.domains`

1885 1979 

1886Type / Values1980Type / Values

1887 1981 

1888`array<string>`1982`map<string, allow | deny>`

1889 1983 

1890Details1984Details

1891 1985 

1892Denylist of domains blocked by the managed proxy.1986Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values.

1893 1987 

1894Key1988Key

1895 1989 

1965 2059 

1966Key2060Key

1967 2061 

2062`permissions.<name>.network.unix_sockets`

2063 

2064Type / Values

2065 

2066`map<string, allow | none>`

2067 

2068Details

2069 

2070Unix socket rules for the managed proxy. Use socket paths as keys, with `allow` or `none` values.

2071 

2072Key

2073 

1968`personality`2074`personality`

1969 2075 

1970Type / Values2076Type / Values

2433 2539 

2434Key2540Key

2435 2541 

2542`tool_suggest.discoverables`

2543 

2544Type / Values

2545 

2546`array<table>`

2547 

2548Details

2549 

2550Allow tool suggestions for additional discoverable connectors or plugins. Each entry uses `type = "connector"` or `"plugin"` and an `id`.

2551 

2552Key

2553 

2436`tools.view_image`2554`tools.view_image`

2437 2555 

2438Type / Values2556Type / Values

2553 2671 

2554Key2672Key

2555 2673 

2674`tui.terminal_title`

2675 

2676Type / Values

2677 

2678`array<string> | null`

2679 

2680Details

2681 

2682Ordered list of terminal window/tab title item identifiers. Defaults to `["spinner", "project"]`; `null` disables title updates.

2683 

2684Key

2685 

2556`tui.theme`2686`tui.theme`

2557 2687 

2558Type / Values2688Type / Values

2636| Key | Type / Values | Details |2766| Key | Type / Values | Details |

2637| --- | --- | --- |2767| --- | --- | --- |

2638| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`). |2768| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`). |

2769| `allowed_approvals_reviewers` | `array<string>` | Allowed values for `approvals_reviewer` (for example `user` and `guardian_subagent`). |

2639| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |2770| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |

2640| `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`. |2771| `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`. |

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

2666 2797 

2667Key2798Key

2668 2799 

2800`allowed_approvals_reviewers`

2801 

2802Type / Values

2803 

2804`array<string>`

2805 

2806Details

2807 

2808Allowed values for `approvals_reviewer` (for example `user` and `guardian_subagent`).

2809 

2810Key

2811 

2669`allowed_sandbox_modes`2812`allowed_sandbox_modes`

2670 2813 

2671Type / Values2814Type / Values

109# - never: never prompt (risky)109# - never: never prompt (risky)

110# - { granular = { ... } }: allow or auto-reject selected prompt categories110# - { granular = { ... } }: allow or auto-reject selected prompt categories

111approval_policy = "on-request"111approval_policy = "on-request"

112# Who reviews eligible approval prompts: user (default) | guardian_subagent

113# approvals_reviewer = "user"

114 

112# Example granular policy:115# Example granular policy:

113# approval_policy = { granular = {116# approval_policy = { granular = {

114# sandbox_approval = true,117# sandbox_approval = true,

127# - workspace-write130# - workspace-write

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

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

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

134# default_permissions = "workspace"

130 135 

131################################################################################136################################################################################

132# Authentication & Login137# Authentication & Login

274# Managed network proxy settings279# Managed network proxy settings

275################################################################################280################################################################################

276 281 

277[permissions.network]282# Set `default_permissions = "workspace"` before enabling this profile.

283# [permissions.workspace.network]

278# enabled = true284# enabled = true

279# proxy_url = "http://127.0.0.1:43128"285# proxy_url = "http://127.0.0.1:43128"

280# admin_url = "http://127.0.0.1:43129"286# admin_url = "http://127.0.0.1:43129"

286# dangerously_allow_non_loopback_admin = false292# dangerously_allow_non_loopback_admin = false

287# dangerously_allow_all_unix_sockets = false293# dangerously_allow_all_unix_sockets = false

288# mode = "limited" # limited | full294# mode = "limited" # limited | full

289# allowed_domains = ["api.openai.com"]

290# denied_domains = ["example.com"]

291# allow_unix_sockets = ["/var/run/docker.sock"]

292# allow_local_binding = false295# allow_local_binding = false

296#

297# [permissions.workspace.network.domains]

298# "api.openai.com" = "allow"

299# "example.com" = "deny"

300#

301# [permissions.workspace.network.unix_sockets]

302# "/var/run/docker.sock" = "allow"

293 303 

294################################################################################304################################################################################

295# History (table)305# History (table)

327# Set to [] to hide the footer.337# Set to [] to hide the footer.

328# status_line = ["model", "context-remaining", "git-branch"]338# status_line = ["model", "context-remaining", "git-branch"]

329 339 

340# Ordered list of terminal window/tab title item IDs. When unset, Codex uses:

341# ["spinner", "project"]. Set to [] to clear the title.

342# Available IDs include app-name, project, spinner, status, thread, git-branch, model,

343# and task-progress.

344# terminal_title = ["spinner", "project"]

345 

330# Syntax-highlighting theme (kebab-case). Use /theme in the TUI to preview and save.346# Syntax-highlighting theme (kebab-case). Use /theme in the TUI to preview and save.

331# You can also add custom .tmTheme files under $CODEX_HOME/themes.347# You can also add custom .tmTheme files under $CODEX_HOME/themes.

332# theme = "catppuccin-mocha"348# theme = "catppuccin-mocha"

350# hide_rate_limit_model_nudge = true366# hide_rate_limit_model_nudge = true

351# hide_gpt5_1_migration_prompt = true367# hide_gpt5_1_migration_prompt = true

352# "hide_gpt-5.1-codex-max_migration_prompt" = true368# "hide_gpt-5.1-codex-max_migration_prompt" = true

353# model_migrations = { "gpt-4.1" = "gpt-5.1" }369# model_migrations = { "gpt-5.3-codex" = "gpt-5.4" }

354 370 

355################################################################################371################################################################################

356# Centralized Feature Flags (preferred)372# Centralized Feature Flags (preferred)

360# Leave this table empty to accept defaults. Set explicit booleans to opt in/out.376# Leave this table empty to accept defaults. Set explicit booleans to opt in/out.

361# shell_tool = true377# shell_tool = true

362# apps = false378# apps = false

379# codex_hooks = false

363# unified_exec = true380# unified_exec = true

364# shell_snapshot = true381# shell_snapshot = true

365# multi_agent = true382# multi_agent = true

415# - openai432# - openai

416# - ollama433# - ollama

417# - lmstudio434# - lmstudio

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

418 436 

419[model_providers]437[model_providers]

420 438 

423# name = "OpenAI Data Residency"441# name = "OpenAI Data Residency"

424# base_url = "https://us.api.openai.com/v1" # example with 'us' domain prefix442# base_url = "https://us.api.openai.com/v1" # example with 'us' domain prefix

425# wire_api = "responses" # only supported value443# wire_api = "responses" # only supported value

426# # requires_openai_auth = true # built-in OpenAI defaults to true444# # requires_openai_auth = true # use only for providers backed by OpenAI auth

427# # request_max_retries = 4 # default 4; max 100445# # request_max_retries = 4 # default 4; max 100

428# # stream_max_retries = 5 # default 5; max 100446# # stream_max_retries = 5 # default 5; max 100

429# # stream_idle_timeout_ms = 300000 # default 300_000 (5m)447# # stream_idle_timeout_ms = 300000 # default 300_000 (5m)

442# env_key_instructions = "Set AZURE_OPENAI_API_KEY in your environment"460# env_key_instructions = "Set AZURE_OPENAI_API_KEY in your environment"

443# # supports_websockets = false461# # supports_websockets = false

444 462 

463# --- Example: command-backed bearer token auth ---

464# [model_providers.proxy]

465# name = "OpenAI using LLM proxy"

466# base_url = "https://proxy.example.com/v1"

467# wire_api = "responses"

468#

469# [model_providers.proxy.auth]

470# command = "/usr/local/bin/fetch-codex-token"

471# args = ["--audience", "codex"]

472# timeout_ms = 5000

473# refresh_interval_ms = 300000

474 

445# --- Example: Local OSS (e.g., Ollama-compatible) ---475# --- Example: Local OSS (e.g., Ollama-compatible) ---

446# [model_providers.ollama]476# [model_providers.local_ollama]

447# name = "Ollama"477# name = "Ollama"

448# base_url = "http://localhost:11434/v1"478# base_url = "http://localhost:11434/v1"

449# wire_api = "responses"479# wire_api = "responses"

470# enabled = false500# enabled = false

471# approval_mode = "approve"501# approval_mode = "approve"

472 502 

503# Optional tool suggestion allowlist for connectors or plugins Codex can offer to install.

504# [tool_suggest]

505# discoverables = [

506# { type = "connector", id = "gmail" },

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

508# ]

509 

473################################################################################510################################################################################

474# Profiles (named presets)511# Profiles (named presets)

475################################################################################512################################################################################

2 2 

3# Running Codex as an MCP server3# Running Codex as an MCP server

4 4 

5You can run Codex as an MCP server and connect it from other MCP clients (for example, an agent built with the [OpenAI Agents SDK](https://openai.github.io/openai-agents-js/guides/mcp/)).5You can run Codex as an MCP server and connect it from other MCP clients (for example, an agent built with the [OpenAI Agents SDK MCP integration](https://developers.openai.com/api/docs/guides/agents/integrations-observability#mcp)).

6 6 

7To start Codex as an MCP server, you can use the following command:7To start Codex as an MCP server, you can use the following command:

8 8 

1# Hooks

2 

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

4disabled.

5 

6Hooks are an extensibility framework for Codex. They allow

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

8 

9- Send the conversation to a custom logging/analytics engine

10- Scan your team's prompts to block accidentally pasting API keys

11- Summarize conversations to create persistent memories automatically

12- Run a custom validator when a conversation turn stops, enforcing standards

13- Customize prompting when in a certain directory

14 

15Hooks are behind a feature flag in `config.toml`:

16 

17```toml

18[features]

19codex_hooks = true

20```

21 

22Runtime behavior to keep in mind:

23 

24- Matching hooks from multiple files all run.

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

26 so one hook cannot prevent another matching hook from starting.

27- `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, and `Stop` run at turn

28 scope.

29- Hooks are currently disabled on Windows.

30 

31## Where Codex looks for hooks

32 

33Codex discovers `hooks.json` next to active config layers.

34 

35In practice, the two most useful locations are:

36 

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

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

39 

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

41Higher-precedence config layers do not replace lower-precedence hooks.

42 

43## Config shape

44 

45Hooks are organized in three levels:

46 

47- A hook event such as `PreToolUse`, `PostToolUse`, or `Stop`

48- A matcher group that decides when that event matches

49- One or more hook handlers that run when the matcher group matches

50 

51```json

52{

53 "hooks": {

54 "SessionStart": [

55 {

56 "matcher": "startup|resume",

57 "hooks": [

58 {

59 "type": "command",

60 "command": "python3 ~/.codex/hooks/session_start.py",

61 "statusMessage": "Loading session notes"

62 }

63 ]

64 }

65 ],

66 "PreToolUse": [

67 {

68 "matcher": "Bash",

69 "hooks": [

70 {

71 "type": "command",

72 "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py\"",

73 "statusMessage": "Checking Bash command"

74 }

75 ]

76 }

77 ],

78 "PostToolUse": [

79 {

80 "matcher": "Bash",

81 "hooks": [

82 {

83 "type": "command",

84 "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/post_tool_use_review.py\"",

85 "statusMessage": "Reviewing Bash output"

86 }

87 ]

88 }

89 ],

90 "UserPromptSubmit": [

91 {

92 "hooks": [

93 {

94 "type": "command",

95 "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/user_prompt_submit_data_flywheel.py\""

96 }

97 ]

98 }

99 ],

100 "Stop": [

101 {

102 "hooks": [

103 {

104 "type": "command",

105 "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/stop_continue.py\"",

106 "timeout": 30

107 }

108 ]

109 }

110 ]

111 }

112}

113```

114 

115Notes:

116 

117- `timeout` is in seconds.

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

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

120- `statusMessage` is optional.

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

122- For repo-local hooks, prefer resolving from the git root instead of using a

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

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

125 

126## Matcher patterns

127 

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

129`""`, or omit `matcher` entirely to match every occurrence of a supported

130event.

131 

132Only some current Codex events honor `matcher`:

133 

134| Event | What `matcher` filters | Notes |

135| --- | --- | --- |