Runners

Un runner exécute vos étapes d’agent avec votre propre Claude Code, Codex ou Gemini CLI sur votre machine : démarrage, portée, délais et révocation.

Un runner permet à vos étapes d’agent de s’exécuter avec votre propre Claude Code, Codex ou Gemini CLI sur votre propre machine. C’est un petit programme, customermates-runner, qui demande à votre espace de travail vos tâches d’agent, lance la CLI dont vous avez ouvert la session, renvoie ce que fait la CLI sous forme de transcription et signale le résultat. Votre connexion à la CLI reste sur votre machine : Customermates ne la reçoit jamais. Les runners fonctionnent sur Customermates Cloud et sur les instances auto-hébergées.

Vous gérez les runners sous Paramètres, Agents, dans la carte Runners. Pour ajouter ou révoquer un runner, il faut les mêmes accès de rôle que pour les clés API.

Que fait un runner ?

Toutes les 60 secondes, il indique à l’espace de travail le nom de sa machine et les CLI qu’il peut lancer, avec leurs versions. Entre deux rapports, il garde une requête ouverte jusqu’à 25 secondes pour récupérer la prochaine tâche en attente, puis redemande aussitôt. Un runner n’exécute que les tâches du membre qui l’a ajouté : les étapes d’agent des automatisations dont ce membre est propriétaire. Il confirme chaque tâche à l’espace de travail avant de lancer la CLI. Pour une tâche, il écrit une configuration MCP temporaire avec l’adresse de votre espace de travail et la clé de cette tâche, lance la CLI avec le prompt de la tâche dans un dossier temporaire vide, renvoie chaque étape du travail de la CLI comme événement de transcription, et supprime la configuration quand la CLI a terminé. Ensuite, il attend la tâche suivante.

La CLI travaille en votre nom, vous, le membre qui a ajouté le runner, avec vos autorisations dans cet espace de travail. Elle utilise les outils de votre espace de travail via MCP avec une clé qui appartient à cette seule tâche. La clé ne fonctionne que sur l’adresse MCP de votre espace de travail et seulement pendant que la tâche s’exécute. Elle permet au plus 25 appels d’outils et refuse les appels qui demanderaient votre approbation dans le chat, comme supprimer des enregistrements ou modifier des rôles. Elle refuse aussi de créer, de modifier ou de supprimer des pages de la base de connaissances. Quand la consigne de l’étape contient du texte venu de l’extérieur de l’espace de travail, elle refuse aussi d’envoyer des e-mails ou des messages de chat, d’envoyer des invitations de mise en relation et de créer, de modifier ou de lancer des webhooks et des routines, comme décrit sous Que peut faire une étape d’agent ?.

De quoi a-t-il besoin ?

  • Node 24, ou Docker.
  • Claude Code, Codex ou Gemini CLI, installé et connecté sur cette machine. Sans CLI, le runner n’en signale aucune et ne prend aucune tâche. Tant qu’aucun de vos runners n’a signalé de CLI, une étape d’agent qui s’exécute sur votre propre runner n’attend pas : elle échoue aussitôt avec « Vous n’avez pas encore de runner prêt. Les runners sont personnels : chaque membre ajoute le sien. »
  • Une connexion réseau de cette machine vers l’adresse de votre Customermates. Le runner ne fait que des requêtes sortantes : il fonctionne derrière un pare-feu et n’a besoin d’aucun port ouvert.

Comment ajouter et démarrer un runner ?

  1. Ouvrez Paramètres, Agents et cliquez sur Ajouter un runner. Donnez-lui un nom qui indique de quelle machine il s’agit.
  2. Copiez le jeton. Il n’est affiché qu’une fois et commence par cmr_. Traitez-le comme un mot de passe : toute personne qui le possède peut récupérer vos tâches de runner dans cet espace de travail.
  3. Démarrez le runner sur cette machine, soit avec Node :
CUSTOMERMATES_RUNNER_TOKEN=cmr_... npx customermates-runner --url https://crm.example.com

soit avec Docker, en montant le dossier de connexion de votre CLI pour qu’elle reste connectée :

docker run -d --restart unless-stopped \
  -e CUSTOMERMATES_URL=https://crm.example.com \
  -e CUSTOMERMATES_RUNNER_TOKEN=cmr_... \
  -v "$HOME/.claude:/home/node/.claude" \
  -v "$HOME/.claude.json:/home/node/.claude.json" \
  ghcr.io/customermates/runner

L’adresse est celle à laquelle vous ouvrez Customermates ; sur une instance auto-hébergée, c’est votre propre BASE_URL. Elle peut aussi venir de CUSTOMERMATES_URL. Donnez son jeton au runner dans la variable CUSTOMERMATES_RUNNER_TOKEN, ou dans un fichier que seul votre compte peut lire, indiqué avec --token-file ou CUSTOMERMATES_RUNNER_TOKEN_FILE. Ne le passez pas en argument : une ligne de commande est visible par tous les utilisateurs de la machine. Sous macOS, Claude Code garde sa connexion dans le Trousseau, le dossier monté n’apporte donc aucune connexion dans le conteneur : passez ANTHROPIC_API_KEY, ou un jeton obtenu avec claude setup-token dans CLAUDE_CODE_OAUTH_TOKEN. Options utiles :

  • --client claude, codex ou gemini choisit la CLI qui exécute les tâches. Par défaut, c’est la première trouvée.
  • --workdir <dossier> exécute la CLI dans ce dossier. Par défaut, chaque tâche reçoit un dossier temporaire vide.
  • --permission-mode <mode>, --allowed-tools <outils> et --setting-sources <liste> définissent ce que Claude Code peut faire sans demander. Par défaut, seuls les outils de votre espace de travail sont autorisés et vos propres réglages Claude Code ne sont pas chargés.
  • --allow-shell laisse Codex exécuter des commandes shell dans son bac à sable en lecture seule. Par défaut, Codex n’a pas de shell.

Le runner écrit ses journaux sur sa sortie standard et n’affiche jamais son jeton.

Qu’envoie le serveur, et que n’envoie-t-il jamais ?

Le serveur envoie le prompt de la tâche, l’indication que des personnes extérieures peuvent influencer ce prompt, l’adresse MCP de votre espace de travail et la clé de la tâche. Quand le runner confirme la tâche, le serveur lui indique combien de temps elle peut durer. Il n’envoie jamais de secret de l’espace de travail, de clé de fournisseur ni de tâche d’un autre membre. La clé n’atteint que cet espace de travail, seulement en votre nom, et seulement pendant que la tâche s’exécute : le serveur la refuse avant que le runner ait confirmé la tâche et dès que la tâche est terminée, expirée ou annulée.

Le runner n’envoie jamais votre connexion à la CLI, vos fichiers ni votre environnement. Il envoie le nom de la machine, les CLI qu’il peut lancer, les événements de transcription (ce que l’agent a écrit, chaque appel d’outil avec un court résumé de ses arguments et chaque résultat d’outil, jetons retirés) et le résultat. Les transcriptions sont conservées avec la tâche : ne laissez donc pas une CLI afficher des secrets qui ne doivent pas être visibles. L’espace de travail conserve les 200 derniers événements d’une tâche : une exécution plus longue montre donc ses étapes les plus récentes.

Un prompt que des personnes extérieures peuvent influencer, par exemple un prompt qui contient une soumission de formulaire, un webhook entrant ou le nom d’un enregistrement, est signalé dans la tâche. Le runner l’entoure du même cadrage que le serveur MCP : le texte est une donnée, pas une instruction, et une demande qu’il contient de changer le comportement de l’agent est signalée, pas suivie.

Que peut atteindre la CLI sur ma machine ?

La CLI s’exécute sous le compte qui a démarré le runner. Présenter un texte comme une donnée réduit le risque qu’un modèle le suive, sans l’éliminer. Ce que pourrait faire une CLI trompée est borné par la clé de la tâche, décrite plus haut, et par ces réglages par défaut :

  • Claude Code ne peut appeler que les outils de votre espace de travail, ne charge que le serveur MCP de la tâche et ne charge pas vos propres réglages. Ses outils de fichiers restent dans le dossier vide de la tâche.
  • Codex s’exécute sans votre propre configuration et sans shell. Si vous démarrez le runner avec --allow-shell, les commandes s’exécutent dans le bac à sable en lecture seule de Codex, qui empêche d’écrire mais pas de lire : une commande peut lire tout fichier que votre compte peut lire, et les outils de votre espace de travail peuvent ensuite écrire ce contenu dans un enregistrement. Ne l’utilisez que sur une machine, dans un conteneur ou sous un compte qui ne contient rien d’autre.
  • Gemini CLI est démarré avec le seul serveur MCP de votre espace de travail autorisé. Ses outils intégrés suivent vos propres réglages Gemini.
  • Le jeton du runner et vos connexions aux CLI se trouvent dans votre compte sur cette machine. Une CLI que vous autorisez à exécuter des commandes peut les lire. Pour une séparation stricte, faites tourner le runner avec Docker ou sous son propre compte utilisateur.

Que devient une tâche ?

Une tâche attend dans la file jusqu’à ce qu’un runner de son propriétaire la prenne. Une prise en charge que le runner ne confirme pas en une minute, par exemple parce qu’il a été arrêté à ce moment, revient dans la file en quelques minutes. Une tâche qu’aucun runner ne récupère en 15 minutes se termine comme expirée. Une tâche confirmée peut durer un peu moins de dix minutes ; le runner arrête alors la CLI et tout ce qu’elle a lancé, et la tâche se termine comme expirée. Une tâche confirmée n’est jamais exécutée une seconde fois : si le runner disparaît pendant qu’elle s’exécute, la tâche se termine comme expirée quelques minutes après la fin de ses dix minutes. Si la CLI échoue, la tâche se termine comme échouée, avec la raison. Quand un runner est révoqué, ses tâches se terminent comme annulées. Une tâche déjà terminée, expirée ou annulée ne peut plus être modifiée par un rapport tardif d’un runner, et le runner arrête sa CLI quand l’espace de travail le lui indique.

Plusieurs runners peuvent travailler dans un même espace de travail. Les tâches d’un membre vont aux runners de ce membre, et chaque tâche à un seul d’entre eux. Une étape d’agent qui nomme un runner attend ce runner.

Comment savoir si un runner est en ligne ?

La carte Runners montre pour chaque runner sa machine, les CLI qu’il peut lancer et sa dernière activité, avec l’un de quatre états : En ligne s’il a été vu ces deux dernières minutes, Hors ligne s’il a été vu plus tôt, Jamais connecté s’il ne s’est pas encore signalé, et Révoqué. La carte se met à jour d’elle-même toutes les 30 secondes.

Quand vos tâches d’agent attendent et qu’aucun de vos runners capables de les prendre n’a été vu depuis 10 minutes, vous recevez une notification de type Alertes d’automatisation, une fois à chaque fois que le runner s’est absenté, avec un lien vers la carte Runners.

Comment révoquer un runner ?

Cliquez sur Révoquer sur le runner et confirmez. Le runner ne peut plus récupérer de tâches : sa prochaine requête est refusée et le programme s’arrête. Les tâches qu’il exécute, et celles qui attendent précisément ce runner, se terminent comme annulées, et leurs clés cessent aussitôt de fonctionner. Une révocation est irréversible. Pour réutiliser la machine, ajoutez un nouveau runner et démarrez-le avec le nouveau jeton. Révoquez un runner immédiatement si son jeton fuite. Un runner est aussi révoqué quand le membre qui l’a ajouté quitte l’espace de travail ou est désactivé. Un membre que la formule Free a mis en pause garde ses runners : pendant la pause, les requêtes du runner sont refusées et le programme s’arrête, et dès qu’une formule payante fait revenir le membre, le même jeton fonctionne de nouveau.

Pour les agents

Les runners parlent à l’espace de travail en REST avec Authorization: Bearer cmr_..., le jeton affiché à l’ajout du runner. Un jeton de runner n’atteint que ces cinq points d’accès, décrits dans la référence de l’API :

  • POST /api/v1/runner/heartbeat signale la machine et les CLI que le runner peut lancer.
  • POST /api/v1/runner/jobs/claim attend jusqu’à 25 secondes et répond 200 avec une tâche du membre du runner, son numéro de tentative et ses identifiants MCP, ou 204 si aucune n’est arrivée.
  • POST /api/v1/runner/jobs/{id}/start confirme la tentative prise en charge, démarre la tâche et répond combien de secondes elle peut durer.
  • POST /api/v1/runner/jobs/{id}/events ajoute des événements de transcription de cette tentative et répond 409 une fois la tâche close.
  • POST /api/v1/runner/jobs/{id}/result signale succeeded, failed ou timedOut pour cette tentative avec la réponse finale et, si la CLI les fournit, les jetons consommés.

Un jeton révoqué, un runner dont le membre a quitté l’espace de travail, a été désactivé ou est mis en pause par la formule Free, et un espace de travail en cours de suppression répondent 401.

Questions fréquentes

Customermates reçoit-il ma connexion à Claude Code, Codex ou Gemini ?

Non. Le runner lance la CLI que vous avez installée et connectée vous-même, sur votre machine. L’espace de travail ne lui envoie que le prompt et une clé pour cette seule tâche sur l’adresse MCP de votre espace de travail.

Quelqu’un hors de mon équipe peut-il faire faire quelque chose à mon runner ?

Seulement par un prompt que vous avez mis en place. Si un prompt contient du texte de personnes extérieures ou d’un enregistrement, la tâche le signale et le runner le présente comme une donnée, pas comme une instruction. Un modèle peut malgré tout se laisser tromper par un tel texte. Ce qu’il pourrait alors faire est limité : la clé de la tâche agit en votre nom, permet au plus 25 appels d’outils, refuse ce qui demande votre approbation et cesse de fonctionner quand la tâche se termine. Par défaut, Claude Code ne peut utiliser que les outils de votre espace de travail et Codex n’a pas de shell : n’élargissez cela que sur une machine de confiance.

Le runner d’un collègue peut-il exécuter mes tâches ?

Non. Un runner n’exécute que les tâches du membre qui l’a ajouté : la machine d’un autre membre ne reçoit donc jamais de clé qui agit en votre nom. Pour exécuter vos étapes d’agent sur un runner, ajoutez le vôtre.

Que se passe-t-il si ma machine est éteinte ?

Vos tâches attendent dans la file jusqu’à 15 minutes, puis se terminent comme expirées. Après 10 minutes sans l’un de vos runners, vous recevez une notification.

Puis-je faire tourner le runner sur un serveur ?

Oui. Toute machine avec Node 24 ou Docker, une CLI connectée et une connexion à l’adresse de votre Customermates convient, par exemple une machine virtuelle toujours allumée.