agent-approvals-security diff

agent-approvals-security.md +380 −0 added

Details

1# Agent approvals & security

3Codex helps protect your code and data and reduces the risk of misuse.

5This page covers how to operate Codex safely, including sandboxing, approvals,

6 and network access. If you are looking for Codex Security, the product for

7 scanning connected GitHub repositories, see [Codex Security](https://developers.openai.com/codex/security).

9By default, the agent runs with network access turned off. Locally, Codex uses an OS-enforced sandbox that limits what it can touch (typically to the current workspace), plus an approval policy that controls when it must stop and ask you before acting.

11For a high-level explanation of how sandboxing works across the Codex app, IDE

12extension, and CLI, see [sandboxing](https://developers.openai.com/codex/concepts/sandboxing).

13For a broader enterprise security overview, see the [Codex security white paper](https://trust.openai.com/?itemUid=382f924d-54f3-43a8-a9df-c39e6c959958&source=click).

15## Sandbox and approvals

17Codex security controls come from two layers that work together:

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

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

22Codex uses different sandbox modes depending on where you run it:

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

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

27In the `Auto` preset (for example, `--sandbox workspace-write --ask-for-approval on-request`), Codex can read files, make edits, and run commands in the working directory automatically.

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

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

33## Network access <ElevatedRiskBadge class="ml-2" />

35For Codex cloud, see [agent internet access](https://developers.openai.com/codex/cloud/internet-access) to enable full internet access or a domain allow list.

37For 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:

39```toml

40[sandbox_workspace_write]

41network_access = true

42```

44You 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:

46```toml

47web_search = "cached" # default

48# web_search = "disabled"

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

50```

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

54## Defaults and recommendations

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

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

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

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

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

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

62- You can set these explicitly:

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

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

66### Protected paths in writable roots

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

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

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

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

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

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

76### Deny reads with filesystem profiles

78Named permission profiles can also deny reads for exact paths or glob patterns.

79This is useful when a workspace should stay writable but specific sensitive

80files, such as local environment files, must stay unreadable:

82```toml

83default_permissions = "workspace"

85[permissions.workspace.filesystem]

86":project_roots" = { "." = "write", "**/*.env" = "none" }

87glob_scan_max_depth = 3

88```

90Use `"none"` for paths or globs that Codex shouldn't read. The sandbox policy

91evaluates globs for local macOS and Linux command execution. On platforms that

92pre-expand glob matches before the sandbox starts, set `glob_scan_max_depth` for

93unbounded `**` patterns, or list explicit depths such as `*.env`, `*/*.env`, and

94`*/*/*.env`.

96### Run without approval prompts

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

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

101

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

103

104For a middle ground, `approval_policy = { granular = { ... } }` lets you keep specific approval prompt categories interactive while automatically rejecting others. The granular policy covers sandbox approvals, execpolicy-rule prompts, MCP prompts, `request_permissions` prompts, and skill-script approvals.

105

106### Automatic approval reviews

107

108By default, approval requests route to you:

109

110```toml

111approvals_reviewer = "user"

112```

113

114Automatic approval reviews apply when approvals are interactive, such as

115`approval_policy = "on-request"` or a granular approval policy. Set

116`approvals_reviewer = "auto_review"` to route eligible approval requests

117through a reviewer agent before Codex runs the request:

118

119```toml

120approval_policy = "on-request"

121approvals_reviewer = "auto_review"

122```

123

124For the full reviewer lifecycle, trigger conditions, configuration precedence,

125and failure behavior, see

126[Auto-review](https://developers.openai.com/codex/concepts/sandboxing/auto-review).

127

128The reviewer evaluates only actions that already need approval, such as sandbox

129escalations, blocked network requests, `request_permissions` prompts, or

130side-effecting app and MCP tool calls. Actions that stay inside the sandbox

131continue without an extra review step.

132

133The reviewer policy checks for data exfiltration, credential probing, persistent

134security weakening, and destructive actions. Low-risk and medium-risk actions

135can proceed when policy allows them. The policy denies critical-risk actions.

136High-risk actions require enough user authorization and no matching deny rule.

137Prompt-build, review-session, and parse failures fail closed. Timeouts are

138surfaced separately, but the action still does not run.

139

140The [default reviewer policy](https://github.com/openai/codex/blob/main/codex-rs/core/src/guardian/policy.md)

141is in the open-source Codex repository. Enterprises can replace its

142tenant-specific section with `guardian_policy_config` in managed requirements.

143Local `[auto_review].policy` text is also supported, but managed requirements

144take precedence. For setup details, see

145[Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration#configure-automatic-review-policy).

146

147In the Codex app, these reviews appear as automatic review items with a status

148such as Reviewing, Approved, Denied, Aborted, or Timed out. They can also

149include a risk level and user-authorization assessment for the reviewed

150request.

151

152Automatic review uses extra model calls, so it can add to Codex usage. Admins

153can constrain it with `allowed_approvals_reviewers`.

154

155### Common sandbox and approval combinations

156

157| Intent | Flags / config | Effect |

158| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |

159| Auto (preset) | _no flags needed_ or `--sandbox workspace-write --ask-for-approval on-request` | Codex can read files, make edits, and run commands in the workspace. Codex requires approval to edit outside the workspace or to access network. |

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

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

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

163| Auto-review mode | `--sandbox workspace-write --ask-for-approval on-request -c approvals_reviewer=auto_review` or `approvals_reviewer = "auto_review"` | Same sandbox boundary as standard on-request mode, but eligible approval requests are reviewed by Auto-review instead of surfacing to the user. |

164| Dangerous full access | `--dangerously-bypass-approvals-and-sandbox` (alias: `--yolo`) | <ElevatedRiskBadge /> No sandbox; no approvals _(not recommended)_ |

165

166For non-interactive runs, use `codex exec --sandbox workspace-write`; Codex keeps older `codex exec --full-auto` invocations as a deprecated compatibility path and prints a warning.

167

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

169

170#### Configuration in `config.toml`

171

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

173

174```toml

175# Always ask for approval mode

176approval_policy = "untrusted"

177sandbox_mode = "read-only"

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

179

180# Optional: Allow network in workspace-write mode

181[sandbox_workspace_write]

182network_access = true

183

184# Optional: granular approval policy

185# approval_policy = { granular = {

186# sandbox_approval = true,

187# rules = true,

188# mcp_elicitations = true,

189# request_permissions = false,

190# skill_approval = false

191# } }

192```

193

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

195

196```toml

197[profiles.full_auto]

198approval_policy = "on-request"

199sandbox_mode = "workspace-write"

200

201[profiles.readonly_quiet]

202approval_policy = "never"

203sandbox_mode = "read-only"

204```

205

206### Test the sandbox locally

207

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

209

210```bash

211# macOS

212codex sandbox macos [--permissions-profile <name>] [--log-denials] [COMMAND]...

213# Linux

214codex sandbox linux [--permissions-profile <name>] [COMMAND]...

215# Windows

216codex sandbox windows [--permissions-profile <name>] [COMMAND]...

217```

218

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

220

221## OS-level sandbox

222

223Codex enforces the sandbox differently depending on your OS:

224

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

226- **Linux** uses `bwrap` plus `seccomp` by default.

227- **Windows** uses the Linux sandbox implementation when running in [Windows Subsystem for Linux 2 (WSL2)](https://developers.openai.com/codex/windows#windows-subsystem-for-linux). WSL1 was supported through Codex `0.114`; starting in `0.115`, the Linux sandbox moved to `bwrap`, so WSL1 is no longer supported. When running natively on Windows, Codex uses a [Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox) implementation.

228

229If you use the Codex IDE extension on Windows, it supports WSL2 directly. Set the following in your VS Code settings to keep the agent inside WSL2 whenever it's available:

230

231```json

232{

233 "chatgpt.runCodexInWindowsSubsystemForLinux": true

234}

235```

236

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

238

239When running natively on Windows, configure the native sandbox mode in `config.toml`:

240

241```toml

242[windows]

243sandbox = "unelevated" # or "elevated"

244# sandbox_private_desktop = true # default; set false only for compatibility

245```

246

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

248

249When you run Linux in a containerized environment such as Docker, the sandbox may not work if the host or container configuration blocks the namespace, setuid `bwrap`, or `seccomp` operations that Codex needs.

250

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

252

253### Run Codex in Dev Containers

254

255If your host cannot run the Linux sandbox directly, or if your organization already standardizes on containerized development, run Codex with Dev Containers and let Docker provide the outer isolation boundary. This works with Visual Studio Code Dev Containers and compatible tools.

256

257Use the [Codex secure devcontainer example](https://github.com/openai/codex/tree/main/.devcontainer) as a reference implementation. The example installs Codex, common development tools, `bubblewrap`, and firewall-based outbound controls.

258

259Devcontainers provide substantial protection, but they do not prevent every

260 attack. If you run Codex with `--sandbox danger-full-access` or

261 `--dangerously-bypass-approvals-and-sandbox` inside the container, a malicious

262 project can exfiltrate anything available inside the devcontainer, including

263 Codex credentials. Use this pattern only with trusted repositories, and

264 monitor Codex activity as you would in any other elevated environment.

265

266The reference implementation includes:

267

268- an Ubuntu 24.04 base image with Codex and common development tools installed;

269- an allowlist-driven firewall profile for outbound access;

270- VS Code settings and extension recommendations for reopening the workspace in a container;

271- persistent mounts for command history and Codex configuration;

272- `bubblewrap`, so Codex can still use its Linux sandbox when the container grants the needed capabilities.

273

274To try it:

275

2761. Install Visual Studio Code and the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).

2772. Copy the Codex example `.devcontainer` setup into your repository, or start from the Codex repository directly.

2783. In VS Code, run **Dev Containers: Open Folder in Container...** and select `.devcontainer/devcontainer.secure.json`.

2794. After the container starts, open a terminal and run `codex`.

280

281You can also start the container from the CLI:

282

283```bash

284devcontainer up --workspace-folder . --config .devcontainer/devcontainer.secure.json

285```

286

287The example has three main pieces:

288

289- `.devcontainer/devcontainer.secure.json` controls container settings, capabilities, mounts, environment variables, and VS Code extensions.

290- `.devcontainer/Dockerfile.secure` defines the Ubuntu-based image and installed tools.

291- `.devcontainer/init-firewall.sh` applies the outbound network policy.

292

293The reference firewall is intentionally a starting point. If you depend on domain allowlisting for isolation, implement DNS rebinding and DNS refresh protections that fit your environment, such as TTL-aware refreshes or a DNS-aware firewall.

294

295Inside the container, choose one of these modes:

296

297- Keep Codex's Linux sandbox enabled if the Dev Container profile grants the capabilities needed for `bwrap` to create the inner sandbox.

298- If the container is your intended security boundary, run Codex with `--sandbox danger-full-access` inside the container so Codex does not try to create a second sandbox layer.

299

300## Version control

301

302Codex works best with a version control workflow:

303

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

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

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

307

308## Monitoring and telemetry

309

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

311

312### Overview

313

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

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

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

317

318### Enable OTel (opt-in)

319

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

321

322```toml

323[otel]

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

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

326log_user_prompt = false # redact prompt text unless policy allows

327```

328

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

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

331

332```toml

333[otel]

334exporter = { otlp-http = {

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

336 protocol = "binary",

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

338}}

339```

340

341```toml

342[otel]

343exporter = { otlp-grpc = {

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

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

346}}

347```

348

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

350

351### Event categories

352

353Representative event types include:

354

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

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

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

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

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

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

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

362

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

364

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

366

367### Security and privacy guidance

368

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

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

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

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

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

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

375

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

377

378## Managed configuration

379

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

agent-approvals-security.md Codex Docs, 2026-03-04 06:20 UTC → 2026-05-12 01:59 UTC