Funk-lab/admin/hermes.md

# Hermes Agent — Commandes d'administration

Hermes Agent tourne en deux services systemd sur **storage-01** :
- `hermes-agent` — gateway (messagerie, API)
- `hermes-dashboard` — interface web (port 9119)

Il passe par **LiteLLM** (`:4000`) pour toute inférence — Qwen local ou Claude API.
Les données persistantes sont sur le RAID5 : `/srv/data/hermes`.

---

## Architecture

```
hermes chat / hermes -z / http://192.168.1.200:9119
        │
        ▼  LM_BASE_URL=http://127.0.0.1:4000/v1
   LiteLLM Proxy (:4000)
        ├── hermes-default  →  qwen3-8b          →  llama-server gpu-01  (défaut)
        └── hermes-default  →  claude-sonnet-4-6 →  api.anthropic.com    (switch)
```

---

## Dashboard Web

Accessible depuis le poste admin uniquement (`192.168.1.10`) :

```
http://192.168.1.200:9119
```

Inclut : gestion des sessions, configuration, API keys.

> L'onglet Chat (TUI embarqué via WebSocket/PTY) ne s'affiche pas dans le dashboard malgré `--tui`.
> Utiliser `hermes-tui` en SSH à la place (voir ci-dessous).

```bash
# Service dashboard
sudo systemctl status hermes-dashboard
sudo systemctl restart hermes-dashboard
sudo journalctl -u hermes-dashboard -f
```

## TUI (chat interactif)

Le TUI nécessite un terminal interactif (PTY) et doit tourner sous le compte `hermes` :

```bash
# Depuis le poste perso
ssh storage-01
sudo -i -u hermes        # basculer vers le compte hermes
cd /srv/data/hermes
hermes --tui
```

> Lancer depuis un autre compte (ex: ansible) génère des "gateway error" — toujours utiliser le compte hermes.

---

## Service systemd

```bash
sudo systemctl status hermes-agent
sudo systemctl restart hermes-agent
sudo journalctl -u hermes-agent -f
sudo journalctl -u hermes-agent -n 50
```

---

## Utilisation CLI

```bash
# Chat interactif (depuis storage-01)
cd /srv/data/hermes && hermes chat

# Question one-shot
cd /srv/data/hermes && hermes -z "ta question"

# Statut global
hermes status

# Diagnostics
hermes doctor
```

---

## Switcher le modèle

```bash
sudo /usr/local/bin/hermes-switch qwen     # Qwen3-8B local (gratuit)
sudo /usr/local/bin/hermes-switch claude   # Claude Sonnet 4.6 (API Anthropic ~1$/session)
sudo /usr/local/bin/hermes-switch status   # Modèle actif
```

---

## Configuration

### config.yaml (`/srv/data/hermes/config.yaml`)

```yaml
model:
  provider: lmstudio
  base_url: "http://127.0.0.1:4000/v1"
  default: "hermes-default"
  context_length: 65536

gateway:
  host: "0.0.0.0"
  port: 8080
```

### .env (`/srv/data/hermes/.env`)

```bash
LM_BASE_URL=http://127.0.0.1:4000/v1
LM_API_KEY=lm-studio    # valeur exacte obligatoire
```

---

## Variables d'environnement (service systemd)

| Variable | Valeur |
|---|---|
| `HOME` | `/opt/hermes` |
| `HERMES_HOME` | `/srv/data/hermes` |
| `LM_BASE_URL` | `http://127.0.0.1:4000/v1` |
| `LM_API_KEY` | `lm-studio` |

---

## Skill Qdrant Vector Search

```bash
# Vérifier le skill installé
cat /srv/data/hermes/skills/mlops/qdrant/SKILL.md

# Tester les embeddings (requis pour le skill)
curl -s -X POST http://192.168.10.20:1234/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3-8b","input":["test"]}' | python3 -c \
  "import sys,json; print('dim:', len(json.load(sys.stdin)['data'][0]['embedding']))"

# Installer qdrant-client si absent
sudo -u hermes /srv/data/hermes/hermes-agent/venv/bin/pip install "qdrant-client>=1.12.0"
```

> Toujours passer par le terminal (fichier /tmp/*.py) pour accéder à Qdrant depuis Hermes,
> jamais via execute_code (pas de qdrant-client dans cet environnement).

---

## Arborescence HERMES_HOME

```
/srv/data/hermes/
├── config.yaml         → configuration principale (géré Ansible)
├── .env                → LM_BASE_URL, LM_API_KEY (géré Ansible)
├── hermes-agent/       → installation (venv Python, binaire, frontend web)
│   └── web/            → source frontend dashboard (compilé via npm)
├── node/               → Node.js local (pour compiler le frontend)
├── memories/           → mémoire persistante (MEMORY.md auto-chargé)
├── sessions/           → historique des sessions
├── logs/               → logs
├── skills/             → skills installées
└── state.db            → base SQLite état agent
```

---

## Recompiler le frontend dashboard

Si mise à jour de hermes-agent nécessite un rebuild :

```bash
sudo -u hermes bash -c \
  'export PATH=/srv/data/hermes/node/bin:$PATH && \
   cd /srv/data/hermes/hermes-agent/web && \
   npm install && npm run build'
sudo systemctl restart hermes-dashboard
```

---

## Points d'attention

| Sujet | Détail |
|---|---|
| Données sur RAID5 | `HERMES_HOME=/srv/data/hermes` — jamais sur le SSD OS |
| LiteLLM requis | litellm.service doit tourner avant hermes-agent |
| `LM_API_KEY` | Doit valoir `lm-studio` exactement |
| Contexte | Qwen3-8B : 32768 tokens, system prompt ~15k → ~17k tokens dispo |
| path `hermes -z` | Toujours lancer depuis `/srv/data/hermes` (cherche .git en remontant) |
| Gemma 4 | Interdit — crash ROCm sur prompts >800 tokens |
| SELinux | Fichiers sur RAID5 ont contexte `unlabeled_t` — exécuter via binaire dans `/opt/hermes/.local/bin/` |
| Dashboard | Accessible uniquement depuis `192.168.1.10:9119` (restreint nftables) |
| TUI | `hermes --tui` nécessite un TTY — utiliser `sudo hermes-tui` en SSH interactif |
| `/opt/hermes` perms | Répertoire en `711` — traversable par tous mais non listable |