Les environnements auto-hébergés sont en bêta publique sur les plans Team et Enterprise ; un Propriétaire les active en activant Autoriser les environnements auto-hébergés sur la page d’administration Environnements cloud. Cette page est la référence des drapeaux et des métriques ; consultez le guide de démarrage rapide pour la configuration et Déployer en production pour les recettes de flotte.
/workspace et ~/.claude s’appliquent. Exécutez claude self-hosted-runner --help pour la liste faisant autorité sur votre version installée.
Les séries de métriques et quelques champs API utilisent toujours pool pour ce que ces pages appellent un environnement ; les deux termes désignent la même chose. L’ID d’environnement est le champ pool_id, avec la forme ccpool_... : partout où ces pages affichent un identifiant pool, il désigne l’environnement. Les drapeaux CLI et les variables d’environnement l’écrivent environment, comme --environment-secret-file ; les orthographes pool dépréciées fonctionnent toujours, comme la ligne --environment-secret-file le décrit.
Drapeaux CLI du runner
La plupart des drapeaux ont une variable d’environnement correspondante. Quand les deux sont définis, le drapeau a la priorité. Les drapeaux de durée prennent des minutes ou des secondes sur la CLI, mais la variable d’environnement appariée est toujours en millisecondes, indiquée par le suffixe_MS, et la colonne Par défaut affiche l’unité du drapeau : --exit-if-unused-min 10 équivaut à SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS=600000, et une valeur Helm comme SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS: "15" signifie 15 millisecondes, pas la valeur par défaut de 15 minutes.
La plupart des drapeaux de durée ont un maximum, choisi pour garder chaque délai d’attente en dessous du plafond de minuteur 32 bits du runtime d’environ 24,85 jours. Les drapeaux
--*-min sont plafonnés à 10080 minutes, 7 jours ; --drain-grace-sec à 604800 secondes, également 7 jours ; et --drain-wait-sec à 86400 secondes, 24 heures. --session-stop-grace-sec et --post-session-hook-timeout-sec ne sont pas plafonnés. Dépasser un plafond se comporte différemment par surface :
- Drapeau : le démarrage échoue avec une erreur.
- Variable d’environnement : le runner serre la valeur au plafond de minuteur plutôt que de la rejeter.
Drapeaux CLI de l’orchestrateur
La sous-commandeself-hosted-runner orchestrator, qui génère les runners à la demande, accepte --api-url, --environment-secret-file, --hooks-dir, --health-port et --log-level avec les mêmes valeurs par défaut que le runner et, où le drapeau du runner en a une, la même variable d’environnement, sauf que --hooks-dir est requis et doit contenir un hook spawn-runner. Il prend également ses propres drapeaux :
Drapeaux du connecteur SCM
L’orchestrateur peut maintenir une connexion WebSocket permanente au plan de contrôle d’Anthropic afin que les flux pré-session hébergés, comme le sélecteur de dépôt et le résolveur de branche ou de ref, puissent atteindre un hôte GitHub Enterprise Server qui n’est routable que de l’intérieur de votre réseau. Le connecteur reste désactivé sauf si vous définissez--scm-connector-host.
Le connecteur s’authentifie avec le secret d’environnement existant de l’orchestrateur et se reconnecte automatiquement : avec backoff exponentiel sur une connexion abandonnée, ou un délai fixe de 30 secondes quand le plan de contrôle ferme la connexion parce qu’un autre réplica d’orchestrateur la détient déjà.
Paramètres réservés aux variables d’environnement
Ces paramètres du runner sont lus uniquement à partir de l’environnement et couvrent le comportement que la plupart des déploiements laissent à la valeur par défaut :Télémétrie
Les enfants de session envoient la télémétrie opérationnelle à Anthropic sauf si vous la désactivez. Aucun code ou contenu de dépôt n’est envoyé. Définir les variables de télémétrie sur le processus du runner ; le runner les réaffirme après l’application des variables d’environnement fournies par le serveur, donc le paramètre de l’opérateur a toujours la priorité. Un contrôle est spécifique aux environnements auto-hébergés :CLAUDE_CODE_BYOC_ENABLE_DATADOG=1 opte pour les métriques opérationnelles Datadog, qui sont désactivées par défaut dans les environnements auto-hébergés. Les contrôles de télémétrie Claude Code généraux, DISABLE_TELEMETRY, DO_NOT_TRACK, DISABLE_ERROR_REPORTING et CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, s’appliquent aux enfants de session comme documenté dans la référence des variables d’environnement. DISABLE_GROWTHBOOK est connexe mais différent : définir DISABLE_GROWTHBOOK=1 désactive la récupération des drapeaux de fonctionnalité, et la télémétrie reste activée sauf si DISABLE_TELEMETRY est également défini.
CLAUDE_CODE_ENABLE_TELEMETRY n’est pas connexe : il active l’export OpenTelemetry vers votre propre collecteur, comme décrit dans Surveillance, et ne contrôle pas l’analytique d’Anthropic.
Point de terminaison de santé
Le runner sertGET /healthz sur le port de santé configuré. La réponse est 200 OK chaque fois que le processus est actif, quel que soit l’état de la boucle d’interrogation, donc une sonde HTTP sur ce point de terminaison détecte uniquement un processus mort. Le corps JSON décrit l’état actuel :
last_poll_age_ms comme signal de vivacité dans les sondes personnalisées ; une valeur qui croît sans limite indique que la boucle d’interrogation est bloquée. À la fois last_poll_at et last_poll_age_ms sont null jusqu’à la fin de la première interrogation.
L’orchestrateur sert son propre /healthz sur son port de santé. Son point de terminaison retourne toujours 200, et le corps porte un champ connected signalant si l’interrogation la plus récente a réussi, plus les comptes de file d’attente de génération par état dans queue_counts. Gater la disponibilité et les alertes sur connected plutôt que sur le code de statut.
Quand le connecteur SCM est configuré, le corps /healthz de l’orchestrateur porte également scm_connector_connected et un objet scm_connector avec connected, last_connected_at, last_error, reconnects et requests_forwarded. Les deux champs sont null quand --scm-connector-host n’est pas défini.
Métriques Prometheus
Chaque runner sert les métriques Prometheus àGET /metrics sur le même port que /healthz. Séries clés :
L’orchestrateur sert ses propres séries à
GET /metrics sur le même port que son /healthz :
Pour la mise à l’échelle automatique, choisissez la série qui correspond à votre style de mise à l’échelle et gâtez-la avant qu’elle n’alimente le scaler :
- Mise à l’échelle basée sur la profondeur de file d’attente : alimenter
claude_code_self_hosted_orchestrator_pool_pending_sessionsdans votre HPA ou scaler KEDA, pasqueue_pending_sessions. - Mise à l’échelle basée sur la capacité : mettre à l’échelle sur le ratio des
active_sessionsdu runner àcapacity. - Gâter sur
connected: filtrer la requête avecclaude_code_self_hosted_orchestrator_connected == 1par instance, afin que la valeur obsolète d’un réplica déconnecté n’alimente pas le scaler.
ignoreNullValues: "true" par défaut lit le résultat vide comme zéro et réduit ; définir ignoreNullValues: "false" sur le ScaledObject, éventuellement avec un plancher de réplicas fallback.
Le PodMonitor Prometheus Operator suivant couvre les deux processus. Il sélectionne les pods par l’étiquette app.kubernetes.io/part-of: claude-code-self-hosted-runner et le port nommé health que la recette Kubernetes définit ; ajustez les espaces de noms pour correspondre à votre déploiement :
Transmettre les métriques de l’enfant de session
Chaque session s’exécute dans son propre processus enfant avec ses propres métriques OpenTelemetry ; à--capacity au-dessus d’un, le runner réécrit comment ces métriques enfants sont exposées. Définir OTEL_METRICS_EXPORTER=prometheus sur l’hôte du runner et CLAUDE_CODE_ENABLE_TELEMETRY=1 dans l’environnement de la session, par exemple à partir de votre script wrapper ou de l’environnement propre du runner, que les sessions héritent, réexpose les instruments de compteur et de jauge de chaque enfant sur le point de terminaison /metrics propre du runner, aux côtés de la série du runner. Le runner réécrit l’exporteur de l’enfant pour pousser sur OTLP vers un récepteur loopback uniquement sur le port de santé, étiquette chaque série avec les étiquettes session_id et client_platform, et expulse la série d’une session quand cette session se termine. Les histogrammes ne passent pas, et une métrique enfant dont le nom entrerait en collision avec le préfixe propre du runner est supprimée.
À la --capacity 1 par défaut, la réécriture ne s’applique pas : l’enfant de la session lie son propre point de terminaison Prometheus sur le port 9464 comme d’habitude.
Sémantique du compteur de cycle de vie de session
Les compteurssessions_started_total, sessions_completed_total, sessions_failed_total et sessions_interrupted_total classent chaque session par la façon dont elle s’est terminée. Chaque enfant de session généré incrémente sessions_started_total au moment du lancement, et exactement l’un des trois autres incrémente à la sortie, donc sessions_started_total moins la somme des trois autres égale le nombre d’enfants de session actuellement en cours d’exécution.
completed: la session s’est terminée proprement. Cela couvre l’enfant se terminant de lui-même avec le code0, la session étant archivée ou supprimée tandis que l’enfant était toujours connecté, et le runner libérant le créneau comme une remise propre : une libération inactive, un délai d’attente de démarrage ou une désassignation côté serveur que la boucle d’interrogation a remarquée avant la sortie de l’enfant. Incrémentesessions_completed_total.failed: l’enfant s’est terminé de lui-même avec un code non-zéro, soit un crash soit une défaillance de configuration après le lancement. Incrémentesessions_failed_total.interrupted: le runner a terminé l’enfant pour une raison opérationnelle qui n’est ni un succès de session ni une faute du runner, comme un drainage ou le watchdog de durée de vie maximale--kill-session-after-min. Un redémarrage roulant Kubernetes envoyantSIGTERMest un exemple de drainage. Incrémentesessions_interrupted_total.
CLAUDE_RUNNER_EXIT_REASON du hook post-session n’utilise pas cette classification pour les remises propres. Le hook signale une libération inactive, un délai d’attente de démarrage et une désassignation serveur comme interrupted, puisque du point de vue du hook le runner a tué l’enfant, tandis que les compteurs ci-dessus enregistrent ces mêmes événements comme completed, puisque rien n’a mal tourné et le créneau a été remis proprement. Si vous réconciliez les reçus du hook directement contre sessions_completed_total, vous sous-comptez les complétions. Utilisez le hook pour les garanties par session et les compteurs pour les taux agrégés.
Sur un environnement unique, --capacity 1 avec le --drain-grace-sec 0 par défaut, chaque processus runner se termine peu de temps après la fin de sa session unique. sessions_completed_total, sessions_failed_total et sessions_interrupted_total n’incrémentent qu’à la fin de la session, juste avant cette sortie, donc une récupération Prometheus toutes les 15 à 60 secondes attrape rarement l’incrément avant que la série du runner ne disparaisse ; ces trois compteurs de fin de session sont les compteurs terminaux auxquels le reste de cette section se réfère. sessions_started_total incrémente au lancement et reste visible pendant la durée de vie de la session, donc il s’affiche de manière fiable, mais sur un environnement unique il se lit plus proche de « sessions actuellement en cours d’exécution » qu’un compte cumulatif.
Utilisez la série dans ce tableau pour l’objectif correspondant au lieu des compteurs terminaux :
Les lignes
orchestrator_* n’existent que sur les environnements exécutant l’orchestrateur à la demande. Sur une flotte fixe dont les runners survivent à leurs sessions, avec --drain-grace-sec au-dessus de 0, utilisez sum(rate(claude_code_self_hosted_runner_sessions_started_total[5m])) pour le débit ; sur une flotte unique cette série a le même problème de fenêtre de récupération que les compteurs terminaux, donc fiez-vous au compte de sessions en file d’attente à la place. Vérifiez l’arriéré sur l’onglet Activity de l’environnement, sur la page d’administration Cloud environments : les runners n’exportent pas une série de profondeur de file d’attente.
Pour le rapport de résultat par session, utilisez le hook post-session à la place : il se déclenche à chaque fin de session où un processus enfant a été généré, à part la terminaison abrupte du runner comme une préemption de VM, selon le contrat propre du hook.
Étapes suivantes
- Environnements auto-hébergés : le modèle d’environnement, de runner et de session ; le guide de démarrage rapide et Déployer en production contiennent la configuration et les opérations
- Personnaliser les sessions : scripts wrapper, hooks de cycle de vie et runners à la demande
- Vérifier l’identité de la session : le token de session, ses revendications et comment le vérifier