Skip to content

Manage Models

Sign in as an administrator and open Models at /models. Configure the provider credentials or endpoint first; catalog entries contain metadata, not secrets.

Add a model card to a catalog, review its capabilities, and test it in a chat.

Add a model

  1. Select Add Model and choose a provider.
  2. Use Find on provider to search and select a result, or enter details manually.
  3. Review Display label, Logical ID, Upstream / API model, and Wire API. Set the model's capabilities to match the endpoint.
  4. Enable the entry and select Save.
  5. Open a new chat, select the model, and send a message to verify it works.

The logical id is the stable selector stored by chats. api_model is the upstream provider ID and may differ. After creation, keep id unchanged. Routes are unique by (provider, wire_api, api_model or id).

For OpenRouter, choosing a discovery result fills reasoning support, mandatory status, and supported effort levels. For an existing entry, edit it and use Refresh provider metadata to update those fields. Review the result before saving; discovery does not test a chat request.

The form does not expose every JSON field. In particular, set context_window through catalog JSON and import it; the current per-model edit endpoint does not accept that field. See the catalog field reference.

Edit, disable, or choose a default

Use the model's row actions to edit it, enable or disable it, or make it the default. The default must remain enabled. Disable a model referenced by chats instead of deleting it.

Catalog edits take effect at runtime. Provider credential and base URL changes still require a server restart. See the Model catalog reference for fields, validation rules, and the meaning of available versus selectable.

Import, export, and reload

Export downloads the active catalog as portable JSON. Import offers two modes:

  • Merge adds new entries and replaces entries with the same logical ID and route. Include the complete model entry: omitted optional fields take their defaults, rather than retaining their previous values.
  • Replace uses the imported catalog as the complete document.

Review the selected mode and entries before importing. Replacement and deletion are checked against model references held by chats and background settings.

Use Reload catalog after editing the file outside Numi. Invalid runtime reloads leave the last known-good catalog active; invalid private JSON at startup prevents the application from starting.

Catalog files

The packaged public default is src/numi_chat/llm/models.default.json. When an operator-owned state/models.json exists, it is the complete runtime catalog. The two files are never merged at startup.

For manual setup, export from the Models page or copy the packaged file into state/models.json, then edit the complete document. Set NUMI_CHAT_MODEL_CONFIG_PATH to use another path. Unknown JSON fields and secret-like fields are rejected; keep API keys and provider base URLs in .env or deployment secrets.

Docker deployments should mount the whole state directory:

volumes:
  - ./state:/app/state

Atomic Admin writes replace the file in its own directory. An individual file bind mount can prevent replacement and should be treated as read-only.

Background memory and title models have separate choices on the Models page. See Providers and endpoints before changing their provider or wire API.