OpenAI - Codex Docs Changes 2026-04-08 00:40 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 

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 

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).

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

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. |

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 

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.

60sudo dnf install bubblewrap60sudo dnf install bubblewrap

61```61```

62 62 

63Codex uses the system `bwrap` at `/usr/bin/bwrap` when it is available. If it63Codex uses the first `bwrap` executable it finds on `PATH`. If no `bwrap`

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

65unprivileged user namespaces. Installing your distro’s `bubblewrap` package is65requires support for unprivileged user namespace creation. Installing the

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

67 67 

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

69namespaces. On distributions that restrict them with AppArmor, you can enable69can't create the needed user namespace. On distributions that restrict this

70them with:70AppArmor setting, you can enable it with:

71 71 

72```bash72```bash

73sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=073sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

99 99 

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

101 101 

102- `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

103 commands without approval.103 commands without approval.

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

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

110 110 

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

112 112 

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

114 set.114 set.

115- `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

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

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

118 118 

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

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

124If 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

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

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

127and 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.

128 134 

129When 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

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

127 127 

128## Custom model providers128## Custom model providers

129 129 

130A 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`.

131 131 

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

133 133 

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

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

142 142 

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

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

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

146 146 

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

159```159```

160 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 

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

162 179 

163Codex 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.

176env_key = "AZURE_OPENAI_API_KEY"193env_key = "AZURE_OPENAI_API_KEY"

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

178wire_api = "responses"195wire_api = "responses"

179 

180[model_providers.openai]

181request_max_retries = 4196request_max_retries = 4

182stream_max_retries = 10197stream_max_retries = 10

183stream_idle_timeout_ms = 300000198stream_idle_timeout_ms = 300000

184```199```

185 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 

186## ChatGPT customers using data residency203## ChatGPT customers using data residency

187 204 

188Projects 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).

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

97| `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. |

98| `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`. |

99| `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). |

100| `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. |

101| `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. |

102| `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. |

145| `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. |

146| `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. |

147| `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. |

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

149| `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. |

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

151| `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. |

152| `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. |

153| `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. |

154| `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. |

155| `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. |

156| `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. |

157| `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. |

158| `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. |

159| `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. |

160| `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`. |

161| `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. |

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

196| `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. |

197| `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. |

198| `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`. |

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

200| `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. |

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

206| `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. |

207| `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). |

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

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

210| `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. |

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

382 391 

383Key392Key

384 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 

385`apps._default.destructive_enabled`406`apps._default.destructive_enabled`

386 407 

387Type / Values408Type / Values

1258 1279 

1259Key1280Key

1260 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 

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

1262 1367 

1263Type / Values1368Type / Values

1834 1939 

1835Key1940Key

1836 1941 

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

1838 

1839Type / Values

1840 

1841`array<string>`

1842 

1843Details

1844 

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

1846 

1847Key

1848 

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

1850 1943 

1851Type / Values1944Type / Values

1858 1951 

1859Key1952Key

1860 1953 

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

1862 

1863Type / Values

1864 

1865`array<string>`

1866 

1867Details

1868 

1869Allowlist of domains permitted through the managed proxy.

1870 

1871Key

1872 

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

1874 1955 

1875Type / Values1956Type / Values

1894 1975 

1895Key1976Key

1896 1977 

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

1898 1979 

1899Type / Values1980Type / Values

1900 1981 

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

1902 1983 

1903Details1984Details

1904 1985 

1905Denylist 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.

1906 1987 

1907Key1988Key

1908 1989 

1978 2059 

1979Key2060Key

1980 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 

1981`personality`2074`personality`

1982 2075 

1983Type / Values2076Type / Values

2446 2539 

2447Key2540Key

2448 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 

2449`tools.view_image`2554`tools.view_image`

2450 2555 

2451Type / Values2556Type / Values

2566 2671 

2567Key2672Key

2568 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 

2569`tui.theme`2686`tui.theme`

2570 2687 

2571Type / Values2688Type / Values

2649| Key | Type / Values | Details |2766| Key | Type / Values | Details |

2650| --- | --- | --- |2767| --- | --- | --- |

2651| `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`). |

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

2653| `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`. |

2654| `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. |

2679 2797 

2680Key2798Key

2681 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 

2682`allowed_sandbox_modes`2812`allowed_sandbox_modes`

2683 2813 

2684Type / 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"

416# - openai432# - openai

417# - ollama433# - ollama

418# - lmstudio434# - lmstudio

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

419 436 

420[model_providers]437[model_providers]

421 438 

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

425# 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

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

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

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

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

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

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

444# # supports_websockets = false461# # supports_websockets = false

445 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 

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

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

448# name = "Ollama"477# name = "Ollama"

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

450# wire_api = "responses"479# wire_api = "responses"

471# enabled = false500# enabled = false

472# approval_mode = "approve"501# approval_mode = "approve"

473 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 

474################################################################################510################################################################################

475# Profiles (named presets)511# Profiles (named presets)

476################################################################################512################################################################################

225 225 

226### PreToolUse226### PreToolUse

227 227 

228Work in progress

229 

228Currently `PreToolUse` only supports Bash tool interception. The model can230Currently `PreToolUse` only supports Bash tool interception. The model can

229still work around this by writing its own script to disk and then running that231still work around this by writing its own script to disk and then running that

230script with Bash, so treat this as a useful guardrail rather than a complete232script with Bash, so treat this as a useful guardrail rather than a complete

231enforcement boundary.233enforcement boundary

234 

235This doesn't intercept all shell calls yet, only the simple ones. The newer

236 `unified_exec` mechanism allows richer streaming stdin/stdout handling of

237shell, but interception is incomplete. Similarly, this doesn’t intercept MCP,

238Write, WebSearch, or other non-shell tool calls.

232 239 

233`matcher` is applied to `tool_name`, which currently always equals `Bash`.240`matcher` is applied to `tool_name`, which currently always equals `Bash`.

234 241 

273 280 

274### PostToolUse281### PostToolUse

275 282 

283Work in progress

284 

276Currently `PostToolUse` only supports Bash tool results. It is not limited to285Currently `PostToolUse` only supports Bash tool results. It is not limited to

277commands that exit successfully: non-interactive `exec_command` calls can still286commands that exit successfully: non-interactive `exec_command` calls can still

278trigger `PostToolUse` when Codex emits a Bash post-tool payload. It cannot undo287trigger `PostToolUse` when Codex emits a Bash post-tool payload. It cannot undo

279side effects from the command that already ran.288side effects from the command that already ran.

280 289 

290This doesn't intercept all shell calls yet, only the simple ones. The newer

291 `unified_exec` mechanism allows richer streaming stdin/stdout handling of

292shell, but interception is incomplete. Similarly, this doesn’t intercept MCP,

293Write, WebSearch, or other non-shell tool calls.

294 

281`matcher` is applied to `tool_name`, which currently always equals `Bash`.295`matcher` is applied to `tool_name`, which currently always equals `Bash`.

282 296 

283Fields in addition to [Common input fields](#common-input-fields):297Fields in addition to [Common input fields](#common-input-fields):

17- [Download for JetBrains IDEs](#jetbrains-ide-integration)17- [Download for JetBrains IDEs](#jetbrains-ide-integration)

18 18 

19The Codex VS Code extension is available on macOS and Linux. Windows support19The Codex VS Code extension is available on macOS and Linux. Windows support

20is experimental. For the best Windows experience, use Codex in a WSL workspace20is experimental. For the best Windows experience, use Codex in a WSL2

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

22 22 

23After you install it, you'll find Codex in your editor sidebar.23After you install it, you'll find Codex in your editor sidebar.

24In VS Code, Codex opens in the right sidebar by default.24In VS Code, Codex opens in the right sidebar by default.

11 11 

12- Run as part of a pipeline (CI, pre-merge checks, scheduled jobs).12- Run as part of a pipeline (CI, pre-merge checks, scheduled jobs).

13- Produce output you can pipe into other tools (for example, to generate release notes or summaries).13- Produce output you can pipe into other tools (for example, to generate release notes or summaries).

14- Fit naturally into CLI workflows that chain command output into Codex and pass Codex output to other tools.

14- Run with explicit, pre-set sandbox and approval settings.15- Run with explicit, pre-set sandbox and approval settings.

15 16 

16## Basic usage17## Basic usage

33codex exec --ephemeral "triage this repository and suggest next steps"34codex exec --ephemeral "triage this repository and suggest next steps"

34```35```

35 36 

37If stdin is piped and you also provide a prompt argument, Codex treats the prompt as the instruction and the piped content as additional context.

38 

39This makes it easy to generate input with one command and hand it directly to Codex:

40 

41```bash

42curl -s https://jsonplaceholder.typicode.com/comments \

43 | codex exec "format the top 20 items into a markdown table" \

44 > table.md

45```

46 

47For more advanced stdin piping patterns, see [Advanced stdin piping](#advanced-stdin-piping).

48 

36## Permissions and safety49## Permissions and safety

37 50 

38By default, `codex exec` runs in a read-only sandbox. In automation, set the least permissions needed for the workflow:51By default, `codex exec` runs in a read-only sandbox. In automation, set the least permissions needed for the workflow:

235#### Alternative: Use the Codex GitHub Action248#### Alternative: Use the Codex GitHub Action

236 249 

237If you want to avoid installing the CLI yourself, you can run `codex exec` through the [Codex GitHub Action](https://developers.openai.com/codex/github-action) and pass the prompt as an input.250If you want to avoid installing the CLI yourself, you can run `codex exec` through the [Codex GitHub Action](https://developers.openai.com/codex/github-action) and pass the prompt as an input.

251 

252## Advanced stdin piping

253 

254When another command produces input for Codex, choose the stdin pattern based on where the instruction should come from. Use prompt-plus-stdin when you already know the instruction and want to pass piped output as context. Use `codex exec -` when stdin should become the full prompt.

255 

256### Use prompt-plus-stdin

257 

258Prompt-plus-stdin is useful when another command already produces the data you want Codex to inspect. In this mode, you write the instruction yourself and pipe in the output as context, which makes it a natural fit for CLI workflows built around command output, logs, and generated data.

259 

260```bash

261npm test 2>&1 \

262 | codex exec "summarize the failing tests and propose the smallest likely fix" \

263 | tee test-summary.md

264```

265 

266More prompt-plus-stdin examples

267 

268### Summarize logs

269 

270```bash

271tail -n 200 app.log \

272 | codex exec "identify the likely root cause, cite the most important errors, and suggest the next three debugging steps" \

273 > log-triage.md

274```

275 

276### Inspect TLS or HTTP issues

277 

278```bash

279curl -vv https://api.example.com/health 2>&1 \

280 | codex exec "explain the TLS or HTTP failure and suggest the most likely fix" \

281 > tls-debug.md

282```

283 

284### Prepare a Slack-ready update

285 

286```bash

287gh run view 123456 --log \

288 | codex exec "write a concise Slack-ready update on the CI failure, including the likely cause and next step" \

289 | pbcopy

290```

291 

292### Draft a pull request comment from CI logs

293 

294```bash

295gh run view 123456 --log \

296 | codex exec "summarize the failure in 5 bullets for the pull request thread" \

297 | gh pr comment 789 --body-file -

298```

299 

300### Use `codex exec -` when stdin is the prompt

301 

302If you omit the prompt argument, Codex reads the prompt from stdin. Use `codex exec -` when you want to force that behavior explicitly.

303 

304The `-` sentinel is useful when another command or script is generating the entire prompt dynamically. This is a good fit when you store prompts in files, assemble prompts with shell scripts, or combine live command output with instructions before handing the whole prompt to Codex.

305 

306```bash

307cat prompt.txt | codex exec -

308```

309 

310```bash

311printf "Summarize this error log in 3 bullets:\n\n%s\n" "$(tail -n 200 app.log)" \

312 | codex exec -

313```

314 

315```bash

316generate_prompt.sh | codex exec - --json > result.jsonl

317```

14 14 

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

16 16 

17 Need a different operating system?

18 

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

20 

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

182. Open Codex and sign in222. Open Codex and sign in

19 23 

35- Build a classic Snake game in this repo.39- Build a classic Snake game in this repo.

36- Find and fix bugs in my codebase with minimal, high-confidence changes.40- Find and fix bugs in my codebase with minimal, high-confidence changes.

37 41 

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

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

40 44 

41 [Learn more about the Codex app](https://developers.openai.com/codex/app)45 [Learn more about the Codex app](https://developers.openai.com/codex/app)

11 11 

12## TypeScript library12## TypeScript library

13 13 

14The TypeScript library provides a way to control Codex from within your application that is more comprehensive and flexible than non-interactive mode.14The TypeScript library provides a way to control Codex from within your application that's more comprehensive and flexible than non-interactive mode.

15 15 

16Use the library server-side; it requires Node.js 18 or later.16Use the library server-side; it requires Node.js 18 or later.

17 17 

57```57```

58 58 

59For more details, check out the [TypeScript repo](https://github.com/openai/codex/tree/main/sdk/typescript).59For more details, check out the [TypeScript repo](https://github.com/openai/codex/tree/main/sdk/typescript).

60 

61## Python library

62 

63The Python SDK is experimental and controls the local Codex app-server over JSON-RPC. It requires Python 3.10 or later and a local checkout of the open-source Codex repo.

64 

65### Installation

66 

67From the Codex repo root, install the SDK in editable mode:

68 

69```bash

70cd sdk/python

71python -m pip install -e .

72```

73 

74For manual local SDK usage, pass `AppServerConfig(codex_bin=...)` to point at a local `codex` binary, or use the repo examples and notebook bootstrap.

75 

76### Usage

77 

78Start Codex, create a thread, and run a prompt:

79 

80```python

81from codex_app_server import Codex

82 

83with Codex() as codex:

84 thread = codex.thread_start(model="gpt-5.4")

85 result = thread.run("Make a plan to diagnose and fix the CI failures")

86 print(result.final_response)

87```

88 

89Use `AsyncCodex` when your application is already asynchronous:

90 

91```python

92import asyncio

93 

94from codex_app_server import AsyncCodex

95 

96async def main() -> None:

97 async with AsyncCodex() as codex:

98 thread = await codex.thread_start(model="gpt-5.4")

99 result = await thread.run("Implement the plan")

100 print(result.final_response)

101 

102asyncio.run(main())

103```

104 

105For more details, check out the [Python repo](https://github.com/openai/codex/tree/main/sdk/python).

1# Create a CLI Codex can use | Codex use cases

2 

3Codex use cases

4 

5![](/assets/OpenAI-black-wordmark.svg)

6 

7![Codex](/assets/OAI_Codex-Lockup_Fallback_Black.svg)

8 

9Codex use case

10 

11# Create a CLI Codex can use

12 

13Give Codex a composable command for an API, log source, export, or team script.

14 

15Difficulty **Intermediate**

16 

17Time horizon **1h**

18 

19Ask Codex to create a composable CLI it can run from any folder, combine with repo scripts, use to download files, and remember through a companion skill.

20 

21## Best for

22 

23- Repeated work where Codex needs to search, read, download from, or safely write to the same service, export, local archive, or repo script.

24- Agent tools that need paged search, exact reads by ID, predictable JSON, downloaded files, local indexes, or draft-before-write commands.

25 

26# Contents

27 

28[← All use cases](https://developers.openai.com/codex/use-cases)

29 

30Copy page [Export as PDF](https://developers.openai.com/codex/use-cases/agent-friendly-clis/?export=pdf)

31 

32Ask Codex to create a composable CLI it can run from any folder, combine with repo scripts, use to download files, and remember through a companion skill.

33 

34Intermediate

35 

361h

37 

38Related links

39 

40[Codex skills](https://developers.openai.com/codex/skills) [Create custom skills](https://developers.openai.com/codex/skills/create-skill)

41 

42## Best for

43 

44- Repeated work where Codex needs to search, read, download from, or safely write to the same service, export, local archive, or repo script.

45- Agent tools that need paged search, exact reads by ID, predictable JSON, downloaded files, local indexes, or draft-before-write commands.

46 

47## Skills & Plugins

48 

49- [Cli Creator](https://github.com/openai/skills/tree/main/skills/.curated/cli-creator)

50 

51 Design the command surface, build the CLI, add setup and auth checks, install the command on PATH, and verify it from another folder.

52- [Skill Creator](https://github.com/openai/skills/tree/main/skills/.system/skill-creator)

53 

54 Create the companion skill that teaches later Codex tasks which CLI commands to run first and which write actions require approval.

55 

56| Skill | Why use it |

57| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |

58| [Cli Creator](https://github.com/openai/skills/tree/main/skills/.curated/cli-creator) | Design the command surface, build the CLI, add setup and auth checks, install the command on PATH, and verify it from another folder. |

59| [Skill Creator](https://github.com/openai/skills/tree/main/skills/.system/skill-creator) | Create the companion skill that teaches later Codex tasks which CLI commands to run first and which write actions require approval. |

60 

61## Starter prompt

62 

63Use $cli-creator to create a CLI you can use, and use $skill-creator to create the companion skill in this same thread.

64Source to learn from: [docs URL, OpenAPI spec, redacted curl command, existing script path, log folder, CSV or JSON export, SQLite database path, or pasted --help output].

65First job the CLI should support: [download failed CI logs from a build URL, search support tickets and read one by ID, query an admin API, read a local database, or run one step from an existing script].

66Optional write job: [create a draft comment, upload media, retry a failed job, or read-only for now].

67 Command name: [cli-name, or recommend one].

68Before coding, show me the proposed command surface and ask only for missing details that would block the build.

69 

70Use $cli-creator to create a CLI you can use, and use $skill-creator to create the companion skill in this same thread.

71Source to learn from: [docs URL, OpenAPI spec, redacted curl command, existing script path, log folder, CSV or JSON export, SQLite database path, or pasted --help output].

72First job the CLI should support: [download failed CI logs from a build URL, search support tickets and read one by ID, query an admin API, read a local database, or run one step from an existing script].

73Optional write job: [create a draft comment, upload media, retry a failed job, or read-only for now].

74 Command name: [cli-name, or recommend one].

75Before coding, show me the proposed command surface and ask only for missing details that would block the build.

76 

77## Introduction

78 

79When Codex keeps using the same API, log source, exported inbox, local database, or team script, give that work a composable interface: a command it can run from any folder, inspect, narrow, and combine with `git`, `gh`, `rg`, tests, and repo scripts.

80 

81Add a companion skill that records when Codex should use the CLI, what to run first, how to keep output small, where downloaded files land, and which write commands need approval.

82 

83In this workflow, `$cli-creator` helps Codex build the command. `$skill-creator` helps Codex save a reusable skill such as `$ci-logs`, which future tasks can invoke by name.

84 

85## How to use

86 

871. [Decide whether the job needs a CLI](#choose-what-the-cli-should-do)

882. [Share the source Codex should learn from](#share-the-docs-files-or-commands)

893. [Run `$cli-creator`](#ask-codex-to-build-the-cli-and-skill)

904. [Test the installed command](#verify-the-command-works-from-any-folder)

915. [Invoke the saved skill later](#use-the-skill-later)

92 

93## Choose what the CLI should do

94 

95Start with the thing you want Codex to do, not the technology you want it to write. A good CLI turns a repeated read, search, download, export, draft, upload, poll, or safe write into a command Codex can run from any repo.

96 

97| Situation | What Codex can do with the CLI |

98| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |

99| **CI logs live behind a build page.** | Take a build URL, download failed job logs to `./logs`, and return file paths plus short snippets. |

100| **Support tickets arrive as a weekly export.** | Index the newest CSV or JSON export, search by customer or phrase, and read one ticket by stable ID. |

101| **An API response is too large for context.** | List only the fields it needs, read the full object by ID, and export the complete response to a file. |

102| **A Slack export has long threads.** | Search with `--limit`, read one thread, and return nearby context instead of the whole archive. |

103| **A team script runs four different steps.** | Split setup, discovery, download, draft, upload, poll, and live write into separate commands. |

104| **A plugin finds the record, but Codex needs a file.** | Keep the plugin in the thread; use a CLI to download the attachment, trace, report, video, or log bundle and return the path. |

105 

106## Share the docs, files, or commands

107 

108Codex needs something concrete to learn from: docs or OpenAPI, a redacted curl command, an export or database path, a log folder, or an existing script. If you want the CLI to follow a familiar style, paste a short `--help` output from `gh`, `kubectl`, or your team's own tool.

109 

110If the command needs auth, tell Codex the environment variable name, config file path, or login flow it should support. Set the secret yourself in your shell or config file. Do not paste secrets into the thread. Ask Codex to make the CLI's setup check fail clearly when auth is missing.

111 

112## Ask Codex to build the CLI and skill

113