# Reference: configuration file

> Neutral, exhaustive description of the YAML file read by `mm`. Every key is optional; a key left out keeps its built-in default. The file is decoded on top of the defaults, so unknown keys are ignored.

## Top-level keys

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `provider` | string | `dmr` | Registry key of the LLM server: `dmr` or `llamacpp`. Overridden by `AGENT_PROVIDER`. |
| `model` | string | `huggingface.co/jetbrains/mellum2-12b-a2.5b-instruct-gguf-q4_k_m:Q4_K_M` | Model identifier in the provider's naming. Overridden by `AGENT_MODEL`. |
| `baseUrl` | string | `""` (provider default) | OpenAI-compatible endpoint tried first. Overridden by `AGENT_BASE_URL`. |
| `fallback` | string or absent | absent (provider default) | Endpoint used when `baseUrl` does not answer `/models` within 2 s. Absent = provider default; `""` = no fallback. |
| `apiKeyEnv` | string | `""` (provider default) | Name of the environment variable holding the API key. |
| `contextWindow` | int | `0` | Tokens the server serves. `0` = ask the server, else unknown. Must be ≥ 0. |
| `maxOutput` | int | `16000` | Maximum characters a tool returns to the model; longer output keeps its head and up to 2000 characters of tail. Must be > 0. |
| `maxTurns` | int | `10` | Maximum model ↔ tools round trips per question. Must be > 0. |
| `previewLines` | int | `20` | Lines of a command's output echoed to the terminal. `0` disables the echo. Must be ≥ 0. |
| `displayCommands` | bool | `false` | Print the numbered list of commands and file operations after each answer. |
| `system` | string | built-in prompt | The system prompt, first message of every history. |
| `skillsDir` | string | `skills` | Directory holding the skills, as `<name>.md` files or `<name>/SKILL.md` directories. A relative path is resolved from the directory `mm` is started in (terminal mode, or ACP mode without a config file), or next to the config file (ACP mode with one); the banner warns with the absolute path when nothing is found there. |
| `editTools` | bool | `true` | Declare `read_file`, `write_file`, `edit_file`. `false` leaves `bash` and `read_skill` only. |
| `sampling` | map | `temperature: 0.0`, `top_p: 0.9`, `max_tokens: 4096` | Generation settings, OpenAI API key names, passed to the server. The shipped `agent.yaml` adds `parallel_tool_calls: false`. |
| `watchdogTimeout` | duration | `20s` | Silence tolerated between two streamed tokens before the connection is declared hung. Doubled for summary requests. |
| `context` | map | see below | Automatic history compression. |

## `context` keys

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | bool | `false` | Turn the automatic compression on. `/compact` works regardless. |
| `threshold` | int | `75` | Percentage of the context window beyond which the history is compressed before the next question. Between 1 and 100. |
| `maxMessages` | int | `80` | Message count that triggers a compression when the window is unknown or the estimate is low. `0` disables. Must be ≥ 0. |
| `keepLastTurns` | int | `3` | Question turns kept raw at the end of the history. Must be ≥ 1. |
| `summaryMaxTokens` | int | `1200` | `max_tokens` of the summary request. Must be > 0. |
| `prompt` | string | `""` | Replaces the built-in summary prompt when not empty. |
| `showStats` | bool | `true` | Print the one-line `🗜️` report after each compression. |

## Provider defaults

| Provider | `baseUrl` | `fallback` | `apiKeyEnv` | Key required |
|----------|-----------|------------|-------------|--------------|
| `dmr` | `http://localhost:12434/engines/v1` | `http://host.docker.internal:12434/engines/v1` | none | no |
| `llamacpp` | `http://127.0.0.1:8080/v1` | none | `LLAMA_API_KEY` | no |

## Validation errors

Reported as `[config error: <path>: <message>]`, exit code 1.

| Message | Cause |
|---------|-------|
| `provider must not be empty` | `provider: ""` |
| `model must not be empty` | `model: ""` |
| `contextWindow must be >= 0` | negative value |
| `maxOutput must be > 0` | zero or negative |
| `maxTurns must be > 0` | zero or negative |
| `previewLines must be >= 0` | negative value |
| `context.threshold must be between 1 and 100` | out of range |
| `context.keepLastTurns must be >= 1` | zero or negative |
| `context.summaryMaxTokens must be > 0` | zero or negative |
| `context.maxMessages must be >= 0` | negative value |
| `unknown provider "x" (known: dmr, llamacpp)` | Reported by the engine, as `[engine error: …]`. |

A start-up warning, not an error, is printed when `context.enabled` is `true`, the window is unknown and `context.maxMessages` is `0`.

## Shipped files

| File | Purpose |
|------|---------|
| `agent.yaml` | Docker Model Runner set-up: `provider: dmr`, `maxTurns: 40`, `displayCommands: true`, compression off, a system prompt named "Bob" that describes the skills and file-editing rules. |
| `agent.llamacpp.yaml` | llama.cpp set-up: `provider: llamacpp`, `baseUrl: http://127.0.0.1:8080/v1`, `fallback: ""`, compression on. |

### Example

```yaml
provider: llamacpp
model: my-alias
baseUrl: http://127.0.0.1:8080/v1
fallback: ""
maxTurns: 40
context:
  enabled: true
```