Comment faire tourner mini-me dans un Docker Sandbox

  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
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206

# Comment faire tourner mini-me dans un Docker Sandbox

Ce guide montre comment lancer `mm` dans un [Docker Sandbox](https://docs.docker.com/ai/sandboxes/), pour que chaque commande lancée par le modèle et chaque fichier qu'il modifie le soient dans un conteneur, sur une copie montée de votre projet. Il couvre le mode fenêtre dans votre terminal et un éditeur via l'Agent Client Protocol. Il suppose Docker Desktop avec la commande `sbx`, et un serveur de modèles qui tourne sur votre machine.

Tout se trouve sous [`demos/use-with-sbx/`](../../../demos/use-with-sbx/README.md) dans le dépôt. Les kits suivent la [spécification des kits v3](https://github.com/docker/sandbox-kit-spec) (`schemaVersion: "3"`) : un **workload** qui lance `mm`, et des **mixins** qu'on lui ajoute avec `--kit`.

| Élément | Où | Ce que c'est |
|---|---|---|
| `mini-me` | [bots-garden/mini-me-kit](https://rickub.com/bots-garden/mini-me-kit), dossier `mini-me/` | Le **workload** : le template `shell` de Docker (Ubuntu, utilisateur `agent`) avec le binaire `mm` d'une release (`mm_version`, `v0.3.0` par défaut), téléchargé depuis la page de release de mini-me. Point d'entrée `mm`, arguments par défaut `-tui`. Versionné par ses propres tags (`v0.0.1`). |
| `go-toolchain` | `demos/use-with-sbx/kits/go-toolchain/` | Un **mixin** : Go (`go_version`, `1.27.2` par défaut), `gofmt` et `gopls` (`gopls_version`, `latest` par défaut). Autorise à l'exécution les hôtes des modules : `proxy.golang.org`, `sum.golang.org`, `github.com`, `golang.org`. |
| `cli-tools` | `demos/use-with-sbx/kits/cli-tools/` | Un **mixin** : `rg`, `bat` et `eza` en binaires statiques. Pas de réseau à l'exécution. |
| `agent.yaml`, `agent.lucy.yaml` | `demos/use-with-sbx/` | Deux configurations `mm` pour llmman (Jan-nano, Lucy). |
| `AGENTS.md` | `demos/use-with-sbx/` | Les consignes de l'agent qui travaille dans le sandbox (les outils installés, comment lancer Go) : `mm` les ajoute à son prompt système quand il tourne dans ce dossier — voir [Comment donner à l'agent les consignes de votre projet](give-project-instructions.md). |

## Étapes

### 1. Autoriser la source du kit

Le kit `mini-me` est désigné par son URL git, un tag et son dossier. Son hôte doit être une source de kits autorisée, une fois pour toutes :

```bash
sbx settings set kit.allowedSources '["docker.io/","git.rickub.com/bots-garden/"]'
```

### 2. Mode fenêtre dans le terminal

Depuis le dossier sur lequel `mm` doit travailler — `demos/use-with-sbx/` lui-même, pour utiliser ses configurations et son `AGENTS.md` :

```bash
cd demos/use-with-sbx
RELEASE=v0.0.1
REPOSITORY=git+https://git.rickub.com/bots-garden/mini-me-kit.git
sbx run --name mm-demo-remote "${REPOSITORY}#ref=${RELEASE}&dir=mini-me"
```

Le premier lancement construit le kit, crée le sandbox, monte le dossier courant comme espace de travail et lance `mm -tui`, qui lit `./agent.yaml`. Ajoutez les mixins avec `--kit` ; ce qui suit `--` remplace les arguments par défaut : c'est toute la ligne de commande de `mm` :

```bash
sbx run --name mm-demo-remote "${REPOSITORY}#ref=${RELEASE}&dir=mini-me" \
    --kit ./kits/go-toolchain --kit ./kits/cli-tools \
    -- -tui -config agent.lucy.yaml
```

Le sandbox garde son nom ; `sbx run --name mm-demo-remote` s'y rattache plus tard. La fenêtre est celle décrite dans [Utiliser le mode fenêtre](use-the-window-mode.md). Les sessions, quand `sessions.enabled` est actif, sont écrites sous `.mm/sessions` de l'espace de travail — votre dossier sur la machine hôte — et survivent donc au sandbox.

Pour travailler sur le kit lui-même, clonez [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit) et lancez-le depuis son dossier `demo/` : `sbx run --name mm-demo ../mini-me`.

### 3. Depuis un éditeur (ACP)

Un éditeur parle à `mm -acp` par stdin et stdout bruts, ce que `sbx run` ne peut pas transporter (il alloue toujours un terminal). Créez le sandbox une fois, sans vous y attacher, puis laissez l'éditeur lancer `mm` dedans avec `sbx exec -i` :

1. Depuis le projet que l'éditeur ouvrira, avec la référence distante du kit :

   ```bash
   RELEASE=v0.0.1
   REPOSITORY=git+https://git.rickub.com/bots-garden/mini-me-kit.git
   sbx create --name mm-acp "${REPOSITORY}#ref=${RELEASE}&dir=mini-me" . \
       --kit /chemin/vers/mini-me/demos/use-with-sbx/kits/go-toolchain
   ```

   ou avec un clone local de [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit) (un chemin de kit doit commencer par `./`, `../` ou `/`) :

   ```bash
   git clone https://git.rickub.com/bots-garden/mini-me-kit.git /chemin/vers/mini-me-kit
   sbx create --name mm-acp /chemin/vers/mini-me-kit/mini-me . \
       --kit /chemin/vers/mini-me/demos/use-with-sbx/kits/go-toolchain
   ```

   L'espace de travail (`.`) est fixé à la création : un sandbox par projet, chacun avec son propre `--name`.

2. Vérifiez à la main :

   ```bash
   sbx exec -i mm-acp mm -acp -config agent.lucy.yaml
   ```

3. Déclarez-le dans le `settings.json` de Zed :

   ```json
   {
     "agent_servers": {
       "mini-me (sandbox)": {
         "type": "custom",
         "command": "sbx",
         "args": ["exec", "-i", "mm-acp", "mm", "-acp", "-config", "agent.lucy.yaml"]
       }
     }
   }
   ```

   Si l'éditeur ne trouve pas `sbx`, mettez le chemin absolu donné par `which sbx` dans `"command"`. Les appels d'outils, les demandes de permission, les mentions `@fichier` et le menu des commandes slash fonctionnent comme sur l'hôte ; la différence est l'endroit où les commandes s'exécutent. Voir [Utiliser mini-me depuis un éditeur](use-from-an-editor.md) pour l'installation côté hôte.

## Générer un sbxenv.yaml avec `mm sbxinit`

Pour décrire la sandbox dans un fichier, lancez ceci dans le dossier de votre projet :

```bash
mm sbxinit
sbx env create --force
```

`sbx env` demande sbx 0.39.0 ou plus, et `docker.io/` parmi les sources de kits autorisées (étape 1). Le fichier indique la dernière version de `mini-me-kit`, et `pullPolicy: always` fait récupérer ce kit par la sandbox à chaque création. Si cette version ne peut pas être lue, par exemple sans réseau, mm le signale et utilise le tag `latest`. La sandbox prend le nom de `acp.name` dans `agent.yaml`, suivi de `-sbx` ; `--name` permet d'en choisir un autre.

Pour monter un sous-dossier plutôt que le dossier courant :

```bash
mm sbxinit --workspace ./workspace
```

Le fichier contient alors le chemin absolu du dossier. Créez ce dossier vous-même : mm vous avertit s'il n'existe pas. Pour supprimer la sandbox, lancez `sbx env rm --force`.

Toutes les options sont dans la [référence CLI](../reference/cli.md#mm-sbxinit--le-fichier-de-la-sandbox).

### Quand le fichier d'agent est hors du workspace

La sandbox ne voit que ce qui est monté. Avec `--workspace ./workspace` et un `agent.yaml` dans le dossier parent, mm ne peut pas lire ce fichier dans la sandbox. `mm sbxinit` vous avertit (`agent.yaml is outside the workspace`) et ne change rien d'autre : le fichier généré ne monte que le workspace.

Vous avez deux façons de régler ce cas.

**Mettre le fichier d'agent dans le workspace.** C'est la façon simple, et le fichier généré ne change pas :

```bash
mv agent.yaml workspace/
```

L'agent peut alors réécrire son propre fichier, puisque le workspace est accessible en écriture.

**Monter le dossier du fichier d'agent en lecture seule.** Choisissez cette façon quand l'agent ne doit pas pouvoir modifier ses propres réglages. Gardez le fichier d'agent dans son propre dossier, pas dans le parent du workspace :

```
project/
├── sbxenv.yaml      non monté
├── agents/          agent.yaml, monté en lecture seule
└── workspace/       le code, monté en lecture-écriture
```

Ajoutez ensuite ceci à la main dans `sbxenv.yaml` :

```yaml
additionalWorkspaces:
  - path: ./agents
    readOnly: true

# The folder of this file, as the sandbox sees it.
args:
  PROJECT_DIR:
    required: true

env:
  # mm reads this agent file instead of ./agent.yaml.
  AGENT_CONFIG: ${{ env.args.PROJECT_DIR }}/agents/agent.yaml
```

Chaque commande `sbx env` a maintenant besoin de l'argument :

```bash
sbx env create --force --env-arg PROJECT_DIR="$PWD"
sbx env rm --force --env-arg PROJECT_DIR="$PWD"
```

`mm sbxinit` ne génère pas cette forme, car elle allonge le fichier pour un cas que la plupart des projets n'ont pas. Relancer `mm sbxinit` en répondant `yes` remplace ces ajouts. [`demos/dev.team/sbxenv.yaml`](../../../demos/dev.team/sbxenv.yaml) en est un exemple complet.

## Le serveur de modèles reste sur l'hôte

Dans un sandbox, `localhost` est le sandbox lui-même. Votre serveur de modèles continue de tourner sur votre machine et se joint par `host.docker.internal`, que le proxy du sandbox redirige vers votre machine.

- La politique réseau du kit `mini-me` autorise **`host.docker.internal:12434`** (Docker Model Runner), **`:11434`** (Ollama) et **`:17434`** (llmman). `agent.dmr.yaml` se replie déjà sur `http://host.docker.internal:12434/engines/v1` ; les configurations livrées dans `demos/use-with-sbx/` utilisent llmman (`fallback: http://host.docker.internal:17434/v1`).
- Pour un autre port — le `8080` de llama-server, par exemple — ajoutez-le à la capacité `network-policy` du kit, ou autorisez-le pour un seul sandbox :

  ```bash
  sbx policy allow network host.docker.internal:8080
  ```

  `sbx policy log` montre ce qui a été bloqué.

## Changer une version

- **mm** : le `default` de `mm_version` dans `mini-me/mini-me.yaml` du dépôt [mini-me-kit](https://rickub.com/bots-garden/mini-me-kit) — un tag de release comme `v0.3.0` ; le tag du kit lui-même (`RELEASE` ci-dessus) désigne alors le nouveau kit. La construction télécharge `https://rickub.com/bots-garden/mini-me/releases/download/<tag>/mm-<version>-linux-<arch>` ; un tag sans release correspondante fait échouer la construction.
- **Go, gopls, rg, bat, eza** : le `default` de l'argument correspondant dans le YAML du mixin (`go_version`, `gopls_version`, `rg_version`, `bat_version`, `eza_version`) ; chacun a un `pattern` qui refuse une version mal formée.

## Des serveurs MCP via la passerelle de sbx

Dans un sandbox, `mm` ne parle pas lui-même aux serveurs MCP et ne détient aucun jeton. `sbx` lance une passerelle MCP par sandbox, sur l'hôte, et inscrit `MCP_GATEWAY_URL` dans le conteneur. Quand `mm` trouve `MCP_GATEWAY_URL` et `mcp.enabled: true`, il ajoute un serveur nommé `sbx-gateway`, dont les outils apparaissent sous la forme `sbx-gateway_<outil>` :

```yaml
mcp:
  enabled: true
  permissions: ask
  discoveryTimeout: 10s
  servers: []        # la passerelle est ajoutée par mm quand MCP_GATEWAY_URL est défini
```

Déclarez le serveur sur l'hôte (`sbx mcp add <nom> --command <script>`), puis créez un **nouveau** sandbox qui l'a dans son ensemble fixe — `--static-mcp <nom>` est une option de `sbx` et se place avant `--`. Si aucun outil `sbx-gateway_*` n'apparaît dans la bannière, `sbx mcp inspect <nom>` et le fichier `mcp/mcp.log` de sbx disent pourquoi.

## Variantes

- **Skills.** `skillsDir` est relatif au dossier où tourne `mm` — l'espace de travail — comme sur l'hôte.
- **Lire les journaux.** En mode fenêtre, ils sont à l'écran ; en ACP, ils vont sur stderr, que Zed affiche sous `dev: open acp logs`.
- **Un shell dans le sandbox.** `sbx exec -it mm-acp bash`.
- **Supprimer un sandbox.** `sbx rm mm-acp`. Le dossier du projet est un montage et n'est pas touché.

## Voir aussi

- Le format des kits : [spécification v3](https://github.com/docker/sandbox-kit-spec).
- Ce que `mm -acp` expose à l'éditeur : [référence ACP](../reference/acp.md).
- Les options et variables d'environnement que lit `mm` : [référence de la ligne de commande](../reference/cli.md).