Model Configuration

This guide explains how Self-Managed Kindo installations define and maintain global models — the system-wide LLMs (and related models like embeddings or transcription) that power workflows, chat, ingestion, and other core experiences.

In a self-managed environment, you add models to Kindo, map them to Unleash feature variants, and keep those mappings up to date when models are replaced.

Deploying model infrastructure?

Before configuring models in Kindo, you need working inference endpoints. See Prepare AI Models for how to deploy and verify self-hosted models (vLLM, context window sizing, tool-call parsers) or connect cloud API providers.

Unleash Features and Strategy Variants

Each key below is an Unleash feature whose variant payload contains one or more global model IDs. The backend and frontend read these variants to decide which models to use.

Required Features

Feature Key	Description
AUDIO_TRANSCRIPTION	Converts audio to text
CRON_EXPRESSION_GENERATION	Generates cron expressions from natural language schedule descriptions
DEFAULT_WORKFLOW_STEP_MODEL	Default model for workflow step execution
EMBEDDING_MODELS	Models for generating text embeddings
INGESTION_WORKERS	Models for data ingestion and extraction
INTERNAL_AUTO_GENERATION	Internal model for automatic content generation and internal worker tasks
LOCAL_STORAGE_CHAT_ACTIONS_MODELS	Fallback default chat model for the model dropdown and chat action selection. Applies when an org admin has not chosen a default chat model in Settings → Models (or the chosen model is unavailable)
TOOL_CALLING_MODELS	Models that support tool/function calling (used to filter model selection in chat UI)

Optional Features

Feature Key	Description	Notes
API_STEP_GENERATION	Models for generating API steps in workflows
DYNAMIC_API_REQUEST_PARSER	Parses dynamic API requests
SLACK_MESSAGE_GENERATION	Generates Slack messages	Only if Slack integration is enabled
MULTIMODAL_MODELS	Models with image/multimodal input support	Only if multimodal chat is enabled

Minimum Model Requirements

Self-Managed Kindo needs baseline global models to function. Without them, core flows like chat, workflow execution, ingestion, and indexing will fail.

Absolute Minimum Set

Model Type	Purpose	Recommendations
Embedding model	Semantic search, retrieval, and indexing	Open source: BAAI/bge-m3. Hosted: Gemini embedding
Strong/large model	Complex reasoning, workflow execution, long-form generation	Open source: gpt-oss 120B. Hosted: Gemini 2.5 Pro, Claude 4.5, GPT 5.2
Audio transcription	Audio file processing, voice notes, transcription workflows	Open source: Faster Whisper. Hosted: Deepgram

Recommended Additional Models

• Small model (title generation, quick summaries, low-latency steps): Gemma 3 or Llama 3.2 7B
• Security-focused: DeepHat 32B
• Multimodal: Gemini 2.5 Pro (image + text)

Managing Models

Overview of Steps

1. Add the new model in Settings → Models → Add model.
2. Update Unleash variants to reference the new model IDs.
3. Delete the old model with replacement.

If you are operating through the released Helmfile installer, the equivalent workflow is make add-models, then make sync-model-flags. That path updates only the model ID payloads for the model-related flags instead of re-importing the full Unleash export.

Caution

If the model you are deleting is still referenced by Unleash, the response will list the feature flags that need updates. Update those variants first, then retry the delete.

Add a Self-Managed Model in the UI

A self-managed model is a model you already run or pay for somewhere else — a self-hosted vLLM box, a serverless endpoint such as Together, Fireworks, or Groq, an internal inference gateway, or your own OpenAI account — that you want to use inside Kindo for chat and agents. The endpoint must be OpenAI-compatible (it accepts OpenAI-style chat completion requests). The Add Model form asks only for the handful of facts any such endpoint needs, in plain English.

Field	Required?	What to enter
Display name	Yes	The name you’ll see in Kindo when choosing this model, for example Llama 3.3 70B (self-managed).
Model ID	Yes	The model’s name exactly as your endpoint expects it in a request, for example Qwen/Qwen3.7-Max, llama-3.3-70b, or gpt-4o. Use exactly what your provider or server calls it. For Azure OpenAI, use your deployment name.
Endpoint URL	Yes	The base URL of your model’s API, for example https://api.together.xyz/v1, http://my-vllm:8000/v1, or https://your-resource.openai.azure.com. Paste exactly what your provider gives you — Kindo tidies it up (trims it, drops a trailing slash or a mis-pasted /chat/completions, and adds the version segment if your base URL doesn’t already include one).
API version	No	Leave blank for most providers. Only needed when your endpoint requires an api-version query parameter — for example an Azure OpenAI deployment pinned to a dated version such as 2024-10-21.
API key	Yes	The key your endpoint uses to authenticate. Stored encrypted; never shown again.
Context window	Yes	Your model’s maximum context length in tokens, from your provider’s docs, for example 128000. Kindo uses this to keep long conversations within the model’s limit.
Max output tokens	Yes	The maximum number of tokens the model should generate per response, from your provider’s docs, for example 4096.

Endpoint URL examples

Paste the base URL your provider hands you. Common shapes already work as-is:

• OpenAI: https://api.openai.com/v1
• Together: https://api.together.xyz/v1
• Groq: https://api.groq.com/openai/v1
• Fireworks: https://api.fireworks.ai/inference/v1
• Self-hosted vLLM: http://<host>:8000 (Kindo appends /v1 for you)
• Azure OpenAI: https://<your-resource>.openai.azure.com (Kindo routes to Azure’s OpenAI-compatible /openai/v1 surface for you)

Azure OpenAI

Azure OpenAI endpoints work like any other OpenAI-compatible endpoint:

• Most deployments: paste your resource URL (for example https://my-resource.openai.azure.com), set Model ID to your deployment name, and leave API version blank. Kindo talks to Azure’s OpenAI-compatible v1 surface, which needs no api-version parameter.
• Deployments pinned to a dated API version: fill in the API version field (for example 2024-10-21) and Kindo dispatches through Azure’s versioned API instead. Pasting the full target URI from the Azure portal (https://…/openai/deployments/<name>/chat/completions?api-version=…) also works — Kindo picks up the api-version from the URL automatically.

Note

The URL must point at your chat completions endpoint. URLs for other APIs (for example ones ending in /embeddings or /responses) are rejected so a wrong paste can’t silently mis-configure the model.

Test & Save

Test & Save (the primary button) sends one real chat completion to your endpoint before anything is saved. If the test fails, nothing is created — the form stays filled in and the error points at the field to fix: a rejected key highlights API key, an unknown model name highlights Model ID, an unreachable or timed-out endpoint highlights Endpoint URL, and a too-high Max output tokens or a rejected request parameter is called out by name. From the failure banner you can either Edit the form and test again, or Save anyway to store the config without a passing test.

Save without testing skips the test entirely — useful when the endpoint is temporarily down, a self-hosted model is cold-starting, or you don’t want to spend a request on a quota-limited endpoint.

The model list shows the outcome as a chip next to each self-managed model: Verified (last test passed), Untested (saved without a passing test), or Failed (a later re-test failed — hover the chip for the reason). Kindo’s built-in global models are managed for you and carry no chip.

Add a Global Model via API

curl -X POST <API_URL>/internal/openapi/admin/model/new \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <UM_INTERNAL_API_KEY>' \
  -d '{
    "orgId": "<YOUR_ORG_ID>",
    "userId": "<YOUR_USER_ID>",
    "displayName": "Model Display Name",
    "modelProviderDisplayName": "Provider Name",
    "type": "CHAT",
    "contextWindow": 200000,
    "metadata": {
      "type": "Text Generation",
      "costTier": "HIGH",
      "usageTag": "Chat + Agents",
      "description": "Model description",
      "modelCreator": "Provider Name"
    },
    "litellmModelName": "model-name",
    "litellmParams": {
      "model": "provider/model-name",
      "api_key": "<API_KEY>",
      "max_tokens": 64000
    }
  }'

Note

Ensure modelProviderDisplayName matches the display name in the ModelProvider table. Otherwise, a new ModelProvider record will be created. Also verify that LiteLLM params are correct for the specific model, as defaults vary by provider.

Delete with Replacement

curl -X POST <API_URL>/internal/openapi/admin/model/delete-with-replacement \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <UM_INTERNAL_API_KEY>' \
  -d '{
    "deletingModelId": "<OLD_MODEL_ID>",
    "replacementModelId": "<NEW_MODEL_ID>",
    "orgId": "<YOUR_ORG_ID>",
    "userId": "<YOUR_USER_ID>"
  }'

Update Parameters on an Existing Model

To modify LiteLLM parameters for an existing model, update the LiteLLM database directly:

UPDATE "public"."LiteLLM_ProxyModelTable"
SET "litellm_params" = jsonb_set(
  "litellm_params",
  '{max_tokens}',
  '64000'::jsonb
)
WHERE "model_name" = 'your-model-name';

Tip

When adding models to dev/prod, be mindful of which region you are using to manage quota efficiently. Separate dev and prod to avoid rate-limit outages during local testing.