Agents

Un agent exécute les processus de vos services. Le serveur décide de ce qui doit tourner, et l'agent lance les processus sur sa machine. Un service peut donc tourner sur une autre machine que celle où vous consultez l'interface.

L'agent local

Runeya démarre un agent sur votre machine au lancement. Il apparaît avec l'étiquette « Local » dans la liste des agents. Il ne se modifie pas et ne se supprime pas. Sans autre réglage, vos services tournent sur lui.

Ajouter un agent sur une autre machine

1. Lancer l'agent sur la machine distante

La machine distante a besoin de Node.js 22 ou plus, et de Runeya :

npm install -g @runeya/runeya
runeya --agent --lan

--lan fait écouter l'agent sur toutes les interfaces réseau. Sans lui, l'agent n'écoute que sur 127.0.0.1 et reste injoignable depuis une autre machine.

Drapeau	Variable	Défaut
--agent	aucune	lance l'agent seul, sans serveur ni interface
--lan	aucune	écoute sur toutes les interfaces (0.0.0.0)
--host <adresse> ou --agent-host <adresse>	RUNEYA_AGENT_HOST	127.0.0.1
--port <n> ou --agent-port <n>	RUNEYA_AGENT_PORT	4001

Au démarrage, l'agent affiche deux lignes à noter :

RUNEYA_PASSPHRASE=<64 caractères hexadécimaux>
Agent listening on 0.0.0.0:4001

La passphrase change à chaque redémarrage de l'agent. Pour la garder fixe, lancez l'agent avec la variable RUNEYA_AGENT_PASSPHRASE (une chaîne hexadécimale de votre choix). Sinon, il faudra saisir la nouvelle passphrase dans Runeya après chaque redémarrage.

2. Enregistrer l'agent dans Runeya

1. Ouvrez Paramètres → Agents (groupe « Accès et intégrations »).
2. Cliquez sur Enregistrer un agent.
3. Remplissez le formulaire :
   • Nom : un nom pour reconnaître la machine, par exemple serveur-staging.
   • URL : l'adresse de l'agent, par exemple http://192.168.1.20:4001.
   • Passphrase : la valeur affichée après RUNEYA_PASSPHRASE=.
   • Appartient à : affiché seulement si ce poste synchronise une organisation. Choisissez « Cette machine » ou l'organisation qui pourra utiliser l'agent.
4. Cliquez sur Tester la connexion. L'étiquette « Connecté » confirme que l'agent répond. En cas d'échec, l'étiquette rouge affiche l'erreur.
5. Cliquez sur Enregistrer un agent.

L'agent apparaît dans la liste avec son statut, « Connecté » ou « Déconnecté ». Les actions de chaque ligne permettent de le modifier, de le supprimer, de régler ses variables transmises (« Env passthrough ») et son proxy Traefik. En modification, laissez la passphrase vide pour garder la valeur enregistrée.

Choisir l'agent d'un service

Un service tourne sur l'agent choisi dans l'ordre suivant :

1. l'agent du service, s'il en a un ;
2. sinon, l'agent par défaut de l'environnement actif ;
3. sinon, l'agent local.

À la création d'un service, le champ Agent propose « — Hériter de l'environnement actif — » par défaut. Choisissez un agent pour forcer la machine.

Pour un service existant, ouvrez l'onglet Config, puis Commandes. La carte Agent permet de changer de machine, et le changement est enregistré tout de suite. Si le service tournait, Runeya l'arrête sur l'ancien agent. Cliquez ensuite sur Démarrer pour le lancer sur le nouveau.

Pour tout un environnement, ouvrez le formulaire de l'environnement et réglez Agent par défaut. Les services sans agent explicite tournent sur cet agent quand l'environnement est actif. Par exemple, l'environnement staging peut envoyer tous les services sur la machine de staging.

Ce qui doit exister sur la machine de l'agent

Les commandes du service s'exécutent sur la machine de l'agent. Le code du projet et les outils dont il a besoin (Node, Docker, base de données…) doivent donc s'y trouver.

• Le répertoire de travail est résolu sur la machine de l'agent. Si le dossier attendu n'existe pas et que le service a un dépôt git configuré, Runeya peut proposer de le cloner.
• Les variables d'environnement de la machine de l'agent ne sont pas transmises aux services, sauf celles déclarées dans Env passthrough.
• L'agent n'enregistre rien sur son disque. Il reçoit la configuration du service du serveur à chaque démarrage. Il n'y a rien à sauvegarder sur une machine d'exécution.

Si l'agent est injoignable, le service ne démarre pas. Une notification « Démarrage échoué » indique que l'agent ne répond pas, et l'agent apparaît « Déconnecté » dans Paramètres → Agents. Vérifiez que runeya --agent tourne toujours sur la machine distante et que la passphrase enregistrée est la bonne.

Sécurité

Par défaut, un agent n'écoute que sur 127.0.0.1. Il n'accepte que les requêtes qui portent sa passphrase. Runeya enregistre cette passphrase chiffrée.

Un agent lancé avec --lan ou --host 0.0.0.0 est accessible à toute machine qui peut l'atteindre. Seule la passphrase protège alors l'accès. Réservez ce mode à un réseau de confiance.