Docs/ Assistant IA/ AI Sandbox

AI Sandbox

Un conteneur Alpine Linux complet qui donne à l'assistant IA un accès pratique à l'environnement de votre application pour le débogage, les tests et l'analyse.

Qu'est-ce que l'AI Sandbox

L'AI Sandbox est un conteneur Alpine Linux dédié qui tourne à côté de votre application. Il partage l'espace de noms réseau de l'app, ce qui signifie qu'il peut atteindre votre app via localhost, et a accès aux volumes montés de l'app. Cela donne à l'assistant IA un véritable environnement de travail -- pas une simulation.

Dans le sandbox, l'IA peut installer des paquets, cloner des dépôts, construire et exécuter des applications, inspecter des fichiers, tester la connectivité réseau et exécuter des commandes arbitraires. C'est la différence entre une IA qui lit les logs et devine, et une IA qui peut réellement sonder votre service en cours d'exécution.

Activer le sandbox

Le sandbox est désactivé par défaut. Pour l'activer, allez dans la page Settings de votre app dans le tableau de bord et activez AI Sandbox. Alternativement, utilisez l'API :

Terminal

curl -X PATCH https://your-server:9000/api/v1/apps/:id \
  -H "Authorization: Bearer $SH0_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sandbox_enabled": true}'

Tip

Le sandbox est créé à la demande lorsque le premier outil sandbox est appelé. Si vous activez sandbox_enabled mais n'utilisez jamais d'outil sandbox, aucun conteneur n'est créé.

Spécifications du conteneur

Chaque conteneur sandbox est provisionné avec les spécifications suivantes :

Propriété	Valeur
Image	Alpine 3.19
User	root
RAM	1 Go
CPU	2 cœurs
Network	Partagé avec l'app (mode réseau de conteneur)
Volumes	Volumes de l'app montés (en écriture)
Command timeout	5 minutes
Output limit	100 Ko
Pre-installed tools	`curl`, `wget`, `dig`, `nc`, `jq`, `git`, `node`, `npm`, `python3`, `pip`, `bash`

Ce que l'IA peut faire

Avec l'accès au sandbox, l'assistant IA peut effectuer du débogage et de l'analyse pratiques :

Déboguer les endpoints de l'application

Comme le sandbox partage le réseau de l'app, l'IA peut appeler directement votre application :

Sandbox

curl localhost:3000/health
curl -v localhost:8080/api/users | jq .

Analyser le code source et les dépendances

Clonez le dépôt, installez les dépendances et inspectez le projet :

Sandbox

git clone https://github.com/user/app.git /tmp/app
cd /tmp/app && npm install
npm audit

Tester la connectivité

Vérifiez que les services peuvent se joindre mutuellement :

Sandbox

nc -zv db 5432
dig redis.internal
curl -s http://api:8000/healthz

Inspecter les fichiers et les logs

Lire les fichiers de configuration, les fichiers d'environnement et la sortie des logs depuis les volumes montés :

Sandbox

cat /app/config/production.json
ls -la /app/logs/
tail -100 /app/logs/error.log

Exécuter du code et tester les correctifs

Exécutez des scripts et validez les correctifs avant de les appliquer à l'application réelle :

Sandbox

python3 -c "import json; print(json.loads(open('/app/config.json').read()))"
node -e "const db = require('./db'); db.ping().then(console.log)"

Outils sandbox

L'IA interagit avec le sandbox via cinq outils dédiés :

Outil	Risque	Description	Exemple
`sandbox_exec`	Medium	Exécuter une commande dans le conteneur sandbox	`curl localhost:3000/health`
`sandbox_read_file`	Low	Lire un fichier depuis le système de fichiers du sandbox	`/app/config.json`
`sandbox_write_file`	High	Écrire un fichier dans le système de fichiers du sandbox	`/tmp/test-script.sh`
`sandbox_status`	Low	Vérifier si le sandbox est en cours d'exécution et en bonne santé	--
`sandbox_reset`	Medium	Détruire et recréer le conteneur sandbox	--

Cycle de vie

Le conteneur sandbox suit le cycle de vie de son application parente :

Créé : À la demande lorsque le premier outil sandbox est invoqué. La création est non bloquante et se produit de manière asynchrone après le déploiement.
Démarré : Automatiquement lorsque l'app parente démarre. Le sandbox reste en cours d'exécution tant que l'app tourne.
Arrêté : Lorsque l'app parente est arrêtée. Le conteneur sandbox est arrêté en même temps.
Détruit : Lorsque l'app parente est supprimée. Le conteneur sandbox et toutes ses données sont définitivement supprimés.

Le sandbox n'a pas de politique de redémarrage. S'il plante, il reste arrêté jusqu'à ce que le prochain appel d'outil sandbox déclenche une recréation.

Validation des commandes

Le sandbox applique une liste de blocage minimale pour empêcher les opérations catastrophiques. Les commandes suivantes sont rejetées :

rm -rf / -- destruction du système de fichiers
mkfs -- formatage de disque
shutdown / reboot -- opérations au niveau de l'hôte
Fork bombs (ex. : patterns :())

Tout le reste est autorisé. Le sandbox est intentionnellement permissif car son objectif est de donner à l'IA les mêmes capacités qu'un développeur humain lors du débogage. Le conteneur lui-même est la frontière de sécurité, pas le filtre de commandes.

Modèle de sécurité

Le modèle de sécurité du sandbox repose sur l'isolation des conteneurs plutôt que sur le filtrage des commandes :

Système de fichiers isolé : Le sandbox a son propre système de fichiers racine. Seuls les volumes explicitement montés sont partagés avec l'app.
Limites de ressources : Plafonds stricts sur la RAM (1 Go) et le CPU (2 cœurs) pour empêcher l'épuisement des ressources de l'hôte.
Jetable : Le conteneur peut être détruit et recréé à tout moment sans affecter l'application.
Pas de politique de redémarrage : Un sandbox planté ne redémarre pas automatiquement, empêchant les boucles de crash infinies.
Timeout des commandes : Chaque commande a un timeout de 5 minutes pour empêcher les processus incontrôlés.
Plafond de sortie : La sortie des commandes est tronquée à 100 Ko pour empêcher l'épuisement de la mémoire dans le transport MCP.

Warning

Le sandbox a un accès en écriture aux volumes de votre app. Bien que cela soit nécessaire pour que l'IA puisse correctement déboguer et tester, sachez que l'IA peut modifier les fichiers dans les volumes montés.

MCP Server

Tools Reference