Bundle model, effort, approval, and sandbox into a named profile

By the end of the last lesson you were setting the model one way, the effort another, and - back in the approvals chapter - the approval policy and sandbox mode separately on top. That’s four knobs, and across a week on budgetcli you keep reaching for the same two or three combinations. The boilerplate work always wants a light model, low effort, and loose-enough approvals to move fast. The design work always wants a heavy model, high effort, and a careful approval posture because it’s touching real money logic. Setting all four by hand every time is exactly the kind of friction that makes you stop bothering. Profiles are how you name a combination once and select it with a single flag.

A profile is a named bundle

A profile is a layer file sitting next to config.toml - ~/.codex/<name>.config.toml - whose top-level keys override your base config’s for the runs that use it. Model, reasoning effort, approval policy, sandbox mode all live there. Two postures for two kinds of day:

model_reasoning_effort = "low"
approval_policy        = "on-request"
sandbox_mode           = "workspace-write"

model_reasoning_effort = "high"
approval_policy        = "untrusted"
sandbox_mode           = "read-only"

That budget-build is the same file you wrote in Approvals & sandboxing, not a second one - the block above shows only the keys this lesson is adding, so its [sandbox_workspace_write] section is still sitting there underneath. Any key you set inside the file replaces the base-config value when that profile is active; anything you leave out falls back to your defaults. (I’ve left the model line out of these examples on purpose - that’s the key you’d set to your chosen model, and which models you can name there depends on your auth tier, exactly as the last lesson covered.)

Selecting one

Activate a profile at launch with --profile (short -p):

codex -p budget-build  "add the accounts CRUD endpoint"
codex -p budget-design "design the categorisation rules engine"

One flag now carries the whole posture. budget-build drops the effort and lets the agent move through mechanical work with a working sandbox; budget-design raises the effort and tightens approvals and the sandbox down to read-only so the agent reasons and proposes before it can touch anything. You stopped setting four knobs and started naming an intent.

If you find yourself always launching with the same one, wrap the -p in a shell alias so it comes for free, and type the explicit flag on the days the work changes. The full profile mechanics - where the layer files live, which keys are eligible - are in the advanced config reference.

This is the same bundle you met under approvals

If approval_policy and sandbox_mode in those files look familiar, they should - profiles are not a models-chapter feature that happens to also carry trust settings. They’re the one mechanism for bundling a posture, and the approvals chapter builds the trust side of exactly the same idea: a read-only, ask-first profile for code you don’t trust yet, a looser one for work you do. The full treatment of designing profiles around trust - how the two-axis approval-and-sandbox model maps onto named bundles - lives there, at Profiles for trust. This lesson just adds the two model knobs to the same files. One profile, the whole posture: which brain, how hard it thinks, what it’s allowed to do, and how much it asks first.

You can now express a complete working stance in a single flag. The last piece is the judgment underneath all of it - reasoning about what each gear actually costs you, so you reach for the right profile on purpose rather than by reflex.