runbook: Hermes x3 -> Bifrost via bifrost-proxy

common/hermes-vers-bifrost-bifrost-proxy.md

@@ -0,0 +1,35 @@
+# Hermes x3 → Bifrost via bifrost-proxy (Bearer→x-bf-vk) (15/07/2026)
+
+## But
+Sortir les 3 Hermes de **opencode-go en direct** (clé exposée) et router leurs appels LLM via **Bifrost** — normaliser + sécuriser.
+
+## Le piège
+Bifrost n'accepte la VK **que** via l'en-tête `x-bf-vk` (`Authorization: Bearer` → **401**). Le transport Hermes (`openai_chat`) envoie la clé en **Bearer**, et `HermesOverlay` n'a **aucun** champ d'en-tête custom. Un simple échange de clé enverrait donc du Bearer → 401 → les 3 Hermes cassés.
+
+## La clé : bifrost-proxy fait déjà la conversion
+Conteneur `bifrost-proxy` (openresty, réseau `n8n`, conf `/volume1/docker/bifrost-proxy/nginx.conf`) :
+```
+map $http_authorization $bearer_vk { ~*^Bearer\s+(.+)$ $1; default ""; }
+map $http_x_api_key $resolved_vk { "" $bearer_vk; default $http_x_api_key; }
+location / { proxy_set_header x-bf-vk $resolved_vk; proxy_pass http://bifrost:8080; }
+```
+→ il extrait le token du `Bearer` et le réinjecte en `x-bf-vk`. Donc envoyer `Authorization: Bearer <VK>` vers **bifrost-proxy** fonctionne. (Il plafonne aussi `max_tokens` à 16384 et sert `/v1/models` depuis `models.json` ; `access_log off`.)
+
+## Recette (config.yaml, RESTART, pas de recreate)
+Dans `/opt/data/config.yaml` (hôte `/volume1/docker/hermes-platform/hermes-<inst>/data/config.yaml`), bloc `model:` :
+- `provider: opencode-go` → `provider: custom`
+- ajouter `base_url: http://bifrost-proxy/v1`
+- ajouter `api_key: <VK Bifrost>` (Nabil-Key)
+Puis `docker restart hermes-agent-<inst>`. `runtime_provider.py` honore `model.base_url`+`api_key` pour `provider: custom`.
+
+## Validation
+`hermes -z "..."` répond **et** `governance_budgets.current_usage` (bifrost `config.db`) **augmente** → preuve du routage. 3/3 healthy, aucun conflit/lock Telegram (restart ≠ recreate). Effet de bord positif : la veille Nexum (mimo-v2.5) passe aussi par Bifrost → coût tracké + plafonné par le budget 8 $.
+
+## Reste / sécurité
+- `fallback_providers` reste `opencode-go` direct (filet de secours) → à normaliser/retirer plus tard.
+- **Roter** la clé opencode exposée (`sk-O47k…`, action Nabil) ; puis MAJ `OPENCODE_GO_API_KEY` (recreate) ou retirer le fallback.
+- La VK `bfk-0cd1fba7…` a transité en clair → rotation idéale (mais utilisée aussi par n8n ; une VK dédiée Hermes serait plus propre).
+- Backups : `config.yaml.bak_*_claude_bifrost` par instance.
+
+## Test direct de la chaîne
+Depuis un conteneur hermes : `python3 urllib` POST `http://bifrost-proxy/v1/chat/completions` avec `Authorization: Bearer <VK>` (deepseek-v4-flash + mimo-v2.5 → 200).