Setup script de Claude Code en la nube: por qué falla y por qué tarda

TL;DR En el setup script, solo las herramientas que no trae la máquina, y que termine en menos de cinco minutos. El npm install de tu proyecto va en un hook SessionStart que solo corre en la nube.

El setup script de un entorno en la nube se ejecuta como root en Ubuntu 24.04, antes de que arranque Claude Code. Si termina en unos cinco minutos, Anthropic guarda una foto del disco y las sesiones siguientes arrancan desde ella sin volver a ejecutarlo. De ese mecanismo salen los dos problemas: el script que tumba la sesión y la sesión que tarda en arrancar.

El reparto que los evita:

Setup script (en el entorno)    herramientas de la máquina   una vez, con caché
Hook SessionStart (en el repo)  dependencias del proyecto    en cada sesión

Por qué falla la instalación

Si el script sale con un código distinto de cero, la sesión no arranca. Las causas habituales:

Para ver qué comando falla, empieza el script con set -x. A lo que no sea crítico ponle || true detrás, así un fallo puntual no te deja sin sesión.

Una diferencia que despista: un cambio de acceso a la red llega a las sesiones abiertas en un minuto, pero un cambio en el script solo lo ve una sesión nueva.

Por qué tarda en arrancar

1. Pasarte de cinco minutos te deja sin foto

El entorno no se guarda en caché, así que cada sesión nueva vuelve a pasar por el script, y puede colgarse o fallar con un error genérico del contenedor. Lanza en paralelo lo que no depende entre sí:

#!/bin/bash
set -x
(apt update && apt install -y shellcheck) &
docker pull mcr.microsoft.com/mssql/server:2022-latest &
wait

Si una descarga sola no cabe en el presupuesto, sácala a un hook SessionStart que la lance en segundo plano. Y quita los sleep de los reintentos: cuentan contra los cinco minutos.

2. La foto guarda archivos, no procesos

Los paquetes, las imágenes de Docker y los ficheros que escribe el script sobreviven. Un PostgreSQL que arrancó el script o un docker compose up no. Pídele a Claude que los arranque en cada sesión, o hazlo en el hook.

3. La foto no se entera de tu package.json

Solo se rehace cuando cambias el script o los dominios permitidos, o cuando caduca, a los siete días más o menos. Si cambias las dependencias del proyecto, el script no vuelve a ejecutarse hasta entonces. Por eso esas dependencias van en otro sitio.

Setup script o hook SessionStart

1. Añade el hook al repo

En .claude/settings.json, como cualquier otro hook:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR\"/scripts/install_pkgs.sh"
          }
        ]
      }
    ]
  }
}

2. Escribe el script que llama

En scripts/install_pkgs.sh:

#!/bin/bash
if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then
  exit 0
fi
cd "$CLAUDE_PROJECT_DIR" || exit 1
npm install

CLAUDE_CODE_REMOTE vale true en la máquina de la nube y nunca en la tuya, así que en tu portátil el script sale sin instalar nada. La versión de la documentación guarda además un hash de package.json y package-lock.json y se salta npm install si no han cambiado, para que el hook no sume tiempo a cada arranque.

Tres límites del hook:

• Tiene que estar en el repo. Los hooks de tu ~/.claude/settings.json no viajan a la nube.
• Se corta a los 600 segundos si no le pones timeout.
• Una sesión con varios repos no carga el .claude/settings.json de ninguno. Ahí las dependencias vuelven al setup script.

Documentación oficial: Configure cloud environments · Troubleshoot setup

Requisitos

• Plan Pro, Max o Team (o Enterprise con asiento premium) y GitHub conectado.
• Comprobado contra la documentación el 15 de octubre de 2026. La foto, el límite de cinco minutos y los siete días son aproximados según Anthropic.