Pourquoi Claude Code recommande Docker ? Guide complet pour débutants (2026)

Vous venez d'installer Claude Code, vous ouvrez la doc officielle — et dès la première page apparaissent devcontainer, Docker et --dangerously-skip-permissions. Réaction fréquente : « Je veux juste que l'IA m'écrive du code, pourquoi apprendre les conteneurs ? »

Ce n'est pas Anthropic qui complique la vie des débutants. La différence majeure avec l'autocomplétion : Claude Code exécute vraiment des commandes, modifie plusieurs fichiers, installe des dépendances et lance des tests. Plus les capacités sont grandes, plus le risque d'erreur et de dépassement de droits augmente. Docker fournit une « clôture » reproductible — elle protège votre machine et aligne l'environnement de toute l'équipe.

Ce guide suit un ordre accessible : pourquoi Docker est recommandé → Docker en 30 secondes → devcontainer officiel → premier lancement pas à pas → quand s'en passer. Pas besoin d'être expert DevOps.

En bref : pourquoi Claude Code parle-t-il tant de Docker ?

Trois raisons essentielles :

• Isolation : les commandes dans le conteneur n'atteignent pas par défaut ~/.ssh, vos identifiants cloud ni vos photos — sauf si vous les montez volontairement.
• Reproductibilité : .devcontainer/devcontainer.json fixe la version de Node, les CLI, etc. Un collègue clone, reconstruit le conteneur — même environnement que vous. Fini le « chez moi ça marche ».
• Base de sécurité : dans le dépôt claude-code, Anthropic maintient un devcontainer de référence avec pare-feu sortant en refus par défaut (liste blanche npm, GitHub, API Anthropic…). Cela rend défendable l'exécution d'agents sans surveillance dans la documentation.

La documentation Development containers est claire : le dev container tourne dans Docker, l'éditeur (Cursor, VS Code, JetBrains…) s'y connecte. Le terminal et les outils de build s'exécutent dans le conteneur ; vos fichiers édités restent mappés vers le dépôt local. Claude Code aussi — « recommander Docker » ne signifie pas tout déplacer dans un conteneur, mais délimiter l'espace de travail de l'agent IA.

Pour les vrais débutants : c'est quoi Docker ?

Oubliez Kubernetes et les microservices pour l'instant. Une seule image suffit :

Un conteneur Docker = un « mini-ordinateur » léger et jetable avec un extrait d'OS, Node/Python et vos outils. Il partage le CPU avec votre machine réelle, mais le système de fichiers et le réseau se configurent séparément.

Par rapport aux VM : démarrage rapide, empreinte réduite. Par rapport à « installer sur l'hôte » : un conteneur ne laisse pas de résidus — crucial quand l'IA teste dix combinaisons de dépendances en une journée.

Trois termes à retenir :

Pour les bases Docker : Docker Get started. Ici, le chemin le plus court pour Claude Code.

Que contient le devcontainer officiel d'Anthropic ?

Le dossier .devcontainer/ de anthropics/claude-code n'est pas décoratif : c'est un modèle de développement sécurisé reproductible :

• devcontainer.json : volumes, variables d'environnement, extensions VS Code/Cursor, Feature d'installation Claude Code ;
• Dockerfile : image de base (Debian/Ubuntu), outils de dev, utilisateur non root ;
• init-firewall.sh : trafic sortant refusé par défaut, domaines en liste blanche — souvent oublié dans les Dockerfiles maison.

La doc recommande le Claude Code Dev Container Feature. Exemple minimal dans devcontainer.json :

{
                  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
                  "features": {
                    "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
                  },
                  "remoteUser": "node",
                  "mounts": [
                    "source=claude-code-config-${devcontainerId},target=/home/node/.claude,type=volume"
                  ],
                  "containerEnv": {
                    "DISABLE_AUTOUPDATER": "1"
                  }
                }

Le volume nommé pour ~/.claude dans mounts : après reconstruction, connexion et historique de session persistent — pas de réauthentification à chaque fois.

Si vous utilisez déjà ECC (Everything Claude Code), le devcontainer est la « couche matérielle » : ECC gère skills et hooks, Docker fixe où les commandes Claude touchent le système de fichiers.

Sécurité : pourquoi « ignorer les permissions » n'a de sens que dans le conteneur

Claude Code demande confirmation pour presque chaque bash et chaque écriture de fichier. En CI ou pour des tâches longues sans surveillance, certains ajoutent --dangerously-skip-permissions.

Position officielle : ce flag est conçu pour un devcontainer durci — pas pour le bureau sur l'hôte. Sans confirmation sur l'hôte, l'IA opère sans limite dans votre répertoire utilisateur — suppression de fichiers, lecture de secrets, requêtes vers n'importe quelle URL. Un conteneur offre au minimum :

• Frontière fichiers : uniquement le projet + volumes de config nécessaires ;
• Frontière réseau : pare-feu sortant limitant les destinations ;
• Frontière utilisateur : exécution non root, sudo restreint.

Les conteneurs ne sont pas une panacée. Si vous montez ~/.aws ou des URL de prod dans .env, l'IA peut les lire. La sécurité dépend de ce que vous montez et de la confiance accordée au dépôt. Officiellement : « Only use dev containers when developing with trusted repositories. »

Pas à pas : première exécution de Claude Code avec Docker

Un parcours validé sur macOS / Windows (WSL2), sans avoir lu l'intégralité de la doc Docker.

Étape 1 : installer le moteur Docker

Une option suffit ; l'important est l'uniformité en équipe :

• macOS : Docker Desktop (le plus simple) ; sur Apple Silicon, Colima ou OrbStack aussi — CLI compatible docker ;
• Windows : Docker Desktop avec backend WSL2 ;
• Linux : Docker Engine ou Podman rootless (vérifier le support devcontainer CLI).

Ensuite en terminal : docker --version et docker run hello-world — « Hello from Docker », c'est gagné.

Étape 2 : préparer le projet et le devcontainer

À la racine du dépôt, créez .devcontainer/. Soit :

1. Copier la config de référence depuis anthropics/claude-code et adapter le Dockerfile ; ou
2. Dans Cursor / VS Code : Dev Containers: Add Dev Container Configuration Files, puis ajouter le Feature Claude Code selon la doc.

Sans écrire à la main : demandez à Claude Code (CLI installé une fois en local) : « Génère un .devcontainer pour ce projet Node 20 avec Feature Claude Code et pnpm. » — puis vérifiez manuellement les montages et le pare-feu.

Étape 3 : ouvrir le projet dans le conteneur

Cursor / VS Code : palette de commandes → Dev Containers: Reopen in Container. La première construction de l'image prend quelques minutes ; ensuite, démarrage incrémental plus rapide. Prompt shell modifié, which node pointe vers le conteneur — vous êtes « dans la boîte ».

Terminal uniquement ? Exemple conceptuel :

# À la racine du projet, avec docker-compose.yml
                docker compose up -d
                docker compose exec dev bash
                claude

Le nom du service suit votre fichier compose ; devcontainer standardise ce flux.

Étape 4 : vérifier Claude Code dans le conteneur

Dans le terminal du conteneur, lancez claude et testez quelque chose de simple : « Liste les scripts de package.json et explique-les. » Vérifiez :

• Les modifications apparaissent-elles dans le statut Git de l'hôte ? (bind mount OK)
• cat /etc/os-release affiche-t-il l'OS du conteneur, pas celui de l'hôte ?
• Un chemin non monté est-il refusé si Claude tente d'y accéder ?

Tout est conforme → l'isolation fonctionne. Désormais, la doc d'équipe peut imposer : « Reopen in Container avant Claude Code » — plus d'installation Node séparée pour les nouveaux.

Quand Docker n'est vraiment pas nécessaire

Recommandation ≠ obligation. Dans ces cas, le natif est souvent plus simple :

Règle simple : « Suis-je prêt à laisser l'IA exécuter des commandes en mon absence ? » Oui, et dépôt de confiance → conteneur avec montages stricts. Non → interactif sur l'hôte suffit.

Utilisateurs Mac : faire cohabiter Docker et l'écosystème Apple

Beaucoup alternent Xcode et full-stack assisté par IA. Répartition courante :

• Xcode, simulateur, signature restent sur macOS ;
• Services Node/Python, longues sessions Claude Code, scripts expérimentaux dans le devcontainer ;
• Pour un backend d'équipe unifié : docker-compose.yml dans le dépôt, API testées dans le conteneur.

Sur Apple Silicon, évitez les images x86 — préférez arm64. Allouez au moins 4 à 8 Go de RAM à Docker Desktop, sinon dev server + Claude swappent vite.

Dépannage rapide

• Reconnexion après Rebuild : vérifiez que ~/.claude est monté en volume nommé, pas seulement dans la couche writable du conteneur.
• Pas d'accès npm / GitHub : liste blanche de init-firewall.sh ; proxy d'entreprise → HTTP_PROXY.
• Port 3000 inaccessible : forwardPorts dans devcontainer ou mapping dans compose.
• Permission denied : remoteUser doit pouvoir écrire ; sous Linux, aligner l'UID des bind mounts.
• Docker Desktop ne démarre pas : Windows → WSL2 ; Mac → virtualisation bloquée par un antivirus ?

Questions fréquentes (FAQ)

Claude Code et l'agent Cursor ont-ils tous deux besoin de Docker ?

Non. L'agent Cursor tourne par défaut dans votre workspace local ; Claude Code est une CLI autonome avec un support devcontainer de premier ordre. Édition dans Cursor, claude dans le terminal du conteneur — les deux coexistent.

Le devcontainer impose-t-il VS Code ?

Non. La spec a été popularisée par VS Code, mais Cursor, JetBrains et GitHub Codespaces la supportent. docker compose + shell pur fonctionne aussi — sans le confort graphique de Reopen in Container.

Je déploie déjà avec docker compose — est-ce redondant ?

Non. Le compose de déploiement vise la mise en production ; le devcontainer, l'endroit où Claude travaille en développement. Même logique, objectifs de config différents. L'expérience déploiement aide pour les montages et le réseau.

Comment mettre à jour Claude Code dans le conteneur ?

Le Feature officiel installe la dernière CLI avec mise à jour auto. Pour figer une version : dans le Dockerfile ou DISABLE_AUTOUPDATER dans containerEnv.

L'entreprise interdit Docker Desktop ?

Demandez à l'IT un hôte devcontainer distant, GitHub Codespaces ou un espace dev K8s interne. Claude Code a besoin d'un « environnement Linux isolé » — pas forcément Docker sur le portable.

En résumé : Docker n'est pas un devoir, c'est la « ceinture de sécurité » de Claude Code

Retour à la question : pourquoi Claude Code recommande Docker ?

• Parce que les assistants de code IA exécutent, ils ne se contentent plus de suggérer ;
• Parce que les équipes ont besoin du même environnement reconstruisible, pas de captures d'écran pour installer Node ;
• Parce qu'Anthropic veut enfermer le mode sans surveillance derrière un pare-feu dans le conteneur — pas le laisser errer dans ~/.

Pour un débutant, une seule action aujourd'hui : dans un petit projet, Reopen in Container, tapez claude une fois dans le terminal du conteneur, et constatez que les commandes s'exécutent dedans tandis que les fichiers changent sur l'hôte. Vous serez en avance sur la plupart des lecteurs de doc.

ECC, MCP ou agent sur VPS — Docker devient l'« installateur universel » de l'ère IA. Claude Code l'a simplement écrit plus tôt et plus explicitement dans ses lignes de sécurité.