Lancer un agent dans une sandbox sbx

 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

# Lancer un agent dans une sandbox sbx

Ce guide montre comment déclarer un agent qui tourne dans une sandbox Docker (`sbx`), pour que Sidekicks converse avec lui, affiche ses fichiers et y ouvre un terminal. Il suppose `sbx` installé, et une sandbox démarrée qui contient le programme de l'agent.

## Ce dont Sidekicks a besoin

| Réglage | Rôle |
| --- | --- |
| `command` et `args` | comment l'agent démarre : `sbx exec -i <sandbox> <programme> <arguments>`. Sidekicks lui parle par l'entrée et la sortie standard (ACP) : `-i`, jamais `-t`. |
| `workspace` | le dossier de l'agent **sur cet ordinateur**. La commande y est lancée, et l'agent reçoit ce même chemin comme dossier de travail de ses sessions. sbx monte les dossiers de l'hôte qu'il partage **au même chemin** : c'est donc aussi le dossier vu dans la sandbox. |
| `runtime` | où sont ses fichiers et son terminal : `{type: sbx, sandbox: <sandbox>}`. |

## Étapes

1. Vérifiez que la sandbox tourne et partage le dossier de l'agent — elle doit lister son contenu au même chemin :

   ```bash
   sbx exec milo-sbx sh -c 'command -v mm; ls /Users/moi/agents/milo/workspace'
   ```

   Si le dossier manque, partagez-le à la création de la sandbox (dans sa configuration sbx), puis recréez-la.

2. Dans **Settings**, ajoutez l'agent et enregistrez :

   ```yaml
   agents:
     - name: milo
       title: Milo (sbx)
       icon: "🦊"
       command: sbx
       args: [exec, -i, milo-sbx, mm, -acp]
       workspace: /Users/moi/agents/milo/workspace
       runtime:
         type: sbx
         sandbox: milo-sbx
   ```

3. Démarrez l'agent depuis le panneau **Agents** (▶), ou écrivez-lui : il répond depuis la sandbox. **📂** affiche `sandbox milo-sbx · /Users/moi/agents/milo/workspace`, ses fichiers et un terminal (`sbx exec -it`). Chaque action sur les fichiers prend une à deux secondes : chacune passe par `sbx exec`.

## Recréer la sandbox quand elle a disparu

Quand la sandbox est supprimée (par vous, par `sbx rm`, après une remise à zéro de sbx), l'agent ne peut plus démarrer. Donnez à Sidekicks les commandes qui gèrent la sandbox : il la recrée avant de démarrer l'agent.

1. Avec l'assistant : choisissez **Dans une sandbox sbx**, puis déposez le `sbxenv.yaml` de la sandbox sur la zone **Recréer la sandbox si elle a disparu** (ou cliquez sur **Choisir un sbxenv.yaml…**). Le nom de la sandbox, le dossier et les commandes `sbx env` sont remplis ; modifiez-les au besoin.
2. Ou dans **Settings**, ajoutez `lifecycle` au runtime :

   ```yaml
       runtime:
         type: sbx
         sandbox: milo-sbx
         lifecycle:
           folder: /Users/moi/agents/milo
           create: [sbx, env, create, --force]
           stop: [sbx, stop, milo-sbx]
           remove: [sbx, env, rm, --force]
   ```

3. Démarrez l'agent : si `milo-sbx` n'existe pas, l'onglet **Journal** affiche `sandbox: sandbox milo-sbx not found: creating it` et la sortie de `sbx env create`, puis l'agent démarre. Créer une sandbox peut prendre une minute (les kits sont téléchargés).

Les boutons **■ Arrêter la sandbox** et **🗑 Supprimer la sandbox** apparaissent dans l'en-tête de l'agent quand `stop` et `remove` sont définis. Toutes les clés : [`runtime.lifecycle`](../reference/configuration.md#runtimelifecycle-conteneur-et-sbx).

## Variantes

- **Le nom de la sandbox n'est pas le `name:` du sbxenv.yaml** : après `create`, Sidekicks ne trouve toujours pas de sandbox et le dit. Donnez la même valeur à `sandbox` et à `name:`.
- **Sidekicks lancé depuis le Finder** : il peut ne pas trouver `sbx` dans son `PATH` réduit. Écrivez son chemin complet (`command: /usr/local/bin/sbx`, voir `which sbx`) ou ajoutez `env: {PATH: "…"}` à l'agent.
- **Le serveur de modèles tourne sur cet ordinateur** : depuis la sandbox, atteignez-le par `host.docker.internal`, comme depuis un conteneur.
- **Un autre programme que mm** (docker-agent, par exemple) : seuls les `args` changent, par exemple `[exec, -i, ma-sandbox, docker-agent, serve, acp, /chemin/vers/agent.yaml]`.
- **Vérifier sans Sidekicks** : `sbx exec -it <sandbox> bash` ouvre le même genre de shell que l'onglet Terminal.

## Voir aussi

- [Travailler avec les fichiers et le terminal d'un agent](fichiers-et-terminal-d-un-agent.md)
- [Lancer un agent dans un conteneur Docker](lancer-un-agent-dans-docker.md)
- [Référence : le fichier de configuration](../reference/configuration.md) · [workspaces](../reference/agents-et-evenements.md#workspaces-milestone-m4)