Lia conectada al Miniverse — heartbeat de un agente en mi homelab

El Miniverse no es un juego. Es el panel visual de mi homelab: cada servicio, cada VM, cada agente aparece como un sprite animado en un mapa vivo. Hace unos días integré a Lia, el agente que corre en mi VPS de Oracle Cloud, como un sprite más dentro de ese sistema.

Y para que un sprite sea algo más que una imagen estática, necesita enviar estado. Así que monté el enlace.

La arquitectura — un salto y un túnel

Lia no está en mi red local. Corre en un VPS Ubuntu en Oracle Cloud (82.70.92.125), detrás de NAT y sin acceso directo a la API del Miniverse, que escucha en 192.168.50.63:4321 — dentro de mi LAN.

La solución: un túnel SSH desde Lia hasta Palomino, mi agente de infraestructura que sí está en la red local (100.114.224.89 por Tailscale). El túnel expone un localhost:4321 en el VPS que en realidad es 192.168.50.63:4321 en casa.

Lia (VPS, 82.70.92.125)
  → SSH tunnel a palomino (100.114.224.89)
    → curl localhost:4321/api/heartbeat
      → Miniverse API (192.168.50.63:4321)

El túnel lo mantiene abierto systemd con auto-reconnect. Si el VPS se reinicia, el túnel vuelve a levantarse solo.

Los scripts — un heartbeat cada 30 segundos

Dos scripts bash, un propósito:

miniverse_heartbeat.sh — envía un heartbeat único. Recibe estado y tarea opcional, y manda un POST a la API con el payload correspondiente.

./miniverse_heartbeat.sh working "procesando peticiones de Christian"
# Estados disponibles: working, idle, thinking, sleeping, speaking, error

miniverse_loop.sh — un bucle infinito que ejecuta el heartbeat cada 30 segundos. Corre en background vía nohup y escribe logs a /tmp/miniverse_lia.log.

Treinta segundos no es un número al azar. Es el mínimo que la API del Miniverse espera: si un sprite no envía heartbeat en ese intervalo, pasa a estado offline automáticamente. Suficiente granularidad para ver actividad en tiempo real sin saturar la API.

Estados de Lia en el Miniverse

El sprite de Lia (alias nova) puede estar en tres estados:

• working — coordinación activa, procesando tareas
• idle — sin actividad reciente, disponible
• resting — más de 15 minutos inactivo (pendiente de implementar)

Cada estado cambia el sprite visualmente en el mapa. Si no hay heartbeat en 30 segundos, el sprite se vuelve gris — caída del túnel, script detenido, o VPS caído. Lo veo al instante sin mirar logs.

Independencia del sistema de coordinación

Lia y Palomino se comunican también mediante un sistema de archivos JSON en el NAS — el canal principal para peticiones y respuestas. El heartbeat del Miniverse corre completamente aparte. No se interfieren.

Esto es intencionado: el heartbeat puede fallar sin bloquear la comunicación entre agentes, y viceversa. Dos capas independientes con un único punto en común: el túnel SSH.

Lo que sigue

Por ahora el estado lo actualiza el script manualmente según lo que Lia esté haciendo. El siguiente paso es que el propio agente actualice su estado automáticamente según la actividad del portfolio — si está escribiendo un post, el Miniverse lo refleja sin que yo intervenga.

Si tienes dudas sobre cómo montar algo similar, contacta a Christian.