Hermes Workspace — Migration depuis hermes-telegram¶

Contexte¶

Migration de l'ancienne stack hermes-telegram (container Docker tout-en-un) vers une nouvelle architecture Hermes Workspace avec séparation des responsabilités. L'objectif était d'obtenir une interface web moderne avec sessions, skills, mémoire et dashboard complets.

Ancienne architecture (hermes-telegram)¶

Docker hermes-telegram
  ├── Gateway Hermes (Telegram + API)
  ├── Hermes WebUI (port 8787)
  └── Dashboard (port 9119)

Docker open-webui (port 3000) → remplacé
Docker caddy → proxy

Limites : image Docker nousresearch/hermes-agent:latest = version lite, sans sessions ni skills avancés.

Nouvelle architecture #systemd + Docker¶

Host (systemd — kanmaber)
  ├── hermes-gateway.service → port 8642 (0.0.0.0)
  └── hermes-dashboard.service → port 9119 (0.0.0.0)

Docker
  ├── hermes-workspace (ghcr.io/outsourc-e/hermes-workspace) → port 3000
  └── caddy → proxy (ports 3001, 2019, 7682)

Le workspace container se connecte au gateway host via host.docker.internal:8642.

Installation¶

# Prérequis
nvm install 22 && nvm use 22 && nvm alias default 22
npm install -g pnpm

# Installation
cd ~ && curl -fsSL https://hermes-workspace.com/install.sh | bash

Crée ~/hermes-workspace/ avec docker-compose.yml et .env.

Configuration docker-compose.yml final¶

services:
  hermes-workspace:
    image: ghcr.io/outsourc-e/hermes-workspace:latest
    env_file:
      - .env
    environment:
      HERMES_API_URL: http://host.docker.internal:8642
      HERMES_API_TOKEN: ${API_SERVER_KEY:-}
      HERMES_PASSWORD: ${HERMES_PASSWORD:-${CLAUDE_PASSWORD:-}}
      HERMES_DASHBOARD_URL: http://host.docker.internal:9119
      COOKIE_SECURE: ${COOKIE_SECURE:-}
      TRUST_PROXY: ${TRUST_PROXY:-}
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    ports:
      - '3000:3000'
    volumes:
      - hermes-workspace-data:/home/workspace/.hermes

volumes:
  hermes-workspace-data:

Services systemd¶

Fichiers dans ~/.config/systemd/user/ :

# hermes-gateway.service
[Service]
ExecStart=/bin/bash -c 'source /home/kanmaber/.nvm/nvm.sh && /home/kanmaber/.local/bin/hermes gateway run'
EnvironmentFile=/home/kanmaber/.hermes/.env

# hermes-dashboard.service
[Service]
ExecStart=/bin/bash -c 'source /home/kanmaber/.nvm/nvm.sh && /home/kanmaber/.local/bin/hermes dashboard --host 0.0.0.0 --insecure --no-open --skip-build'
EnvironmentFile=/home/kanmaber/.hermes/.env

systemctl --user enable hermes-gateway hermes-dashboard
systemctl --user start hermes-gateway hermes-dashboard

Configuration ~/.hermes/.env (clés importantes)¶

API_SERVER_ENABLED=true
API_SERVER_HOST=0.0.0.0
API_SERVER_KEY=<clé 64 chars hex>
TELEGRAM_TOKEN=<bot token>
TELEGRAM_BOT_TOKEN=<bot token>
TELEGRAM_ENABLED=true
TELEGRAM_HOME_CHANNEL=1945031566
TELEGRAM_HOME_CHANNEL_NAME=Kanmaber
GATEWAY_ALLOW_ALL_USERS=true
PATH=/home/kanmaber/bin:/home/kanmaber/.local/bin:...

Skill Telegram Notify #telegram¶

Script /home/kanmaber/bin/telegram-notify.sh :

#!/bin/bash
MESSAGE="$1"
TOKEN="${TELEGRAM_TOKEN:-${TELEGRAM_BOT_TOKEN}}"
CHAT_ID="${TELEGRAM_HOME_CHANNEL}"
curl -s -X POST "https://api.telegram.org/bot${TOKEN}/sendMessage" \
  -d "chat_id=${CHAT_ID}" -d "text=${MESSAGE}" -d "parse_mode=Markdown" \
  | python3 -c "import sys,json; r=json.load(sys.stdin); print('✅ Envoyé' if r.get('ok') else '❌ Erreur')"

Skill déclaré dans ~/.hermes/hermes-agent/skills/devops/send-telegram-notification/SKILL.md et ~/.hermes/skills/notifications/telegram-notify/SKILL.md.

Règle de déclenchement : - Automatiquement après toute tâche longue (>30s) - Sur demande explicite de l'utilisateur

Dashboard — build obligatoire¶

Le dashboard nécessite une compilation avant première utilisation :

export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh"
cd /home/kanmaber/.hermes/hermes-agent/web && npm install && npm run build

À refaire après hermes update.

Skill psycho-code (/cc)¶

Copié depuis l'ancienne installation vers ~/.hermes/skills/psycho-en-ligne/ :

sudo cp -r /home/kanmaber/hermes/data/skills/psycho-en-ligne ~/.hermes/skills/
sudo chown -R kanmaber:kanmaber ~/.hermes/skills/psycho-en-ligne

Accès interactif à Hermes¶

1 — Sur le VPS en SSH : chat direct¶

/home/kanmaber/.local/bin/hermes chat

Mode CLI complet — accès direct au système de fichiers, aux skills, aux outils shell. Pas de limitations.

Pour ne plus taper le chemin complet, ajouter dans ~/.bashrc :

export PATH="$HOME/.local/bin:$PATH"

Après ça, hermes chat suffit.

2 — Sur téléphone sans Telegram : workspace + ttyd¶

Workspace : http://178.105.46.57:3001 — interface de chat dans le navigateur, mode zero-fork avec sessions, skills et config disponibles.

Limitations par rapport au CLI : - Pas d'accès direct au terminal (sauf skill shell activé) - enhancedChat manquant (pas encore implémenté dans cette version)

Terminal web (ttyd) : http://178.105.46.57:7682 — terminal bash complet dans le navigateur. Depuis là, lancer hermes chat = identique à une session SSH sur le VPS. Pour fermer : taper exit puis fermer l'onglet.

Réinitialiser le mot de passe Caddy (basic auth)¶

Le mot de passe basic auth protège le dashboard (:2019) et le terminal ttyd (:7682). Pour le changer :

# 1. Générer le nouveau hash (sur le VPS)
docker exec caddy caddy hash-password --plaintext 'NOUVEAU_MOT_DE_PASSE'

# 2. Remplacer l'ancien hash dans le Caddyfile
sed -i 's|ANCIEN_HASH|NOUVEAU_HASH|g' ~/hermes/Caddyfile

# 3. Redémarrer Caddy
docker restart caddy

caddy reload échoue si l'API admin de Caddy est protégée — utiliser docker restart caddy à la place.

Tester ensuite :

curl -u 'hermes:NOUVEAU_MOT_DE_PASSE' http://127.0.0.1:7682/
# Attendu : HTTP 200 (pas 401)

Pièges rencontrés¶

Problème	Cause	Solution
`missing=[sessions,skills...]`	Image Docker lite	Utiliser hermes depuis les sources sur le host
Dashboard inaccessible depuis container	Bind sur 127.0.0.1	`--host 0.0.0.0 --insecure`
`host.docker.internal` non résolu	Linux Docker	`extra_hosts: host.docker.internal:host-gateway`
Dashboard pas compilé	npm absent en SSH non-interactive	`source nvm.sh && npm run build`
Skills non détectés	Mauvais dossier	`~/.hermes/skills/` (pas `~/.hermes/hermes-agent/skills/`) pour les custom
Workspace en mode `portable` (sessions manquantes)	Port 9119 bloqué par UFW pour les containers Docker	`ufw allow from 172.16.0.0/12 to any port 9119`
ttyd boucle "connecting/reconnected"	Commande ttyd pointe sur container supprimé (`hermes-telegram`)	Relancer ttyd avec `bash` : `ttyd -p 7681 -W bash`
`caddy reload` retourne HTTP 401	API admin Caddy protégée	Utiliser `docker restart caddy` à la place

Accès¶

Workspace : http://178.105.46.57:3001 (via Caddy, mot de passe requis)
Dashboard : http://178.105.46.57:2019 (via Caddy, basic auth)
Terminal ttyd : http://178.105.46.57:7682 (via Caddy, basic auth)

Liens connexes¶

shared/architecture/hermes-acces-vps-hetzner — ancienne architecture, interfaces Hermes
shared/architecture/vps-securite-ufw — firewall UFW configuré en même temps
shared/architecture/infrastructure-partagee-postgres-redis — shared_infra postgres/redis
shared/references/hermes-webui-guide — ancienne WebUI remplacée par workspace
PsychoEnLigneV2/architecture/cicd-options-deploiement-automatique — CI/CD GitHub Actions