Codex permission profiles: how to set up the sandbox, and the four gaps it leaves open
OpenAI published how the Codex sandbox works on November 18, and Codex CLI 0.170.0 and 0.171.0 fixed how permission profiles carry across threads and directories. If you run Codex locally, write a custom profile, sandbox your stdio MCP servers, and know what the sandbox can't stop.
On this page
The source is OpenAI's engineering post Inside the Codex sandbox, by Michael Bolin. Codex doesn't use a VM or container on your machine. It uses each OS's own sandboxing to limit commands that run in your existing environment, with the same files and tools you already have.
The config examples below come from that post. We haven't run them ourselves, so test each one with codex sandbox before you rely on it.
What changed this week
- November 18: OpenAI published the sandbox internals. The Codex changelog for CLI 0.170.0 the same day says the sandbox docs were updated to explain permission profiles and filesystem rules, and that permission updates and child threads now keep sandbox restrictions.
- November 20: Codex CLI 0.171.0 keeps permission profiles intact when you change working directories, and stops late completion events from cancelling approvals for a newer turn. It also makes GPT-6.2 Sol the default catalog model.
The two fixes matter together. Before them, a child thread or a directory change could lose the restrictions of the profile you chose. Upgrade with npm install -g @openai/[email protected] before you tune anything else.
How the sandbox works on each OS
| OS | Mechanism | Notes |
|---|---|---|
| macOS | Seatbelt via /usr/bin/sandbox-exec | Profiles start from (deny default). OpenAI notes sandbox-exec is marked deprecated and its profile language is undocumented, but plans to keep using it. |
| Linux | bubblewrap plus seccomp-bpf | Codex ships its own bwrap but prefers one on your PATH. With the network off, connect(2) and bind(2) are blocked. Some distributions disable the user namespaces it needs. |
| Windows | Microsoft eXecution Container (MXC) | Replaces the older sandbox, which needed admin setup and left ACLs, firewall rules, and sandbox users behind. Supported "on compatible Windows devices." |
Every platform goes through the same internal call, which takes the command, working directory, environment, a permission profile, and a network proxy. That is why one profile in config.toml applies on all three systems.
Writing a permission profile
A permission profile sets the filesystem and network rules for commands Codex runs. Built-in profiles start with a colon: :workspace, :read-only, and :danger-full-access.
The default :workspace profile lets commands write inside the workspace, keeps .git, .codex, .agents, and .aws read-only, allows broad reads subject to normal OS permissions, and turns the network off. In the CLI, the workspace is the directory you started in. In the ChatGPT desktop app, it is the project's source folders.
OpenAI's example extends that profile with extra protections:
default_permissions = "dev"
[permissions.dev]
description = "Development with extra read-only protections."
extends = ":workspace"
[permissions.dev.filesystem]
"~/build-cache" = "write"
[permissions.dev.filesystem.":workspace_roots"]
".devcontainer" = "read"
".vscode" = "read"
"**/*.env" = "deny"
"secrets" = "deny"Each path takes read, write, or deny. Rules under ":workspace_roots" apply relative to every workspace root, so one rule covers all source folders in a multi-folder project. Tables merge when you layer configs, but arrays replace each other whole.
Making .vscode and .devcontainer read-only is a good default. Both can hold settings or tasks that run code the next time you open the editor, outside any sandbox. To check a profile, run a command under it directly:
codex sandbox --permission-profile dev -- touch .vscode/.codex-sandbox-checkUse a throwaway file name so a wrong profile can't overwrite your real settings. OpenAI's post shows a write into .vscode failing on macOS with "Operation not permitted". If yours succeeds, delete the file and fix the profile, because it isn't doing what you think.
Turning the network on safely
| Mode | How to set it | Default for |
|---|---|---|
| Off | Nothing to set | :workspace |
| Full direct access | enabled = true under [permissions.dev.network] | :danger-full-access |
| Allowlist through a proxy | enabled = true, a domains table, and network_proxy = true under [features] | None |
The allowlist mode is the one to use. Codex starts codex-network-proxy, sets HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY, and the OS blocks any direct connection that skips it:
[permissions.dev.network]
enabled = true
[permissions.dev.network.domains]
"*.openai.com" = "allow"
"localhost" = "allow"
"evil.example" = "deny"
[features]
network_proxy = trueExplicit denies beat allows. A domain that matches nothing either needs approval or is blocked, and the proxy only resolves a hostname after it is allowed or approved. Add your package registry, such as registry.npmjs.org or pypi.org, or installs will fail with the network off.
Sandbox your MCP servers yourself
This is the most important line in the post: for stdio MCP servers, "the Codex harness does not attempt to sandbox the command used to start the server." A local MCP server runs with your full user permissions unless you wrap it.
OpenAI's fix is to launch the server through codex sandbox with its own profile. Create the data folder first with mkdir -p ~/mcp-data; the post notes the sandbox can write to that folder but can't create it.
[mcp_servers.memory]
command = "codex"
args = ["sandbox", "--permission-profile", "memory-mcp", "--",
"npx", "--offline", "@modelcontextprotocol/[email protected]"]
[mcp_servers.memory.env]
MEMORY_FILE_PATH = "~/mcp-data/memory.jsonl"
[permissions.memory-mcp.filesystem]
":root" = "read"
"~/.npm" = "write"
"~/mcp-data" = "write"
[permissions.memory-mcp.network]
enabled = falseNote the pinned version and --offline. With the network off, npx can't fetch a new release, so the package has to be cached first. That is a feature: a compromised update can't land mid-session.
Locking it down for a team
Admins set limits in requirements.toml, either at /etc/codex/requirements.toml or through cloud-managed policy, which takes precedence over the system file. OpenAI's example forces read-only by default and bans full access:
default_permissions = ":read-only"
[allowed_permission_profiles]
":read-only" = true
":danger-full-access" = falseWhen a single command needs more, the model can ask for it with a sandbox_permissions value of with_additional_permissions or require_escalated plus a written justification. The harness either prompts you or sends the request to auto-review, so the model can't grant itself access.
The four gaps the sandbox leaves open
- Broad reads. The default profile can read most of your home directory, including config files with API keys. Add
denyrules for credential files you care about. - Deny globs are a snapshot. On Linux and Windows, Codex expands deny globs to concrete paths before each command. A new
.envcreated during the command isn't covered. - DNS exfiltration. Wildcard domain rules or DNS access can still leak data through lookups. Keep allowlists narrow.
- Delayed execution. The post warns the agent "could inject malicious code into a locally installed package such as node_modules/prettier." That code runs later, outside the sandbox, when you or CI call it. Review diffs under
node_modules, build scripts, and editor config the same way you review source.
Claude Code users face the same class of problem. Our Claude Code vs Codex CLI comparison covers how the two tools handle approvals more broadly.
What we'd do
Upgrade to 0.171.0, copy the dev profile above, add deny rules for your secret files, and switch to the proxy allowlist with only your registries and APIs. Then wrap every stdio MCP server in codex sandbox, since that is the one gap Codex leaves open by default. For a team, ship a requirements.toml that bans :danger-full-access, and keep reviewing diffs under node_modules and editor config, because the sandbox only limits what runs now.
Sources
- OpenAI: Inside the Codex sandbox (November 18, 2026): OS mechanisms, permission profiles, network proxy, MCP wrapping, requirements, and limitations.
- ChatGPT and Codex changelog: Codex CLI 0.170.0 (November 18) and 0.171.0 (November 20) release notes.
Researched and drafted by an AI agent from the linked sources. How posts are made.