Personnaliser les sessions dans les environnements auto-hébergés

​

Scripts wrapper

claude self-hosted-runner --environment-secret-file /etc/claude/environment-secret --exec-path /etc/claude/session-wrapper.sh

​

Donner une valeur par défaut aux variables qui peuvent être non définies

​

Mettre entre guillemets les arguments et les variables que votre script développe

• Arguments : transmettez-les sous la forme "$@"
• Variables : mettez chacune d’elles entre guillemets, comme dans "${CLAUDE_CODE_REMOTE_SLACK_THREAD_URL:-}". Le lien du fil Slack, par exemple, peut contenir ? et &.
• Chaînes eval et sh -c : ne substituez pas une valeur dans une chaîne que eval ou sh -c exécute, même entre guillemets. Faites plutôt référencer la variable par cette chaîne.

​

Garder stdin et le descripteur de fichier 3 attachés

exec 9<&0   # le runner utilise 3 et, à partir de v2.1.309, réserve 4 et 5
"$CLAUDE_RUNNER_CLAUDE_BIN" "$@" <&9 9<&- &
CHILD=$!
trap 'teardown' EXIT
wait "$CHILD"

• Descripteur de fichier 3 : transporte les signaux d’activité de l’enfant vers le runner. Ne le fermez pas et ne le réutilisez pas dans le wrapper.
• Descripteurs de fichier 4 et 5 : les runners sur Claude Code v2.1.309 ou ultérieur les réservent à l’enfant. Ne les fermez pas et ne les réutilisez pas dans le wrapper. Si votre wrapper utilise l’un d’eux, par exemple pour enregistrer stdin, déplacez cet usage vers un descripteur de 6 à 9, que les versions antérieures laissent également libres.
• stderr : lorsque le wrapper ou l’enfant se termine avec un code non nul, le runner publie les dernières lignes de stderr dans la session et les affiche dans son propre log. L’utilisateur de la session voit ces lignes, donc n’affichez pas de secrets sur stderr, et retirez set -x avant de déployer le wrapper. Si vous redirigez stderr, les sessions s’exécutent toujours, mais le runner signale un échec avec le seul code de sortie.

​

Transmettre les flags de prompt système

• Transmettez-les : terminez le wrapper avec exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@", qui transmet les flags de fichier avec tous les autres arguments. Ne les supprimez pas et ne les réécrivez pas. Si une session perd un flag de fichier de prompt, elle s’exécute sans les instructions que le plan de contrôle lui a envoyées.
• Sur un runner en v2.1.281 ou ultérieur, un flag de fichier que vous ajoutez remplace celui du serveur, sans jamais s’y ajouter : chaque flag de fichier de prompt n’accepte qu’une seule valeur et Claude Code conserve la dernière occurrence, donc si vous ajoutez --append-system-prompt-file <path> après "$@", le contenu de votre fichier remplace les instructions ajoutées par le serveur. Pour ajouter des instructions en plus de celles du serveur, placez-les dans le CLAUDE.md de l’image du runner, que le runner injecte dans la configuration de niveau utilisateur de chaque session.

​

Corriger Argument list too long au démarrage de la session

Session <id> finished: failed — reason: child exited 126: /opt/wrapper.sh: line 9: /usr/local/bin/claude: Argument list too long

exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --append-system-prompt "$(cat /opt/team-instructions.md)"

​

Provisionner les identifiants limités au créateur de la session

#!/bin/bash
# Clé sur l'ID utilisateur Anthropic stable et exiger un créateur humain.
CREATOR_SUB=$("$CLAUDE_RUNNER_CLAUDE_BIN" self-hosted-runner decode-token \
  | jq -re '.act.sub // "" | select(startswith("user:"))') \
  || { echo "decode-token: verification failed or no human creator" >&2; exit 1; }

creds=$(your-sts-helper assume-role --subject "$CREATOR_SUB") \
  || { echo "credential exchange failed" >&2; exit 1; }
eval "$creds"

exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"

​

Hooks de cycle de vie

​

checkout

​

Obtenir des identifiants git dans le hook

• Identifiants de clone par session : vérifiez CLAUDE_CODE_SESSION_ACCESS_TOKEN avec une bibliothèque JWT standard par rapport à l’endpoint JWKS sous CLAUDE_RUNNER_API_BASE_URL, comme décrit dans Vérifier le token à partir de votre service. Faites ensuite émettre par votre service d’identifiants des identifiants de clone de courte durée pour l’identité figurant dans la revendication act du jeton. Associez ces identifiants à act.sub, et n’exigez pas act.email.
• Authentification git de l’hôte : utilisez l’authentification git dont l’hôte dispose déjà, comme un agent SSH, un helper d’identifiants ou .netrc.

​

Quand le hook échoue

• Un dépôt vers lequel la session envoie les résultats : le runner fait échouer la session et, en cas de sortie non nulle, affiche à l’utilisateur la fin du stderr du script. Écrivez la raison dans stderr sur une seule ligne courte, écrivez-la en dernier, puis terminez avec un code non nul. N’affichez pas de secrets dans stderr, et supprimez set -x avant de déployer le hook. Si le message git couldn't find remote ref apparaît dans environ les 4 derniers Ko du stderr du hook, le runner signale plutôt une branche supprimée. Le message d’erreur de la session indique alors que la branche n’existe plus sur le remote et demande à l’utilisateur de la restaurer. Si cette branche existe, voir Une session échoue avec no longer exists on the remote ou couldn't find remote ref.
• Un dépôt que la session lit uniquement, comme un dépôt ajouté à une session en cours d’exécution : le runner l’ignore et continue avec les dépôts restants. Le runner publie une étape Skipped dans la session et supprime ce que le hook a laissé au chemin de checkout. Lorsque l’étape Skipped mentionne le hook de checkout, trouvez le détail de l’échec sur la ligne [runner:warn] checkout hook failed dans le log du runner. Lorsque l’étape indique qu’une ref source no longer exists on remote, voir Une session échoue avec no longer exists on the remote ou couldn't find remote ref. Si l’omission laisse la session sans aucun dépôt, le runner fait quand même échouer la session.

​

post-session

• completed : la session s’est terminée proprement. Le processus Claude Code s’est terminé normalement, ou s’est terminé de lui-même après l’archivage ou la suppression de la session.
• failed : le processus Claude Code s’est écrasé, ou la configuration a échoué après son démarrage.
• interrupted : le runner a arrêté la session, dans l’un des cas suivants :
  • Le runner a libéré la session pour libérer l’emplacement.
  • La session a expiré au démarrage.
  • Le serveur a déplacé la session hors de ce runner.
  • L’interrogation du runner a détecté un archivage ou une suppression avant la sortie du processus.
  • Le runner était en drainage.
  • La session a dépassé sa limite --kill-session-after-min.
• abandoned : réservé à une session qu’un autre runner a revendiquée. Le hook ne se déclenche actuellement pas dans ce cas.

#!/usr/bin/env bash
set -u
export GIT_ALLOW_PROTOCOL=${GIT_ALLOW_PROTOCOL:-https:http:ssh}
IFS=':'
# Les remplacements -c l'emportent sur les paramètres locaux au dépôt, empêchant la configuration
# fsmonitor, hook-path et gpg-program écrite par la session d'exécuter du code avec les
# privilèges du hook. -c commit.gpgsign=false laisse aussi ces commits de secours
# non signés sous --configure-git.
# credential.helper et pushurl locaux au dépôt s'appliquent toujours, ainsi que
# core.sshCommand sur un runner antérieur à v2.1.280 ; lisez la note sous le script
# avant de fournir des identifiants à ce push.
g() { git -c core.fsmonitor=false -c core.hooksPath=/dev/null \
        -c commit.gpgsign=false "$@"; }
for ws in $CLAUDE_RUNNER_WORKSPACE_PATHS; do
  cd "$ws" 2>/dev/null || continue
  [ -z "$(g status --porcelain 2>/dev/null)" ] && continue
  g add -A
  g commit -q -m "runner snapshot: $CLAUDE_RUNNER_SESSION_ID ($CLAUDE_RUNNER_EXIT_REASON)" || continue
  g push -q origin "HEAD:refs/heads/rescue/$CLAUDE_RUNNER_SESSION_ID" || true
done

​

Timing du hook quand le runner libère une session

• Inactif après un tour, ou expiré au démarrage : le runner arrête l’enfant et exécute ce hook jusqu’à la fin. Ce n’est qu’alors qu’il libère la session. Un message utilisateur envoyé pendant que le hook s’exécute ne peut pas reprendre la session sur un autre runner avant que le hook se termine.
• En attente que l’utilisateur réponde à une invite, comme une invite de permission : le runner libère d’abord la session, puis exécute ce hook. Un message utilisateur envoyé pendant que le hook s’exécute peut reprendre la session sur un autre runner avant que le hook se termine.

​

Configuration git dans les hooks de cycle de vie

• Hooks git : sauf si vous fournissez une valeur, core.hooksPath vaut /dev/null, donc git ignore les hooks du .git/hooks d’un dépôt et tout répertoire de hooks que ~/.gitconfig désigne. Pour en fournir une, exportez core.hooksPath sous forme de paire GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n dans l’environnement du runner. Le runner lit aussi core.hooksPath depuis la configuration git système, et ne l’utilise que lorsque l’utilisateur du runner ne peut écrire ni ce fichier, ni le répertoire qu’il désigne, ni les fichiers de hooks qu’il contient. Quand le runner ignore une valeur, une ligne [runner:warn] au démarrage indique la valeur et la raison.
• Moniteur du système de fichiers : core.fsmonitor est vide, donc git dans votre hook n’exécute pas de programme de surveillance désigné par un fichier de configuration.
• Protocoles distants : GIT_ALLOW_PROTOCOL vaut https:http:ssh. Un clone, un fetch ou un push qui utilise un chemin local, une URL file:// ou une URL git:// échoue avec fatal: transport 'file' not allowed ou fatal: transport 'git' not allowed.
• Commande SSH et demande d’identifiants : git dans votre hook ignore core.sshCommand et core.askPass provenant des fichiers de configuration. Pour utiliser votre propre commande SSH, définissez GIT_SSH_COMMAND dans l’environnement du runner. Pour utiliser un programme de demande d’identifiants, définissez-y GIT_ASKPASS. Les sessions héritent de l’environnement du runner, donc les deux variables atteignent aussi le git de la session elle-même. N’y placez aucun identifiant.
• Programmes gpg : gpg.program, gpg.openpgp.program, gpg.x509.program et gpg.ssh.program sont des chemins que le runner définit, jamais des valeurs provenant d’un fichier de configuration.
• Signature des commits : avec --configure-git, les commits que vous créez depuis un hook sont signés au nom de la session. Sans ce flag, commit.gpgsign et tag.gpgsign valent false.

• Paires de configuration : une paire GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n que vous exportez dans l’environnement du runner remplace la valeur du runner pour la même clé. Numérotez vos paires à partir de 0 et définissez GIT_CONFIG_COUNT sur leur nombre. Quand la dernière paire annoncée par le compteur est manquante, le runner ignore toutes vos paires et consigne une ligne [runner:warn] au démarrage.
• Variables d’environnement git : le runner laisse GIT_ALLOW_PROTOCOL, GIT_SSH_COMMAND et GIT_ASKPASS tels que vous les avez définis dans son environnement.
• Options git -c : une option git -c à l’intérieur du hook remplace une paire GIT_CONFIG_KEY_n, celle du runner ou la vôtre. Elle ne modifie pas GIT_ALLOW_PROTOCOL, GIT_SSH_COMMAND ni GIT_ASKPASS, que git lit avant toute configuration.

​

command

​

Runners à la demande

claude self-hosted-runner orchestrator \
  --environment-secret-file /etc/claude/environment-secret \
  --hooks-dir /etc/claude/hooks

​

Le hook spawn-runner

• Démarrez-le avec le bon de travail : pointez --environment-secret-file vers un fichier contenant le JWT du bon de travail, ou définissez SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET à la valeur JWT.
• Copiez le JWT avant la sortie du hook : l’orchestrateur supprime le fichier du bon de travail après la sortie du hook, donc copiez le JWT dans la charge de travail que vous soumettez, comme un Secret Kubernetes sur le Job généré, plutôt que de transmettre le chemin du fichier.
• Utilisez --capacity 1 sur les runners générés : un bon de travail lié à une session enregistre exactement un runner lié à cette session, donc une capacité plus élevée ajoute des emplacements qui ne reçoivent jamais de travail, et le runner enregistre un avertissement au démarrage.
• Les bons de travail de pré-réchauffage s’enregistrent sans liaison : le runner de secours n’est pas lié à une session et revendique le travail en attente comme un runner de flotte fixe.

1. Soyez idempotent sur CLAUDE_RUNNER_ORDER_ID. La redélivraison de la même demande doit générer au maximum un runner. Dérivez un nom de ressource déterministe à partir de l’ID de commande et laissez votre plateforme rejeter le doublon. Ne vous basez pas plutôt sur CLAUDE_RUNNER_SESSION_ID. Chaque re-demande pour une session porte le même ID de session avec un nouvel ID de commande. Une charge de travail nommée ou dédupliquée par l’ID de session n’est pas recréée tant que la première existe.
2. Ne réessayez pas la charge de travail. Un ID de commande signifie au maximum une charge de travail créée. Si le runner ne s’enregistre jamais, Anthropic re-demande avec un ID de commande frais après --expected-spawn-seconds.
3. Utilisez le contrat du code de sortie. Sortez avec le statut qui correspond au résultat :
   • Sortie 0 : soumis.
   • Sortie 1, ou hook toujours en cours d’exécution à l’expiration de --hook-timeout : échec pouvant être réessayé. La session recule et est re-proposée. Après 10 demandes échouées consécutives, elle est bloquée comme après une sortie 2 ou supérieure.
   • Sortie 2 ou supérieure : échec ne pouvant pas être réessayé. La session est empêchée de générer un nouveau spawn jusqu’à ce qu’un utilisateur lui envoie un nouveau message ou qu’un Owner sélectionne Retry sur elle dans l’onglet Activity de l’environnement.
   Pendant qu’une session recule, elle affiche Queued dans l’onglet Activity sans erreur de spawn, donc lisez la sortie du hook dans le journal de l’orchestrateur. Une fois bloquée, la session affiche Failed. Développez-la pour lire l’erreur de spawn, tirée des 512 derniers caractères du stderr du hook. Écrivez une erreur exploitable sur stderr, sans aucun secret. Dans un hook shell, gardez les échecs transitoires réessayables. Une demande de pré-réchauffage n’a pas de session à faire échouer : l’orchestrateur consigne une sortie non nulle localement uniquement, et le serveur re-demande le spawn après l’expiration du bail --expected-spawn-seconds.
4. Définissez --expected-spawn-seconds à au moins votre temps p99 entre la demande de spawn et l’enregistrement du runner. Mesurez à partir du moment où l’orchestrateur reçoit la demande de spawn, et incluez toute attente de capacité sur votre plateforme ainsi que le temps de démarrage. Cette valeur est le bail côté serveur, et le bon de travail expire avec lui, donc un runner dont la charge de travail prend plus de temps ne peut pas s’enregistrer. Toutes les répliques d’orchestrateur doivent utiliser la même valeur.

​

Corriger les sessions rouvertes qui restent Queued ou affichent Failed

name="runner-${CLAUDE_RUNNER_SESSION_ID}"

1. Lors de la première demande de spawn de la session, le hook crée une charge de travail portant ce nom, et un runner démarre
2. Le runner se termine, par exemple après --release-idle-session-min, et l’utilisateur rouvre plus tard la session
3. La demande de spawn suivante de la session porte le même ID de session et un nouvel ID de commande, donc le hook construit le même nom
4. Si votre plateforme possède encore la charge de travail de la première demande, parce que rien ne l’a supprimée lorsque son runner s’est terminé, le hook ne crée aucune nouvelle charge de travail et aucun runner ne démarre
5. Chaque demande de spawn ultérieure pour la session se termine de la même manière

name="runner-${CLAUDE_RUNNER_ORDER_ID}"

• Queued : la session reçoit d’elle-même sa prochaine demande de spawn
• Failed : sélectionnez Retry sur elle en tant qu’Owner, ou demandez à son utilisateur de lui envoyer un nouveau message

​

Faire quitter les runners à la demande lorsqu’ils sont inactifs

​

Envoyer la sortie d’un processus en arrière-plan vers un fichier

your-background-command >> "$HOME/claude-runner.log" 2>&1 &

• Environ une seconde après la sortie du hook, l’orchestrateur consigne exited, but a process it started still has the hook's stdout or stderr open. À partir de cette ligne, il consigne jusqu’à 64 Ko supplémentaires de cette sortie sous [runner:hook:spawn-runner:after-exit jti=<order id>], puis abandonne le reste.
• Une fois que l’orchestrateur s’est terminé, les écritures du processus à cet endroit échouent.

• Onglet Activity, dans l’erreur de spawn d’une session échouée : spawn-runner hook timed out after 60000ms, ou les dernières lignes du stderr du hook.
• Journal de l’orchestrateur : timed out after 60000ms, sending SIGTERM to process tree.

​

Quitter le hook sans attendre le runner

• Pour confirmer que c’est le délai d’expiration qui arrête vos runners : recherchez dans le journal de l’orchestrateur timed out after 60000ms, sending SIGTERM to process tree à chaque demande de spawn. Le 60000 correspond à votre --hook-timeout en millisecondes.
• Pour corriger le problème : faites en sorte que le hook soumette le runner à votre plateforme puis sorte avec 0. Si vous augmentez plutôt --hook-timeout, le runner s’arrête simplement plus tard.

​

Garder les échecs transitoires réessayables dans un hook shell

set -e
PERMANENT=; permanent() { printf '%s\n' "$*" >&2; PERMANENT=1; exit 2; }
trap 'rc=$?; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT

• exit 2 ou supérieur isolé : avec le trap défini, il devient une sortie 1. Pour une erreur qu’aucune nouvelle tentative ne peut corriger, appelez plutôt permanent avec la raison, comme permanent "namespace claude-runners does not exist". Appelez-le dans le shell principal, pas à l’intérieur de $( ), ( ) ou d’un pipe.
• exec : ne commencez pas la dernière commande du hook par exec, car exec remplace le shell et le trap ne s’exécute pas.
• Second trap EXIT : un second trap ... EXIT remplace le premier, donc fusionnez les deux en un seul trap. Placez vos commandes de nettoyage directement après rc=$?; et terminez chacune par || true;. Le nettoyage s’exécute alors en cas d’échec comme en cas de succès, et une commande de nettoyage en échec ne définit pas le statut de sortie du hook. Ce trap fusionné illustre la forme, your-cleanup-command représentant votre propre commande :
  trap 'rc=$?; your-cleanup-command || true; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT
  
• Commandes autorisées à échouer : si le hook n’utilisait pas set -e auparavant, il s’arrête désormais à la première commande qui renvoie une valeur non nulle, comme une recherche qui ne trouve rien. Si le hook agit sur le résultat, faites de cette commande la condition d’un if. S’il ignore le résultat, faites suivre la commande de || true.
• La commande qui soumet la charge de travail : ne la faites pas suivre de || true. Avec || true, le hook sort avec 0 même lorsque votre plateforme refuse la soumission, par exemple en cas de dépassement de quota, et la session attend un runner qui n’a jamais été démarré. Nommez la charge de travail d’après CLAUDE_RUNNER_ORDER_ID, comme l’indique la première règle du hook. Une réponse indiquant que la ressource existe déjà correspond alors à une redélivraison de la même demande, donc traitez uniquement cette réponse comme un succès. Pour toute autre réponse, affichez-la sur stderr et sortez avec 1, ou appelez permanent si aucune nouvelle tentative ne peut corriger le problème. Cet exemple le fait pour kubectl create, avec un job.yaml qui ne contient que la charge de travail :
  if ! out=$(kubectl create -f job.yaml 2>&1); then
    case "$out" in
      *AlreadyExists*) ;;
      *) printf '%s\n' "${out:-kubectl create failed}" >&2; exit 1 ;;
    esac
  fi
  
  Le journal de l’orchestrateur affiche alors ce message. Si le hook crée d’autres objets, nommez chacun d’après l’ID de commande, donnez-lui sa propre commande et traitez de la même manière sa réponse indiquant qu’il existe déjà comme un succès. Pour un objet qui contient un secret, affichez un message fixe à la place de la sortie de la commande.

​

Envoyer les requêtes de modèle vers Bedrock ou Agent Platform

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

env | grep -E 'CLAUDE_CODE_USE_(BEDROCK|VERTEX)'

​

Différences par rapport aux sessions sur l’API Anthropic

• Stratégie depuis claude.ai : les paramètres gérés par le serveur n’atteignent pas ces sessions. Les stratégies d’organisation qu’un Owner définit dans les paramètres d’administration de Claude Code ne les atteignent pas non plus ; Claude Code ne les applique donc pas à l’intérieur de la session. Placez les règles sur lesquelles vous comptez dans le fichier de paramètres gérés de l’image du runner.
• Skills du compte : ces sessions ne téléchargent pas les skills activés pour le compte claude.ai d’une personne. Consultez Comment la configuration de chaque session est assemblée.
• Fichiers : les fichiers que les utilisateurs joignent à une session dans claude.ai ou dans l’application mobile ou de bureau ne l’atteignent pas, et Claude ne peut pas renvoyer de fichiers avec l’outil SendUserFile. Placez plutôt les fichiers d’entrée dans le dépôt ou sur le runner.
• Sélection du modèle : le plan de contrôle d’Anthropic envoie le modèle de chaque session, et lorsqu’une session démarre sans modèle, Claude Code utilise son modèle par défaut pour le fournisseur. Vous ne pouvez pas choisir le modèle avec ANTHROPIC_MODEL ou ANTHROPIC_DEFAULT_MODEL dans l’environnement du runner, mais vous pouvez épingler ce vers quoi un alias est résolu :
  • ANTHROPIC_MODEL et ANTHROPIC_DEFAULT_MODEL : le runner les supprime de l’environnement qu’il transmet aux sessions, même si les exemples des pages des fournisseurs définissent ANTHROPIC_MODEL.
  • Variables d’épinglage par famille : les variables décrites dans Épingler les versions de modèle pour Amazon Bedrock et Agent Platform atteignent bien les sessions. Elles déterminent ce vers quoi un alias comme opus est résolu, et non ce vers quoi un ID de modèle complet est résolu.
• Modèles que votre compte ne fournit pas : une session peut échouer sur un message avec une erreur qui nomme le modèle. Activez les modèles que vos développeurs peuvent choisir, le modèle d’arrière-plan décrit dans Épingler les versions de modèle, ainsi que le modèle de classifieur utilisé par le mode auto. Sur Amazon Bedrock, autorisez chacun d’eux dans votre stratégie.
• Recherche web et mode rapide : la recherche web n’est pas disponible sur Amazon Bedrock, et le mode rapide n’est disponible sur aucun des deux fournisseurs. Pour les autres fonctionnalités qui varient selon le fournisseur, consultez Fonctionnalités de la CLI qui varient selon le fournisseur.

​

Serveurs MCP

RUN claude mcp add --scope user sidecar -- /usr/local/bin/mcp-sidecar
RUN claude mcp add --scope user --transport http internal http://mcp-gateway.svc.cluster.local:8080

• Le fichier MCP géré de portée entreprise, à son chemin système standard : /etc/claude-code/managed-mcp.json sur les hôtes de runner Linux, /Library/Application Support/ClaudeCode/managed-mcp.json sur les hôtes macOS. Utilisez-le pour les parcs verrouillés où seuls les serveurs listés par un administrateur peuvent être chargés. Consultez le contrôle exclusif avec managed-mcp.json pour les règles de priorité. Lorsque ce fichier est présent sur l’hôte du runner, Claude Code ignore les serveurs MCP que le plan de contrôle d’Anthropic fournit à une session, y compris les connecteurs claude.ai, et les nomme dans un avertissement sur la sortie stderr du processus enfant de la session, que le runner enregistre au niveau de log debug. Avant la v2.1.229, ces sessions se terminaient au démarrage avec You cannot dynamically configure MCP servers when an enterprise MCP config is present.
• La clé managedMcpServers dans les paramètres gérés sur l’hôte du runner : elle fournit des serveurs HTTP et SSE sans prendre le contrôle exclusif, de sorte que les serveurs des autres sources sont toujours chargés. Nécessite Claude Code v2.1.259 ou une version ultérieure.
• <repo>/.mcp.json : portée projet. En dehors d’un fil de projet, faites un commit du fichier dans le dépôt ; ses serveurs sont approuvés automatiquement dans les sessions cloud. Dans une session comportant plusieurs dépôts, le fichier d’un seul dépôt au plus est chargé.
• Un fichier --mcp-config passé par votre script wrapper : ajoutez le flag après "$@", comme dans exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --mcp-config /etc/claude/mcp.json. Pour que les serveurs de ce fichier continuent de fonctionner lorsque les serveurs fournis à la session sont mis à jour en cours de session, faites en sorte que votre wrapper transmette l’environnement complet au processus enfant, comme le fait exec. Avant la v2.1.299, les serveurs stdio, HTTP et SSE de ce fichier s’arrêtaient à la première mise à jour de ce type qui ne les nommait pas.

​

Attendre les serveurs MCP avant le premier tour

• Démarrage de la session : avant que la liste des outils ne soit établie pour la première fois, la session attend par défaut jusqu’à 5 secondes un serveur HTTP ou SSE dont l’entrée définit alwaysLoad: true, ou tous les serveurs lorsque vous définissez MCP_CONNECTION_NONBLOCKING=0 dans l’environnement du runner. Sinon, les serveurs HTTP et SSE se connectent en arrière-plan. Pendant cette attente, la session s’initialise plus lentement. MCP_CONNECT_TIMEOUT_MS modifie la valeur par défaut de 5 secondes.
• Premier tour : après l’arrivée du message, le premier tour attend jusqu’à 2 secondes les serveurs stdio qui sont encore en cours de connexion. Pendant cette attente, la première réponse est plus lente. Pour modifier la durée de cette attente, définissez CLAUDE_CODE_MCP_STARTUP_WAIT_MS dans l’environnement du runner. Cela ne modifie pas les serveurs couverts par l’attente. Nécessite Claude Code v2.1.274 ou une version ultérieure.

RUN claude mcp add-json core '{"type":"http","url":"https://mcp.example.com/mcp","alwaysLoad":true}' --scope user

​

Désactiver les outils de session intégrés

{
  "permissions": {
    "deny": [
      "mcp__Claude_Code_Remote",
      "mcp__claude-code-remote",
      "mcp__bf7c680d-5fdc-5ef4-b4a0-abadb619bf0a"
    ]
  }
}

​

Inviter les sessions à envoyer leur travail

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "timeout": 10,
            "command": "\"$CLAUDE_CONFIG_DIR/hooks/stop-hook-nudge.sh\""
          }
        ]
      }
    ]
  }
}

#!/bin/sh
# Implémentation de référence du hook Stop pour les runners auto-hébergés.
#
# Pousse Claude une fois par tour si le répertoire du projet a des changements
# non commités OU des commits non envoyés, afin que le travail ne soit pas perdu
# quand une session inactive est libérée et afin que le bouton "Create PR" sur
# claude.ai/code s'allume.
#
# Niveau runner (pas de changements de dépôt) : déposez ce fichier à
# ~/.claude/hooks/ sur l'hôte runner et fusionnez le bloc de paramètres du
# hook Stop accompagnant dans ~/.claude/settings.json — le runner sème les deux
# dans chaque session.
# Alternative au niveau du dépôt : commitez dans <repo>/.claude/hooks/ et
# changez le chemin de la commande settings.json en $CLAUDE_PROJECT_DIR/.claude/hooks/.
#
# stdin : payload JSON du hook (voir https://code.claude.com/docs/en/hooks)
# stdout : {"decision":"block","reason":"..."} pour pousser, ou rien pour permettre l'arrêt.

# Garde de re-entrée : le harnais définit stop_hook_active=true lors de la
# re-invocation du hook Stop après un blocage. Sortez afin que nous ne poussions
# qu'une fois par tour. Le harnais émet du JSON compact (pas d'espace après les
# deux-points), sur lequel ce motif s'appuie ; utilisez jq si vous avez besoin
# d'une vérification tolérante aux espaces.
in=$(cat)
case "$in" in *'"stop_hook_active":true'*) exit 0 ;; esac

d="$CLAUDE_PROJECT_DIR"

# Renforcement : ce script s'exécute en dehors du sandbox Bash de Claude Code,
# donc ses appels git ignorent certaines fonctionnalités qui peuvent lancer un
# programme nommé dans les paramètres git du checkout. Ils ne les ignorent pas
# toutes, donc ne comptez pas uniquement sur le sandbox.
GIT_OPTIONAL_LOCKS=0
export GIT_OPTIONAL_LOCKS
git() { command git -c core.fsmonitor= -c core.hooksPath=/dev/null "$@"; }

# Pas un dépôt git → rien à pousser.
git -C "$d" rev-parse --git-dir >/dev/null 2>&1 || exit 0

# Pas de distant → « envoyer au distant » est insatisfaisable ; sortez.
[ -z "$(git -C "$d" remote 2>/dev/null)" ] && exit 0

# Changements non commités (en attente, non en attente ou non suivis). Excluez
# .claude/ entièrement — les paramètres semés par l'opérateur et l'état
# d'exécution écrit par la CLI (verrou du planificateur, worktrees, état de
# routine) vivent là et ni l'un ni l'autre n'est du « travail non commité »
# que le modèle doit envoyer.
s=$(git -C "$d" status --porcelain --ignore-submodules=dirty -- . ':(exclude).claude/' 2>/dev/null)
if [ -n "$s" ]; then
  printf '{"decision":"block","reason":"There are uncommitted changes in the repository. Please commit and push these changes to the remote branch."}'
  exit 0
fi

# Commits non envoyés. Comptez les commits sur HEAD non accessibles à partir
# d'aucune ref de suivi distant ou FETCH_HEAD. Cela fonctionne uniformément
# pour :
#   - checkouts init+fetch (runner par défaut : seul FETCH_HEAD existe)
#   - checkouts basés sur clone (origin/* existent)
#   - le runner par défaut : l'enfant démarre sur la branche de résultat de
#     la session, que le runner crée après le checkout
#   - HEAD détaché, quand une configuration personnalisée ignore cette création
#     de branche
# Sans point de référence du tout (jamais récupéré), restez silencieux plutôt
# que de produire un faux positif sur un tour en lecture seule.
base=""
git -C "$d" rev-parse --verify -q FETCH_HEAD >/dev/null && base="FETCH_HEAD"
if [ -z "$base" ] && [ -z "$(git -C "$d" for-each-ref --count=1 refs/remotes/origin 2>/dev/null)" ]; then
  exit 0
fi
# shellcheck disable=SC2086  # $base est soit "" soit "FETCH_HEAD", division de mot intentionnelle
unpushed=$(git -C "$d" rev-list HEAD --not $base --remotes=origin --count 2>/dev/null) || unpushed=0
if [ "$unpushed" -gt 0 ]; then
  branch=$(git -C "$d" symbolic-ref --short -q HEAD)
  if [ -n "$branch" ]; then
    # $branch est influencée par l'attaquant — git-check-ref-format(1) permet
    # les `"` dans les noms de ref. `\` est interdit (règle 10) mais échappé
    # de toute façon comme défense en profondeur bon marché.
    # Échappez les métacaractères JSON avant d'interpoler dans le payload
    # construit à la main afin qu'une branche comme x","continue":false ne
    # puisse pas injecter de clés dans le JSON de sortie du hook que le harnais
    # analyse. $unpushed est sûr — la garde -gt ci-dessus rejette tout ce qui
    # n'est pas un entier simple.
    branch_esc=$(printf '%s' "$branch" | sed 's/\\/\\\\/g; s/"/\\"/g')
    printf '{"decision":"block","reason":"There are %s unpushed commit(s) on branch '\''%s'\''. Please push these changes to the remote repository."}' "$unpushed" "$branch_esc"
  else
    printf '{"decision":"block","reason":"There are %s unpushed commit(s) on a detached HEAD. Please create a branch and push it to the remote repository."}' "$unpushed"
  fi
  exit 0
fi

exit 0

• Une identité git : définissez user.name et user.email dans votre image de runner, ou démarrez le runner avec --configure-git
• Des identifiants d’envoi : utilisez git géré par Anthropic, ou fournissez des identifiants comme le décrit Intégrer la configuration git dans votre image
• Pour les sessions reprises : définissez --push-outcome-on-release sur chaque runner de l’environnement. Une session reprise démarre alors à partir des commits que Claude a envoyés sur la branche de la session. Pour les limites de ce flag, consultez Les sessions reprises perdent le travail non envoyé.

​

Sous-modules et hook Stop

• Un nouveau commit dans un sous-module : Claude est sollicité jusqu’à ce que le dépôt parent l’enregistre, même si .gitmodules définit ignore = all pour ce sous-module
• Des fichiers non commités dans un sous-module : Claude n’est pas sollicité, ce travail reste donc uniquement sur le disque du runner
• Des commits non envoyés dans un sous-module : le hook Stop ne vérifie pas s’ils ont été envoyés, le parent peut donc pointer vers un commit que personne d’autre ne peut récupérer

​

Remplacer une version antérieure du script du hook Stop

• Quand : si vos sessions s’exécutent avec le sandbox Bash activé, remplacez-la dès maintenant. Sinon, remplacez-la lors de votre prochain build d’image ou redémarrage du runner.
• Ce qui change : les fichiers non commités dans un sous-module ne sollicitent plus Claude. Un nouveau commit dans un sous-module que .gitmodules marque ignore = all le sollicite désormais.

​

Permissions et approbation d’outils

#!/bin/bash
exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --permission-mode auto

​

Comment la configuration de chaque session est assemblée

• Paramètres du projet : en dehors d’un fil de projet, un .claude/settings.json commité dans le dépôt se superpose à la ligne de base au niveau utilisateur. Dans une session avec plusieurs dépôts, le fichier d’au plus un dépôt prend effet.
• Paramètres gérés : les sessions lisent managed-settings.json à partir du chemin système standard dans votre image runner. Pour savoir si ses clés s’appliquent aux côtés des paramètres gérés par le serveur, voir comment Claude Code combine les sources gérées.

• Où ils atterrissent : le runner écrit chaque script de hook fourni dans un sous-répertoire réservé hooks/.ccr-launcher/ du répertoire de configuration de la session et enregistre les scripts dans un fichier de paramètres séparé qu’il transmet à la session avec --settings, laissant le settings.json semé et vos propres scripts à hooks/<name> intacts. Le runner recrée le sous-répertoire réservé pour chaque session et ne sème pas le contenu de l’hôte à ~/.claude/hooks/.ccr-launcher/ dans les sessions.
• Qui les crée : le plan de contrôle remplit les scripts à partir de constantes fixes dans son propre déploiement, jamais à partir d’entrées par session ou tierces.
• Ce qui les gouverne toujours : les hooks livrés via --settings entrent dans la configuration de hook fusionnée ordinaire, pas le niveau géré, donc vos paramètres gérés s’appliquent toujours. disableAllHooks les désactive, et ils ne font pas partie des catégories que allowManagedHooksOnly garde chargées.

​

Arrêter les sessions qui ne parviennent pas à récupérer les paramètres gérés par le serveur

• Sessions de canal Claude Tag : n’ajoutez pas la clé sur les runners d’un environnement vers lequel un Owner achemine des canaux Claude Tag. L’API d’Anthropic refuse la requête de paramètres gérés par le serveur de ces sessions, donc avec la clé définie, elles ne démarrent pas. Placez leurs règles dans le managed-settings.json de l’image runner, qu’elles lisent toujours. Pour utiliser la clé pour vos autres sessions, exécutez-les dans un environnement séparé.
• Bedrock ou Agent Platform : les sessions sur ces fournisseurs ne récupèrent pas les paramètres gérés par le serveur, elles démarrent donc que vous définissiez la clé ou non. Appliquez plutôt vos règles à partir du même managed-settings.json.

{
  "forceRemoteSettingsRefresh": true
}

​

Paramètres de dépôt dans les sessions avec plusieurs dépôts

• --capacity 1, la valeur par défaut, avec le checkout intégré : la session démarre dans le premier dépôt de sa liste de dépôts. Le .claude/settings.json de ce dépôt prend effet comme paramètres du projet et son .mcp.json se charge, contrairement à ceux des autres dépôts.
• Un --capacity supérieur à un, ou un hook checkout : la session démarre dans un répertoire propre à la session qui contient les checkouts. Aucun .claude/settings.json de dépôt ne prend effet comme paramètres du projet, aucun .mcp.json de dépôt ne se charge, et $CLAUDE_PROJECT_DIR dans une commande de hook correspond à ce répertoire, et non à un checkout.

​

Règles de permission validées dans le référentiel

​

Prochaines étapes

• Référence : chaque flag CLI, variable d’environnement et métrique
• Vérifier l’identité de la session : valider le token de session à partir de services en dehors du runner