Skip to main content

Model Catalog

Ethos ships a remote model catalog so new models become available without upgrading the CLI. The catalog is a static JSON file published alongside the documentation site.

Published URL​

https://ethos-agent.ai/api/model-catalog.json

JSON Schema​

interface ModelCatalogManifest {
  version: number;          // Always 1
  updatedAt: string;        // ISO-8601 timestamp
  providers: {
    [providerId: string]: {
      models: Array<{
        id: string;         // Model identifier (e.g. "claude-sonnet-4-6")
        label: string;      // Display label for the picker
        contextWindow: number; // Max context in tokens
        default?: boolean;  // Default model for this provider
      }>;
    };
  };
}

The catalog ships exactly three provider keys: anthropic, openai-compat, azure.

Three-level Fallback​

The CLI resolves models in order:

  1. Remote — fetches the published URL (8s timeout)
  2. Cache — ~/.ethos/cache/model-catalog.json (24h TTL by default)
  3. Bundled — the snapshot compiled into the CLI binary

A fresh install with no internet still works (bundled fallback). Network failures are silent — one log line at warn level.

Configuration​

In ~/.ethos/config.yaml:

modelCatalog.enabled: true
modelCatalog.url: https://ethos-agent.ai/api/model-catalog.json
modelCatalog.ttlHours: 24
modelCatalog.providers.anthropic.url: https://internal.example.com/anthropic.json
KeyDefaultDescription
modelCatalog.enabledtrueSet to false to disable remote fetch entirely
modelCatalog.urlOfficial URLOverride the catalog URL
modelCatalog.ttlHours24Cache time-to-live in hours
modelCatalog.providers.<id>.url—Per-provider URL override

Adding a New Model​

  1. Edit packages/wiring/src/model-catalog.ts — add the entry to MODEL_CATALOG
  2. Open a PR to main
  3. On merge, CI runs pnpm build:model-catalog, Docusaurus deploys, and the JSON is live
  4. Existing CLIs pick it up within 24 hours (or on next cache expiry)

Private Catalog for Operators​

Organizations can host their own catalog JSON at an internal URL:

modelCatalog.url: https://internal.corp.example.com/model-catalog.json

The JSON must conform to the same schema. Per-provider overrides let you mix sources:

modelCatalog.providers.anthropic.url: https://internal.corp.example.com/anthropic-only.json

Cache Location​

~/.ethos/cache/model-catalog.json — managed via the Storage abstraction. Delete it to force a re-fetch on next CLI start.

Source​