Pour lancer Claude Code dans Docker, démarrez-le dans un conteneur qui ne monte que votre dossier de projet : l’agent y travaille alors librement pendant que le reste de votre disque reste hors de portée. Vous pouvez le faire à la main avec une image et une longue ligne docker run, ou cocher une case dans AgentVera et obtenir le même conteneur tout préparé, avec la connexion, l’identité git et la propriété des fichiers gérées.
Ce guide couvre ce qu’un conteneur vous épargne (et ce qu’il n’épargne pas), la voie maison, et le fonctionnement des agents Docker d’AgentVera.
Ce qu’un conteneur protège, et ce qu’il ne protège pas
Un agent de code exécute des commandes sous votre utilisateur. Sans sandbox, il peut lire tous les fichiers que vous pouvez lire : autres dépôts, ~/.ssh, identifiants cloud, dotfiles. La plupart du temps, ce n’est pas grave. Le risque, c’est la rare mauvaise commande, un nettoyage confus, ou une injection de prompt cachée dans une page web ou le README d’une dépendance.
| Risque | Terminal ordinaire | Conteneur Docker |
|---|---|---|
| Lit des fichiers hors du projet | Oui | Seulement ce que vous montez |
| Lit les clés SSH et les identifiants | Oui | Non, sauf si montés |
| Supprime des fichiers hors du projet | Possible | Hors d’atteinte |
| Installe des outils globaux sur votre machine | Possible | Seulement dans le conteneur, disparus à la sortie |
| Modifie ou supprime des fichiers du projet | Possible | Toujours possible |
| Accède à internet | Oui | Oui, par défaut |
Deux lignes comptent le plus. Le dossier du projet reste modifiable : commitez souvent ou utilisez un worktree git. Et Docker ne coupe pas le réseau tout seul : pour cela, il faut des règles réseau supplémentaires. Pour un tour plus large des menaces, voir la sécurité des agents de code IA.
Lancer Claude Code dans Docker à la main
La voie maison demande trois éléments : une image, une commande de lancement et une décision sur la connexion.
1. Construire une image avec la CLI
Un petit Dockerfile suffit :
FROM node:22-bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
git curl ca-certificates ripgrep openssh-client less procps jq python3 \
&& rm -rf /var/lib/apt/lists/*
RUN npm install -g @anthropic-ai/claude-codedocker build -t my-claude .Ajoutez ce dont votre projet a besoin pour compiler et tester, comme un compilateur, un client de base de données ou un runtime de langage.
2. Le démarrer en ne montant que le projet
docker run --rm -it --init \
--user "$(id -u):$(id -g)" \
-v "$PWD":/work -w /work \
-e HOME=/home/agent --tmpfs /home/agent \
my-claude claudeCe que fait chaque partie :
--rmsupprime le conteneur quand Claude Code se termine.--users’exécute avec votre propre id utilisateur, pour que les nouveaux fichiers du projet n’appartiennent pas à root.-v "$PWD":/workmonte le projet, et rien d’autre de votre disque.- Un
HOMEjetable sur tmpfs donne à la CLI un endroit où écrire ses réglages.
3. Gérer la connexion et l’historique
Avec un home jetable, Claude Code oublie votre connexion et vos conversations à chaque lancement. Vous pouvez monter à la place un dossier de config dédié, ou passer une clé API avec -e ANTHROPIC_API_KEY. Passez les secrets par leur nom (-e NAME) plutôt qu’avec -e NAME=value, pour que la valeur n’apparaisse pas dans l’historique de votre shell.
Anthropic publie aussi une configuration devcontainer de référence pour Claude Code avec un pare-feu ; si vous travaillez avec des devcontainers, consultez la doc de Claude Code à ce sujet.
Où la voie manuelle devient fastidieuse
Chaque nouvel agent signifie les mêmes flags à nouveau. La reprise, les statistiques d’usage et les réglages par projet vivent dans un dossier que le conteneur ne voit pas sauf si vous le montez. Les commits git dans le conteneur n’ont pas de nom sauf si vous montez ~/.gitconfig. Et si vous lancez plusieurs agents à la fois, vous jonglez avec plusieurs de ces commandes.
Lancer Claude Code dans Docker avec AgentVera
AgentVera est une application de bureau pour macOS, Windows et Linux qui fait tourner des CLI d’agents de code côte à côte dans de vrais terminaux. Pour les agents Claude Code et Codex, la boîte de dialogue de l’agent comporte une case Run in a Docker container. Son indication est claire : l’agent ne voit que le dossier du projet ; les autres fichiers, programmes et clés SSH de cet ordinateur lui restent fermés.
Étapes
- Démarrez Docker Desktop, Colima ou OrbStack.
- Ouvrez un projet dans AgentVera et ajoutez un agent Claude Code ou Codex.
- Cochez Run in a Docker container. Définissez éventuellement Image, CPU et Memory (GB) ; laissez la mémoire vide pour aucune limite.
- Démarrez l’agent.
À la première utilisation, AgentVera construit son image d’agent, agentvera/agent:1, et vous suivez la sortie de la construction dans le terminal de l’agent. L’image est basée sur node:22-bookworm-slim avec git, ripgrep, jq, python3, make, g++ et quelques autres outils, plus Claude Code et Codex. Si vous indiquez votre propre image, elle doit contenir la commande claude ou codex ; une image absente de votre machine est téléchargée.
L’en-tête de l’agent affiche alors une pastille Docker, et le panneau indique qu’il tourne dans un conteneur Docker avec le nom de l’image. Vous pouvez aussi faire passer un agent existant dans ou hors d’un conteneur en le modifiant ; l’agent redémarre et garde la même conversation.
Ce qu’AgentVera prépare pour vous
| Sujet | Ce que fait AgentVera |
|---|---|
| Fichiers du projet | Monte le dossier du projet (pour un worktree, aussi son dépôt) |
| Connexion, reprise, stats | Monte le dossier de conversations de la CLI : reprise, stats d’usage et budgets fonctionnent comme d’habitude |
| Identité git | Monte ~/.gitconfig en lecture seule : les commits portent votre nom |
| Propriété des fichiers | S’exécute avec votre id utilisateur sur macOS et Linux : les fichiers n’appartiennent pas à root |
| Dossier home | Un home neuf sur tmpfs, supprimé à l’arrêt du conteneur |
| Durcissement | no-new-privileges, une limite de processus et plusieurs capacités Linux retirées |
| Secrets | Valeurs d’environnement passées par nom : les tokens n’apparaissent pas dans la liste des processus |
| Outils AgentVera | Les hooks et serveurs MCP comme la carte du projet, le tableau et la messagerie d’agents continuent de fonctionner |
Quand l’agent s’arrête, le conteneur est supprimé. Seules les modifications du dossier du projet restent.
Quelques points à savoir :
- Le réseau est ouvert. Sous Linux, le conteneur utilise le réseau de l’hôte ; ailleurs, il joint les serveurs locaux d’AgentVera via
host.docker.internal. Le conteneur limite les fichiers, pas internet. - Connexion sur macOS. Claude Code stocke sa connexion dans le trousseau macOS, qu’un conteneur ne peut pas lire : vous devrez peut-être vous connecter une fois à l’intérieur.
- Claude in Chrome n’est pas utilisé dans un conteneur. Le navigateur AgentVera, qui passe par Playwright MCP, est une option distincte dans la même boîte de dialogue.
- Agents locaux uniquement. Les agents distants via SSH tournent sur leur serveur et ne prennent pas cette option.
Les agents Docker sont inclus dans l’offre gratuite. L’application a aussi une page de gestion Docker séparée pour vos propres conteneurs et projets compose ; voir la page de la fonction Docker.
Associer le conteneur au bon niveau de permission
Un conteneur rend raisonnable un niveau de permission plus souple. Les agents AgentVera ont trois niveaux : Ask, Auto et Full access. L’indication de Full access dit : ne demande jamais, convient surtout dans un worktree ou un conteneur.
Une configuration pratique pour une longue tâche :
- Créez l’agent dans son propre worktree git, pour que ses changements restent sur une branche séparée.
- Cochez Run in a Docker container.
- Choisissez Auto ou Full access, selon la confiance que vous accordez à la tâche.
- À la fin, relisez le diff avant de fusionner.
Si vous hésitez devant --dangerously-skip-permissions, ignorer les permissions dans Claude Code détaille les compromis, et lancer Claude Code pendant la nuit montre comment un conteneur s’intègre à une exécution que personne ne surveille.
Checklist rapide
- Le conteneur ne monte que le projet, pas votre dossier home.
- Les nouveaux fichiers du projet vous appartiennent, pas à root.
- Les secrets sont passés par nom, pas intégrés à l’image.
- Le travail est commité, ou l’agent est sur une branche de worktree.
- Vous savez que le réseau reste ouvert, et vous avez ajouté des règles si cela compte.
Téléchargez AgentVera pour lancer Claude Code et Codex dans des conteneurs à côté du reste de vos agents, ou lisez la page agents dans Docker.