hermes infos

hermes infos

docs/AI_CONTEXT.md

@@ -51,6 +51,29 @@ Traefik ist der zentrale Web-Einstieg fuer HTTP(S). Admin-/Ops-UIs liegen entwed
 ### Apps
 
 Wichtige Apps sind Paperless, Immich, Mealie, Mail Archiver, Nextcloud, ntfy, Vaultwarden und Gitea. Admin-/Ops-Tools sind u. a. Homepage, Komodo, Borg UI, Backrest, Uptime Kuma, Filebrowser, code-server, Glances, Scrutiny, Speedtest, Grafana und Hermes Agent.
+
+### Hermes Agent — Architektur und Ops-Monitor
+
+Hermes laeuft nach Model C (siehe `ops/hermes-agent/README.md`):
+
+- `hermes-gateway` als Docker-Container auf dem Unraid-Host, intern auf `hermes_net:8642`
+- Terminal-Befehle werden via SSH auf eine dedizierte Linux-VM ausgefuehrt
+- VM-IP: `192.168.178.143`, SSH-User: `hermes`
+- Repo-Clone auf der VM: `/srv/hermes-workspace/homelab-infra/`
+
+**Fuer KI-Agenten wichtig:** Das Hermes-Terminal laeuft auf der VM, nicht auf dem Unraid-Host.
+`/mnt/user/...`-Pfade sind von der VM aus nicht direkt erreichbar.
+Docker-CLI ist auf der VM nicht installiert — fuer Homelab-Checks wird `check_health.py` verwendet.
+
+**Ops-Monitor (homelab-ops-monitor):**
+
+- Skill: `ops/hermes-agent/skills/homelab-ops-monitor.md`
+- Script: `ops/hermes-agent/scripts/check_health.py` — prueft Services via HTTP, keine externen Deps
+- Wissensbasis: `ops/hermes-agent/services.json` — maschinenlesbare Ableitung aus `docs/SERVICE_CATALOG.md`
+- Check-Strategie: HTTP GET fuer URL-basierte Services, interne Services (DBs, Redis) als `"internal"` markiert
+- ntfy-Topic fuer Alerts: `homelab-alerts` auf `https://ntfy.kaleschke.info`
+
+Nach Aenderungen an `services.json` oder `check_health.py`: `git pull` auf der VM ausfuehren.
 - Mail Archiver ist ein Hybrid-Dienst mit `frontend_net` fuer IMAP/Traefik und `backend_net` fuer PostgreSQL; die Web-UI liegt hinter Authelia und behaelt zusaetzlich App-eigene Auth.
 
 ### Monitoring / Metriken

docs/SERVICE_CATALOG.md

@@ -68,7 +68,7 @@ Secret-Werte sind nicht enthalten. Es werden nur Secret-Namen, Env-Key-Namen und
 | `code-server` | Web-Editor / Operations Workspace | `ops/code-server/docker-compose.yml` | `https://code.kaleschke.info` | Traefik + Authelia | `/mnt/user/appdata/code-server`, `/mnt/user/services/dev` | Tier 3 | ja + Authelia | `PASSWORD_FILE`; Workspaces beachten |
 | `grafana` | Metrik-Dashboard | `ops/grafana-influxdb/docker-compose.yml` | `https://grafana.kaleschke.info` | Traefik + Authelia, InfluxDB 3 Core | `/mnt/user/appdata/grafana`, Grafana provisioning | Tier 3 | ja + Authelia | Datasource wird provisioniert, Token ueber Secret; laeuft aktuell als `user: "0"` wegen Host-Appdata-Permissions |
 | `influxdb3-core` | Zeitreihen-/Metrikdaten fuer Grafana und Home Assistant | `ops/grafana-influxdb/docker-compose.yml` | LAN `8181` je `INFLUXDB_BIND_IP`, keine Public URL | Grafana, Home Assistant Writer | `/mnt/user/appdata/influxdb3/data`, `/mnt/user/appdata/influxdb3/plugins` | Tier 3 | nein | LAN-only Host-Port-Ausnahme; `401 Unauthorized` beim Curl ohne Token ist erwarteter Reachability-Test; laeuft aktuell als `user: "0"` wegen Host-Appdata-Permissions |
-| `hermes-gateway` | Hermes Agent Gateway/API intern | `ops/hermes-agent/docker-compose.yml` | intern `8642` auf `hermes_net` | SSH Runner, LLM Provider, optional Home Assistant | `/mnt/user/appdata/hermes-agent/data`, SSH key path | Tier 3, Borg/Share | nein | kein Docker socket; terminal backend `ssh`; echte `.env` auf Host-Appdata |
+| `hermes-gateway` | Hermes Agent Gateway/API intern | `ops/hermes-agent/docker-compose.yml` | intern `8642` auf `hermes_net` | SSH Runner (VM 192.168.178.143), LLM Provider, optional Home Assistant | `/mnt/user/appdata/hermes-agent/data`, SSH key path | Tier 3, Borg/Share | nein | kein Docker-Socket; terminal backend `ssh` auf dedizierte VM (192.168.178.143, User `hermes`, Repo unter `/srv/hermes-workspace/homelab-infra/`); Ops-Monitor-Skill `homelab-ops-monitor` aktiv; echte `.env` auf Host-Appdata |
 | `hermes-dashboard` | Hermes Dashboard | `ops/hermes-agent/docker-compose.yml` | `https://hermes.kaleschke.info` via `${HERMES_DASHBOARD_HOST}` | `hermes-gateway`, Traefik + Authelia | shared read-only data mount | Tier 3, Borg/Share | ja + Authelia | Compose-Profil `dashboard`; bindet intern mit `--insecure` auf `0.0.0.0`, externe Absicherung bleibt Authelia |
 
 ## Backup- und Restore-Hinweise

ops/hermes-agent/README.md

@@ -425,6 +425,81 @@ Back up at least:
 - `/mnt/user/appdata/hermes-agent/ssh/known_hosts`
 - `/mnt/user/appdata/secrets/hermes_runner_id_ed25519`
 
+## Phase 7 - Ops Monitor (homelab-ops-monitor)
+
+### Was es ist
+
+Ein Skill + Script das Hermes zum kontextuellen Ops-Assistenten macht.
+Wenn ein Service ausfaellt, bekommt er nicht eine rohe Fehlermeldung, sondern einen
+angereicherten Alert: Abhaengigkeiten, letzter Backup-Dump, erster Diagnoseschritt.
+
+### Laufzeit-Architektur (Stand 2026-05-06)
+
+- Hermes laeuft als Docker-Container auf dem Unraid-Host (hermes-gateway, hermes_net)
+- Terminal-Backend SSH-Ziel: `192.168.178.143` (dedizierte Linux-VM, Model C)
+- Hermes-User auf der VM: `hermes`
+- Repo-Clone auf der VM: `/srv/hermes-workspace/homelab-infra/`
+- Workspace-Verzeichnis auf der VM: `/srv/hermes-workspace/`
+
+Wichtig fuer KI-Agenten und Betreiber: Das Terminal laeuft auf der VM, nicht auf dem
+Unraid-Host. `/mnt/user/...`-Pfade sind von der VM aus nicht direkt erreichbar.
+Docker-CLI ist auf der VM nicht vorhanden und wird nicht benoetigt.
+
+### Dateien
+
+| Datei | Pfad im Repo | Pfad auf VM |
+|---|---|---|
+| Wissensbasis | `ops/hermes-agent/services.json` | `/srv/hermes-workspace/homelab-infra/ops/hermes-agent/services.json` |
+| Health-Script | `ops/hermes-agent/scripts/check_health.py` | `/srv/hermes-workspace/homelab-infra/ops/hermes-agent/scripts/check_health.py` |
+| Skill-Prompt | `ops/hermes-agent/skills/homelab-ops-monitor.md` | `/srv/hermes-workspace/homelab-infra/ops/hermes-agent/skills/homelab-ops-monitor.md` |
+
+### check_health.py
+
+- Keine externen Abhaengigkeiten — nur Python-Standardbibliothek (`json`, `urllib`, `ssl`)
+- Kein Docker CLI, kein pip, kein Root noetig
+- Prueft Services mit URL via HTTP GET (2xx/3xx/4xx = healthy, 5xx/Timeout = unhealthy)
+- Interne Services ohne URL (Datenbanken, Redis) werden als `"internal"` markiert — kein Fehler
+- Dump-Timestamps werden gelesen falls `/mnt/user/backups/borg/dumps/latest` erreichbar ist (optional)
+- services.json wird relativ zum Script-Verzeichnis gesucht (`../services.json`)
+
+Verwendung auf der VM:
+```bash
+cd /srv/hermes-workspace/homelab-infra
+python3 ops/hermes-agent/scripts/check_health.py --summary        # Tier 1+2
+python3 ops/hermes-agent/scripts/check_health.py paperless-ngx    # gezielt
+python3 ops/hermes-agent/scripts/check_health.py --all            # alle Tiers
+```
+
+### services.json
+
+Maschinenlesbare Wissensbasis abgeleitet aus `docs/SERVICE_CATALOG.md`.
+Enthaelt fuer jeden Service: Tier, Container-Name, Abhaengigkeiten, Dump-Dateiname,
+Datenpfade, first_check-Hinweis und betriebliche Notizen.
+
+Bei Aenderungen am Service Catalog: `services.json` und `services.yaml` parallel aktualisieren.
+
+### Skill importieren
+
+```
+„Bitte erstelle einen neuen Skill namens homelab-ops-monitor. Lies dazu die Datei
+/srv/hermes-workspace/homelab-infra/ops/hermes-agent/skills/homelab-ops-monitor.md
+und lege den Skill mit diesem Inhalt an."
+```
+
+Nach Repo-Aenderungen auf der VM pullen:
+```bash
+cd /srv/hermes-workspace/homelab-infra && git pull
+```
+
+### Bekannte Einschraenkungen
+
+- Interne Services (PostgreSQL, Redis, MongoDB) koennen nicht extern geprueft werden
+- Dump-Timestamps nur lesbar wenn `/mnt/user/backups/` per NFS oder Mount erreichbar ist
+- Docker-Healthstatus der Container ist von der VM aus nicht pruefbar (kein Docker-Socket)
+- Alerting via ntfy erfordert dass ntfy selbst healthy ist (Fallback: Telegram)
+
+---
+
 ## Official sources used
 
 - Repository README: <https://github.com/NousResearch/hermes-agent>