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 [profiles.<name>] block in config.toml that overrides any top-level setting — model, reasoning effort, approval policy, sandbox mode — for the runs that use it:

# config.toml — two postures for two kinds of day

[profiles.budget-build]
model_reasoning_effort = "low"
approval_policy        = "on-request"
sandbox_mode           = "workspace-write"

[profiles.budget-design]
model_reasoning_effort = "high"
approval_policy        = "untrusted"
sandbox_mode           = "read-only"

Any key you set inside the block 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, you can make it the standing default with default_profile = "budget-build" in config.toml, and override it per launch with -p on the days the work changes. The full profile mechanics — inline blocks versus separate layer files, 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 blocks 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 blocks. 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.