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

# Faire tourner mini-me dans un Docker Sandbox

Ce guide montre comment exécuter `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 votre projet monté. Il couvre les deux usages : le mode fenêtre dans votre terminal, et depuis un éditeur via l'Agent Client Protocol. Il suppose Docker Desktop avec la commande `sbx`, et un serveur de modèles (Docker Model Runner ou llama-server) qui tourne sur votre machine.

Tout est sous [`docker-sbx/`](../../../docker-sbx/README.md) dans le dépôt :

| Élément | Ce que c'est |
|---|---|
| `template/Dockerfile` | Le **template** : l'image `shell` de Docker Sandboxes avec `mm` compilé depuis ce dépôt, plus les deux points d'entrée ci-dessous. |
| `kits/mm-tui/spec.yaml` | Un **kit sandbox** : `sbx run` dessus ouvre le mode fenêtre de `mm` sur l'espace de travail. |
| `kits/mm-acp/spec.yaml` | Un **kit sandbox** pour un éditeur : créé une fois avec `sbx create`, l'éditeur y lance ensuite `mm -acp`. |
| `build.sh` | Construit l'image du template, `k33g/mm-sandbox:<version>` ; `PUSH=1` la construit pour linux/amd64 et linux/arm64 et la pousse. |
| `sync-kits.sh`, `push-kits.sh` | Alignent les kits sur une image, et les publient sur Docker Hub comme artefacts OCI de kit. |

## Utiliser les kits publiés

Chaque release publie l'image et les deux kits sur Docker Hub à la version de mm — `k33g/mm-sandbox:0.0.2`, `k33g/mm-tui:0.0.2`, `k33g/mm-acp:0.0.2` — le chemin le plus court ne demande donc aucune construction. Docker Hub est une source de kits autorisée par défaut (`sbx settings get kit.allowedSources` montre `docker.io/`), et une référence avec un `/` mais sans hôte de registre est lue comme `docker.io/…` :

```bash
cd /chemin/de/votre/projet
sbx run k33g/mm-tui:0.0.2 . -- agent.dmr.yaml
```

pour le mode fenêtre, et pour un éditeur :

```bash
sbx create --name mm-acp k33g/mm-acp:0.0.2 . --kit-arg config=agent.dmr.yaml
```

puis la déclaration dans l'éditeur de l'étape 3 ci-dessous. Pas de `--pull never` : le kit nomme `k33g/mm-sandbox:0.0.2` et sbx la télécharge. `sbx kit inspect k33g/mm-tui:0.0.2` montre ce qu'un kit déclare avant de le lancer. Les étapes qui suivent construisent la même chose en local, pour un mm en cours de travail.

## Étapes

### 1. Construire le template

Depuis la racine du dépôt :

```bash
./docker-sbx/build.sh
```

Cela lit le tag de mm dans `release.env` (`v0.0.2`) et construit `k33g/mm-sandbox:0.0.2` : le tag de l'image est la version sans le `v`, comme les binaires de release, et le `mm` à l'intérieur est estampillé avec le tag — `mm --version` est exécuté dans l'image comme preuve. Le script réécrit ensuite la valeur par défaut de l'argument `tag` des kits à `0.0.2`, pour que kits et image avancent ensemble. `./docker-sbx/build.sh v0.0.3` construit une autre version ; une image antérieure reste joignable avec `--kit-arg tag=0.0.1`.

L'image est dans votre store d'images Docker local : chaque `sbx run` ou `sbx create` sur ces kits prend `--pull never` tant qu'elle n'est pas poussée (`docker push k33g/mm-sandbox:0.0.2`), sinon `sbx` tente de la télécharger et échoue. Si `sbx` tourne sur une autre machine, `EXPORT=1 ./docker-sbx/build.sh` écrit aussi `tmp/mm-sandbox-0.0.2.tar`, à charger là-bas avec `sbx template load`.

### 2. Mode fenêtre dans le terminal (kit `mm-tui`)

Depuis le projet sur lequel `mm` doit travailler :

```bash
sbx run --pull never ./docker-sbx/kits/mm-tui . -- agent.dmr.yaml
```

La première fois, `sbx` crée le sandbox, monte le répertoire courant comme espace de travail et s'y attache ; puis il lance le point d'entrée du kit avec ce qui suit `--` en arguments — ici `mm -tui agent.dmr.yaml`, dans l'espace de travail. N'importe quel drapeau de `mm` passe de la même façon : `-- -config autre.yaml`.

Sans rien après `--`, `mm` lit l'argument `config` du kit, puis `./agent.yaml` dans l'espace de travail, puis ses valeurs par défaut :

```bash
sbx run --pull never ./docker-sbx/kits/mm-tui . --kit-arg config=agent.dmr.yaml
```

| `--kit-arg` | Défaut | Effet |
|---|---|---|
| `config=<chemin>` | vide | Le fichier de configuration, comme `AGENT_CONFIG` de `mm` : relatif à l'espace de travail, ou absolu dans le sandbox. |
| `tag=<version>` | la dernière version construite (`0.0.2`) | L'image `k33g/mm-sandbox:<version>` dont le sandbox est fait. |

Le sandbox garde son nom (`mm-tui-<répertoire>` sauf `--name`) ; `sbx run --name <nom>` s'y rattache plus tard. À l'intérieur, 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` dans l'espace de travail — c'est votre répertoire hôte, elles survivent donc au sandbox.

### 3. Depuis un éditeur (kit `mm-acp`)

Un éditeur parle à `mm -acp` sur l'entrée et la sortie standard brutes de l'agent. `sbx run` ne peut pas porter cela : il alloue toujours un terminal. Le sandbox est donc créé une fois sans s'y attacher, et l'éditeur y lance `mm` avec `sbx exec -i`, qui transmet stdin et stdout tels quels.

1. Depuis le projet que l'éditeur ouvrira, créez le sandbox avec le fichier de configuration intégré (`.` est l'espace de travail, sbx le rend absolu ; le chemin du kit doit être explicite : `./`, `../` ou absolu) :

   ```bash
   cd /chemin/de/votre/projet
   sbx create --pull never --name mm-acp /chemin/de/mini-me/docker-sbx/kits/mm-acp . \
       --kit-arg config=agent.dmr.yaml
   ```

   Un chemin d'espace de travail qui n'existe pas sur votre machine fait demander à sbx « The selected workspace does not exist. Would you like to create it? » — répondez `N` et corrigez le chemin.

   `--kit-arg config` devient l'`AGENT_CONFIG` du conteneur, relatif à l'espace de travail parce que c'est là que `sbx exec` démarre `mm`. L'espace de travail est fixé à la création : un sandbox par projet, chacun avec son `--name`.

2. Déclarez-le dans l'éditeur. Dans le `settings.json` de Zed :

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

   Par rapport à [la configuration côté hôte](use-from-an-editor.md), la commande est `sbx` et aucun `env` n'est nécessaire : `AGENT_CONFIG` est déjà dans le conteneur. Si l'éditeur ne trouve pas `sbx`, mettez le chemin absolu donné par `which sbx` dans `"command"`.

3. Ouvrez le panneau agent et choisissez **mini-me (sandbox)**. L'éditeur lance `mm -acp` dans le sandbox à chaque conversation ; `sbx exec` démarre d'abord le sandbox s'il est arrêté. Appels d'outils, dialogues de permission, mentions `@fichier` et menu des commandes fonctionnent comme sur l'hôte — la différence est l'endroit où les commandes s'exécutent.

S'attacher à ce sandbox avec `sbx run --name mm-acp` ne lance pas `mm` : son point d'entrée affiche le câblage ci-dessus avec le vrai nom et les vrais chemins du sandbox, puis ouvre un shell à l'intérieur. `sbx exec -it mm-acp bash` est le chemin le plus court vers ce shell.

## 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 fait pointer vers le `localhost` de l'hôte.

- **Docker Model Runner** — rien à changer : `agent.dmr.yaml` a déjà `fallback: http://host.docker.internal:12434/engines/v1`, et `mm` bascule dessus quand `localhost:12434` ne répond pas (la bannière dit quelle URL a gagné).
- **llama-server** — `agent.llamacpp.yaml` n'a pas de fallback. Soit vous changez son `baseUrl` en `http://host.docker.internal:8080/v1`, soit vous passez `--env AGENT_BASE_URL=http://host.docker.internal:8080/v1` à `sbx run` / `sbx create` (voir [Faire tourner sur llama.cpp](run-with-llama-cpp.md)).

Les deux kits autorisent les ports 12434 et 8080 de l'hôte dans la politique réseau du sandbox. Pour un autre port : `sbx policy allow network host.docker.internal:<port>`.

## Publier une version

Le workflow Release (`.github/workflows/release.yml`, job `docker-sandbox`) publie l'image et les kits à chaque tag `v*`, après le job des binaires. Il a besoin de deux secrets du dépôt, exposés au job comme variables d'environnement : `DOCKER_HANDLE`, le compte Docker Hub (aussi le propriétaire de l'image), et `DOCKER_PAT`, un jeton d'accès en lecture/écriture. Il lance ensuite les scripts qu'un portable lancerait :

```bash
docker login -u k33g                       # coller un jeton d'accès
PUSH=1 ./docker-sbx/build.sh v0.0.2        # buildx, linux/amd64 + linux/arm64, poussée comme k33g/mm-sandbox:0.0.2
./docker-sbx/push-kits.sh v0.0.2           # sbx kit validate + sbx kit push → k33g/mm-tui:0.0.2, k33g/mm-acp:0.0.2
```

`push-kits.sh` a besoin de la CLI `sbx` sur le PATH (ou `SBX=/chemin/vers/sbx` ; le workflow télécharge l'archive Linux de `docker/sbx-releases`). `sbx kit push` parle directement au registre et s'authentifie depuis le magasin d'identifiants Docker — aucun démon sandbox n'intervient, c'est ce qui le rend utilisable en CI. Les deux scripts appellent d'abord `sync-kits.sh`, qui réécrit `version`, le `tag` par défaut et le propriétaire de l'image des kits, de sorte qu'un kit publié nomme toujours l'image poussée avec lui. `IMAGE_OWNER=<compte>` publie sous un autre compte.

## Variantes

- **Une autre configuration pour une session d'éditeur.** Ajoutez `"-e", "AGENT_CONFIG=agent.lsp.yaml"` avant le nom du sandbox dans `"args"` ; `sbx exec -e` remplace la valeur intégrée pour cette exécution seulement.
- **Skills.** `skillsDir` est relatif au répertoire où `mm` tourne, c'est-à-dire l'espace de travail dans les deux kits — la même règle que sur l'hôte.
- **Docker dans le sandbox.** Construisez le template sur le shell Docker-in-Docker : `SHELL_TEMPLATE=docker/sandbox-templates:shell-docker ./docker-sbx/build.sh`.
- **Lire les logs.** En mode fenêtre ils sont à l'écran ; en ACP ils vont sur stderr, que Zed montre sous `dev: open acp logs`.
- **Supprimer un sandbox.** `sbx rm mm-acp`. Le répertoire du projet est un montage et n'est pas touché.

## Voir aussi

- Le format suivi par ces deux fichiers : la spécification des kits de Docker Sandboxes (`schemaVersion: "2"`), livrée avec les sources de `sbx`.
- Ce que `mm -acp` expose à l'éditeur : [référence ACP](../reference/acp.md).
- Les drapeaux et variables d'environnement que `mm` lit : [référence de la ligne de commande](../reference/cli.md).