NeXifyAI Betriebslogik v1.0 — AI-Vollintegriert

Stand: 13.07.2026 | Gültig ab: sofort | Prüfzyklus: täglich 07:00 via Cron

§1 — VORGABEN (SOLL-Zustand)

V1: System-Verfügbarkeit

• 8 Kern-Services MÜSSEN active sein: gateway, webui, dashboard, paperclip, portal, auth, traefik, agentmemory
• 7 HTTP-Endpoints MÜSSEN 200: Factory:3100, Hermes:8787, 9Router:20128, Portal:8880, LightRAG:9621, agentmemory:3113, Spaether:8000
• Docker-Container restart-policy MUSS unless-stopped oder always sein
• Load DARF 15min-Mittelwert 8 NICHT überschreiten

V2: Security-Hardening

• Erlaubte 0.0.0.0-Bindings:
  • 22 (SSH)
  • 80/443 (Traefik)
  • 20128 (9Router via Cloudflare)
  • 9119 (Hermes Dashboard — direkter Server, kein Traefik-Proxy)
  • 8644 (Hermes Gateway — interner Kommunikationsport)
  • 49134 (agentmemory iii — iptables-DROP für non-localhost)
• ALLE anderen Ports MÜSSEN auf 127.0.0.1 gebunden sein
• agentmemory:49134 MUSS iptables-DROP für non-localhost haben
• Keine API-Keys in config.yaml — NUR in /etc/nexifyai/credentials.env (600) oder /opt/nexifyai/.env
• Keine Rogue-Prozesse auf 0.0.0.0:8000 (postgres-user uvicorn)
• SSH PasswordAuth MUSS no sein
• UFW MUSS aktiv sein, NUR 22/80/443 offen

V3: Credential-Schutz

• /etc/nexifyai/credentials.env MUSS 600 root:root sein
• /opt/nexifyai/.env DARF KEINE Keys im Klartext in Git/Logs/Backups enthalten
• CUSTOM_PROVIDER_API_KEY MUSS in ALLEN 3 .env-Dateien gesetzt sein:
  • /opt/nexifyai/.env (gateway)
  • /root/.hermes/.env (dashboard)
  • /opt/nexifyai/repos/hermes-webui/.env (webui)

V4: Skills & Factory

• Factory (localhost:3100) MUSS erreichbar sein (200)
• 3 Taps MÜSSEN aktiv sein: davila7/claude-code-templates, 0xNyk/awesome-hermes-agent, langfuse/skills
• config.yaml skills-Sektion MUSS directories: [] + korrekte taps enthalten
• Skill-Updates automatisch via hermes skills update im Health-Check

V5: Backups

• Tägliches Backup MUSS existieren (00:02 UTC via systemd timer)
• Backup-Script MUSS pg_dump ODER docker volume Referenzen enthalten (min. 2)
• Letztes Backup DARF NICHT älter als 25h sein

V6: agentmemory

• iii-Engine MUSS auf 127.0.0.1:3111 laufen (REST)
• Viewer MUSS auf 127.0.0.1:3113 antworten (200)
• Kein MCP-Server erforderlich — GDOK-Queries via direkte REST-Calls
• AGENTMEMORY_SECRET MUSS in iii-Engine konfiguriert sein

§2 — REGELN (Betriebslogik)

R1: Config-Änderungen

1. VORHER: Backup via cp config.yaml config.yaml.bak.$(date +%Y%m%d-%H%M%S)
2. NUR via Python yaml.safe_load/yaml.safe_dump
3. NIEMALS hermes config set (Bug v0.18.2 — zerstört Struktur)
4. NACHHER: Service-Restart + L1/L2/L3-Verifikation

R2: Service-Restart-Reihenfolge

1. hermes-gateway ZUERST (TimeoutStopSec=90)
2. hermes-webui + hermes-dashboard PARALLEL danach
3. Warten bis is-active = active
4. Health-Check aller 7 Endpoints

R3: Rogue-Prozess-Kill

• Symptom: uvicorn auf 0.0.0.0:8000 mit User=postgres, cwd=/usr/src/app
• Aktion: kill <PID> → ss -tlnp | grep ':8000' verifizieren
• Root-Cause: Unbekannt (kein systemd, kein Docker) — bei Wiederkehr untersuchen

R4: Port-Security

• iptables-Regel für 49134 bei jedem Boot prüfen
• Neue 0.0.0.0-Bindings sofort via ss -tlnp erkennen
• Docker-Container mit network_mode: host → auf Port-Exposure prüfen

R5: API-Key-Rotation

1. Neuen Key generieren/erhalten
2. In ALLE 3 .env-Dateien schreiben
3. config.yaml prüfen dass KEIN api_key mehr drin
4. Gateway restarten → Health-Check
5. webui+dashboard restarten → Health-Check

R6: agentmemory-GDOK-Queries

• Direkt via REST (nicht MCP): curl -H "Authorization: Bearer $SECRET" localhost:3111/agentmemory/memories?type=...
• 5 Pflicht-Typen: architecture, fact, pattern, decision, workflow
• Bei leeren Antworten: iii-Engine-Status prüfen, Secret verifizieren

§3 — VERBOTE (NIE tun)

| # | Verbot | Grund | |---|--------|-------| | V1 | hermes config set <key> <value> | Zerstört config.yaml (Bug v0.18.2) | | V2 | kill -9 auf agentmemory iii-Prozess | Korrumpiert state_store.db — Datenverlust | | V3 | API-Keys in config.yaml speichern | Security-Leak, Credential-Scanner schlägt an | | V4 | docker compose restart für Port-Änderungen | Wendet KEINE neuen Port-Bindings an — down+up nötig | | V5 | systemctl restart chain mit && | degraded state bricht Kette — ; oder || true nutzen | | V6 | cat/head/tail großer Dateien in terminal() | CCR-Kompression — read_file mit offset/limit nutzen | | V7 | grep/rg/find/ls/sed/awk in terminal() | search_files/patch/write_file nutzen | | V8 | Factory-Skills aus anderen Quellen laden | Quelle der Wahrheit = localhost:3100 | | V9 | Rogue uvicorn auf 0.0.0.0:8000 ignorieren | Security-Leak — SOFORT killen | | V10 | Credentials in Git/Logs/Backups committen | DSGVO-Verstoß — pre-commit hook check |

§4 — AUTOMATISIERUNG (AI-Vollintegriert)

A1: Health-Check-Cron (alle 5min)

cron: nexifyai-healthcheck.timer
script: /opt/nexifyai/scripts/health-check.sh
checks:
  - 8 Services active
  - 7 HTTP 200
  - 0 failed systemd units (außer snap.cups)
  - Rogue uvicorn detection
  - 0.0.0.0 Port-Audit

A2: Täglicher Oracle-Audit (07:00 UTC)

cron: 0 7 * * *
script: /opt/nexifyai/scripts/generate-digest.sh
checks:
  - GDOK 5 Pflicht-Queries
  - Backup-Freshness <25h
  - TLS-Zertifikat >30 Tage
  - Skill-Updates verfügbar?
  - Disk >20% frei?

A3: Credential-Scan (täglich)

grep -rn --include="*.py" -E '(password|secret|api_key|token)\s*[:=]\s*["\x27][a-zA-Z0-9_\-]{8,}' \
  /opt/nexifyai/ --exclude-dir=.venv --exclude-dir=node_modules --exclude-dir=__pycache__ \
  | grep -v 'environ\|env\.\|os\.\|getenv\|Test'

A4: agentmemory-Monitor (alle 30min)

• Viewer (3113) auf 200 prüfen
• iii-Engine (3111) auf 401 prüfen (auth-gated = OK)
• Memory-Count via /memories Endpoint
• Bei Count=0 → Alarm (Datenverlust?)

A5: Self-Healing

• Root-FS ro: mount -o remount,rw / → Alarm
• Rogue uvicorn: Auto-kill via Cron
• Container restart-policy on-failure: Auto-fix via docker update --restart unless-stopped
• Governance-Timer: Bei failed → systemctl reset-failed + restart

§5 — VERIFIKATION (3-Stufen)

| Stufe | Name | Prüfung | |-------|------|---------| | L1 | Lebend | systemctl is-active / docker ps / curl HTTP-Code | | L2 | Marker | @NEXIFYAI-MARKER: in config.yaml/Dokumenten | | L3 | Funktional | Login-Test, API-Endpoint-Test, GDOK-Query |

§6 — ESKALATION

| Schwere | Bedingung | Aktion | |---------|-----------|--------| | 🔴 CRITICAL | Gateway down, DB korrupt, TLS abgelaufen | SOFORT fixen, Pascal benachrichtigen | | ⚠️ WARNING | Rogue-Prozess, Port-Leak, Backup >25h | Fixen innerhalb 1h, Log-Eintrag | | ℹ️ INFO | Skill-Update, Disk-Trend, Load-Spike | Nächster Wartungszyklus |

Gültigkeit: Bis nächste GDOK-Revision. Änderungen NUR via deepcode-director mit Queen-Mode-Planung.