Personalizar sesiones en entornos autohospedados

​

Scripts contenedores

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

​

Dar un valor predeterminado a las variables que pueden no estar establecidas

​

Poner entre comillas los argumentos y las variables que expande tu script

• Argumentos: pásalos como "$@"
• Variables: pon cada una entre comillas, como en "${CLAUDE_CODE_REMOTE_SLACK_THREAD_URL:-}". El enlace del hilo de Slack, por ejemplo, puede contener ? y &.
• Cadenas de eval y sh -c: no sustituyas un valor en una cadena que ejecuta eval o sh -c, ni siquiera entre comillas. En su lugar, haz que esa cadena haga referencia a la variable.

​

Mantener stdin y descriptor de archivo 3 adjuntos

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"

• Descriptor de archivo 3: lleva las señales de actividad del hijo al ejecutor. No lo cierres ni lo reutilices en el contenedor.
• Descriptores de archivo 4 y 5: los ejecutores en Claude Code v2.1.309 o posterior los reservan para el hijo. No los cierres ni los reutilices en el contenedor. Si tu contenedor usa alguno de ellos, por ejemplo para guardar stdin, mueve ese uso a un descriptor del 6 al 9, que las versiones anteriores también dejan libres.
• stderr: cuando el contenedor o el hijo salen con un código distinto de cero, el ejecutor publica las últimas líneas de stderr en la sesión y las imprime en su propio registro. El usuario de la sesión ve esas líneas, así que no imprimas secretos en stderr y quita set -x antes de implementar el contenedor. Si rediriges stderr, las sesiones siguen ejecutándose, pero el ejecutor informa un fallo solo con el código de salida.

​

Transmitir los flags del prompt del sistema

• Transmítelos: termina el contenedor con exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@", que reenvía los flags de archivo junto con todos los demás argumentos. No los descartes ni los reescribas. Si una sesión pierde un flag de archivo de prompt, se ejecuta sin las instrucciones que el plano de control envió para ella.
• En un ejecutor con v2.1.281 o posterior, un flag de archivo que agregues reemplaza el del servidor, nunca se suma a él: cada flag de archivo de prompt toma un único valor y Claude Code conserva la última aparición, por lo que si agregas --append-system-prompt-file <path> después de "$@", el contenido de tu archivo reemplaza las instrucciones anexadas del servidor. Para agregar instrucciones además de las del servidor, colócalas en el CLAUDE.md de la imagen del ejecutor, que el ejecutor incorpora en la configuración a nivel de usuario de cada sesión.

​

Corregir Argument list too long al inicio de la sesión

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

​

Aprovisionar credenciales limitadas al creador de la sesión

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

​

Hooks de ciclo de vida

​

checkout

​

Obtener credenciales de git en el hook

• Credencial de clon por sesión: verifica CLAUDE_CODE_SESSION_ACCESS_TOKEN con una biblioteca JWT estándar contra el endpoint JWKS bajo CLAUDE_RUNNER_API_BASE_URL, como se describe en Verificar el token desde tu servicio. Luego haz que tu servicio de credenciales emita una credencial de clon de corta duración para la identidad en la reclamación act del token. Asocia esa credencial a act.sub, y no exijas act.email.
• Autenticación git del host: usa la autenticación git que el host ya tenga, como un agente SSH, un ayudante de credenciales o .netrc.

​

Cuando el hook falla

• Un repositorio al que la sesión envía resultados: el ejecutor falla la sesión, y en una salida distinta de cero muestra la cola del stderr del script al usuario. Escribe el motivo en stderr como una sola línea breve, escríbelo al final y luego sal con un código distinto de cero. No imprimas secretos en stderr, y quita set -x antes de desplegar el hook. Si el mensaje couldn't find remote ref de git aparece aproximadamente en los últimos 4 KB del stderr del hook, el ejecutor informa en su lugar de una rama eliminada. El mensaje de error de la sesión indica entonces que la rama ya no existe en el remoto y pide al usuario que la restaure. Si esa rama existe, consulta Una sesión falla con no longer exists on the remote o couldn't find remote ref.
• Un repositorio que la sesión solo lee, como un repositorio agregado a una sesión en ejecución: el ejecutor lo omite y continúa con los repositorios restantes. El ejecutor publica un paso Skipped en la sesión y elimina lo que el hook haya dejado en la ruta de checkout. Cuando el paso Skipped menciona el hook de checkout, busca el detalle del fallo en la línea [runner:warn] checkout hook failed del registro del ejecutor. Cuando el paso indica que una ref de origen no longer exists on remote, consulta Una sesión falla con no longer exists on the remote o couldn't find remote ref. Si al omitirlo la sesión queda sin ningún repositorio, el ejecutor falla la sesión de todas formas.

​

post-session

• completed: la sesión terminó limpiamente. El proceso de Claude Code salió normalmente, o salió por sí mismo después de que la sesión fue archivada o eliminada.
• failed: el proceso de Claude Code se bloqueó, o la configuración falló después de que comenzó.
• interrupted: el ejecutor detuvo la sesión, en uno de estos casos:
  • El ejecutor liberó la sesión para liberar la ranura.
  • Se agotó el tiempo de espera de la sesión al inicio.
  • El servidor movió la sesión fuera de este ejecutor.
  • El sondeo del ejecutor detectó un archivado o una eliminación antes de que el proceso saliera.
  • El ejecutor estaba drenando.
  • La sesión superó su límite de --kill-session-after-min.
• abandoned: reservado para una sesión que otro ejecutor reclamó. El hook actualmente no se dispara en ese 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

​

Tiempo del hook cuando el ejecutor libera una sesión

• Inactivo después de un turno, o tiempo de espera agotado al inicio: el ejecutor detiene el hijo y ejecuta este hook hasta completarse. Solo entonces libera la sesión. Un mensaje de usuario enviado mientras se ejecuta el hook no puede reanudar la sesión en otro ejecutor antes de que el hook termine.
• Esperando que el usuario responda a un mensaje, como un mensaje de permiso: el ejecutor libera la sesión primero, luego ejecuta este hook. Un mensaje de usuario enviado mientras se ejecuta el hook puede reanudar la sesión en otro ejecutor antes de que el hook termine.

​

Configuración de Git dentro de los hooks de ciclo de vida

• Hooks de Git: a menos que proporciones un valor, core.hooksPath es /dev/null, por lo que git omite los hooks en el .git/hooks de un repositorio y cualquier directorio de hooks que nombre ~/.gitconfig. Para proporcionar uno, exporta core.hooksPath como un par GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n en el entorno del ejecutor. El ejecutor también lee core.hooksPath de la configuración de git del sistema, y solo lo usa cuando el usuario del ejecutor no puede escribir en ese archivo, en el directorio que nombra ni en los archivos de hooks que contiene. Cuando el ejecutor ignora un valor, una línea [runner:warn] al iniciar indica el valor y el motivo.
• Monitor del sistema de archivos: core.fsmonitor está vacío, por lo que git en tu hook no ejecuta un programa de monitor que nombre un archivo de configuración.
• Protocolos remotos: GIT_ALLOW_PROTOCOL es https:http:ssh. Un clone, fetch o push que use una ruta local, una URL file:// o una URL git:// falla con fatal: transport 'file' not allowed o fatal: transport 'git' not allowed.
• Comando SSH y solicitud de credenciales: git en tu hook ignora core.sshCommand y core.askPass de los archivos de configuración. Para usar tu propio comando SSH, establece GIT_SSH_COMMAND en el entorno del ejecutor. Para usar un programa de solicitud de credenciales, establece allí GIT_ASKPASS. Las sesiones heredan el entorno del ejecutor, por lo que ambas variables también llegan al git propio de la sesión. No pongas una credencial en ninguna de ellas.
• Programas gpg: gpg.program, gpg.openpgp.program, gpg.x509.program y gpg.ssh.program son rutas que establece el ejecutor, nunca valores de un archivo de configuración.
• Firma de commits: con --configure-git, los commits que hagas desde un hook se firman como la sesión. Sin el flag, commit.gpgsign y tag.gpgsign son false.

• Pares de configuración: un par GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n que exportes en el entorno del ejecutor reemplaza el valor del ejecutor para la misma clave. Numera tus pares a partir de 0 y establece GIT_CONFIG_COUNT en la cantidad que haya. Cuando falta el último par que anuncia el conteo, el ejecutor ignora todos tus pares y registra una línea [runner:warn] al iniciar.
• Variables de entorno de Git: el ejecutor deja GIT_ALLOW_PROTOCOL, GIT_SSH_COMMAND y GIT_ASKPASS tal como los establezcas en su entorno.
• Opciones git -c: una opción git -c dentro del hook sobrescribe un par GIT_CONFIG_KEY_n, sea del ejecutor o tuyo. No cambia GIT_ALLOW_PROTOCOL, GIT_SSH_COMMAND ni GIT_ASKPASS, que git lee antes que cualquier configuración.

​

command

​

Ejecutores bajo demanda

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

​

El hook spawn-runner

• Inicie con la orden de trabajo: apunte --environment-secret-file a un archivo que contenga el JWT de orden de trabajo, o establezca SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET al valor JWT.
• Copie el JWT antes de que el hook salga: el orquestador elimina el archivo de orden de trabajo después de que el hook sale, por lo que copie el JWT en la carga de trabajo que envía, como un Secret de Kubernetes en el Job generado, en lugar de pasar la ruta del archivo.
• Use --capacity 1 en ejecutores generados: una orden de trabajo vinculada a sesión registra exactamente un ejecutor vinculado a esa sesión, por lo que una capacidad más alta agrega espacios que nunca reciben trabajo, y el ejecutor registra una advertencia al inicio.
• Las órdenes de trabajo de precalentamiento registran sin vincular: el ejecutor en espera no está vinculado a una sesión y reclama trabajo en cola como un ejecutor de flota fija.

1. Sé idempotente en CLAUDE_RUNNER_ORDER_ID. La reentrega de la misma solicitud debe generar como máximo un ejecutor. Deriva un nombre de recurso determinista del ID de orden y deja que tu plataforma rechace el duplicado. No uses CLAUDE_RUNNER_SESSION_ID como clave en su lugar. Cada resolicitud de una sesión lleva el mismo ID de sesión con un nuevo ID de orden. Una carga de trabajo nombrada o deduplicada por el ID de sesión no se vuelve a crear mientras exista la primera.
2. No reintente la carga de trabajo. Un ID de orden significa como máximo una carga de trabajo creada. Si el ejecutor nunca se registra, Anthropic reintenta con un ID de orden nuevo después de --expected-spawn-seconds.
3. Usa el contrato de código de salida. Sal con el estado que corresponda al resultado:
   • Salida 0: enviado.
   • Salida 1, o si sigue en ejecución cuando termina --hook-timeout: fallo reintentable. La sesión espera un tiempo y se vuelve a ofrecer. Después de 10 solicitudes fallidas seguidas, queda bloqueada igual que tras una salida 2 o superior.
   • Salida 2 o superior: fallo no reintentable. La sesión queda bloqueada para generar nuevamente hasta que un usuario le envíe un mensaje nuevo o un Propietario seleccione Retry en ella en la pestaña Activity del entorno.
   Mientras una sesión espera para reintentar, aparece como Queued en la pestaña Activity sin error de generación, así que lee la salida del hook en el registro del orquestador. Una vez bloqueada, la sesión aparece como Failed. Expándela para leer el error de generación, tomado de los últimos 512 caracteres del stderr del hook. Escribe un error procesable en stderr, y ningún secreto. En un hook de shell, mantén los fallos transitorios reintentables. Una solicitud de precalentamiento no tiene sesión que pueda fallar: el orquestador registra una salida distinta de cero solo localmente, y el servidor vuelve a solicitar la generación después de que expira el arrendamiento de --expected-spawn-seconds.
4. Establece --expected-spawn-seconds en al menos tu tiempo p99 desde la solicitud de generación hasta el registro del ejecutor. Mide desde el momento en que el orquestador recibe la solicitud de generación, e incluye cualquier espera de capacidad en tu plataforma además del tiempo de arranque. Este valor es el arrendamiento del lado del servidor, y la orden de trabajo expira con él, por lo que un ejecutor cuya carga de trabajo tarde más no puede registrarse. Todas las réplicas del orquestador deben usar el mismo valor.

​

Corrige las sesiones reabiertas que permanecen en Queued o muestran Failed

name="runner-${CLAUDE_RUNNER_SESSION_ID}"

1. En la primera solicitud de generación de la sesión, el hook crea una carga de trabajo con ese nombre, y se inicia un ejecutor
2. El ejecutor sale, por ejemplo después de --release-idle-session-min, y el usuario reabre la sesión más tarde
3. La siguiente solicitud de generación de la sesión lleva el mismo ID de sesión y un nuevo ID de orden, así que el hook construye el mismo nombre
4. Si tu plataforma todavía tiene la carga de trabajo de la primera solicitud, porque nada la eliminó cuando su ejecutor salió, el hook no crea ninguna carga de trabajo nueva y no se inicia ningún ejecutor
5. Cada solicitud de generación posterior para la sesión termina de la misma manera

name="runner-${CLAUDE_RUNNER_ORDER_ID}"

• Queued: la sesión recibe su siguiente solicitud de generación por sí sola
• Failed: selecciona Retry en ella como Propietario, o haz que su usuario le envíe un mensaje nuevo

​

Haz que los ejecutores bajo demanda salgan cuando estén inactivos

​

Envía la salida de un proceso en segundo plano a un archivo

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

• Aproximadamente un segundo después de que el hook sale, el orquestador registra exited, but a process it started still has the hook's stdout or stderr open. A partir de esa línea, registra hasta 64 KB más de esa salida bajo [runner:hook:spawn-runner:after-exit jti=<order id>] y luego descarta el resto.
• Una vez que el orquestador sale, las escrituras del proceso allí fallan.

• Pestaña Activity, en el error de generación de una sesión fallida: spawn-runner hook timed out after 60000ms, o las últimas líneas del stderr del hook.
• Registro del orquestador: timed out after 60000ms, sending SIGTERM to process tree.

​

Sal del hook sin esperar al ejecutor

• Para confirmar que el tiempo de espera es lo que detiene tus ejecutores: busca en el registro del orquestador timed out after 60000ms, sending SIGTERM to process tree en cada solicitud de generación. El 60000 es tu --hook-timeout en milisegundos.
• Para corregirlo: haz que el hook envíe el ejecutor a tu plataforma y salga con 0. Si en su lugar aumentas --hook-timeout, el ejecutor solo se detiene más tarde.

​

Mantén los fallos transitorios reintentables en un 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 o superior a secas: con el trap establecido, se convierte en salida 1. Para un error que ningún reintento puede corregir, llama a permanent con el motivo en su lugar, como permanent "namespace claude-runners does not exist". Llámalo en el shell principal, no dentro de $( ), ( ) ni de una tubería.
• exec: no inicies el último comando del hook con exec, porque exec reemplaza el shell y el trap no se ejecuta.
• Segundo trap EXIT: un segundo trap ... EXIT reemplaza al primero, así que combina los dos en un solo trap. Coloca tus comandos de limpieza justo después de rc=$?; y termina cada uno con || true;. Así la limpieza se ejecuta tanto en caso de fallo como de éxito, y un comando de limpieza que falla no establece el estado de salida del hook. Este trap combinado muestra la forma, con your-cleanup-command en lugar de tu propio comando:
  trap 'rc=$?; your-cleanup-command || true; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT
  
• Comandos a los que se les permite fallar: si el hook no usaba set -e antes, ahora se detiene en el primer comando que devuelve un valor distinto de cero, como una búsqueda que no encuentra nada. Si el hook actúa según el resultado, convierte ese comando en la condición de un if. Si ignora el resultado, añade || true después del comando.
• El comando que envía la carga de trabajo: no le añadas || true después. Con || true, el hook sale con 0 incluso cuando tu plataforma rechaza el envío, por ejemplo por exceder la cuota, y la sesión espera a un ejecutor que nunca se inició. Nombra la carga de trabajo según CLAUDE_RUNNER_ORDER_ID, como indica la primera regla del hook. Así, una respuesta de que ya existe es una reentrega de la misma solicitud, por lo que solo esa respuesta debe tratarse como éxito. Para cualquier otra, imprime la respuesta en stderr y sal con 1, o llama a permanent si ningún reintento puede corregirlo. Este ejemplo lo hace para kubectl create, con un job.yaml que contiene solo la carga de trabajo:
  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
  
  El registro del orquestador muestra entonces ese mensaje. Si el hook crea otros objetos, nombra cada uno según el ID de orden, dale su propio comando y trata su respuesta de que ya existe como éxito de la misma manera. Para un objeto que contiene un secreto, imprime un mensaje fijo en lugar de la salida del comando.

​

Enviar solicitudes de modelo a Bedrock o 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)'

​

Qué cambia respecto a las sesiones en la API de Anthropic

• Políticas de claude.ai: la configuración administrada por el servidor no llega a estas sesiones. Tampoco llegan las políticas de organización que un Owner establece en la configuración de administración de Claude Code, por lo que Claude Code no las aplica dentro de la sesión. Coloca las reglas de las que dependes en el archivo de configuración administrada de la imagen del runner.
• Skills de la cuenta: estas sesiones no descargan los skills habilitados para la cuenta de claude.ai de una persona. Consulta Cómo se ensambla la configuración de cada sesión.
• Archivos: los archivos que las personas adjuntan a una sesión en claude.ai o en la aplicación móvil o de escritorio no llegan a ella, y Claude no puede devolver archivos con la herramienta SendUserFile. En su lugar, coloca los archivos de entrada en el repositorio o en el runner.
• Selección de modelo: el plano de control de Anthropic envía el modelo de cada sesión y, cuando una sesión se inicia sin uno, Claude Code usa su modelo predeterminado para el proveedor. No puedes elegir el modelo con ANTHROPIC_MODEL ni con ANTHROPIC_DEFAULT_MODEL en el entorno del runner, pero sí puedes fijar a qué se resuelve un alias:
  • ANTHROPIC_MODEL y ANTHROPIC_DEFAULT_MODEL: el runner las elimina del entorno que pasa a las sesiones, aunque los ejemplos de las páginas de los proveedores establezcan ANTHROPIC_MODEL.
  • Variables de fijación por familia: las variables de Fijar versiones de modelos para Amazon Bedrock y Agent Platform sí llegan a las sesiones. Deciden a qué se resuelve un alias como opus, no a qué se resuelve un ID de modelo completo.
• Modelos que tu cuenta no ofrece: una sesión puede fallar en un mensaje con un error que nombra el modelo. Habilita los modelos que tus desarrolladores pueden elegir, el modelo en segundo plano descrito en Fijar versiones de modelos y el modelo clasificador que usa el modo automático. En Amazon Bedrock, permite cada uno de ellos en tu política.
• Búsqueda web y modo rápido: la búsqueda web no está disponible en Amazon Bedrock, y el modo rápido no está disponible en ninguno de los dos proveedores. Para otras capacidades que varían según el proveedor, consulta Capacidades de la CLI que varían según el proveedor.

​

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

• El archivo MCP administrado de alcance empresarial en su ruta estándar del sistema: /etc/claude-code/managed-mcp.json en hosts de runner Linux, /Library/Application Support/ClaudeCode/managed-mcp.json en hosts macOS. Úsalo para flotas restringidas donde solo pueden cargarse los servidores que indica el administrador. Consulta control exclusivo con managed-mcp.json para conocer las reglas de precedencia. Cuando este archivo está en el host del runner, Claude Code omite los servidores MCP que el plano de control de Anthropic entrega a una sesión, incluidos los conectores de claude.ai, y los nombra en una advertencia en el stderr del proceso hijo de la sesión, que el runner registra en el nivel de registro debug. Antes de la v2.1.229, esas sesiones terminaban al iniciar con You cannot dynamically configure MCP servers when an enterprise MCP config is present.
• La clave managedMcpServers en la configuración administrada del host del runner: proporciona servidores HTTP y SSE sin tomar el control exclusivo, por lo que los servidores de las demás fuentes se siguen cargando. Requiere Claude Code v2.1.259 o posterior.
• <repo>/.mcp.json: alcance de proyecto. Fuera de un hilo de proyecto, haz commit del archivo en el repositorio y sus servidores se aprueban automáticamente en las sesiones en la nube. En una sesión con varios repositorios, se carga como máximo el archivo de un repositorio.
• Un archivo --mcp-config desde tu script contenedor: agrega el flag después de "$@", como en exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --mcp-config /etc/claude/mcp.json. Para que los servidores de ese archivo sigan ejecutándose cuando los servidores entregados a la sesión se actualicen a mitad de la sesión, haz que tu script contenedor pase el entorno completo al proceso hijo, como hace exec. Antes de la v2.1.299, los servidores stdio, HTTP y SSE de ese archivo se cerraban en la primera actualización de ese tipo que no los nombraba.

​

Esperar a los servidores MCP antes del primer turno

• Inicio de la sesión: antes de que se tome la lista de herramientas por primera vez, la sesión espera de forma predeterminada hasta 5 segundos a un servidor HTTP o SSE cuya entrada defina alwaysLoad: true, o a todos los servidores cuando defines MCP_CONNECTION_NONBLOCKING=0 en el entorno del runner. En los demás casos, los servidores HTTP y SSE se conectan en segundo plano. Mientras la sesión espera aquí, tarda más en inicializarse. MCP_CONNECT_TIMEOUT_MS cambia el valor predeterminado de 5 segundos.
• Primer turno: después de que llega el mensaje, el primer turno espera hasta 2 segundos a los servidores stdio que aún se están conectando. Mientras la sesión espera aquí, la primera respuesta tarda más. Para cambiar cuánto dura esta espera, define CLAUDE_CODE_MCP_STARTUP_WAIT_MS en el entorno del runner. No cambia qué servidores abarca la espera. Requiere Claude Code v2.1.274 o posterior.

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

​

Desactivar las herramientas de sesión integradas

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

​

Solicitar a sesiones que envíen su trabajo

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

• Una identidad de git: establece user.name y user.email en la imagen de tu ejecutor, o inicia el ejecutor con --configure-git
• Credenciales de push: usa git administrado por Anthropic, o proporciona credenciales como se describe en Incluir la configuración de git en tu imagen
• Para sesiones reanudadas: establece --push-outcome-on-release en cada ejecutor del entorno. Así, una sesión reanudada comienza desde los commits que Claude envió a la rama de la sesión. Para conocer los límites del flag, consulta Las sesiones reanudadas pierden el trabajo no enviado.

​

Submódulos y el hook Stop

• Un commit nuevo en un submódulo: se le solicita a Claude hasta que el repositorio principal lo registre, incluso si .gitmodules establece ignore = all para ese submódulo
• Archivos no confirmados en un submódulo: no se le solicita nada a Claude, por lo que ese trabajo permanece solo en el disco del ejecutor
• Commits no enviados en un submódulo: el hook Stop no comprueba si se enviaron, por lo que el repositorio principal puede apuntar a un commit que nadie más puede obtener

​

Reemplazar una copia anterior del script del hook Stop

• Cuándo: si tus sesiones se ejecutan con el sandbox de Bash activado, reemplázala ahora. De lo contrario, reemplázala en tu próxima compilación de imagen o reinicio del ejecutor.
• Qué cambia: los archivos no confirmados en un submódulo ya no generan una solicitud a Claude. Un commit nuevo en un submódulo que .gitmodules marca con ignore = all ahora sí la genera.

​

Permisos y aprobación de herramientas

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

​

Cómo se ensambla la configuración de cada sesión

• Configuración del proyecto: fuera de un hilo de un proyecto, un .claude/settings.json incluido mediante commit en el repositorio se superpone a la línea base a nivel de usuario. En una sesión con varios repositorios, como máximo tiene efecto el archivo de un solo repositorio.
• Configuración administrada: las sesiones leen managed-settings.json desde la ruta estándar del sistema en tu imagen del ejecutor. Para saber si sus claves se aplican junto con la configuración administrada por el servidor, consulta cómo Claude Code combina las fuentes administradas.

• Dónde aterrizan: el ejecutor escribe cada script de hook suministrado en un subdirectorio reservado hooks/.ccr-launcher/ del directorio de configuración de la sesión y registra los scripts en un archivo de configuración separado que pasa a la sesión con --settings, dejando el settings.json sembrado y sus propios scripts en hooks/<name> sin tocar. El ejecutor recrea el subdirectorio reservado para cada sesión y no siembra contenido del host en ~/.claude/hooks/.ccr-launcher/ en sesiones.
• Quién los autor: el plano de control puebla los scripts desde constantes fijas en su propia implementación, nunca desde entrada por sesión o de terceros.
• Qué aún los rige: los hooks entregados a través de --settings entran en la configuración de hook ordinaria fusionada, no en el nivel administrado, por lo que su configuración administrada aún se aplica. disableAllHooks los deshabilita, y no están entre las categorías que allowManagedHooksOnly mantiene cargadas.

​

Detener las sesiones que no logran obtener la configuración administrada por el servidor

• Sesiones de canales de Claude Tag: omite la clave en los ejecutores de un entorno al que un Owner dirige canales de Claude Tag. La API de Anthropic rechaza la solicitud de configuración administrada por el servidor de estas sesiones, por lo que, con la clave establecida, no logran iniciarse. Coloca sus reglas en el managed-settings.json de la imagen del ejecutor, que siguen leyendo. Para usar la clave en tus demás sesiones, ejecútalas en un entorno independiente.
• Bedrock o Agent Platform: las sesiones en estos proveedores no obtienen la configuración administrada por el servidor, por lo que se inician tanto si estableces la clave como si no. En su lugar, aplica tus reglas desde el mismo managed-settings.json.

{
  "forceRemoteSettingsRefresh": true
}

​

Configuración de repositorios en sesiones con varios repositorios

• --capacity 1, el valor predeterminado, con el checkout integrado: la sesión se inicia en el primer repositorio de su lista de repositorios. El .claude/settings.json de ese repositorio tiene efecto como configuración del proyecto y su .mcp.json se carga, y los de los demás repositorios no.
• Un --capacity mayor que uno, o un hook checkout: la sesión se inicia en un directorio por sesión que contiene los checkouts. Ningún .claude/settings.json de repositorio tiene efecto como configuración del proyecto, ningún .mcp.json de repositorio se carga, y $CLAUDE_PROJECT_DIR en un comando de hook es ese directorio, no un checkout.

​

Reglas de permiso confirmadas en el repositorio

​

Qué sigue

• Referencia: cada bandera CLI, variable de entorno y métrica
• Verificar identidad de sesión: validar el token de sesión desde servicios fuera del ejecutor