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.
`fetchContentTool`	bool	`false`	Declare `fetch_content`, which fetches web pages as Markdown. Off by default: it is the only built-in tool that reaches the network.
`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`. `max_tokens` also bounds one tool call: a `write_file` of a long document (or a thinking model's reasoning plus the call) can hit it, and the call is then cut off. mm hands it back to the model twice, asking for smaller pieces, then stops with `the model hit max_tokens (N) while writing a tool call`; raise the value if that happens. With streaming, mm also asks the server for token counts (`stream_options.include_usage`).
`watchdogTimeout`	duration	`20s`	Silence tolerated between two streamed tokens before the connection is declared hung. Doubled for summary requests.
`firstTokenTimeout`	duration	`3m`	Silence tolerated before a model call's first token, while the server reads the prompt (every round trip of a turn has one). Never shorter than `watchdogTimeout`; must be >= 0. With a llama.cpp server (`dmr`, `llamacpp`) mm asks for `return_progress`: each progress report restarts this clock, and the spinner shows `Reading the prompt 12.0k/25.3k tokens`. On a timeout the watchdog says `no first token from the server after …` (before the first token) or `connection hang detected after …` (after).
`context`	map	see below	Automatic history compression.
`sessions`	map	see below	Persistent, per-project sessions.
`acp`	map	see below	How `mm -acp` introduces itself to the editor.
`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. A thinking model's reasoning counts against it: on `dmr` and `llamacpp` the summary request turns reasoning off (`chat_template_kwargs.enable_thinking: false`); elsewhere, if the error says the model "reasoned until the limit", raise it.
`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.

`acp` keys

Key	Type	Default	Description
`acp.name`	string	`bob`	`agentInfo.name` in the `initialize` response. Must not be empty.
`acp.title`	string	`Bob (bash-first agent)`	`agentInfo.title`, the name the editor may display. Empty: not sent.

The version is not configurable: agentInfo.version is always the binary's, as printed by mm --version.

`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
`acp.name must not be empty`	empty or blank 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
127
128
129
130
131
132
133
134
135
136
137
138
139


# 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. |
| `fetchContentTool` | bool | `false` | Declare `fetch_content`, which fetches web pages as Markdown. Off by default: it is the only built-in tool that reaches the network. |
| `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`. `max_tokens` also bounds one tool call: a `write_file` of a long document (or a thinking model's reasoning plus the call) can hit it, and the call is then cut off. mm hands it back to the model twice, asking for smaller pieces, then stops with `the model hit max_tokens (N) while writing a tool call`; raise the value if that happens. With streaming, mm also asks the server for token counts (`stream_options.include_usage`). |
| `watchdogTimeout` | duration | `20s` | Silence tolerated between two streamed tokens before the connection is declared hung. Doubled for summary requests. |
| `firstTokenTimeout` | duration | `3m` | Silence tolerated before a model call's first token, while the server reads the prompt (every round trip of a turn has one). Never shorter than `watchdogTimeout`; must be >= 0. With a llama.cpp server (`dmr`, `llamacpp`) mm asks for `return_progress`: each progress report restarts this clock, and the spinner shows `Reading the prompt 12.0k/25.3k tokens`. On a timeout the watchdog says `no first token from the server after …` (before the first token) or `connection hang detected after …` (after). |
| `context` | map | see below | Automatic history compression. |
| `sessions` | map | see below | Persistent, per-project sessions. |
| `acp` | map | see below | How `mm -acp` introduces itself to the editor. |
| `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. A thinking model's reasoning counts against it: on `dmr` and `llamacpp` the summary request turns reasoning off (`chat_template_kwargs.enable_thinking: false`); elsewhere, if the error says the model "reasoned until the limit", raise it. |
| `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. |

## `acp` keys

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `acp.name` | string | `bob` | `agentInfo.name` in the `initialize` response. Must not be empty. |
| `acp.title` | string | `Bob (bash-first agent)` | `agentInfo.title`, the name the editor may display. Empty: not sent. |

The version is not configurable: `agentInfo.version` is always the binary's, as printed by `mm --version`.

## `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 |
| `acp.name must not be empty` | empty or blank 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
```