Custom Models

Kilo Code ships with a curated list of models for each provider, but you can use any model your provider supports — including models that aren't in the built-in list. This is useful for:

• Using a newly released model before it's added to the built-in catalog
• Running a custom or fine-tuned model via LM Studio, Ollama, or another local provider
• Connecting to a self-hosted model behind an OpenAI-compatible API
• Configuring model-specific options like token limits, pricing, or reasoning settings

Defining a Custom Model

Add custom models under the provider.<provider_id>.models key in your config file. The model key becomes the model ID you reference elsewhere.

{
  "$schema": "https://app.kilo.ai/config.json",
  "model": "lmstudio/my-custom-model",
  "provider": {
    "lmstudio": {
      "models": {
        "my-custom-model": {
          "name": "My Custom Model",
        },
      },
    },
  },
}

The model key uses the format provider_id/model_id, where:

• provider_id is the key under provider (e.g., lmstudio, ollama, openai, anthropic, openai-compatible)
• model_id is the key under provider.<provider_id>.models (e.g., my-custom-model)

Model Configuration Fields

All fields are optional. When a model ID matches one already in the built-in catalog, your values are merged on top of the defaults — you only need to specify what you want to override.

Examples

Local model with LM Studio

Register a model that LM Studio serves under a custom name:

{
  "$schema": "https://app.kilo.ai/config.json",
  "model": "lmstudio/deepseek-r1-0528",
  "provider": {
    "lmstudio": {
      "models": {
        "deepseek-r1-0528": {
          "name": "DeepSeek R1 0528",
        },
      },
    },
  },
}

Local model with Ollama

{
  "$schema": "https://app.kilo.ai/config.json",
  "model": "ollama/my-finetune:latest",
  "provider": {
    "ollama": {
      "models": {
        "my-finetune:latest": {
          "name": "My Fine-tuned Model",
          "tool_call": true,
          "limit": {
            "context": 32768,
            "output": 8192,
          },
        },
      },
    },
  },
}

New or unlisted model from a cloud provider

Use a model that's not yet in the built-in catalog:

{
  "$schema": "https://app.kilo.ai/config.json",
  "model": "openai/gpt-6-preview",
  "provider": {
    "openai": {
      "models": {
        "gpt-6-preview": {
          "name": "GPT-6 Preview",
          "tool_call": true,
          "reasoning": true,
          "limit": {
            "context": 200000,
            "output": 32768,
          },
        },
      },
    },
  },
}

OpenAI-compatible provider with a custom endpoint

Connect to any provider that exposes an OpenAI-compatible API:

{
  "$schema": "https://app.kilo.ai/config.json",
  "model": "openai-compatible/my-model",
  "provider": {
    "openai-compatible": {
      "options": {
        "apiKey": "{env:MY_PROVIDER_API_KEY}",
        "baseURL": "https://api.my-provider.com/v1",
      },
      "models": {
        "my-model": {
          "name": "My Custom Model",
          "tool_call": true,
          "limit": {
            "context": 128000,
            "output": 16384,
          },
        },
      },
    },
  },
}

Configuring model options and variants

Override options or define reasoning variants for a built-in model:

{
  "$schema": "https://app.kilo.ai/config.json",
  "provider": {
    "anthropic": {
      "models": {
        "claude-sonnet-4-20250514": {
          "options": {
            "thinking": {
              "type": "enabled",
              "budgetTokens": 16000,
            },
          },
          "variants": {
            "thinking-high": {
              "thinking": {
                "type": "enabled",
                "budgetTokens": 32000,
              },
            },
            "fast": {
              "disabled": true,
            },
          },
        },
      },
    },
  },
}

Using the id field to map model names

If the model key in your config differs from what the provider expects, use the id field:

{
  "$schema": "https://app.kilo.ai/config.json",
  "model": "lmstudio/my-local-llama",
  "provider": {
    "lmstudio": {
      "models": {
        "my-local-llama": {
          "id": "meta-llama-3.1-8b-instruct",
          "name": "Llama 3.1 8B (Local)",
        },
      },
    },
  },
}

Here my-local-llama is the key you use in your config and model picker, while meta-llama-3.1-8b-instruct is the actual model identifier sent to the LM Studio API.

Model Loading Priority

When Kilo starts, it resolves the active model in this order:

1. The --model (or -m) command-line flag
2. The model key in your config file
3. The last used model from your previous session
4. The first available model using an internal priority

The format for all of these is provider_id/model_id.

Provider-Level Options

You can also set options that apply to all models from a provider:

{
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}",
        "baseURL": "https://my-proxy.example.com/v1",
        "timeout": 120000,
      },
    },
  },
}

Filtering Available Models

Control which models appear in the model picker for a provider using allowlists and blocklists:

{
  "provider": {
    "openai": {
      "whitelist": ["gpt-5", "gpt-5-mini"],
      "blacklist": ["gpt-4-turbo"],
    },
  },
}

• whitelist — only these model IDs are available from this provider
• blacklist — these model IDs are hidden from this provider

Troubleshooting

Model doesn't appear in the model picker:

• Verify the provider has valid credentials configured (API key, or local server running)
• Check that the model key matches what you set in "model": "provider/model-key"
• Run kilo models to list all available models and confirm your provider is active

Model errors or unexpected behavior:

• Set tool_call: true if you need the model to use tools (file editing, terminal, etc.)
• Set limit.context and limit.output to match the model's actual capabilities
• For local models, ensure your inference server is running and accessible at the configured URL