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.
`showThinking`	bool	`true`	Show what a thinking model reasons about before it answers. Only the display is optional: the reasoning is always read off the wire, because it is what keeps the watchdog alive while the model thinks. See Thinking models.
`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.
`bashTool`	bool	`true`	Declare `bash`. `false` removes it: the model can still read and edit files (`editTools`) and load skills, but never runs a command. Reword a system prompt that still announces a bash tool.
`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.
`sessions`	map	see below	Persistent, per-project sessions.
`lsp`	map	see below	Language servers behind the `lsp` tool. No server listed = no tool.
`tui`	bool	`false`	Start in the single-window mode without the `-tui` flag. Falls back to the line mode when stdin or stdout is not a terminal; ignored with `-acp`.
`permissions`	string	`auto`	`ask`: in the window mode, `bash`, `write_file` and `edit_file` wait for the user's answer (`a`/`s`/`r`) before running. `auto`: tools run at once. The line mode and the ACP façade do not read it (ACP has its own dialog). Must be `auto` or `ask`.

`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.

`sessions` keys

Key	Type	Default	Description
`sessions.enabled`	bool	`false`	Save every conversation to a file, rewritten after each turn, `/compact` and `/new`. The file also records, outside the history, every error shown (`errors` array: failed generation, failed compaction, failed `/resume`). Enables `/sessions` and `/resume` in the terminal and `session/load` over ACP.
`sessions.dir`	string	`.mm/sessions`	Directory of the session files, one `<id>.json` each. Relative to the directory `mm` is started from (terminal) or to the session's `cwd` (ACP); an absolute path is used as-is. Must not be empty.

`lsp` keys

Key	Type	Default	Description
`lsp.servers`	list	`[]`	One entry per language server. The file extension picks the server.
`lsp.servers[].name`	string	—	How the banner, the tool description and the warnings call it. Required.
`lsp.servers[].command`	string	—	The executable, looked up on the `PATH` at start-up. Required. Not found: warning, server skipped.
`lsp.servers[].args`	list of strings	`[]`	Its arguments (many servers need `--stdio`).
`lsp.servers[].extensions`	list of strings	—	File extensions it serves, with the dot (`.go`, `.ts`). Required, at least one; matched case-insensitively; an extension may be served by one server only.

lsp:
  servers:
    - name: gopls
      command: gopls
      extensions: [".go"]
    - name: typescript
      command: typescript-language-server
      args: ["--stdio"]
      extensions: [".ts", ".tsx", ".js", ".jsx"]

The shipped agent.lsp.yaml is agent.dmr.yaml with this block on (gopls active, other servers ready to uncomment) and a system prompt that says when to use the tool.

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
`sessions.dir must not be empty`	empty string
`lsp.servers[N].name must not be empty`	a server without `name`
`lsp.servers[N].command must not be empty`	a server without `command`
`lsp.servers[N].extensions must list at least one extension`	a server without `extensions`
`lsp.servers[N].extensions: "go" must start with a dot, like ".go"`	an extension without its dot
`lsp.servers[N]: extension ".ts" is already served by "typescript"`	two servers on one extension
`permissions must be "auto" or "ask"`	any other 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

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

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126


# 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. |
| `showThinking` | bool | `true` | Show what a thinking model reasons about before it answers. Only the display is optional: the reasoning is always read off the wire, because it is what keeps the watchdog alive while the model thinks. See [Thinking models](../explanation/thinking-models.md). |
| `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. |
| `bashTool` | bool | `true` | Declare `bash`. `false` removes it: the model can still read and edit files (`editTools`) and load skills, but never runs a command. Reword a system prompt that still announces a bash tool. |
| `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. |
| `sessions` | map | see below | Persistent, per-project sessions. |
| `lsp` | map | see below | Language servers behind the `lsp` tool. No server listed = no tool. |
| `tui` | bool | `false` | Start in the single-window mode without the `-tui` flag. Falls back to the line mode when stdin or stdout is not a terminal; ignored with `-acp`. |
| `permissions` | string | `auto` | `ask`: in the window mode, `bash`, `write_file` and `edit_file` wait for the user's answer (`a`/`s`/`r`) before running. `auto`: tools run at once. The line mode and the ACP façade do not read it (ACP has its own dialog). Must be `auto` or `ask`. |

## `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. |

## `sessions` keys

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `sessions.enabled` | bool | `false` | Save every conversation to a file, rewritten after each turn, `/compact` and `/new`. The file also records, outside the history, every error shown (`errors` array: failed generation, failed compaction, failed `/resume`). Enables `/sessions` and `/resume` in the terminal and `session/load` over ACP. |
| `sessions.dir` | string | `.mm/sessions` | Directory of the session files, one `<id>.json` each. Relative to the directory `mm` is started from (terminal) or to the session's `cwd` (ACP); an absolute path is used as-is. Must not be empty. |

## `lsp` keys

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `lsp.servers` | list | `[]` | One entry per language server. The file extension picks the server. |
| `lsp.servers[].name` | string | — | How the banner, the tool description and the warnings call it. Required. |
| `lsp.servers[].command` | string | — | The executable, looked up on the `PATH` at start-up. Required. Not found: warning, server skipped. |
| `lsp.servers[].args` | list of strings | `[]` | Its arguments (many servers need `--stdio`). |
| `lsp.servers[].extensions` | list of strings | — | File extensions it serves, with the dot (`.go`, `.ts`). Required, at least one; matched case-insensitively; an extension may be served by one server only. |

```yaml
lsp:
  servers:
    - name: gopls
      command: gopls
      extensions: [".go"]
    - name: typescript
      command: typescript-language-server
      args: ["--stdio"]
      extensions: [".ts", ".tsx", ".js", ".jsx"]
```

The shipped `agent.lsp.yaml` is `agent.dmr.yaml` with this block on (gopls active, other servers ready to uncomment) and a system prompt that says when to use the tool.

## 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 |
| `sessions.dir must not be empty` | empty string |
| `lsp.servers[N].name must not be empty` | a server without `name` |
| `lsp.servers[N].command must not be empty` | a server without `command` |
| `lsp.servers[N].extensions must list at least one extension` | a server without `extensions` |
| `lsp.servers[N].extensions: "go" must start with a dot, like ".go"` | an extension without its dot |
| `lsp.servers[N]: extension ".ts" is already served by "typescript"` | two servers on one extension |
| `permissions must be "auto" or "ask"` | any other 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
```