nas-runbooks/common/hermes-hub-deploiement.md

Hermes Hub — Déploiement et Exploitation Multi-Univers sur VPS

Instance auteur : gemini / nabil
Date : 2026-08-20
Tags : hermes, hub, multi-univers, vps, tailscale, cloudflare-access, fastapi, subdomains, filebrowser, dsh, basic-auth, security-audit, stateless-proxy, websocket-bridge
Statut : valide (testé et vérifié en direct sur VPS Contabo avec transport HTTP 100% sans état et passerelle WebSocket bidirectionnelle)

---

Problème

Nabil dispose de 4 instances Hermes strictement cloisonnées :

• TT (hermes-tt, port 3010, NAS Synology) — Achats Zone Sud, Tunisie Telecom
• Nyora (hermes-nyora, port 3020, NAS Synology) — Venture perso, Dr Nexum
• Perso (hermes-perso, port 3031, NAS Synology) — Famille, personnel, santé
• Nabil (hermes-nabil, port 9119, VPS Contabo) — Master agent & DeepSeek Harness (DSH)

L'objectif est d'offrir une interface web unifiée sur le VPS Contabo (100.94.90.119) avec :

1. Un Workspace Switcher latéral fluide et étanche entre les 4 univers.
2. Un Sélecteur Toggle DSH pour basculer instantanément entre la session et l'explorateur de fichiers DSH (https://dsh.hub.yesminedor.tn/).
3. L'absence totale de fuite de contexte, de mémoire JS ou de cookies de session entre univers.
4. La résolution 100% native des assets absolus (/assets/main-*.js) via un routage par sous-domaine dédié (*.hub.yesminedor.tn).
5. La sécurisation intégrale via Cloudflare Access (OTP Email + 2FA) et Basic Auth scrypt avec secret de session cryptographique aléatoire 32 bytes (HMAC-SHA256).
6. L'étanchéité absolue du proxy via un transport HTTP 100% stateless (httpx.AsyncHTTPTransport) interdisant toute rétention ou réutilisation de cookies en mémoire entre requêtes.
7. Une passerelle WebSocket bidirectionnelle full-duplex (proxy_websocket via websockets) pour le streaming en temps réel des chats, des événements (/api/events), des terminaux interactifs (/api/pty) et de la console (/api/console).

---

Architecture WebSocket Proxy

1. Mécanisme

La route générique @app.websocket("/{path:path}") intercepte toutes les requêtes d'upgrade WebSocket :

• Résolution de la cible backend via l'en-tête Host (tt.hub.yesminedor.tn, nabil.hub.yesminedor.tn, etc.) ou par sous-chemin (/u/{id}/*).
• Établissement d'une connexion WebSocket amont vers l'instance Hermes ciblée (ws://hermes-nabil:9119/api/ws?ticket=...).
• Transfert transparent des cookies et headers d'authentification tout en filtrant les en-têtes hop-by-hop (upgrade, sec-websocket-key, etc.).
• Exécution de deux boucles asynchrones concurrentes (client_to_upstream et upstream_to_client) assurant le multiplexage des trames texte/binaire en duplex intégral.

2. Validation de bout en bout

• Authentification réussie via Basic Auth et émission d'un ticket éphémère (POST /api/auth/ws-ticket).
• Connexion WebSocket établie avec succès (OPEN) sur ws://nabil.hub.yesminedor.tn/api/ws?ticket=....
• Échange de trames JSON-RPC validé en direct (réception de la trame initiale gateway.ready contenant la configuration complète du thème, du branding et des événements).

---

Matrice Complète d'Audit de Sécurité des Routes API (nabil.hub.yesminedor.tn)

Route API	Description	Anonyme (sans cookie)	Authentifié (avec cookie)	Statut Audit
/api/sessions	Historique des sessions (Sensible)	401 Unauthorized	200 OK	✅ Conforme
/api/profiles	Profils & Personas	401 Unauthorized	200 OK	✅ Conforme
/api/skills	Compétences & Outils	401 Unauthorized	200 OK	✅ Conforme
/api/memory	Vecteurs & Mémoire	401 Unauthorized	200 OK	✅ Conforme
/api/credentials/pool	Pool d'identifiants	401 Unauthorized	200 OK	✅ Conforme
/api/config/raw	Configuration brute & Clés	401 Unauthorized	200 OK	✅ Conforme
/api/mcp/catalog	Catalogues MCP	401 Unauthorized	200 OK	✅ Conforme
/api/webhooks	Configuration Webhooks	401 Unauthorized	200 OK	✅ Conforme
/api/analytics/usage	Statistiques & Utilisation	401 Unauthorized	200 OK	✅ Conforme
/api/plugins/kanban/board	Tableaux & Tâches Kanban	401 Unauthorized	200 OK	✅ Conforme
/api/auth/providers	Découverte des auth providers	200 OK (Public)	200 OK	✅ Conforme
/api/status	Sonde de statut / liveness	200 OK (Public)	200 OK	✅ Conforme
/api/health	Sonde de santé globale	200 OK (Public)	200 OK	✅ Conforme