Keep Model Pickers Current Without Breaking Offline Use
Hermes keeps the OpenRouter and Nous Portal model pickers current through a curated JSON manifest hosted with the documentation site. Maintainers can update the picker lists without waiting for a new CLI release. Availability does not depend on that remote file: if it is unreachable or invalid, Hermes falls back first to usable cache data and then to the snapshot bundled with the installed CLI.[1]
Know what the catalog controls
The live manifest is published at https://hermes-agent.nousresearch.com/docs/api/model-catalog.json. Its top level includes a schema version, an updated_at value, optional metadata, and provider blocks containing model records. A model record requires an id and may carry a description, metadata, or a default marker.[1]
The manifest is curation, not a complete provider registry. OpenRouter descriptions drive picker badges such as recommended, free, or default. Nous Portal determines free-tier access from live pricing instead. Pricing and context length are intentionally absent from the manifest; Hermes obtains those details from live provider APIs and models.dev during provider discovery.[1]
Treat schema and defaults as safety boundaries
Hermes accepts only schema versions it understands. An unsupported version is treated like an unreachable manifest and triggers fallback rather than risking a broken picker. Exactly one model per provider may be marked default: true. That record is the silent default used when a provider exists but the user has not selected a model. Runtime default resolution reads cached data and falls back to an in-repo constant when no cache exists, keeping hot paths off the network.[1]
Understand fetch and cache behavior
/model and hermes model fetch only when the disk cache is stale. A fresh cache creates no network request. A failed network request uses the cache when available, or the in-repo snapshot when it is not. The default cache lives at ~/.hermes/cache/model_catalog.json, and the documented configuration enables remote fetching with a one-hour TTL:[1]
model_catalog:
enabled: true
url: https://hermes-agent.nousresearch.com/docs/api/model-catalog.json
ttl_hours: 1
providers: {}Set enabled: false when an installation must always use its bundled snapshot. A provider-specific override URL can replace only that provider's block while all other providers continue using the master manifest.[1]
Keep the picker intentional
The optional excluded_providers list hides providers from every model-picker surface even when Hermes discovers valid credentials. Matching is case-insensitive across the provider identifiers Hermes may expose, so one exclusion can cover mapped, overlay, or canonical forms. This is useful for legacy or test credentials that should not appear in routine selection.[1]
Catalog rollout checklist
- Validate the manifest against schema version 1.
- Mark no more than one default model per provider.
- Keep model IDs within the correct provider block.
- Choose a TTL that fits your freshness and network policy.
- Preserve a bundled snapshot for offline operation.
- Review provider exclusions across every picker surface.
Common pitfalls
- Adding pricing or context data and expecting the picker to treat it as authoritative.
- Marking multiple models as the provider default.
- Shipping a new schema version before installed clients understand it.
- Assuming a successful picker proves the network manifest was used; Hermes may be serving cache or snapshot data.
- Using provider exclusions as credential deletion; they only control picker visibility.
Verification
Open /model or run hermes model while online and confirm the curated providers and default selection appear. Inspect the cache file after a successful fetch. Next, test in an isolated environment with network access unavailable: the picker should still load from cache or the bundled snapshot. Finally, supply a deliberately incompatible manifest in a test setup and confirm Hermes rejects it without breaking model selection.