Skip to content

Connect providers and endpoints

A provider supplies credentials and an API endpoint. A catalog entry supplies the model ID and request protocol. Configure both before a model can appear in the chat selector.

The packaged catalog uses OpenRouter. To use it, set OPENROUTER_API_KEY in .env and restart. To add another provider, follow the steps below.

Connect a provider, match a model and adapter, and verify a chat reply.

1. Configure the provider

Choose the row matching your endpoint. Set these variables in the existing .env; keep credentials out of the model catalog.

Catalog provider API key Base URL setting Default base URL
openrouter OPENROUTER_API_KEY OPENROUTER_BASE_URL https://openrouter.ai/api/v1
zai Z_AI_API_KEY Z_AI_BASE_URL https://api.z.ai/api/coding/paas/v4
openai OPENAI_API_KEY OPENAI_BASE_URL https://api.openai.com/v1
responses RESPONSES_API_KEY RESPONSES_BASE_URL Must be set
anthropic ANTHROPIC_API_KEY ANTHROPIC_BASE_URL https://api.anthropic.com
anthropic_compat ANTHROPIC_COMPAT_API_KEY ANTHROPIC_COMPAT_BASE_URL Must be set
inception INCEPTION_API_KEY INCEPTION_BASE_URL https://api.inceptionlabs.ai/v1
local LOCAL_AI_API_KEY (if required by the server) LOCAL_AI_BASE_URL http://localhost:8080/v1

These are Numi's configured defaults. Use the endpoint supplied for your provider account if it differs.

For example, a local server already listening on port 8080 uses:

LOCAL_AI_BASE_URL="http://localhost:8080/v1"
LOCAL_AI_API_KEY="sk-no-key-required"

Use the real key if that server requires authentication. From a Docker container, localhost refers to the container itself; use a hostname or address reachable from the container for a server running elsewhere.

Restart Numi after changing environment variables. For Docker, recreate the service with docker compose up -d so changed environment values are applied.

2. Add the model

  1. Sign in as an administrator and open Models at /models.
  2. Use provider discovery or add an entry manually.
  3. Choose the configured provider and the wire API accepted by its endpoint: openai_chat, openai_responses, or anthropic_messages.
  4. Set the upstream model ID in api_model, enable the entry, and save it.
  5. Choose it as the default if new chats should use it.

Use anthropic_messages with anthropic or anthropic_compat: the Messages adapter uses those providers' settings. Use openai_responses for Responses endpoints. OpenRouter, Z.AI, and Inception catalog entries normally use openai_chat. A catalog entry can pass schema validation even when its provider/protocol pairing cannot serve a request.

The catalog id is Numi's stable identifier; it can differ from the upstream api_model. See Manage models for editing, importing, and refreshing provider metadata.

Adding a key does not create catalog entries. Changing Z_AI_MODEL also does not add a selectable model.

3. Check background model choices

Memory extraction and automatic titles have separate, instance-wide model settings: MEMORY_SUMMARY_MODEL and CHAT_TITLE_MODEL. Their configured default is deepseek/deepseek-v4.1-flash; ensure your catalog contains the chosen model and its provider is configured.

For background jobs to use the catalog default instead:

MEMORY_SUMMARY_MODEL=inherit
CHAT_TITLE_MODEL=inherit

These jobs currently require a catalog model using openai_chat. Choosing an Anthropic Messages or Responses model for chat does not make it suitable for the background jobs. A saved administrator override takes precedence over the environment setting.

See Memory for the extraction controls and Privacy and data for external data flows.

4. Verify a real response

Open a new chat, select the model, and send a short message. A listed model only proves its catalog entry is enabled and provider settings exist; it does not prove that the endpoint is reachable or the key is valid.

Catalog edits on the Models page take effect without a server restart. Reasoning behavior follows the entry's capabilities and selected wire API; reasoning mode and replay are separate.

Troubleshooting

Symptom Check
Model is missing from the selector Check its catalog provider, enabled state, and provider credentials.
Authentication error Check the key and base URL privately in your editor; do not print keys into terminal logs.
Connection refused for a local model Verify the server is running and reachable from the machine or container running Numi.
Provider rejects a model ID Check api_model against the IDs available to your endpoint/account.
Provider rejects reasoning fields Refresh metadata where supported and verify wire API, effort levels, and preservation settings for that route.
Chat works but memory or titles fail Check the separately selected background models and any saved administrator overrides.

The Configuration reference lists the remaining provider settings.