Claude Code dans un dev container : l'installation sûre et reproductible
Installez l'extension Dev Containers, gardez Docker lancé, ajoutez la feature officielle claude-code, Reopen in Container, connectez-vous depuis le terminal et gardez l'authentification en vie entre les rebuilds — chaque étape vérifiée contre la documentation dev container d'Anthropic.
L'essentiel
- Installez l'extension Dev Containers, gardez Docker lancé, puis Reopen in Container sur n'importe quel dépôt avec .devcontainer/ — Claude Code et chaque commande qu'il exécute tournent dans le conteneur, pas sur votre machine.
- La feature officielle — "ghcr.io/anthropics/devcontainer-features/claude-code:1.0" dans le bloc features — installe la CLI dans n'importe quel devcontainer ; VS Code reçoit aussi l'extension, et les deux partagent un même ~/.claude.
- Connectez-vous depuis le terminal du conteneur ; si le callback du navigateur ne l'atteint pas, collez le code à l'invite. Faites survivre l'authentification aux rebuilds avec un volume ~/.claude plus containerEnv.CLAUDE_CONFIG_DIR.
- Un dev container remplace l'environnement (le /sandbox, lui, confine les commandes individuelles sur votre machine). Les deux se composent — conteneur pour l'environnement, sandbox et demandes de permission pour le comportement.
Run Your AI Coding Agent in Dev Containers - Complete Beginner's Guide
Chaîne : Visual Studio Code15:39
Step-by-Step: Run Claude Code SAFELY in a Dev Container
Chaîne : Fuzz Puppy6:56
Development containers — official documentation
Documentation officielle : code.claude.com/docs
Chaque étape de configuration, nom de feature et chemin d'identifiants de cette page est vérifié contre la documentation officielle des development containers ; les vidéos ci-dessus sont les sources visuelles et factuelles.
Les captures d'écran sont attribuées à leurs créateurs, avec des liens profonds vers les horodatages exacts. Aucune image de visage filmé n'est utilisée.
Exécuter Claude Code dans un dev container, pas à pas
Partie 1 — Prérequis : VS Code rencontre Docker
- 1
Installer l'extension Dev Containers
Ouvrez la vue Extensions de VS Code et installez Dev Containers de Microsoft. Cette extension ajoute l'indicateur distant dans la barre de statut, la commande Reopen in Container et le Remote Explorer — tout le flux ci-dessous passe par elle. Pas besoin de Docker pour l'instant.
L'extension Dev Containers est ce qui ajoute Reopen in Container à VS Code — installez-la d'abord depuis la vue Extensions.Voir à 2:00 - 2
Installer Docker Desktop et le démarrer
Les dev containers sont de vrais conteneurs : un moteur de conteneurs doit donc tourner avant que quoi que ce soit s'ouvre. Docker Desktop est le choix habituel sur macOS et Windows ; Docker Engine convient sous Linux. Démarrez-le et laissez-le tourner — un moteur éteint est la cause numéro un d'un "Opening Remote" bloqué au premier essai.
Docker Desktop a juste besoin de tourner ; une liste de conteneurs vide, c'est exactement l'allure d'une configuration saine avant le premier conteneur.Voir à 2:12 - 3
Savoir ce qui change pour Claude Code
Après Reopen in Container, VS Code exécute son serveur dans le conteneur — et chaque commande que Claude Code exécute aussi. Installations, lancements de tests et modifications de fichiers restent dans le conteneur pendant que le dossier de workspace est remonté vers votre dépôt. Votre machine n'a besoin que de VS Code et Docker ; les toolchains et dépendances vivent dans l'image, et une expérience hasardeuse de l'agent ne peut rien toucher au-dehors.
Partie 2 — Un conteneur fonctionnel, de bout en bout
- 4
Ouvrir un dev container prêt à l'emploi
Le moyen le plus rapide de voir la mécanique en action : dans le Remote Explorer, choisissez un exemple comme le dev container Go. VS Code clone github.com/microsoft/vscode-remote-try-go et l'ouvre dans un volume de conteneur — sans aucune configuration écrite par vous.
Le Remote Explorer embarque des exemples prêts à l'emploi — choisissez-en un et VS Code clone le dépôt directement dans un volume de conteneur.Voir à 2:30 - 5
Laisser VS Code construire et se connecter
La première connexion clone le dépôt, télécharge l'image du conteneur couche par couche et démarre le conteneur — la barre de statut annonce "Connecting to Dev Container". Sur une connexion lente, c'est la plus longue attente de l'installation ; chaque ouverture suivante réutilise l'image et prend quelques secondes.
La première build télécharge l'image du conteneur couche par couche ; la barre de statut suit la connexion au dev container.Voir à 2:52 - 6
Confirmer que le terminal est dans le conteneur
Ouvrez un nouveau terminal et affichez la version du toolchain (go version ici). La sortie nomme l'OS et l'architecture du conteneur, pas ceux de votre portable. Ce terminal est exactement là où vous lanceriez claude — et tout ce qu'il exécute reste dans le conteneur.
go version affiche le toolchain du conteneur, pas celui de votre portable — lancez claude dans ce terminal et il restera dedans aussi.Voir à 3:50 - 7
Lire le devcontainer.json
Le fichier .devcontainer/devcontainer.json définit tout l'environnement : l'image de base (ou un Dockerfile), les extensions VS Code à installer dans le conteneur, les ports redirigés, les étapes postCreateCommand et le remoteUser. Pour Claude Code, ce fichier accueille aussi la feature officielle et le volume d'identifiants — traités aux étapes 9 et 13.
Tout ce dont le conteneur est fait vit dans .devcontainer/devcontainer.json : image, extensions, ports redirigés, commandes post-create.Voir à 4:40 - 8
Pointer l'agent vers le workspace
Joignez @workspace dans le panneau de l'agent et demandez-lui d'expliquer le projet. L'explication et chaque commande derrière s'exécutent dans le conteneur. Claude Code fonctionne de même une fois sa CLI installée dans l'image : contexte à la @workspace plus des commandes qui ne quittent jamais le conteneur.
Demander à l'agent d'expliquer le projet via @workspace — chaque commande qu'il lance s'exécute dans le conteneur.Voir à 5:20 - 9
Passer à la feature officielle Claude Code
Sans installation manuelle : ajoutez "ghcr.io/anthropics/devcontainer-features/claude-code:1.0" au bloc features de devcontainer.json et reconstruisez. La feature installe la CLI — et, quand le conteneur s'ouvre dans VS Code, l'extension Claude Code aussi, partageant le même ~/.claude que le terminal. Si l'image de base n'a pas de Node.js, vous verrez "Failed to install Node.js and npm" : ajoutez la feature Node au-dessus. Les réglages d'environnement comme CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC ou DISABLE_AUTOUPDATER vont sous containerEnv, et des mounts peuvent tirer vos autres dépôts locaux dans le conteneur.
- 10
Lancer l'application et utiliser le port redirigé
Démarrez l'application depuis le conteneur (panneau de debug, npm run dev, go run — ce que le stack exige) et VS Code détecte le port en écoute : une notification propose de l'ouvrir dans votre navigateur local. Le serveur ne quitte jamais le conteneur ; la redirection fait juste que localhost se comporte comme d'habitude.
L'application tourne sur le port 9000 dans le conteneur ; VS Code le redirige pour que localhost fonctionne exactement comme d'habitude.Voir à 6:08
Partie 3 — Votre propre dépôt et la connexion
- 11
Ajouter un dev container à votre propre projet
Dans n'importe quel dépôt, lancez Dev Containers: Add Dev Container Configuration Files depuis la palette de commandes ou l'indicateur distant, et choisissez "Add configuration to workspace folder". Commitée avec le code, la configuration offre à vos collègues — et à Codespaces — le même environnement gratuitement.
Pas encore de devcontainer.json ? VS Code en génère un depuis un modèle — gardez-le dans le workspace pour que git le partage.Voir à 9:00 - 12
Choisir le modèle et les features
VS Code propose un modèle correspondant à votre stack (Node.js, Python, Go…), puis montre la liste des features — des installateurs réutilisables comme Git LFS ou la GitHub CLI. C'est dans cette même liste que s'insère la feature claude-code de l'étape 9. Acceptez les défauts (ou laissez l'agent affiner le fichier généré), puis rouvrez dans le conteneur.
La liste des features est l'endroit où s'insère une ligne de feature Claude Code à côté de ce que le modèle propose.Voir à 9:48 - 13
Se connecter dans le conteneur
Lancez claude dans le terminal intégré et choisissez votre connexion (abonnement Claude ou Anthropic Console). Le navigateur s'ouvre sur votre hôte ; si le callback n'atteint pas le conteneur, copiez le code depuis le navigateur et collez-le à l'invite "Paste code here if prompted". Pour survivre aux rebuilds, montez un volume sur ~/.claude et réglez containerEnv.CLAUDE_CONFIG_DIR sur le même chemin — le fichier de compte ~/.claude.json vit hors de ce dossier, voilà pourquoi les deux moitiés comptent. Pour les exécutions headless ou Codespaces, générez un jeton avec claude setup-token et passez ANTHROPIC_API_KEY ou CLAUDE_CODE_OAUTH_TOKEN.
Dev container vs /sandbox : quel isolement vous faut-il ?
Claude Code livre deux réponses d'isolement qui résolvent des problèmes différents. Un dev container remplace l'environnement où travaille l'agent ; le sandbox intégré confine les commandes qu'il lance sur votre machine actuelle. La documentation officielle les pose comme complémentaires — le devcontainer de référence embarque même un script de restriction du trafic sortant.
- 1Périmètre. Un dev container échange tout l'environnement — OS, toolchain, dépendances — contre celui défini dans devcontainer.json. Le sandboxing garde votre machine et restreint ce que chaque commande bash peut lire, écrire et atteindre sur le réseau.
- 2Prérequis. Les dev containers exigent Docker (Desktop ou Engine) plus l'extension Dev Containers ; le sandboxing est intégré à Claude Code et n'a besoin de ni l'un ni l'autre.
- 3Mécanique d'équipe. devcontainer.json est commité, chaque collègue et chaque Codespace construit donc l'environnement identique ; la politique de sandbox vit dans les réglages de Claude Code et suit l'utilisateur, pas le dépôt.
- 4Rayon de dégâts. Dans un conteneur, un rm -rf malheureux ou une installation malveillante frappe un système de fichiers jetable et votre hôte reste intact. Le sandbox vise le même résultat, commande par commande — sans frontière de conteneur.
- 5Choisissez un dev container quand le projet lui-même a besoin d'un environnement : runtimes multiples, intégration propre, développement cloud. Choisissez le sandbox comme garde-fou quotidien pour les sessions sur votre hôte. Les deux se composent — lancez Claude Code dans un dev container et gardez sandboxing et demandes de permission actifs.
Une ligne de plus les départage : /sandbox est une politique par session, ajustable en cours de conversation, tandis qu'un dev container se décide avant le début de la session — le changer suppose un rebuild. Les exécutions en lot non surveillées s'appuient sur les deux à la fois : utilisateur de conteneur non root, trafic sortant restreint et --dangerously-skip-permissions uniquement dans le conteneur.
Quelque chose se comporte mal ? Commencez ici
La plupart des frictions du dev container avec Claude Code tombent dans une poignée de schémas connus. Chaque correctif ci-dessous vient droit de la documentation officielle des development containers.
- 1"Failed to install Node.js and npm" pendant l'installation de la feature : l'image de base n'a pas de Node.js. Ajoutez la feature Node (ghcr.io/devcontainers/features/node:1) au-dessus de la feature claude-code dans le bloc features et reconstruisez.
- 2La connexion aboutit dans le navigateur mais le conteneur reste déconnecté : le callback OAuth n'atteint pas le conteneur. Copiez le code affiché dans le navigateur et collez-le à l'invite "Paste code here if prompted" du terminal.
- 3Connexion et réglages disparaissent après chaque rebuild : rien ne persiste ~/.claude. Montez un volume nommé sur ce chemin et réglez containerEnv.CLAUDE_CONFIG_DIR dessus — incluez la variable devcontainerId dans le nom du volume pour que les projets restent isolés. Sur Codespaces, le dossier survit à stop/start mais est effacé lors d'un rebuild complet ; fournissez donc ANTHROPIC_API_KEY ou un CLAUDE_CODE_OAUTH_TOKEN de claude setup-token comme secret.
- 4Surprises de version de Claude Code : le tag de feature claude-code:1.0 épinglant le script d'installation, pas la CLI — la dernière version est installée et se met à jour automatiquement dans le conteneur. Pour geler une version, installez-la dans le Dockerfile avec npm install -g @anthropic-ai/claude-code@X.Y.Z.
- 5"Is Docker running?" ou un "Opening remote" bloqué : le moteur est injoignable — démarrez Docker Desktop (ou le daemon) et réessayez. Si --dangerously-skip-permissions refuse de démarrer, le conteneur tourne en root ; réglez remoteUser sur un utilisateur non root comme "vscode". Les organisations peuvent désactiver totalement le mode bypass via managed-settings.json dans /etc/claude-code.
Reconstruire est le retry universel : palette de commandes → "Dev Containers: Rebuild Container" relit devcontainer.json et relance les features après toute modification. Si un rebuild se comporte différemment d'un clone frais, supprimez le conteneur et rouvrez — images et volumes nommés survivent à la suppression.