Agent approvals & security

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

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

For a high-level explanation of how sandboxing works across the Codex app, IDE extension, and CLI, see sandboxing. For a broader enterprise security overview, see the Codex security white paper.

Sandbox and approvals

Codex security controls come from two layers that work together:

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

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

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

In the Auto preset (for example, --full-auto), Codex can read files, make edits, and run commands in the working directory automatically.

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

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

Network access Elevated Risk

For Codex cloud, see agent internet access to enable full internet access or a domain allow list.

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

[sandbox_workspace_write]
network_access = true

You can also control the web search tool 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, 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:

web_search = "cached"  # default
# web_search = "disabled"
# web_search = "live"  # same as --search

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

Defaults and recommendations

• On launch, Codex detects whether the folder is version-controlled and recommends:
  • Version-controlled folders: Auto (workspace write + on-request approvals)
  • Non-version-controlled folders: read-only
• 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).
• The workspace includes the current directory and temporary directories like /tmp. Use the /status command to see which directories are in the workspace.
• To accept the defaults, run codex.
• You can set these explicitly:
  • codex --sandbox workspace-write --ask-for-approval on-request
  • codex --sandbox read-only --ask-for-approval on-request

Protected paths in writable roots

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

• <writable_root>/.git is protected as read-only whether it appears as a directory or file.
• If <writable_root>/.git is a pointer file (gitdir: ...), the resolved Git directory path is also protected as read-only.
• <writable_root>/.agents is protected as read-only when it exists as a directory.
• <writable_root>/.codex is protected as read-only when it exists as a directory.
• Protection is recursive, so everything under those paths is read-only.

Deny reads with filesystem profiles

Named permission profiles can also deny reads for exact paths or glob patterns. This is useful when a workspace should stay writable but specific sensitive files, such as local environment files, must stay unreadable:

default_permissions = "workspace"

[permissions.workspace.filesystem]
":project_roots" = { "." = "write", "**/*.env" = "none" }
glob_scan_max_depth = 3

Use "none" for paths or globs that Codex shouldn’t read. The sandbox policy evaluates globs for local macOS and Linux command execution. On platforms that pre-expand glob matches before the sandbox starts, set glob_scan_max_depth for unbounded ** patterns, or list explicit depths such as *.env, */*.env, and */*/*.env.

Run without approval prompts

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

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

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

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

Set approvals_reviewer = "guardian_subagent" to route eligible approval reviews through the Guardian reviewer subagent instead of prompting the user directly. Admin requirements can constrain this with allowed_approvals_reviewers.

Common sandbox and approval combinations

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

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

Configuration in config.toml

For the broader configuration workflow, see Config basics, Advanced Config, and the Configuration Reference.

# Always ask for approval mode
approval_policy = "untrusted"
sandbox_mode    = "read-only"
allow_login_shell = false # optional hardening: disallow login shells for shell-based tools

# Optional: Allow network in workspace-write mode
[sandbox_workspace_write]
network_access = true

# Optional: granular approval policy
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

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

[profiles.full_auto]
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

[profiles.readonly_quiet]
approval_policy = "never"
sandbox_mode    = "read-only"

Test the sandbox locally

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

# macOS
codex sandbox macos [--full-auto] [--log-denials] [COMMAND]...
# Linux
codex sandbox linux [--full-auto] [COMMAND]...

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

OS-level sandbox

Codex enforces the sandbox differently depending on your OS:

• 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.
• Linux uses bwrap plus seccomp by default.
• Windows uses the Linux sandbox implementation when running in Windows Subsystem for Linux 2 (WSL2). 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 implementation.

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

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

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

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

[windows]
sandbox = "unelevated" # or "elevated"
# sandbox_private_desktop = true  # default; set false only for compatibility

See the Windows setup guide for details.

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

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

Run Codex in Dev Containers

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

Use the Codex secure devcontainer example as a reference implementation. The example installs Codex, common development tools, bubblewrap, and firewall-based outbound controls.

The reference implementation includes:

• an Ubuntu 24.04 base image with Codex and common development tools installed;
• an allowlist-driven firewall profile for outbound access;
• VS Code settings and extension recommendations for reopening the workspace in a container;
• persistent mounts for command history and Codex configuration;
• bubblewrap, so Codex can still use its Linux sandbox when the container grants the needed capabilities.

To try it:

1. Install Visual Studio Code and the Dev Containers extension.
2. Copy the Codex example .devcontainer setup into your repository, or start from the Codex repository directly.
3. In VS Code, run Dev Containers: Open Folder in Container… and select .devcontainer/devcontainer.secure.json.
4. After the container starts, open a terminal and run codex.

You can also start the container from the CLI:

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

The example has three main pieces:

• .devcontainer/devcontainer.secure.json controls container settings, capabilities, mounts, environment variables, and VS Code extensions.
• .devcontainer/Dockerfile.secure defines the Ubuntu-based image and installed tools.
• .devcontainer/init-firewall.sh applies the outbound network policy.

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

Inside the container, choose one of these modes:

• Keep Codex’s Linux sandbox enabled if the Dev Container profile grants the capabilities needed for bwrap to create the inner sandbox.
• 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.

Version control

Codex works best with a version control workflow:

• Work on a feature branch and keep git status clean before delegating. This keeps Codex patches easier to isolate and revert.
• 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.
• Treat Codex suggestions like any other PR: run targeted verification, review diffs, and document decisions in commit messages for auditing.

Monitoring and telemetry

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

Overview

• Codex turns off OTel export by default to keep local runs self-contained.
• 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.
• Codex tags exported events with service.name (originator), CLI version, and an environment label to separate dev/staging/prod traffic.

Enable OTel (opt-in)

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

[otel]
environment = "staging"   # dev | staging | prod
exporter = "none"          # none | otlp-http | otlp-grpc
log_user_prompt = false     # redact prompt text unless policy allows

• exporter = "none" leaves instrumentation active but doesn’t send data anywhere.
• To send events to your own collector, pick one of:

[otel]
exporter = { otlp-http = {
  endpoint = "https://otel.example.com/v1/logs",
  protocol = "binary",
  headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}

[otel]
exporter = { otlp-grpc = {
  endpoint = "https://otel.example.com:4317",
  headers = { "x-otlp-meta" = "abc123" }
}}

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

Event categories

Representative event types include:

• codex.conversation_starts (model, reasoning settings, sandbox/approval policy)
• codex.api_request (attempt, status/success, duration, and error details)
• codex.sse_event (stream event kind, success/failure, duration, plus token counts on response.completed)
• codex.websocket_request and codex.websocket_event (request duration plus per-message kind/success/error)
• codex.user_prompt (length; content redacted unless explicitly enabled)
• codex.tool_decision (approved/denied, source: configuration vs. user)
• codex.tool_result (duration, success, output snippet)

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

For the full event catalog and configuration reference, see the Codex configuration documentation on GitHub.

Security and privacy guidance

• Keep log_user_prompt = false unless policy explicitly permits storing prompt contents. Prompts can include source code and sensitive data.
• Route telemetry only to collectors you control; apply retention limits and access controls aligned with your compliance requirements.
• Treat tool arguments and outputs as sensitive. Favor redaction at the collector or SIEM when possible.
• 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 and Configuration Reference.
• 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.
• Review events periodically for approval/sandbox changes and unexpected tool executions.

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

Managed configuration

Enterprise admins can configure Codex security settings for their workspace in Managed configuration. See that page for setup and policy details.