Claude Code sur votre serveur : le tuto self-hosted et son piège

Depuis le 7 août, je fais tourner Claude Code sur une de mes machines, pas sur les serveurs d'Anthropic. Le checkout du dépôt, les artefacts de build, tout ce que la session écrit sur disque : ça reste chez moi. Anthropic a ouvert la chose en beta publique sous le nom de self-hosted environments, réservée aux plans Team et Enterprise. J'ai monté mon premier runner en une vingtaine de minutes. Voici le tuto complet — et le détail qui change tout, celui qu'on lit rarement dans les threads enthousiastes.

Ce qu'Anthropic a ouvert le 7 août (et ce qui part encore chez eux)

Jusqu'ici, quand vous lanciez une session Claude Code depuis le web, tout s'exécutait sur le compute d'Anthropic : le clone du repo, la compilation, les fichiers modifiés. Avec les self-hosted environments, un processus runner que vous déployez sur votre hôte prend le relais. La session tourne comme un processus enfant du runner, sur votre réseau.

Ce qui reste chez vous, concrètement : le checkout du dépôt, les artefacts de build, les secrets montés pendant la session, et tout ce que Claude écrit sur disque. C'est une preuve de résidence au niveau réseau, plus seulement une clause contractuelle. Faire (la marketplace) le résume dans l'annonce officielle : intégrer Claude Code dans leurs workflows existants tout en gardant leurs contrôles de sécurité.

Voilà pour la façade. Maintenant le point que je veux que vous ayez en tête avant de dérouler le tuto.

C'est une nuance, pas un défaut. Pour beaucoup d'équipes ça suffit : le repo privé n'est jamais cloné hors du réseau, les internal APIs ne sont jamais exposées sur Internet. Mais si un juriste vous a vendu « le code ne sort plus », il se trompe. Sur la question plus large de ce qui traverse vraiment votre frontière réseau, croisez toujours avec votre politique de résidence — j'en parle dans notre guide sur où poser votre IA pour rester en règle face au Cloud Act.

Les prérequis avant de lancer le runner

Rien d'exotique, mais chaque case compte. Sur les trois heures que j'ai passées la première fois, deux ont été mangées par deux prérequis idiots. Le check-list honnête :

• Un hôte Linux ou macOS (ou un conteneur). Pas de runner sous Windows : vous le faites tourner dans un conteneur Linux.
• Claude Code v2.1.224 ou plus. Le runner fait partie du binaire claude standard ; les versions antérieures ne connaissent pas la sous-commande self-hosted-runner.
• Git 2.24 ou plus.
• HTTPS sortant vers api.anthropic.com, claude.ai et votre hôte git pour le clone.
• Une horloge à l'heure. Plus de 5 minutes de décalage et l'authentification plante. NTP obligatoire.
• Un plan Team ou Enterprise, avec l'option « Allow self-hosted environments » activée par un Owner/admin, plus une connexion GitHub pour que les devs puissent piocher les repos.

Deux exclusions à noter : la fonctionnalité est off par défaut, et elle n'est pas disponible pour les organisations en ZDR (Zero Data Residency). Si vous êtes en ZDR, la porte est fermée, point.

Le tuto pas à pas : premier runner en 20 minutes

Vérifier la version, puis lancer le setup guidé

D'abord, confirmez que l'hôte est prêt. Un hôte à jour imprime l'aide du runner avec des flags comme --environment-secret-file :

claude self-hosted-runner --help

Si vous voyez à la place l'aide générale de claude, vous êtes sur une vieille version : claude update ou réinstallez depuis le canal latest. Le canal stable, le cask Homebrew et les repos apt/dnf stables traînent d'environ une semaine.

Le plus simple ensuite, c'est le setup interactif. Il crée l'environnement dans l'admin, démarre un runner local avec le secret, confirme l'enregistrement et vous écrit un pense-bête dans ./runner-setup/CHEAT-SHEET.md :

claude self-hosted-runner setup

Ma première galère, la vraie : je l'ai lancée sur une machine encore en 2.1.219. Résultat, Claude s'est mis à me répondre comme si « setup » était un prompt de conversation. J'ai cru à un bug pendant deux minutes avant de réaliser que la sous-commande n'existait pas sur cette version. Contrôlez le --help avant, ça évite l'humiliation.

Router manuellement quand il n'y a pas de session interactive

Sur un serveur headless, pas de setup guidé. On fait à la main. Dans l'admin claude.ai, page Cloud environments > New, on nomme l'environnement, puis on copie la environment key. Attention : la clé n'est affichée qu'une fois, impossible de la récupérer ensuite, et elle expire 365 jours après création. Notez aussi l'ID ccpool_... de l'environnement, utile pour la vérification de token en CI.

Sur l'hôte, on écrit le secret dans un fichier sans le laisser traîner dans l'historique shell, on choisit un base-dir inscriptible, et on démarre :

mkdir -p /etc/claude
(umask 077 && cat > /etc/claude/environment-secret)
claude self-hosted-runner \
  --environment-secret-file '/etc/claude/environment-secret' \
  --base-dir '/srv/claude/work'

Le runner crée le répertoire, s'enregistre et se met à poller. Sans --base-dir, il vise /workspace, qui n'existe pas par défaut — deuxième source de plantage au démarrage. Retournez sur la page Cloud environments : le statut passe de « No runners deployed » à « Healthy » en quelques secondes.

Reste à router une session. Sur claude.ai/code, on démarre une session et on sélectionne son environnement dans le picker, à côté des environnements hébergés par Anthropic. Le runner clone avec les credentials git déjà présents sur l'hôte — donc un repo public ou un repo que la machine sait déjà cloner pour ce premier test. Dans les logs du runner, vous verrez Picked up session <session-id>. C'est gagné.

Envie de relancer un message dans la session depuis n'importe quelle machine où vous êtes loggé ? La forme queue-and-exit :

claude -p "relance les tests unitaires" --cloud <session-id>

Un envoi réussi imprime Sent to cloud session. avec l'ID et un lien. Rien de plus. Pour orchestrer plusieurs de ces sessions en parallèle sans vous perdre, notre tuto sur piloter plusieurs agents Claude Code depuis un terminal complète bien ce montage.

Combien coûte Claude Code self-hosted, vraiment

C'est là que le calcul se corse, et que le « self-hosted » n'est pas gratuit du tout. Vous ne payez plus à la session au tarif Anthropic — vous payez du compute provisionné, actif ou non.

Point de comparaison utile : en Managed Agents (infra Anthropic), le tarif beta tourne autour de 0,08 $/session-heure plus les tokens standard. J'avais détaillé ce modèle dans notre analyse d'Anthropic Managed Agents et son tarif à 0,08 $/heure. En self-hosted, une configuration documentée fait tourner un modèle de code 20B quantifié en 4-bit sur un GPU A4500 à 0,25 $/heure — mais ce prix court, que la sandbox travaille ou reste inactive entre deux sessions. C'est le idle burn qui tue la facture des équipes à usage sporadique.

La règle empirique que j'en retire : utilisation soutenue et prévisible, le self-hosted gagne ; usage en pics, le managed reste moins cher une fois qu'on compte l'inactif et l'ops. Le mode on-demand runner atténue le problème — un orchestrateur surveille la file, démarre un runner quand du travail arrive, l'arrête quand c'est fini — mais il ajoute sa propre complexité.

Passage en prod : ce qui casse

Le quickstart vous fait tourner une session sur un hôte. La prod, c'est un autre métier, et Anthropic ne s'en cache pas : aucun SLA ne couvre votre infra. Trois choses m'ont sauté au visage.

Le runner sort par design. Une fois ses sessions actives terminées, il s'arrête. En prod, vous le faites tourner sous un orchestrateur (Kubernetes, Compose) qui le relance, normalement avec un filesystem frais à chaque redémarrage. Si vous voulez réutiliser un checkout pré-chauffé, il y a une procédure disque persistant à suivre — pas de bricolage maison.

Les sessions qui pendouillent. Détection des hangs, nettoyage des processus emballés, observabilité : c'est votre boulot désormais. Là où le managed vous couvrait, vous construisez runbooks et smoke tests réseau avant d'élargir.

L'egress et les credentials git. Pour les repos privés en prod, on ne se repose plus sur les credentials de l'hôte : il faut configurer proprement. Et « rien ne sort du réseau » n'est vrai que si vos règles d'egress et vos montages de secrets sont bien réglés. Une règle mal fichue rouvre le trou que vous vouliez fermer. Sur cette discipline-là, notre checklist de sécurisation des agents IA est un bon garde-fou.

Pour qui c'est un bon calcul — et pour qui c'est non

Mon verdict après quelques jours. C'est fait pour vous si un auditeur vous réclame une résidence d'exécution prouvable au niveau réseau, ou si vos sessions sont longues, interactives et branchées sur des APIs internes non exposées. Vous avez une équipe plateforme, un usage soutenu, un vrai besoin de compliance sur l'exécution : foncez, le montage est propre et documenté.

C'est non si vous êtes une PME sans ops de production, si votre usage est en dents de scie, ou si votre compliance est déjà satisfaite par le managed. Dans ces cas, vous allez payer de l'inactif et hériter d'incidents que personne ne vous paie pour gérer. Et si votre exigence, c'est que le code source ne quitte jamais l'UE — pas seulement le disque de build — relisez le callout du haut : la conversation part toujours chez Anthropic. Le self-hosted déplace la frontière, il ne la ferme pas. À vous de savoir si c'est celle qui compte pour vous. Pour choisir votre agent CLI en amont, notre comparatif Claude Code contre Codex CLI pose les bases.