Codex CLI Config Generator

Codex CLI config generator: get approval_policy and sandbox_mode right in config.toml

OpenAI's Codex CLI keeps almost everything in one TOML file at ~/.codex/config.toml — model, reasoning effort, how much it may do without asking, how tightly the filesystem is locked down, and every MCP server. This generator writes that file for you and, on a second tab, an AGENTS.md for the repository you are working in. Both update live as you change the form, entirely in your browser: nothing is sent anywhere, because the whole thing is a client-side component with no network calls in the generation path.

TOML is the reason a generator earns its keep here. The values are exact strings with hyphens in them — on-failure, workspace-write, danger-full-access — and a typo does not produce an error message so much as a policy you did not intend. Picking from segmented buttons removes that class of mistake entirely.

Installing the CLI first

The generator shows the install commands at the top of the tool, each with its own copy button, because the config file is useless until the binary exists. Three routes are offered:

Whichever you pick, the config file lands in the same place. Run the CLI once before writing the file so it creates ~/.codex for you, or create the directory by hand.

What the config.toml tab writes

Four top-level keys are always emitted, followed by one [mcp_servers.NAME] table for each server you tick:

Unlike some config generators, this one writes all four unconditionally rather than omitting defaults. That is the right call for TOML: a file that states its posture explicitly is one you can read in a code review and know exactly what the agent is permitted to do, without having to remember what the CLI falls back to.

Approvals and the sandbox are two different questions

This is the concept that trips people up, and it is worth being precise. approval_policy decides when Codex stops and asks you. sandbox_mode decides what it is physically able to do when it does not ask. They are orthogonal, and the combination is what actually determines your risk.

The approval options:

• untrusted — ask before anything that is not already trusted. The most conservative posture; expect frequent prompts.
• on-failure — let it run inside the sandbox, and only surface a prompt when a sandboxed run fails. Useful when the sandbox is doing the real containment work and you only want to be involved on escalation.
• on-request — the model decides when it needs permission and asks for it. The tool's default, and the usual day-to-day setting.
• never — no prompts at all. Only defensible when paired with a restrictive sandbox_mode; the two are a pair, not alternatives.

The sandbox options:

• read-only — Codex can read and reason but cannot write. Good for review, audit and exploration tasks.
• workspace-write — writes are confined to the workspace. The default, and the setting most real work happens under.
• danger-full-access — no sandbox. The option's own hint in the tool says "trusted only", and that is the whole of the advice.

The combination to think hardest about is approval_policy = "never" with sandbox_mode = "danger-full-access": no prompts and no containment, on your real filesystem. Nothing stops you selecting it, and there are legitimate uses inside a throwaway container, but it should be a decision rather than a leftover.

Reasoning effort, including the one that is not always available

model_reasoning_effort trades latency and cost against depth. The five levels run minimal, low, medium, high, xhigh. The top level carries a note in the tool itself: xhigh applies to the codex-max and 5.2 models. Set it against a model that does not support it and you are relying on the CLI to fall back gracefully — if a run behaves oddly after you raise effort, that pairing is the first thing to check.

Model choice interacts with this. gpt-5.1-codex-mini is labelled "cheap" in the picker and is the sensible target for high-volume, low-stakes work; pairing it with high effort mostly spends the savings you chose it for. The -codex variants are the coding-tuned line; gpt-5.2 and gpt-5.1 are the general models, available here if you prefer their behaviour on prose-heavy or analysis-heavy tasks.

Worked example: a config.toml for daily work

Pick gpt-5.1-codex-max, high effort, on-failure approvals, workspace-write sandbox, and tick the GitHub MCP server. The output is:

model = "gpt-5.1-codex-max"
model_reasoning_effort = "high"
approval_policy = "on-failure"
sandbox_mode = "workspace-write"

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "${GITHUB_TOKEN}" }

That reads as: use the deepest coding model at high effort, let it work inside the workspace without interrupting me, and only ask if something fails — with GitHub access wired in through a token that lives in my shell rather than in this file.

MCP servers live in the same file

Codex does not use a separate MCP file. Each server becomes a TOML table named [mcp_servers.<id>] appended to the bottom of config.toml, with command, args, and an optional inline env table. The generator knows five: Filesystem, GitHub, Context7, Playwright and Postgres. All five launch over stdio via npx -y, so they resolve on demand with no separate install step.

Two carry values you should edit before trusting them. Filesystem is generated scoped to ., the current directory — change that argument if you want it pointed somewhere specific. Postgres is generated with the placeholder connection string postgresql://localhost/mydb, which will simply fail to connect until you replace it. GitHub is the only one with an env table, and it references ${GITHUB_TOKEN} rather than embedding a token, which is what keeps the file safe to check into a dotfiles repository.

Because these tables append after the four scalar keys, TOML's ordering rule is satisfied automatically: bare key/value pairs must precede any table header. If you hand-edit the file later, keep new top-level keys above the first [mcp_servers.*] line or the parser will read them as part of that table.

AGENTS.md: the context file Codex reads

The second tab writes AGENTS.md to your repository root. The name matters — Codex reads AGENTS.md, not CLAUDE.md and not GEMINI.md, and a correctly written context file under the wrong filename is simply invisible. AGENTS.md is also the cross-tool convention several agents have converged on, so it is the one context file with a reasonable chance of being read by more than one agent in the same repo.

The deterministic template is built from four fields — project name, primary stack, package manager and test command — and produces a Project block, a Commands block with install, dev, test, build and lint derived from your package manager, a short Conventions section, and Guardrails covering secrets and destructive actions. The package-manager control is hidden for stacks where it is meaningless, appearing only for Node.js, Next.js and "Other". An empty test command falls back to <pm> test.

That tab is also the only place in the tool where a language model is involved. A collapsed panel below the file lets you describe your project in plain English and have a small model rewrite AGENTS.md around those specifics. It runs in your browser over WebGPU using a compact model such as Qwen2.5 1.5B or Llama 3.2 1B, downloads nothing until you open the panel and ask, and your description never leaves the machine. The config.toml tab has no AI involvement whatsoever — it is pure string assembly, which is exactly what you want from a file that encodes a security posture.

Things that go wrong

• The file is in the wrong place. It belongs at ~/.codex/config.toml. Create the ~/.codex directory if the CLI has not yet made it.
• An MCP server silently never connects. Check the env var actually expands. ${GITHUB_TOKEN} resolving to an empty string looks identical to a broken server from the outside.
• Approvals feel wrong after a change. You probably changed the sandbox instead. Re-read the two keys as a pair — "when does it ask" and "what can it touch" are separate answers.
• An effort level appears to do nothing. xhigh is not offered by every model. Move to a codex-max or 5.2 model or drop to high.
• AGENTS.md is ignored. Check the filename and location first, then the length — a context file loaded into every session pays its token cost every turn, so keep it to the commands and the specific mistakes you want stopped.

Each tab has copy and download buttons, and Reset restores the whole form including any AI-tailored context file. If you are configuring the same MCP server across several different clients rather than setting up Codex itself, the MCP server config generator handles that shape directly.