Codex sandbox permission profiles: config.toml rules for secrets, domains and MCP servers
OpenAI's Inside the Codex sandbox post shows how permission profiles in config.toml control what Codex commands can read, write and reach. Copyable profiles for hiding secrets, allowlisting domains and sandboxing MCP servers, plus the gaps OpenAI admits.
OpenAI published a long engineering post on November 18, 2026, Inside the Codex sandbox by Michael Bolin, that explains how Codex limits the commands it runs on your machine and, more usefully, how to configure those limits yourself. The tool is permission profiles in config.toml: named sets of filesystem and network rules. The post also shows a codex sandbox command that applies the same rules to any program, including the MCP servers Codex does not sandbox on its own.
This guide pulls out the parts you can copy: the defaults, a profile that hides secrets, a domain allowlist, a sandboxed MCP server, and the gaps OpenAI itself points out.
Quick facts
- Where: permission profiles live under [permissions] in Codex's config.toml; default_permissions picks the one a session uses.
- Profiles whose names start with a colon are provided by Codex. The post walks through :workspace; :read-only and :danger-full-access appear in its network and admin examples.
- Filesystem rules take three values: read, write or deny. Network is off, fully on, or routed through a proxy with per-domain allow and deny rules.
- Platforms: macOS uses Seatbelt via /usr/bin/sandbox-exec; Linux uses bubblewrap plus seccomp-bpf; Windows is moving to Microsoft's MXC library.
- Child processes inherit the sandbox, including ones that outlive the original command.
- Not a VM or container: commands run in your normal environment, so native toolchains such as Xcode and the iOS simulator keep working.
What the default :workspace profile allows
With a Git repository as the workspace root, :workspace lets Codex write inside the workspace but keeps .git and .codex read-only, so it cannot edit .codex/config.toml or drop a Git hook into .git/hooks. Its rules also keep .agents and .aws under each workspace root read-only, and a profile that extends :workspace, like the dev example below, inherits them. Reads elsewhere on the disk are broadly allowed, subject to your normal OS permissions, because compilers and SDKs need them. Network access is off, which blocks uploads and exfiltration but also blocks npm install and similar downloads.
OpenAI is explicit about the trade-off: broad reads mean sensitive files elsewhere on the machine, such as config files with API keys, may still be readable. That is the first thing to tighten.
A profile that hides secrets
This is the post's dev example. It extends :workspace, adds one writable cache directory outside the repo, makes editor and devcontainer settings read-only, and denies .env files and a secrets folder in every workspace root:
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"Why .vscode read-only? The post's own attack example: a command that writes .vscode/settings.json to point Prettier at a malicious copy and enable format-on-save would run code outside the sandbox the next time you save a file. Under the dev profile, codex sandbox shows the write failing on macOS with Operation not permitted.
The CLI's workspace root is its working directory; the ChatGPT desktop app uses the project's source folders. Rules under :workspace_roots apply to every root.
Allowing only some domains
To let commands reach a few hosts, turn on the network for the profile, list domains, and enable the proxy feature. Without network_proxy = true from your config or managed requirements, the profile gets direct network access and the domain rules are not enforced, so do not skip that line:
[permissions.dev.network]
enabled = true
[permissions.dev.network.domains]
"*.openai.com" = "allow"
"localhost" = "allow"
"127.0.0.1" = "allow"
"::1" = "allow"
"evil.example" = "deny"
[features]
network_proxy = trueExplicit deny beats allow. Requests to other domains either need approval or are blocked; when approval is possible, Codex may ask you directly or route the request to auto-review. The proxy runs an HTTP and a SOCKS5 endpoint and only resolves a hostname after the rules allow it, because a DNS lookup alone can leak data encoded in the name. OpenAI notes that broad wildcards or access to DNS services can still allow DNS-based exfiltration.
A profile is not a hard lock for every command. For each command the model can ask for the default sandbox (use_default), for extra access inside the sandbox (with_additional_permissions), or to run outside it (require_escalated). The harness decides based on your settings, for example by asking you or routing to auto-review, before anything runs. The description field in a profile is what /permissions shows in the Codex CLI.
Sandboxing an MCP server
This step is easy to miss. Codex does not sandbox the command that starts a stdio MCP server, since it cannot guess what the server needs; a plain npx entry runs with your full user permissions. The fix is to wrap the server in codex sandbox with its own profile. OpenAI's example for the memory server:
[permissions.memory-mcp.filesystem]
":root" = "read"
"~/.npm" = "write"
"~/mcp-data" = "write"
[permissions.memory-mcp.network]
enabled = false
[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"Two setup steps come first, because the sandbox can write to the data folder but cannot create it, and the offline npx needs the package already cached:
mkdir -p ~/mcp-data
npx -y --package=@modelcontextprotocol/[email protected] -c trueThe same pattern works for testing any profile before you trust it: codex sandbox --permission-profile dev -- followed by the command you want to see blocked.
Team and enterprise limits
Codex merges config.toml files from several layers. Tables merge key by key and arrays are replaced whole, which is why profiles use tables: a team file can add one path or domain and inherit the rest of the organisation's base profile. Admins can go further with managed requirements in requirements.toml, for example allowed_permission_profiles with ":danger-full-access" = false. Cloud-provided requirements take precedence over /etc/codex/requirements.toml, and a profile that ends up false or absent in the merged table cannot be selected.
Known limits
- Writable paths can still lead outside the sandbox. OpenAI's example: the agent edits a package in node_modules, which Git usually ignores, and your editor later runs that copy outside the sandbox. The sandbox is one layer; OpenAI pairs it with training and alignment.
- On Linux, deny globs are expanded to concrete paths before each command starts. A matching file created later is not automatically covered for that command.
- On macOS, Seatbelt's sandbox-exec is marked deprecated by Apple and its profile language is undocumented; OpenAI says it will keep using it, as Chrome does.
- Some Linux distributions disable user namespaces by default, which bubblewrap depends on. Codex vendors its own bwrap but prefers a compatible one on PATH.
- Windows: the current sandbox needs admin setup and leaves ACLs, firewall rules and sandbox users on the host; OpenAI is replacing it with an MXC-based one on compatible devices.
Try it with your AI. Give this to Codex in a repository where you want tighter sandbox rules. It proposes a profile and tests it before anything is made the default.
Help me add a Codex permission profile for this repository.
1. First show me the relevant parts of my existing Codex config.toml, if any, and
explain how your change would merge with them. Do not change anything yet.
2. List paths in this repo that agent commands should never read, such as .env files and
[my secrets folder]. Do not open them; just list paths, and do not include template
files like .env.example unless I say so.
3. Propose a [permissions.dev] profile that extends ":workspace", marks .vscode and
.devcontainer read-only, and denies the paths from step 2 under ":workspace_roots".
If I need network for [package registry domains I name], set enabled = true under
[permissions.dev.network], add those domains under [permissions.dev.network.domains],
and set network_proxy = true under [features].
4. Show me the full TOML diff and wait for my confirmation before writing it. Back up
the current file first.
5. After I confirm, test with codex sandbox --permission-profile dev -- followed by a
command that tries to write .vscode/settings.json. Report only whether it was
blocked.
6. Only then ask whether to set default_permissions = "dev".
Do not delete files, do not print the contents of any secret file, and do not install
anything.FAQ
What is a Codex permission profile? A named set of filesystem and network rules in config.toml under [permissions]. Codex applies it to every command it runs in a session; default_permissions selects which one.
Does Codex sandbox MCP servers? Not stdio MCP servers started from config.toml. OpenAI recommends wrapping the server's command in codex sandbox --permission-profile <name> -- so it runs under a profile you define.
Can Codex still run a command outside the sandbox? Yes, if it asks with require_escalated and the request is approved, either by you or, depending on your settings, by auto-review.
How do I allow npm or pip downloads but block everything else? In the profile, set enabled = true under [permissions.<name>.network], add the registry domains you use with "allow" under [permissions.<name>.network.domains], and set network_proxy = true under [features]. OpenAI's post does not list specific registry domains, so check which hosts your package manager actually contacts. Requests to other domains then need approval or are blocked.
Is the Codex sandbox a container? No. It uses OS sandboxing (Seatbelt, bubblewrap and seccomp, or MXC) to constrain commands in your existing environment, so native tools keep working.
Related on claudefox
- External sandboxes for coding agents: run Claude Code, Codex and Pi commands in a Linux guest with npx or uvx
- BAMA: Claude Code and Codex skills that plan, design and build native macOS apps
- Kanzo puts a kanban board and an MCP server for coding agents in one 4.7 MB binary
- Floorplan: a Claude Code and Codex plugin that maps your codebase in plain English
Source: OpenAI: Inside the Codex sandbox
This story first appeared in the claudefox daily briefing for November 19, 2026.