Choosing Models
How a run gets its model: the resolution order from node pin to system, the model selection values (pinned, follow, profile, router, inherit with effort), default effort, and profiles as optional constraints.
Preview. Stages 1.0 is built and merged but not deployed yet. Names, screens and defaults on this page can change before release.
A model is chosen for every run, and you decide how at the level that fits: a whole org, one project, one stage, or one card in one stage. You do not need a profile for every combination of model and effort. You install a model once (Model Access), then point stages and cards at it.
Resolution order
The platform looks for the model level by level and takes the first one that gives a concrete answer. The narrowest scope wins, and inside a scope the most specific setting wins:
| Order | Level | What is checked |
|---|---|---|
| 1 | Workflow node pin | A model profile pinned on a node in the workflow editor. |
| 2 | Workflow | The stage card, then the stage. |
| 3 | Project | The stage card, then the stage, then the project default. |
| 4 | Org | The stage card, then the stage, then the org default. |
| 5 | System | The stage card, then the stage, then the system default. |
Written out: node pin → workflow → project → org → system, and inside each scope stage card → stage → default.
A consequence is worth stating: a setting at a broader scope never beats a narrower scope's default. A system-level stage card selection does not override your org's default, and an org-level stage selection does not override your project's default. "Inherit" means pass the question to the next level down.
A node pin is a deliberate override you add in the workflow editor. The portable SDLC template does not set one.
Existing assignments by work type, and descriptor rules that match on issue labels, are still read during the move to stages. At each scope they rank below that scope's stage card and stage settings. If no level gives a model, the worker's own configuration decides.
Model selection values
A stage and a stage card each hold one model selection. Every selection may also carry an effort.
| Value | What it does |
|---|---|
inherit | Takes the model from the next level. On its own it is stored as "not set". With an effort, it changes only the effort and leaves the model to the levels below. |
pinned | One specific installed model. It never moves to a newer version on its own. |
follow | A model line, such as anthropic/claude-opus, on the minor or latest track. It resolves at dispatch to the newest installed version that fits. |
profile | A named profile that constrains provider, auth mode, effort, provider config or sub-agent. |
router | Hands the choice to the learned router. |
Efforts are low, medium, high, xhigh and max. Not every harness can apply an effort, and an effort the chosen model or harness cannot apply is not sent.
Pinned
A pinned selection names one of your org's installed models. It resolves the way an installed model always does, through the providers and credentials you connected. If the model has been retired, uninstalled, or has no live provider behind it, the dispatch fails. It does not silently use a different model.
If an operator withdraws the model from the catalog later, existing installs keep working and the run receipt carries a warning. See Withdrawn models.
Follow a model line
A line is a model's identity without its version: anthropic/claude-opus, for example, covers every Opus release. A follow selection says which line and how far to move:
minorstays on the major version that was current when you wrote the selection (the selection records it) and picks up newer minor versions on that major.latestalso crosses major versions.
Both resolve at dispatch to the newest version that:
- your org has installed;
- is granted for the project the run belongs to;
- has a live provider serving that is not withdrawn or deprecated.
If a newer version exists but you have not installed it, the newest installed version on the line runs. Nothing is installed for you. If no installed, granted version exists on the line, the follow selection is skipped and the next level is tried. A model whose catalog name cannot be split into a line and a version cannot be followed.
To see what a follow selection would pick right now, and whether a newer version is available:
GET /api/org/{orgId}/model-library/follow-preview?line=anthropic/claude-opus&track=minor&major=5&projectId={projectId}The response has resolved (the installed, granted model a dispatch would use), newest (the newest version on the track in the catalog and whether you installed it) and newerAvailable. major is required with track=minor. Any org member can call it.
To set a follow selection, write it to a stage or a stage card through the stages API:
{
"modelSelection": {
"mode": "follow",
"line": "anthropic/claude-opus",
"track": "minor",
"major": 5,
"effort": "high"
}
}This is a PATCH to /api/projects/{projectId}/stages/{key} (or the org route), or a card entry in the PUT to .../stages/{key}/cards. An unknown line is rejected with 404, and minor without major with 400.
The stage editor in Settings does not offer Follow a model line yet. It lists it as not available. Until it does, set follow selections through the API.
Profile
A profile selection loads the named profile and resolves a concrete model within its constraints. If the profile is not visible to the run, that selection is skipped and the next level is tried; the receipt records that it was passed over.
Router
router is accepted and stored, but dispatch does not resolve it yet. A stage or card set to router is skipped, the receipt notes that, and the next level decides. The editor lists it as not available.
Inherit with an effort
Use this to change only how hard the model thinks. Setting a stage card to "inherit, high" runs whatever model the project, org or system would have chosen, and asks for high effort. The narrowest effort set along the way is the one requested. If the profile that finally wins pins its own effort, the profile's effort is used and the request is recorded as not sent.
Default effort
The effort for a run is decided in this order:
- the winning profile's own effort, when the profile sets one;
- an effort requested by the run's node, stage card or stage, when the chosen model and harness can apply it;
- the chosen catalog model's default effort, when nothing above asked for one;
- nothing, so the provider's own default applies.
A requested effort that the model or harness cannot apply is dropped, and the catalog default is not substituted for it.
The default effort of a catalog model is filled in from provider metadata when models are imported or synced, only where the provider publishes one and only if the field is empty. A value an operator set is never overwritten. Providers that do not publish a default leave it empty, and runs on those models send no effort.
The run receipt records which of these sources chose the effort: node, stage-card, stage, descriptor-rule, profile, catalog-default, or omitted.
Profiles are optional constraints
A profile is a named bundle that constrains a run: provider, auth mode, effort, provider config and a sub-agent override. Profiles still exist, and they are still the right tool when you want a rule such as "Opus through my own key at high effort".
What changed is that you no longer need one to use a model. A stage or stage card can pin or follow an installed model directly. The project and org defaults, the last entry in each scope, are still held as profiles, so setting a default model for a whole project still goes through Settings, then Model Profiles.
A profile is also the way to apply a constraint that a pinned model alone cannot express, for example restricting a model to one auth mode. See Auth Modes.
What the run records
Every dispatch receipt records how the model was chosen: the level that won and the stage, card and scope behind it; the selection value; for follow, the line and the model it resolved to; the concrete model and the provider serving that ran; and the effort source. "What ran" is always exact, even when the selection was a line.