apps-registry/workloads/docs-portal/docs/arquitectura/sesion-tmux-persistente.md

Sesión persistente de Claude Code (tmux en Docker)

Problema que resuelve

Correr Claude Code directo en una shell SSH sobre el NAS lo ata al ciclo de vida de esa conexión: un corte de red, cambiar de laptop a tablet, o cerrar la terminal por accidente mata el proceso y con él todo el contexto de trabajo en curso — no hay forma de "retomar donde quedó" porque el proceso ya no existe.

Esto es un problema distinto al de los límites de uso/cuota de Claude Code. Este setup no aumenta cuota de mensajes ni tokens — eso lo controla el backend de Anthropic sin importar dónde corra el CLI. Lo único que resuelve es que la sesión de terminal sobreviva a cortes de red o cambios de dispositivo; si la cuota se agota, sigue agotada exactamente igual dentro de este setup.

Por qué Docker y no instalación nativa

ZimaOS no tiene gestor de paquetes tradicional utilizable para esto: / está montado como squashfs de solo lectura (imagen del SO inmutable), y /usr es un overlay de solo lectura sobre eso — /usr/local/bin ni siquiera existe y no se puede crear, tampoco como root (mkdir falla con "Read-only file system"). No hay dónde instalar Node.js, npm ni tmux directamente sobre el host.

Un contenedor Docker sortea esto por completo: tiene su propio filesystem de escritura (overlay2), independiente del squashfs del host — ahí es donde npm install -g deja el binario de claude sin tocar el host en absoluto. Lo único que el contenedor toma del host es lo que se monta explícitamente como volumen.

Arquitectura

flowchart LR
    SSH["Cliente SSH<br/>(laptop / tablet / lo que sea)"] -->|docker exec| C["Contenedor tmux-host<br/>--network host, --restart unless-stopped"]
    C --> T["tmux server<br/>sesión 'lab'"]
    T --> CC["proceso claude<br/>(Claude Code)"]
    C --> HC["healthcheck.sh (background)<br/>cada 30 min"]
    HC -.->|curl| NET["gitea.cruzcloud.net"]
    HC -.->|recrea si falta| T
    C -.->|bind mount| DATA["/DATA (host)<br/>repos y configs del lab"]
    C -.->|bind mount| SOCK["/var/run/docker.sock (host)<br/>control de Docker/k3d"]
    C -.->|bind mount| HOME["/DATA/AppData/k3d-lab-v3/claude-code-home (host)<br/>-> /root/.claude"]

El contenedor sigue vivo aunque la conexión SSH se corte — es el servidor tmux, no la shell del cliente, el que sostiene el proceso de Claude Code. --restart unless-stopped además lo revive si el NAS reinicia.

Contenedor: tmux-host

La imagen se construye desde scripts/tmux-host/Dockerfile (antes era un docker run ... alpine sh -c "apk add ..." inline — mismo contenido, pero ahora como imagen versionada en vez de reinstalar todo en cada arranque). El Dockerfile fija WORKDIR /DATA/AppData/k3d-lab-v3/lab-cruzcloud (la raíz del lab, con CLAUDE.md, apps-registry/, platform-infra/ y scripts/) y agrega healthcheck.sh (ver más abajo) como proceso en background del contenedor.

docker build -t tmux-host:local scripts/tmux-host

docker run -d \
  --name tmux-host \
  --restart unless-stopped \
  -v /DATA:/DATA \
  -v /media/HDD-Storage:/media/HDD-Storage \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /DATA/AppData/k3d-lab-v3/claude-code-home:/root/.claude \
  -v /DATA/AppData/k3d-lab-v3/claude-code-home.json:/root/.claude.json \
  --network host \
  tmux-host:local

WORKDIR hace que docker exec (y por lo tanto lab-session.sh) arranquen ya posicionados en la raíz del lab sin tener que navegar a mano — lab-session.sh además pasa la ruta explícita vía tmux new -c por las dudas, para no depender de que docker exec herede el WORKDIR de la imagen.

Volumen	Destino	Por qué
/DATA	/DATA	Acceso a los repos (apps-registry, platform-infra, scripts) y configs del lab, mismos paths que en el host
/media/HDD-Storage	/media/HDD-Storage	Ver "Gotcha: el symlink /DATA/AppData" abajo — sin esto, los repos no se ven dentro del contenedor pese a montar /DATA
/var/run/docker.sock	/var/run/docker.sock	Seguir controlando Docker y k3d (contenedores, k3d node, etc.) desde dentro del contenedor
/DATA/AppData/k3d-lab-v3/claude-code-home	/root/.claude	Persistir login/config de Claude Code — sobrevive no solo a un docker restart, sino a recrear el contenedor entero
/DATA/AppData/k3d-lab-v3/claude-code-home.json	/root/.claude.json	Ver "Gotcha: la confianza del folder no persistía" abajo — es un archivo suelto, no vive dentro de ~/.claude/

Gotcha: el symlink /DATA/AppData

Montar -v /DATA:/DATA no alcanza para ver los repos dentro del contenedor. /DATA/AppData en el host es un symlink absoluto:

/DATA/AppData -> /media/HDD-Storage/AppData

Los repos del lab (lab-cruzcloud) viven físicamente en el disco btrfs /media/HDD-Storage, no en el ext4 de /DATA — ZimaOS lo expone dentro de /DATA como submount (/DATA/.media/HDD-Storage/..., que sí viaja al contenedor porque Docker hace bind recursivo por defecto) pero el path "bonito" /DATA/AppData/... que usan CLAUDE.md y todos los scripts del lab llega ahí vía ese symlink absoluto, no vía el submount. Un symlink absoluto que apunta fuera del árbol montado queda roto dentro del contenedor aunque el submount subyacente esté perfectamente accesible por otra ruta.

Cómo se detectó: todo el trabajo de configuración inicial de este mismo setup se hizo con git/docker exec corriendo en el host, no dentro del contenedor — nadie había probado cd /DATA/AppData/k3d-lab-v3/lab-cruzcloud desde una sesión lab real hasta que se preguntó explícitamente por esto. ls devolvía "No such file or directory" pese a que el volumen de /DATA estaba montado y "andando".

Fix: montar también -v /media/HDD-Storage:/media/HDD-Storage, para que el symlink resuelva exactamente igual que en el host.

Gotcha: git "dubious ownership" dentro del contenedor

Con el mount anterior ya arreglado, git status/git log dentro del contenedor fallan con:

fatal: detected dubious ownership in repository at '/media/HDD-Storage/...'

Los archivos en /DATA//media/HDD-Storage pertenecen al usuario devops del host (via samba), pero los procesos dentro del contenedor corren como root (UID 0) — git, desde la versión que introdujo la protección CVE-2022-24765, rechaza operar sobre un repo cuyo dueño no coincide con el UID del proceso, a menos que el path esté explícitamente marcado como seguro.

Fix: git config --global --add safe.directory '*' dentro del contenedor. El wildcard (en vez de listar cada repo) es intencional acá: este contenedor ya tiene acceso root-equivalente al host vía el volumen de /var/run/docker.sock, así que restringir safe.directory por repo no suma aislamiento real.

Por qué está en el comando de arranque y no como paso manual aparte: igual que los paquetes apk, esta configuración vive en el filesystem efímero del contenedor (/root/.gitconfig, que no está bajo el volumen de /root/.claude) — se perdería si el contenedor se recrea. Ponerla en el sh -c de arranque la deja recreándose sola cada vez, sin pasos manuales que recordar.

Gotcha: la confianza del folder no persistía

Al abrir claude por primera vez en un directorio, pide confirmar un diálogo de "¿confiás en este folder?" (más aún acá, porque este repo trae un .claude/settings.local.json con permisos pre-aprobados). Esa confirmación se guarda en ~/.claude.json — un archivo suelto en /root, no dentro de la carpeta ~/.claude/ que ya estaba montada como volumen. Resultado: aunque el login (~/.claude/.credentials.json) sí persistía, el diálogo de confianza volvía a aparecer cada vez que se recreaba el contenedor — justo el tipo de "reconfigurar de nuevo" que este setup existe para evitar.

Cómo se detectó: al confirmar el diálogo por primera vez, se comparó /root/.claude.json dentro del contenedor contra sí mismo antes y después — mismo tamaño y mismo mtime, es decir, la confirmación en pantalla nunca se había registrado. La causa real: la primera vez se movió el selector con las flechas pero nunca se presionó Enter, así que en rigor el diálogo seguía sin confirmar; una vez confirmado de verdad (tmux send-keys moviendo el cursor a "Yes, I trust this folder" + Enter), el archivo saltó de 2.2 KB a 40 KB y apareció la clave projects con la ruta del repo adentro.

Fix: copiar ese .claude.json ya confirmado a /DATA/AppData/k3d-lab-v3/claude-code-home.json en el host, y montarlo archivo a archivo (no como carpeta) en -v .../claude-code-home.json:/root/.claude.json. A diferencia de los demás volúmenes de este setup, este necesitó sembrarse con contenido real primero — un bind mount de archivo con un origen que no existe todavía en el host termina creando un directorio vacío en su lugar, no un archivo, y rompe el arranque del contenedor. Verificado en vivo: tras recrear el contenedor con este mount, claude arrancó directo en la sesión normal, sin volver a pedir el diálogo de confianza.

Sobre paquetes: alpine (imagen alpine sin pin de versión, la misma que uso este setup) sí trae kubectl en sus repos — no hizo falta cambiar de imagen base ni instalarlo por binario aparte, contrario a lo que se sospechaba inicialmente. nodejs/npm (v24/v11 al momento de escribir esto) también están en los repos de alpine y cumplen de sobra el mínimo que pide Claude Code.

Nota sobre --network host + docker.sock: el contenedor tiene, en la práctica, control equivalente a root sobre el NAS (puede lanzar cualquier otro contenedor con cualquier mount). Es una concesión deliberada — es exactamente lo que hace falta para seguir operando Docker/k3d desde dentro — no un descuido.

Reconexión: un solo comando

/media/HDD-Storage/AppData/k3d-lab-v3/lab-cruzcloud/scripts/lab-session.sh

El script (scripts/lab-session.sh) es intencionalmente el mismo comando sin importar el estado previo:

docker exec -it "$CONTAINER" tmux attach -t "$SESSION" || \
  docker exec -it "$CONTAINER" tmux new -s "$SESSION"

Si la sesión lab existe, se adjunta a ella (mismo shell, mismo claude corriendo, mismo directorio de trabajo). Si no existe —por ejemplo justo después de que el contenedor se recreó desde cero— la crea. No hay que recordar cuál de los dos casos aplica.

Chequeo de salud automático (cada 30 min)

scripts/tmux-host/healthcheck.sh corre en background dentro del propio contenedor (lanzado por entrypoint.sh, el ENTRYPOINT de la imagen) y cada HEALTHCHECK_INTERVAL_SEC (1800s por defecto) hace dos chequeos independientes, con una respuesta distinta según el tipo de falla:

• Conectividad de red real (curl a https://gitea.cruzcloud.net/): si falla, solo se registra en el log y se notifica por Telegram — el contenedor nunca intenta "arreglar" la red del host. Un problema de red puede ser de hardware/BIOS (deuda técnica ya conocida, ver incidente-medusa-crashloop-2026-08.md), fuera del alcance real de un contenedor.
• Existencia de la sesión tmux lab (tmux has-session): si no existe, sí se recrea automáticamente (tmux new-session -d -s lab -c <WORKDIR>, seguido de tmux send-keys -t lab claude Enter — ver gotcha "sesión recreada pero sin Claude Code adentro" más abajo) — es solo recuperar el propio entorno de trabajo del contenedor, no tocar infraestructura externa, así que es seguro hacerlo sin intervención humana. Si WORKDIR todavía no está montado (ver gotcha siguiente), no se crea la sesión esa vuelta — se reintenta en el próximo ciclo en vez de crearla mal posicionada.

Todo evento (chequeo ok, falla de red, sesión recreada) queda en /DATA/AppData/k3d-lab-v3/tmux-host/logs/health.log — persistente en /DATA, no solo en el stdout del contenedor (que se pierde con docker logs al recrearlo). Las notificaciones de Telegram reusan el mismo bot/chat_id ya configurado para scripts/lab-agent/ (lab-agent.env), en vez de duplicar credenciales entre los dos agentes del lab.

Para probar el intervalo sin esperar 30 minutos, se puede levantar el contenedor con -e HEALTHCHECK_INTERVAL_SEC=60 (solo para pruebas en un contenedor descartable — nunca cambiar esto en el tmux-host real sin volver a 1800 después).

Gotcha: sesión recreada, pero sin Claude Code adentro (reinicio completo del NAS, 2026-09-19)

Distinto al caveat de persistencia de sesión de más abajo (ese cubre "el proceso muere pero el contenedor sigue vivo" — cerrar la sesión lab a mano, o un crash del propio claude). Este es otro escenario: el HOST completo se apaga y vuelve a arrancar desde cero (corte de luz, no un docker restart ordenado) — reordena cuándo arrancan Docker, la red y los montajes de /DATA//media/HDD-Storage entre sí, algo que un docker restart normal nunca ejercita porque el host ya estaba arriba.

Tras un corte de luz real, se encontró que el usuario se reconectó a la sesión lab y encontró un shell vacío, no Claude Code corriendo. Dos causas distintas, ambas corregidas:

1. La sesión tmux SÍ se recreaba sola (confirmado en health.log: el contenedor arrancó y la sesión lab quedó recreada en cuestión de segundos), pero check_tmux_session() nunca lanzó claude adentro — solo garantizaba que existiera el shell, no que el proceso de Claude Code estuviera corriendo. El diagrama de arquitectura de este mismo doc siempre mostró T --> CC["proceso claude"] como si fuera automático, pero el código nunca lo implementó — el hueco quedó invisible mientras nadie pasó por un reinicio completo real del NAS (en un docker restart normal, el claude que ya estaba corriendo dentro de la sesión simplemente sigue vivo, porque ahí el proceso no muere). Fix: check_tmux_session() ahora llama launch_claude_in_session() (tmux send-keys -t lab claude Enter) justo después de crear la sesión — solo cuando la crea de cero, nunca sobre una sesión que ya existe (no se reinyecta claude sobre un pane con trabajo en curso).
2. Riesgo de carrera no ejercitado todavía, pero real: WORKDIR (/DATA/AppData/k3d-lab-v3/lab-cruzcloud) llega vía el symlink absoluto /DATA/AppData -> /media/HDD-Storage/AppData (ver el gotcha del symlink más arriba). Si el storage externo (/media/HDD-Storage) tarda en montarse en el host más de lo que tarda Docker en arrancar este contenedor — plausible después de un corte de luz, no de un simple restart —, mkdir -p "$LOG_DIR" fallaba en silencio (set -u sin -e) y ese arranque quedaba sin ningún rastro en el log, y tmux new-session -c "$WORKDIR" habría creado la sesión mal posicionada (o fallado) contra un directorio que todavía no existe. Fix: wait_for_workdir() reintenta con backoff (pasos de 5s, hasta STARTUP_MOUNT_WAIT_MAX_SEC=120 por defecto) a que WORKDIR exista antes de tocar el log o crear la sesión; si sigue sin existir pasado ese máximo, se registra el error explícitamente y se reintenta en el siguiente ciclo (30 min) en vez de fallar una sola vez y quedarse así.

Validado en vivo: imagen reconstruida (tmux-host:test-fix) y probada en un contenedor descartable aparte (mismos mounts de /DATA y /media/HDD-Storage, sin tocar el tmux-host real) — docker stop + docker start (arranque desde cero, no restart) recreó la sesión lab con claude corriendo adentro sin intervención manual, en ~1 segundo.

Qué sobrevive a qué

Evento	¿Sobrevive la sesión tmux (lab)?	¿Sobrevive el login de Claude Code?
Corte de SSH / cerrar la terminal / cambiar de dispositivo	Sí — es exactamente el caso que este setup resuelve	Sí
docker restart tmux-host (reinicio del NAS)	No al toque, pero se auto-recupera solo — el proceso tmux server muere con el contenedor; healthcheck.sh la recrea en el próximo ciclo (máx. 30 min) sin intervención, o lab-session.sh la crea al instante si alguien se reconecta antes	Sí, vía el volumen montado en /root/.claude
docker rm + recrear el contenedor desde cero	No, pero igual se auto-recupera sola (mismo mecanismo de arriba)	Sí, vía el mismo volumen — no hace falta volver a autenticar ni reconfirmar el diálogo de confianza del folder (ver el mount de claude-code-home.json)
Falla de red real del host/NAS	N/A	N/A — healthcheck.sh la detecta y notifica, pero no la corrige (fuera de su alcance)

Validación en vivo

Confirmado en este mismo lab (2026-08-27): se dejó una variable de entorno (export MARCA_PERSISTENCIA=ok_<timestamp>) corriendo dentro de la sesión lab vía tmux send-keys, y una invocación completamente separada de docker exec (equivalente a una nueva conexión) leyó de vuelta el mismo valor — confirma que el estado vive en el servidor tmux del contenedor, no en el cliente que se conecta. claude --version respondió 2.1.250 dentro de esa misma sesión, y un archivo de prueba escrito en /root/.claude dentro del contenedor apareció de inmediato en /DATA/AppData/k3d-lab-v3/claude-code-home en el host, confirmando el bind mount de credenciales.

Después de agregar el mount de /media/HDD-Storage y el safe.directory, se validó además: md5sum de CLAUDE.md idéntico leído desde el host y desde dentro del contenedor (vía el path con symlink /DATA/AppData/...), y git log/git status corriendo sin error sobre apps-registry y scripts desde una shell dentro de tmux-host.