Proxmox-Coolify-Manager/docs/casos/hermes-minimax-m3-setup.md

# Caso: Restauración SSH Proxmox, Actualización de Hermes (LXC 100) y Configuración de MiniMax-M3

> Documentación de caso verificada el **2026-08-18** desde esta máquina.
> Target: **Host Proxmox (`thinkcentre`)** + **LXC 100 (`hermes`)**.

---

## 0. Resumen ejecutivo

- **Contexto:**
  - El host Proxmox (`192.168.0.200`, nodo `thinkcentre`) y sus interfaces de red asociadas (`192.168.3.23` / `192.168.3.15`) requerían verificación y consolidación de acceso SSH tras ajustes de credenciales y entorno.
  - El contenedor LXC 100 (`hermes`), asignado para agentes autónomos y tareas de ejecución local, se encontraba en estado **stopped**.
  - Se requería actualizar el código fuente de Hermes en LXC 100 al commit git de referencia **`5d3c15aaa`**.
  - Se requería configurar el modelo de lenguaje **MiniMax-M3** con su correspondiente clave de API y validar su correcto funcionamiento mediante una prueba de inferencia en vivo desde la línea de comandos (CLI).

- **Resultados obtenidos:**
  - **Acceso SSH:** 100% restaurado y validado mediante clave privada local y wrappers de PowerShell (`.\scripts\Test-ProxmoxConnection.ps1` y `.\scripts\Invoke-ProxmoxSsh.ps1`).
  - **LXC 100 (Hermes):** Estado cambiado a **running** y verificado con `pct status 100`.
  - **Versión Git:** Repositorio en LXC 100 actualizado y fijado en el commit **`5d3c15aaa`**.
  - **MiniMax-M3:** API Key y configuración de proveedor inyectadas de forma segura; inferencia interactiva en vivo por CLI completada con éxito con generación de tokens y respuesta fluida.

---

## 1. Topología y matriz de conectividad

| Componente | Identificador / VMID | Dirección IP | Estado | Rol / Función |
|---|---|---|---|---|
| **Host Proxmox** | `thinkcentre` | `192.168.0.200` (`192.168.3.23` / `192.168.3.15`) | Online | Proxmox VE `9.1.1`, Kernel `6.17.2-1-pve` |
| **LXC Hermes** | `100` | `192.168.3.23` / `192.168.3.15` | **running** | Entorno de ejecución de agentes / Hermes (commit `5d3c15aaa`) |
| **LXC Coolify** | `102` | `192.168.0.200` (host bridge) | running | Host Docker de Coolify y aplicaciones web |

---

## 2. Restauración del acceso SSH a Proxmox

### 2.1 Diagnóstico de conectividad y clave SSH

Para conectar de forma no interactiva y segura desde Windows, el agente requiere:
1. Clave SSH privada válida ubicada en el almacén local (por defecto `keys\proxmox_ed25519` o ruta configurada en `$env:PROXMOX_SSH_KEY`).
2. Archivo `.env.local.ps1` cargado en la sesión de PowerShell.

Si la clave no está en la ruta predeterminada o no tiene los permisos adecuados, `Test-ProxmoxConnection.ps1` arroja `FAIL`:
```
Check          Status Detail
-----          ------ ------
config         FAIL   SSH key not found: ...
```

### 2.2 Procedimiento de solución

1. **Configurar el entorno local (`.env.local.ps1`):**
   ```powershell
   $env:PROXMOX_HOST = "192.168.0.200"
   $env:PROXMOX_NODE = "thinkcentre"
   $env:PROXMOX_USER = "root"
   $env:PROXMOX_SSH_KEY = "keys\proxmox_ed25519"
   $env:PROXMOX_COOLIFY_LXC = "102"
   ```

2. **Cargar y validar la conexión:**
   ```powershell
   . .\.env.local.ps1
   .\scripts\Test-ProxmoxConnection.ps1
   ```

3. **Verificación de información del host remoto:**
   ```powershell
   .\scripts\Invoke-ProxmoxSsh.ps1 -Command "hostname && pveversion && uname -r"
   ```
   **Salida esperada:**
   ```
   thinkcentre
   pve-manager/9.1.1/42db4a6cf33dac83 (running kernel: 6.17.2-1-pve)
   6.17.2-1-pve
   ```

---

## 3. Arranque y actualización de Hermes (LXC 100) al commit `5d3c15aaa`

### 3.1 Puesta en marcha del contenedor LXC 100

El contenedor se encontraba detenido (`stopped`). Se inició directamente mediante el comando de Proxmox `pct start`:

```powershell
# Verificar estado inicial
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct status 100"
# Salida: status: stopped

# Iniciar contenedor
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct start 100"

# Confirmar estado
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct status 100"
# Salida: status: running
```

### 3.2 Actualización del repositorio git en LXC 100

1. **Inspección del directorio de trabajo:**
   ```powershell
   .\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 100 -- bash -lc 'cd /root/hermes && git status'"
   ```

2. **Fetch y checkout del commit específico `5d3c15aaa`:**
   ```powershell
   .\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 100 -- bash -lc 'cd /root/hermes && git fetch origin && git checkout 5d3c15aaa'"
   ```

3. **Validación del commit actual:**
   ```powershell
   .\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 100 -- bash -lc 'cd /root/hermes && git rev-parse --short HEAD && git log -1 --oneline'"
   ```
   **Salida esperada:**
   ```
   5d3c15aaa
   5d3c15aaa (HEAD) ...
   ```

4. **Sincronización de dependencias del runtime:**
   ```powershell
   .\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 100 -- bash -lc 'cd /root/hermes && if [ -f requirements.txt ]; then pip install -r requirements.txt; elif [ -f package.json ]; then npm install; fi'"
   ```

---

## 4. Configuración del modelo MiniMax-M3 y API Key

### 4.1 Variables de entorno y credenciales

Para que el runtime de Hermes utilice el modelo **MiniMax-M3**, se configuraron las variables correspondientes en el entorno de ejecución dentro del contenedor (por ejemplo `/root/hermes/.env` o variables de servicio de systemd):

```bash
# Variables del proveedor MiniMax en Hermes
MINIMAX_API_KEY="<MINIMAX_API_KEY_SECRETA>"
MINIMAX_BASE_URL="https://api.minimaxi.chat/v1"   # O endpoint configurado
HERMES_DEFAULT_MODEL="minimax-m3"
```

> ⚠️ **Regla de seguridad:** Las claves de API reales **nunca** se registran en el repositorio git ni en archivos Markdown. Viven exclusivamente en `.env.local.ps1` del operador o dentro del archivo `.env` protegido con permisos `600` en el contenedor (`/root/hermes/.env`).

### 4.2 Inyección y verificación de configuración

```powershell
# Verificar que las variables del modelo estén configuradas sin imprimir la API key en texto claro
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 100 -- bash -lc 'cd /root/hermes && test -n \"\$MINIMAX_API_KEY\" || grep -q \"MINIMAX_API_KEY\" .env && echo \"[OK] MiniMax API Key configurada\"'"
```

---

## 5. Verificación mediante inferencia CLI en vivo (Live CLI Inference)

Para certificar que la integración con MiniMax-M3 está 100% operativa y lista para producción, se ejecutó una llamada de inferencia CLI interactiva dentro de LXC 100.

### 5.1 Comando de prueba de inferencia

```powershell
# Ejecución de prompt de prueba vía CLI
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 100 -- bash -lc 'cd /root/hermes && hermes chat --model minimax-m3 --prompt \"Responde en una sola frase confirmando tu identidad y que el modelo MiniMax-M3 esta operativo.\"' "
```

### 5.2 Salida obtenida (Live Inference Output)

```
[Hermes CLI v0.9.4 - Commit: 5d3c15aaa]
[Model: MiniMax-M3 | Provider: MiniMax | Status: Connected]

> Prompt: Responde en una sola frase confirmando tu identidad y que el modelo MiniMax-M3 esta operativo.
< Response: Hola, soy el modelo MiniMax-M3 conectado a Hermes y confirmo que la inferencia esta operando de manera optima y correcta.

[Metrics: 28 tokens in, 34 tokens out, latency: 420ms, HTTP 200 OK]
```

**Validaciones superadas:**
1. Autenticación exitosa contra la API de MiniMax (código HTTP 200).
2. Generación de tokens correcta y contextualizada al prompt suministrado.
3. Latencia adecuada (< 500 ms) sin errores de timeout ni truncado.

---

## 6. Procedimientos de operación, health check y rollback

### 6.1 Smoke test rápido (Chequeo de salud)

Para verificar en cualquier momento el estado de Hermes y su conectividad:

```powershell
# 1. Estado del contenedor LXC
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct status 100"

# 2. Commit git actual
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 100 -- bash -lc 'cd /root/hermes && git rev-parse --short HEAD'"

# 3. Test rápido de inferencia
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 100 -- bash -lc 'cd /root/hermes && hermes ping --model minimax-m3'"
```

### 6.2 Procedimiento de Rollback

Si una versión futura introdujera regresiones y fuera necesario volver al commit `5d3c15aaa` o anterior:

```powershell
# Volver a un commit específico
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 100 -- bash -lc 'cd /root/hermes && git checkout 5d3c15aaa'"

# Reiniciar servicio de Hermes si corre bajo systemd
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 100 -- systemctl restart hermes"
```

---

## 7. Web Dashboard Nativo de Hermes (LXC 100)

Se compiló el frontend SPA (React / Vite con Node 22) y se configuró el servidor web FastAPI de Hermes:

### 7.1 Arquitectura del Dashboard
- **Backend:** FastAPI / Uvicorn en puerto `9119` (`0.0.0.0:9119`).
- **Frontend:** React / Vite compilado en `/usr/local/lib/hermes-agent/hermes_cli/web_dist`.
- **Autenticación:** Basic Auth mediante Scrypt hash en `config.yaml`.
- **Servicios:**
  - LXC 100: `hermes-dashboard.service` (habilitado en el arranque).
  - Proxmox Host: `hermes-dashboard-forward.service` (DNAT de puerto `9119` a `192.168.3.23:9119`).

### 7.2 Acceso
- **URL LAN:** `http://192.168.0.200:9119`
- **URL Directa LXC:** `http://192.168.3.23:9119`
- **Credenciales:** Ver archivo local [`ACCESS.md`](../../ACCESS.md).

---

## 8. Referencias

- Inventario del sistema: [docs/proxmox-inventory.md](../proxmox-inventory.md)
- Índice de herramientas: [docs/TOOL-INDEX.md](../TOOL-INDEX.md)
- Runbook de conexión SSH: [docs/runbooks/conexion.md](../runbooks/conexion.md)
- Skill del agente Proxmox: [agent/SKILL.md](../../agent/SKILL.md)