security.md Codex Docs, 2026-03-05 00:34 UTC → 2026-03-28 06:26 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. Uses a two-phase runtime model: setup runs before the agent phase and can access the network to install specified dependencies, then the agent phase runs offline by default unless you enable internet access for that environment. Secrets configured for cloud environments are available only during setup and are removed before the agent phase starts.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. Destructive app/MCP tool calls always require approval when the tool advertises a destructive annotation, even if it also advertises other hints (for example, read-only hints).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 

76For a middle ground, `approval_policy = { reject = { ... } }` lets you auto-reject specific approval prompt categories (sandbox escalation, execpolicy-rule prompts, or MCP elicitations) while keeping other prompts interactive.

77 

78### Common sandbox and approval combinations

79 

80| Intent | Flags | Effect |

81| --- | --- | --- |

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

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

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

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

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

87 

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

89 

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

91 

92#### Configuration in `config.toml`

93 

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

95 

96```

97# Always ask for approval mode

98approval_policy = "untrusted"

99sandbox_mode = "read-only"

100allow_login_shell = false # optional hardening: disallow login shells for shell-based tools

101 

102# Optional: Allow network in workspace-write mode

103[sandbox_workspace_write]

104network_access = true

105 

106# Optional: granular approval prompt auto-rejection

107# approval_policy = { reject = { sandbox_approval = true, rules = false, mcp_elicitations = false } }

108```

109 

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

111 

112```

113[profiles.full_auto]

114approval_policy = "on-request"

115sandbox_mode = "workspace-write"

116 

117[profiles.readonly_quiet]

118approval_policy = "never"

119sandbox_mode = "read-only"

120```

121 

122### Test the sandbox locally

123 

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

125 

126```

127# macOS

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

129# Linux

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

131```

132 

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

134 

135## OS-level sandbox

136 

137Codex enforces the sandbox differently depending on your OS:

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.

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, Codex uses a [Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox) implementation.

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:

144 

145```

146{

147 "chatgpt.runCodexInWindowsSubsystemForLinux": true

148}

149```

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

152 

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.

161 

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.

163 

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

165 

166## Version control

167 

168Codex works best with a version control workflow:

169 

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

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

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

173 

174## Monitoring and telemetry

175 

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

177 

178### Overview

179 

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

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

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

183 

184### Enable OTel (opt-in)

185 

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

187 

188```

189[otel]

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

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

192log_user_prompt = false # redact prompt text unless policy allows

193```

194 

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

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

197 

198```

199[otel]

200exporter = { otlp-http = {

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

202 protocol = "binary",

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

204}}

205```

206 

207```

208[otel]

209exporter = { otlp-grpc = {

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

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

212}}

213```

214 

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

216 

217### Event categories

218 

219Representative event types include:

220 

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

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

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

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

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

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

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

228 

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

230 

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

232 

233### Security and privacy guidance

234 

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

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

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

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

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

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

241 

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

243 

244## Managed configuration

245 

246Enterprise admins can configure Codex security settings for their workspace in [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration). See that page for setup and policy details.