Installer Claude Code sur une VM Alpine de développement

Pourquoi installer Claude Code dans la VM ?

Quand on veut déléguer une partie du développement d'un projet à Claude Code, l'installer directement sur la VM de test/dev offre plusieurs avantages : pas de synchronisation à gérer entre poste local et VM, accès natif à la toolchain du projet (Go, tests, packaging), et un workflow homogène entre la session SSH et l'agent.

Voici la procédure suivie sur le projet chronos-web (application web de pointage en Go, déployée sur Alpine Linux), avec les pièges rencontrés et la méthode d'authentification qui s'est révélée la plus fiable.

Pré-requis Alpine

Anthropic supporte officiellement Alpine depuis la version 3.19, mais la distribution musl impose deux dépendances que glibc rend transparentes :

• libgcc et libstdc++ : le binaire natif Claude Code en dépend en runtime.
• ripgrep système : le ripgrep embarqué dans Claude Code est compilé contre glibc et ne s'exécute pas sur musl. On installe celui d'Alpine et on désactive l'embarqué.
• curl, bash et git : l'installateur officiel est un script bash, et Claude Code utilise git pour le contexte projet.

Installation des paquets :

apk update
apk add curl bash libgcc libstdc++ git

Installation du binaire natif

Anthropic recommande l'installateur natif plutôt que le paquet npm — il est autonome, ne dépend pas de Node.js, et se met à jour tout seul en arrière-plan.

curl -fsSL https://claude.ai/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile

Le binaire s'installe dans ~/.local/bin/claude. Vérification du bon état de l'installation :

claude --version
claude doctor

La commande claude doctor est l'outil de diagnostic officiel : elle signale les dépendances manquantes, les soucis de PATH, et confirme que le ripgrep système est bien utilisé.

Authentification : méthode du token API

Pourquoi pas OAuth ?

L'authentification OAuth via abonnement Pro/Max ouvre un navigateur côté serveur — ce qui ne fonctionne pas sur une VM headless en SSH. Le flux dit « device code » existe en théorie, mais souffre actuellement d'un bug récurrent lorsque le compte possède à la fois un abonnement Pro/Max et une organisation Console : l'erreur « Redirect URI is not supported by client » empêche complètement de se connecter.

La méthode du token API

La voie la plus fiable sur une VM headless est de passer par une clé API générée sur la Console Anthropic :

• Se connecter à console.anthropic.com depuis son poste local.
• Aller dans Settings > API Keys et créer une clé dédiée à la VM (lui donner un nom explicite, par exemple chronos-web-dev-vm).
• Copier la clé immédiatement — elle ne sera plus affichée ensuite.
• L'exporter sur la VM et la rendre persistante :

export ANTHROPIC_API_KEY="sk-ant-..."
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.profile
claude

Conséquences à connaître

• L'usage est facturé en pay-as-you-go sur la Console, même si un abonnement Pro/Max est actif sur le même compte. La clé bypasse l'abonnement.
• La clé peut être révoquée à tout moment depuis la Console si elle fuite (commit accidentel, partage de VM, etc.).
• Sur une VM partagée, ne jamais mettre la clé dans .bashrc partagé ou dans un script commité.

Organisation des documents projet

Claude Code travaille bien mieux quand il a accès au contexte de planification du projet, pas seulement au code. La convention retenue : un sous-dossier docs/ à la racine du dépôt, qui n'est pas dans le packaging final mais qui est versionné.

• docs/cahier_des_charges.txt : spécification fonctionnelle normative du projet (la source de vérité quand le code et le plan divergent).
• docs/plan_developpement.txt : découpage en étapes avec critères d'entrée et de sortie pour chaque étape.
• docs/RESUME_NEXT.md : fichier court qui décrit l'état courant du chantier et la prochaine étape à attaquer. À mettre à jour à chaque fin de session.
• CLAUDE.md (à la racine) : généré par la commande /init dans Claude Code. Décrit la stack, les conventions, les commandes de build et de test. Lu automatiquement à chaque session.

Transfert des documents de planification depuis le poste local :

ssh root@<ip-vm> 'mkdir -p /root/chronos-web/docs'
scp docs/*.txt docs/*.md root@<ip-vm>:/root/chronos-web/docs/

Bonnes pratiques en session

Toujours lancer claude dans le dossier projet

Lancer claude depuis ~/chronos-web et pas depuis ~. Sinon Claude Code indexe le home en entier, ce qui pollue le contexte et coûte des tokens pour rien.

Choisir le bon modèle pour la tâche

En session, la commande /model permet de basculer entre les modèles disponibles. Le bandeau du haut indique celui actuellement actif.

• Sonnet pour le travail itératif quotidien : refactoring, écriture de tests, débogage, petites features. Largement suffisant et environ 5 fois moins cher qu'Opus.
• Opus pour les chantiers critiques : conception d'API, migrations de schéma SQL, refonte d'architecture. Sa profondeur de raisonnement se paie en tokens.
• /effort ajuste indépendamment l'intensité du raisonnement. medium ou high couvre la majorité des cas ; xhigh est rarement nécessaire et facture cher.

Planifier avant de coder

La règle qui économise le plus de tokens et de frustration : demander un plan d'action explicite avant toute écriture de code, et le valider fichier par fichier. Sans ça, Claude Code part vite, écrit beaucoup, et il faut tout repasser.

Formulation type pour un premier prompt sur un nouveau chantier :

Lis docs/RESUME_NEXT.md, docs/plan_developpement.txt
et les sections pertinentes du cahier.

Propose-moi un plan d'action concret pour l'étape N,
fichier par fichier, fonction par fonction.

N'écris aucun code à ce stade — on valide le plan
avant.

Surveiller la consommation

La commande /usage affiche la consommation de la session courante, ventilée par catégorie (skills, sous-agents, MCP, etc.). À regarder ponctuellement, surtout si on a opté pour Opus sur un long chantier.

Conclusion

L'installation de Claude Code sur une VM Alpine est rapide une fois les deux pièges contournés : les dépendances musl (libgcc, libstdc++, ripgrep système avec USE_BUILTIN_RIPGREP=0) et le bug OAuth sur les comptes mixtes (auquel on échappe en passant par une clé API Console dédiée).

L'investissement réel est dans la mise en place du contexte projet — dossier docs/ à jour, CLAUDE.md généré, RESUME_NEXT.md tenu à chaque fin de session. C'est ce qui transforme Claude Code d'un assistant générique en un développeur qui connaît vraiment le projet.