---
title: Configuration
description: Configure Kit using config files, environment variables, and CLI flags.
---

# Configuration

Kit looks for configuration in the following locations, in order of priority:

1. CLI flags
2. Environment variables (with `KIT_` prefix)
3. `./.kit.yml` / `./.kit.yaml` / `./.kit.json` (project-local)
4. `~/.kit.yml` / `~/.kit.yaml` / `~/.kit.json` (global)

## Basic configuration

Create `~/.kit.yml`:

```yaml
model: anthropic/claude-sonnet-latest
max-tokens: 4096
temperature: 0.7
stream: true
```

## All configuration keys

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `model` | string | `anthropic/claude-sonnet-latest` | Model to use (provider/model format) |
| `max-tokens` | int | `4096` | Maximum tokens in response |
| `temperature` | float | `0.7` | Randomness 0.0–1.0 |
| `top-p` | float | `0.95` | Nucleus sampling 0.0–1.0 |
| `top-k` | int | `40` | Limit top K tokens |
| `stream` | bool | `true` | Enable streaming output |
| `debug` | bool | `false` | Enable debug logging |
| `compact` | bool | `false` | Enable compact output mode |
| `system-prompt` | string | — | System prompt text or file path |
| `max-steps` | int | `0` | Maximum agent steps (0 = unlimited) |
| `thinking-level` | string | `off` | Extended thinking: off, minimal, low, medium, high |
| `provider-api-key` | string | — | API key for the provider |
| `provider-url` | string | — | Base URL for provider API |
| `tls-skip-verify` | bool | `false` | Skip TLS certificate verification |
| `stop-sequences` | list | — | Custom stop sequences |
| `theme` | object or string | — | UI theme ([inline overrides or file path](/themes)) |
| `prompt-templates` | bool | `true` | Enable prompt template loading |
| `prompt-template` | string | — | Specific template to load by name |

## Environment variables

Any configuration key can be set via environment variable with the `KIT_` prefix. Hyphens become underscores:

```bash
export KIT_MODEL="openai/gpt-4o"
export KIT_MAX_TOKENS="8192"
export KIT_TEMPERATURE="0.5"
```

Provider API keys use their own environment variables:

```bash
export ANTHROPIC_API_KEY="sk-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="..."
```

## MCP server configuration

Add external MCP servers to your `.kit.yml`:

```yaml
mcpServers:
  filesystem:
    type: local
    command: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"]
    environment:
      LOG_LEVEL: "info"
    allowedTools: ["read_file", "write_file"]
    excludedTools: ["delete_file"]

  search:
    type: remote
    url: "https://mcp.example.com/search"
```

### MCP server fields

| Field | Type | Description |
|-------|------|-------------|
| `type` | string | `local` (stdio) or `remote` (streamable HTTP) |
| `command` | list | Command and args for local servers |
| `environment` | map | Environment variables for the server process |
| `url` | string | URL for remote servers |
| `allowedTools` | list | Whitelist of tool names to expose |
| `excludedTools` | list | Blacklist of tool names to hide |

A legacy format with `transport`, `args`, `env`, and `headers` fields is also supported.

## Custom models

Define custom models in your `.kit.yml` for use with the `custom` provider. This is useful for self-hosted models or API endpoints not in the built-in database:

```yaml
customModels:
  my-model:
    name: "My Custom Model"
    baseUrl: "http://localhost:8080/v1"
    apiKey: "my-secret-key"
    reasoning: true
    temperature: true
    cost:
      input: 0.002
      output: 0.004
    limit:
      context: 128000
      output: 32000
```

### Custom model fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Display name for the model |
| `baseUrl` | string | No | Per-model base URL override; when set, `--provider-url` is not required |
| `apiKey` | string | No | Per-model API key override |
| `reasoning` | bool | No | Whether the model supports reasoning/thinking |
| `temperature` | bool | No | Whether the model supports temperature adjustment |
| `cost.input` | float | No | Cost per 1K input tokens |
| `cost.output` | float | No | Cost per 1K output tokens |
| `limit.context` | int | Yes | Maximum context window in tokens |
| `limit.output` | int | No | Maximum output tokens |

Use with a per-model `baseUrl` (no `--provider-url` needed):

```bash
kit --model custom/my-model "Hello"
```

Or override the base URL at runtime:

```bash
kit --provider-url "http://localhost:8080/v1" --model custom/my-model "Hello"
```

When `--provider-url` is specified without `--model`, Kit defaults to `custom/custom` which has zero cost tracking and a 262K context window.

## Theme configuration

```yaml
# Inline partial overrides (unspecified fields inherit from default)
theme:
  primary:
    light: "#8839ef"
    dark: "#cba6f7"
  error:
    dark: "#FF0000"
```

```yaml
# Reference external theme file
theme: "./themes/my-custom-theme.yml"
```

See [Themes](/themes) for the full theme file format, built-in themes, and the extension theme API.

## Preferences persistence

Kit automatically saves your UI preferences across sessions to `~/.config/kit/preferences.yml`:

- **Theme** — Set via `/theme <name>` or `ctx.SetTheme()`
- **Model** — Set via `/model <name>` or the model selector
- **Thinking level** — Set via `/thinking <level>` or Shift+Tab cycling

These preferences are restored on next launch. Precedence (highest to lowest):
1. CLI flags (`--model`, `--thinking-level`)
2. Config file (`model:`, `thinking-level:`)
3. Saved preferences (`~/.config/kit/preferences.yml`)
4. Default values
