devopsandClaude Sonnet 5
a77a6f2fd0
Tras un corte de luz real, la sesion tmux "lab" se recreaba sola pero Claude Code nunca arrancaba adentro -- distinto al caveat de persistencia de sesion ya documentado (ese es "el proceso muere, el contenedor sigue vivo"; esto es "el host completo se apaga y arranca de cero"). Documenta las dos causas encontradas (claude nunca se lanzaba tras recrear la sesion; riesgo de carrera con el mount de /media/HDD-Storage) y el fix aplicado en scripts/tmux-host/healthcheck.sh. Co-Authored-By: Claude Sonnet 5 <[email protected]>
333 lines
17 KiB
Markdown
333 lines
17 KiB
Markdown
# 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
|
|
|
|
```mermaid
|
|
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.
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
/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:
|
|
|
|
```bash
|
|
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`.
|