cloche

Lance Claude Code dans un conteneur podman, avec le dossier courant monté comme espace de travail. Claude n'a accès qu'à ce dossier, et aux éventuels dossiers que vous ajoutez explicitement, pas au reste de votre machine.

Prérequis

• podman 4.3 ou plus récent, en mode rootless (utilisateur normal, pas root)
• bash
• just, facultatif, pour l'installation en une commande

Installation

git clone <url-du-dépôt> ~/cloche
cd ~/cloche
just deploy

just deploy vérifie le script, crée le lien symbolique ~/.local/bin/cloche et construit l'image. Vérifiez que ~/.local/bin est dans votre PATH ; just vous prévient si ce n'est pas le cas.

Sans just, le lien symbolique suffit, l'image étant alors construite au premier lancement :

ln -s ~/cloche/cloche ~/.local/bin/cloche

Dans les deux cas, le script retrouve le Containerfile à côté de son emplacement réel : ne déplacez pas le dépôt après l'installation, ou relancez just install.

Recettes just

Recette	Effet
just deploy	Enchaîne check, install et build
just install	Crée le lien symbolique vers le script (refuse d'écraser un vrai fichier)
just build	Construit l'image si elle n'existe pas encore
just rebuild	Reconstruit l'image de zéro (met à jour Claude Code)
just check	Vérifie la syntaxe du script
just uninstall	Supprime le lien symbolique et l'image ; la configuration de Claude reste

CLOCHE_BINDIR change le dossier du lien symbolique (défaut : ~/.local/bin). Les recettes respectent aussi CLOCHE_IMAGE et, pour construire l'image derrière un proxy, les variables de la section « Proxy HTTP sortant ».

Utilisation

cd ~/mon-projet
cloche

Au premier lancement, l'image est construite si elle ne l'a pas déjà été (quelques minutes), puis Claude Code vous demande de vous connecter. La connexion est conservée pour les lancements suivants.

Tout ce qui suit les options de cloche est transmis à claude :

cloche --continue
cloche -p "résume ce dépôt"

Options

Option	Effet
--rebuild	Reconstruit l'image avant de lancer (met à jour Claude Code)
--build-only	Construit l'image si besoin (ou de zéro avec --rebuild) puis quitte
--shell	Ouvre un shell bash dans le conteneur au lieu de Claude Code
--include CHEMIN	Monte un dossier de plus sur /work/<nom>, en lecture/écriture ; répétable
--include-ro CHEMIN	Idem, en lecture seule ; répétable
--cloche-help	Affiche l'aide du script

Ces options doivent être placées avant les arguments destinés à claude.

Travailler sur plusieurs projets

Pour donner à Claude accès à d'autres dossiers que le projet courant, ajoutez-les avec --include (ou --include-ro si Claude doit seulement les lire) :

cd ~/mon-projet
cloche --include ../ma-lib --include-ro ~/docs-api

Chaque dossier est monté à côté du projet, sur /work/<nom-du-dossier> (ici /work/ma-lib et /work/docs-api), et transmis à Claude Code par son option --add-dir, qui les ajoute à son espace de travail au même titre que le projet. Le projet courant reste le dossier de travail du conteneur. Avec --shell, les dossiers sont montés mais rien n'est transmis à Claude Code.

Variables d'environnement

Variable	Rôle	Défaut
CLOCHE_IMAGE	Nom de l'image utilisée	localhost/cloche:latest
CLOCHE_CONFIG_DIR	Dossier hôte de la configuration de Claude	~/.local/share/cloche
CLOCHE_PROXY	Proxy sortant, tel que vu du conteneur	variables de proxy de l'hôte

ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL et CLAUDE_CODE_OAUTH_TOKEN sont transmises au conteneur si elles sont définies sur l'hôte, de même que les variables de proxy décrites ci-dessous.

Proxy HTTP sortant

Si votre réseau impose un proxy, exportez comme d'habitude HTTPS_PROXY et HTTP_PROXY (et NO_PROXY si besoin) sur l'hôte, en majuscules ou en minuscules. cloche les transmet à la construction de l'image (apt, npm) comme au conteneur (Claude Code, git, curl) :

export HTTPS_PROXY=http://proxy.exemple.fr:3128 HTTP_PROXY=http://proxy.exemple.fr:3128
cloche

Si le proxy n'a pas la même adresse vu du conteneur, donnez celle-ci dans CLOCHE_PROXY : elle remplace alors HTTP_PROXY et HTTPS_PROXY dans le conteneur et dans les étapes de construction. C'est le cas d'un proxy local à votre machine (cntlm, px…), car localhost désigne dans le conteneur le conteneur lui-même ; cloche affiche un avertissement dans cette situation. L'hôte y est joignable sous le nom host.containers.internal :

export CLOCHE_PROXY=http://host.containers.internal:3128

Selon la version de podman et son mode réseau, ce nom peut mener à une adresse de l'hôte autre que 127.0.0.1 : le proxy local doit alors écouter aussi sur cette adresse, pas seulement en boucle locale.

Le téléchargement de l'image de base est fait par podman sur l'hôte, donc toujours avec les variables de proxy de l'hôte. NO_PROXY est toujours repris de l'hôte.

Si l'URL du proxy contient un mot de passe, celui-ci est visible dans le conteneur et, avec CLOCHE_PROXY, dans la liste des processus de l'hôte tant que le conteneur tourne.

Ce que voit le conteneur

Sur l'hôte	Dans le conteneur	Accès
Dossier courant ($PWD)	/work/<nom-du-dossier>	lecture/écriture
~/.local/share/cloche	/home/node/.claude	lecture/écriture
~/.gitconfig (s'il existe)	/home/node/.gitconfig	lecture seule
Dossiers --include	/work/<nom-du-dossier>	lecture/écriture
Dossiers --include-ro	/work/<nom-du-dossier>	lecture seule

Rien d'autre n'est partagé : ni vos clés SSH, ni le reste de votre dossier personnel. Le conteneur a en revanche accès au réseau.

Le conteneur est supprimé à la sortie (--rm). Seuls le dossier de travail et la configuration de Claude (connexion, réglages, historique) persistent.

Droits sur les fichiers

Votre utilisateur est mappé sur l'utilisateur node du conteneur (--userns=keep-id). Les fichiers créés par Claude dans le dossier de travail vous appartiennent donc normalement sur l'hôte, sans chown à faire.

Mise à jour de Claude Code

La mise à jour automatique est désactivée dans le conteneur. Pour mettre à jour :

cloche --rebuild

just rebuild, depuis le dépôt, fait la même chose sans lancer Claude Code.

Limites

• cloche refuse de se lancer depuis $HOME ou /, pour ne pas exposer tout votre dossier personnel (sauf avec --build-only, qui ne monte rien).
• Deux projets dont les dossiers portent le même nom partagent le même chemin dans le conteneur, donc le même historique de sessions Claude.
• Un dossier inclus ne peut pas porter le même nom que le projet ou qu'un autre dossier inclus, puisqu'ils seraient montés au même endroit : cloche refuse alors de se lancer. Il ne peut pas non plus être $HOME ou /, ni avoir de : dans son chemin.
• Un proxy qui déchiffre le TLS avec sa propre autorité de certification n'est pas pris en charge : le certificat de cette autorité n'est pas installé dans l'image ni transmis au conteneur.
• L'image ne contient que Node.js, git, ripgrep, curl et jq. Pour d'autres outils (Python, compilateurs…), ajoutez-les au Containerfile puis lancez cloche --rebuild.