/Documentation/Installation

Guide d'installation

Name: Klody
Author: Klody

Installez le daemon Klody sur vos serveurs en quelques minutes. Le daemon connecte vos machines au hub central pour orchestrer vos agents Claude Code.

#1. Prérequis

Composant	Requis	Notes
OS	Ubuntu 22.04 LTS+	x86_64 ou arm64
Node.js	v18.0.0+	Installé automatiquement via NodeSource si absent
PM2	Dernière version	Installé automatiquement par le script
RAM	512 MB min	1 GB+ recommandé pour agents multiples
Disque	200 MB	Pour le daemon + dépendances
Réseau	HTTPS sortant	WebSocket vers klody.app:443
Accès root	Requis	sudo ou root direct pour l'installation

Vérifier les prérequis manuellement

Vérifier la version de Node.js

node --version
# Doit afficher v18.x.x ou superieur

Vérifier PM2 (optionnel, installe par le script)

pm2 --version

#2. Installation pas-à-pas

Créer un serveur dans le hub

Connectez-vous au hub Klody et rendez-vous sur la page Servers.

Cliquez sur Add Server, puis remplissez :

Nom : un identifiant pour ce serveur (ex: production-1)
Hostname (optionnel) : le FQDN ou IP
Provider : Claude Code (Anthropic)
Clef API (optionnel) : clef Anthropic. Si vide, le daemon utilisera la clef locale.

Ecran Hub

Servers → Add Server → Remplir le formulaire

Copier la commande d'installation

Après la création, le hub affiche une commande contenant un token à usage unique. La commande curl | bash s'exécute directement dans votre terminal.

Ce token est à usage unique ! Il est invalidé après la première exécution. Ne le partagez pas publiquement.

Commande d'installation (exemple)

curl -fsSL https://klody.app/api/install/clr_abc123... | sudo bash

Exécuter sur le serveur cible

Connectez-vous en SSH sur votre serveur et collez la commande :

ssh [email protected]
# Puis collez la commande curl...

Le script effectue automatiquement :

Vérification de l'OS et de l'architecture
Installation de Node.js si absent (via NodeSource)
Installation de PM2 globalement
Téléchargement et extraction du daemon dans /opt/klody-daemon/
Configuration automatique (~/.klody/config.json)
Démarrage via PM2 avec auto-restart
Vérification de la connectivité avec le hub

Vérifier dans le hub

Retournez sur la page Servers du hub. Votre serveur devrait apparaitre en ONLINE en quelques secondes.

Serveur connecté

Le daemon envoie un heartbeat toutes les 30 secondes

#3. Vérification

Après l'installation, vérifiez que tout fonctionne correctement :

Vérifier le statut PM2

pm2 status klody-daemon
# Doit afficher "online"

Vérifier les logs

pm2 logs klody-daemon --lines 20

Vérifier la config

cat ~/.klody/config.json | jq .

Tester la connexion WebSocket

# Le daemon se connecte automatiquement.
# Vérifiez dans les logs :
pm2 logs klody-daemon --lines 5 | grep "Connected to hub"

#4. Configuration avancée

Le fichier de configuration se trouve dans ~/.klody/config.json. Modifiez-le puis redémarrez le daemon pour appliquer les changements.

Option	Défaut	Description
maxSessions	20	Nombre max d'agents simultanes
heartbeatInterval	30000	Intervalle heartbeat en ms (30s). Le hub déconnecte après 90s sans heartbeat.
logLevel	"info"	Niveau de log : debug, info, warn, error
autoRestart	true	Redémarrer automatiquement les sessions en erreur
provider	"claude-code"	"claude-code" (Anthropic)
contextHistorySize	50	Messages de contexte envoyés aux sessions
autoUpdate	false	Mise a jour automatique du daemon
autoUpdateCheckInterval	3600000	Intervalle de verification des mises a jour (1h)

Exemple de configuration

{
  "hubUrl": "wss://klody.app/ws/daemon",
  "token": "votre-token-serveur",
  "serverId": "clr_...",
  "serverName": "production-1",
  "provider": "claude-code",
  "maxSessions": 20,
  "heartbeatInterval": 30000,
  "contextHistorySize": 50,
  "autoRestart": true,
  "logLevel": "info",
  "autoUpdate": false
}

Redémarrer après modification

pm2 restart klody-daemon

#5. Troubleshooting

Node.js trop ancien

Le daemon requiert Node.js 18+. Si le script detecte une version trop ancienne, il l'installe automatiquement. En cas d'échec :

# Installer Node.js 20.x manuellement
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

PM2 ne démarre pas

Si PM2 ne parvient pas à démarrer le daemon :

# Vérifier les erreurs
pm2 logs klody-daemon --lines 50 --err

# Redémarrer complètement PM2
pm2 kill
pm2 start /opt/klody-daemon/dist/index.js --name klody-daemon
pm2 save

Le daemon ne se connecte pas au hub

Causes possibles :

Firewall bloquant les connexions sortantes HTTPS/WSS (port 443)
Token invalide ou expiré dans la config
hubUrl incorrecte

Diagnostiquer

# Tester la connectivité
curl -s https://klody.app/api/version

# Vérifier le token
cat ~/.klody/config.json | jq .token

# Activer les logs debug
# Éditer config.json : "logLevel": "debug"
pm2 restart klody-daemon
pm2 logs klody-daemon --lines 30

Port déjà utilisé

Le daemon n'écoute sur aucun port — il initie une connexion WebSocket sortante vers le hub. Ce problème ne devrait donc pas se produire. Si PM2 signale une erreur de port, c'est probablement un autre service.

# Trouver ce qui utilise un port
sudo lsof -i :3000
sudo ss -tlnp | grep 3000

Erreurs de permissions

# Réparer les permissions
sudo chown -R $(whoami) /opt/klody-daemon
sudo chown -R $(whoami) ~/.klody
chmod 600 ~/.klody/config.json

Réinstallation complète

En cas de problème persistant, désinstallez puis réinstallez :

pm2 stop klody-daemon
pm2 delete klody-daemon
sudo rm -rf /opt/klody-daemon
# Re-créer le serveur dans le hub pour obtenir un nouveau token
# Puis ré-exécuter la commande curl

La config et la base de données locale sont préservées dans ~/.klody/. Supprimez ce dossier également pour un fresh start complet.

#6. FAQ

Klody — Centralized control for AI coding agents

Accueil Connexion Inscription