Faire tourner mini-me avec les kits sandbox v3

  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

# Faire tourner mini-me avec les kits sandbox v3

Ce guide montre comment exécuter `mm` dans un [Docker Sandbox](https://docs.docker.com/ai/sandboxes/) avec les kits écrits pour la [spécification de kit v3](https://github.com/docker/sandbox-kit-spec), sous [`docker-sbx-v3/`](../../../docker-sbx-v3/README.md). Ils font le même travail que les kits v2 de [Faire tourner mini-me dans un Docker Sandbox](run-in-a-docker-sandbox.md) — le mode fenêtre avec `mm-tui`, un éditeur avec `mm-acp` — et les kits v2 continuent de fonctionner à côté. 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.

> **État.** Les kits v3 se construisent avec le frontend `docker/sandbox-kit:3` et passent le contrôle de conformité de la spécification (`kit-tck validate`), mais ils n'ont pas encore été lancés avec `sbx`, et ne sont pas encore publiés. La spécification de kit elle-même est encore marquée expérimentale.

| Élément | Ce que c'est |
|---|---|
| `template/Dockerfile` | L'image **template**, `k33g/mm-sandbox:<version>` — la même image qu'en v2. |
| `kits/mm-tui/mm-tui.yaml` + `mm-tui.dockerfile` | Le kit du mode fenêtre : un descripteur (les déclarations) et un Dockerfile (le contenu : `FROM` le template, `ENTRYPOINT ["mm-tui"]`). |
| `kits/mm-acp/mm-acp.yaml` + `mm-acp.dockerfile` | Le kit pour un éditeur, même forme, `ENTRYPOINT ["mm-acp-info"]`. |
| `build.sh`, `sync-kits.sh` | Construisent le template, et alignent les kits dessus. |
| `check-kits.sh` | Construit les kits en local et les vérifie, sans `sbx` et sans push. |
| `push-kits.sh`, `publish.sh` | Publient les kits (et le template) sur Docker Hub avec `docker buildx`. |

## Avant de commencer : deux différences avec la v2

- **L'image template doit être sur un registre.** Un kit v3 est *construit* au-dessus du template. Quand vous lancez un kit depuis son dossier, `sbx` le construit dans son sandbox de build, dont le moteur Docker télécharge le template depuis le registre. Une image présente seulement dans votre stockage local ne suffit pas, et `--pull never` ou `sbx template load` n'y changent rien. `k33g/mm-sandbox:0.2.1` est déjà sur Docker Hub ; pour une autre version, poussez-la d'abord (étape 1).
- **L'espace de travail est `/home/agent/workspace`.** L'image de base du template déclare ce répertoire de travail, et un workload d'agent v3 (`sbx@1`) y est monté. Donnez à `config` un chemin relatif à l'espace de travail (`agent.dmr.yaml`, `demo/agent.dmr.yaml`) ; un chemin absolu de votre Mac (`/Users/…`) n'existe pas dans le sandbox.

## Étapes

### 1. Rendre le template disponible

Pour la version de `release.env` (`v0.2.1`), rien à faire : `k33g/mm-sandbox:0.2.1` est sur Docker Hub. Pour un `mm` en cours de travail, construisez et poussez le template depuis la racine du dépôt :

```bash
PUSH=1 ./docker-sbx-v3/build.sh v0.2.2
```

Le script construit `k33g/mm-sandbox:0.2.2` pour linux/amd64 et linux/arm64, la pousse, puis réécrit les valeurs par défaut `image` et `tag` des kits pour qu'ils nomment cette image. `IMAGE_OWNER=<compte>` la pousse sous votre propre compte.

### 2. Vérifier les kits (facultatif)

```bash
./docker-sbx-v3/check-kits.sh
```

Chaque kit est construit avec `docker buildx build -f <kit>.yaml`, qui passe par le frontend des kits : il refuse une clé inconnue ou un argument qui ne respecte pas son motif. Le résultat va dans `tmp/kits-v3/<kit>/`. Avec [`kit-tck`](https://github.com/docker/sandbox-kit-spec) dans le `PATH` (`go build ./cmd/kit-tck` dans un clone de la spécification), le script lance aussi le contrôle de conformité et affiche `✓ conforms`.

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

Depuis le projet sur lequel `mm` doit travailler :

```bash
cd /chemin/de/votre/projet
sbx run /chemin/de/mini-me/docker-sbx-v3/kits/mm-tui . -- agent.dmr.yaml
```

Le premier lancement construit le kit (quelques secondes : une couche au-dessus du template), crée le sandbox, monte le répertoire courant et lance `mm -tui agent.dmr.yaml`. Ce qui suit `--` est la ligne de commande de `mm`. Sans rien après `--`, `mm` lit l'argument `config` du kit, puis `./agent.yaml`, puis ses valeurs par défaut :

```bash
sbx run /chemin/de/mini-me/docker-sbx-v3/kits/mm-tui . --kit-arg config=agent.dmr.yaml
```

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

1. Créez le sandbox une fois, depuis le projet que l'éditeur ouvrira :

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

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"]
       }
     }
   }
   ```

3. Ouvrez le panneau d'agent et choisissez **mini-me (sandbox)**. Comme en v2, l'éditeur passe par `sbx exec -i`, parce qu'un client ACP a besoin de stdin et stdout bruts et que `sbx run` alloue toujours un terminal. `sbx run --name mm-acp` affiche ce branchement et ouvre un shell.

### 5. Une fois les kits publiés

Après `./docker-sbx-v3/publish.sh` (ou `push-kits.sh`) pour une version, les kits sont des images ordinaires sur Docker Hub, et aucun dossier n'est nécessaire :

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

Les dépôts sont `sbx-kit-<kit>`, pas les `k33g/mm-tui` / `k33g/mm-acp` de la v2 : publier un kit v3 ne remplace jamais un kit v2.

## Arguments des kits

| `--kit-arg` | Défaut | Quand il s'applique | Effet |
|---|---|---|---|
| `config=<chemin>` | vide | à `sbx run` / `sbx create` | L'`AGENT_CONFIG` de `mm` : relatif à l'espace de travail, ou absolu dans le sandbox. Vide : `./agent.yaml`, puis les valeurs par défaut. |
| `tag=<version>` | la version de mm (`0.2.1`) | à la construction du kit | Le tag du template sur lequel le kit est construit ; c'est aussi la version du kit. Sans `v`. |
| `image=<dépôt>` | `k33g/mm-sandbox` | à la construction du kit | Le dépôt du template sur lequel le kit est construit. |

`tag` et `image` sont des arguments de construction : ils sont figés dans un kit publié, qui nomme toujours l'image sur laquelle il a été construit. Pour une autre version de `mm`, prenez le kit de cette version.

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

Rien ne change par rapport à la v2 : Docker Model Runner et llama-server tournent sur votre machine et sont joints par `host.docker.internal`. `agent.dmr.yaml` s'y replie déjà ; pour llama-server, voir [le guide v2](run-in-a-docker-sandbox.md#le-serveur-de-modèles-reste-sur-lhôte). Les deux kits autorisent les ports 12434 et 8080 de l'hôte ; pour un autre port, `sbx policy allow network host.docker.internal:<port>`.

## Voir aussi

- Ce qui change par rapport aux kits v2, champ par champ : [`docker-sbx-v3/README.md`](../../../docker-sbx-v3/README.md).
- Les kits v2, la passerelle MCP et les variantes pour éditeur : [Faire tourner mini-me dans un Docker Sandbox](run-in-a-docker-sandbox.md).
- Le format des kits : [spécification v3](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/SPEC-v3.md).