Codex Live Session
Arquitectura
Codex trabaja dentro de la única sesión tmux "aeos-dev". El servicio ttyd adjunta un cliente web de solo lectura a esa sesión y escucha exclusivamente en "127.0.0.1:7681". Nginx publica el transporte HTTP y WebSocket bajo "/development/terminal/live/", mientras Spring Boot sirve la página "/development/terminal".
Codex -> tmux aeos-dev -> ttyd solo lectura -> Nginx -> /development/terminal
No existe escritorio gráfico, X11, VNC ni acceso directo a ttyd desde la red. La opción "--writable" de ttyd no se utiliza.
Componentes instalados
- tmux 3.3a-3, instalado desde Debian 12 mediante APT.
- ttyd 1.7.7, binario oficial x86_64 instalado en /usr/local/bin/ttyd después de verificar SHA256SUMS.
La dependencia nativa libevent-core-2.1-7 es instalada automáticamente por APT para tmux. No se instala ningún escritorio, servidor gráfico o servicio de escritorio remoto.
Funcionamiento
"aeos-dev.service" ejecuta un script idempotente al arrancar. Si la sesión exacta "aeos-dev" existe, la reutiliza; si no existe, crea una sola sesión con "/opt/esp-platform/repo" como directorio de trabajo. tmux mantiene la sesión aunque no haya clientes conectados.
"esp-platform-ttyd.service" depende de la sesión y ejecuta ttyd como el usuario "codex". El navegador solo recibe la salida de terminal y no puede escribir, pegar, enviar teclas ni interrumpir procesos.
Conexión
La vista HTTPS normal está disponible en:
https://iot.aeizoon.com/development/terminal
Para trabajar desde SSH dentro de la misma sesión:
tmux attach-session -t aeos-dev
Para salir sin detenerla, use la secuencia tmux "Ctrl+B", seguida de "D".
Operación
Comprobar o recrear la sesión si falta, sin duplicarla:
sudo systemctl restart aeos-dev.service
Reiniciar la publicación web sin detener tmux:
sudo systemctl restart esp-platform-ttyd.service
Consultar estado y logs:
systemctl status aeos-dev.service esp-platform-ttyd.service
journalctl -u esp-platform-ttyd.service -n 100 --no-pager
Verificación
tmux list-sessions
systemctl is-active aeos-dev.service esp-platform-ttyd.service nginx
ss -ltnp | grep 7681
curl -I http://127.0.0.1:7681/development/terminal/live/
curl -I http://127.0.0.1:88/development/terminal
Debe existir exactamente una sesión "aeos-dev"; ttyd debe escuchar solo en "127.0.0.1:7681"; la página debe responder a través de Nginx. El servicio ttyd no debe contener "--writable" ni "-W".
Configuración versionada
- "scripts/ensure-aeos-dev-session.sh": creación idempotente de la sesión.
- "infrastructure/systemd/aeos-dev.service": persistencia tras reinicio.
- "infrastructure/systemd/esp-platform-ttyd.service": ttyd de solo lectura.
- "infrastructure/nginx/codex-live-session.conf": proxy WebSocket.
Los archivos efectivos se instalan en "/etc/systemd/system/" y en el sitio Nginx de ESP Platform. Los cambios se realizan primero en el repositorio y después se despliegan.
Política de redimensionado
La sesión utiliza la política global "window-size largest" de tmux 3.3a y mantiene "aggressive-resize off". Con varios clientes conectados, la ventana toma las dimensiones del cliente más grande; una conexión SSH de 80x24 no puede reducir la vista web.
ttyd fija "fontSize=18" y "lineHeight=1.35". El navegador permanece en modo de solo lectura porque ttyd no se inicia con "--writable" ni "-W". El cliente tmux no usa "attach-session -r": tmux 3.3a excluye los clientes de solo lectura del cálculo de tamaño y eso impediría que la vista web aportase sus dimensiones a "window-size largest".
La página reajusta xterm.js tras la carga del iframe, una recreación del terminal, cambios del contenedor, cambios de pantalla completa y redimensionados de la ventana. Se usa "ResizeObserver", con dos reintentos cortos después de cada evento; no existe un bucle periódico de redimensionado.
Durante una caída del WebSocket la vista puede mostrar temporalmente el estado de desconexión. Al reabrirse la conexión, ttyd conserva o recrea el terminal y el observador vuelve a ajustarlo al contenedor.
Para verificar la política:
tmux show-window-options -g | grep -E 'window-size|aggressive-resize'
tmux list-clients -F '#{client_tty} #{client_width}x#{client_height} readonly=#{client_readonly}'
tmux list-windows -F '#{session_name} #{window_index} #{window_width}x#{window_height}'