security.md Codex Docs, 2026-02-21 00:33 UTC → 2026-04-08 18:32 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 Web. 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 Web 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 

92For the broader configuration workflow, see [Config basics](https://developers.openai.com/codex/config-basic), [Advanced Config](https://developers.openai.com/codex/config-advanced#approval-policies-and-sandbox-modes), and the [Configuration Reference](https://developers.openai.com/codex/config-reference).

93 

94```

95# Always ask for approval mode

96approval_policy = "untrusted"

97sandbox_mode = "read-only"

98 

99# Optional: Allow network in workspace-write mode

100[sandbox_workspace_write]

101network_access = true

102```

103 

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

105 

106```

107[profiles.full_auto]

108approval_policy = "on-request"

109sandbox_mode = "workspace-write"

110 

111[profiles.readonly_quiet]

112approval_policy = "never"

113sandbox_mode = "read-only"

114```

115 

116### Test the sandbox locally

117 

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

119 

120```

121# macOS

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

123# Linux

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

125```

126 

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

128 

129## OS-level sandbox

130 

131Codex enforces the sandbox differently depending on your OS:

132 

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

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

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

136 

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

138 

139```

140{

141 "chatgpt.runCodexInWindowsSubsystemForLinux": true

142}

143```

144 

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

146 

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

148 

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

150 

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

152 

153## Version control

154 

155Codex works best with a version control workflow:

156 

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

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

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

160 

161## Monitoring and telemetry

162 

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

164 

165### Overview

166 

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

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

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

170 

171### Enable OTel (opt-in)

172 

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

174 

175```

176[otel]

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

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

179log_user_prompt = false # redact prompt text unless policy allows

180```

181 

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

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

184 

185```

186[otel]

187exporter = { otlp-http = {

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

189 protocol = "binary",

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

191}}

192```

193 

194```

195[otel]

196exporter = { otlp-grpc = {

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

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

199}}

200```

201 

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

203 

204### Event categories

205 

206Representative event types include:

207 

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

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

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

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

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

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

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

215 

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

217 

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

219 

220### Security and privacy guidance

221 

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

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

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

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

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

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

228 

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

230 

231## Managed configuration

232 

233Enterprise admins can control local Codex behavior in two ways. For the exact key list, see the [`requirements.toml` section in Configuration Reference](https://developers.openai.com/codex/config-reference#requirementstoml):

234 

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

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

237 

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

239 

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

241 

242#### Locations

243 

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

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

246 

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

248 

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

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

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

252 

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

254Codex continues without the cloud layer.

255 

256Requirements layer in this order (higher wins):

257 

258- macOS managed preferences (MDM; highest precedence)

259- Cloud requirements (ChatGPT Business or Enterprise)

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

261 

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

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

264 

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

266 

267#### Example requirements.toml

268 

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

270 

271```

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

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

274```

275 

276You can also constrain web search mode:

277 

278```

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

280```

281 

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

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

284 

285#### Enforce command rules from requirements

286 

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

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

289most restrictive decision still wins.

290 

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

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

293 

294```

295[rules]

296prefix_rules = [

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

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

299]

300```

301 

302To 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`:

303 

304```

305[mcp_servers.docs]

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

307 

308[mcp_servers.remote]

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

310```

311 

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

313 

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

315 

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

317 

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

319 

320#### Precedence and layering

321 

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

323 

324- Managed preferences (macOS MDM; highest precedence)

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

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

327 

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

329 

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

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

332for their precedence.

333 

334#### Locations

335 

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

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

338 

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

340 

341#### macOS managed preferences (MDM)

342 

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

344 

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

346- Keys:

347 - `config_toml_base64` (managed defaults)

348 - `requirements_toml_base64` (requirements)

349 

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

351 

352### MDM setup workflow

353 

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

355 

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

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

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

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

360 

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

362 

363### Example managed\_config.toml

364 

365```

366# Set conservative defaults

367approval_policy = "on-request"

368sandbox_mode = "workspace-write"

369 

370[sandbox_workspace_write]

371network_access = false # keep network disabled unless explicitly allowed

372 

373[otel]

374environment = "prod"

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

376log_user_prompt = false # keep prompts redacted

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

378```

379 

380### Recommended guardrails

381 

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

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

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

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