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.
  • Une connexion GitHub pour votre organisation, afin que les développeurs puissent sélectionner des référentiels 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.
  • 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. Le canal latest par défaut du programme d’installation natif porte chaque version dès sa publication ; le canal stable, le cask Homebrew claude-code, et les référentiels apt, dnf et apk stables traînent d’environ une semaine. 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 drapeaux 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 ; mettez à jour avec claude update ou réinstallez à partir du canal latest.

​
Configurer un environnement et un runner

Claude Code inclut une configuration guidée : une session Claude Code interactive qui vous guide à travers 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. Exécutez-le sur une machine où vous vous êtes connecté avec claude auth login en utilisant un compte qui détient un rôle Propriétaire ; il n’est pas disponible avec les clés API ou les fournisseurs de modèles tiers. Sur les hôtes où une session interactive n’est pas possible, utilisez plutôt les étapes manuelles ci-dessous. Confirmez d’abord que la vérification de version a réussi : sur les versions antérieures à 2.1.224, cette commande démarre une session Claude ordinaire avec les mots comme invite au lieu de la configuration guidée. Pour démarrer la configuration guidée, exécutez la sous-commande setup et suivez les invites :
Pour configurer manuellement à la place :
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 enregistrant 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 étape et la suivante nécessitent root pour le chemin /etc/claude ; n’importe quel chemin que le processus runner peut lire fonctionne, donc ajustez les deux commandes et la valeur --environment-secret-file ensemble si vous en utilisez un différent.
É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.Si le runner ne peut pas créer ou écrire dans le chemin, 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 s’enregistre auprès de votre environnement et commence à interroger le travail. Si le runner se termine, redémarrez-le manuellement. Les déploiements en production exécutent le runner sous un orchestrateur qui redémarre les runners terminés, normalement avec un système de fichiers frais par redémarrage ; Réutiliser un checkout pré-chauffé couvre la configuration de disque persistant prise en charge.
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.
4

Router une session vers l'environnement

Démarrez une session à 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. Le runner clone avec les identifiants git que l’hôte a déjà, donc choisissez un référentiel que cet hôte peut déjà cloner, ou un public ; les options d’identifiants pour les référentiels privés en production sont sur Configurer git. Le prochain runner disponible récupère la session en attente et enregistre Picked up session <session-id> ainsi que son nombre actif 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 fonctionner et lisez les réponses de Claude à claude.ai/code. Si la session reste en attente à la place, consultez Dépannage.
Le runner se termine par conception une fois que ses sessions actives se terminent ; consultez Cycle de vie du runner. Pour la production, déployez-le sous un orchestrateur qui le redémarre à la sortie. Consultez Déployer en production.

​
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, les exigences de compte et de politique, et la référence d’erreur 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