DEV Community

Cover image for Codex Permission Profiles: config.toml Examples for Safe Agent Runs
Hassann
Hassann

Posted on Originally published at apidog.com

Codex Permission Profiles: config.toml Examples for Safe Agent Runs

Codex permission profiles are named policies in config.toml that decide what commands Codex runs on your machine can read, write and reach on the network. You pick one with default_permissions, start from a built-in (:read-only, :workspace or :danger-full-access), then add read, write and deny paths plus a domain allowlist.

Try Apidog today

This guide gives you copy-ready config.toml examples for the most common setups, including one for API work that lets your coding agent run Apidog CLI tests against your own API hosts without open internet.

What are Codex permission profiles?

A permission profile is a reusable sandbox policy for Codex. It combines filesystem rules (which paths commands can read, write or never touch) with network rules (whether commands can reach the network, and which domains). Codex enforces it with Seatbelt on macOS, bubblewrap plus seccomp on Linux and WSL, and MXC on Windows.

OpenAI explained the design in Inside the Codex sandbox, published November 18, 2026. Instead of moving your work into a container, Codex constrains commands in your existing environment, so native toolchains still run.

Codex ships three built-in profiles:

Profile Filesystem Network
:read-only Commands can read, not write Off
:workspace Writes inside workspace roots and temp dirs; .git, .agents, .codex, .aws stay read-only Off
:danger-full-access No local sandbox restrictions Full, direct

The permissions docs still label the feature Beta, so expect keys to shift between releases.

Where the permissions table goes in config.toml

Your profiles live in ~/.codex/config.toml (or a project or system layer). Two top-level pieces matter:

  • default_permissions names the profile Codex applies by default. It must match a built-in or a profile under [permissions].
  • [permissions.<name>] defines a profile. Give it a description; it shows up in the /permissions picker.

One rule trips people up. Permission profiles don’t compose with the older sandbox settings. If sandbox_mode appears in any loaded config file, or you pass --sandbox, Codex uses the old settings and ignores default_permissions. Remove sandbox_mode and [sandbox_workspace_write] before you switch.

Profiles follow the normal config precedence model. Tables merge recursively, so a team config can add one domain or one path to an organization’s profile without restating the whole thing.

Filesystem rules: read, write and deny

Each filesystem entry maps a path to read, write or deny. More specific paths win over broader ones, and when two entries target the same path, deny beats write, which beats read.

The path forms you’ll use most:

  • :minimal: the platform and runtime paths common tools need
  • :workspace_roots: the session’s workspace roots plus any roots the profile adds
  • :root, :tmpdir, :slash_tmp, absolute paths and ~/ paths

Use extends so you inherit the built-in safeguards instead of rebuilding them. Here’s a profile that keeps the :workspace defaults and locks down secrets:

default_permissions = "dev"

[permissions.dev]
description = "Workspace edits, secrets denied, no network."
extends = ":workspace"

[permissions.dev.filesystem]
"~/build-cache" = "write"

[permissions.dev.filesystem.":workspace_roots"]
".vscode" = "read"
"**/*.env" = "deny"
"secrets" = "deny"
Enter fullscreen mode Exit fullscreen mode

Rules under :workspace_roots apply to every root, so secrets means the secrets folder in each project root. A profile can extend :read-only, :workspace or another named profile. It can’t extend :danger-full-access.

On Linux, WSL and native Windows, an unbounded ** deny glob may need glob_scan_max_depth (at least 1) under [permissions.<name>.filesystem] so Codex can expand it before the sandbox starts.

Diagram of how a Codex permission profile filters filesystem paths and network requests before a command runs

Network rules: off, open or allowlisted

Network has three states, and two settings control them:

  1. Network off (enabled = false, the :workspace default): commands can’t reach the network.
  2. Network on, proxy off: commands get direct, unrestricted access. Your domain rules are ignored.
  3. Network on, proxy on: traffic goes through the Codex network proxy, which enforces the profile’s domain rules.

The second state is the trap. Setting permissions.<name>.network.enabled = true doesn’t start the proxy. You also need this at the top level:

[features]
network_proxy = true
Enter fullscreen mode Exit fullscreen mode

Domain patterns support exact hosts (api.example.com), *.example.com for subdomains only, **.example.com for the apex plus subdomains, and * as an allow-only global wildcard. Deny entries override allow entries, and an active proxy with no allow entries blocks everything external.

When the proxy is active, it also blocks local and private network targets by default. To reach a local service, allowlist the literal host, such as "localhost" = "allow" or "127.0.0.1" = "allow".

A Codex permission profile for API work

Here’s the profile we tested for API development. It edits code in the workspace, never reads .env files or a secrets folder, and can only reach your API host and Apidog:

default_permissions = "api-work"

[features]
network_proxy = true

[permissions.api-work]
description = "Workspace edits, no secrets, API hosts only."
extends = ":workspace"

[permissions.api-work.filesystem.":workspace_roots"]
"**/*.env" = "deny"
"secrets" = "deny"

[permissions.api-work.network]
enabled = true

[permissions.api-work.network.domains]
"api.your-company.com" = "allow"      # the API under test
"staging-api.your-company.com" = "allow"
"**.apidog.com" = "allow"             # Apidog CLI and its API
Enter fullscreen mode Exit fullscreen mode

Replace the two hosts with the ones your tests hit. Apidog CLI sends test requests from your machine to the API under test, so that host must be allowlisted, not only Apidog’s. If you test a local server, add "localhost" = "allow".

Install packages before the session, not inside it. Running npm install -g apidog-cli@latest needs registry.npmjs.org, which this profile blocks on purpose.

One gotcha from our test run: on a Mac running a proxy app or VPN in fake-IP DNS mode, every allowed host resolved to a 198.18.x.x address. The local/private guard treated those as private and blocked them, and Codex reported “local/private network addresses are blocked by the sandbox policy.” Adding allow_local_binding = true under [permissions.api-work.network] fixed it, but it also opens allowlisted hostnames that resolve to private addresses, so only set it when you need it.

Test the profile with codex sandbox

Don’t trust a profile until you’ve watched it block something. The codex sandbox command runs any command under a named profile and treats the current directory as a workspace root:

codex sandbox --permission-profile api-work -- cat README.md .env
Enter fullscreen mode Exit fullscreen mode

With the profile above, our run printed the README and then:

cat: .env: Operation not permitted
Enter fullscreen mode Exit fullscreen mode

A write outside the workspace failed the same way (Operation not permitted), while a new file inside the workspace was created. For the network, check that the proxy blocks a host you didn’t list:

codex sandbox -P api-work -- curl -sI https://example.org
Enter fullscreen mode Exit fullscreen mode

The proxy answered 403 Forbidden with x-proxy-error: blocked-by-allowlist, while apidog.com returned 200. On macOS, add --log-denials to print the Seatbelt denials after the command exits.

You can also use codex sandbox to wrap processes Codex doesn’t sandbox on its own. OpenAI’s post notes that stdio MCP servers in config.toml run unsandboxed, and shows a memory-mcp profile with "~/mcp-data" = "write" and network.enabled = false wrapping the server’s npx command.

Switch profiles mid-session with /permissions

In the Codex CLI, type /permissions to open the picker. When named profiles exist, it lists them with their descriptions. To select one directly:

/permissions api-work --approval-policy=on-request --reviewer=user
Enter fullscreen mode Exit fullscreen mode

That sets the profile for the current session and sends approval requests to you. Profiles and approvals are separate controls: the profile decides what a sandboxed command can touch, and the approval policy decides when Codex asks before stepping outside it. The CLI command reference lists the other session commands.

Let Codex test your API with Apidog CLI

With api-work active, Codex can run real API tests without open internet. Apidog CLI gives your agent commands for endpoints, test cases and runs, with JSON output it can read. You set it up once outside the sandbox:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install
Enter fullscreen mode Exit fullscreen mode

Then give Codex one prompt:

Using Apidog CLI, create a test case in project <projectId> for
GET /orders/{id} on endpoint <endpointId> that asserts a 200 status and
a non-empty "items" array. Run it against environment <envId> and
summarize any failures.
Enter fullscreen mode Exit fullscreen mode

Codex reads the payload schema, validates its JSON and runs the case:

apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog test-case run --project <projectId> --endpoint <endpointId> -e <envId> -r cli,json
Enter fullscreen mode Exit fullscreen mode

In our test, apidog auth status and apidog project list both ran inside the api-work sandbox with only **.apidog.com allowlisted. Your token stays in ~/.apidog, which the profile can read but not change. For a full walk-through, see how to use the Apidog CLI in Codex, and swap -r cli,json for -r junit when the same run moves into a CI pipeline. Apidog’s Free plan covers up to 4 users.

Flow diagram of Codex running Apidog CLI inside the api-work profile, with the network proxy allowing the API host and Apidog and blocking other domains

Limits to know before you trust a profile

Permission profiles shrink the blast radius. They don’t make an agent safe on their own. The docs and OpenAI’s post list these limits:

  • Broad reads stay on with :workspace. Compilers need SDKs and config outside the repo, so a config file elsewhere holding API keys may stay readable. Deny ~/.ssh and similar paths explicitly, or use ":root" = "deny" plus ":minimal" = "read".
  • Deny globs are a snapshot. On Linux, WSL and Windows, matches are expanded when each sandboxed process starts. A .env created later is readable by a long-running shell or dev server.
  • Wildcards can still leak through DNS. The proxy resolves a hostname only after it’s allowed, but broad wildcard rules or access to DNS services can still permit DNS-based exfiltration.
  • The proxy covers sandboxed commands only. Web search, connectors, MCP servers, the browser and Codex’s own model traffic use separate controls.
  • Writes can outlive the session. OpenAI’s example is a tampered node_modules/prettier that your editor later runs on save, outside the sandbox.

If you’ve used workarounds to bypass the Codex sandbox, a narrow custom profile is usually the cleaner fix. Teams that need policy across machines should read the Codex security cookbook and managed allowed_permission_profiles.

FAQ

What is the default Codex permission profile?

There isn’t one you should rely on. The docs say to set default_permissions explicitly for predictable behavior. For most coding work, :workspace is the sensible base: writes in workspace roots and temp directories, network off.

Why are my domain rules ignored?

Usually features.network_proxy is missing. With network.enabled = true and no proxy, commands get direct, unrestricted network access. Also check that no loaded config sets sandbox_mode, which disables profiles entirely.

How do I stop Codex from reading .env files?

Add "**/*.env" = "deny" under [permissions.<name>.filesystem.":workspace_roots"]. On Linux, WSL and Windows, set glob_scan_max_depth for unbounded ** patterns, and remember new matches aren’t added to processes that are already running.

Can I allow localhost in a Codex permission profile?

Yes. Allowlist the literal host, such as "localhost" = "allow" or "127.0.0.1" = "allow". Set allow_local_binding = true only when an allowlisted hostname resolves to a local or private address.

Do permission profiles sandbox MCP servers?

No. Stdio MCP servers in config.toml start unsandboxed. Wrap the server command in codex sandbox --permission-profile <name> -- with its own profile.

Can I use profiles with the --sandbox flag?

No. Passing --sandbox or setting sandbox_mode makes Codex use the older sandbox settings instead of default_permissions. Pick one system per session.

Top comments (0)