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) :

  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) :

   # 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