security.md Codex Docs, 2026-02-19 20:53 UTC → 2026-03-07 00:33 UTC

1# Codex Security1# Codex Security

2 2 

3Codex helps protect your code and data and reduces the risk of misuse.3Codex Security helps engineering and security teams find, validate, and remediate likely vulnerabilities in connected GitHub repositories.

4 4 

5By 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.5This page covers Codex Security, the product that scans connected GitHub

6 repositories for likely security issues. For Codex sandboxing, approvals,

7 network controls, and admin settings, see [Agent approvals &

8 security](https://developers.openai.com/codex/agent-approvals-security).

6 9 

7## Sandbox and approvals10It helps teams:

8 11 

9Codex security controls come from two layers that work together:121. **Find likely vulnerabilities** by using a repo-specific threat model and real code context.

132. **Reduce noise** by validating findings before you review them.

143. **Move findings toward fixes** with ranked results, evidence, and suggested patch options.

10 15 

11- **Sandbox mode**: What Codex can do technically (for example, where it can write and whether it can reach the network) when it executes model-generated commands.16## How it works

12- **Approval policy**: When Codex must ask you before it executes an action (for example, leaving the sandbox, using the network, or running commands outside a trusted set).

13 17 

14Codex uses different sandbox modes depending on where you run it:18Codex Security scans connected repositories commit by commit.

19It builds scan context from your repo, checks likely vulnerabilities against that context, and validates high-signal issues in an isolated environment before surfacing them.

15 20 

16- **Codex cloud**: Runs in isolated OpenAI-managed containers, preventing access to your host system or unrelated data. You can expand access intentionally (for example, to install dependencies or allow specific domains) when needed. Network access is always enabled during the setup phase, which runs before the agent has access to your code.21You get a workflow focused on:

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

18 22 

19In the `Auto` preset (for example, `--full-auto`), Codex can read files, make edits, and run commands in the working directory automatically.23- repo-specific context instead of generic signatures

24- validation evidence that helps reduce false positives

25- suggested fixes you can review in GitHub

20 26 

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

22 28 

23Codex can also elicit approval for app (connector) tool calls that advertise side effects, even when the action isn’t a shell command or file change.29Codex Security works with connected GitHub repositories through Codex cloud. OpenAI manages access. If you need access or a repository isn’t visible, contact your OpenAI account team and confirm the repository is available through your Codex cloud workspace.

24 30 

25## Network access [Elevated Risk](https://help.openai.com/articles/20001061)31## Related docs

26 32 

27For Codex cloud, see [agent internet access](https://developers.openai.com/codex/cloud/internet-access) to enable full internet access or a domain allow list.33- [Codex Security setup](https://developers.openai.com/codex/security/setup) covers setup, scanning, and findings review.

28 34- [FAQ](https://developers.openai.com/codex/security/faq) covers common product questions.

29For the Codex app, CLI, or IDE Extension, the default `workspace-write` sandbox mode keeps network access turned off unless you enable it in your configuration:35- [Improving the threat model](https://developers.openai.com/codex/security/threat-model) explains how to tune scope, attack surface, and criticality assumptions.

30 

31```

32[sandbox_workspace_write]

33network_access = true

34```

35 

36You can also control the [web search tool](https://platform.openai.com/docs/guides/tools-web-search) without granting full network access to spawned commands. Codex defaults to using a web search cache to access results. 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](#common-sandbox-and-approval-combinations), web search defaults to live results. Use `--search` or set `web_search = "live"` to allow live browsing, or set it to `"disabled"` to turn the tool off:

37 

38```

39web_search = "cached" # default

40# web_search = "disabled"

41# web_search = "live" # same as --search

42```

43 

44Use caution when enabling network access or web search in Codex. Prompt injection can cause the agent to fetch and follow untrusted instructions.

45 

46## Defaults and recommendations

47 

48- On launch, Codex detects whether the folder is version-controlled and recommends:

49 - Version-controlled folders: `Auto` (workspace write + on-request approvals)

50 - Non-version-controlled folders: `read-only`

51- Depending on your setup, Codex may also start in `read-only` until you explicitly trust the working directory (for example, via an onboarding prompt or `/permissions`).

52- The workspace includes the current directory and temporary directories like `/tmp`. Use the `/status` command to see which directories are in the workspace.

53- To accept the defaults, run `codex`.

54- You can set these explicitly:

55 - `codex --sandbox workspace-write --ask-for-approval on-request`

56 - `codex --sandbox read-only --ask-for-approval on-request`

57 

58### Protected paths in writable roots

59 

60In the default `workspace-write` sandbox policy, writable roots still include protected paths:

61 

62- `<writable_root>/.git` is protected as read-only whether it appears as a directory or file.

63- If `<writable_root>/.git` is a pointer file (`gitdir: ...`), the resolved Git directory path is also protected as read-only.

64- `<writable_root>/.agents` is protected as read-only when it exists as a directory.

65- `<writable_root>/.codex` is protected as read-only when it exists as a directory.

66- Protection is recursive, so everything under those paths is read-only.

67 

68### Run without approval prompts

69 

70You can disable approval prompts with `--ask-for-approval never` or `-a never` (shorthand).

71 

72This option works with all `--sandbox` modes, so you still control Codex’s level of autonomy. Codex makes a best effort within the constraints you set.

73 

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

75 

76### Common sandbox and approval combinations

77 

78| Intent | Flags | Effect |

79| --- | --- | --- |

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

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

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

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

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

85 

86`--full-auto` is a convenience alias for `--sandbox workspace-write --ask-for-approval on-request`.

87 

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

89 

90#### Configuration in `config.toml`

91 

92```

93# Always ask for approval mode

94approval_policy = "untrusted"

95sandbox_mode = "read-only"

96 

97# Optional: Allow network in workspace-write mode

98[sandbox_workspace_write]

99network_access = true

100```

101 

102You can also save presets as profiles, then select them with `codex --profile <name>`:

103 

104```

105[profiles.full_auto]

106approval_policy = "on-request"

107sandbox_mode = "workspace-write"

108 

109[profiles.readonly_quiet]

110approval_policy = "never"

111sandbox_mode = "read-only"

112```

113 

114### Test the sandbox locally

115 

116To see what happens when a command runs under the Codex sandbox, use these Codex CLI commands:

117 

118```

119# macOS

120codex sandbox macos [--full-auto] [--log-denials] [COMMAND]...

121# Linux

122codex sandbox linux [--full-auto] [COMMAND]...

123```

124 

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

126 

127## OS-level sandbox

128 

129Codex enforces the sandbox differently depending on your OS:

130 

131- **macOS** uses Seatbelt policies and runs commands using `sandbox-exec` with a profile (`-p`) that corresponds to the `--sandbox` mode you selected.

132- **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`).

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

134 

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

136 

137```

138{

139 "chatgpt.runCodexInWindowsSubsystemForLinux": true

140}

141```

142 

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

144 

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

146 

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

148 

149In that case, configure your Docker container to provide the isolation you need, then run `codex` with `--sandbox danger-full-access` (or the `--dangerously-bypass-approvals-and-sandbox` flag) inside the container.

150 

151## Version control

152 

153Codex works best with a version control workflow:

154 

155- Work on a feature branch and keep `git status` clean before delegating. This keeps Codex patches easier to isolate and revert.

156- Prefer patch-based workflows (for example, `git diff`/`git apply`) over editing tracked files directly. Commit frequently so you can roll back in small increments.

157- Treat Codex suggestions like any other PR: run targeted verification, review diffs, and document decisions in commit messages for auditing.

158 

159## Monitoring and telemetry

160 

161Codex supports opt-in monitoring via OpenTelemetry (OTel) to help teams audit usage, investigate issues, and meet compliance requirements without weakening local security defaults. Telemetry is off by default; enable it explicitly in your configuration.

162 

163### Overview

164 

165- Codex turns off OTel export by default to keep local runs self-contained.

166- When enabled, Codex emits structured log events covering conversations, API requests, SSE/WebSocket stream activity, user prompts (redacted by default), tool approval decisions, and tool results.

167- Codex tags exported events with `service.name` (originator), CLI version, and an environment label to separate dev/staging/prod traffic.

168 

169### Enable OTel (opt-in)

170 

171Add an `[otel]` block to your Codex configuration (typically `~/.codex/config.toml`), choosing an exporter and whether to log prompt text.

172 

173```

174[otel]

175environment = "staging" # dev | staging | prod

176exporter = "none" # none | otlp-http | otlp-grpc

177log_user_prompt = false # redact prompt text unless policy allows

178```

179 

180- `exporter = "none"` leaves instrumentation active but doesn’t send data anywhere.

181- To send events to your own collector, pick one of:

182 

183```

184[otel]

185exporter = { otlp-http = {

186 endpoint = "https://otel.example.com/v1/logs",

187 protocol = "binary",

188 headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }

189}}

190```

191 

192```

193[otel]

194exporter = { otlp-grpc = {

195 endpoint = "https://otel.example.com:4317",

196 headers = { "x-otlp-meta" = "abc123" }

197}}

198```

199 

200Codex batches events and flushes them on shutdown. Codex exports only telemetry produced by its OTel module.

201 

202### Event categories

203 

204Representative event types include:

205 

206- `codex.conversation_starts` (model, reasoning settings, sandbox/approval policy)

207- `codex.api_request` (attempt, status/success, duration, and error details)

208- `codex.sse_event` (stream event kind, success/failure, duration, plus token counts on `response.completed`)

209- `codex.websocket_request` and `codex.websocket_event` (request duration plus per-message kind/success/error)

210- `codex.user_prompt` (length; content redacted unless explicitly enabled)

211- `codex.tool_decision` (approved/denied, source: configuration vs. user)

212- `codex.tool_result` (duration, success, output snippet)

213 

214Associated OTel metrics (counter plus duration histogram pairs) include `codex.api_request`, `codex.sse_event`, `codex.websocket.request`, `codex.websocket.event`, and `codex.tool.call` (with corresponding `.duration_ms` instruments).

215 

216For the full event catalog and configuration reference, see the [Codex configuration documentation on GitHub](https://github.com/openai/codex/blob/main/docs/config.md#otel).

217 

218### Security and privacy guidance

219 

220- Keep `log_user_prompt = false` unless policy explicitly permits storing prompt contents. Prompts can include source code and sensitive data.

221- Route telemetry only to collectors you control; apply retention limits and access controls aligned with your compliance requirements.

222- Treat tool arguments and outputs as sensitive. Favor redaction at the collector or SIEM when possible.

223- Review local data retention settings (for example, `history.persistence` / `history.max_bytes`) if you don’t want Codex to save session transcripts under `CODEX_HOME`. See [Advanced Config](https://developers.openai.com/codex/config-advanced#history-persistence) and [Configuration Reference](https://developers.openai.com/codex/config-reference).

224- If you run the CLI with network access turned off, OTel export can’t reach your collector. To export, allow network access in `workspace-write` mode for the OTel endpoint, or export from Codex cloud with the collector domain on your approved list.

225- Review events periodically for approval/sandbox changes and unexpected tool executions.

226 

227OTel is optional and designed to complement, not replace, the sandbox and approval protections described above.

228 

229## Managed configuration

230 

231Enterprise admins can control local Codex behavior in two ways:

232 

233- **Requirements**: admin-enforced constraints that users can’t override.

234- **Managed defaults**: starting values applied when Codex launches. Users can still change settings during a session; Codex reapplies managed defaults the next time it starts.

235 

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

237 

238Requirements constrain security-sensitive settings (approval policy, sandbox mode, web search mode, and optionally which MCP servers you can enable). If a user explicitly selects a disallowed value (via `config.toml`, CLI flags, profiles, or in-session UI), Codex rejects the change. If a value isn’t explicitly set and the default conflicts with requirements, Codex falls back to a requirements-compliant default. If you configure an `mcp_servers` approved list, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex turns it off.

239 

240#### Locations

241 

242- Linux/macOS (Unix): `/etc/codex/requirements.toml`

243- macOS MDM: preference domain `com.openai.codex`, key `requirements_toml_base64`

244 

245#### Cloud requirements (Business and Enterprise)

246 

247When you sign in with ChatGPT on a Business or Enterprise plan, Codex can also

248fetch admin-enforced requirements from the Codex service. This applies across

249Codex surfaces, including the TUI, `codex exec`, and `codex app-server`.

250 

251Cloud requirements are currently best-effort. If the fetch fails or times out,

252Codex continues without the cloud layer.

253 

254Requirements layer in this order (higher wins):

255 

256- macOS managed preferences (MDM; highest precedence)

257- Cloud requirements (ChatGPT Business or Enterprise)

258- `/etc/codex/requirements.toml`

259 

260Cloud requirements only fill unset requirement fields, so higher-precedence

261managed layers still win when both specify the same constraint.

262 

263For backwards compatibility, Codex also interprets legacy `managed_config.toml` fields `approval_policy` and `sandbox_mode` as requirements (allowing only that single value).

264 

265#### Example requirements.toml

266 

267This example blocks `--ask-for-approval never` and `--sandbox danger-full-access` (including `--yolo`):

268 

269```

270allowed_approval_policies = ["untrusted", "on-request"]

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

272```

273 

274You can also constrain web search mode:

275 

276```

277allowed_web_search_modes = ["cached"] # "disabled" remains implicitly allowed

278```

279 

280`allowed_web_search_modes = []` effectively allows only `"disabled"`.

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

282 

283#### Enforce command rules from requirements

284 

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

286using a `[rules]` table. These rules merge with regular `.rules` files, and the

287most restrictive decision still wins.

288 

289Unlike `.rules`, requirements rules must specify `decision`, and that decision

290must be `"prompt"` or `"forbidden"` (not `"allow"`).

291 

292```

293[rules]

294prefix_rules = [

295 { pattern = [{ token = "rm" }], decision = "forbidden", justification = "Use git clean -fd instead." },

296 { pattern = [{ token = "git" }, { any_of = ["push", "commit"] }], decision = "prompt", justification = "Require review before mutating history." },

297]

298```

299 

300To restrict which MCP servers Codex can enable, add an `mcp_servers` approved list. For stdio servers, match on `command`; for streamable HTTP servers, match on `url`:

301 

302```

303[mcp_servers.docs]

304identity = { command = "codex-mcp" }

305 

306[mcp_servers.remote]

307identity = { url = "https://example.com/mcp" }

308```

309 

310If `mcp_servers` is present but empty, Codex disables all MCP servers.

311 

312### Managed defaults (managed\_config.toml)

313 

314Managed defaults merge on top of a user’s local `config.toml` and take precedence over any CLI `--config` overrides, setting the starting values when Codex launches. Users can still change those settings during a session; Codex reapplies managed defaults the next time it starts.

315 

316Make sure your managed defaults meet your requirements; Codex rejects disallowed values.

317 

318#### Precedence and layering

319 

320Codex assembles the effective configuration in this order (top overrides bottom):

321 

322- Managed preferences (macOS MDM; highest precedence)

323- `managed_config.toml` (system/managed file)

324- `config.toml` (user’s base configuration)

325 

326CLI `--config key=value` overrides apply to the base, but managed layers override them. This means each run starts from the managed defaults even if you provide local flags.

327 

328Cloud requirements affect the requirements layer (not managed defaults). See

329[Admin-enforced requirements](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml)

330for their precedence.

331 

332#### Locations

333 

334- Linux/macOS (Unix): `/etc/codex/managed_config.toml`

335- Windows/non-Unix: `~/.codex/managed_config.toml`

336 

337If the file is missing, Codex skips the managed layer.

338 

339#### macOS managed preferences (MDM)

340 

341On macOS, admins can push a device profile that provides base64-encoded TOML payloads at:

342 

343- Preference domain: `com.openai.codex`

344- Keys:

345 - `config_toml_base64` (managed defaults)

346 - `requirements_toml_base64` (requirements)

347 

348Codex parses these “managed preferences” payloads as TOML and applies them with the highest precedence.

349 

350### MDM setup workflow

351 

352Codex honors standard macOS MDM payloads, so you can distribute settings with tooling like `Jamf Pro`, `Fleet`, or `Kandji`. A lightweight deployment looks like:

353 

3541. Build the managed payload TOML and encode it with `base64` (no wrapping).

3552. Drop the string into your MDM profile under the `com.openai.codex` domain at `config_toml_base64` (managed defaults) or `requirements_toml_base64` (requirements).

3563. Push the profile, then ask users to restart Codex and confirm the startup config summary reflects the managed values.

3574. When revoking or changing policy, update the managed payload; the CLI reads the refreshed preference the next time it launches.

358 

359Avoid embedding secrets or high-churn dynamic values in the payload. Treat the managed TOML like any other MDM setting under change control.

360 

361### Example managed\_config.toml

362 

363```

364# Set conservative defaults

365approval_policy = "on-request"

366sandbox_mode = "workspace-write"

367 

368[sandbox_workspace_write]

369network_access = false # keep network disabled unless explicitly allowed

370 

371[otel]

372environment = "prod"

373exporter = "otlp-http" # point at your collector

374log_user_prompt = false # keep prompts redacted

375# exporter details live under exporter tables; see Monitoring and telemetry above

376```

377 

378### Recommended guardrails

379 

380- Prefer `workspace-write` with approvals for most users; reserve full access for controlled containers.

381- Keep `network_access = false` unless your security review allows a collector or domains required by your workflows.

382- Use managed configuration to pin OTel settings (exporter, environment), but keep `log_user_prompt = false` unless your policy explicitly allows storing prompt contents.

383- Periodically audit diffs between local `config.toml` and managed policy to catch drift; managed layers should win over local flags and files.