Personalizzare le sessioni negli ambienti self-hosted

​

Script wrapper

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

​

Assegnare un valore predefinito alle variabili che possono non essere impostate

​

Mettere tra virgolette gli argomenti e le variabili che il tuo script espande

• Argomenti: passali come "$@"
• Variabili: metti ciascuna tra virgolette, come in "${CLAUDE_CODE_REMOTE_SLACK_THREAD_URL:-}". Il link del thread Slack, ad esempio, può contenere ? e &.
• Stringhe di eval e sh -c: non sostituire un valore in una stringa eseguita da eval o sh -c, nemmeno tra virgolette. Fai invece in modo che quella stringa faccia riferimento alla variabile.

​

Mantenere stdin e il descrittore di file 3 collegati

exec 9<&0   # the runner uses 3, and from v2.1.309 reserves 4 and 5
"$CLAUDE_RUNNER_CLAUDE_BIN" "$@" <&9 9<&- &
CHILD=$!
trap 'teardown' EXIT
wait "$CHILD"

• Descrittore di file 3: trasporta i segnali di attività del figlio al runner. Non chiuderlo né riutilizzarlo nel wrapper.
• Descrittori di file 4 e 5: i runner su Claude Code v2.1.309 o successivo li riservano al figlio. Non chiuderli né riutilizzarli nel wrapper. Se il tuo wrapper usa uno dei due, ad esempio per salvare stdin, sposta quell’uso su un descrittore da 6 a 9, che anche le versioni precedenti lasciano liberi.
• stderr: quando il wrapper o il figlio esce con codice diverso da zero, il runner pubblica le ultime righe dello stderr nella sessione e le stampa nel proprio log. L’utente della sessione vede quelle righe, quindi non stampare segreti sullo stderr e rimuovi set -x prima di distribuire il wrapper. Se reindirizzi lo stderr, le sessioni vengono comunque eseguite, ma il runner segnala un errore con il solo codice di uscita.

​

Passare i flag del prompt di sistema

• Passali così come sono: termina il wrapper con exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@", che inoltra i flag dei file insieme a ogni altro argomento. Non eliminarli né riscriverli. Se una sessione perde un flag del file di prompt, viene eseguita senza le istruzioni che il piano di controllo ha inviato per essa.
• Su un runner alla v2.1.281 o successiva, un flag di file che aggiungi sostituisce quello del server, non vi si aggiunge mai: ogni flag del file di prompt accetta un solo valore e Claude Code mantiene l’ultima occorrenza, quindi se aggiungi --append-system-prompt-file <path> dopo "$@", il contenuto del tuo file sostituisce le istruzioni aggiuntive del server. Per aggiungere istruzioni oltre a quelle del server, inseriscile nel CLAUDE.md dell’immagine del runner, che il runner inserisce nella configurazione a livello utente di ogni sessione.

​

Correggere Argument list too long all’avvio della sessione

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)"

​

Provisioning di credenziali limitate al creatore della sessione

#!/bin/bash
# Key on the stable Anthropic user ID and require a human creator.
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" "$@"

​

Hook del ciclo di vita

​

checkout

​

Ottenere le credenziali git nell’hook

• Credenziale di clone per sessione: verifica CLAUDE_CODE_SESSION_ACCESS_TOKEN con una libreria JWT standard rispetto all’endpoint JWKS sotto CLAUDE_RUNNER_API_BASE_URL, come descritto in Verify the token from your service. Poi fai in modo che il tuo servizio di credenziali emetta una credenziale di clone di breve durata per l’identità nel claim act del token. Associa quella credenziale a act.sub e non richiedere act.email.
• Autenticazione git dell’host: usa qualsiasi autenticazione git di cui l’host dispone già, come un agente SSH, un credential helper o .netrc.

​

Quando l’hook fallisce

• Un repository a cui la sessione spinge i risultati: il runner fa fallire la sessione e, in caso di uscita diversa da zero, mostra all’utente la coda dello stderr dello script. Scrivi il motivo nello stderr come un’unica riga breve, scrivilo per ultimo e poi esci con un codice diverso da zero. Non stampare segreti nello stderr e rimuovi set -x prima di distribuire l’hook. Se il messaggio couldn't find remote ref di git compare all’incirca negli ultimi 4 KB dello stderr dell’hook, il runner segnala invece un branch eliminato. Il messaggio di errore della sessione indica allora che il branch non esiste più sul remote e chiede all’utente di ripristinarlo. Se quel branch esiste, consulta Una sessione fallisce con no longer exists on the remote o couldn't find remote ref.
• Un repository che la sessione legge soltanto, come un repository aggiunto a una sessione in esecuzione: il runner lo salta e continua con i repository rimanenti. Il runner pubblica un passaggio Skipped nella sessione e rimuove ciò che l’hook ha lasciato nel percorso di checkout. Quando il passaggio Skipped menziona l’hook di checkout, trovi il dettaglio del fallimento nella riga [runner:warn] checkout hook failed del log del runner. Quando il passaggio indica che un ref di origine no longer exists on remote, consulta Una sessione fallisce con no longer exists on the remote o couldn't find remote ref. Se saltarlo lascia la sessione senza alcun repository, il runner fa comunque fallire la sessione.

​

post-session

• completed: la sessione è terminata in modo pulito. Il processo Claude Code è uscito normalmente, oppure è uscito da solo dopo che la sessione è stata archiviata o eliminata.
• failed: il processo Claude Code è andato in crash, oppure la configurazione è fallita dopo l’avvio.
• interrupted: il runner ha interrotto la sessione, in uno di questi casi:
  • Il runner ha rilasciato la sessione per liberare lo slot.
  • La sessione è andata in timeout all’avvio.
  • Il server ha spostato la sessione da questo runner.
  • Il polling del runner ha rilevato un’archiviazione o un’eliminazione prima che il processo uscisse.
  • Il runner era in fase di drain.
  • La sessione ha superato il limite --kill-session-after-min.
• abandoned: riservato per una sessione che un altro runner ha rivendicato. L’hook attualmente non si attiva in quel caso.

#!/usr/bin/env bash
set -u
export GIT_ALLOW_PROTOCOL=${GIT_ALLOW_PROTOCOL:-https:http:ssh}
IFS=':'
# -c overrides beat repo-local settings, blocking session-written fsmonitor,
# hook-path, and gpg-program config from executing code with the hook's
# privileges. -c commit.gpgsign=false also leaves these rescue commits
# unsigned under --configure-git.
# Repo-local credential.helper and pushurl still apply, and on a runner
# before v2.1.280 so does core.sshCommand; see the note below the script
# before you give this push a credential.
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

​

Hook timing quando il runner rilascia una sessione

• Inattivo dopo un turno, o timeout all’avvio: il runner ferma il figlio ed esegue questo hook fino al completamento. Solo allora rilascia la sessione. Un messaggio utente inviato mentre l’hook viene eseguito non può riprendere la sessione su un altro runner prima che l’hook finisca.
• In attesa che l’utente risponda a un prompt, come un prompt di autorizzazione: il runner rilascia la sessione per primo, quindi esegue questo hook. Un messaggio utente inviato mentre l’hook viene eseguito può riprendere la sessione su un altro runner prima che l’hook finisca.

​

Configurazione git all’interno degli hook del ciclo di vita

• Hook git: a meno che tu non fornisca un valore, core.hooksPath è /dev/null, quindi git salta gli hook nella .git/hooks di un repository e in qualsiasi directory di hook indicata da ~/.gitconfig. Per fornirne uno, esporta core.hooksPath come coppia GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n nell’ambiente del runner. Il runner legge anche core.hooksPath dalla configurazione git di sistema, e la usa solo quando l’utente del runner non può scrivere in quel file, nella directory indicata o nei file di hook che contiene. Quando il runner ignora un valore, una riga [runner:warn] all’avvio indica il valore e il motivo.
• Monitor del file system: core.fsmonitor è vuoto, quindi il git nel tuo hook non esegue un programma di monitoraggio indicato da un file di configurazione.
• Protocolli remoti: GIT_ALLOW_PROTOCOL è https:http:ssh. Un clone, un fetch o un push che usa un percorso locale, un URL file:// o un URL git:// fallisce con fatal: transport 'file' not allowed o fatal: transport 'git' not allowed.
• Comando SSH e richiesta di credenziali: il git nel tuo hook ignora core.sshCommand e core.askPass dai file di configurazione. Per usare il tuo comando SSH, imposta GIT_SSH_COMMAND nell’ambiente del runner. Per usare un programma di richiesta delle credenziali, imposta lì GIT_ASKPASS. Le sessioni ereditano l’ambiente del runner, quindi entrambe le variabili raggiungono anche il git della sessione. Non inserire una credenziale in nessuna delle due.
• Programmi gpg: gpg.program, gpg.openpgp.program, gpg.x509.program e gpg.ssh.program sono percorsi impostati dal runner, mai valori provenienti da un file di configurazione.
• Firma dei commit: con --configure-git, i commit che esegui da un hook vengono firmati come la sessione. Senza il flag, commit.gpgsign e tag.gpgsign sono false.

• Coppie di configurazione: una coppia GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n che esporti nell’ambiente del runner sostituisce il valore del runner per la stessa chiave. Numera le tue coppie a partire da 0 e imposta GIT_CONFIG_COUNT sul loro numero. Quando manca l’ultima coppia indicata dal conteggio, il runner ignora tutte le tue coppie e registra una riga [runner:warn] all’avvio.
• Variabili d’ambiente git: il runner lascia GIT_ALLOW_PROTOCOL, GIT_SSH_COMMAND e GIT_ASKPASS come le imposti nel suo ambiente.
• Opzioni git -c: un’opzione git -c all’interno dell’hook sovrascrive una coppia GIT_CONFIG_KEY_n, sia quella del runner sia la tua. Non modifica GIT_ALLOW_PROTOCOL, GIT_SSH_COMMAND o GIT_ASKPASS, che git legge prima di qualsiasi configurazione.

​

command

​

Runner on demand

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

​

L’hook spawn-runner

• Avvialo con l’ordine di lavoro: fai puntare --environment-secret-file a un file contenente il JWT dell’ordine di lavoro, oppure imposta SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET sul valore del JWT.
• Copia il JWT prima che l’hook termini: l’orchestratore elimina il file dell’ordine di lavoro dopo l’uscita dell’hook, quindi copia il JWT nel carico di lavoro che invii, ad esempio in un Secret Kubernetes sul Job avviato, anziché passare il percorso del file.
• Usa --capacity 1 sui runner avviati: un ordine di lavoro legato a una sessione registra esattamente un runner legato a quella sessione, quindi una capacità maggiore aggiunge slot che non ricevono mai lavoro, e il runner registra un avviso all’avvio.
• Gli ordini di lavoro di pre-riscaldamento si registrano senza vincoli: il runner in standby non è legato a una sessione e rivendica il lavoro in coda come un runner di una flotta fissa.

1. Sii idempotente su CLAUDE_RUNNER_ORDER_ID. La riconsegna della stessa richiesta deve avviare al massimo un runner. Ricava un nome di risorsa deterministico dall’ID dell’ordine e lascia che la tua piattaforma rifiuti il duplicato. Non usare invece CLAUDE_RUNNER_SESSION_ID come chiave. Ogni nuova richiesta per una sessione riporta lo stesso ID di sessione con un nuovo ID dell’ordine. Un carico di lavoro denominato o deduplicato in base all’ID di sessione non viene creato di nuovo finché esiste il primo.
2. Non riprovare il carico di lavoro. Un ID dell’ordine significa al massimo un carico di lavoro creato. Se il runner non si registra mai, Anthropic invia una nuova richiesta con un nuovo ID dell’ordine dopo --expected-spawn-seconds.
3. Usa il contratto dei codici di uscita. Esci con lo stato corrispondente all’esito:
   • Uscita 0: inviato.
   • Uscita 1, oppure ancora in esecuzione allo scadere di --hook-timeout: errore per cui è possibile riprovare. La sessione attende con backoff e viene riproposta. Dopo 10 richieste non riuscite consecutive, viene bloccata come avviene dopo un’uscita 2 o superiore.
   • Uscita 2 o superiore: errore per cui non è possibile riprovare. Alla sessione viene impedito un nuovo spawn finché un utente non le invia un nuovo messaggio o un Owner non seleziona Retry su di essa nella scheda Activity dell’ambiente.
   Mentre una sessione è in backoff, nella scheda Activity appare come Queued senza errori di spawn, quindi leggi l’output dell’hook nel log dell’orchestratore. Una volta bloccata, la sessione appare come Failed. Espandila per leggere l’errore di spawn, ricavato dagli ultimi 512 caratteri dello stderr dell’hook. Scrivi su stderr un errore utile per intervenire, e nessun segreto. In un hook shell, mantieni ripetibili gli errori transitori. Una richiesta di pre-riscaldamento non ha una sessione da far fallire: l’orchestratore registra un’uscita diversa da zero solo localmente, e il server richiede di nuovo lo spawn dopo la scadenza del lease --expected-spawn-seconds.
4. Imposta --expected-spawn-seconds almeno al tuo p99 del tempo che intercorre tra la richiesta di spawn e la registrazione del runner. Misura a partire dal momento in cui l’orchestratore riceve la richiesta di spawn, e includi sia l’eventuale attesa di capacità sulla tua piattaforma sia il tempo di avvio. Questo valore è il lease lato server, e l’ordine di lavoro scade insieme a esso, quindi un runner il cui carico di lavoro impiega più tempo non può registrarsi. Tutte le repliche dell’orchestratore devono usare lo stesso valore.

​

Correggi le sessioni riaperte che restano Queued o appaiono come Failed

name="runner-${CLAUDE_RUNNER_SESSION_ID}"

1. Alla prima richiesta di spawn della sessione, l’hook crea un carico di lavoro con quel nome e un runner si avvia
2. Il runner termina, ad esempio dopo --release-idle-session-min, e in seguito l’utente riapre la sessione
3. La successiva richiesta di spawn della sessione riporta lo stesso ID di sessione e un nuovo ID dell’ordine, quindi l’hook costruisce lo stesso nome
4. Se la tua piattaforma ha ancora il carico di lavoro della prima richiesta, perché nulla lo ha rimosso quando il suo runner è terminato, l’hook non crea alcun nuovo carico di lavoro e nessun runner si avvia
5. Ogni successiva richiesta di spawn per la sessione termina allo stesso modo

name="runner-${CLAUDE_RUNNER_ORDER_ID}"

• Queued: la sessione riceve autonomamente la sua prossima richiesta di spawn
• Failed: seleziona Retry su di essa come Owner, oppure chiedi al suo utente di inviarle un nuovo messaggio

​

Fai terminare i runner on demand quando sono inattivi

​

Invia l’output di un processo in background a un file

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

• Circa un secondo dopo l’uscita dell’hook, l’orchestratore registra exited, but a process it started still has the hook's stdout or stderr open. Da quella riga in poi, registra fino a 64 KB aggiuntivi di quell’output sotto [runner:hook:spawn-runner:after-exit jti=<order id>] e poi scarta il resto.
• Una volta terminato l’orchestratore, le scritture del processo su quei flussi falliscono.

• Scheda Activity, nell’errore di spawn di una sessione non riuscita: spawn-runner hook timed out after 60000ms, oppure le ultime righe sullo stderr dell’hook.
• Log dell’orchestratore: timed out after 60000ms, sending SIGTERM to process tree.

​

Termina l’hook senza attendere il runner

• Per verificare che sia il timeout ad arrestare i tuoi runner: cerca nel log dell’orchestratore timed out after 60000ms, sending SIGTERM to process tree a ogni richiesta di spawn. Il valore 60000 è il tuo --hook-timeout in millisecondi.
• Per risolvere il problema: fai in modo che l’hook invii il runner alla tua piattaforma ed esca con 0. Se invece aumenti --hook-timeout, il runner si arresta solo più tardi.

​

Mantieni ripetibili gli errori transitori in 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 o superiore isolato: con il trap impostato, diventa un’uscita 1. Per un errore che nessun nuovo tentativo può risolvere, chiama invece permanent con il motivo, ad esempio permanent "namespace claude-runners does not exist". Chiamalo nella shell principale, non all’interno di $( ), ( ) o di una pipe.
• exec: non iniziare l’ultimo comando dell’hook con exec, perché exec sostituisce la shell e il trap non viene eseguito.
• Secondo trap EXIT: un secondo trap ... EXIT sostituisce il primo, quindi unisci i due in un unico trap. Inserisci i tuoi comandi di pulizia subito dopo rc=$?; e termina ciascuno con || true;. In questo modo la pulizia viene eseguita sia in caso di errore sia in caso di successo, e un comando di pulizia che fallisce non imposta lo stato di uscita dell’hook. Questo trap unificato mostra la struttura, con your-cleanup-command al posto del tuo comando:
  trap 'rc=$?; your-cleanup-command || true; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT
  
• Comandi a cui è consentito fallire: se prima l’hook non usava set -e, ora si ferma al primo comando che restituisce un valore diverso da zero, come una ricerca che non trova nulla. Se l’hook agisce in base al risultato, rendi quel comando la condizione di un if. Se ignora il risultato, fai seguire al comando || true.
• Il comando che invia il carico di lavoro: non farlo seguire da || true. Con || true, l’hook esce con 0 anche quando la tua piattaforma rifiuta l’invio, ad esempio per superamento della quota, e la sessione attende un runner che non è mai stato avviato. Assegna al carico di lavoro un nome basato su CLAUDE_RUNNER_ORDER_ID, come indica la prima regola dell’hook. Una risposta che indica che la risorsa esiste già è quindi una riconsegna della stessa richiesta, perciò tratta solo quella risposta come un successo. Per qualsiasi altra risposta, stampala su stderr ed esci con 1, oppure chiama permanent se nessun nuovo tentativo può risolvere l’errore. Questo esempio fa proprio questo per kubectl create, con un job.yaml che contiene solo il carico di lavoro:
  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
  
  Il log dell’orchestratore mostra quindi quel messaggio. Se l’hook crea altri oggetti, assegna a ciascuno un nome basato sull’ID dell’ordine, usa un comando dedicato per ciascuno e tratta allo stesso modo come un successo la risposta che indica che esiste già. Per un oggetto che contiene un segreto, stampa un messaggio fisso al posto dell’output del comando.

​

Inviare le richieste al modello a Bedrock o ad 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)'

​

Cosa cambia rispetto alle sessioni sull’API di Anthropic

• Policy da claude.ai: le impostazioni gestite dal server non raggiungono queste sessioni. Nemmeno le policy dell’organizzazione che un Owner imposta nelle impostazioni di amministrazione di Claude Code le raggiungono, quindi Claude Code non le applica all’interno della sessione. Inserisci le regole su cui fai affidamento nel file delle impostazioni gestite dell’immagine del runner.
• Skill dell’account: queste sessioni non scaricano le skill abilitate per l’account claude.ai di una persona. Consulta Come viene assemblata la configurazione di ogni sessione.
• File: i file che le persone allegano a una sessione in claude.ai o nell’app mobile o desktop non la raggiungono, e Claude non può inviare file indietro con lo strumento SendUserFile. Inserisci invece i file di input nel repository o sul runner.
• Selezione del modello: il control plane di Anthropic invia il modello di ogni sessione e, quando una sessione viene avviata senza un modello, Claude Code usa quello predefinito per il provider. Non puoi scegliere il modello con ANTHROPIC_MODEL o ANTHROPIC_DEFAULT_MODEL nell’ambiente del runner, ma puoi fissare a cosa si risolve un alias:
  • ANTHROPIC_MODEL e ANTHROPIC_DEFAULT_MODEL: il runner le rimuove dall’ambiente che passa alle sessioni, anche se gli esempi nelle pagine dei provider impostano ANTHROPIC_MODEL.
  • Variabili per famiglia per fissare i modelli: le variabili descritte in Fissare le versioni dei modelli per Amazon Bedrock e per Agent Platform raggiungono invece le sessioni. Determinano a cosa si risolve un alias come opus, non a cosa si risolve un ID completo del modello.
• Modelli non serviti dal tuo account: una sessione può fallire su un messaggio con un errore che indica il modello. Abilita i modelli che i tuoi sviluppatori possono scegliere, il modello in background descritto in Fissare le versioni dei modelli e il modello del classificatore usato dalla modalità auto. Su Amazon Bedrock, consenti ciascuno di essi nella tua policy.
• Ricerca web e modalità veloce: la ricerca web non è disponibile su Amazon Bedrock e la modalità veloce non è disponibile su nessuno dei due provider. Per altre funzionalità che variano in base al provider, consulta Funzionalità della CLI che variano in base al provider.

​

Server 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

• Il file MCP gestito con ambito enterprise nel suo percorso di sistema standard: /etc/claude-code/managed-mcp.json sugli host runner Linux, /Library/Application Support/ClaudeCode/managed-mcp.json sugli host macOS. Usalo per flotte bloccate in cui possono essere caricati solo i server elencati dall’amministratore. Consulta controllo esclusivo con managed-mcp.json per le regole di precedenza. Quando questo file si trova sull’host del runner, Claude Code ignora i server MCP che il control plane di Anthropic fornisce a una sessione, inclusi i connettori di claude.ai, e li nomina in un avviso sullo stderr del processo figlio della sessione, che il runner registra al livello di log debug. Prima della v2.1.229, quelle sessioni terminavano all’avvio con You cannot dynamically configure MCP servers when an enterprise MCP config is present.
• La chiave managedMcpServers nelle impostazioni gestite sull’host del runner: fornisce server HTTP e SSE senza assumere il controllo esclusivo, quindi i server delle altre fonti vengono comunque caricati. Richiede Claude Code v2.1.259 o successiva.
• <repo>/.mcp.json: ambito di progetto. Al di fuori di un thread di progetto, esegui il commit del file nel repository e i suoi server vengono approvati automaticamente nelle sessioni cloud. In una sessione con più repository, viene caricato al massimo il file di un solo repository.
• Un file --mcp-config passato dal tuo script wrapper: aggiungi il flag dopo "$@", come in exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --mcp-config /etc/claude/mcp.json. Per mantenere in esecuzione i server di quel file quando i server forniti alla sessione vengono aggiornati a sessione in corso, fai in modo che il tuo wrapper passi l’ambiente completo al processo figlio, come fa exec. Prima della v2.1.299, i server stdio, HTTP e SSE in quel file si arrestavano al primo aggiornamento di questo tipo che non li nominava.

​

Attendere i server MCP prima del primo turno

• Avvio della sessione: prima che l’elenco degli strumenti venga acquisito per la prima volta, la sessione attende per impostazione predefinita fino a 5 secondi un server HTTP o SSE la cui voce imposta alwaysLoad: true, oppure tutti i server quando imposti MCP_CONNECTION_NONBLOCKING=0 nell’ambiente del runner. Altrimenti i server HTTP e SSE si connettono in background. Mentre la sessione attende qui, l’inizializzazione è più lenta. MCP_CONNECT_TIMEOUT_MS modifica il valore predefinito di 5 secondi.
• Primo turno: dopo l’arrivo del messaggio, il primo turno attende fino a 2 secondi i server stdio che si stanno ancora connettendo. Mentre la sessione attende qui, la prima risposta è più lenta. Per modificare la durata di questa attesa, imposta CLAUDE_CODE_MCP_STARTUP_WAIT_MS nell’ambiente del runner. Non modifica quali server sono coperti dall’attesa. Richiede Claude Code v2.1.274 o successiva.

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

​

Disattivare gli strumenti di sessione integrati

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

​

Prompt delle sessioni per spingere il loro lavoro

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

#!/bin/sh
# Implementazione di riferimento dello stop-hook per runner self-hosted.
#
# Sollecita Claude una volta per turno se la directory del progetto ha modifiche
# senza commit O commit senza push, in modo che il lavoro non vada perso quando
# una sessione inattiva viene rilasciata e in modo che il pulsante "Create PR" su
# claude.ai/code si attivi.
#
# Livello runner (nessuna modifica al repository): metti questo file in ~/.claude/hooks/
# sull'host del runner e fai il merge del blocco di impostazioni dello Stop-hook associato
# in ~/.claude/settings.json — il runner inserisce entrambi in ogni sessione.
# Alternativa a livello di repository: fai il commit in <repo>/.claude/hooks/ e cambia il
# percorso del comando in settings.json in $CLAUDE_PROJECT_DIR/.claude/hooks/.
#
# stdin: payload JSON dell'hook (consulta https://code.claude.com/docs/en/hooks)
# stdout: {"decision":"block","reason":"..."} per sollecitare, o nulla per consentire lo stop.

# Protezione dal rientro: l'harness imposta stop_hook_active=true quando reinvoca
# lo Stop hook dopo un blocco. Esci in modo da sollecitare solo una volta per turno.
# L'harness emette JSON compatto (nessuno spazio dopo i due punti), su cui questo
# pattern si basa; usa jq se hai bisogno di un controllo tollerante agli spazi bianchi.
in=$(cat)
case "$in" in *'"stop_hook_active":true'*) exit 0 ;; esac

d="$CLAUDE_PROJECT_DIR"

# Hardening: questo script viene eseguito fuori dalla sandbox Bash di Claude Code, quindi
# le sue chiamate git saltano alcune funzionalità che possono avviare un programma indicato
# nelle impostazioni git del checkout. Non le saltano tutte, quindi non fare affidamento solo sulla sandbox.
GIT_OPTIONAL_LOCKS=0
export GIT_OPTIONAL_LOCKS
git() { command git -c core.fsmonitor= -c core.hooksPath=/dev/null "$@"; }

# Non è un repository git → nulla da sollecitare.
git -C "$d" rev-parse --git-dir >/dev/null 2>&1 || exit 0

# Nessun remoto → "fare il push sul remoto" è impossibile; esci.
[ -z "$(git -C "$d" remote 2>/dev/null)" ] && exit 0

# Modifiche senza commit (staged, unstaged o untracked). Escludi .claude/
# interamente — le impostazioni inserite dall'operatore e lo stato di runtime scritto dalla CLI
# (lock dello scheduler, worktree, stato della routine) si trovano lì e nessuno dei due è
# "lavoro senza commit" di cui il modello deve fare il push.
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

# Commit senza push. Conta i commit su HEAD non raggiungibili da alcun
# ref di tracciamento remoto o FETCH_HEAD. Questo funziona uniformemente per:
#   - checkout init+fetch (predefinito del runner: esiste solo FETCH_HEAD)
#   - checkout basati su clone (esistono origin/*)
#   - il predefinito del runner: il processo figlio parte dal branch di risultato
#     della sessione, che il runner crea dopo il checkout
#   - HEAD staccato, quando una configurazione personalizzata salta la creazione di quel branch
# Senza alcun punto di riferimento (mai eseguito il fetch), rimani silenzioso piuttosto che
# dare un falso positivo su un turno di sola lettura.
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 è "" o "FETCH_HEAD", word-split intenzionale
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 è influenzabile da un attaccante — git-check-ref-format(1) consente `"`
    # nei nomi dei ref. `\` è vietato (regola 10) ma viene comunque sottoposto a escape
    # come difesa in profondità a basso costo.
    # Applica l'escape ai metacaratteri JSON prima di interpolarli nel payload costruito a mano,
    # in modo che un branch come x","continue":false non possa iniettare chiavi nel
    # JSON di output dell'hook che l'harness analizza. $unpushed è sicuro — il
    # controllo -gt sopra rifiuta qualsiasi cosa che non sia un semplice intero.
    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

• Un’identità git: imposta user.name e user.email nell’immagine del runner, oppure avvia il runner con --configure-git
• Credenziali per il push: usa git gestito da Anthropic, oppure fornisci le credenziali come descritto in Includere la configurazione git nell’immagine
• Per le sessioni riprese: imposta --push-outcome-on-release su ogni runner dell’ambiente. Una sessione ripresa parte quindi dai commit di cui Claude ha fatto il push sul branch della sessione. Per i limiti del flag, consulta Le sessioni riprese perdono il lavoro senza push.

​

Submodule e lo Stop hook

• Un nuovo commit in un submodule: Claude viene sollecitato finché il repository padre non lo registra, anche se .gitmodules imposta ignore = all per quel submodule
• File senza commit in un submodule: Claude non viene sollecitato, quindi quel lavoro rimane solo sul disco del runner
• Commit senza push in un submodule: lo Stop hook non controlla se è stato fatto il push, quindi il padre può puntare a un commit che nessun altro può recuperare

​

Sostituire una copia precedente dello script dello Stop hook

• Quando: se le tue sessioni vengono eseguite con la sandbox Bash attiva, sostituiscila subito. Altrimenti, sostituiscila alla prossima build dell’immagine o al prossimo riavvio del runner.
• Cosa cambia: i file senza commit in un submodule non sollecitano più Claude. Un nuovo commit in un submodule che .gitmodules contrassegna con ignore = all ora invece lo fa.

​

Permessi e approvazione degli strumenti

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

​

Come viene assemblata la configurazione di ogni sessione

• Impostazioni di progetto: al di fuori di un thread di un progetto, un file .claude/settings.json di cui è stato fatto il commit nel repository si sovrappone alla base a livello utente. In una sessione con più repository, ha effetto al massimo il file di un solo repository.
• Impostazioni gestite: le sessioni leggono managed-settings.json dal percorso di sistema standard nella tua immagine del runner. Per sapere se le sue chiavi si applicano insieme alle impostazioni gestite dal server, consulta come Claude Code combina le fonti gestite.

• Dove vengono collocati: il runner scrive ogni script hook fornito in una sottodirectory riservata hooks/.ccr-launcher/ della directory di configurazione della sessione e registra gli script in un file di impostazioni separato che passa alla sessione con --settings, lasciando intatti il settings.json popolato e i tuoi script in hooks/<name>. Il runner ricrea la sottodirectory riservata per ogni sessione e non copia nelle sessioni il contenuto dell’host presente in ~/.claude/hooks/.ccr-launcher/.
• Chi li crea: il control plane popola gli script a partire da costanti fisse nel proprio deploy, mai da input per sessione o di terze parti.
• Cosa continua a regolarli: gli hook forniti tramite --settings entrano nella normale configurazione degli hook unita, non nel livello gestito, quindi le tue impostazioni gestite continuano ad applicarsi. disableAllHooks li disabilita, e non rientrano tra le categorie che allowManagedHooksOnly mantiene caricate.

​

Bloccare le sessioni che non riescono a recuperare le impostazioni gestite dal server

• Sessioni di canali Claude Tag: ometti la chiave sui runner di un ambiente verso cui un Owner instrada i canali Claude Tag. L’API di Anthropic rifiuta la richiesta di impostazioni gestite dal server di queste sessioni, quindi con la chiave impostata non riescono ad avviarsi. Inserisci le loro regole nel managed-settings.json dell’immagine del runner, che continuano a leggere. Per usare la chiave per le altre sessioni, eseguile in un ambiente separato.
• Bedrock o Agent Platform: le sessioni su questi provider non recuperano le impostazioni gestite dal server, quindi si avviano indipendentemente dal fatto che tu imposti o meno la chiave. Applica invece le tue regole dallo stesso managed-settings.json.

{
  "forceRemoteSettingsRefresh": true
}

​

Impostazioni del repository nelle sessioni con più repository

• --capacity 1, il valore predefinito, con il checkout integrato: la sessione si avvia nel primo repository del suo elenco di repository. Il .claude/settings.json di quel repository ha effetto come impostazioni di progetto e il suo .mcp.json viene caricato, mentre quelli degli altri repository no.
• Un --capacity maggiore di uno, oppure un hook checkout: la sessione si avvia in una directory per sessione che contiene i checkout. Nessun .claude/settings.json di alcun repository ha effetto come impostazioni di progetto, nessun .mcp.json viene caricato e $CLAUDE_PROJECT_DIR in un comando hook corrisponde a quella directory, non a un checkout.

​

Regole di permesso di cui è stato fatto il commit nel repository

​

Cosa c’è dopo

• Reference: ogni flag CLI, variabile di ambiente e metrica
• Verify session identity: convalidare il token della sessione da servizi al di fuori del runner