Référence : fichier de configuration

Description neutre et exhaustive du fichier YAML lu par mm. Chaque clé est optionnelle ; une clé omise garde sa valeur par défaut intégrée. Le fichier est décodé par-dessus les valeurs par défaut, donc les clés inconnues sont ignorées.

Clés de premier niveau

Clé	Type	Défaut	Description
`provider`	chaîne	`dmr`	Clé du registre du serveur LLM : `dmr` ou `llamacpp`. Surchargée par `AGENT_PROVIDER`.
`model`	chaîne	`huggingface.co/jetbrains/mellum2-12b-a2.5b-instruct-gguf-q4_k_m:Q4_K_M`	Identifiant du modèle dans la nomenclature du fournisseur. Surchargé par `AGENT_MODEL`.
`baseUrl`	chaîne	`""` (défaut du fournisseur)	Point d'accès compatible OpenAI essayé en premier. Surchargé par `AGENT_BASE_URL`.
`fallback`	chaîne ou absente	absente (défaut du fournisseur)	Point d'accès utilisé quand `baseUrl` ne répond pas sur `/models` en 2 s. Absente = défaut du fournisseur ; `""` = pas de repli.
`apiKeyEnv`	chaîne	`""` (défaut du fournisseur)	Nom de la variable d'environnement qui contient la clé d'API.
`contextWindow`	entier	`0`	Tokens servis par le serveur. `0` = demander au serveur, sinon inconnu. Doit être ≥ 0.
`maxOutput`	entier	`16000`	Nombre maximal de caractères qu'un outil renvoie au modèle ; au-delà, la sortie garde son début et jusqu'à 2000 caractères de fin. Doit être > 0.
`maxTurns`	entier	`10`	Nombre maximal d'allers-retours modèle ↔ outils par question. Doit être > 0.
`previewLines`	entier	`20`	Lignes de la sortie d'une commande affichées dans le terminal. `0` désactive l'affichage. Doit être ≥ 0.
`displayCommands`	booléen	`false`	Affiche la liste numérotée des commandes et opérations sur fichiers après chaque réponse.
`showThinking`	booléen	`true`	Affiche ce qu'un modèle à raisonnement réfléchit avant de répondre. Seul l'affichage est optionnel : le raisonnement est toujours lu sur le fil, car c'est lui qui maintient le chien de garde en vie pendant que le modèle réfléchit. Voir Modèles à raisonnement.
`system`	chaîne	prompt intégré	Le prompt système, premier message de chaque historique.
`skillsDir`	chaîne	`skills`	Répertoire des skills, sous forme de fichiers `<nom>.md` ou de répertoires `<nom>/SKILL.md`. Un chemin relatif est résolu depuis le répertoire de lancement de `mm` (mode terminal, ou mode ACP sans fichier de configuration), ou à côté du fichier de configuration (mode ACP avec fichier) ; la bannière avertit avec le chemin absolu quand rien n'y est trouvé.
`bashTool`	booléen	`true`	Déclare `bash`. `false` le retire : le modèle peut encore lire et modifier des fichiers (`editTools`) et charger des skills, mais n'exécute jamais de commande. Reformulez un prompt système qui annonce encore un outil bash.
`editTools`	booléen	`true`	Déclare `read_file`, `write_file`, `edit_file`. `false` ne laisse que `bash` et `read_skill`.
`sampling`	dictionnaire	`temperature: 0.0`, `top_p: 0.9`, `max_tokens: 4096`	Paramètres de génération, noms de l'API OpenAI, transmis au serveur. L'`agent.yaml` livré ajoute `parallel_tool_calls: false`.
`watchdogTimeout`	durée	`20s`	Silence toléré entre deux tokens diffusés avant de déclarer la connexion bloquée. Doublé pour les requêtes de résumé.
`context`	dictionnaire	voir ci-dessous	Compression automatique de l'historique.
`sessions`	dictionnaire	voir ci-dessous	Sessions persistantes, par projet.
`lsp`	dictionnaire	voir ci-dessous	Serveurs de langage derrière l'outil `lsp`. Aucun serveur listé = pas d'outil.
`tui`	bool	`false`	Démarre dans le mode fenêtre unique sans l'option `-tui`. Retombe sur le mode ligne quand stdin ou stdout n'est pas un terminal ; ignoré avec `-acp`.
`permissions`	chaîne	`auto`	`ask` : en mode fenêtre, `bash`, `write_file` et `edit_file` attendent la réponse de l'utilisateur (`a`/`s`/`r`) avant de s'exécuter. `auto` : les outils s'exécutent aussitôt. Le mode ligne et la façade ACP ne la lisent pas (ACP a son propre dialogue). Doit valoir `auto` ou `ask`.

Clés de `context`

Clé	Type	Défaut	Description
`enabled`	booléen	`false`	Active la compression automatique. `/compact` fonctionne dans tous les cas.
`threshold`	entier	`75`	Pourcentage de la fenêtre de contexte au-delà duquel l'historique est compressé avant la question suivante. Entre 1 et 100.
`maxMessages`	entier	`80`	Nombre de messages qui déclenche une compression quand la fenêtre est inconnue ou l'estimation trop basse. `0` désactive. Doit être ≥ 0.
`keepLastTurns`	entier	`3`	Tours de question conservés bruts en fin d'historique. Doit être ≥ 1.
`summaryMaxTokens`	entier	`1200`	`max_tokens` de la requête de résumé. Doit être > 0.
`prompt`	chaîne	`""`	Remplace le prompt de résumé intégré quand non vide.
`showStats`	booléen	`true`	Affiche le rapport `🗜️` d'une ligne après chaque compression.

Clés de `sessions`

Clé	Type	Défaut	Description
`sessions.enabled`	bool	`false`	Enregistre chaque conversation dans un fichier, réécrit après chaque tour, `/compact` et `/new`. Le fichier enregistre aussi, hors de l'historique, chaque erreur affichée (tableau `errors` : génération échouée, compression échouée, `/resume` échoué). Active `/sessions` et `/resume` dans le terminal et `session/load` en ACP.
`sessions.dir`	chaîne	`.mm/sessions`	Répertoire des fichiers de session, un `<id>.json` chacun. Relatif au répertoire de lancement de `mm` (terminal) ou au `cwd` de la session (ACP) ; un chemin absolu est utilisé tel quel. Ne doit pas être vide.

Clés de `lsp`

Clé	Type	Défaut	Description
`lsp.servers`	liste	`[]`	Une entrée par serveur de langage. L'extension du fichier choisit le serveur.
`lsp.servers[].name`	chaîne	—	Le nom qu'utilisent la bannière, la description de l'outil et les avertissements. Obligatoire.
`lsp.servers[].command`	chaîne	—	L'exécutable, cherché sur le `PATH` au démarrage. Obligatoire. Introuvable : avertissement, serveur ignoré.
`lsp.servers[].args`	liste de chaînes	`[]`	Ses arguments (beaucoup de serveurs veulent `--stdio`).
`lsp.servers[].extensions`	liste de chaînes	—	Les extensions de fichier qu'il sert, avec le point (`.go`, `.ts`). Obligatoire, au moins une ; comparaison insensible à la casse ; une extension ne peut être servie que par un serveur.

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

Le fichier livré agent.lsp.yaml est agent.dmr.yaml avec ce bloc actif (gopls, les autres serveurs prêts à décommenter) et un prompt système qui dit quand utiliser l'outil.

Valeurs par défaut des fournisseurs

Fournisseur	`baseUrl`	`fallback`	`apiKeyEnv`	Clé requise
`dmr`	`http://localhost:12434/engines/v1`	`http://host.docker.internal:12434/engines/v1`	aucune	non
`llamacpp`	`http://127.0.0.1:8080/v1`	aucun	`LLAMA_API_KEY`	non

Erreurs de validation

Signalées sous la forme [config error: <chemin>: <message>], code de sortie 1.

Message	Cause
`provider must not be empty`	`provider: ""`
`model must not be empty`	`model: ""`
`contextWindow must be >= 0`	valeur négative
`maxOutput must be > 0`	zéro ou négatif
`maxTurns must be > 0`	zéro ou négatif
`previewLines must be >= 0`	valeur négative
`context.threshold must be between 1 and 100`	hors intervalle
`context.keepLastTurns must be >= 1`	zéro ou négatif
`context.summaryMaxTokens must be > 0`	zéro ou négatif
`context.maxMessages must be >= 0`	valeur négative
`sessions.dir must not be empty`	chaîne vide
`lsp.servers[N].name must not be empty`	un serveur sans `name`
`lsp.servers[N].command must not be empty`	un serveur sans `command`
`lsp.servers[N].extensions must list at least one extension`	un serveur sans `extensions`
`lsp.servers[N].extensions: "go" must start with a dot, like ".go"`	une extension sans son point
`lsp.servers[N]: extension ".ts" is already served by "typescript"`	deux serveurs sur une même extension
`permissions must be "auto" or "ask"`	toute autre valeur
`unknown provider "x" (known: dmr, llamacpp)`	Signalée par le moteur, sous la forme `[engine error: …]`.

Un avertissement au démarrage, et non une erreur, est affiché quand context.enabled vaut true, que la fenêtre est inconnue et que context.maxMessages vaut 0.

Fichiers livrés

Fichier	Rôle
`agent.yaml`	Configuration Docker Model Runner : `provider: dmr`, `maxTurns: 40`, `displayCommands: true`, compression désactivée, un prompt système nommé « Bob » qui décrit les skills et les règles d'édition de fichiers.
`agent.llamacpp.yaml`	Configuration llama.cpp : `provider: llamacpp`, `baseUrl: http://127.0.0.1:8080/v1`, `fallback: ""`, compression activée.

Exemple

provider: llamacpp
model: mon-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


# Référence : fichier de configuration

> Description neutre et exhaustive du fichier YAML lu par `mm`. Chaque clé est optionnelle ; une clé omise garde sa valeur par défaut intégrée. Le fichier est décodé par-dessus les valeurs par défaut, donc les clés inconnues sont ignorées.

## Clés de premier niveau

| Clé | Type | Défaut | Description |
|-----|------|--------|-------------|
| `provider` | chaîne | `dmr` | Clé du registre du serveur LLM : `dmr` ou `llamacpp`. Surchargée par `AGENT_PROVIDER`. |
| `model` | chaîne | `huggingface.co/jetbrains/mellum2-12b-a2.5b-instruct-gguf-q4_k_m:Q4_K_M` | Identifiant du modèle dans la nomenclature du fournisseur. Surchargé par `AGENT_MODEL`. |
| `baseUrl` | chaîne | `""` (défaut du fournisseur) | Point d'accès compatible OpenAI essayé en premier. Surchargé par `AGENT_BASE_URL`. |
| `fallback` | chaîne ou absente | absente (défaut du fournisseur) | Point d'accès utilisé quand `baseUrl` ne répond pas sur `/models` en 2 s. Absente = défaut du fournisseur ; `""` = pas de repli. |
| `apiKeyEnv` | chaîne | `""` (défaut du fournisseur) | Nom de la variable d'environnement qui contient la clé d'API. |
| `contextWindow` | entier | `0` | Tokens servis par le serveur. `0` = demander au serveur, sinon inconnu. Doit être ≥ 0. |
| `maxOutput` | entier | `16000` | Nombre maximal de caractères qu'un outil renvoie au modèle ; au-delà, la sortie garde son début et jusqu'à 2000 caractères de fin. Doit être > 0. |
| `maxTurns` | entier | `10` | Nombre maximal d'allers-retours modèle ↔ outils par question. Doit être > 0. |
| `previewLines` | entier | `20` | Lignes de la sortie d'une commande affichées dans le terminal. `0` désactive l'affichage. Doit être ≥ 0. |
| `displayCommands` | booléen | `false` | Affiche la liste numérotée des commandes et opérations sur fichiers après chaque réponse. |
| `showThinking` | booléen | `true` | Affiche ce qu'un modèle à raisonnement réfléchit avant de répondre. Seul l'affichage est optionnel : le raisonnement est toujours lu sur le fil, car c'est lui qui maintient le chien de garde en vie pendant que le modèle réfléchit. Voir [Modèles à raisonnement](../explanation/thinking-models.md). |
| `system` | chaîne | prompt intégré | Le prompt système, premier message de chaque historique. |
| `skillsDir` | chaîne | `skills` | Répertoire des skills, sous forme de fichiers `<nom>.md` ou de répertoires `<nom>/SKILL.md`. Un chemin relatif est résolu depuis le répertoire de lancement de `mm` (mode terminal, ou mode ACP sans fichier de configuration), ou à côté du fichier de configuration (mode ACP avec fichier) ; la bannière avertit avec le chemin absolu quand rien n'y est trouvé. |
| `bashTool` | booléen | `true` | Déclare `bash`. `false` le retire : le modèle peut encore lire et modifier des fichiers (`editTools`) et charger des skills, mais n'exécute jamais de commande. Reformulez un prompt système qui annonce encore un outil bash. |
| `editTools` | booléen | `true` | Déclare `read_file`, `write_file`, `edit_file`. `false` ne laisse que `bash` et `read_skill`. |
| `sampling` | dictionnaire | `temperature: 0.0`, `top_p: 0.9`, `max_tokens: 4096` | Paramètres de génération, noms de l'API OpenAI, transmis au serveur. L'`agent.yaml` livré ajoute `parallel_tool_calls: false`. |
| `watchdogTimeout` | durée | `20s` | Silence toléré entre deux tokens diffusés avant de déclarer la connexion bloquée. Doublé pour les requêtes de résumé. |
| `context` | dictionnaire | voir ci-dessous | Compression automatique de l'historique. |
| `sessions` | dictionnaire | voir ci-dessous | Sessions persistantes, par projet. |
| `lsp` | dictionnaire | voir ci-dessous | Serveurs de langage derrière l'outil `lsp`. Aucun serveur listé = pas d'outil. |
| `tui` | bool | `false` | Démarre dans le mode fenêtre unique sans l'option `-tui`. Retombe sur le mode ligne quand stdin ou stdout n'est pas un terminal ; ignoré avec `-acp`. |
| `permissions` | chaîne | `auto` | `ask` : en mode fenêtre, `bash`, `write_file` et `edit_file` attendent la réponse de l'utilisateur (`a`/`s`/`r`) avant de s'exécuter. `auto` : les outils s'exécutent aussitôt. Le mode ligne et la façade ACP ne la lisent pas (ACP a son propre dialogue). Doit valoir `auto` ou `ask`. |

## Clés de `context`

| Clé | Type | Défaut | Description |
|-----|------|--------|-------------|
| `enabled` | booléen | `false` | Active la compression automatique. `/compact` fonctionne dans tous les cas. |
| `threshold` | entier | `75` | Pourcentage de la fenêtre de contexte au-delà duquel l'historique est compressé avant la question suivante. Entre 1 et 100. |
| `maxMessages` | entier | `80` | Nombre de messages qui déclenche une compression quand la fenêtre est inconnue ou l'estimation trop basse. `0` désactive. Doit être ≥ 0. |
| `keepLastTurns` | entier | `3` | Tours de question conservés bruts en fin d'historique. Doit être ≥ 1. |
| `summaryMaxTokens` | entier | `1200` | `max_tokens` de la requête de résumé. Doit être > 0. |
| `prompt` | chaîne | `""` | Remplace le prompt de résumé intégré quand non vide. |
| `showStats` | booléen | `true` | Affiche le rapport `🗜️` d'une ligne après chaque compression. |

## Clés de `sessions`

| Clé | Type | Défaut | Description |
|-----|------|--------|-------------|
| `sessions.enabled` | bool | `false` | Enregistre chaque conversation dans un fichier, réécrit après chaque tour, `/compact` et `/new`. Le fichier enregistre aussi, hors de l'historique, chaque erreur affichée (tableau `errors` : génération échouée, compression échouée, `/resume` échoué). Active `/sessions` et `/resume` dans le terminal et `session/load` en ACP. |
| `sessions.dir` | chaîne | `.mm/sessions` | Répertoire des fichiers de session, un `<id>.json` chacun. Relatif au répertoire de lancement de `mm` (terminal) ou au `cwd` de la session (ACP) ; un chemin absolu est utilisé tel quel. Ne doit pas être vide. |

## Clés de `lsp`

| Clé | Type | Défaut | Description |
|-----|------|--------|-------------|
| `lsp.servers` | liste | `[]` | Une entrée par serveur de langage. L'extension du fichier choisit le serveur. |
| `lsp.servers[].name` | chaîne | — | Le nom qu'utilisent la bannière, la description de l'outil et les avertissements. Obligatoire. |
| `lsp.servers[].command` | chaîne | — | L'exécutable, cherché sur le `PATH` au démarrage. Obligatoire. Introuvable : avertissement, serveur ignoré. |
| `lsp.servers[].args` | liste de chaînes | `[]` | Ses arguments (beaucoup de serveurs veulent `--stdio`). |
| `lsp.servers[].extensions` | liste de chaînes | — | Les extensions de fichier qu'il sert, avec le point (`.go`, `.ts`). Obligatoire, au moins une ; comparaison insensible à la casse ; une extension ne peut être servie que par un serveur. |

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

Le fichier livré `agent.lsp.yaml` est `agent.dmr.yaml` avec ce bloc actif (gopls, les autres serveurs prêts à décommenter) et un prompt système qui dit quand utiliser l'outil.

## Valeurs par défaut des fournisseurs

| Fournisseur | `baseUrl` | `fallback` | `apiKeyEnv` | Clé requise |
|-------------|-----------|------------|-------------|-------------|
| `dmr` | `http://localhost:12434/engines/v1` | `http://host.docker.internal:12434/engines/v1` | aucune | non |
| `llamacpp` | `http://127.0.0.1:8080/v1` | aucun | `LLAMA_API_KEY` | non |

## Erreurs de validation

Signalées sous la forme `[config error: <chemin>: <message>]`, code de sortie 1.

| Message | Cause |
|---------|-------|
| `provider must not be empty` | `provider: ""` |
| `model must not be empty` | `model: ""` |
| `contextWindow must be >= 0` | valeur négative |
| `maxOutput must be > 0` | zéro ou négatif |
| `maxTurns must be > 0` | zéro ou négatif |
| `previewLines must be >= 0` | valeur négative |
| `context.threshold must be between 1 and 100` | hors intervalle |
| `context.keepLastTurns must be >= 1` | zéro ou négatif |
| `context.summaryMaxTokens must be > 0` | zéro ou négatif |
| `context.maxMessages must be >= 0` | valeur négative |
| `sessions.dir must not be empty` | chaîne vide |
| `lsp.servers[N].name must not be empty` | un serveur sans `name` |
| `lsp.servers[N].command must not be empty` | un serveur sans `command` |
| `lsp.servers[N].extensions must list at least one extension` | un serveur sans `extensions` |
| `lsp.servers[N].extensions: "go" must start with a dot, like ".go"` | une extension sans son point |
| `lsp.servers[N]: extension ".ts" is already served by "typescript"` | deux serveurs sur une même extension |
| `permissions must be "auto" or "ask"` | toute autre valeur |
| `unknown provider "x" (known: dmr, llamacpp)` | Signalée par le moteur, sous la forme `[engine error: …]`. |

Un avertissement au démarrage, et non une erreur, est affiché quand `context.enabled` vaut `true`, que la fenêtre est inconnue et que `context.maxMessages` vaut `0`.

## Fichiers livrés

| Fichier | Rôle |
|---------|------|
| `agent.yaml` | Configuration Docker Model Runner : `provider: dmr`, `maxTurns: 40`, `displayCommands: true`, compression désactivée, un prompt système nommé « Bob » qui décrit les skills et les règles d'édition de fichiers. |
| `agent.llamacpp.yaml` | Configuration llama.cpp : `provider: llamacpp`, `baseUrl: http://127.0.0.1:8080/v1`, `fallback: ""`, compression activée. |

### Exemple

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