Core Concepts

Aliases

Aliases map capability requirements to provider models. Pass any free:${string} alias to languageModel().

freerouter.languageModel("free:auto", keys)
freerouter.languageModel("free:fast", keys)
freerouter.languageModel("free:reasoning", keys)

Resolution pipeline

alias → filter by capability
  → exclude deprecated models
  → exclude providers without key
  → exclude down providers (unless cooldown expired)
  → sort by priority
  → try each until one succeeds

Step by step

1. Capability filter - maps alias to capability tag, queries registry
2. Deprecation filter - removes models marked deprecated: true
3. Key filter - removes providers where caller has no key
4. Health filter - removes providers in "down" state (unless 10s cooldown expired)
5. Priority sort - orders remaining candidates by provider priority
6. Failover loop - tries each candidate until one succeeds or all fail

Provider priority

Providers are tried in this order (all else equal):

Rate-limited providers are deprioritized but still included. Down providers are excluded entirely.

Key Format Reference