Skip to main content
Two axes decide which model answers a turn. The provider is the API surface that serves the model. The credential is what pays for it. They are separate on purpose. The same model can be reached by a key, a subscription, or a hosted account. Keys and subscriptions live side by side in the same session.

​
Providers

The provider is spelled xai, not grok. Grok is the model family and xAI is the company that serves it, which is also how the model catalog indexes it. SERI_PROVIDER names which provider SERI_MODEL is read against. A successful /model pick persists both for you, so setting them by hand is the scripted equivalent of picking one.

​
Bring your own key

/setup adds or replaces a provider key without leaving the session. OpenRouter is omitted unless you already have a local key — that slot is the hosted-account offer, not a BYOK paste target. Setting the environment variable before you launch works too, and the environment wins over anything stored. Guided setup will not finish without a model pick. A key supplied through the environment skips setup entirely, and a session that has never had a pick falls back to the built-in default, openai/gpt-oss-120b on Groq. /model is how you get off it. On a genuinely blank first run, meaning a real terminal with no key configured anywhere, seri opens guided setup instead of the input box. It is two steps. Add a key, then pick a model. The model step is not optional, because a key with no model does not leave seri in a runnable state. Declining to add a key at all closes setup rather than trapping you in it.

​
Subscriptions, inside the harness

/setup lists API keys and Subscriptions in one panel. Two consumer plans connect from there. A subscription and a metered key can both be present. For that vendor the subscription wins, and the key is marked unused. Turns on a subscription report (cost: included) instead of a dollar amount.
seri never silently falls back from a refused subscription to a key that would charge you. If the plan refuses the turn, that is the answer.

​
Grok (xAI)

XAI_API_KEY is metered API billing from console.x.ai. A SuperGrok or X Premium+ plan is a second credential for the same provider. Connect it from /setup with a browser sign-in. The grant lives in xai-auth.json in your profile root. Disconnecting from /setup unlinks that file. It does not revoke access on xAI’s side.

​
ChatGPT / Codex (OpenAI)

OPENAI_API_KEY is metered API billing. A ChatGPT plan is a second credential for the same provider. seri does not host ChatGPT OAuth. Install the Codex CLI, run codex login, and /setup shows the plan as connected. seri reads ~/.codex/auth.json (or $CODEX_HOME) and never writes it. An API-key Codex login is not a plan. /setup says so and will not treat it as a subscription. Disconnecting from /setup writes a profile-local codex-ignore so this profile stops using the plan. It does not run codex logout. Enter on the ignored row clears the file. /model lists every provider and every route, including plan-included Codex rows. A plan that cannot be read still lists the OpenAI rows; it just cannot say which ones are included.

​
A hosted account

/signup creates a seri account and /login signs in to one. A signed-in account manages no keys at all and defaults to openai/gpt-oss-120b through OpenRouter. /setup lists that coverage as a seri subscription (free / pro / max / ultra), next to Grok and Codex. A leftover OpenRouter key is marked unused while the plan is connected. Disconnect the seri row to use your keys without logging out. /model labels those routes seri, Grok routes grok, Codex routes codex, and a BYOK route your key. That default was chosen by measurement rather than preference. On the same task, with the same prompt and a fresh session each run, it made a real tool call in 20 of 20 runs where llama-3.3-70b-versatile managed 5 of 11. /usage shows what the account has spent. See Hosted accounts and usage.

​
Switching model

/model opens the picker. It lists every provider and every route to a given model, including plan-included subscription rows, and a switch takes effect mid-session without losing context. A pick whose next turn actually succeeds becomes the default for every future brand-new session, not only the one you picked it in. A pick that fails does not, so a typo or an unreachable model never becomes your default.

​
Rerouting

A model is often reachable through more than one provider. If the pair you are on has no credential, seri reroutes to a configured provider that reaches the same model and says so once in the transcript.
  • Native providers are preferred over an aggregator such as OpenRouter, so an Anthropic key beats an OpenRouter key for a Claude model.
  • An explicit /model pick wins over rerouting, as long as its own provider has a credential.

​
Reasoning effort

/effort <level> sets this session’s reasoning-effort override, /effort auto clears it, and /effort alone shows the current setting. Which levels are legal depends on the model. The value also persists as SERI_REASONING_EFFORT once a turn has actually succeeded on it.

​
Models for subagents

Subagent roles inherit the session’s provider and model unless a task names a different pair. You ask the parent to dispatch and name the child model in the prompt.
provider is one of the six ids above and model is that provider’s own id. For OpenRouter, that is the OpenRouter slug.
  • A model given without a valid provider is ignored rather than mixed with the session provider.
  • A pair that cannot be constructed warns and falls back to the session model rather than failing the turn.
  • SERI_ROLE_<ROLE>_MODEL and SERI_ROLE_<ROLE>_PROVIDER supply a default for when a task omits the pair.
  • The session’s /effort copies onto a child only when that child runs the same pair, unless the task names an effort itself.
Subagents covers the roles themselves.