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

# 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 [`sbx/`](../../../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` | `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` | `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` | `sbx/` | Deux configurations `mm` pour llmman (Jan-nano, Lucy). |
| `AGENTS.md` | `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 — `sbx/` lui-même, pour utiliser ses configurations et son `AGENTS.md` :

```bash
cd 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/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/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.

## 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 `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).