● Recherche Web · navigateur local persistant

Camofox + recherche Web

Installer Camofox comme navigateur local de secours pour Hermes, conserver les sessions utiles entre les tâches et respecter la stratégie Golden : recherche/extraction Web d’abord, Camofox seulement lorsque la page nécessite un vrai navigateur, du JavaScript ou une session persistante.

Version Golden

Camofox v1.14.0

Runtime

Node ≥ 22

Service local

localhost · port 9377

Lecture seuleModificationValidationOptionnel

Principe Golden : Camofox reste un service local. Il ne doit pas être publié directement sur Internet. Il sert de fallback lorsque la recherche ou l’extraction standard ne suffit pas ; il ne doit pas être utilisé pour contourner CAPTCHA, authentification, paywall ou restriction d’accès.

Golden vs version actuelle : la configuration Jarvis historique utilise Camofox v1.14.0. Pour reproduire exactement le Golden Build, épinglez cette version. Pour une nouvelle installation non strictement reproductible, une version plus récente peut être choisie après lecture des notes de version et validation complète de ce module.

Installation pas à pas

Le chemin principal ci-dessous reproduit l’installation Golden en service utilisateur local. Docker reste présenté plus loin comme alternative.

11.1 · Vérifier les prérequis

Validation

git --version
node --version
npm --version
hermes --version

Pourquoi : Camofox est un serveur Node.js. La version Golden nécessite Node 22 ou plus récent.

Résultat attendu : Git, Node, npm et Hermes répondent. La version majeure de Node est au minimum 22.

11.2 · Si Node est absent ou trop ancien

Optionnel

# Méthode Hermes actuelle : prépare son runtime navigateur et un Node récent
hermes acp --setup-browser --yes

# Pour la session courante, si nécessaire :
export PATH="$HOME/.hermes/node/bin:$PATH"
node --version
npm --version

Pourquoi : Les versions récentes d’Hermes peuvent installer un Node géré sous le répertoire Hermes, sans modifier globalement le système.

Résultat attendu : node --version indique une version ≥22. Si votre installation Hermes ne fournit pas cette commande, installez un Node LTS ≥22 par votre méthode habituelle puis reprenez ici.

11.3 · Préparer les répertoires locaux

Modification

mkdir -p ~/.local/share
mkdir -p ~/.camofox/profiles
chmod 700 ~/.camofox ~/.camofox/profiles

Pourquoi : Séparer le logiciel Camofox de ses profils persistants et protéger les cookies/session states qu’ils contiennent.

Résultat attendu : Les répertoires existent et ~/.camofox n’est accessible qu’au compte propriétaire.

11.4 · Vérifier qu’aucune ancienne installation n’est active

Lecture seule

systemctl --user status camofox.service --no-pager 2>/dev/null || true
ss -lntp | grep ':9377' || true
test -d ~/.local/share/camofox && echo "Installation Camofox déjà présente" || true

Pourquoi : Éviter d’installer deux serveurs sur le même port ou d’écraser une version existante.

Résultat attendu : Soit rien n’est actif, soit vous identifiez clairement l’installation existante avant de continuer.

11.5 · Cloner Camofox

Modification

git clone https://github.com/jo-inc/camofox-browser.git   ~/.local/share/camofox
cd ~/.local/share/camofox

Pourquoi : Installer le serveur Camofox dans l’emplacement Golden, sans privilège root.

Résultat attendu : Le dépôt est présent dans ~/.local/share/camofox.

11.6 · Épingler la version Golden

Modification

cd ~/.local/share/camofox
git fetch --tags
git checkout v1.14.0
git describe --tags --always

Pourquoi : Reproduire la version validée dans le Golden Build au lieu de dépendre automatiquement de la branche la plus récente.

Résultat attendu : La dernière commande affiche v1.14.0.

11.7 · Installer les dépendances Node

Modification

cd ~/.local/share/camofox
npm ci --omit=dev

Pourquoi : Installer les dépendances exactement à partir du lockfile. Le post-install récupère également les composants navigateur nécessaires lorsque le cache est absent.

Résultat attendu : npm termine sans erreur bloquante et le dossier node_modules existe.

11.8 · Vérifier la version installée

Validation

cd ~/.local/share/camofox
node -p "require('./package.json').version"
git status --short

Pourquoi : Confirmer que les fichiers exécutés correspondent bien au checkout Golden et qu’aucune modification locale involontaire n’a été faite.

Résultat attendu : La version est 1.14.0 et git status --short reste vide ou ne montre que des fichiers attendus.

11.9 · Tester Camofox au premier plan

Validation

cd ~/.local/share/camofox
CAMOFOX_BIND_HOST=localhost CAMOFOX_PORT=9377 CAMOFOX_PROFILE_DIR="$HOME/.camofox/profiles" CAMOFOX_CRASH_REPORT_ENABLED=false npm start

Pourquoi : Faire un premier démarrage visible avant de créer le service systemd. Le bind localhost empêche l’écoute sur le LAN.

Résultat attendu : Le serveur démarre sans erreur. Laissez-le quelques secondes puis utilisez Ctrl+C pour l’arrêter.

11.10 · Créer le service systemd utilisateur

Modification

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/camofox.service <<'EOF'
[Unit]
Description=Camofox Browser for Jarvis
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=%h/.local/share/camofox
Environment=PATH=%h/.hermes/node/bin:/usr/local/bin:/usr/bin:/bin
Environment=NODE_ENV=production
Environment=CAMOFOX_BIND_HOST=localhost
Environment=CAMOFOX_PORT=9377
Environment=CAMOFOX_CRASH_REPORT_ENABLED=false
ExecStart=/usr/bin/env node server.js
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
EOF

Pourquoi : Démarrer Camofox automatiquement pour l’utilisateur Jarvis et le relancer en cas de panne, tout en conservant une écoute locale.

Résultat attendu : Le fichier ~/.config/systemd/user/camofox.service existe.

11.11 · Valider le fichier systemd

Validation

systemd-analyze --user verify ~/.config/systemd/user/camofox.service

Pourquoi : Détecter les erreurs de syntaxe avant d’activer le service.

Résultat attendu : Aucune erreur liée à camofox.service. Des avertissements sur d’autres services utilisateur peuvent être indépendants du module.

11.12 · Activer et démarrer Camofox

Modification

systemctl --user daemon-reload
systemctl --user enable --now camofox.service
systemctl --user status camofox.service --no-pager

Pourquoi : Rendre le navigateur disponible au démarrage de la session utilisateur.

Résultat attendu : Le service est active (running).

11.13 · Tester le endpoint de santé

Validation

curl -fsS http://localhost:9377/health
ss -lntp | grep ':9377'

Pourquoi : Vérifier que le serveur REST répond et que le port attendu est ouvert localement.

Résultat attendu : Le endpoint répond avec un état sain et le listener correspond au processus Camofox/Node.

11.14 · Ajouter CAMOFOX_URL à Hermes

Modification

cp ~/.hermes/.env "$HOME/.hermes/.env.backup-$(date +%Y%m%d-%H%M%S)"
sed -i '/^CAMOFOX_URL=/d' ~/.hermes/.env
printf '%s
' 'CAMOFOX_URL=http://localhost:9377' >> ~/.hermes/.env
chmod 600 ~/.hermes/.env

Pourquoi : Déclarer l’adresse locale du serveur sans l’exposer dans le skill ni dans le code.

Résultat attendu : Une seule ligne CAMOFOX_URL=... existe dans ~/.hermes/.env.

11.15 · Sélectionner Camofox comme backend navigateur

Modification

hermes config set browser.cloud_provider camofox
hermes config set browser.camofox.managed_persistence true
hermes config check

Pourquoi : Les versions actuelles d’Hermes ne sélectionnent plus forcément Camofox par la seule présence de CAMOFOX_URL. Le provider doit être explicite, et la persistance doit être placée au bon chemin imbriqué.

Résultat attendu : La configuration passe la validation et managed_persistence se trouve sous browser.camofox.

11.16 · Vérifier la configuration Browser

Validation

hermes config get browser
grep '^CAMOFOX_URL=' ~/.hermes/.env | sed 's#=.*#=<CONFIGURE>#'

Pourquoi : Vérifier le provider et la présence de la variable sans recopier de valeur sensible si elle change un jour.

Résultat attendu : Le provider est camofox et la persistance managée est activée.

11.17 · Redémarrer Hermes

Modification

hermes gateway restart
hermes gateway status

Pourquoi : Hermes doit relire la configuration Browser et le fichier .env.

Résultat attendu : La Gateway redémarre normalement.

11.18 · Tester le navigateur depuis Hermes

Validation

hermes chat -q "Utilise le navigateur pour ouvrir https://example.com et donne uniquement le titre de la page."

Pourquoi : Valider la chaîne Hermes → Camofox → navigation → extraction.

Résultat attendu : Hermes ouvre la page via son outil navigateur et retourne son titre sans erreur Camofox.

11.19 · Vérifier la persistance des profils

Validation

find ~/.camofox/profiles -maxdepth 2 -type f | head
ls -ld ~/.camofox ~/.camofox/profiles

Pourquoi : La persistance est un élément Golden important : les états de session doivent pouvoir survivre aux tâches et redémarrages lorsqu’un site l’autorise.

Résultat attendu : Le répertoire de profils reste privé et des données de profil peuvent apparaître après utilisation de Camofox.

11.20 · Vérifier les logs

Validation

journalctl --user -u camofox.service -n 100 --no-pager |   grep -Ei 'error|warning|persistence|profile|listening|camofox' || true

Pourquoi : Détecter un navigateur absent, un problème de dépendance ou un échec du plugin de persistance.

Résultat attendu : Aucun message d’erreur bloquant. Le plugin de persistance est chargé ou le fonctionnement des profils est confirmé par le test précédent.

Stratégie de recherche Golden

1 · Recherche / extraction standard

research-watch doit privilégier les outils de recherche et d’extraction Web lorsque la page est directement accessible. C’est plus léger et plus rapide.

2 · Camofox en fallback

Utilisez Camofox lorsqu’un rendu JavaScript, une interaction, une navigation multi-étapes ou une session persistante est réellement nécessaire.

3 · Pas de contournement

Ne pas employer le navigateur pour contourner CAPTCHA, paywalls, restrictions d’accès ou authentifications auxquelles vous n’êtes pas autorisé.

4 · Sessions persistantes

La persistance sert à conserver une session légitime entre deux tâches, pas à extraire ou partager des identifiants.

Alternative — Camofox sous Docker

Le chemin officiel actuel d’Hermes documente également un déploiement Docker. Il peut être choisi si vous préférez isoler Camofox dans un conteneur. Ne mélangez pas les deux méthodes sur la même machine.

Principe

Cloner le dépôt Camofox.
Construire l’image avec make build ou démarrer avec make up.
Persister ~/.camofox dans un volume ou bind mount.
Publier le service uniquement vers la machine locale ou protéger explicitement tout accès distant.
Conserver CAMOFOX_URL=http://localhost:9377 côté Hermes.

Attention : la commande Docker par défaut peut publier un port sur plusieurs interfaces. Pour Jarvis, la règle reste : ne pas exposer Camofox sur Internet et ne pas rendre son API accessible au LAN sans justification et contrôle d’accès.

Dépannage rapide

Node trop ancien

Vérifiez node --version. Camofox v1.14.0 demande Node ≥22. Utilisez le runtime Hermes ou installez un Node LTS compatible.

Le service démarre puis tombe

Lisez journalctl --user -u camofox.service. Vérifiez surtout le binaire Node, les dépendances npm et le téléchargement Camoufox.

Health ne répond pas

Contrôlez systemctl --user status camofox.service, puis le listener du port 9377. Ne changez pas le port tant que le diagnostic n’est pas compris.

Hermes n’utilise pas Camofox

Vérifiez browser.cloud_provider=camofox. Sur les versions actuelles, définir seulement CAMOFOX_URL peut ne pas suffire.

Les connexions disparaissent

Vérifiez que browser.camofox.managed_persistence est bien imbriqué sous browser.camofox et que le serveur écrit dans ~/.camofox/profiles.

Port visible depuis le réseau

Arrêtez le service et corrigez le bind. Le Golden Build attend un service local uniquement.

Références officielles

Validation du Module 11

Ne passez au module suivant que lorsque tous les points applicables sont validés.

Node est en version 22 ou supérieure.

Camofox est installé sous ~/.local/share/camofox.

La version Golden est épinglée à v1.14.0.

Le service systemd utilisateur est actif.

Le endpoint /health répond sur localhost.

Camofox n’est pas volontairement exposé sur Internet.

CAMOFOX_URL est présent dans ~/.hermes/.env.

browser.cloud_provider vaut camofox.

browser.camofox.managed_persistence est activé.

Un test de navigation depuis Hermes fonctionne.

Le répertoire ~/.camofox/profiles est protégé.

Les logs Camofox ne montrent aucune erreur bloquante.

STOP — Module 11 validé

Jarvis dispose maintenant d’un navigateur local persistant pour les cas où la recherche/extraction standard ne suffit pas. Le prochain module installera Open WebUI.

← Module précédent Revenir à l’ordre des modules