63 63
64| Host | Puerto | Cuando es requerido |64| Host | Puerto | Cuando es requerido |
65| :- | :- | :- |65| :- | :- | :- |
66| `api.github.com` | 443 | Con o sin `--use-anthropic-git-proxy`, cuando la imagen del runner incluye la [GitHub CLI](#github-api-access-with-the-github-cli) y das a las sesiones una credencial de github.com, como un `GH_TOKEN` |
66| `downloads.claude.ai` | 443 | En el momento de la instalación, cuando instala o actualiza Claude Code en el host con el instalador nativo; el script `install.sh` en sí se sirve desde `claude.ai`. En tiempo de ejecución de sesión, solo cuando las sesiones instalan plugins del mercado oficial de Anthropic. |67| `downloads.claude.ai` | 443 | En el momento de la instalación, cuando instala o actualiza Claude Code en el host con el instalador nativo; el script `install.sh` en sí se sirve desde `claude.ai`. En tiempo de ejecución de sesión, solo cuando las sesiones instalan plugins del mercado oficial de Anthropic. |
67| `storage.googleapis.com` | 443 | En tiempo de ejecución de sesión, para los recuentos de instalación de plugins y metadatos mostrados en `/plugin`. |68| `storage.googleapis.com` | 443 | En tiempo de ejecución de sesión, para los recuentos de instalación de plugins y metadatos mostrados en `/plugin`. |
68| `code.claude.com` y `claude.com` | 443 | Búsquedas de documentación por el agente integrado claude-code-guide y solicitudes de WebFetch preaprobadas durante sesiones. Bloquear estos hosts solo afecta las búsquedas de documentación. |69| `code.claude.com` y `claude.com` | 443 | Búsquedas de documentación por el agente integrado claude-code-guide y solicitudes de WebFetch preaprobadas durante sesiones. Bloquear estos hosts solo afecta las búsquedas de documentación. |
167 168
168* El runner establece `GIT_TERMINAL_PROMPT=0`, por lo que git no pide un nombre de usuario o contraseña.169* El runner establece `GIT_TERMINAL_PROMPT=0`, por lo que git no pide un nombre de usuario o contraseña.
169* El runner ejecuta SSH con `BatchMode=yes`, añadido a su `GIT_SSH_COMMAND` si establece uno, por lo que SSH no pide una frase de contraseña o confirmación de host.170* El runner ejecuta SSH con `BatchMode=yes`, añadido a su `GIT_SSH_COMMAND` si establece uno, por lo que SSH no pide una frase de contraseña o confirmación de host.
170* El runner establece `GCM_INTERACTIVE=never`, por lo que Git Credential Manager no abre un diálogo de inicio de sesión.171* El runner establece `GCM_INTERACTIVE=never`, por lo que Git Credential Manager no abre un diálogo de inicio de sesión. Antes de v2.1.229, la preparación del repositorio podía quedarse colgada en una solicitud de Git Credential Manager.
171* El runner borra `core.askPass`, así que si usa un ayudante askpass, establézcalo a través de la variable de entorno `GIT_ASKPASS` en su lugar.172* El runner borra `core.askPass`, así que si usa un ayudante askpass, establézcalo a través de la variable de entorno `GIT_ASKPASS` en su lugar.
172 173
173Si su host de git rechaza la credencial, o no configuró una, el runner reintenta algunas veces y luego falla la preparación del repositorio cuando el repositorio es el que la sesión empuja resultados a. Para un repositorio que la sesión solo lee, [Troubleshooting](#troubleshooting) cubre cuándo el runner lo omite en su lugar. El runner no pasa estas configuraciones al entorno de la sesión.174Si su host de git rechaza la credencial, o no configuró una, el runner reintenta algunas veces y luego falla la preparación del repositorio cuando el repositorio es el que la sesión empuja resultados a. Para un repositorio que la sesión solo lee, [Troubleshooting](#troubleshooting) cubre cuándo el runner lo omite en su lugar. El runner no pasa estas configuraciones al entorno de la sesión.
287* **`jq`**: instala `jq` en la imagen si quieres que `--jq` funcione288* **`jq`**: instala `jq` en la imagen si quieres que `--jq` funcione
288* **[`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/es/env-vars)**: si el entorno de la sesión la establece, Claude Code no proporciona el `gh` integrado, y la sesión no tiene `gh`289* **[`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/es/env-vars)**: si el entorno de la sesión la establece, Claude Code no proporciona el `gh` integrado, y la sesión no tiene `gh`
289 290
290Cuando la imagen incluye la GitHub CLI, las sesiones la usan.291#### Acceso a la API de GitHub con la GitHub CLI
292
293Si la imagen de tu runner incluye la GitHub CLI para que la usen las sesiones, haz que tu [script de envoltura](https://code.claude.com/docs/es/self-hosted-environments-configuration.md#provision-credentials-scoped-to-the-session-creator) genere por sesión un `GH_TOKEN` de corta duración y alcance mínimo para el creador de la sesión. Cuando `gh` está en el `PATH` con el que se inicia Claude Code, la sesión tiene ese `gh` y ningún [`gh` integrado](#github-api-access-without-the-github-cli). Con el token, ese `gh` llega a GitHub con el acceso que el token conceda y fuera de git gestionado por Anthropic, así que permite [`api.github.com`](#network-requirements).
294
295Con git gestionado por Anthropic, deja la GitHub CLI fuera de la imagen para usar el `gh` integrado en su lugar.
291 296
292#### Confíe en una autoridad de certificados privada con git gestionado por Anthropic297#### Confíe en una autoridad de certificados privada con git gestionado por Anthropic
293 298
343 348
344La reescritura de host se ejecuta primero, así que enumere el nombre de host interno en `--git-ssh-rewrite` si necesita ambos. Para control total sobre el checkout, use un [hook de ciclo de vida `checkout`](https://code.claude.com/docs/es/self-hosted-environments-configuration#checkout).349La reescritura de host se ejecuta primero, así que enumere el nombre de host interno en `--git-ssh-rewrite` si necesita ambos. Para control total sobre el checkout, use un [hook de ciclo de vida `checkout`](https://code.claude.com/docs/es/self-hosted-environments-configuration#checkout).
345 350
351### Inicia una sesión en un repositorio fuera de GitHub
352
353Para ejecutar una sesión en un repositorio de un host de git distinto de GitHub, inicia la sesión desde tu terminal, en un checkout de ese repositorio. Primero revisa las credenciales de git del runner, la red y el proxy de git, la dirección del repositorio y tu rama:
354
355* **Credenciales de git y red**: [proporciona credenciales](#ship-git-config-in-your-image) que [funcionen sin pedir nada](#git-must-work-without-a-prompt) para `https://<host>/<owner>/<name>`, la dirección que clona el runner, y permite que el runner llegue a tu host de git, como indica [Requisitos de red](#network-requirements). Para un host de git que solo acepta SSH, consulta [`--git-ssh-rewrite`](#rewrite-git-urls-for-private-networks).
356* **Proxy de git**: si los runners del entorno usan el proxy de git de Anthropic, [desactívalo](#turn-the-anthropic-git-proxy-off).
357* **Dirección del repositorio**: revisa el remoto `origin` del checkout. Su host debe ser un nombre de dominio como `git.example.com`, y su ruta debe tener la forma `<owner>/<name>`. Una ruta anidada como `group/subgroup/name` no es válida.
358* **Rama**: haz push a tu host de git de la rama en la que estás, porque el runner clona esa rama.
359
360En el checkout, con la sesión iniciada en claude.ai como describe [Autenticarse desde CI](https://code.claude.com/docs/es/self-hosted-environments-testing.md#authenticate-from-ci), ejecuta `claude -p` con [`--environment`](https://code.claude.com/docs/es/self-hosted-environments-testing#run-the-test-loop) y el ID `ccpool_...` de tu entorno:
361
362```bash theme={null}
363claude -p "Fix the login bug" --environment ccpool_abc123 --output-format json
364```
365
366Cuando se crea la sesión, el comando imprime una línea de JSON que empieza con `{"ok":true`. Si el remoto `origin` no cumple estos requisitos, el comando falla con `requires a git source, but no GitHub remote was detected`.
367
368Revisa y fusiona en tu host de git las ramas a las que las sesiones [hacen push](https://code.claude.com/docs/es/self-hosted-environments-configuration.md#prompt-sessions-to-push-their-work).
369
346## Construya la imagen del runner370## Construya la imagen del runner
347 371
348Anthropic no publica una imagen de runner precompilada. Construya la suya alrededor del binario `claude`, agregando cualquier cadena de herramientas que sus repositorios necesiten: tiempos de ejecución de lenguaje, compiladores, gestores de paquetes, y sidecars de [MCP](https://code.claude.com/docs/es/mcp.md).372Anthropic no publica una imagen de runner precompilada. Construya la suya alrededor del binario `claude`, agregando cualquier cadena de herramientas que sus repositorios necesiten: tiempos de ejecución de lenguaje, compiladores, gestores de paquetes, y sidecars de [MCP](https://code.claude.com/docs/es/mcp.md).
617 641
618### Dejar que los turnos en ejecución terminen antes de un reinicio642### Dejar que los turnos en ejecución terminen antes de un reinicio
619 643
620Para dejar que los turnos en ejecución terminen antes de un reinicio gradual, establece `--drain-wait-sec` y aumenta tu tiempo de parada a al menos esa espera más 80 segundos. Con la espera predeterminada de `0`, un reinicio interrumpe cualquier turno que aún esté en ejecución, y la sesión se reanuda en otro runner sin su [trabajo no enviado](#additional-limitations).644Para dejar que los turnos en ejecución terminen antes de un reinicio gradual, establece `--drain-wait-sec` y aumenta tu tiempo de parada a al menos esa espera más 80 segundos. Con la espera predeterminada de `0`, un reinicio interrumpe cualquier turno que aún esté en ejecución, y la sesión se reanuda en otro runner sin su [trabajo no enviado](#resumed-sessions-lose-unpushed-work).
621 645
622* **`--drain-wait-sec`**: aproximadamente lo que duran los turnos y las tareas en segundo plano que quieres dejar terminar. Es un máximo: la espera termina antes si ellos terminan primero.646* **`--drain-wait-sec`**: aproximadamente lo que duran los turnos y las tareas en segundo plano que quieres dejar terminar. Es un máximo: la espera termina antes si ellos terminan primero.
623* **Tu tiempo de parada**: `terminationGracePeriodSeconds` en Kubernetes, `stop_grace_period` en Docker Compose. Por ejemplo, con `--drain-wait-sec 120`, reemplaza el `90` en la receta de [Kubernetes](#kubernetes) o de [Docker Compose](#docker-compose) por `200`.647* **Tu tiempo de parada**: `terminationGracePeriodSeconds` en Kubernetes, `stop_grace_period` en Docker Compose. Por ejemplo, con `--drain-wait-sec 120`, reemplaza el `90` en la receta de [Kubernetes](#kubernetes) o de [Docker Compose](#docker-compose) por `200`.
735 759
736Para liberar las sesiones inactivas, inicia cada runner con [`--release-idle-session-min`](https://code.claude.com/docs/es/self-hosted-environments-reference#runner-cli-flags) y ese tiempo en minutos, como `--release-idle-session-min 30`. El runner libera entonces cualquier sesión que permanezca inactiva ese tiempo, ya sea que la haya iniciado una tarea programada o una persona, a menos que [la retengas por los procesos que dejó en ejecución](#keep-an-idle-session-while-its-processes-run).760Para liberar las sesiones inactivas, inicia cada runner con [`--release-idle-session-min`](https://code.claude.com/docs/es/self-hosted-environments-reference#runner-cli-flags) y ese tiempo en minutos, como `--release-idle-session-min 30`. El runner libera entonces cualquier sesión que permanezca inactiva ese tiempo, ya sea que la haya iniciado una tarea programada o una persona, a menos que [la retengas por los procesos que dejó en ejecución](#keep-an-idle-session-while-its-processes-run).
737 761
738* **Trabajo sin enviar**: una sesión liberada se reanuda con su siguiente mensaje, sin el trabajo que no había enviado con push. Para conservar sus commits, consulta [Las sesiones reanudadas pierden el trabajo sin enviar](#additional-limitations).762* **Trabajo sin enviar**: una sesión liberada se reanuda con su siguiente mensaje, sin el trabajo que no había enviado con push. Para conservar sus commits, consulta [Las sesiones reanudadas pierden el trabajo sin enviar](#resumed-sessions-lose-unpushed-work).
739* **El runner termina**: un runner que libera su última sesión inicia una [salida normal](#when-the-runner-exits). Haz que tu supervisor lo reinicie en un sistema de archivos limpio, como se describe en [Refuerza tu despliegue](#harden-your-deployment).763* **El runner termina**: un runner que libera su última sesión inicia una [salida normal](#when-the-runner-exits). Haz que tu supervisor lo reinicie en un sistema de archivos limpio, como se describe en [Refuerza tu despliegue](#harden-your-deployment).
740* **Sesiones que nunca quedan inactivas**: establece también [`--kill-session-after-min`](https://code.claude.com/docs/es/self-hosted-environments-reference#runner-cli-flags), porque [algunas sesiones no cuentan como inactivas](#some-sessions-don’t-count-as-idle)764* **Sesiones que nunca quedan inactivas**: establece también [`--kill-session-after-min`](https://code.claude.com/docs/es/self-hosted-environments-reference#runner-cli-flags), porque [algunas sesiones no cuentan como inactivas](#some-sessions-don’t-count-as-idle)
741 765
811* Si un turno aún se está ejecutando, el runner espera a que el turno termine, o a que la sesión espere a su usuario, y luego la libera.835* Si un turno aún se está ejecutando, el runner espera a que el turno termine, o a que la sesión espere a su usuario, y luego la libera.
812* Si la sesión aún está en el runner cuando la ventana de gracia termina, el runner la termina, y se pierde el trabajo de cualquier turno en ejecución. Un turno esperando una aprobación solicitada desde dentro de una llamada de herramienta en ejecución es una forma en que una sesión supera la ventana.836* Si la sesión aún está en el runner cuando la ventana de gracia termina, el runner la termina, y se pierde el trabajo de cualquier turno en ejecución. Un turno esperando una aprobación solicitada desde dentro de una llamada de herramienta en ejecución es una forma en que una sesión supera la ventana.
813 837
814Una sesión liberada se reanuda desde un clon nuevo, por lo que el trabajo que no había empujado se ha ido de cualquier forma; consulte [Las sesiones reanudadas pierden trabajo no empujado](#additional-limitations). Antes de v2.1.260, el runner terminaba cada sesión en el límite, después de esperar como máximo la ventana de gracia a que un turno en ejecución terminara.838Una sesión liberada se reanuda desde un clon nuevo, por lo que el trabajo al que no había hecho push se pierde de cualquier forma; consulta [Las sesiones reanudadas pierden el trabajo sin push](#resumed-sessions-lose-unpushed-work). Antes de v2.1.260, el runner terminaba cada sesión al llegar al límite, después de esperar como máximo la ventana de gracia a que terminara un turno en ejecución.
815 839
816Establezca la bandera anterior a su sesión más larga esperada, como `--kill-session-after-min 480` para 8 horas. Para liberar ranuras de conversaciones que se vuelven inactivas, use `--release-idle-session-min` en su lugar.840Establezca la bandera anterior a su sesión más larga esperada, como `--kill-session-after-min 480` para 8 horas. Para liberar ranuras de conversaciones que se vuelven inactivas, use `--release-idle-session-min` en su lugar.
817 841
842### Las sesiones reanudadas pierden el trabajo sin push
843
844Una sesión que se reanuda en un runner nuevo pierde el trabajo al que no había hecho push, porque ese runner vuelve a clonar el repositorio desde su rama inicial.
845
846Para conservar el trabajo con commit, establece [`--push-outcome-on-release`](https://code.claude.com/docs/es/self-hosted-environments-reference#runner-cli-flags) en todos los runners del entorno. Un runner con el flag hace, en la medida de lo posible, push de las ramas de resultado de la sesión antes de liberarla, y la sesión reanudada comienza desde esos commits. Un runner sin él reanuda la sesión desde su rama inicial. El push usa las credenciales de git propias del host del runner, incluso en un runner que usa [git administrado por Anthropic](#use-the-anthropic-git-proxy).
847
848> [!WARNING]
849>
850> Antes de establecer el flag, restringe quién puede hacer push a las refs `claude/*` en el remoto de origen. Al reanudar, el runner obtiene la rama a la que se hizo push previamente sin verificar quién hizo el push.
851
852Incluso con el flag establecido, guarda este trabajo de otra forma:
853
854* **Cambios sin commit**: se siguen perdiendo. Consulta [Pedir a las sesiones que hagan push de su trabajo](https://code.claude.com/docs/es/self-hosted-environments-configuration.md#prompt-sessions-to-push-their-work).
855* **Repositorios obtenidos mediante un [hook de ciclo de vida `checkout`](https://code.claude.com/docs/es/self-hosted-environments-configuration#checkout)**: a estos no se les hace push. Guarda una instantánea de ellos desde el [hook `post-session`](https://code.claude.com/docs/es/self-hosted-environments-configuration#post-session).
856* **Commits en una sesión que alguien archiva o elimina, o cuyo runner libera desde el menú de la sesión**: no cuentes con el push del flag. Para guardarlos, haz push de `HEAD` a una rama de rescate desde un [hook `post-session`](https://code.claude.com/docs/es/self-hosted-environments-configuration#post-session). El ejemplo de esa sección solo hace push después de un commit de instantánea, así que haz que el tuyo haga push incluso cuando no haya nada sin commit.
857
818### Limitaciones adicionales858### Limitaciones adicionales
819 859
820* **Las sesiones reanudadas pierden el trabajo sin push**: un runner nuevo vuelve a clonar el repositorio desde su rama inicial, por lo que el trabajo al que la sesión no había hecho push se pierde.
821 * **Para conservar el trabajo con commit**: establece [`--push-outcome-on-release`](https://code.claude.com/docs/es/self-hosted-environments-reference#runner-cli-flags) en todos los runners del entorno, porque un runner sin el flag reanuda la sesión desde su rama inicial. Un runner con el flag hace, en la medida de lo posible, push de las ramas de resultado de la sesión antes de liberarla, y la sesión reanudada comienza desde esos commits. El push usa las credenciales de git propias del host del runner, incluso en un runner que usa [git administrado por Anthropic](#use-the-anthropic-git-proxy).
822 * **Con un hook `checkout`**: a los repositorios obtenidos mediante un [hook de ciclo de vida `checkout`](https://code.claude.com/docs/es/self-hosted-environments-configuration#checkout) no se les hace push. En su lugar, guarda una instantánea de ellos desde el [hook `post-session`](https://code.claude.com/docs/es/self-hosted-environments-configuration#post-session).
823 * **Antes de habilitar el flag**: restringe quién puede hacer push a las refs `claude/*` en el remoto de origen. Al reanudar, el runner obtiene la rama a la que se hizo push previamente sin verificar quién hizo el push.
824 * **Los cambios sin commit se siguen perdiendo**: para pedirle a Claude que haga commit y push cuando termine de responder, consulta [Pedir a las sesiones que hagan push de su trabajo](https://code.claude.com/docs/es/self-hosted-environments-configuration.md#prompt-sessions-to-push-their-work)
825* **Un comando interrumpido por la pérdida de un runner puede volver a ejecutarse**: cuando la sesión se reanuda en otro runner, Claude ve la llamada a herramienta interrumpida con un resultado que indica que su desenlace es desconocido.860* **Un comando interrumpido por la pérdida de un runner puede volver a ejecutarse**: cuando la sesión se reanuda en otro runner, Claude ve la llamada a herramienta interrumpida con un resultado que indica que su desenlace es desconocido.
826* **Un repositorio agregado a mitad de sesión puede fallar al clonarse**: Claude lo clona con `git clone` a través de HTTPS. En un runner sin [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy), la clonación falla con un error de autenticación de git si nada en el host puede leer el repositorio. Siempre que puedas, selecciona todos los repositorios que la sesión necesita al crearla.861* **Un repositorio agregado a mitad de sesión puede fallar al clonarse**: Claude lo clona con `git clone` a través de HTTPS. En un runner sin [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy), la clonación falla con un error de autenticación de git si nada en el host puede leer el repositorio. Siempre que puedas, selecciona todos los repositorios que la sesión necesita al crearla.
827 * **Cuando la sesión se reanuda**: un [hook `checkout`](https://code.claude.com/docs/es/self-hosted-environments-configuration#checkout) también se ejecuta para el repositorio agregado, con [`CLAUDE_RUNNER_REPO_REF`](https://code.claude.com/docs/es/self-hosted-environments-configuration#checkout) vacío, así que asegúrate de que tu hook maneje ese caso.862 * **Cuando la sesión se reanuda**: un [hook `checkout`](https://code.claude.com/docs/es/self-hosted-environments-configuration#checkout) también se ejecuta para el repositorio agregado, con [`CLAUDE_RUNNER_REPO_REF`](https://code.claude.com/docs/es/self-hosted-environments-configuration#checkout) vacío, así que asegúrate de que tu hook maneje ese caso.
828* **Algunos conectores no aparecen en sesiones autohospedadas**: un conector que aún no ha conectado en la configuración de claude.ai no se enumera en una sesión autohospedada, y la sesión no le pedirá que lo conecte. Conéctelo en Configuración primero, luego inicie una sesión nueva. Agregar un conector a una sesión ya en ejecución tampoco hace que sus herramientas estén disponibles para Claude; inicie una sesión nueva para recoger un conector recién agregado.863* **Algunos conectores no aparecen en sesiones autohospedadas**: un conector que aún no ha conectado en la configuración de claude.ai no se enumera en una sesión autohospedada, y la sesión no le pedirá que lo conecte. Conéctelo en Configuración primero, luego inicie una sesión nueva. Agregar un conector a una sesión ya en ejecución tampoco hace que sus herramientas estén disponibles para Claude; inicie una sesión nueva para recoger un conector recién agregado.
829* **Cuando alguien archiva o elimina una sesión, o libera su runner desde el menú de la sesión**: no cuentes con el push de [`--push-outcome-on-release`](https://code.claude.com/docs/es/self-hosted-environments-reference#runner-cli-flags). Para guardar los commits en esos casos, haz push de `HEAD` a una rama de rescate desde un [hook `post-session`](https://code.claude.com/docs/es/self-hosted-environments-configuration#post-session). Si partes del ejemplo de esa sección, haz que haga push incluso cuando no haya nada sin commit, porque solo hace push después de un commit de instantánea.
830 864
831### Reportar un problema865### Reportar un problema
832 866
