OpenAI - Codex Docs Changes 2026-02-24 00:33 UTC → 2026-03-03 00:35 UTC

1# Codex app

2 

3The Codex app is a focused desktop experience for working on Codex threads in parallel, with built-in worktree support, automations, and Git functionality.

4 

5ChatGPT Plus, Pro, Business, Edu, and Enterprise plans include Codex. Learn more about [what’s included](https://developers.openai.com/codex/pricing).

6 

7![Codex app window with a project sidebar, active thread, and review pane](/images/codex/app/app-screenshot-light.webp)

8 

9## Getting started

10 

11The Codex app is available on macOS (Apple Silicon).

12 

131. Download and install the Codex app

14 

15 The Codex app is currently only available for macOS.

16 

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

18 

19 [Get notified for Windows and Linux](https://openai.com/form/codex-app/)

202. Open Codex and sign in

21 

22 Once you downloaded and installed the Codex app, open it and sign in with your ChatGPT account or an OpenAI API key.

23 

24 If you sign in with an OpenAI API key, some functionality such as [cloud threads](https://developers.openai.com/codex/prompting#threads) might not be available.

253. Select a project

26 

27 Choose a project folder that you want Codex to work in.

28 

29If you used the Codex app, CLI, or IDE Extension before you’ll see past projects that you worked on.

30 

314. Send your first message

32 

33 After choosing the project, make sure **Local** is selected to have Codex work on your machine and send your first message to Codex.

34 

35 You can ask Codex anything about the project or your computer in general. Here are some examples:

36 

37- Tell me about this project

38- Build a classic Snake game in this repo.

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

40 

41 If you need more inspiration, check out the [explore section](https://developers.openai.com/codex/explore).

42 

43---

44 

45## Work with the Codex app

46 

47[### Multitask across projects

48 

49Run multiple tasks in parallel and switch quickly between them.](https://developers.openai.com/codex/app/features#multitask-across-projects)[### Built-in Git tools

50 

51Review diffs, comment inline, stage or revert chunks, and commit without leaving the app.](https://developers.openai.com/codex/app/features#built-in-git-tools)[### Worktrees for parallel tasks

52 

53Isolate changes of multiple Codex threads using built-in Git worktree support.](https://developers.openai.com/codex/app/worktrees)[### Skills support

54 

55Give your Codex agent additional capabilities and reuse skills across App, CLI, and IDE Extension.](https://developers.openai.com/codex/app/features#skills-support)[### Automations

56 

57Pair skills with automations to automate recurring tasks in the background. Codex adds findings to the inbox, or automatically archives runs if there’s nothing to report.](https://developers.openai.com/codex/app/automations)[### Built-in terminal

58 

59Open a terminal per thread to test your changes, run dev servers, scripts, and custom commands.](https://developers.openai.com/codex/app/features#integrated-terminal)[### Local environments

60 

61Define worktree setup scripts and common project actions for easy access.](https://developers.openai.com/codex/app/local-environments)[### Sync with the IDE extension

62 

63Share Auto Context and active threads across app and IDE sessions.](https://developers.openai.com/codex/app/features#sync-with-the-ide-extension)[### MCP support

64 

65Connect your Codex agent to additional services using MCP.](https://developers.openai.com/codex/app/features#mcp-support)

66 

67---

68 

69Need help? Visit the [troubleshooting guide](https://developers.openai.com/codex/app/troubleshooting).

69 69 

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

71 71 

72#### Windows sandbox mode

73 

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

75 

76```toml

77[windows]

78sandbox = "elevated" # Recommended

79# sandbox = "unelevated" # Fallback if admin permissions/setup are unavailable

80```

81 

72#### Web search mode82#### Web search mode

73 83 

74Codex enables web search by default for local tasks and serves results from a web search cache. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](https://developers.openai.com/codex/security#common-sandbox-and-approval-combinations), web search defaults to live results. Choose a mode with `web_search`:84Codex enables web search by default for local tasks and serves results from a web search cache. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](https://developers.openai.com/codex/security#common-sandbox-and-approval-combinations), web search defaults to live results. Choose a mode with `web_search`:

140| `apply_patch_freeform` | false | Experimental | Include the freeform `apply_patch` tool |150| `apply_patch_freeform` | false | Experimental | Include the freeform `apply_patch` tool |

141| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |151| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |

142| `apps_mcp_gateway` | false | Experimental | Route Apps MCP calls through `https://api.openai.com/v1/connectors/mcp/` instead of legacy routing |152| `apps_mcp_gateway` | false | Experimental | Route Apps MCP calls through `https://api.openai.com/v1/connectors/mcp/` instead of legacy routing |

143| `elevated_windows_sandbox` | false | Experimental | Use the elevated Windows sandbox pipeline |

144| `collaboration_modes` | true | Stable | Enable collaboration modes such as plan mode |153| `collaboration_modes` | true | Stable | Enable collaboration modes such as plan mode |

145| `experimental_windows_sandbox` | false | Experimental | Use the Windows restricted-token sandbox |

146| `multi_agent` | false | Experimental | Enable multi-agent collaboration tools |154| `multi_agent` | false | Experimental | Enable multi-agent collaboration tools |

147| `personality` | true | Stable | Enable personality selection controls |155| `personality` | true | Stable | Enable personality selection controls |

148| `remote_models` | false | Experimental | Refresh remote model list before showing readiness |156| `remote_models` | false | Experimental | Refresh remote model list before showing readiness |

44| `features.apps_mcp_gateway` | `boolean` | Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental). |44| `features.apps_mcp_gateway` | `boolean` | Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental). |

45| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |45| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |

46| `features.collaboration_modes` | `boolean` | Enable collaboration modes such as plan mode (stable; on by default). |46| `features.collaboration_modes` | `boolean` | Enable collaboration modes such as plan mode (stable; on by default). |

47| `features.elevated_windows_sandbox` | `boolean` | Enable the elevated Windows sandbox pipeline (experimental). |

48| `features.experimental_windows_sandbox` | `boolean` | Run the Windows restricted-token sandbox (experimental). |

49| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default). |47| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default). |

50| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |48| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |

51| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |49| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |

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

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

180| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |178| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

179| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |

181 180 

182Key181Key

183 182 

589 588 

590Key589Key

591 590 

592`features.elevated_windows_sandbox`

593 

594Type / Values

595 

596`boolean`

597 

598Details

599 

600Enable the elevated Windows sandbox pipeline (experimental).

601 

602Key

603 

604`features.experimental_windows_sandbox`

605 

606Type / Values

607 

608`boolean`

609 

610Details

611 

612Run the Windows restricted-token sandbox (experimental).

613 

614Key

615 

616`features.multi_agent`591`features.multi_agent`

617 592 

618Type / Values593Type / Values

2195 2170 

2196Track Windows onboarding acknowledgement (Windows only).2171Track Windows onboarding acknowledgement (Windows only).

2197 2172 

2173Key

2174 

2175`windows.sandbox`

2176 

2177Type / Values

2178 

2179`unelevated | elevated`

2180 

2181Details

2182 

2183Windows-only native sandbox mode when running Codex natively on Windows.

2184 

2198Expand to view all2185Expand to view all

2199 2186 

2200You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).2187You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).

348# request_rule = true348# request_rule = true

349# collaboration_modes = true349# collaboration_modes = true

350# use_linux_sandbox_bwrap = false350# use_linux_sandbox_bwrap = false

351# experimental_windows_sandbox = false

352# elevated_windows_sandbox = false

353# remote_models = false351# remote_models = false

354# runtime_metrics = false352# runtime_metrics = false

355# powershell_utf8 = true353# powershell_utf8 = true

522# client-certificate = "/etc/codex/certs/client.pem"520# client-certificate = "/etc/codex/certs/client.pem"

523# client-private-key = "/etc/codex/certs/client-key.pem"521# client-private-key = "/etc/codex/certs/client-key.pem"

524```522```

523 

524################################################################################

525 

526# Windows

527 

528################################################################################

529 

530[windows]

531 

532# Native Windows sandbox mode (Windows only): unelevated | elevated

533 

534sandbox = "unelevated"

104 104 

105### Example agent roles105### Example agent roles

106 106 

107Below is an example that overrides the definitions for the built-in `default` and `explorer` agent roles and defines a new `reviewer` role.107The best role definitions are narrow and opinionated. Give each role one clear job, a tool surface that matches that job, and instructions that keep it from drifting into adjacent work.

108 108 

109Example `~/.codex/config.toml`:109#### Example 1: PR review team

110 

111This pattern splits review into three focused roles:

112 

113- `explorer` maps the codebase and gathers evidence.

114- `reviewer` looks for correctness, security, and test risks.

115- `docs_researcher` checks framework or API documentation through a dedicated MCP server.

116 

117Project config (`.codex/config.toml`):

110 118 

111```119```

112[agents.default]120[agents]

113description = "General-purpose helper."121max_threads = 6

122max_depth = 1

123 

124[agents.explorer]

125description = "Read-only codebase explorer for gathering evidence before changes are proposed."

126config_file = "agents/explorer.toml"

114 127 

115[agents.reviewer]128[agents.reviewer]

116description = "Find security, correctness, and test risks in code."129description = "PR reviewer focused on correctness, security, and missing tests."

117config_file = "agents/reviewer.toml"130config_file = "agents/reviewer.toml"

118 131 

119[agents.explorer]132[agents.docs_researcher]

120description = "Fast codebase explorer for read-heavy tasks."133description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."

121config_file = "agents/custom-explorer.toml"134config_file = "agents/docs-researcher.toml"

135```

136 

137`agents/explorer.toml`:

138 

139```

140model = "gpt-5.3-codex-spark"

141model_reasoning_effort = "medium"

142sandbox_mode = "read-only"

143developer_instructions = """

144Stay in exploration mode.

145Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.

146Prefer fast search and targeted file reads over broad scans.

147"""

122```148```

123 149 

124Example config file for the `reviewer` role (`~/.codex/agents/reviewer.toml`):150`agents/reviewer.toml`:

125 151 

126```152```

127model = "gpt-5.3-codex"153model = "gpt-5.3-codex"

128model_reasoning_effort = "high"154model_reasoning_effort = "high"

129developer_instructions = "Focus on high priority issues, write tests to validate hypothesis before flagging an issue. When finding security issues give concrete steps on how to reproduce the vulnerability."155sandbox_mode = "read-only"

156developer_instructions = """

157Review code like an owner.

158Prioritize correctness, security, behavior regressions, and missing test coverage.

159Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.

160"""

130```161```

131 162 

132Example config file for the `explorer` role (`~/.codex/agents/custom-explorer.toml`):163`agents/docs-researcher.toml`:

133 164 

134```165```

135model = "gpt-5.3-codex-spark"166model = "gpt-5.3-codex-spark"

136model_reasoning_effort = "medium"167model_reasoning_effort = "medium"

137sandbox_mode = "read-only"168sandbox_mode = "read-only"

169developer_instructions = """

170Use the docs MCP server to confirm APIs, options, and version-specific behavior.

171Return concise answers with links or exact references when available.

172Do not make code changes.

173"""

174 

175[mcp_servers.openaiDeveloperDocs]

176url = "https://developers.openai.com/mcp"

177```

178 

179This setup works well for prompts like:

180 

181```

182Review this branch against main. Have explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on.

183```

184 

185#### Example 2: frontend integration debugging team

186 

187This pattern is useful for UI regressions, flaky browser flows, or integration bugs that cross application code and the running product.

188 

189Project config (`.codex/config.toml`):

190 

191```

192[agents]

193max_threads = 6

194max_depth = 1

195 

196[agents.explorer]

197description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."

198config_file = "agents/explorer.toml"

199 

200[agents.browser_debugger]

201description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."

202config_file = "agents/browser-debugger.toml"

203 

204[agents.worker]

205description = "Implementation-focused agent for small, targeted fixes after the issue is understood."

206config_file = "agents/worker.toml"

207```

208 

209`agents/explorer.toml`:

210 

211```

212model = "gpt-5.3-codex-spark"

213model_reasoning_effort = "medium"

214sandbox_mode = "read-only"

215developer_instructions = """

216Map the code that owns the failing UI flow.

217Identify entry points, state transitions, and likely files before the worker starts editing.

218"""

219```

220 

221`agents/browser-debugger.toml`:

222 

223```

224model = "gpt-5.3-codex"

225model_reasoning_effort = "high"

226sandbox_mode = "workspace-write"

227developer_instructions = """

228Reproduce the issue in the browser, capture exact steps, and report what the UI actually does.

229Use browser tooling for screenshots, console output, and network evidence.

230Do not edit application code.

231"""

232 

233[mcp_servers.chrome_devtools]

234url = "http://localhost:3000/mcp"

235startup_timeout_sec = 20

236```

237 

238`agents/worker.toml`:

239 

240```

241model = "gpt-5.3-codex"

242model_reasoning_effort = "medium"

243developer_instructions = """

244Own the fix once the issue is reproduced.

245Make the smallest defensible change, keep unrelated files untouched, and validate only the behavior you changed.

246"""

247 

248[[skills.config]]

249path = "/Users/me/.agents/skills/docs-editor/SKILL.md"

250enabled = false

251```

252 

253This setup works well for prompts like:

254 

255```

256Investigate why the settings modal fails to save. Have browser_debugger reproduce it, explorer trace the responsible code path, and worker implement the smallest fix once the failure mode is clear.

138```257```

138 138 

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

140- **Linux** uses `Landlock` plus `seccomp` by default. You can opt into the alternative Linux sandbox pipeline with `features.use_linux_sandbox_bwrap = true` (or `-c use_linux_sandbox_bwrap=true`). In managed proxy mode, the bwrap pipeline routes egress through a proxy-only bridge and fails closed if it cannot build valid loopback proxy routes; landlock-only flows do not use that bridge behavior.140- **Linux** uses `Landlock` plus `seccomp` by default. You can opt into the alternative Linux sandbox pipeline with `features.use_linux_sandbox_bwrap = true` (or `-c use_linux_sandbox_bwrap=true`). In managed proxy mode, the bwrap pipeline routes egress through a proxy-only bridge and fails closed if it cannot build valid loopback proxy routes; landlock-only flows do not use that bridge behavior.

141- **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, you can enable an [experimental sandbox](https://developers.openai.com/codex/windows#windows-experimental-sandbox) implementation.141- **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.

142 142 

143If 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:143If 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:

144 144 

150 150 

151This ensures the IDE extension inherits Linux sandbox semantics for commands, approvals, and filesystem access even when the host OS is Windows. Learn more in the [Windows setup guide](https://developers.openai.com/codex/windows).151This ensures the IDE extension inherits Linux sandbox semantics for commands, approvals, and filesystem access even when the host OS is Windows. Learn more in the [Windows setup guide](https://developers.openai.com/codex/windows).

152 152 

153The native Windows sandbox is experimental and has important limitations. For example, it can’t prevent writes in directories where the `Everyone` SID already has write permissions (for example, world-writable folders). See the [Windows setup guide](https://developers.openai.com/codex/windows#windows-experimental-sandbox) for details and mitigation steps.153When running natively on Windows, configure the native sandbox mode in `config.toml`:

154 

155```

156[windows]

157sandbox = "unelevated" # or "elevated"

158```

159 

160See the [Windows setup guide](https://developers.openai.com/codex/windows#windows-sandbox) for details.

154 161 

155When you run Linux in a containerized environment such as Docker, the sandbox may not work if the host or container configuration doesn’t support the required `Landlock` and `seccomp` features.162When you run Linux in a containerized environment such as Docker, the sandbox may not work if the host or container configuration doesn’t support the required `Landlock` and `seccomp` features.

156 163 

2 2 

3The easiest way to use Codex on Windows is to [set up the IDE extension](https://developers.openai.com/codex/ide) or [install the CLI](https://developers.openai.com/codex/cli) and run it from PowerShell.3The easiest way to use Codex on Windows is to [set up the IDE extension](https://developers.openai.com/codex/ide) or [install the CLI](https://developers.openai.com/codex/cli) and run it from PowerShell.

4 4 

5When you run Codex natively on Windows, the agent mode uses an experimental Windows sandbox to block filesystem writes outside the working folder and prevent network access without your explicit approval. [Learn more below](#windows-experimental-sandbox).5When you run Codex natively on Windows, agent mode uses a [Windows sandbox](#windows-sandbox) to block filesystem writes outside the working folder and prevent network access without your explicit approval. [Learn more below](#windows-sandbox).

6 6 

7Instead, you can use [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) (WSL2). WSL2 gives you a Linux shell, Unix-style semantics, and tooling that match many tasks that models see in training.7If you prefer to have Codex use [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) (WSL2), [read the instructions](#windows-subsystem-for-linux) below.

8 

9## Windows sandbox

10 

11Native Windows sandbox support includes two modes that you can configure in `config.toml`:

12 

13```

14[windows]

15sandbox = "unelevated" # or "elevated"

16```

17 

18How `elevated` mode works:

19 

20- Uses a Restricted Token approach with filesystem ACLs to limit which files the sandbox can write to.

21- Runs commands as a dedicated Windows Sandbox User.

22- Limits network access by installing Windows Firewall rules.

23 

24### Grant sandbox read access

25 

26When a command fails because the Windows sandbox can't read a directory, use:

27 

28```text

29/sandbox-add-read-dir C:\absolute\directory\path

30```

31 

32The path must be an existing absolute directory. After the command succeeds, later commands that run in the sandbox can read that directory during the current session.

8 33 

9## Windows Subsystem for Linux34## Windows Subsystem for Linux

10 35 

81 ```106 ```

82- If you need Windows access to files, they’re under `\wsl$\Ubuntu\home<user>` in Explorer.107- If you need Windows access to files, they’re under `\wsl$\Ubuntu\home<user>` in Explorer.

83 108 

84## Windows experimental sandbox109## Troubleshooting and FAQ

85 

86The Windows sandbox support is experimental. How it works:

87 

88- Launches commands inside a restricted token derived from an AppContainer profile.

89- Grants only specifically requested filesystem capabilities by attaching capability security identifiers to that profile.

90- Disables outbound network access by overriding proxy-related environment variables and inserting stub executables for common network tools.

91 

92Its primary limitation is that it can’t prevent file writes, deletions, or creations in any directory where the Everyone SID already has write permissions (for example, world-writable folders). When using the Windows sandbox, Codex scans for folders where Everyone has write access and recommends that you remove that access.

93 

94### Grant sandbox read access

95 

96When a command fails because the Windows sandbox can't read a directory, use:

97 

98```text

99/sandbox-add-read-dir C:\absolute\directory\path

100```

101 

102The path must be an existing absolute directory. After the command succeeds, later commands that run in the sandbox can read that directory during the current session.

103 

104### Troubleshooting and FAQ

105 110 

106#### Installed extension, but it’s unresponsive111#### Installed extension, but it’s unresponsive

107 112