Déployer des environnements auto-hébergés en production

​

Sécurisez votre déploiement

• Conteneurs éphémères, par session : exécutez chaque processus runner dans un conteneur ou une VM fraîche qui est détruite lorsque le processus se termine, avec --capacity 1 et la valeur par défaut --drain-grace-sec 0 afin que chaque conteneur serve exactement une session. À une capacité plus élevée, ou avec une période de drainage positive, un conteneur sert plusieurs sessions du même propriétaire verrouillé ; voir Cycle de vie du runner. Ne réutilisez pas un système de fichiers entre les redémarrages du runner, sauf dans la configuration délibérée checkout pré-chauffé, et jamais entre les propriétaires.
• Pas de larges identifiants dans l’image : n’incluez pas de clés SSH de longue durée, d’identifiants de fournisseur cloud, ou de jetons d’accès personnel qui accordent plus que ce qu’une session a besoin. Générez les identifiants utilisés pendant une session, tels que les jetons push ou API, par session à partir de votre script wrapper. Pour le clone initial, qui se produit avant l’exécution du wrapper, utilisez un hook de cycle de vie checkout ou --use-anthropic-git-proxy ; voir Configurer git.
• Gardez le secret de l’environnement loin des hôtes exécutant les sessions : le secret de l’environnement peut enregistrer des runners et récupérer toute session mise en file d’attente sur l’environnement. Sur une flotte fixe, il réside sur chaque hôte runner, où le code de toute session peut lire le fichier secret. Préférez les runners à la demande, où le secret reste sur l’hôte orchestrateur, qui n’exécute jamais de code utilisateur, et chaque runner reçoit un bon de travail à usage unique qui enregistre exactement un runner. Sur une flotte fixe, traitez le fichier secret-environnement comme lisible par toute session et faites tourner le secret après tout compromis de session suspecté.
• Sortie réseau par défaut-refuser : limitez le trafic sortant du conteneur runner et session à votre propre limite réseau sur chaque environnement ; Sortie par défaut-refuser couvre ce qu’il faut autoriser et pourquoi.
• IAM hôte avec privilèges minimaux : l’identité de calcul attachée à l’hôte runner, telle qu’un profil d’instance ou un compte de service de nœud, ne devrait accorder que ce dont le runner lui-même a besoin. Les sessions devraient obtenir leurs propres identifiants via votre script wrapper plutôt que d’hériter de ceux de l’hôte.
• Bloquez le point de terminaison des métadonnées cloud des sessions : garder les sessions hors de l’identité hôte nécessite de bloquer leur accès au point de terminaison des métadonnées, et les politiques de sortie au niveau du sous-réseau n’interceptent pas le trafic de métadonnées link-local, donc bloquez-le dans le conteneur lui-même :
  • IMDSv2 avec une limite de saut d’un
  • GKE Workload Identity avec dissimulation des métadonnées
  • Un refus explicite pour 169.254.169.254 dans l’espace de noms réseau du conteneur de session
  Le bloc s’applique également à votre script wrapper et aux hooks de cycle de vie, puisqu’ils partagent le conteneur. Authentifiez tout échange de jeton avec le JWT de session contre votre propre service de jeton sur une sortie autorisée, ou utilisez une identité web basée sur fichier telle que les rôles IAM pour les comptes de service (IRSA) sur Amazon EKS.
• Isolation du système de fichiers par runner : chaque processus runner obtient son propre répertoire de travail qu’aucun autre processus sur l’hôte ne peut lire ou écrire. Rendez --hooks-dir, le script wrapper, et le ~/.claude/ de l’hôte en lecture seule pour la session, soit intégrés dans l’image, soit montés en lecture seule.
• Dispatch n’a pas de contrôle d’accès par environnement : tout membre de votre organisation Anthropic peut dispatcher une session vers n’importe lequel de ses environnements. Si un propriétaire route les canaux Claude Tag vers l’environnement, toute personne que le paramètre d’accès Claude Tag admet peut démarrer des sessions de canal qui s’y exécutent. Par défaut, il s’agit de toute personne dans l’espace de travail Slack connecté, avec ou sans compte Claude. Traitez chaque hôte runner comme accessible pour l’exécution de code par tous ceux qui peuvent dispatcher vers lui, et placez sur un hôte runner uniquement les données et identifiants que toutes ces personnes sont autorisées à lire. --lock-to-account limite les sessions de quel compte un hôte donné exécute, mais cela ne réduit pas qui peut dispatcher dans l’environnement. Pour faire des environnements auto-hébergés la seule option de sélection, un propriétaire peut masquer les environnements hébergés par Anthropic pour toute l’organisation à partir de la page Environnements cloud.
• Appliquez la garde des paramètres de dépôt : choisissez le mode de garde avec --confine-repo-settings. La valeur par défaut warn enregistre une violation et lance quand même la session, enforce refuse la session, et off désactive l’analyse. Le runner analyse les paramètres validés de chaque dépôt pour :
  • Une autorisation qui se résout en dehors de l’espace de travail propre de cette session : une entrée additionalDirectories, une règle Edit, Write, ou NotebookEdit dans permissions.allow, ou une entrée sandbox.filesystem.allowWrite ou allowRead
  • Un bloc env non vide
  • Un remplacement de posture d’opérateur tel que sandbox.enabled: false
  La garde s’exécute indépendamment de --trust-workspace, et ne couvre pas les hooks de dépôt, .mcp.json, ou les règles Bash ; voir Permissions et approbation des outils pour savoir où ces autorisations doivent se trouver.

​

Exigences réseau

​

Sortie par défaut-refuser

​

S’authentifier auprès d’un proxy de sortie

​

Choisir d’où provient la valeur Proxy-Authorization

• --proxy-authorization-command <command> : choisissez ceci pour un jeton que vous générez à la demande. Le runner exécute la commande shell et utilise sa stdout rognée comme valeur d’en-tête, par exemple Bearer <token>.
• --proxy-authorization-file <path> : choisissez ceci pour un jeton qu’un autre processus fait tourner en place. Le runner lit le fichier et utilise son contenu rogné comme valeur d’en-tête.

​

Configurations que le runner refuse de démarrer avec

• Les deux drapeaux définis : un drapeau plus la variable d’environnement de l’autre drapeau compte comme la définition des deux.
• Pas d’URL de proxy : ni HTTPS_PROXY ni HTTP_PROXY ne contient une URL http:// ou https://. Le runner lit les deux variables en majuscules ou minuscules, et ne consulte pas ALL_PROXY.
• L’un ou l’autre drapeau passé à la sous-commande orchestrateur : self-hosted-runner orchestrator n’accepte pas les drapeaux ou leurs variables d’environnement. Passez le drapeau à chaque runner que l’orchestrateur démarre à la place.

​

Ce que le runner change quand un drapeau d’autorisation de proxy est défini

• Écouteur : l’écouteur est un proxy avant sur 127.0.0.1. Le runner démarre l’écouteur avant de s’enregistrer auprès du plan de contrôle, et quitte au démarrage si l’écouteur ne peut pas démarrer.
• Variables de proxy : le runner réécrit lequel de HTTPS_PROXY et HTTP_PROXY vous avez défini pour qu’il pointe vers l’écouteur. Cette valeur réécrite atteint le runner lui-même, ses hooks de cycle de vie, et chaque session qu’il exécute.
• Rotation de jeton : un jeton pivoté prend effet sans redémarrage. Pour chaque connexion que l’écouteur ouvre vers votre proxy, le runner exécute votre commande ou relit votre fichier et ajoute le résultat comme en-tête.
• Environnement de session : une session atteint votre proxy uniquement via l’écouteur. Dans l’environnement de chaque session, le runner supprime ALL_PROXY, supprime toute orthographe de HTTPS_PROXY ou HTTP_PROXY que vous n’avez pas définie, et épingle NO_PROXY à la valeur du runner.
• Journaux : le runner ne journalise jamais la valeur de l’en-tête.

​

Configurer git

• Laisser le runner configurer git : démarrez le runner avec --configure-git pour qu’il écrive la même identité et configuration de signature de commit que les sessions hébergées par Anthropic utilisent
• Livrer la configuration git dans votre image : définissez l’identité et les identifiants push vous-même, par exemple pour committer sous votre propre identité de bot

​

Laisser le runner configurer git

• user.name = Claude et user.email = noreply@anthropic.com, correspondant aux sessions hébergées par Anthropic
• Signature de commit et de tag au format SSH, routée via un shim géré par le runner qui signe chaque commit via le service de signature d’Anthropic en utilisant les identifiants de la session. Les signatures sont vérifiables sur GitHub par rapport à la clé de signature SSH publiée d’Anthropic.

​

Livrer la configuration git dans votre image

RUN git config --system user.name "Claude" && \
    git config --system user.email "noreply@anthropic.com"

• Une clé de déploiement SSH limitée à un référentiel avec une réécriture url.<base>.insteadOf
• Un credential.helper qui retourne un jeton minimalement scoped
• GIT_SSH_COMMAND pointant vers une clé étroitement scoped

• Le runner définit GIT_TERMINAL_PROMPT=0, donc git ne demande pas de nom d’utilisateur ou de mot de passe.
• Le runner exécute SSH avec BatchMode=yes, ajouté à votre GIT_SSH_COMMAND si vous en définissez un, donc SSH ne demande pas de phrase de passe ou de confirmation d’hôte.
• Le runner définit GCM_INTERACTIVE=never, donc Git Credential Manager n’ouvre pas de dialogue de connexion.
• Le runner efface core.askPass, donc si vous utilisez un helper askpass, définissez-le via la variable d’environnement GIT_ASKPASS à la place.

RUN git config --system --add safe.directory '*'

​

Utiliser le proxy git Anthropic

​

Réécrire les URL git pour les réseaux privés

• --git-host-rewrite <from>=<to> : pour le DNS à horizon divisé, où Anthropic atteint votre hôte git via un nom d’hôte externe mais les runners doivent utiliser un interne
• --git-ssh-rewrite <host> : pour les hôtes git qui n’acceptent que SSH, réécrivant https://<host>/owner/repo en git@<host>:owner/repo

​

Construire l’image du runner

FROM debian:bookworm-slim
ARG CLAUDE_CODE_VERSION
RUN apt-get update && apt-get install -y --no-install-recommends git curl ca-certificates openssh-client \
 && rm -rf /var/lib/apt/lists/*
RUN curl -fsSL "https://downloads.claude.ai/claude-code-releases/${CLAUDE_CODE_VERSION:?set with --build-arg CLAUDE_CODE_VERSION}/linux-x64/claude" \
      -o /usr/local/bin/claude && chmod +x /usr/local/bin/claude
RUN git config --system user.name "Claude" \
 && git config --system user.email "noreply@anthropic.com" \
 && git config --system --add safe.directory '*'
ENTRYPOINT ["claude"]

docker build --build-arg CLAUDE_CODE_VERSION=2.1.224 -t <your-registry>/claude-runner:latest .

​

Dimensionner le CPU et la mémoire pour les sessions

• Mémoire : une demande et une limite de 4 Gio chacune, ce qui satisfait le minimum de 4 Go dans les exigences système de Claude Code. Gardez les deux égales afin que le planificateur tienne compte de la mémoire complète du conteneur. Lorsque le conteneur atteint sa limite de mémoire, le noyau tue les processus à l’intérieur, ce qui peut terminer une session en cours de tâche.
• CPU : une demande de 2 CPUs et une limite de 4 CPUs, afin qu’une session puisse dépasser la demande lors des builds. Le noyau limite un conteneur à sa limite de CPU plutôt que de tuer les processus à l’intérieur, donc les sessions à la limite s’exécutent plus lentement mais continuent de s’exécuter.

resources:
  requests:
    cpu: "2"
    memory: 4Gi
  limits:
    cpu: "4"
    memory: 4Gi

• Une session par runner : donnez à chaque conteneur les valeurs d’une session. Utilisez ce dimensionnement à --capacity 1, que la section de durcissement recommande, et pour les runners à la demande, où vous définissez les valeurs sur la charge de travail que votre hook spawn-runner soumet, comme un modèle de pod de Job Kubernetes.
• Plusieurs sessions par runner : à un --capacity supérieur à un, multipliez les valeurs d’une session par la capacité, car jusqu’à ce nombre de sessions peuvent s’exécuter dans le conteneur en même temps. Les recettes Kubernetes et Docker Compose exécutent --capacity 4 sans limites de CPU ou de mémoire, donc ajoutez des limites dimensionnées pour la capacité que vous exécutez.

​

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: claude-runner
  namespace: claude-runners
spec:
  replicas: 3
  selector:
    matchLabels:
      app: claude-runner
  template:
    metadata:
      labels:
        app: claude-runner
        app.kubernetes.io/part-of: claude-code-self-hosted-runner
    spec:
      terminationGracePeriodSeconds: 90
      containers:
        - name: runner
          image: <your-registry>/claude-runner:latest
          args:
            - self-hosted-runner
            - --environment-secret-file
            - /etc/claude/environment-secret
            - --capacity
            - "4"
          volumeMounts:
            - name: environment-secret
              mountPath: /etc/claude
              readOnly: true
          ports:
            - name: health
              containerPort: 8080
          readinessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10
          livenessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 30
            periodSeconds: 30
      volumes:
        - name: environment-secret
          secret:
            secretName: claude-runner-environment-secret

kubectl create namespace claude-runners

kubectl create secret generic claude-runner-environment-secret -n claude-runners --from-file=environment-secret=./environment-secret

​

Docker Compose

services:
  claude-runner:
    image: <your-registry>/claude-runner:latest
    command:
      - self-hosted-runner
      - --environment-secret-file
      - /run/secrets/environment-secret
      - --capacity
      - "4"
    secrets:
      - environment-secret
    restart: always
    stop_grace_period: 90s

secrets:
  environment-secret:
    file: ./environment-secret

​

Délai d’arrêt

• Avec une période de grâce SIGTERM : définissez terminationGracePeriodSeconds sur Kubernetes, stop_grace_period sur Docker Compose, ou l’équivalent de votre orchestrateur à au moins ce total. La valeur par défaut de Kubernetes de 30 secondes est plus courte que le chemin de drainage du runner, donc Kubernetes arrête le pod avant que le runner ne termine le drainage.
• Avec --retire-at : dimensionnez la marge entre l’heure de retraite et l’heure d’arrêt de l’hôte pour couvrir les tours typiques, plus la rétention des tâches de fond que Cycle de vie du runner décrit, plus ce même total. Calculez l’heure de retraite à chaque lancement, par exemple date +%s plus la durée de vie prévue du runner.
• Avec --defer-shutdown-max-min : ajoutez deux parties supplémentaires au total du chemin de drainage. La première est les minutes que vous configurez. La seconde est la grâce post-libération que Différer le drainage au-delà du premier signal décrit, 75 secondes par défaut. Avec le flag défini, le runner imprime également la figure combinée au démarrage, après le total du chemin de drainage.

​

Différer le drainage au-delà du premier signal

​

Ce qui arrive aux sessions que le runner détient après le premier signal

• Pendant les premiers n minutes : le runner sert ses sessions normalement et continue d’appliquer --startup-timeout-min et --kill-session-after-min. Si vous définissez également --release-idle-session-min, le runner libère toute session dont l’utilisateur a été inactif aussi longtemps ; sans cela, le runner ne libère aucune session tôt, à part un délai d’expiration au démarrage.
• Lorsque les n minutes s’écoulent : le runner libère chaque session qu’il détient toujours, inactive ou non. Le runner attend la fin du tour d’une session en cours de tour, et jusqu’à 60 secondes supplémentaires pour les tâches de fond d’un tour, avant de libérer cette session.
• Lorsque la grâce post-libération s’écoule : le runner draine les sessions qu’il détient toujours, et le plan de contrôle remet chaque session drainée en file d’attente vers un autre runner immédiatement. La grâce post-libération commence lorsque les n minutes s’écoulent et est de 75 secondes par défaut. Si vous définissez --drain-wait-sec au-dessus de 60 secondes, la grâce post-libération est --drain-wait-sec plus 15 secondes à la place.

​

Dimensionner le délai d’arrêt

​

Ce qui atteint un hook post-session en cours d’exécution

• Un SIGTERM tandis que le runner draine déjà : force la sortie du runner immédiatement, en sautant tout ce qui reste du chemin de drainage. Sans --defer-shutdown-max-min, c’est le deuxième SIGTERM que le runner reçoit. Rien ne signale un hook post-session en cours d’exécution, donc sur un hôte nu où un processus init adopte les orphelins, il se termine de lui-même, mais sans supervision : son budget de délai d’expiration ne s’applique plus, et une écriture au tuyau de journal fermé peut le tuer avec SIGPIPE, donc un hook qui doit survivre à une sortie forcée là devrait rediriger sa propre sortie vers un fichier. Dans les recettes de conteneur sur cette page, le runner est le PID 1 du conteneur et sa sortie termine le conteneur, et sous le KillMode=control-group par défaut de systemd, la suppression au niveau du cgroup atteint également le hook, comme l’entrée Suppressions au niveau du cgroup le décrit ; dans les deux cas, traitez une sortie forcée comme fatale au hook et fiez-vous à la période de grâce à la place.
• Signaux au niveau du groupe de processus, tels que kill -- -<pid> dans un script wrapper, le contrôle des tâches du shell, ou un watchdog au niveau du groupe : atteignent le runner et un sous-processus de hook checkout en cours, qui reste intentionnellement attaché au groupe, mais pas un hook post-session en cours d’exécution ou l’enfant de session.
• Suppressions au niveau du cgroup, telles que le KillMode=control-group par défaut de systemd ou le SIGKILL que Kubernetes livre à tout le conteneur lorsque terminationGracePeriodSeconds expire : atteignent tout, y compris le hook. L’isolation du groupe de processus ne protège pas contre celles-ci, c’est pourquoi la période de grâce doit couvrir le chemin de drainage complet.
• Le délai d’expiration du hook lui-même : lorsqu’un hook dépasse --post-session-hook-timeout-sec, le runner envoie SIGTERM à tout le groupe de processus du hook, puis SIGKILL deux secondes plus tard, donc un worker que le hook a forké, tel que tar, rsync, ou git, se termine avec le shell wrapper au lieu de survivre en tant qu’orphelin. La supervision du runner se termine une fois que le stdio du hook se ferme : un worker qui a redirigé sa propre sortie vers un fichier et survit à l’étape SIGTERM est au-delà de la portée du runner.

​

Garder le répertoire de base et la capacité identiques sur tous les runners

​

Réutiliser un checkout pré-chauffé

• Clone dans l’image : construisez le clone dans votre image runner à ce chemin. Chaque conteneur frais démarre alors avec le clone chaud sans réutiliser un disque.
• Clone sur un volume persistant : sur les runners que vous pré-verrouillez au compte d’un utilisateur avec --lock-to-account, pointez --base-dir vers un volume persistant, pour que le disque ne serve que ce compte. Un runner pré-verrouillé ne récupère jamais les sessions de canal Claude Tag, donc cette option ne s’applique pas aux runners qui les servent.

• N’importe quelle forme de clone fonctionne : un clone complet, peu profond, ou à branche unique au chemin est utilisé tel quel. Le runner ne passe jamais --depth lors de la récupération dans un clone existant, donc un pré-chauffage complet garde son historique complet et un peu profond reste peu profond. CLAUDE_RUNNER_FETCH_DEPTH (full, 0, ou un nombre ; par défaut 50) contrôle uniquement le clone froid que le runner fait quand aucun clone n’existe encore.
• Les changements suivis se réinitialisent, les fichiers non suivis persistent : chaque session commence à partir d’une réinitialisation dur qui efface les modifications suivies de la session précédente, mais le runner ne lance jamais git clean, donc les fichiers non suivis des sessions antérieures du propriétaire verrouillé restent dans l’arbre.
• Avec le proxy git, la réinitialisation devient un checkout : avec --use-anthropic-git-proxy, le runner assainit le .git/ du clone avant chaque session, gardant le magasin d’objets, les refs, et l’état peu profond mais supprimant l’index, donc chaque session paie un checkout complet de l’arbre de travail au lieu d’une réinitialisation quasi-instantanée ; il ne re-clone toujours pas. Les pré-chauffages de sous-module ne sont pas supportés sous le proxy.
• Les longs clones n’ont besoin d’aucune solution de contournement : le runner limite chaque opération git avec un watchdog sans progrès de 120 secondes et un plafond dur de 30 minutes, pas un délai d’expiration plat, donc un clone froid lent qui continue de signaler le progrès se termine.

​

Épingler la version

• Pour garder une flotte sur une version : construisez l’image avec une version épinglée, ou sur un hôte nu installez une version spécifique et désactivez les mises à jour automatiques
• Pour mettre à niveau : installez la version plus récente ou reconstruisez l’image, puis redémarrez les runners
• Plugins : les places de marché de plugins ne se mettent pas à jour automatiquement non plus ; définissez FORCE_AUTOUPDATE_PLUGINS=1 dans l’environnement du runner pour laisser les plugins se mettre à jour automatiquement pendant que le binaire reste épinglé

​

Mettre à l’échelle la flotte

• Flotte fixe : exécutez un ensemble statique de répliques runner et mettez à l’échelle sur les métriques Prometheus que chaque runner sert
• Runners à la demande : exécutez la sous-commande claude self-hosted-runner orchestrator, qui interroge Anthropic pour les sessions en attente sans runner disponible et invoque votre hook spawn-runner pour en démarrer un par session. Consultez Runners à la demande.

​

Problèmes connus et limitations

​

Le trafic du connecteur quitte votre réseau

• https://api.anthropic.com/v2/ccr-sessions/*
• https://api.anthropic.com/v1/code/sessions/*
• https://api.anthropic.com/v1/code/mcp/*

​

Certaines sessions ne comptent pas comme inactives

​

Limitations supplémentaires

• Les sessions reprises perdent le travail non poussé : quand une session est libérée, sur un délai d’expiration d’inactivité ou sur un redémarrage du runner, et que l’utilisateur envoie un autre message, la session reprend sur un runner frais qui clone le référentiel à nouveau à partir de sa branche de démarrage, donc le travail que la session n’avait pas poussé est parti. Définissez --push-outcome-on-release pour que le runner fasse un meilleur effort de push des branches de résultat de la session avant de la libérer, pour que la session reprise commence à partir de ces commits à la place ; cela préserve le travail engagé, pas un arbre de travail sale. Avant de l’activer, limitez qui peut pousser vers les refs claude/* sur la télécommande source, par exemple avec une règle de branche : à la reprise, le runner récupère la branche précédemment poussée sans vérifier qui l’a poussée, donc n’importe qui avec accès push à ces refs peut placer du contenu dans l’espace de travail repris. Le runner rejette également la configuration par session à la reprise, ce qui signifie le répertoire de configuration Claude de la session et tout état de shell que la session a écrit ; --push-outcome-on-release ne couvre pas ceux-ci.
• Les référentiels privés ne peuvent pas être ajoutés en milieu de session : un référentiel ajouté à une session après son démarrage n’est pas cloné avec des identifiants sur un runner auto-hébergé, donc l’ajout échoue. Sélectionnez chaque référentiel dont la session a besoin quand vous la créez.
• Certains connecteurs n’apparaissent pas dans les sessions auto-hébergées : un connecteur que vous n’avez pas encore connecté dans les paramètres claude.ai n’est pas listé dans une session auto-hébergée, et la session ne vous invitera pas à le connecter. Connectez-le d’abord dans les paramètres, puis démarrez une session fraîche. Ajouter un connecteur à une session déjà en cours d’exécution ne rend pas non plus ses outils disponibles à Claude ; démarrez une session fraîche pour récupérer un connecteur nouvellement ajouté.

​

Signaler un problème

​

Dépannage

claude self-hosted-runner doctor

• Le runner n’apparaît pas dans l’environnement : confirmez que l’hôte peut atteindre api.anthropic.com sur HTTPS, que le secret de l’environnement est actuel, et que l’horloge de l’hôte est à moins de cinq minutes de l’heure réelle ; un décalage plus grand cause l’échec de l’authentification. Le runner enregistre [runner:fatal] avec la raison du rejet en cas d’échec d’authentification.
• Le runner quitte au démarrage avec cannot create or write to base directory : le runner ne peut pas créer ou écrire à --base-dir, qui par défaut est /workspace. Corrigez la propriété du répertoire ou pointez --base-dir vers un chemin inscriptible, comme décrit dans Garder le répertoire de base et la capacité identiques sur tous les runners. Si le runner enregistre à la place [runner:fatal] disant que la vérification du répertoire de base a expiré, le répertoire est sur un montage NFS ou CSI suspendu. Vérifiez la santé du montage plutôt que les permissions. Le runner imprime ces deux échecs de démarrage à stderr avant d’ouvrir --log-file, donc cherchez-les dans le terminal ou les journaux de conteneur de votre plateforme plutôt que dans le fichier journal. Avant v2.1.225, le runner ne vérifiait pas le répertoire de base au démarrage, et cette mauvaise configuration échouait les sessions après la récupération à la place.
• Les sessions restent en attente : chaque runner en ligne peut être verrouillé à un propriétaire différent. Vérifiez la métrique claude_code_self_hosted_runner_locked_account de chaque runner métrique ou le champ locked_account de sa ligne de journal [runner:health] pour voir qui la détient. Les deux affichent l’email du propriétaire uniquement après que le runner ait reçu un jeton de session portant une réclamation act.email, ce qu’une session d’agent Claude Tag ne fait jamais. Sans la réclamation, le runner n’émet aucune série locked_account et enregistre locked_account=yes, ce qui vous dit que le runner est verrouillé mais pas à quel propriétaire. Ajoutez des répliques, ou attendez qu’un runner existant se draine et redémarre. Si l’environnement utilise des runners à la demande, vérifiez l’orchestrateur à la place ; consultez Runners à la demande.
• Les sessions échouent immédiatement après la récupération : ouvrez la session dans claude.ai/code pour voir l’erreur. Les causes les plus courantes sont les identifiants git manquants identifiants git dans l’image runner et les outils de build qui ne sont pas installés. Un répertoire de base non inscriptible arrête le runner au démarrage au lieu d’échouer les sessions. Consultez l’entrée Le runner quitte au démarrage avec cannot create or write to base directory dans cette liste.
• Les sessions ne peuvent pas atteindre le réseau via un proxy de sortie authentifiant : quand la source que vous avez définie avec --proxy-authorization-command ou --proxy-authorization-file échoue, expire après 30 secondes, ou produit une valeur vide, le runner répond à cette connexion 502 Bad Gateway et enregistre pourquoi. Le runner rédige la stderr de la commande dans ce journal et ne journalise jamais la valeur de l’en-tête. Avec --proxy-authorization-command, exécutez la commande vous-même sur l’hôte pour confirmer qu’elle imprime la valeur d’en-tête entière sur stdout. Si le runner quitte à la place au démarrage avec could not start the proxy-authorization listener, il ne pouvait pas ouvrir son écouteur de boucle locale.
• Le runner enregistre des lignes Poll failed contenant rejecting the malformed poll response : le runner a reçu une réponse de sondage dont le corps n’est pas le JSON attendu de la file d’attente, le plus souvent parce que quelque chose entre le runner et api.anthropic.com, comme un proxy d’interception ou un portail captif, a répondu avec sa propre page. Le runner rejette la réponse, la compte sous le type transport de la métrique claude_code_self_hosted_runner_poll_errors_total, et réessaie selon le calendrier de sondage échoué décrit dans Cycle de vie de la session. Le runner continue de servir ses sessions en direct. Configurez le proxy pour passer les réponses de api.anthropic.com inchangées. Avant v2.1.246, le runner lisait une telle réponse comme une file d’attente de travail vide, ce qui pouvait terminer ses sessions en direct ou le faire quitter.
• La branche d’une session n’existe plus sur la télécommande : pour une source git que la session ne lit que, le runner saute cette source et continue sur les autres. Pour la source vers laquelle la session pousse les résultats, une branche supprimée, généralement parce qu’elle a été fusionnée et supprimée automatiquement, échoue la session avec une erreur nommant le référentiel et la branche et vous demandant de restaurer la branche et de réessayer. Le runner échoue la session avec la même erreur quand sauter laisserait sans référentiel du tout. Avant v2.1.228, une telle session démarrait dans un répertoire vide.
• Les sessions prennent des minutes pour démarrer : le clone initial domine généralement. Regardez la métrique claude_code_self_hosted_runner_session_init_duration_seconds pour confirmer, et coupez le clone avec un checkout pré-chauffé ou un CLAUDE_RUNNER_FETCH_DEPTH plus petit.
• Le pod est tué en milieu de drainage : augmentez terminationGracePeriodSeconds à au moins la valeur que le runner enregistre au démarrage. Consultez Timing d’arrêt.

​

Prochaines étapes

• Personnaliser les sessions : scripts wrapper, hooks de cycle de vie, runners à la demande, serveurs MCP, et permissions
• Tester de bout en bout : vérifier une nouvelle image runner à partir de CI avant de la promouvoir
• Référence : chaque drapeau CLI, variable d’environnement, et métrique