Claude Code self-hosted runner : le guide pratique

Le self-hosted runner de Claude Code transforme une machine ou un conteneur que ton entreprise contrôle en environnement d'exécution pour des sessions lancées depuis Claude Code sur le web, mobile ou desktop. L'agent reste orchestré par Claude, mais les commandes, fichiers et accès réseau s'exécutent sur ton infrastructure. La fonction est annoncée pour les offres Team et Enterprise.

Cette nuance change tout. "Self-hosted" ne signifie pas que le modèle Claude tourne dans ta salle serveur. Cela signifie que l'environnement qui lit les fichiers, lance les processus et contacte les services internes reste chez toi.

Anthropic a ajouté la commande claude self-hosted-runner dans Claude Code 2.1.224. La note de version officielle présente cette fonction comme un moyen de faire tourner les sessions Claude Code web, mobile et desktop sur tes propres machines ou conteneurs. Ce guide explique ce que tu gagnes, ce qui continue de sortir de ton réseau et comment préparer un déploiement propre.

Ce que fait vraiment le self-hosted runner

Une session Claude Code a besoin de deux couches.

La première est la couche de raisonnement. Le modèle reçoit le contexte utile, choisit une action, interprète le résultat et décide de la suite.

La seconde est la couche d'exécution. Elle ouvre le dépôt, lit un fichier, lance un test, crée un processus, appelle un outil ou contacte un service.

Le self-hosted runner déplace cette seconde couche vers ton infrastructure. Ta machine devient le lieu où le travail technique est exécuté. Elle peut être un serveur interne, une VM, un conteneur isolé ou un worker éphémère créé pour une session.

Le changelog officiel de Claude Code confirme trois points : la commande est claude self-hosted-runner, elle accepte des machines ou conteneurs, et elle sert les sessions lancées depuis plusieurs interfaces Claude Code.

Le résultat est plus proche d'un worker privé que d'une installation locale complète de Claude.

Ce qui reste chez toi et ce qui ne reste pas chez toi

Le mot self-hosted crée facilement une fausse impression de confidentialité totale. Il faut séparer les flux.

Dans un environnement auto-hébergé, tu contrôles normalement :

• le système de fichiers lu et modifié

• les commandes et processus lancés

• les outils installés

• les variables d'environnement exposées au worker

• les dépôts et répertoires montés

• les règles de sortie réseau

• les journaux d'exécution locaux

• le cycle de vie du conteneur ou de la VM

Le modèle a quand même besoin de voir certaines informations pour décider. Les demandes d'outils et leurs résultats transitent donc par la couche d'orchestration. La documentation Anthropic sur les self-hosted sandboxes explique cette frontière clairement : les outils tournent sur ton hôte, tandis que les entrées et sorties nécessaires au modèle remontent vers le plan de contrôle.

Ne promets donc jamais "aucune donnée ne sort" sans avoir audité les messages, extraits de fichiers, logs et résultats réellement envoyés au modèle.

Self-hosted runner, sandbox et modèle local : trois choses différentes

Ces termes sont souvent mélangés.

Self-hosted runner

Claude Code lance le travail sur une machine que tu contrôles. Le modèle Claude reste fourni par Anthropic. C'est le sujet de cet article.

Sandbox

Une sandbox limite ce que le processus peut lire, écrire et contacter. Elle peut être gérée par Anthropic ou par ton entreprise. Un runner auto-hébergé sans isolation forte n'est pas automatiquement sûr.

Anthropic décrit deux frontières utiles pour Claude Code : l'isolation du système de fichiers et l'isolation réseau. Son article sur le sandboxing de Claude Code explique aussi pourquoi des identifiants Git ou des clés de signature ne devraient pas vivre directement dans l'environnement de travail.

Modèle local

Faire tourner un modèle local signifie exécuter les poids du modèle sur ton matériel. Le self-hosted runner ne fait pas cela. Si ton besoin porte sur l'inférence locale, lis plutôt le guide faire tourner une IA en local.

Dans quels cas le runner devient utile

Accéder à des services internes

Un agent dans un cloud public ne voit pas forcément ton registre de paquets, ton environnement de test privé, ta base de staging ou un service accessible uniquement par VPN. Un worker interne peut utiliser les routes réseau déjà autorisées.

Il ne faut pas lui ouvrir tout le réseau. Crée une zone dédiée avec une liste de destinations précises.

Garder le dépôt et les artefacts dans ton périmètre

Le runner peut cloner un dépôt depuis ton infrastructure, lancer les tests et produire des artefacts sans monter le dépôt complet dans une machine externe. Les fragments nécessaires au raisonnement peuvent encore être transmis au modèle, mais le stockage et l'exécution restent maîtrisés.

Utiliser une configuration d'entreprise

Les équipes ont souvent leurs propres certificats, proxys, scanners, caches de dépendances et lanceurs de processus. Claude Code a aussi ajouté CLAUDE_CODE_PROCESS_WRAPPER, qui permet à une organisation d'imposer un exécutable intermédiaire à chaque processus créé par Claude Code.

Déclencher du travail à distance

La valeur produit est simple : tu peux lancer une session depuis le web ou le mobile et faire exécuter le travail sur une machine déjà reliée au bon environnement. Tu n'as pas besoin de laisser ton ordinateur personnel ouvert avec tous tes accès.

Pour une entreprise, ce fonctionnement rapproche Claude Code d'une file de jobs agentiques. Il complète les principes du guide déployer un agent IA en entreprise sans les remplacer.

L'architecture minimale à viser

Une architecture raisonnable comporte cinq blocs.

1. Une file de travail contrôlée

Le runner récupère une mission attribuée à son environnement. Il ne devrait pas accepter des instructions anonymes ou non rattachées à une organisation.

2. Un contexte d'exécution éphémère

Chaque session démarre dans un conteneur ou une VM propre. À la fin, l'environnement est détruit ou remis à zéro. Réutiliser un même dossier entre plusieurs missions augmente le risque de fuite de fichiers et de dépendances.

3. Des identifiants temporaires

Évite les clés permanentes dans les variables globales du serveur. Utilise des jetons courts, limités au dépôt, à la branche et aux services nécessaires.

4. Une politique réseau explicite

Le runner devrait pouvoir joindre uniquement les domaines utiles. Un accès Internet total rend une injection de prompt beaucoup plus dangereuse.

5. Une piste d'audit

Journalise la mission, le demandeur, l'environnement, les outils appelés, les décisions sensibles, les fichiers modifiés et le statut final. Le journal ne doit pas capturer les secrets.

Cette structure ressemble à celle d'un système CI. La différence est que l'agent choisit dynamiquement une partie des commandes. La politique de sécurité doit donc être plus forte, pas plus faible.

La méthode de déploiement en sept étapes

Étape 1 : choisir un seul cas d'usage

Commence par une tâche réversible : lancer une suite de tests, reproduire un bug ou préparer un patch sur une branche isolée. Ne commence pas par un déploiement en production.

Étape 2 : créer un worker dédié

N'installe pas le runner sur un serveur qui contient déjà des secrets critiques. Utilise une VM ou un conteneur avec un compte système séparé, peu de droits et aucun accès interactif inutile.

Étape 3 : borner le dépôt

Autorise un dépôt de test et une branche dédiée. Le runner ne doit pas pouvoir pousser sur la branche principale au premier essai.

Étape 4 : installer les dépendances minimales

Ajoute Claude Code, Git, le runtime de ton projet et les outils de test. Chaque outil supplémentaire agrandit la surface d'attaque.

Étape 5 : configurer le runner

Mets Claude Code à jour vers une version qui expose claude self-hosted-runner. Vérifie l'aide locale de la commande avant de recopier un paramètre trouvé dans un post. La fonction vient d'arriver et les options peuvent évoluer.

Étape 6 : exécuter trois scénarios

Teste une mission normale, une mission qui demande un accès interdit et une mission contenant une instruction malveillante dans un fichier du dépôt. Le runner doit réussir la première, bloquer la deuxième et signaler la troisième.

Étape 7 : ajouter les validations humaines

Garde une approbation avant tout push, changement d'infrastructure, accès à une donnée sensible ou action externe. Le human-in-the-loop pour agent IA fournit le modèle de contrôle détaillé.

Les risques à ne pas sous-estimer

L'injection de prompt dans le dépôt

Un README, un ticket ou une dépendance peut contenir une instruction qui tente de détourner l'agent. Le fait que le runner soit chez toi ne neutralise pas l'attaque. Il lui donne parfois un accès plus proche de tes systèmes internes.

Les secrets lisibles par le processus

Si un secret est présent dans l'environnement, considère que l'agent ou un code qu'il exécute peut tenter de le lire. Préfère un proxy qui attache des identifiants limites au moment de la requête.

Le réseau interne trop large

Un worker place dans le mauvais sous-réseau peut découvrir plus de services que prévu. Applique une politique de refus par défaut.

Les environnements persistants

Un fichier créé pendant une session peut influencer la suivante. Détruis l'environnement après usage ou prouve son nettoyage.

La confusion entre contrôle et confidentialité totale

Tu contrôles le lieu d'exécution. Tu ne rends pas automatiquement la totalité du flux invisible au fournisseur du modèle. Cartographie les données qui transitent réellement.

Comment décider si tu en as besoin

Le self-hosted runner est pertinent si au moins une contrainte est vraie :

• l'agent doit atteindre un service interne non public

• les commandes doivent tourner sous tes contrôles de conformité

• tu veux créer et détruire toi-même les environnements

• les artefacts doivent rester dans ton stockage

• tu as une équipe capable d'exploiter et surveiller le worker

Il est probablement inutile si tu travailles seul sur un dépôt public, sans service interne et sans exigence de conformité. Dans ce cas, la version cloud ou locale standard sera plus simple.

N'ajoute pas de l'infrastructure pour avoir l'impression d'être plus avance. Ajoute-la quand elle ferme une contrainte réelle.

Checklist avant ouverture à une équipe

• offre Team ou Enterprise et disponibilité de la fonction vérifiées

• version Claude Code et commande locale vérifiées

• worker séparé des serveurs critiques

• environnement par session

• secrets temporaires et scopes minimaux

• sortie réseau en refus par défaut

• aucune écriture directe sur la branche principale

• approbation avant action irreversible

• journaux sans secrets

• procédure d'arrêt et de rotation des identifiants testée

FAQ

Le modèle Claude tourne-t-il sur mon serveur ?

Non. Le runner déplace l'exécution des outils vers ta machine. Il ne transforme pas Claude en modèle local.

Est-ce disponible sur Claude Pro ou Max ?

La note de version 2.1.224 annonce les environnements auto-hébergés pour les offres Team et Enterprise. Vérifie l'interface et la documentation de ton organisation avant de planifier un déploiement.

Puis-je utiliser un Mac mini comme runner ?

La note de version parle de machines ou conteneurs. Un Mac mini peut donc être un candidat technique si la commande le supporte dans ton environnement. Pour une équipe, une VM ou un worker éphémère sera souvent plus simple à isoler et auditer.

Le runner protège-t-il contre les injections de prompt ?

Non. L'isolation, les permissions, la politique réseau et les validations humaines restent nécessaires.

Quelle est la différence avec GitHub Actions ?

GitHub Actions exécute un workflow défini à l'avance. Claude Code choisit dynamiquement des actions selon la mission et les observations. Tu peux réutiliser des principes de runner CI, mais tu dois contrôler une surface plus variable.

Faut-il l'utiliser pour la production ?

Pas au premier déploiement. Commence par les tests, la reproduction de bugs et les branches isolées. Ouvre ensuite les actions sensibles une par une, avec preuve et retour arrière.

Avant de partir

Si cet article t'a donné envie de construire au lieu de juste lire : j'ai condensé le démarrage en un guide d'une soirée. Ton premier agent qui produit du travail réel, étape par étape, sans code. Gratuit, contre ton email. Tu recevras aussi Kryve Weekly quand elle sortira : le condensé hebdo de ce qui compte en IA, sans le bruit.

Recevoir le guide

Un email pour te l'envoyer. Pas de spam, désinscription en un clic.