Routes & the picker
How model routes work and how the picker chooses one.
A route is how a harness reaches a model provider. Every harness, on every environment (local or cloud), is on exactly one of three routes, or a combination, depending on the harness.
The three routes
Native. The harness authenticates however it normally would outside
Proliferate: claude login, codex login, a cached token file, whatever it
already does. Proliferate doesn't get involved. This is the default when you
haven't configured anything for that harness.
API key. You supply your own provider key, and Proliferate wires it into
the harness's environment under whatever variable name that harness expects
(ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY, and so on).
Gateway. The harness routes through Proliferate's own model gateway. Proliferate holds the real provider credentials; the harness gets a scoped key with its own budget. No key management on your side. See Gateway, BYOK & OAuth for the full picture.
How many routes a harness can use at once
Not every harness treats routes the same way:
| Harness | Behavior |
|---|---|
| Claude, Codex, Grok | One at a time. Turning on the gateway or enabling an API key row switches off any other enabled source, like a radio button. |
| OpenCode | Any combination. OpenCode can front the gateway and several API key rows at once, one per provider, since it's built to call more than one provider from the same harness. |
| Cursor | None. Cursor authenticates with its own sign-in only. There's nothing to configure. |
This is enforced on the server, not just in the UI, so an invalid combination (two API keys enabled at once on Claude, for example) is rejected before it's saved.
Harness Authentication tab
Settings -> Agents -> Claude -> Authentication: the Proliferate gateway toggle, one API-key row (ANTHROPIC_API_KEY, a key picker, and an enabled switch), and an 'Add variable' button underneath.
If nothing is turned on for a harness, that's not a broken state, it's the native route. Local runs fall back to the CLI's own login. Cloud runs for that harness stay disabled until you turn on a route, because a cloud sandbox has no interactive login to fall back to.
Your organization can also restrict which routes or which harnesses are allowed at all. See Allowed harnesses.
The picker
The picker is the model selector in the chat composer, the small menu you open from the model name above the message box. It groups models by agent (harness), shows which one is active, and lets you switch.
Composer model picker
The chat composer's model picker popover open: a searchable list of models grouped by agent (Claude, Codex, OpenCode, Grok, Cursor), a checkmark next to the active model, and an 'Agent' submenu row at the bottom.
What happens when you choose a model depends on where it comes from:
- A different model on the same harness, in the same chat. The session switches to that model in place. Same conversation, no new chat.
- A model on a different harness. That opens a new chat, because switching harnesses means switching to a different underlying agent process, not just a different model parameter on the same one.
The picker only lists models a harness can actually reach right now, given its current route. See Per-harness x environment for how that list gets built and refreshed.