Sandcastle : faire tourner des agents Claude Code dans des sandboxes isolés

Je suis tombé sur Sandcastle cette semaine, le dernier projet de Matt Pocock, et ça gratte une démangeaison que j'ai depuis des mois. Si tu as déjà voulu faire tourner un agent Claude Code pendant une heure sans regarder chaque diff atterrir, c'est la pièce qui manquait.

Le pitch est simple : invoque un agent avec un seul appel sandcastle.run(), laisse la librairie gérer le sandboxing et la gestion des branches, et récupère un set propre de commits sur une branche que tu peux fusionner ou jeter. Pas de mode cowboy en --dangerously-skip-permissions. Pas d'agent qui édite ton .env au hasard. Juste un container isolé, un worktree, et un résultat.

Le problème que ça résout vraiment

L'agentic coding a un plafond de confiance, et ce n'est pas le modèle. C'est le blast radius. Au moment où tu fais tourner un agent sans surveillance sur ton vrai repo, deux questions arrivent. Que se passe-t-il s'il part en vrille ? Et que se passe-t-il si je veux en faire tourner trois en parallèle ?

La plupart d'entre nous ont bricolé des contournements. Des git worktrees dans des dossiers séparés. Un deuxième laptop. Une VM jetable. J'ai écrit sur les sessions parallèles avec worktrees avant, et le pattern marche, mais c'est manuel. Tu le montes, tu le démontes, tu te souviens quel worktree avait la branche expérimentale.

Sandcastle prend toute cette couche d'orchestration et en fait un appel de fonction. L'agent tourne dans un container Docker (ou Podman, ou une microVM Vercel Firecracker), commit sur une branche temporaire à l'intérieur du sandbox, et l'hôte récupère la branche résultante avec tous les commits attachés. Si l'agent casse quelque chose, les dégâts sont dans un container qui va être détruit.

C'est la partie que je trouve discrètement importante. Le sandboxing pour les agents IA n'est pas une préoccupation de security theater. C'est ce qui rend les workflows sans surveillance réellement sûrs à laisser tourner.

À quoi ressemble l'API

La forme de base est ce que tu espérerais d'une librairie de Matt Pocock : petite surface, types solides, pas de surprises.

import { run, claudeCode } from "@ai-hero/sandcastle";
import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
const result = await run({
  agent: claudeCode("claude-opus-4-6"),
  sandbox: docker(),
  prompt: "Fix the failing tests in the auth module",
});

C'est tout. Tu récupères les itérations, les commits faits par l'agent, et la branche où ils vivent. À partir de là, tu décides si tu fusionnes, reviews, ou jettes.

La partie intéressante, c'est comment fonctionnent les branches. Par défaut, les providers en bind-mount (Docker, Podman) écrivent directement dans ton répertoire de travail parce qu'ils y sont déjà montés. Les providers isolés (Vercel) tournent sur une branche temporaire et la fusionnent à la fin. Tu peux aussi forcer un nom de branche explicite, ce que je ferais en CI :

await run({
  agent: claudeCode("claude-opus-4-6"),
  sandbox: docker(),
  branchStrategy: { type: "branch", branch: "agent/issue-42" },
  prompt: "Fix issue #42",
});

Cette séparation nette entre le provider de sandbox et la stratégie de branche est la décision de design qui rend le reste de la librairie composable.

À quoi je l'utiliserais

Quelques workflows me sont venus à l'esprit immédiatement, et ce sont tous des choses que je fais actuellement à l'ancienne.

Triage d'issues en parallèle. Trois bug reports ouverts, trois sandboxes, trois agents Claude qui tournent en parallèle. Chacun produit une branche avec un fix proposé. Je les review le matin. La partie chère de l'agentic coding, ce ne sont pas les tokens du modèle, c'est le wall-clock time entre « j'ai une idée » et « j'ai une PR ». Le parallélisme fait s'effondrer ça.

Pipelines implement-then-review. Sandcastle a une primitive createSandbox qui te permet de réutiliser le même container à travers plusieurs runs d'agents. L'exemple dans le README fait exactement le workflow que je veux : Opus implémente une feature, puis Sonnet fait une passe de review sur la même branche dans le même container. Deux agents, une feature, pas de perte de contexte.

Runs AFK la nuit. C'est celui qui m'intrigue le plus. File à l'agent un refactoring à faible enjeu avec maxIterations: 5, laisse-le tourner pendant que je dors, réveille-toi sur une branche avec des commits que je peux review autour d'un café. Le mécanisme de completion signal (l'agent sort une sentinel string quand il pense avoir fini) est le genre de détail qui suggère que Matt a vraiment utilisé ça en conditions réelles.

Je couvre le workflow agentic complet dans le cours, y compris comment structurer les prompts et les feedback loops pour les runs sans surveillance.

Les contraintes à connaître

Ce n'est pas de la magie, et le README est honnête là-dessus.

L'extraction de structured output (JSON typé via des schémas Zod) exige maxIterations === 1. Si tu veux à la fois un agent multi-itérations et un résultat typé, tu ne peux pas. C'est une vraie limitation si tu espérais utiliser Sandcastle comme drop-in pour des pipelines qui utilisent des tools.

La reprise de session est liée aux fichiers de session de Claude Code sur l'hôte, ce qui veut dire que les sessions reprises ne se combinent pas non plus avec les runs multi-itérations. Utile pour « continuer ce que tu faisais hier », moins utile pour des boucles autonomes chaînées.

La stratégie de branche head (écrire directement dans ton répertoire de travail) ne marche qu'avec les providers en bind-mount. Si tu es sur les microVMs de Vercel, le sandbox ne voit pas tes fichiers locaux, donc il doit fusionner via une branche. Évident après coup, mais bon à savoir avant de câbler ta CI.

Et comme pour tout workflow basé sur des containers, le temps de startup de Docker est réel. Le premier run paie pour les image pulls et le npm install. Le système de hooks atténue ça avec des commandes de setup de sandbox en parallèle, mais si tu t'attends à des cold starts en <1s, recale tes attentes.

Pourquoi c'est important au-delà de Sandcastle lui-même

La librairie est bonne. Ce qui est plus intéressant, c'est ce qu'elle représente.

L'écosystème de l'agentic coding passe de « comment mieux prompter l'agent » à « comment faire tourner l'agent sûrement sans moi dans la boucle ». Sandboxing, stratégies de branches, lifecycle hooks, structured output, completion signals : ce sont les primitives de l'exécution sans surveillance. Ils ont l'air ennuyeux à côté des benchmarks de modèles. Ce sont eux qui déverrouillent vraiment le parallélisme.

Ça fait quelques mois que je construis des variantes de ça manuellement au-dessus de git worktrees et de tmux. Avoir une librairie typée qui codifie le pattern veut dire que je peux arrêter de maintenir des glue scripts et me concentrer sur les prompts.

Si tu fais tourner Claude Code sur de vrais projets et que tu as déjà souhaité paralléliser quelques tâches sans context-switcher toute la journée, Sandcastle mérite un vrai coup d'œil. C'est une librairie qui en est à ses débuts, l'API peut bouger, mais la forme est la bonne.

Je vais plus loin sur les workflows agentic parallèles dans le cours, y compris les patterns de worktrees que Sandcastle automatise et les structures de prompt qui rendent les runs sans surveillance fiables.