Subscription pools and routing
How RouteKit discovers models, selects accounts, recovers credentials, and contains failover within a subscription pool.
A subscription provider is a pool of named accounts of one kind: codex or
claude-code. The singleton daemon owns credentials, discovery, selection,
cooldowns, and relay state for that pool.
Discovery and eligibility
At startup, RouteKit discovers models against every healthy account and publishes their union under the provider namespace. Per-model eligibility prevents a request from reaching an account that did not advertise that model.
Each member maintains its own credential refresh, quota windows, cooldowns, and reset times. Pool strategy chooses only among members that can serve the exact requested model.
Selection and failover
capacity_weighted, round_robin, and sticky change how RouteKit chooses an
eligible member. They do not change the route namespace.
Exhaustion or a retry can select another account in the same provider pool. RouteKit never crosses to another provider or billing class. It never replays a request after semantic stream output has been committed.
Recover expired credentials
Before response output is committed, a credential-scoped upstream 401—or a
provider-classified credential 403—performs one coalesced refresh and one
validation attempt. Other requests use a healthy account in the same pool
while recovery runs, or wait when no alternative exists.
A rejected credential fingerprint stays quarantined across reloads and
restarts until login replaces it. Temporary refresh failures enter timed
backoff. Model-scoped 403 responses remove only that account/model pairing;
request-policy 403 responses are returned unchanged.
Resolve model capabilities
Explicit reasoningCapabilities configuration has highest precedence. Without
an override, RouteKit chooses discovered metadata deterministically from the
first successful account in configured order that reports it. Failed accounts
and accounts that omit the metadata are skipped.
RouteKit exposes only effort levels that the provider marks supported. Claude Code uses its native effort selector, and Codex uses its native picker levels.
Model names shown to clients
Use canonical provider/native-model IDs in router YAML and generic gateway
requests. Codex presents subscription models under native names in its picker.
Claude Code's installed picker uses reversible
anthropic.routekit.<canonical-routekit-id> entries derived from modelPolicy.
A direct Claude command may use a bare native ID only when it is unambiguous.
These client spellings still resolve through the RouteKit-owned pool. They are not a bypass around the daemon or its selection policy.
Verify routing behavior
Use routekit accounts status for live eligibility and selection state,
routekit usage for quota windows, and routekit calls inspect <call-id> for
completed request attribution.