Personalizar sessões em ambientes auto-hospedados

​

Wrapper scripts

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

​

Give a default to variables that can be unset

​

Quote the arguments and variables your script expands

• Argumentos: repasse-os como "$@"
• Variáveis: coloque cada uma entre aspas, como em "${CLAUDE_CODE_REMOTE_SLACK_THREAD_URL:-}". O link da thread do Slack, por exemplo, pode conter ? e &.
• Strings de eval e sh -c: não substitua um valor em uma string que eval ou sh -c executa, mesmo entre aspas. Em vez disso, faça essa string referenciar a variável.

​

Keep stdin and file descriptor 3 attached

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"

• Descritor de arquivo 3: transporta os sinais de atividade do filho para o runner. Não o feche nem o reutilize no wrapper.
• Descritores de arquivo 4 e 5: runners no Claude Code v2.1.309 ou posterior os reservam para o filho. Não os feche nem os reutilize no wrapper. Se seu wrapper usa algum deles, por exemplo para salvar stdin, mova esse uso para um descritor de 6 a 9, que versões anteriores também deixam livres.
• stderr: quando o wrapper ou o filho sai com código diferente de zero, o runner publica as últimas linhas do stderr na sessão e as imprime em seu próprio log. O usuário da sessão vê essas linhas, então não imprima segredos no stderr e remova set -x antes de implantar o wrapper. Se você redirecionar o stderr, as sessões ainda são executadas, mas o runner relata uma falha apenas com o código de saída.

​

Pass the system prompt flags through

• Repasse-as: termine o wrapper com exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@", que encaminha as flags de arquivo junto com todos os outros argumentos. Não as descarte nem as reescreva. Se uma sessão perder uma flag de arquivo de prompt, ela será executada sem as instruções que o plano de controle enviou para ela.
• Em um runner na v2.1.281 ou posterior, uma flag de arquivo que você acrescenta substitui a do servidor, nunca se soma a ela: cada flag de arquivo de prompt aceita um único valor e o Claude Code mantém a última ocorrência, então se você acrescentar --append-system-prompt-file <path> depois de "$@", o conteúdo do seu arquivo substitui as instruções anexadas do servidor. Para adicionar instruções além das do servidor, coloque-as no CLAUDE.md da imagem do runner, que o runner insere na configuração de nível de usuário de cada sessão.

​

Fix Argument list too long at session start

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

​

Provision credentials scoped to the session creator

#!/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" "$@"

​

Lifecycle hooks

​

checkout

​

Obter credenciais git no hook

• Credencial de clone por sessão: verifique CLAUDE_CODE_SESSION_ACCESS_TOKEN com uma biblioteca JWT padrão contra o endpoint JWKS sob CLAUDE_RUNNER_API_BASE_URL, conforme descrito em Verify the token from your service. Em seguida, faça seu serviço de credencial emitir uma credencial de clone de curta duração para a identidade na reivindicação act do token. Associe essa credencial a act.sub, e não exija act.email.
• Autenticação git do host: use qualquer autenticação git que o host já tenha, como um agente SSH, credential helper ou .netrc.

​

Quando o hook falha

• Um repositório para o qual a sessão faz push de resultados: o runner falha a sessão, e em uma saída diferente de zero exibe a cauda do stderr do script para o usuário. Escreva o motivo no stderr como uma única linha curta, escreva-a por último e então saia com código diferente de zero. Não imprima segredos no stderr e remova set -x antes de implantar o hook. Se o couldn't find remote ref do git aparecer aproximadamente nos últimos 4 KB do stderr do hook, o runner relata um branch excluído em vez disso. A mensagem de erro da sessão então diz que o branch não existe mais no remoto e pede ao usuário que o restaure. Se esse branch existir, consulte Uma sessão falha com no longer exists on the remote ou couldn't find remote ref.
• Um repositório que a sessão apenas lê, como um repositório adicionado a uma sessão em execução: o runner o pula e continua com os repositórios restantes. O runner publica um passo Skipped para a sessão e remove o que o hook deixou no caminho de checkout. Quando o passo Skipped menciona o checkout hook, encontre o detalhe da falha na linha [runner:warn] checkout hook failed no log do runner. Quando o passo diz que uma ref de origem no longer exists on remote, consulte Uma sessão falha com no longer exists on the remote ou couldn't find remote ref. Se pular deixa a sessão sem nenhum repositório, o runner falha a sessão mesmo assim.

​

post-session

• completed: a sessão terminou de forma limpa. O processo Claude Code saiu normalmente, ou saiu por conta própria depois que a sessão foi arquivada ou deletada.
• failed: o processo Claude Code travou, ou a configuração falhou após ele ter iniciado.
• interrupted: o runner parou a sessão, em um destes casos:
  • O runner liberou a sessão para liberar o slot.
  • A sessão atingiu o timeout na inicialização.
  • O servidor moveu a sessão para fora deste runner.
  • A verificação periódica do runner detectou um arquivamento ou exclusão antes de o processo sair.
  • O runner estava drenando.
  • A sessão ultrapassou seu limite --kill-session-after-min.
• abandoned: reservado para uma sessão que outro runner reivindicou. O hook não dispara atualmente nesse 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 when the runner releases a session

• Inativo após uma volta, ou expirado na inicialização: o runner para o filho e executa este hook até a conclusão. Apenas então ele libera a sessão. Uma mensagem do usuário enviada enquanto o hook é executado não pode retomar a sessão em outro runner antes do hook terminar.
• Aguardando o usuário responder a um prompt, como um prompt de permissão: o runner libera a sessão primeiro, então executa este hook. Uma mensagem do usuário enviada enquanto o hook é executado pode retomar a sessão em outro runner antes do hook terminar.

​

Configuração do Git dentro de lifecycle hooks

• Git hooks: a menos que você forneça um valor, core.hooksPath é /dev/null, então o git ignora os hooks no .git/hooks de um repositório e qualquer diretório de hooks que ~/.gitconfig nomeie. Para fornecer um, exporte core.hooksPath como um par GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n no ambiente do runner. O runner também lê core.hooksPath da configuração git do sistema, e o usa apenas quando o usuário do runner não pode escrever nesse arquivo, no diretório que ele nomeia ou nos arquivos de hook dentro dele. Quando o runner ignora um valor, uma linha [runner:warn] na inicialização nomeia o valor e o motivo.
• Monitor do sistema de arquivos: core.fsmonitor é vazio, então o git em seu hook não executa um programa de monitor que um arquivo de configuração nomeie.
• Protocolos remotos: GIT_ALLOW_PROTOCOL é https:http:ssh. Um clone, fetch ou push que usa um caminho local, uma URL file:// ou uma URL git:// falha com fatal: transport 'file' not allowed ou fatal: transport 'git' not allowed.
• Comando SSH e prompt de credencial: o git em seu hook ignora core.sshCommand e core.askPass de arquivos de configuração. Para usar seu próprio comando SSH, defina GIT_SSH_COMMAND no ambiente do runner. Para usar um programa de prompt de credencial, defina GIT_ASKPASS ali. As sessões herdam o ambiente do runner, então ambas as variáveis também chegam ao git da própria sessão. Não coloque uma credencial em nenhuma delas.
• Programas gpg: gpg.program, gpg.openpgp.program, gpg.x509.program e gpg.ssh.program são caminhos que o runner define, nunca valores de um arquivo de configuração.
• Assinatura de commits: com --configure-git, os commits que você faz a partir de um hook são assinados como a sessão. Sem a flag, commit.gpgsign e tag.gpgsign são false.

• Pares de configuração: um par GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n que você exporta no ambiente do runner substitui o valor do runner para a mesma chave. Numere seus pares a partir de 0 e defina GIT_CONFIG_COUNT com a quantidade deles. Quando o último par que a contagem anuncia está ausente, o runner ignora todos os seus pares e registra uma linha [runner:warn] na inicialização.
• Variáveis de ambiente do git: o runner deixa GIT_ALLOW_PROTOCOL, GIT_SSH_COMMAND e GIT_ASKPASS como você as definiu em seu ambiente.
• Opções git -c: uma opção git -c dentro do hook sobrescreve um par GIT_CONFIG_KEY_n, seja do runner ou seu. Ela não altera GIT_ALLOW_PROTOCOL, GIT_SSH_COMMAND ou GIT_ASKPASS, que o git lê antes de qualquer configuração.

​

command

​

On-demand runners

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

​

The spawn-runner hook

• Inicie-o com a ordem de trabalho: aponte --environment-secret-file para um arquivo contendo o JWT da ordem de trabalho, ou defina SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET para o valor JWT.
• Copie o JWT antes do hook sair: o orquestrador deleta o arquivo da ordem de trabalho após o hook sair, então copie o JWT para a carga de trabalho que você submete, como um Kubernetes Secret no Job gerado, em vez de passar o caminho do arquivo.
• Use --capacity 1 em runners gerados: uma ordem de trabalho vinculada a sessão registra exatamente um runner vinculado a essa sessão, então uma capacidade maior adiciona slots que nunca recebem trabalho, e o runner registra um aviso na inicialização.
• Ordens de trabalho de pré-aquecimento registram desvinculadas: o runner em standby não está vinculado a uma sessão e reclama trabalho enfileirado como um runner de frota fixa.

1. Seja idempotente em CLAUDE_RUNNER_ORDER_ID. Reentrega da mesma solicitação deve gerar no máximo um runner. Derive um nome de recurso determinístico do ID de ordem e deixe sua plataforma rejeitar a duplicata. Não use CLAUDE_RUNNER_SESSION_ID como chave. Cada re-solicitação para uma sessão carrega o mesmo ID de sessão com um novo ID de ordem. Uma carga de trabalho nomeada ou deduplicada pelo ID de sessão não é criada novamente enquanto a primeira existir.
2. Não tente novamente a carga de trabalho. Um ID de ordem significa no máximo uma carga de trabalho criada. Se o runner nunca se registra, Anthropic re-solicita com um ID de ordem fresco após --expected-spawn-seconds.
3. Use o contrato de código de saída. Saia com o status que corresponde ao resultado:
   • Saída 0: submetido.
   • Saída 1, ou ainda em execução quando --hook-timeout termina: falha retentável. A sessão recua e é re-oferecida. Após 10 solicitações com falha seguidas, ela é bloqueada da mesma forma que após a saída 2 ou superior.
   • Saída 2 ou superior: falha não-retentável. A sessão é bloqueada de gerar novamente até que um usuário envie uma nova mensagem a ela ou um Owner selecione Retry nela na aba Activity do ambiente.
   Enquanto uma sessão recua, ela aparece como Queued na aba Activity sem erro de spawn, então leia a saída do hook no log do orquestrador. Uma vez bloqueada, a sessão aparece como Failed. Expanda-a para ler o erro de spawn, extraído dos últimos 512 caracteres do stderr do hook. Escreva um erro acionável para stderr, e nenhum segredo. Em um hook de shell, mantenha falhas transitórias retentáveis. Uma solicitação de pré-aquecimento não tem sessão para falhar: o orquestrador registra uma saída diferente de zero localmente apenas, e o servidor re-solicita o spawn após a concessão de --expected-spawn-seconds expirar.
4. Defina --expected-spawn-seconds para pelo menos seu tempo p99 desde a solicitação de spawn até o registro do runner. Meça a partir do momento em que o orquestrador recebe a solicitação de spawn e inclua qualquer espera por capacidade na sua plataforma, além do tempo de boot. Este valor é a concessão no lado do servidor, e a ordem de trabalho expira com ela, então um runner cuja carga de trabalho demora mais não consegue se registrar. Todas as réplicas do orquestrador devem usar o mesmo valor.

​

Corrija sessões reabertas que permanecem Queued ou mostram Failed

name="runner-${CLAUDE_RUNNER_SESSION_ID}"

1. Na primeira solicitação de spawn da sessão, o hook cria uma carga de trabalho com esse nome, e um runner é iniciado
2. O runner sai, por exemplo após --release-idle-session-min, e o usuário reabre a sessão mais tarde
3. A próxima solicitação de spawn da sessão carrega o mesmo ID de sessão e um novo ID de ordem, então o hook monta o mesmo nome
4. Se sua plataforma ainda tem a carga de trabalho da primeira solicitação, porque nada a removeu quando seu runner saiu, o hook não cria nenhuma carga de trabalho nova e nenhum runner é iniciado
5. Cada solicitação de spawn posterior para a sessão termina da mesma forma

name="runner-${CLAUDE_RUNNER_ORDER_ID}"

• Queued: a sessão recebe sua próxima solicitação de spawn por conta própria
• Failed: selecione Retry nela como Owner, ou peça ao usuário dela que envie uma nova mensagem

​

Faça runners sob demanda saírem quando ociosos

​

Envie a saída de um processo em segundo plano para um arquivo

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

• Cerca de um segundo após o hook sair, o orquestrador registra exited, but a process it started still has the hook's stdout or stderr open. A partir dessa linha, ele registra até mais 64 KB dessa saída sob [runner:hook:spawn-runner:after-exit jti=<order id>] e então descarta o restante.
• Depois que o orquestrador sai, as escritas do processo ali falham.

• Aba Activity, no erro de spawn de uma sessão com falha: spawn-runner hook timed out after 60000ms, ou as últimas linhas no stderr do hook.
• Log do orquestrador: timed out after 60000ms, sending SIGTERM to process tree.

​

Saia do hook sem aguardar o runner

• Para confirmar que o timeout é o que interrompe seus runners: procure no log do orquestrador por timed out after 60000ms, sending SIGTERM to process tree em cada solicitação de spawn. O 60000 é seu --hook-timeout em milissegundos.
• Para corrigir: faça o hook submeter o runner à sua plataforma e sair com 0. Se, em vez disso, você aumentar o --hook-timeout, o runner apenas para mais tarde.

​

Mantenha falhas transitórias retentáveis em um hook de 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 superior isolado: com o trap definido, ele se torna saída 1. Para um erro que nenhuma nova tentativa pode corrigir, chame permanent com o motivo, como permanent "namespace claude-runners does not exist". Chame-o no shell principal, não dentro de $( ), ( ) ou de um pipe.
• exec: não inicie o último comando do hook com exec, porque exec substitui o shell e o trap não é executado.
• Segundo trap EXIT: um segundo trap ... EXIT substitui o primeiro, então mescle os dois em um único trap. Coloque seus comandos de limpeza diretamente após rc=$?; e termine cada um com || true;. A limpeza então é executada tanto em caso de falha quanto de sucesso, e um comando de limpeza que falha não define o status de saída do hook. Este trap mesclado mostra o formato, com your-cleanup-command representando o seu próprio comando:
  trap 'rc=$?; your-cleanup-command || true; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT
  
• Comandos que podem falhar: se o hook não usava set -e antes, agora ele para no primeiro comando que retorna diferente de zero, como uma consulta que não encontra nada. Se o hook age com base no resultado, faça desse comando a condição de um if. Se ele ignora o resultado, siga o comando com || true.
• O comando que submete a carga de trabalho: não o siga com || true. Com || true, o hook sai com 0 mesmo quando sua plataforma recusa a submissão, por exemplo por exceder a quota, e a sessão aguarda um runner que nunca foi iniciado. Nomeie a carga de trabalho com base em CLAUDE_RUNNER_ORDER_ID, como diz a primeira regra do hook. Uma resposta de que o recurso já existe é então uma reentrega da mesma solicitação, então trate apenas essa resposta como sucesso. Para qualquer outra coisa, imprima a resposta no stderr e saia com 1, ou chame permanent se nenhuma nova tentativa puder corrigi-la. Este exemplo faz isso para kubectl create, com um job.yaml que contém apenas a carga de trabalho:
  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
  
  O log do orquestrador então mostra essa mensagem. Se o hook cria outros objetos, nomeie cada um com base no ID de ordem, dê a cada um seu próprio comando e trate sua resposta de que o recurso já existe como sucesso da mesma forma. Para um objeto que contém um segredo, imprima uma mensagem fixa no lugar da saída do comando.

​

Enviar requisições de modelo para 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)'

​

O que muda em relação às sessões na API da Anthropic

• Políticas do claude.ai: as configurações gerenciadas pelo servidor não chegam a essas sessões. Também não chegam as políticas da organização que um Owner define nas configurações de administração do Claude Code, portanto o Claude Code não as aplica dentro da sessão. Coloque as regras das quais você depende no arquivo de configurações gerenciadas da imagem do runner.
• Skills da conta: essas sessões não baixam as skills ativadas para a conta do claude.ai de uma pessoa. Consulte Como a configuração de cada sessão é montada.
• Arquivos: os arquivos que as pessoas anexam a uma sessão no claude.ai ou no aplicativo móvel ou desktop não chegam a ela, e o Claude não pode enviar arquivos de volta com a ferramenta SendUserFile. Em vez disso, coloque os arquivos de entrada no repositório ou no runner.
• Seleção de modelo: o plano de controle da Anthropic envia o modelo de cada sessão e, quando uma sessão é iniciada sem um, o Claude Code usa o seu padrão para o provedor. Não é possível escolher o modelo com ANTHROPIC_MODEL ou ANTHROPIC_DEFAULT_MODEL no ambiente do runner, mas você pode fixar para o que um alias é resolvido:
  • ANTHROPIC_MODEL e ANTHROPIC_DEFAULT_MODEL: o runner as remove do ambiente que passa às sessões, embora os exemplos das páginas dos provedores definam ANTHROPIC_MODEL.
  • Variáveis de fixação por família: as variáveis em Fixar versões de modelo para o Amazon Bedrock e o Agent Platform chegam, sim, às sessões. Elas decidem para o que um alias como opus é resolvido, não para o que um ID de modelo completo é resolvido.
• Modelos que a sua conta não disponibiliza: uma sessão pode falhar em uma mensagem com um erro que nomeia o modelo. Ative os modelos que os seus desenvolvedores podem escolher, o modelo de segundo plano descrito em Fixar versões de modelo e o modelo classificador que o modo auto usa. No Amazon Bedrock, permita cada um deles na sua política.
• Pesquisa na web e modo rápido: a pesquisa na web não está disponível no Amazon Bedrock, e o modo rápido não está disponível em nenhum dos dois provedores. Para outros recursos que variam por provedor, consulte Recursos da CLI que variam por provedor.

​

Servidores 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

• O arquivo MCP gerenciado de escopo enterprise em seu caminho padrão do sistema: /etc/claude-code/managed-mcp.json em hosts de runner Linux, /Library/Application Support/ClaudeCode/managed-mcp.json em hosts macOS. Use-o para frotas restritas em que apenas servidores listados pelo administrador podem ser carregados. Consulte controle exclusivo com managed-mcp.json para as regras de precedência. Quando esse arquivo está no host do runner, o Claude Code ignora os servidores MCP que o plano de controle da Anthropic entrega a uma sessão, incluindo conectores do claude.ai, e os nomeia em um aviso no stderr do processo filho da sessão, que o runner registra no nível de log debug. Antes da v2.1.229, essas sessões encerravam na inicialização com You cannot dynamically configure MCP servers when an enterprise MCP config is present.
• A chave managedMcpServers nas configurações gerenciadas no host do runner: fornece servidores HTTP e SSE sem assumir controle exclusivo, de modo que os servidores das outras fontes ainda são carregados. Requer o Claude Code v2.1.259 ou posterior.
• <repo>/.mcp.json: escopo de projeto. Fora de uma thread de projeto, faça commit do arquivo no repositório, e seus servidores são aprovados automaticamente em sessões na nuvem. Em uma sessão com vários repositórios, no máximo o arquivo de um repositório é carregado.
• Um arquivo --mcp-config do seu script wrapper: acrescente a flag depois de "$@", como em exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --mcp-config /etc/claude/mcp.json. Para manter os servidores desse arquivo em execução quando os servidores entregues à sessão forem atualizados no meio da sessão, faça com que seu wrapper passe o ambiente completo para o processo filho, como o exec faz. Antes da v2.1.299, os servidores stdio, HTTP e SSE desse arquivo eram encerrados na primeira atualização desse tipo que não os nomeasse.

​

Aguardar os servidores MCP antes do primeiro turno

• Inicialização da sessão: antes de a lista de ferramentas ser obtida pela primeira vez, a sessão aguarda até 5 segundos por padrão por um servidor HTTP ou SSE cuja entrada define alwaysLoad: true, ou por todos os servidores quando você define MCP_CONNECTION_NONBLOCKING=0 no ambiente do runner. Caso contrário, os servidores HTTP e SSE se conectam em segundo plano. Enquanto a sessão aguarda aqui, ela demora mais para inicializar. MCP_CONNECT_TIMEOUT_MS altera o padrão de 5 segundos.
• Primeiro turno: depois que a mensagem chega, o primeiro turno aguarda até 2 segundos pelos servidores stdio que ainda estão se conectando. Enquanto a sessão aguarda aqui, a primeira resposta demora mais. Para alterar a duração dessa espera, defina CLAUDE_CODE_MCP_STARTUP_WAIT_MS no ambiente do runner. Isso não altera quais servidores a espera abrange. Requer o Claude Code v2.1.274 ou posterior.

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

​

Desativar as ferramentas de sessão integradas

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

​

Prompt sessions to push their work

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

#!/bin/sh
# Stop-hook reference implementation for self-hosted runners.
#
# Nudges Claude once per turn if the project directory has uncommitted
# changes OR unpushed commits, so work isn't lost when an idle session
# is released and so the "Create PR" button on claude.ai/code lights up.
#
# Runner-level (no repo changes): drop this file at ~/.claude/hooks/ on
# the runner host and merge the accompanying Stop-hook settings block
# into ~/.claude/settings.json — the runner seeds both into every session.
# Repo-level alternative: commit to <repo>/.claude/hooks/ and change the
# settings.json command path to $CLAUDE_PROJECT_DIR/.claude/hooks/.
#
# stdin: hook JSON payload (see https://code.claude.com/docs/en/hooks)
# stdout: {"decision":"block","reason":"..."} to nudge, or nothing to allow stop.

# Re-entry guard: the harness sets stop_hook_active=true when re-invoking
# the Stop hook after a block. Bail so we only nudge once per turn. The
# harness emits compact JSON (no space after the colon), which this
# pattern relies on; use jq if you need a whitespace-tolerant check.
in=$(cat)
case "$in" in *'"stop_hook_active":true'*) exit 0 ;; esac

d="$CLAUDE_PROJECT_DIR"

# Hardening: this script runs outside Claude Code's Bash sandbox, so its git
# calls skip some features that can start a program named in the checkout's
# git settings. They don't skip them all, so don't count on the sandbox alone.
GIT_OPTIONAL_LOCKS=0
export GIT_OPTIONAL_LOCKS
git() { command git -c core.fsmonitor= -c core.hooksPath=/dev/null "$@"; }

# Not a git repo → nothing to nudge.
git -C "$d" rev-parse --git-dir >/dev/null 2>&1 || exit 0

# No remote → "push to the remote" is unsatisfiable; bail.
[ -z "$(git -C "$d" remote 2>/dev/null)" ] && exit 0

# Uncommitted changes (staged, unstaged, or untracked). Exclude .claude/
# entirely — operator-seeded settings and CLI-written runtime state
# (scheduler lock, worktrees, routine state) live there and neither is
# "uncommitted work" the model needs to 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

# Unpushed commits. Count commits on HEAD not reachable from any
# remote-tracking ref or FETCH_HEAD. This works uniformly for:
#   - init+fetch checkouts (runner default: only FETCH_HEAD exists)
#   - clone-based checkouts (origin/* exist)
#   - the runner default: the child starts on the session's outcome
#     branch, which the runner creates after checkout
#   - detached HEAD, when a custom setup skips that branch creation
# With no reference point at all (never fetched), stay silent rather
# than false-positive on a read-only turn.
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 is either "" or "FETCH_HEAD", intentional word-split
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 is attacker-influenced — git-check-ref-format(1) allows `"`
    # in ref names. `\` is forbidden (rule 10) but escaped anyway as cheap
    # defense-in-depth.
    # Escape JSON metacharacters before interpolating into the hand-built
    # payload so a branch like x","continue":false can't inject keys into
    # the hook-output JSON the harness parses. $unpushed is safe — the
    # -gt guard above rejects anything that isn't a plain integer.
    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

• Uma identidade git: defina user.name e user.email na imagem do seu runner, ou inicie o runner com --configure-git
• Credenciais de push: use o git gerenciado pela Anthropic, ou forneça credenciais conforme descrito em Incluir a configuração do git na sua imagem
• Para sessões retomadas: defina --push-outcome-on-release em todos os runners do ambiente. Uma sessão retomada então começa a partir dos commits que Claude enviou por push para o branch da sessão. Para os limites da flag, consulte Sessões retomadas perdem trabalho sem push.

​

Submódulos e o hook Stop

• Um novo commit em um submódulo: Claude recebe a solicitação até que o repositório pai o registre, mesmo que .gitmodules defina ignore = all para esse submódulo
• Arquivos sem commit em um submódulo: Claude não recebe a solicitação, então esse trabalho permanece apenas no disco do runner
• Commits sem push em um submódulo: o hook Stop não verifica se eles foram enviados por push, então o repositório pai pode apontar para um commit que ninguém mais consegue buscar

​

Substituir uma cópia anterior do script do hook Stop

• Quando: se suas sessões são executadas com o sandbox do Bash ativado, substitua-a agora. Caso contrário, substitua-a no seu próximo build de imagem ou reinicialização do runner.
• O que muda: arquivos sem commit em um submódulo não solicitam mais a Claude. Um novo commit em um submódulo que .gitmodules marca como ignore = all agora solicita.

​

Permissions and tool approval

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

​

How each session’s config is assembled

• Configurações de projeto: fora de uma thread de projeto, um .claude/settings.json com commit no repositório se sobrepõe à linha de base de nível de usuário. Em uma sessão com vários repositórios, no máximo o arquivo de um repositório tem efeito.
• Configurações gerenciadas: as sessões leem managed-settings.json do caminho de sistema padrão em sua imagem do runner. Para saber se suas chaves se aplicam ao lado de server-managed settings, consulte como Claude Code combina fontes gerenciadas.

• Onde eles pousam: o runner escreve cada script de hook fornecido para um subdiretório reservado hooks/.ccr-launcher/ do diretório de configuração da sessão e registra os scripts em um arquivo de configurações separado que passa para a sessão com --settings, deixando o settings.json semeado e seus próprios scripts em hooks/<name> intocados. O runner recria o subdiretório reservado para cada sessão e não semeia conteúdo do host em ~/.claude/hooks/.ccr-launcher/ em sessões.
• Quem os autora: o plano de controle popula os scripts de constantes fixas em sua própria implantação, nunca de entrada por sessão ou de terceiros.
• O que ainda os governa: hooks entregues através de --settings entram na configuração de hook mesclada ordinária, não na camada gerenciada, então suas configurações gerenciadas ainda se aplicam. disableAllHooks os desabilita, e eles não estão entre as categorias que allowManagedHooksOnly mantém carregadas.

​

Stop sessions that fail to fetch server-managed settings

• Sessões de canal do Claude Tag: deixe a chave de fora nos runners de um ambiente para o qual um Owner direciona canais do Claude Tag. A API da Anthropic recusa a requisição dessas sessões por configurações gerenciadas pelo servidor, então, com a chave definida, elas não conseguem iniciar. Coloque as regras delas no managed-settings.json da imagem do runner, que elas ainda leem. Para usar a chave em suas outras sessões, execute-as em um ambiente separado.
• Bedrock ou Agent Platform: sessões nesses provedores não buscam configurações gerenciadas pelo servidor, então elas iniciam quer você defina a chave ou não. Em vez disso, aplique suas regras a partir do mesmo managed-settings.json.

{
  "forceRemoteSettingsRefresh": true
}

​

Repository settings in sessions with several repositories

• --capacity 1, o padrão, com o checkout integrado: a sessão inicia no primeiro repositório de sua lista de repositórios. O .claude/settings.json desse repositório tem efeito como configurações de projeto e seu .mcp.json é carregado, e os dos outros repositórios não.
• Um --capacity acima de um, ou um hook checkout: a sessão inicia em um diretório por sessão que contém os checkouts. Nenhum .claude/settings.json de repositório tem efeito como configurações de projeto, nenhum .mcp.json de repositório é carregado, e $CLAUDE_PROJECT_DIR em um comando de hook é esse diretório, não um checkout.

​

Repository-committed permission rules

​

What’s next

• Reference: cada flag CLI, variável de ambiente e métrica
• Verify session identity: valide o token de sessão de serviços fora do runner