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.
  • Lorsque le runner arrête une session, il n’envoie aucun signal à un processus encore en cours d’exécution après la fin de sa commande shell, comme un service passé en mode daemon. La destruction du conteneur ou de la VM met fin à ce processus.
• 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. Le clone initial se produit avant l’exécution du wrapper ; gérez-le donc avec un hook de cycle de vie checkout, ou avec --use-anthropic-git-proxy lorsque tous les dépôts d’une session se trouvent sur github.com. Pour ces deux options, voir Configurer git.
• Tenez les identifiants GitHub de l’hôte à l’écart des sessions : Claude peut utiliser tout identifiant GitHub qu’une session peut lire, avec l’accès que cet identifiant accorde. Tenez les identifiants GitHub à portée étendue propres à l’hôte runner hors de tout ce qu’une session peut lire. Un tel identifiant peut être un jeton d’accès personnel, le jeton que gh auth login enregistre pour votre compte, ou un GH_TOKEN dans l’environnement du runner.
  • Avec git géré par Anthropic : avec un tel identifiant, Claude atteint GitHub directement au lieu de passer par git géré par Anthropic.
  • Sans git géré par Anthropic : un identifiant de clone peut rester dans l’image si vous limitez sa portée aussi strictement que le décrit Intégrer la configuration git dans votre image.
• 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

• statsig.anthropic.com, *.sentry.io, claude.ai et platform.claude.com : ces hôtes apparaissent dans certaines listes de contrôle réseau d’entreprise plus anciennes, mais le runner ne les atteint pas. Les récupérations de feature flags vont à api.anthropic.com, et le runner s’authentifie avec le secret de l’environnement plutôt qu’avec OAuth interactif.
• mcp-proxy.anthropic.com : les sessions auto-hébergées ne l’utilisent pas. Quand la livraison des connecteurs est activée pour votre organisation, les connecteurs claude.ai de votre organisation atteignent les sessions via api.anthropic.com. Consultez Serveurs MCP.

• L’installateur d’une ligne : récupère install.sh depuis claude.ai au moment de l’installation.
• claude auth login interactif : se connecte via claude.ai, claude.com et platform.claude.com. La configuration guidée, le mode connecté de doctor et le dispatch CI l’utilisent. Le navigateur avec lequel vous vous connectez charge également les vérifications de navigateur de la page de connexion claude.ai depuis hcaptcha.com, *.hcaptcha.com et challenges.cloudflare.com. Si votre organisation utilise l’authentification unique (SSO), ce navigateur peut également être redirigé via sso.claude.com.

​

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.
• push.negotiate = true, donc git demande à votre hôte git quels commits il possède déjà avant de préparer un push. Nécessite Claude Code v2.1.257 ou plus récent.
• core.hooksPath pointant vers un répertoire de hooks géré par le runner. Ses hooks commit-msg et prepare-commit-msg ajoutent une remorque Co-authored-by: pour le créateur de la session à chaque commit. La remorque est construite à partir de l’email dans CCR_SESSION_ACCOUNT_EMAIL et omise quand cette variable n’est pas définie. Si votre image définit déjà core.hooksPath et que le runner n’utilise pas git géré par Anthropic, le runner laisse votre paramètre en place, ignore l’installation de ces hooks, et affiche un avertissement [runner:git].

​

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 à portée minimale
• GIT_SSH_COMMAND pointant vers une clé à portée étroite

• 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

• github.com uniquement : Anthropic ne sert une session que lorsque tous ses dépôts sont sur github.com, et le proxy git ne prend pas encore en charge GitHub Enterprise Server. Sur un runner avec le proxy git, une session ayant un dépôt sur un autre hôte git ne démarre pas.
• Identifiants pour les dépôts de la session uniquement : Anthropic fournit des identifiants git pour les dépôts qui font partie de la session, et non pour les autres dépôts du même hôte git. Un sous-module privé, une dépendance que votre gestionnaire de paquets récupère avec git, ou une marketplace de plugins dans un autre dépôt n’obtient aucun identifiant d’Anthropic. Demandez aux personnes qui créent des sessions d’ajouter chaque dépôt dont une session a besoin lors de sa création. Chaque exécution d’une tâche planifiée cloud est une session avec les dépôts de la tâche ; demandez donc au propriétaire de chaque tâche d’ajouter chaque dépôt dont ses exécutions ont besoin.
• Pushs de branches uniquement : un push qui supprime une branche échoue, tout comme un push vers tout autre type de ref, comme un tag. Pour savoir quelles branches un push peut mettre à jour, consultez Proxy GitHub.
• Comptes GitHub connectés : demandez à chaque personne qui crée des sessions utilisateur avec un dépôt de connecter GitHub. Sans leur propre connexion, ces sessions ne démarrent pas.
• --capacity 1 : le proxy git nécessite une session par processus runner, donc exécutez plus de répliques pour le parallélisme. Activer le proxy git Anthropic liste les exigences.
• Configuration git globale remplacée : le runner supprime et remplace la configuration git globale de l’utilisateur sous lequel il s’exécute. Exécutez-le en tant qu’utilisateur dédié ou dans un conteneur.
• Identifiants de l’hôte pour les pushs de l’hôte : le push --push-outcome-on-release du runner et tout push effectué par votre hook post-session utilisent toujours les propres identifiants git de l’hôte runner et son chemin réseau vers github.com. Gardez ces identifiants hors de la configuration git globale, et consultez Livrer la configuration git dans votre image pour les façons de les fournir.
• Décision par session : Anthropic décide pour chaque session du runner s’il sert son git, et une session qu’il ne sert pas ne démarre pas. Quand des sessions ne démarrent pas sur un runner avec le proxy git couvre les causes.

​

Activer le proxy git Anthropic

• Claude Code v2.1.267 ou plus récent : les versions antérieures acceptent le flag mais ne transmettent pas la demande pour qu’Anthropic serve git et n’affichent pas la ligne Registering as opted in, donc Anthropic ne sert pas leurs sessions.
• --capacity 1, la valeur par défaut : chaque processus runner gère une session à la fois, donc exécutez plus de répliques pour le parallélisme.
• Git 2.32 ou plus récent : les anciennes versions de git ignorent la configuration git par session que le runner met en place pour le proxy git.

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

​

Comment Anthropic sert git pour une session

• Sessions utilisateur : Anthropic utilise le jeton OAuth GitHub stocké pour le créateur de la session.
• Sessions de bot et d’agent : Anthropic utilise le jeton d’installation GitHub App de votre organisation.
• Réécritures d’URL : --git-host-rewrite et --git-ssh-rewrite n’ont aucun effet sur un dépôt que le proxy git sert.

​

Quand des sessions ne démarrent pas sur un runner avec le proxy git

• Ni governed git ACTIVE ni la ligne withheld : un runner antérieur à Claude Code v2.1.267 ne journalise aucune des deux lignes, et Anthropic ne sert pas ses sessions. Mettez à jour le runner vers v2.1.267 ou plus récent en suivant Épingler la version.
• La ligne withheld : Anthropic n’a pas servi la session. Un runner qui fonctionnait auparavant avec le proxy git peut échouer ainsi sans aucun changement de votre côté.
  • Un dépôt n’est pas sur github.com : une session ayant ne serait-ce qu’un dépôt sur un autre hôte git, comme GitHub Enterprise Server, n’est pas servie, y compris ses dépôts github.com. Désactivez le proxy git Anthropic pour les runners de cet environnement.
  • Tous les dépôts sont sur github.com : signalez l’échec à votre équipe de compte Anthropic avec l’identifiant de session figurant dans la ligne withheld. Anthropic enregistre la raison de son côté.
• Une ligne contenant remote: access denied by the git proxy : une session qu’Anthropic sert peut tout de même être refusée, par exemple lorsque la politique de l’organisation refuse l’accès git pour la session, ou que la session n’est pas autorisée pour le dépôt. Le log du runner affiche alors une ligne contenant remote: access denied by the git proxy, et le reste de cette ligne en indique la raison.
• GitHub authentication required : ce message apparaît lorsque le créateur de la session n’a pas de connexion GitHub fonctionnelle sur claude.ai. Le clone de la session échoue, et l’erreur git indique GitHub authentication required. Please reconnect your GitHub account. Demandez à cette personne de connecter ou reconnecter GitHub dans ses paramètres claude.ai.

​

Désactiver le proxy git Anthropic

unset CLAUDE_RUNNER_USE_GIT_PROXY

​

Accès à l’API GitHub sans la GitHub CLI

gh api repos/{owner}/{repo}/pulls -f title='Fix' -f head='my-branch' -f base='main'

• Identifiants : le gh intégré envoie ses requêtes REST via git géré par Anthropic, qui fournit l’identifiant GitHub du côté d’Anthropic, donc l’image n’a besoin d’aucun jeton GitHub pour celui-ci
• Quelles sessions en bénéficient : Anthropic décide pour chaque session si git géré par Anthropic sert le gh de la session. Lorsque c’est le cas, la ligne [runner:session] governed git ACTIVE que le runner journalise pour la session affiche gh_path_shim=true. Sinon, la session n’a pas de gh
• jq : installez jq dans l’image si vous voulez que --jq fonctionne
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC : si l’environnement de la session la définit, Claude Code ne fournit pas le gh intégré, et la session n’a pas de gh

​

Faire confiance à une autorité de certification privée avec git géré par Anthropic

• Magasin de certificats système : installez votre CA dans le magasin de certificats système de l’hôte runner, et git lui fait confiance sans l’une ou l’autre variable.
• GIT_SSL_CAINFO : définissez-la sur un fichier PEM de vos CAs, par exemple GIT_SSL_CAINFO=/etc/ssl/corp-ca.pem.
• GIT_SSL_NO_VERIFY : n’aide pas derrière un proxy de re-signature. Le clone propre du runner via git géré par Anthropic vérifie les certificats même quand la variable est définie, donc ce clone échoue jusqu’à ce que git fasse confiance à votre CA via l’une des deux autres approches.

• GIT_SSL_CAINFO : ce par rapport à quoi git vérifie git géré par Anthropic dépend de l’endroit où git s’exécute :
  • Clone et récupérations propres du runner : s’exécutent sans la variable et vérifient git géré par Anthropic par rapport à un fichier de certificat par session que le runner écrit. Le runner construit ce fichier à partir du bundle CA système de l’hôte runner et des certificats de votre fichier.
  • Git à l’intérieur de la session : obtient la configuration http.sslCAInfo nommant votre fichier à la place de la variable, plus les entrées http.<url>.sslCAInfo qui vérifient git géré par Anthropic par rapport au fichier par session.
  • Hooks checkout et post-session : héritent la variable inchangée.
• GIT_SSL_NO_VERIFY : quelles vérifications de certificat restent désactivées dépend de l’endroit où git s’exécute :
  • Clone et récupérations propres du runner : s’exécutent sans la variable et vérifient le certificat qui leur est présenté.
  • Git à l’intérieur de la session : obtient la configuration http.sslVerify=false à la place de la variable, donc les vérifications restent désactivées pour les autres hôtes. Il obtient également des entrées http.<url>.sslVerify=true qui gardent les vérifications activées pour git géré par Anthropic.
  • Hooks checkout et post-session : quand la session a un référentiel sur git géré par Anthropic, obtiennent la configuration http.sslVerify=false à la place de la variable. Ils obtiennent également des entrées http.<url>.sslVerify=true qui gardent les vérifications activées pour git géré par Anthropic.

​

Ajouter des dépôts github.com aux sessions de canal Claude Tag

​

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, ou un hôte runner qui ne dispose que d’une clé SSH. Par exemple, pour cloner des dépôts github.com via SSH, ajoutez --git-ssh-rewrite github.com à la commande du runner. Le runner réécrit alors https://github.com/owner/repo en git@github.com:owner/repo. SSH doit se connecter sans invite.

​

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 jq python3 \
 && 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="$(curl -fsSL https://downloads.claude.ai/claude-code-releases/stable)" \
  -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.
• Plusieurs conteneurs de runner sur un même hôte : dimensionnez l’hôte pour la somme des capacités des runners, car chaque runner ne décompte que ses propres sessions par rapport à --capacity :
  • Mémoire : multipliez la mémoire d’une session par cette somme, puis ajoutez ce qu’utilisent les propres processus de l’hôte
  • CPU : multipliez la demande de CPU d’une session par cette somme. Pour permettre à toutes les sessions de dépasser leur demande en même temps, multipliez plutôt sa limite de CPU.
  Donnez à chaque runner son propre conteneur. Utilisez le même chemin --base-dir dans chacun, sur un stockage qu’aucun autre conteneur de runner ne monte, afin que chaque runner dispose de son propre répertoire de travail.

​

Donner à chaque session sa propre limite de mémoire

• Dans un conteneur : exécutez un runner par conteneur, et définissez la limite de mémoire du conteneur, comme limits.memory sur Kubernetes, --memory sur Docker, ou mem_limit dans un fichier Compose. Gardez la somme des limites des conteneurs en dessous de la mémoire de l’hôte, car lorsque l’hôte lui-même manque de mémoire, le noyau peut tuer des processus n’importe où sur l’hôte.
• Sous systemd sans conteneur : définissez MemoryMax sur l’unité du runner, et exécutez un runner par hôte, car les runners qui utilisent le même --base-dir sur un même système de fichiers partagent les dépôts qui y sont clonés. Par exemple, à --capacity 1 sans hook checkout, leurs sessions sur un même dépôt peuvent travailler simultanément dans le même checkout. Pour exécuter plusieurs runners sur un même hôte, donnez à chacun un conteneur.

​

Laisser de la marge sous les limites de processus et de threads

​

Où définir chaque limite

​

Mesurer le pic d’une session

​

Vérifier une limite pids.max

• Vérifier si pids.max a été atteinte : recherchez dans le log du noyau de l’hôte, par exemple avec dmesg, une ligne contenant cgroup: fork rejected by pids controller in et le chemin d’un cgroup. Le noyau ne la consigne que la première fois qu’il refuse un processus ou un thread dans ce cgroup, recherchez donc dans l’ensemble du log.
• Voir la limite en vigueur : lisez pids.max dans le répertoire cgroup du runner et dans chaque répertoire situé au-dessus. La valeur la plus basse est la limite en vigueur, et max signifie qu’il n’y a aucune limite à ce niveau.

​

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"
            - --base-dir
            - /workspace
          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"
      - --base-dir
      - /workspace
    secrets:
      - environment-secret
    restart: always
    stop_grace_period: 90s

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

​

Délai d’arrêt

1. Le runner attend jusqu’à --drain-wait-sec secondes, 0 par défaut, que les tours encore en cours se terminent.
2. Il termine l’arborescence des processus de chaque session, y compris toute commande que Claude exécutait encore, mais pas un processus toujours en cours d’exécution après la fin de sa commande shell.
3. Il exécute le hook de cycle de vie post-session.

• --drain-wait-sec pour l’étape 1, 0 seconde par défaut
• --session-stop-grace-sec pour l’étape 2, 5 secondes par défaut
• --post-session-hook-timeout-sec pour l’étape 3, 60 secondes par défaut
• Une marge fixe de 15 secondes
• 30 secondes supplémentaires lorsque --push-outcome-on-release est défini

• Avec --retire-at : laissez suffisamment de temps entre l’heure de retraite et l’heure d’arrêt de l’hôte pour que les tours typiques se terminent, plus l’attente des tâches en arrière-plan que Cycle de vie du runner décrit, plus la durée journalisée. 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 : le délai d’arrêt doit également couvrir les minutes que vous configurez et une attente supplémentaire avant le début du drainage, 75 secondes avec les paramètres par défaut. Différer le drainage au-delà du premier signal explique les deux. Le runner journalise également cette durée plus longue au démarrage.

​

Laisser les tours en cours se terminer avant un redémarrage

• --drain-wait-sec : à peu près la durée des tours et des tâches en arrière-plan que vous voulez laisser se terminer. Il s’agit d’un maximum : l’attente prend fin plus tôt s’ils se terminent avant.
• Votre délai d’arrêt : terminationGracePeriodSeconds dans Kubernetes, stop_grace_period dans Docker Compose. Par exemple, avec --drain-wait-sec 120, remplacez le 90 dans la recette Kubernetes ou Docker Compose par 200.
• Si vous avez modifié d’autres paramètres d’arrêt : les 80 secondes correspondent aux paramètres par défaut. Démarrez un runner avec vos flags, et utilisez au moins le nombre figurant dans sa ligne de démarrage This runner needs up to, qui inclut l’attente. Avec --defer-shutdown-max-min défini, utilisez le nombre plus élevé de la ligne de démarrage suivante, après Size the stop timeout to at least. Délai d’arrêt liste ce qui s’ajoute à ces nombres.

​

Publier un message d’état avant un redémarrage

​

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, les sessions inactives restent sur le runner.
• 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 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 dans le pipe de log 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 l’intégralité du drainage.
• 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é

• À --capacity 1 : le runner récupère la ref demandée, détache HEAD, et réinitialise dur à celle-ci, ce qui est quasi-instantané quand peu a changé.
• À une --capacity supérieure à un : le runner récupère dans ce clone, puis extrait un worktree distinct à partir de celui-ci pour chaque session. Un clone pré-chauffé économise le téléchargement, mais pas le checkout.

• 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.

• Profondeur du clone : créez le clone sans --depth, avec ou sans --single-branch. Le runner ne passe jamais --depth lorsqu’il récupère dans un clone doté d’un remote origin, même si vous définissez CLAUDE_RUNNER_FETCH_DEPTH. Avec un clone complet, chaque session ne télécharge que les commits qui manquent au clone. Avec un clone peu profond, une session sur une branche qui a divergé avant le commit le plus ancien du clone télécharge tout l’historique de cette branche.
• Les changements suivis se réinitialisent, les fichiers non suivis persistent : à --capacity 1, 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.
• Les répertoires par session persistent aussi : à côté du checkout, le runner crée des entrées par session sous <base-dir>/_sessions/ pour chaque session qu’il exécute. Le répertoire de configuration Claude de la session contient une copie locale de la transcription de la conversation. À côté se trouvent les fichiers téléchargés de la session, quand la session en a. Le répertoire de session s’y trouve aussi : il contient tous les worktrees par session et les checkouts du hook checkout pendant que la session s’exécute, et il conserve tout ce que Claude a écrit dedans. Par défaut, le runner les laisse en place quand la session se termine, donc sur un disque qui survit au processus runner, ils s’accumulent. Chaque session s’exécute en tant qu’utilisateur du runner, donc toute session ultérieure que ce disque sert peut les lire. Si vous conservez un --base-dir persistant, dimensionnez le volume pour cette croissance. La même chose s’applique à toute configuration qui redémarre le runner sur le même système de fichiers, y compris la recette Docker Compose.
• Avec --remove-session-state, les répertoires par session ne persistent pas : démarrez le runner avec --remove-session-state pour qu’il supprime les répertoires par session de chaque session à la fin de la session. La suppression est au mieux : les répertoires restent quand le runner est tué avant l’exécution de son nettoyage. Le clone canonique et les fichiers qu’une session a écrits ailleurs sur l’hôte, comme le répertoire temporaire, restent indépendamment.
• 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. Il conserve le magasin d’objets et l’état peu profond, et supprime l’index. Sans l’index, chaque session commence par un checkout complet de la copie de travail au lieu d’une réinitialisation quasi-instantanée. Le runner récupère toujours dans le clone existant plutôt que de cloner à nouveau le dépôt. Les pré-chauffages de sous-module ne sont pas supportés sous le proxy.
• Avec le proxy git, un pré-chauffage reftable perd ses refs : quand le runner assainit .git/ avant chaque session, il conserve .git/refs/ et supprime le répertoire .git/reftable/. Un clone pré-chauffé au format de ref reftable de git perd ainsi ses refs ; pré-chauffez donc plutôt le clone au format de ref files de git.
• 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.

​

Confirmer que le runner utilise votre clone

​

Épingler la version

• Avant d’épingler une version : vérifiez les versions de Claude Code que les modèles nécessitent pour chaque modèle que vos sessions utilisent. Si un modèle nécessite une version plus récente que celle qu’exécutent vos sessions, le serveur rejette les requêtes pour ce modèle avec Claude Code ne supporte pas ce modèle.
• 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 une flotte fixe : lisez les entrées du changelog entre votre version et celle que vous installez, puis installez la version plus récente ou reconstruisez l’image et redémarrez les runners
• Pour mettre à niveau des runners à la demande : lisez les entrées du changelog entre votre version et celle que vous installez, puis modifiez l’image que démarre votre hook spawn-runner. Chaque nouveau runner obtient la nouvelle version. Un runner déjà actif, y compris un runner en attente démarré par --min-idle, conserve sa version jusqu’à ce qu’il se termine. Ne le redémarrez pas, car son ordre de travail est à usage unique.
• Si les sessions démarrent un binaire différent : si vous utilisez --exec-path ou un hook command pour démarrer un binaire Claude Code autre que celui du runner, les sessions exécutent la version de ce binaire. Mettez à jour ce binaire lorsque vous mettez à jour le runner.
• 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.

​

Libérer les sessions inactives sur une flotte fixe

• Séries au-dessus de cette durée, comme 1800 pour 30 minutes : des sessions inactives occupent ces emplacements, définissez donc --release-idle-session-min
• Toutes les séries en dessous : aucune session n’est restée inactive aussi longtemps. Ajoutez des runners, ou définissez --kill-session-after-min pour les sessions qui ne deviennent jamais inactives.
• Un runner sans aucune série : aucune session ne l’occupe. Consultez Sessions stay queued sous Dépannage.
• Un runner dont les métriques ne répondent pas : son processus s’est peut-être arrêté. Consultez An environment that looks healthy sous Quand le runner s’arrête.

• Travail non poussé : une session libérée reprend à son prochain message, sans le travail qu’elle n’avait pas poussé. Pour conserver ses commits, consultez Les sessions reprises perdent le travail non poussé.
• Arrêt du runner : un runner qui libère sa dernière session entame un arrêt normal. Faites-le redémarrer par votre superviseur sur un système de fichiers vierge, comme le décrit Renforcer votre déploiement.
• Sessions qui ne deviennent jamais inactives : définissez également --kill-session-after-min, car certaines sessions ne comptent pas comme inactives

​

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

• Si la session attend son utilisateur, le runner la libère. Si son tour s’est terminé et elle ne contient que des tâches de fond, le runner attend jusqu’à 60 secondes pour que ces tâches se terminent, puis la libère. La session reprend quand son utilisateur envoie son prochain message.
• Si un tour est toujours en cours d’exécution, le runner attend que le tour se termine, ou que la session attende ensuite son utilisateur, puis la libère.
• Si la session est toujours sur le runner quand la fenêtre de grâce se termine, le runner la termine, et tout travail du tour en cours d’exécution est perdu. Un tour attendant une approbation demandée de l’intérieur d’un appel d’outil en cours d’exécution est une façon pour une session de dépasser la fenêtre.

​

Limitations supplémentaires

• Les sessions reprises perdent le travail non poussé : un nouveau runner clone à nouveau le dépôt à partir de sa branche de démarrage, donc le travail que la session n’avait pas poussé est perdu.
  • Pour conserver le travail commité : définissez --push-outcome-on-release sur chaque runner de l’environnement, car un runner sans ce flag reprend la session à partir de sa branche de démarrage. Un runner avec ce flag effectue, dans la mesure du possible, un push des branches de résultat de la session avant de la libérer, et la session reprise démarre à partir de ces commits. Le push utilise les propres identifiants git de l’hôte runner, y compris sur un runner qui utilise git géré par Anthropic.
  • Avec un hook checkout : les dépôts extraits via un hook de cycle de vie checkout ne font pas l’objet d’un push. Créez plutôt un instantané de ces dépôts à partir du hook post-session.
  • Avant d’activer le flag : limitez qui peut pousser vers les refs claude/* sur le dépôt distant source. À la reprise, le runner récupère la branche précédemment poussée sans vérifier qui l’a poussée.
  • Les modifications non commitées sont toujours perdues : pour demander à Claude de créer un commit et de pousser lorsqu’il a fini de répondre, consultez Demander aux sessions de pousser leur travail
• Une commande interrompue par la perte d’un runner peut s’exécuter à nouveau : lorsque la session reprend sur un autre runner, Claude voit l’appel d’outil interrompu avec un résultat indiquant que son issue est inconnue.
• Le clonage d’un dépôt ajouté en milieu de session peut échouer : Claude le clone avec git clone via HTTPS. Sur un runner sans --use-anthropic-git-proxy, le clonage échoue avec une erreur d’authentification git si rien sur l’hôte ne peut lire le dépôt. Dans la mesure du possible, sélectionnez chaque dépôt 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é.
• Quand quelqu’un archive ou supprime une session, ou libère son runner depuis le menu de la session : ne comptez pas sur le push de --push-outcome-on-release. Pour sauvegarder les commits dans ces cas, poussez HEAD vers une branche de secours à partir d’un hook post-session. Si vous partez de l’exemple qui s’y trouve, faites-le pousser même lorsqu’il n’y a aucune modification non commitée, car il ne pousse qu’après un commit d’instantané.

​

Signaler un problème

​

Dépannage

claude self-hosted-runner doctor

• Le runner n’apparaît pas dans l’environnement : vérifiez que l’hôte peut joindre api.anthropic.com en HTTPS, que le secret de l’environnement est à jour et que l’horloge de l’hôte est à moins de cinq minutes de l’heure réelle ; un décalage plus important fait échouer l’authentification. En cas d’échec d’authentification, le runner journalise [runner:fatal] avec le motif du rejet.
• Le runner s’arrête au démarrage avec cannot create or write to base directory : le runner ne peut pas créer --base-dir ni y écrire, ce répertoire étant /workspace par défaut. Corrigez le propriétaire du répertoire ou faites pointer --base-dir vers un chemin accessible en écriture, comme décrit dans Conserver un répertoire de base et une capacité identiques sur tous les runners. Si le runner journalise plutôt une ligne [runner:fatal] indiquant que la vérification du répertoire de base a expiré, le répertoire se trouve sur un montage NFS ou CSI bloqué. Vérifiez l’état du montage plutôt que les permissions. Le runner affiche ces deux échecs de démarrage sur stderr avant d’ouvrir --log-file ; cherchez-les donc dans le terminal ou dans les logs de conteneur de votre plateforme plutôt que dans le fichier de log. Avant la v2.1.225, le runner ne vérifiait pas le répertoire de base au démarrage, et cette erreur de configuration faisait plutôt échouer les sessions après leur prise en charge.
• Le runner s’arrête au démarrage avec RegisterRunner failed: et une erreur de certificat TLS : l’erreur peut être, par exemple, self signed certificate in certificate chain. Le runner ne fait pas confiance à l’autorité de certification (CA) à l’origine du certificat qu’il a reçu, comme c’est le cas derrière un proxy d’inspection TLS. Définissez NODE_EXTRA_CA_CERTS dans l’environnement du runner avec un fichier PEM contenant la CA racine du proxy. Vous n’avez pas à la redéfinir pour les sessions, qui en héritent. Git ne la lit pas : pour les clones passant par ce proxy, définissez également GIT_SSL_CAINFO.
• Votre script de démarrage affiche une erreur d’écriture contenant Resource temporarily unavailable et s’arrête : votre script partage son stdout ou son stderr avec le processus claude self-hosted-runner ou orchestrateur qu’il démarre, lequel a basculé ce pipe ou ce socket partagé en mode non bloquant. Lorsque le pipe est plein, une écriture de votre script échoue avec cette erreur du système d’exploitation au lieu d’attendre, et avec set -e le script s’arrête. Pour éliminer l’erreur, envoyez la sortie du runner ou de l’orchestrateur vers un fichier que l’utilisateur de votre script peut créer. Ajoutez >> "$HOME/claude-runner.log" 2>&1 à la commande qui le démarre, avant tout & qui le place en arrière-plan :
  claude self-hosted-runner --environment-secret-file /etc/claude/environment-secret >> "$HOME/claude-runner.log" 2>&1
  
  La sortie propre de votre script continue d’aller là où elle allait auparavant, tandis que ce que le runner écrit sur stdout et stderr, y compris ses erreurs de démarrage, va dans ce fichier. Utilisez cette redirection shell plutôt que --log-file seul, qui duplique le log dans un fichier pendant que le runner continue d’écrire sur stdout et stderr. Si vous passez déjà --log-file, conservez-le également, car la redirection ne modifie pas ce que reçoit ce fichier.
• L’orchestrateur journalise poll failed: avec une erreur de certificat TLS et continue de réessayer : l’orchestrateur ne fait pas confiance à la CA à l’origine du certificat qu’il a reçu, comme c’est le cas derrière un proxy d’inspection TLS. Définissez NODE_EXTRA_CA_CERTS dans l’environnement de l’orchestrateur avec un fichier PEM contenant la CA racine du proxy. Définissez-la également pour les runners que votre hook spawn-runner démarre. Par exemple, une ligne peut se terminer par poll failed: self signed certificate in certificate chain — retrying in 1s, avec le message de la bibliothèque TLS entre les deux-points et le tiret. Pour confirmer la correction, vérifiez que connected vaut true dans le corps de /healthz de l’orchestrateur.
• Les sessions restent en file d’attente : chaque runner en ligne est peut-être verrouillé sur un propriétaire différent. Consultez la métrique claude_code_self_hosted_runner_locked_account de chaque runner ou le champ locked_account de sa ligne de log [runner:health] pour savoir qui le détient. Les deux n’affichent l’adresse e-mail du propriétaire qu’une fois que le runner a reçu un jeton de session portant une revendication act.email, ce qui n’est jamais le cas des sessions d’un agent Claude Tag. Sans cette revendication, le runner n’émet aucune série locked_account et journalise locked_account=yes, ce qui vous indique que le runner est verrouillé, mais pas sur quel propriétaire. Ajoutez des réplicas ou attendez qu’un runner existant se vide et redémarre. Si l’environnement utilise des runners à la demande, vérifiez plutôt l’orchestrateur ; consultez Runners à la demande.
• Les sessions échouent immédiatement après leur prise en charge : ouvrez la session dans claude.ai/code pour voir l’erreur. Si l’erreur indique que git n’a pas pu s’authentifier, vérifiez les identifiants git du runner. Sur un runner démarré avec --use-anthropic-git-proxy, consultez Lorsque les sessions ne démarrent pas sur un runner avec le proxy git. Un répertoire de base non accessible en écriture arrête le runner au démarrage au lieu de faire échouer les sessions. Consultez l’entrée Le runner s’arrête au démarrage avec cannot create or write to base directory de cette liste.
• Une session est prise en charge, mais Claude ne répond jamais à son premier message : si vos runners joignent api.anthropic.com via un proxy, configurez-le pour qu’il transmette la réponse /worker/events/stream de la session au fur et à mesure de son arrivée. Augmenter les délais d’expiration du runner n’aide pas. Pour confirmer la cause dans le log du runner, consultez Une session est prise en charge, mais Claude ne répond jamais à son premier message.
• Les sessions ne démarrent pas sur un runner ayant défini --use-anthropic-git-proxy : cherchez dans le log du runner access denied by the git proxy, ou une erreur git mentionnant une adresse api.anthropic.com contenant /git_proxy/. Pour déterminer si Anthropic a servi la session et corriger la cause, consultez Lorsque les sessions ne démarrent pas sur un runner avec le proxy git.
• Les sessions ne peuvent pas accéder au réseau via un proxy de sortie avec authentification : lorsque la source que vous avez définie avec --proxy-authorization-command ou --proxy-authorization-file échoue, expire au bout de 30 secondes ou renvoie une valeur vide, le runner répond 502 Bad Gateway à cette connexion et journalise la raison. Le runner masque le stderr de la commande dans ce log et ne journalise jamais la valeur de l’en-tête. Avec --proxy-authorization-command, exécutez vous-même la commande sur l’hôte pour vérifier qu’elle affiche la valeur complète de l’en-tête sur stdout. Si le runner s’arrête plutôt au démarrage avec could not start the proxy-authorization listener, il n’a pas pu ouvrir son listener de loopback.
• Le runner journalise des lignes Poll failed contenant rejecting the malformed poll response : le runner a reçu une réponse d’interrogation de travail dont le corps n’est pas le JSON attendu de la file d’attente. L’une des causes possibles est un proxy d’interception ou un portail captif qui répond avec sa propre page. Si le runner se connecte via un proxy, configurez le proxy pour qu’il transmette sans modification les réponses de api.anthropic.com. Le runner rejette la réponse malformée, la comptabilise sous le type transport de la métrique claude_code_self_hosted_runner_poll_errors_total et réessaie selon le calendrier des interrogations échouées décrit dans Cycle de vie des sessions. Le runner continue de servir ses sessions actives. Avant la v2.1.246, le runner interprétait une telle réponse comme une file de travail vide, ce qui pouvait mettre fin à ses sessions actives ou provoquer son arrêt.
• Une session échoue avec no longer exists on the remote ou couldn't find remote ref : le runner interprète le message couldn't find remote ref de git comme une branche supprimée. La branche peut pourtant toujours exister. Cherchez-la sur votre hôte git, sous le nom exact figurant dans le message, puis vérifiez chaque cause qui correspond :
  • La branche a disparu : restaurez-la, comme le demande le message.
  • La branche existe et vous n’administrez pas le runner : envoyez le message complet à l’administrateur du runner et indiquez-lui que la branche existe.
  • La branche existe et le runner dispose d’un hook checkout : une commande git de votre hook peut afficher couldn't find remote ref sur stderr avant que le hook ne se termine avec un code non nul. Trouvez cette commande, et corrigez la ref qu’elle demande ou le dépôt distant depuis lequel elle effectue le fetch. Le runner transmet à votre hook la révision demandée par la session via CLAUDE_RUNNER_REPO_REF.
  • La branche existe et le runner n’a pas de hook checkout : le runner récupère lui-même la branche. Si un --git-host-rewrite s’applique au dépôt, vérifiez que l’hôte vers lequel il réécrit possède la branche sous le même nom, et poussez-y la branche si ce n’est pas le cas.
  • La branche existe et le runner est antérieur à la v2.1.301 : mettez à niveau le runner comme décrit dans Épingler la version, afin qu’un autre échec affiche sa propre erreur. Avant la v2.1.301, d’autres échecs dont la sortie d’erreur contenait couldn't find remote ref étaient également signalés comme une branche supprimée.
  Une fois le runner mis à niveau ou la cause corrigée, réessayez la session ou démarrez-en une nouvelle. Si aucune de ces vérifications ne révèle la cause, signalez un problème. Pour la source vers laquelle la session pousse ses résultats, une branche supprimée fait échouer la session. Pour une source git que la session ne fait que lire, le runner ignore cette source et continue avec les autres. Le runner fait échouer la session lorsque l’ignorer la laisserait sans aucun dépôt. Avant la v2.1.228, une telle session démarrait dans un répertoire vide.
• Claude Tag ne publie parfois pas sa réponse dans Slack : le rappel de réponse est un hook fourni par le plan de contrôle. Vérifiez avec claude --version que le runner exécute Claude Code v2.1.229 ou ultérieure, car les runners plus anciens ignorent les hooks fournis ; vérifiez que python3 --version réussit dans l’image du runner, car les hooks exécutent python3 ; et vérifiez qu’aucun fichier de paramètres ne désactive les hooks, qu’il s’agisse de disableAllHooks dans managed-settings.json, dans le ~/.claude/settings.json de l’utilisateur du runner, ou dans le .claude/settings.json ou le .claude/settings.local.json du dépôt, ou encore de allowManagedHooksOnly ou d’un strictPluginOnlyCustomization couvrant les hooks dans les paramètres gérés.
• Une session démarre sans l’un de ses dépôts : sur un runner sans hook checkout, l’hôte git peut refuser la vérification d’accès du runner pour un dépôt que la session ne fait que lire. Le runner ignore alors ce dépôt, journalise une ligne [runner:warn] could not access context source indiquant le refus, et démarre la session avec les dépôts restants. Le runner n’ignore qu’un refus explicite : l’hôte répond que le dépôt est introuvable, git ne trouve aucun identifiant pour l’hôte, ou l’authentification échoue. Une défaillance réseau, un délai d’expiration ou un HTTP 403 fait toujours échouer le démarrage de la session, tout comme un refus pour un dépôt vers lequel la session pousse ses résultats. Le runner fait toujours échouer une session qui se retrouverait sans aucun dépôt si les dépôts refusés étaient ignorés. Avec --use-anthropic-git-proxy, le runner n’ignore qu’un dépôt que le proxy git lui-même refuse. La vérification d’accès est réexécutée chaque fois que la session démarre sur un runner ; ainsi, dès que l’identité git du runner dispose d’un accès en lecture, le démarrage suivant clone le dépôt. Avant la v2.1.274, chacun de ces refus faisait échouer le démarrage de la session.
• Une session échoue au démarrage avec This runner couldn't read : le runner a demandé un dépôt à l’hôte git avec ses identifiants git et a reçu une réponse indiquant que le dépôt est introuvable. Le dépôt n’existe pas, ou ces identifiants ne permettent pas d’atteindre le dépôt.
  • Si vous administrez le runner : accordez à ses identifiants git un accès en lecture au dépôt, puis démarrez une nouvelle session.
  • Si vous avez démarré la session : si le dépôt n’existe pas, démarrez une nouvelle session avec le bon dépôt. Si le runner ne peut pas atteindre le dépôt, demandez à l’administrateur du runner d’accorder l’accès, puis démarrez une nouvelle session.
• Les sessions mettent plusieurs minutes à démarrer ou à reprendre : l’une des causes est un clone initial. Sur une flotte qui démarre chaque runner sur un disque vide, sans hook checkout, le runner clone à nouveau les dépôts de la session avant de démarrer Claude Code. Une session qui reprend sur un disque vide attend de nouveau ce même clone. Pour éviter le clone initial, fournissez un checkout préchauffé. Si vous en fournissez déjà un, vérifiez que le runner l’utilise. Lorsque le runner effectue lui-même le clone et s’arrête après une seule session, réduisez CLAUDE_RUNNER_FETCH_DEPTH par rapport à sa valeur par défaut de 50 commits afin de récupérer moins d’historique. Si vous utilisez un hook, il s’exécute à la place du clone du runner ; examinez donc plutôt ce que fait votre hook. Surveillez la métrique claude_code_self_hosted_runner_session_init_duration_seconds pour connaître la durée des démarrages.
• Les tours échouent avec une erreur 401 : lorsqu’un tour se termine par une erreur 401 ou 403 de l’API Anthropic, le runner récupère un nouveau CLAUDE_CODE_OAUTH_TOKEN auprès d’Anthropic et le transmet à la session. Le tour échoué n’est pas réessayé. Ce jeton a une durée de vie courte, et le runner le renouvelle via le stdin de la session. Lorsqu’une récupération échoue, le runner journalise une ligne inference_token refresh failed indiquant quand il réessaiera, et il continue de réessayer tant que la session s’exécute. Si tous les appels commencent à échouer environ 30 minutes après le début d’une session, un script wrapper a probablement coupé le stdin de la session, de sorte que les renouvellements de jeton ne peuvent pas l’atteindre ; consultez Conserver stdin et le descripteur de fichier 3 attachés. Avant la v2.1.274, le runner cessait de réessayer une récupération échouée après quelques tentatives et attendait la suivante prévue. Un tour échoué ne déclenchait pas de récupération, si bien que chaque tour échouait avec une erreur 401 jusqu’à la récupération planifiée suivante.
• Un tour échoue dans claude.ai/code avec This model needs a newer version of Claude Code : la version de Claude Code avec laquelle vos runners démarrent les sessions est plus ancienne que celle requise par le modèle de la session, si bien que l’API rejette la requête. Mettez à niveau les runners vers la version demandée par le message, ou une version ultérieure, comme décrit dans Épingler la version. D’ici là, les utilisateurs peuvent choisir un autre modèle dans la session.
• Le pod est tué en cours de vidage : augmentez terminationGracePeriodSeconds à au moins la valeur que le runner journalise au démarrage. Consultez Délais d’arrêt.

​

Lorsque le runner s’arrête

• Un arrêt normal : le runner a terminé ses sessions et s’est vidé, a atteint son heure de retrait ou a reçu l’ordre de s’arrêter. Redémarrez-le pour que l’environnement retrouve de la capacité. Cycle de vie du runner décrit ces arrêts.
• Un échec de démarrage : le runner ne peut pas démarrer avec la configuration ou l’hôte qui lui ont été fournis ; il s’arrête donc quelques secondes après avoir démarré, et il s’arrête de la même manière chaque fois que vous le redémarrez. Le redémarrer plus vite n’aide pas. Quelqu’un doit lire sa sortie et corriger la cause.
• Perte de contact : un runner qui ne peut pas joindre Anthropic pendant une durée supérieure à son bail, par exemple pendant la mise en veille de son hôte, peut être retiré de l’environnement. Lorsqu’un runner retiré se reconnecte, il s’arrête. Son log peut afficher une ligne [runner:fatal] contenant runner record gone server-side ou, après une interruption plus longue, poll auth failed. Le runner ne se réenregistre pas de lui-même ; redémarrez-le donc.

​

Reconnaître un échec de démarrage

[runner:fatal] --use-anthropic-git-proxy requires --capacity 1 (the proxy URL is per-session and linked worktrees share origin). Omit --use-anthropic-git-proxy or set --capacity 1.

• Aucune ligne : un runner tué par l’hôte n’affiche ni l’une ni l’autre. Si la sortie se termine sans ligne [runner:fatal] ni ligne error:, vérifiez si l’hôte ou votre orchestrateur a arrêté le processus, par exemple pour dépassement d’une limite de mémoire.
• Le code de sortie : le runner ne réserve pas de code de sortie aux erreurs qui se répètent à chaque démarrage. Il s’arrête avec le même code pour une erreur de configuration, comme une combinaison de flags non prise en charge, et pour un échec susceptible de se résoudre de lui-même, comme une API qui reste inaccessible malgré les nouvelles tentatives du runner. Fondez la décision d’attendre plus longtemps sur le délai au bout duquel le runner s’est arrêté, et lisez la sortie du runner pour en connaître la raison.
• Un environnement qui semble en bonne santé : certaines étapes de démarrage s’exécutent après l’enregistrement du runner auprès de votre environnement, comme --configure-git et la configuration des identifiants du proxy git d’Anthropic. Si l’une de ces étapes échoue, l’environnement peut continuer à répertorier ce runner pendant quelques minutes après l’arrêt du processus, et la page Cloud environments peut afficher Healthy alors qu’aucun runner ne prend de travail. Si les sessions restent en file d’attente dans un environnement qui semble en bonne santé, vérifiez si votre superviseur redémarre le runner.

​

Redémarrer avec une attente croissante

• Kubernetes : le Deployment de cette page ne nécessite aucune modification. Après l’arrêt d’un conteneur, le kubelet attend par défaut avant de redémarrer le conteneur, et l’attente augmente à chaque redémarrage jusqu’à un plafond. L’attente repart de zéro une fois que le conteneur a fonctionné un certain temps sans s’arrêter. Le kubelet applique la même attente après un arrêt normal lorsque le conteneur n’a fonctionné que brièvement. Un runner qui se vide souvent peut donc lui aussi afficher le statut CrashLoopBackOff ; lisez la sortie avant de conclure que le runner ne peut pas démarrer. La commande ci-dessous lit la sortie de la dernière exécution d’un pod du Deployment :
  kubectl logs --previous -n claude-runners deploy/claude-runner
  
  Lorsque la dernière exécution était un échec de démarrage, la ligne [runner:fatal] ou error: figure parmi les dernières lignes de la sortie. Pour lire la dernière exécution d’un autre pod, nommez ce pod à la place de deploy/claude-runner.
• Docker et Docker Compose : la recette Compose de cette page ne nécessite aucune modification. Avec restart: always, Docker attend plus longtemps avant chaque redémarrage d’un conteneur qui continue de s’arrêter, jusqu’à un plafond. Remplacez <container> par le nom du conteneur dans la commande ci-dessous, qui indique combien de fois Docker a redémarré le conteneur :
  docker inspect --format '{{.RestartCount}}' <container>
  
  La commande affiche un nombre. Un nombre qui ne cesse d’augmenter signifie que Docker continue de redémarrer le runner.
• Une unité systemd : par défaut, systemd attend le même RestartSec avant chaque redémarrage et ne l’allonge pas ; une unité avec Restart=always redémarre donc un runner qui ne peut pas démarrer à ce même intervalle à chaque fois. Lorsque les démarrages sont suffisamment rapprochés pour atteindre la limite de débit de démarrage de l’unité, cinq démarrages en 10 secondes par défaut, systemd cesse de redémarrer l’unité. L’unité reste arrêtée jusqu’à ce que quelqu’un la redémarre, ce que systemd autorise une fois l’intervalle de la limite de débit écoulé ou après systemctl reset-failed. Comme RestartSec s’applique à chaque redémarrage, une valeur plus longue retarde également le redémarrage après un arrêt normal. Choisissez une valeur qui équilibre les deux, et configurez une alerte sur le nombre de redémarrages de l’unité.
• Une boucle shell ou votre propre superviseur : appliquez vous-même la même règle. Commencez par une attente de cinq secondes. Après chaque exécution terminée en moins d’une minute, doublez l’attente avant le redémarrage suivant, jusqu’à cinq minutes. Après une exécution ayant duré une minute ou plus, revenez à cinq secondes.

​

Déterminer pourquoi le runner continue de s’arrêter

• La dernière ligne [runner:fatal] ou error: : elle indique pourquoi le runner s’est arrêté. Dépannage répertorie les causes courantes.
• La combinaison de flags : le proxy git d’Anthropic nécessite --capacity 1. Les recettes de cette page utilisent une capacité plus élevée ; réduisez-la donc lorsque vous ajoutez le proxy à l’une d’elles.
• Ce que l’environnement du service peut atteindre : si le runner démarre manuellement mais échoue sous votre superviseur, comparez l’utilisateur, le répertoire personnel, le PATH et la limite de mémoire. --configure-git et le proxy git d’Anthropic nécessitent git dans le PATH et un ~/.gitconfig accessible en écriture.
• Le secret de l’environnement : si vous avez révoqué le secret ou fait une faute de frappe, le runner affiche une ligne contenant RegisterRunner auth failed.
• L’onglet Activity de l’environnement : ouvrez l’environnement et sélectionnez Activity. Si de nouveaux runners continuent d’y apparaître sans qu’aucun ne prenne de travail, votre superviseur redémarre le runner.

​

Une session est prise en charge, mais Claude ne répond jamais à son premier message

GET https://api.anthropic.com/v1/code/sessions/<session-id>/worker/events/stream

• Ne mettez pas la réponse en tampon : transmettez-la au fur et à mesure de son arrivée. Son type de contenu est text/event-stream.
• Laissez la réponse ouverte : elle peut rester ouverte jusqu’à une heure. Si le proxy a un délai d’inactivité, maintenez-le bien au-dessus de 15 secondes, car Anthropic envoie par défaut un keep-alive au moins aussi souvent.

​

Confirmer la cause dans le log du runner

1. Attendez que --startup-timeout-min soit écoulé, 15 minutes par défaut. Le runner arrête alors la session et journalise une ligne qui contient no child output for et se termine par — releasing.
2. Cherchez SDKStartup: SSE dans le log du runner. Ces lignes suivent une ligne finished: interrupted, quelques lignes après celle de l’étape 1. La plupart n’ont pas d’horodatage ; un collecteur de logs peut donc les afficher ailleurs.
3. Trouvez la ligne dans ce tableau :

​

Empêcher la session de réessayer

​

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