Démarrage rapide des environnements auto-hébergés

Configurez votre premier environnement auto-hébergé : installez Claude Code, créez l'environnement, démarrez un runner et routez une session vers celui-ci.

[!NOTE]

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.

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 :

claude self-hosted-runner --help

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 accompagne pour 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 disposant du rôle Owner a créé l'environnement et vous a transmis son secret, car la configuration guidée nécessite une connexion Owner.

Lancer 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 un aide-mémoire dans ./runner-setup/CHEAT-SHEET.md. Avant de la lancer, vérifiez votre connexion et votre version :

• Connexion : lancez-la sur une machine où vous vous êtes connecté avec claude auth login à l'aide d'un compte disposant d'un rôle Owner. Avec uniquement une clé API ou un fournisseur de modèles tiers, la session démarre mais ses vérifications d'organisation échouent.
• Version : vérifiez que la vérification de version a réussi. Sur les versions antérieures à 2.1.224, la commande de configuration démarre une session Claude avec ces 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 :

claude self-hosted-runner setup

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 acheminez 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 acheminer une session vers celui-ci. Si une personne disposant du rôle Owner a déjà créé l'environnement et vous a transmis son secret, commencez à l'étape 2.

1. Créer un environnement

Accédez à la page Cloud environments dans les paramètres d'administration. Sous Self-hosted environments, sélectionnez New, nommez l'environnement et sélectionnez Create. À la deuxième étape de l'assistant, sélectionnez Copy environment key pour copier le secret de l'environnement, que l'interface d'administration appelle une clé d'environnement. claude.ai n'affiche le secret qu'une seule fois et vous ne pourrez pas le récupérer plus tard ; il expire 365 jours après sa création. L'identifiant ccpool_... de l'environnement reste visible dans sa boîte de dialogue de détails ; vous en aurez besoin pour la vérification aud dans la vérification des jetons et pour lancer des sessions de test depuis la CI.

Si vous perdez le secret ou devez le renouveler, créez un nouveau secret depuis 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 lors de leur prochain polling authentifié et s'arrêtent en journalisant poll auth failed, et votre orchestrateur les redémarre avec le nouveau secret.

2. Démarrer un runner

Créez le répertoire du secret. Cette commande et la suivante utilisent /etc/claude, qui nécessite les droits 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 s'arrête 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 transmettez le même chemin à --environment-secret-file. Tout chemin lisible par le processus du runner convient.

mkdir -p /etc/claude

Écrivez le secret de l'environnement dans un fichier. La commande ci-dessous lit depuis votre terminal afin que le secret ne figure pas dans l'historique du shell : collez la valeur que vous avez copiée, appuyez sur Enter, puis sur Ctrl-D, et le umask du sous-shell rend le fichier lisible uniquement par son propriétaire.

(umask 077 && cat > /etc/claude/environment-secret)

Choisissez un répertoire de base, en remplaçant <writable-dir> dans la commande du runner ci-dessous par un chemin absolu dans lequel le runner peut écrire ou qu'il peut créer. Le runner crée le répertoire au démarrage, puis y extrait les dépôts et y crée des répertoires par session. Sans --base-dir, il utilise /workspace, ce 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.

[!WARNING]

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 et écraser ou supprimer des fichiers qu'il contient.

Si le runner ne peut pas créer le répertoire de base ou y écrire, il s'arrête au démarrage avec une erreur indiquant le répertoire au lieu de s'enregistrer. Consultez Dépannage.

Démarrez ensuite le runner avec --environment-secret-file et --base-dir :

claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>'

Le runner journalise Registered: runner_id=<runner-id> une fois enregistré auprès de votre environnement, puis commence à interroger les tâches à traiter. Démarré avec cette commande, il s'arrête 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 s'arrête. Consultez Si le runner s'arrête pour savoir quand cela se produit et ce que le runner journalise.

3. Vérifier que le runner apparaît

Revenez à la page Cloud environments. Le statut de votre environnement passe de No runners deployed à Healthy quelques secondes après le démarrage du runner ; ouvrez l'environnement et sélectionnez Activity 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 fournit le même signal.

4. Acheminer 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 de ceux 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 prend en charge la session en file d'attente et journalise Picked up session <session-id> avec son nombre de sessions actives et sa capacité, ce qui vous permet de confirmer à partir de la sortie du runner lui-même quel hôte a pris la session. Suivez le travail de la session et lisez les réponses de Claude sur claude.ai/code.

Si la session ne commence pas à travailler, identifiez votre situation :

• La session reste en file d'attente : consultez Dépannage.
• La session ne démarre pas en raison d'une erreur git : si l'erreur inclut 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'une ou l'autre de ces corrections : redémarrez le runner et suivez la session en échec au lieu d'en démarrer une nouvelle. Si elle a échoué plusieurs fois, attendez plusieurs minutes que le runner journalise Picked up session.
  • Pour utiliser un autre dépôt à la place : archivez ou supprimez la session en échec, puis redémarrez le runner et démarrez une nouvelle session. Sinon, le runner risque de prendre en charge la session en échec au lieu de la nouvelle.

Si le runner s'arrête

Si le runner s'arrête pendant ce démarrage rapide, redémarrez-le. Le runner peut s'arrêter de lui-même :

• Plus rien en cours d'exécution : le log affiche [runner:exit] account workload drained — exiting. Le runner s'arrête 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
• Perte de contact : 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 s'arrêter lorsqu'il rejoint à nouveau Anthropic.

Un tour terminé ne met pas fin à votre session de test. Après le premier tour, la session est toujours rattachée et le runner toujours actif, vous pouvez donc envoyer un message de suivi à la session sans redémarrer le runner au préalable.

En production, déployez le runner sous un orchestrateur qui le redémarre lorsqu'il s'arrête et qui espace davantage les redémarrages lorsque le runner continue de s'arrêter juste après son démarrage. Consultez Déployer en production et Lorsque le runner s'arrête.

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 :

claude -p "your message" --cloud <session-id>

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