Claude Code dans un devcontainer

Un environnement de développement sandboxé pour exécuter Claude Code avec bypassPermissions activé en toute sécurité. Développé chez Trail of Bits pour les workflows d'audit de sécurité.

Pourquoi l'utiliser ?

Exécuter Claude avec bypassPermissions sur votre machine hôte est risqué : il peut exécuter n'importe quelle commande sans confirmation. Ce devcontainer fournit une isolation du système de fichiers pour que vous profitiez des avantages de productivité d'un Claude sans restriction, sans mettre en danger votre système hôte.

Conçu pour :

• Audits de sécurité : examiner le code client sans risquer votre hôte
• Dépôts non fiables : explorer des bases de code inconnues en toute sécurité
• Travaux expérimentaux : laisser Claude modifier le code librement en isolation
• Engagements multi-dépôts : travailler sur plusieurs dépôts liés

Prérequis

• Runtime Docker (l'un des suivants) :

  • Docker Desktop - assurez-vous qu'il est en cours d'exécution
  • OrbStack
  • Colima : brew install colima docker && colima start

• Pour les workflows en terminal (installation unique) :

  root@kitploit:~

  npm install -g @devcontainers/cli
  git clone https://github.com/trailofbits/claude-code-devcontainer ~/.claude-devcontainer
  ~/.claude-devcontainer/install.sh self-install
  

# Stop and delete current VM (removes containers/images)
colima stop && colima delete

# Start with optimized settings
colima start \
  --cpu 4 \
  --memory 8 \
  --disk 100 \
  --vm-type vz \
  --vz-rosetta \
  --mount-type virtiofs

Démarrage rapide

Choisissez le modèle qui correspond à votre workflow :

Modèle A : Conteneur par projet (isolé)

Chaque projet dispose de son propre conteneur avec des volumes indépendants. Idéal pour les revues ponctuelles, les dépôts non fiables, ou lorsque vous avez besoin d'isolation entre les projets.

Terminal :

git clone <untrusted-repo>
cd untrusted-repo
devc .          # Installs template + starts container
devc shell      # Opens shell in container

VS Code / Cursor :

1. Installez l'extension Dev Containers :

   • VS Code : ms-vscode-remote.remote-containers
   • Cursor : anysphere.remote-containers

2. Configurez le devcontainer (choisissez une option) :

   root@kitploit:~

   # Option A: Use devc (recommended)
   devc .
   
   # Option B: Clone manually
   git clone https://github.com/trailofbits/claude-code-devcontainer .devcontainer/
   

3. Ouvrez le dossier de votre projet dans VS Code, puis :

   • Appuyez sur Cmd+Shift+P (Mac) ou Ctrl+Shift+P (Windows/Linux)
   • Saisissez « Reopen in Container » et sélectionnez Dev Containers: Reopen in Container

Modèle B : Conteneur d'espace de travail partagé (groupé)

Un répertoire parent contient la configuration du devcontainer, et vous clonez plusieurs dépôts à l'intérieur. Volumes partagés entre tous les dépôts. Idéal pour les engagements clients, les dépôts liés ou les travaux en cours.

# Create workspace for a client engagement
mkdir -p ~/sandbox/client-name
cd ~/sandbox/client-name
devc .          # Install template + start container
devc shell      # Opens shell in container

# Inside container:
git clone <client-repo-1>
git clone <client-repo-2>
cd client-repo-1
claude          # Ready to work

Authentification par jeton (sans interface graphique)

Pour les serveurs sans interface graphique ou pour ignorer l'assistant de connexion interactif :

claude setup-token                          # run on host, one-time
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
devc rebuild                                # rebuilds with token

Le jeton est transféré dans le conteneur. À chaque création de conteneur, post_install.py exécute une poignée de main d'authentification unique afin que claude démarre sans l'assistant de connexion.

Cela contourne le fait que l'assistant d'intégration interactif de Claude Code s'affiche toujours dans les conteneurs, même avec des identifiants valides (#8938).

Si vous ne définissez pas de jeton, le flux de connexion interactif fonctionne comme avant.

Commandes utilitaires CLI

devc .              Install template + start container in current directory
devc up             Start the devcontainer
devc rebuild        Rebuild container (preserves persistent volumes)
devc destroy [-f]   Remove container, volumes, and image for current project
devc down           Stop the container
devc shell          Open zsh shell in container
devc exec CMD       Execute command inside the container
devc upgrade        Upgrade Claude Code in the container
devc mount SRC DST  Add a bind mount (host → container)
devc sync [NAME]    Sync Claude Code sessions from devcontainers to host
devc template DIR   Copy devcontainer files to directory
devc self-install   Install devc to ~/.local/bin

Remarque : Utilisez devc destroy pour nettoyer les ressources Docker d'un projet. La suppression manuelle de conteneurs (par exemple, docker rm) laissera des volumes et des images orphelins que devc destroy ne pourra pas retrouver.

Synchronisation des sessions pour /insights

La commande /insights de Claude Code analyse votre historique de sessions, mais elle ne lit que depuis ~/.claude/projects/ sur l'hôte. Les sessions dans les volumes du devcontainer lui sont invisibles.

devc sync copie les journaux de sessions de tous les devcontainers (en cours d'exécution ou arrêtés) vers l'hôte afin que /insights puisse les inclure :

devc sync              # Sync all devcontainers
devc sync crypto       # Filter by project name (substring match)

Les devcontainers sont automatiquement détectés via les labels Docker — pas besoin de connaître les noms ou ID des conteneurs. La synchronisation est incrémentale, il est donc sûr de l'exécuter à plusieurs reprises.

Partage de fichiers

VS Code / Cursor

Glissez les fichiers de votre hôte dans le panneau Explorateur de VS Code — ils sont copiés automatiquement dans /workspace/. Aucune configuration nécessaire.

Terminal : devc mount

Pour rendre un répertoire hôte disponible à l'intérieur du conteneur :

devc mount ~/drop /drop           # Read-write
devc mount ~/secrets /secrets --readonly

Cela ajoute un montage bind à devcontainer.json et recrée le conteneur. Les montages existants sont conservés lors des mises à jour de devc template.

Astuce : Une zone de dépôt partagée est utile pour faire passer des fichiers sans monter l'intégralité de votre répertoire personnel.

Note de sécurité : Évitez de monter de grands répertoires hôte (par exemple, $HOME). Chaque chemin monté est accessible en écriture depuis le conteneur, sauf si --readonly est spécifié, ce qui fragilise l'isolation du système de fichiers fournie par ce projet.

Isolation réseau

Par défaut, les conteneurs disposent d'un accès réseau sortant complet. Pour une sécurité plus stricte, utilisez iptables pour restreindre l'accès réseau.

Quand activer l'isolation réseau

• Examiner du code pouvant contenir des dépendances malveillantes
• Auditer des logiciels avec télémétrie ou comportement de communication vers l'extérieur
• Isolation maximale pour des revues très sensibles

Exemple : Claude + GitHub + registres de paquets

sudo iptables -A OUTPUT -d api.anthropic.com -j ACCEPT
sudo iptables -A OUTPUT -d github.com -j ACCEPT
sudo iptables -A OUTPUT -d raw.githubusercontent.com -j ACCEPT
sudo iptables -A OUTPUT -d registry.npmjs.org -j ACCEPT
sudo iptables -A OUTPUT -d pypi.org -j ACCEPT
sudo iptables -A OUTPUT -d files.pythonhosted.org -j ACCEPT
sudo iptables -A OUTPUT -o lo -j ACCEPT
sudo iptables -A OUTPUT -j DROP

Compromis

• Bloque les gestionnaires de paquets sauf si vous autorisez certains registres
• Peut casser les outils qui nécessitent un accès réseau
• La résolution DNS fonctionne toujours (envisagez de la bloquer si vous êtes paranoïaque)

Modèle de menace

La principale menace traitée par ce projet est l'exécution de commandes arbitraires par Claude Code sur votre machine hôte. Lorsque bypassPermissions est activé, Claude exécute des commandes shell, installe des paquets et modifie des fichiers sans confirmation. Sur une machine hôte, cela signifie qu'il peut modifier votre configuration shell, rm -rf en dehors du répertoire du projet, ou abuser des identifiants stockés localement. Le devcontainer confine tout cela dans un conteneur jetable où le rayon d'impact est limité à /workspace.

Le conteneur inclut des outils de développement courants afin que vous puissiez effectuer tout votre travail de développement à l'intérieur - pas seulement exécuter Claude. Le workflow prévu est : cloner un dépôt, démarrer le devcontainer, et travailler entièrement à l'intérieur. Si votre projet nécessite des runtimes ou outils supplémentaires au-delà de ceux inclus, ajoutez-les au Dockerfile pour une utilisation répétée ou installez-les ponctuellement avec devc exec.

Pour les limites précises de ce qui est isolé et de ce qui ne l'est pas, voir Modèle de sécurité ci-dessous. Une nuance qu'il vaut la peine de souligner : le runtime du devcontainer transfère automatiquement le socket de l'agent SSH de votre hôte (SSH_AUTH_SOCK) dans le conteneur. Cela permet au code à l'intérieur du conteneur de s'authentifier comme vous via SSH (par exemple, git push), mais les clés privées réelles restent sur l'hôte et ne sont jamais exposées au conteneur.

Modèle de sécurité

Ce devcontainer fournit une isolation du système de fichiers mais pas un sandboxing complet.

Sandboxé : Système de fichiers (fichiers hôte inaccessibles), processus (isolés de l'hôte), installations de paquets (restent dans le conteneur)

Non sandboxé : Réseau (accès sortant complet par défaut—voir Isolation réseau), identité git (~/.gitconfig monté en lecture seule), agent SSH (socket transféré, clés restent sur l'hôte), socket Docker (non monté par défaut)

Le conteneur configure automatiquement le mode bypassPermissions — Claude exécute les commandes sans confirmation. Cela serait risqué sur une machine hôte, mais le conteneur lui-même est le sandbox.

Détails du conteneur

Les volumes sont stockés à l'extérieur du conteneur, de sorte que votre historique shell, vos paramètres Claude et votre connexion gh persistent même après devc rebuild. Le ~/.gitconfig de l'hôte est monté en lecture seule pour l'identité git.

Dépannage

« devcontainer CLI introuvable »

npm install -g @devcontainers/cli

Le conteneur ne démarre pas

1. Vérifiez que Docker est en cours d'exécution
2. Essayez de reconstruire : devc rebuild
3. Vérifiez les journaux : docker logs $(docker ps -lq)

L'authentification GitHub CLI ne persiste pas

Le volume gh peut nécessiter une correction de propriété :

sudo chown -R $(id -u):$(id -g) ~/.config/gh

Python/uv ne fonctionne pas

Python est géré via uv :

uv run script.py              # Run a script
uv add package                # Add project dependency
uv run --with requests py.py  # Ad-hoc dependency

Développement

Construisez l'image manuellement :

devcontainer build --workspace-folder .

Testez le conteneur :

devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . zsh