Skip to main content
Les environnements auto-hébergés sont en bêta publique sur les plans Team et Enterprise ; Disponibilité et limitations couvre le chemin d’activation. Cette page lance votre première session ; consultez Environnements auto-hébergés pour comprendre ce qu’ils sont et Déployer en production pour le durcissement et les recettes de flotte.
Un environnement auto-hébergé exécute les sessions cloud de Claude Code sur l’infrastructure que votre organisation exploite, exécutées par des processus runner que vous déployez. Ce démarrage rapide en configure votre premier, le plus petit qui fonctionne : un runner sur un seul hôte, exécutant une session de test. Il y a deux étapes : créer l’environnement, démarrer un runner et router une session vers celui-ci, puis envoyer un message à cette session depuis votre terminal. Vous vous déplacerez entre deux surfaces : claude.ai pour créer l’environnement, vérifier son statut et router une session, et un terminal sur l’hôte pour tout ce que le runner fait. À la fin, vous aurez un environnement sur la page d’administration Environnements cloud, un runner interrogeant le travail, et une session s’exécutant sur votre hôte. Avant de connecter des référentiels réels ou des systèmes internes, travaillez sur Déployer en production, qui couvre la posture de sécurité, le contrôle de sortie, les identifiants git et l’orchestration.

​
Prérequis

​
Organisation et rôles

Le côté claude.ai a besoin de :
  • Autoriser les environnements auto-hébergés activé par un Propriétaire sur la page d’administration Environnements cloud ; le bouton Nouveau n’apparaît pas tant qu’il ne l’est pas. Si vous ne tenez pas le rôle, quelqu’un qui le tient peut créer l’environnement et vous remettre son secret ; les étapes du runner et du terminal sur cette page ne nécessitent aucun rôle claude.ai, et où une étape vérifie le statut dans l’interface d’administration, les propres lignes de journal du runner vous donnent le même signal.
  • Le connecteur GitHub activé par un Propriétaire, et la propre connexion GitHub de chaque développeur, afin qu’ils puissent sélectionner des dépôts github.com lorsqu’ils démarrent des sessions.

​
Hôte et réseau

L’hôte du runner a besoin de :
  • Un hôte ou conteneur Linux ou macOS avec HTTPS sortant vers api.anthropic.com, vers claude.ai et les hôtes de téléchargement vers lesquels il redirige pour l’étape d’installation ci-dessous, et vers votre hôte git pour le clone ; le tableau des exigences réseau a la liste complète. Windows n’est pas pris en charge en tant qu’hôte runner ; exécutez le runner dans un conteneur Linux à la place. Les postes de travail des développeurs ne sont pas affectés, car les sessions démarrent à partir de claude.ai dans un navigateur.
  • Un dépôt pour la session de test : un dépôt public, ou un dépôt que cet hôte peut déjà cloner via son URL HTTPS sans que des identifiants lui soient demandés. Une clé SSH seule ne suffit pas, car le runner clone l’URL https:// du dépôt. Pour cloner via SSH à la place, consultez Réécrire les URL git pour les réseaux privés.
  • Une horloge synchronisée à l’heure réelle, par exemple avec NTP. L’authentification échoue lorsque l’horloge est décalée de plus de cinq minutes ; consultez Dépannage.

​
Logiciel sur l’hôte du runner

Installez sur l’hôte avant de commencer :
  • Claude Code v2.1.224 ou ultérieur, avec l’une des méthodes d’installation standard. Le runner fait partie du binaire claude standard, et les versions antérieures ne reconnaissent pas la sous-commande self-hosted-runner. Un runner qui sert des sessions Claude Tag nécessite la v2.1.229 ou ultérieure et python3 dans son PATH, car les hooks fournis par le plan de contrôle pour ces sessions exécutent python3. Pour épingler la version exacte que votre flotte exécute, consultez Installer une version spécifique. Pour les images de conteneur, consultez le Dockerfile dans Déployer en production.
  • Git 2.24 ou plus récent. Certaines options git sur la page de déploiement nécessitent des versions plus récentes ; Configurer git indique chaque plancher.
Confirmez que l’hôte est prêt :
Un hôte prêt imprime le texte d’utilisation du runner, listant les flags tels que --environment-secret-file. Sur les versions antérieures à 2.1.224, la commande imprime la sortie générale claude --help à la place. Si vous voyez cette sortie, mettez à jour Claude Code. Si vous exécutez claude à partir d’une image de conteneur, reconstruisez l’image avec la version 2.1.224 ou ultérieure.

​
Configurer un environnement et un runner

Utilisez soit la configuration guidée, soit les étapes manuelles. La configuration guidée est une commande unique qui démarre une session Claude Code interactive et vous guide à travers le reste. Utilisez plutôt les étapes manuelles sur un hôte où une session interactive n’est pas possible. Utilisez-les également lorsqu’une personne détenant le rôle Propriétaire a créé l’environnement et vous a remis son secret, car la configuration guidée nécessite une connexion Propriétaire.

​
Exécuter la configuration guidée

La configuration guidée vous accompagne dans la création de l’environnement dans l’interface d’administration, démarre un runner local avec le fichier secret que vous enregistrez, confirme que le runner s’enregistre, et écrit une feuille de triche dans ./runner-setup/CHEAT-SHEET.md. Avant de l’exécuter, vérifiez votre connexion et votre version :
  • Connexion : exécutez-la sur une machine où vous vous êtes connecté avec claude auth login en utilisant un compte qui détient un rôle Propriétaire. Avec seulement une clé API ou un fournisseur de modèles tiers, la session démarre mais ses vérifications d’organisation échouent.
  • Version : confirmez que la vérification de version a réussi. Sur les versions antérieures à 2.1.224, la commande setup démarre une session Claude avec les mots comme prompt au lieu de la configuration guidée.
Pour démarrer la configuration guidée, exécutez la sous-commande setup dans votre shell et suivez les instructions :
La configuration ne démarre pas elle-même de session de test : elle vous indique d’en démarrer une sur claude.ai/code. La dernière étape de la configuration arrête le runner qu’elle a démarré. Si vous quittez la configuration avant cette étape, le runner continue de s’exécuter. Pour continuer après la dernière étape, redémarrez le runner dans votre shell avec la commande figurant dans ./runner-setup/CHEAT-SHEET.md, puis routez une session vers l’environnement.

​
Configurer manuellement

Créez l’environnement sur claude.ai, démarrez le runner depuis un terminal sur l’hôte, puis revenez sur claude.ai pour confirmer que le runner apparaît et y router une session. Si une personne détenant le rôle Propriétaire a déjà créé l’environnement et vous a remis son secret, commencez à l’étape 2.
1

Créer un environnement

Allez à la page Environnements cloud dans les paramètres d’administration. Sous Environnements auto-hébergés, sélectionnez Nouveau, nommez l’environnement, et sélectionnez Créer. À la deuxième étape de l’assistant, sélectionnez Copier la clé d’environnement pour copier le secret d’environnement, que l’interface d’administration étiquette comme clé d’environnement. claude.ai affiche le secret une fois, et vous ne pouvez pas le récupérer plus tard ; il expire 365 jours après sa création. L’ID ccpool_... de l’environnement reste visible dans sa boîte de dialogue de détail ; vous en aurez besoin pour la vérification aud dans vérification de token et pour dispatcher les sessions de test à partir de CI.Si vous perdez le secret ou avez besoin de le faire tourner, créez un nouveau secret à partir de l’onglet Configuration de l’environnement, déployez le nouveau secret sur vos runners, puis révoquez l’ancien. Les runners détenant un secret révoqué échouent leur prochain sondage authentifié et se terminent, en consignant poll auth failed, et votre orchestrateur les redémarre avec le nouveau secret.
2

Démarrer un runner

Créez le répertoire secret. Cette commande et la suivante utilisent /etc/claude, qui nécessite root, et le fichier secret qu’elles créent n’est lisible que par l’utilisateur qui les exécute. Si le runner s’exécute sous un autre utilisateur, il se termine avec error: Failed to read environment secret file <path> (EACCES: permission denied, open '<path>'). Dans ce cas, exécutez les deux commandes en tant qu’utilisateur du runner avec un répertoire dans lequel cet utilisateur peut écrire à la place de /etc/claude, et passez le même chemin à --environment-secret-file. N’importe quel chemin que le processus runner peut lire fonctionne.
Écrivez le secret d’environnement dans un fichier. La commande ci-dessous lit depuis votre terminal afin que le secret reste hors de l’historique du shell : collez la valeur que vous avez copiée, appuyez sur Entrée, puis Ctrl-D, et le umask du sous-shell rend le fichier lisible uniquement par son propriétaire.
Choisissez un répertoire de base, en remplaçant <writable-dir> dans la commande du runner ci-dessous par un chemin absolu que le runner peut écrire ou créer. Le runner crée le répertoire au démarrage, puis extrait les référentiels et crée des répertoires par session sous celui-ci. Sans --base-dir, il utilise /workspace, qui ne fonctionne que si ce répertoire existe déjà et est accessible en écriture ou si vous démarrez le runner en tant que root.
Utilisez un répertoire dédié au runner, et non votre répertoire personnel ou un répertoire contenant vos propres clones. Le runner considère tout ce qu’il trouve dans <writable-dir>/<repo-owner>/<repo> comme son propre clone, et peut le réinitialiser ainsi qu’écraser ou supprimer des fichiers qu’il contient.
Si le runner ne peut pas créer ou écrire dans le répertoire de base, il se termine au démarrage avec une erreur nommant le répertoire au lieu de s’enregistrer. Consultez Dépannage.Ensuite, démarrez le runner avec --environment-secret-file et --base-dir :
Le runner consigne Registered: runner_id=<runner-id> une fois qu’il s’est enregistré auprès de votre environnement, puis commence à interroger pour obtenir du travail. Démarré avec cette commande, il se termine par conception après avoir servi une session, et non après chaque tour. Pour servir davantage de sessions, redémarrez le runner chaque fois qu’il se termine. Consultez Si le runner se termine pour savoir quand cela se produit et ce que le runner consigne.
3

Vérifier que le runner apparaît

Retournez à la page Environnements cloud. Le statut de votre environnement passe de Aucun runner déployé à Sain en quelques secondes après le démarrage du runner ; ouvrez l’environnement et sélectionnez Activité pour voir le runner lui-même. Si vous n’avez pas accès à la page d’administration, la ligne Registered: runner_id=<runner-id> dans le log du runner de l’étape précédente vous donne le même signal.
4

Router une session vers l'environnement

Démarrez une session sur claude.ai/code et sélectionnez votre environnement dans le sélecteur d’environnement, où les environnements auto-hébergés apparaissent aux côtés des environnements hébergés par Anthropic. Pour le dépôt, choisissez celui des prérequis : un dépôt public, ou un dépôt que cet hôte peut déjà cloner via son URL HTTPS sans qu’on lui demande d’identifiants.Le prochain runner disponible récupère la session en attente et consigne Picked up session <session-id> ainsi que son nombre de sessions actives et sa capacité, afin que vous puissiez confirmer à partir de la propre sortie du runner quel hôte a pris la session. Regardez la session travailler et lisez les réponses de Claude sur claude.ai/code.Si la session ne commence pas à travailler, identifiez ce que vous observez :
  • La session reste en attente : consultez Dépannage.
  • La session ne démarre pas en raison d’une erreur git : si l’erreur contient le message git could not read Username for suivi de l’URL de votre hôte git, le runner ne disposait d’aucun identifiant HTTPS pour cet hôte.
    • Fournir des identifiants HTTPS : consultez Configurer git
    • Cloner plutôt via SSH : si l’hôte du runner dispose déjà d’une clé SSH, consultez Réécrire les URL git pour les réseaux privés
    • Après l’un ou l’autre correctif : redémarrez le runner et surveillez la session en échec au lieu d’en démarrer une nouvelle. Si elle a échoué plusieurs fois, attendez plusieurs minutes que le runner consigne Picked up session.
    • Pour utiliser plutôt un autre dépôt : archivez ou supprimez la session en échec, puis redémarrez le runner et démarrez une nouvelle session. Sinon, le runner peut récupérer la session en échec au lieu de la nouvelle.

​
Si le runner se termine

Si le runner se termine pendant ce démarrage rapide, redémarrez-le. Le runner peut se terminer de lui-même :
  • Plus rien en cours d’exécution : le log affiche [runner:exit] account workload drained — exiting. Le runner se termine par conception dès qu’il n’exécute plus aucune session, par exemple :
    • Vous avez archivé ou supprimé la session : redémarrez le runner
    • La session n’a pas pu démarrer : corrigez la cause, puis redémarrez le runner
  • Contact perdu : le log affiche une ligne [runner:fatal] avec runner record gone server-side ou avec poll auth failed. Si le runner perd le contact avec Anthropic pendant un certain temps, par exemple parce que l’hôte se met en veille, il peut se terminer lorsqu’il joint à nouveau Anthropic.
Un tour terminé ne met pas fin à votre session de test. Après le premier tour, la session est toujours attachée et le runner est toujours actif, vous pouvez donc envoyer un message de suivi à la session sans redémarrer le runner au préalable. Pour la production, déployez le runner sous un orchestrateur qui le redémarre à la sortie et attend plus longtemps entre les redémarrages lorsque le runner continue à se terminer juste après son démarrage. Consultez Déployer en production et Quand le runner se termine.

​
Envoyer un message de suivi à une session en cours d’exécution

Une fois qu’une session s’exécute sur votre environnement, envoyez-lui un suivi à partir de la CLI claude sur n’importe quelle machine où vous êtes connecté avec claude auth login ; la commande n’a pas besoin de s’exécuter à partir de la machine qui a démarré la session. La commande publie un message :
Pour <session-id>, passez l’ID nu session_... ou cse_... ou l’URL claude.ai/code de la session. Un envoi réussi imprime Sent to cloud session. avec l’ID de session et un lien de visualisation. Les formes d’ID acceptées, la sortie JSON, ainsi que les exigences de compte et de politique sont sur Envoyer des suivis à partir de la CLI, car la commande fonctionne de la même manière contre les sessions hébergées par Anthropic.

​
Étapes suivantes

  • Déployer en production : durcir le déploiement, contrôler la sortie, configurer les identifiants git et exécuter la flotte sous Kubernetes ou Compose
  • Personnaliser les sessions : scripts wrapper, hooks de cycle de vie, runners à la demande, serveurs MCP et permissions
  • Tester de bout en bout : un test de fumée CI qui dispatche une session et lit les réponses de Claude