Photon iMessage Kit permet à Hermes Agent de recevoir et envoyer des messages iMessage sans héberger toi-même un serveur Apple ni un webhook public. Cette connexion Hermes iMessage repose sur une passerelle gRPC persistante : Hermes garde un canal ouvert vers Photon, reçoit les conversations autorisées, puis renvoie les réponses de l’agent.
Le montage est séduisant, mais il faut distinguer trois couches pour le rendre fiable : le compte Photon, la passerelle Hermes et les règles d’autorisation. Quand un message ne passe pas, chercher au hasard dans « iMessage » fait perdre du temps. Ce guide te donne l’installation propre et un diagnostic couche par couche.
Par Louis LAURENT · Publié le 2 août 2026 · Mis à jour le 12 octobre 2026 : installation en 1 commande, appairage, limites actuelles d’après la documentation officielle de Hermes Agent
En bref. En octobre 2026, Photon relie Hermes Agent à iMessage sans Mac relais, sans webhook et sans URL publique. La ligne partagée est gratuite. hermes photon setup --phone +33… crée le projet, enregistre ton numéro et t’affiche la ligne à qui écrire. Un inconnu qui écrit à ta ligne reçoit un code d’appairage que tu approuves. Limite à connaître : l’agent envoie des images, des vocaux et des documents, mais il ne lit pas encore le contenu des pièces jointes qu’on lui envoie.
Ce qui a changé côté Photon en octobre 2026
Point | Ce que dit la documentation officielle |
|---|---|
Prix | La ligne partagée est gratuite, sans abonnement. La formule Business payante donne le même numéro dédié à tous tes utilisateurs |
Installation |
|
Architecture | Un petit processus Node (le SDK |
Démarrage |
|
Accès | Appairage par défaut ( |
Groupes |
|
Pièces jointes | Envoi d’images, vocaux, vidéos et documents pris en charge ; en réception, l’agent voit seulement le nom et le type du fichier |
Ligne partagée | Elle ne peut écrire qu’à un numéro qui lui a déjà écrit : un message programmé vers un nouveau contact est refusé par Photon |
Source : page Photon iMessage de la documentation Hermes Agent, relue le 12 octobre 2026. Si tu découvres Hermes, commence par notre guide complet de Hermes Agent, et pour le comparer aux autres agents personnels, lis notre guide d’OpenClaw et notre panorama des agents IA open source.
Comment fonctionne Photon avec Hermes Agent
La documentation Photon officielle de Hermes décrit Photon comme une passerelle iMessage gérée. Tu n’as pas besoin d’exposer un port public, de créer un webhook ou de maintenir un Mac serveur pour cette intégration.
Hermes lance une connexion gRPC persistante vers le service. Photon transmet les messages entrants, Hermes exécute l’agent puis la réponse repart par le même canal.
Le flux ressemble à ceci :
un contact envoie un iMessage au numéro Photon
Photon associe le message à ton projet
la passerelle Hermes reçoit l’événement via gRPC
Hermes charge la conversation et exécute le modèle configuré
la réponse est envoyée au contact par Photon
Cette architecture retire la difficulté du réseau entrant, mais elle ne retire pas les dépendances. Une clé incorrecte, une passerelle arrêtée, une liste d’autorisation trop stricte ou un contact jamais initialisé peut toujours bloquer le flux.
Ligne partagée ou numéro dédié
Photon propose deux approches mentionnées dans la documentation Hermes.
La formule gratuite utilise des lignes partagées. Elle convient à un prototype personnel ou à un test contrôlé. Une limitation importante s’applique : une ligne partagée gratuite ne peut pas démarrer une conversation avec un numéro qui ne l’a jamais contactée. Le destinataire doit donc envoyer le premier message.
La formule Business fournit un numéro dédié. Elle est plus cohérente pour un service utilisé par plusieurs personnes, une identité stable ou un usage où l’agent doit initier certaines conversations.
Ne présente pas une ligne partagée comme un numéro professionnel permanent. Le choix dépend du besoin : valider le système avec peu de coût, ou fournir une expérience stable à des utilisateurs réels.
Prérequis avant l’installation
Avant de connecter Photon, vérifie que Hermes Agent fonctionne déjà localement. Une intégration de messagerie ne doit pas servir à diagnostiquer simultanément le modèle, la mémoire et la passerelle.
Tu dois disposer de :
Hermes Agent installé depuis sa source officielle
un modèle déjà configuré et capable de répondre dans le terminal
un compte Photon et un projet actif
les identifiants du projet Photon
un environnement qui peut maintenir un processus Hermes actif
Node.js : Hermes utilise sa version gérée si elle est installée (
hermes pm install node), sinon celle du systèmeun numéro de téléphone qui reçoit iMessage, pour lier ton compte
Fais d’abord une conversation locale avec Hermes. Si l’agent ne répond pas dans son interface de base, Photon ne réparera pas le problème.
Pense aussi à la sécurité. Les messages peuvent contenir des informations privées. Vérifie quel modèle traite les conversations, quelles données sont conservées et qui a accès au numéro.
Installer Photon avec la commande guidée
Hermes fournit un assistant de configuration via la passerelle. D’après la documentation actuelle, tu peux lancer :
hermes gateway setup
L’assistant présente les plateformes disponibles, récupère les paramètres nécessaires et prépare le canal Photon.
Une commande dédiée est aussi documentée :
hermes photon setup --phone TON_NUMERO
Remplace la valeur par le numéro attendu au format demandé par Photon. Utilise la commande et les options exactes affichées dans la version de Hermes installée : un tutoriel ancien peut viser une structure de plugin qui a depuis changé.
L’installation enregistre notamment PHOTON_PROJECT_ID et PHOTON_PROJECT_SECRET dans le fichier d’environnement Hermes, généralement ~/.hermes/.env. Des métadonnées d’authentification peuvent également être écrites dans un fichier comme auth.json.
Ne copie jamais ces valeurs dans un dépôt ou un ticket de support public. Pour vérifier la configuration, confirme que les variables existent sans afficher leur contenu.
Démarrer la passerelle Hermes
Une fois le canal configuré, la passerelle doit tourner. La commande documentée est hermes gateway start. Le journal doit afficher une ligne du type « [photon] connected », avec le processus Node local sur 127.0.0.1:8789. Ensuite, hermes photon status liste les secrets enregistrés, ton numéro, la ligne attribuée et l’état des dépendances.
Le point important est observable : un processus actif doit établir la connexion gRPC vers Photon. Un fichier .env correct ne suffit pas si aucun service ne le lit.
Après le démarrage, cherche dans les journaux :
le chargement du canal Photon
l’authentification du projet
l’établissement de la connexion gRPC
l’absence de boucle de reconnexion immédiate
la réception d’un premier événement
Garde les journaux ouverts pendant le premier test. Ils permettent de savoir si le message arrive jusqu’à Hermes ou s’il reste bloqué avant.
Faire le premier test iMessage
Avec une ligne partagée, envoie le premier message depuis ton téléphone vers le numéro Photon. Utilise une phrase reconnaissable, par exemple « test photon 14h32 », afin de la retrouver facilement dans les logs.
Le test complet doit prouver quatre étapes :
le message est livré côté iMessage
Photon le transmet au projet
Hermes crée ou retrouve la bonne session
la réponse revient sur le même fil
Une simple réponse ne valide pas tout le système. Envoie ensuite un second message qui dépend du premier, par exemple « quel mot ai-je envoyé juste avant ? ». Cela vérifie que le routage conserve la conversation attendue.
Teste enfin une pièce jointe seulement après le texte. La prise en charge des médias ajoute une couche de téléchargement, de type MIME et de taille. Commencer par une image quand le texte ne fonctionne pas brouille le diagnostic.
Contrôler qui peut parler à l’agent
Un numéro de messagerie est une entrée vers ton agent. S’il peut appeler des outils, lire des fichiers ou déclencher des actions, l’accès doit être explicite.
Utilise une liste d’autorisation pour les premiers tests. Seuls tes numéros et ceux des testeurs prévus doivent pouvoir obtenir une réponse. Ne donne pas immédiatement à l’agent des outils sensibles depuis une surface publique.
Hermes propose deux modes. Par défaut, un numéro inconnu reçoit un code d’appairage, que tu approuves avec hermes pairing approve photon CODE (hermes pairing list affiche les demandes en attente). Si tu renseignes PHOTON_ALLOWED_USERS dans ~/.hermes/.env, les inconnus sont ignorés sans code. PHOTON_ALLOW_ALL_USERS=true ouvre l’accès à tout le monde : réserve-le au développement.
Sépare les capacités :
répondre à une question générale
lire une mémoire personnelle
écrire dans un fichier
envoyer un message à un tiers
déclencher une action externe
La réception d’un iMessage ne doit jamais être considérée comme une autorisation universelle. Le texte du message peut contenir une instruction malveillante ou provenir d’un contact compromis.
Si plusieurs personnes utilisent le numéro, vérifie que les sessions sont isolées par contact. Deux utilisateurs ne doivent pas partager accidentellement le même historique ou la même mémoire privée.
Erreur 1 : Hermes ne se connecte pas à Photon
Si les logs indiquent un échec de connexion ou une reconnexion permanente, commence par la couche réseau et la version du plugin.
Contrôles utiles :
la machine a accès à Internet
la date et l’heure système sont correctes
les identifiants Photon appartiennent au bon projet
le secret ne contient pas d’espace ajouté lors du copier-coller
Hermes et ses dépendances sont à jour selon la branche recommandée
Le plugin Photon s’appuie sur des dépendances gRPC. Des issues historiques du dépôt Hermes ont documenté des incompatibilités de version ou des hôtes devenus invalides. La bonne réaction : utiliser la version actuellement épinglée par le projet, puis réinstaller les dépendances avec la méthode officielle, plutôt qu’un ancien correctif trouvé au hasard. Si hermes photon status indique des dépendances manquantes, lance hermes photon install-sidecar.
Consulte le README actuel du plugin Photon et les issues récentes avant de modifier un paquet manuellement. Un contournement valable en juin peut être faux en août.
Erreur 2 : authentification refusée
Une erreur d’authentification vient généralement d’un mauvais couple identifiant-secret, d’un fichier d’environnement non chargé ou d’un projet désactivé.
Vérifie le chemin du fichier utilisé par le processus réel. Une commande lancée à la main et un service système peuvent avoir des environnements différents. Tu peux avoir correctement rempli ~/.hermes/.env alors que le service tourne sous un autre utilisateur ou avec un autre répertoire de travail.
Confirme aussi que les noms de variables sont exactement ceux attendus : PHOTON_PROJECT_ID et PHOTON_PROJECT_SECRET. Ne journalise pas leur valeur complète. Affiche au besoin leur présence et leur longueur, pas leur contenu.
Si tu régénères un secret dans Photon, redémarre proprement la passerelle pour qu’elle recharge la nouvelle valeur.
Erreur 3 : le message arrive, mais l’agent ne répond pas
Quand l’événement apparaît dans les logs mais qu’aucune réponse ne repart, Photon a fait sa partie. Le problème se situe dans Hermes, le modèle ou l’autorisation.
Cherche :
une erreur de fournisseur de modèle
un quota ou une clé API expirée
une liste d’autorisation qui rejette le contact
une exception lors du chargement de la session
un outil qui bloque la boucle avant la réponse finale
Teste le même prompt directement dans Hermes. S’il échoue aussi localement, corrige le modèle ou la configuration centrale. S’il fonctionne localement, compare la session, l’identité du contact et les règles spécifiques au canal Photon.
Évite de redémarrer tous les services sans lire les logs. Tu risques d’effacer l’état précis qui explique la panne.
Erreur 4 : la réponse part vers le mauvais fil
Le routage doit relier un identifiant Photon, un numéro et une session Hermes. Une mauvaise normalisation du numéro ou un ancien état local peut créer une conversation séparée.
Compare l’identifiant exact reçu dans les événements. Les formats internationaux, espaces et préfixes peuvent différer de la valeur affichée dans Contacts.
Ne fusionne pas manuellement plusieurs sessions sans savoir laquelle contient l’historique correct. Fais un test neuf avec un numéro autorisé et un message unique, puis observe la clé de session créée.
Si le problème apparaît après une mise à jour, consulte les issues et commits du dépôt. Le plugin Photon a déjà reçu des corrections sur la pagination ou les curseurs de messages. Utiliser la version courante est plus sûr que recopier un patch historique.
Pièces jointes et messages riches
En octobre 2026, la documentation distingue deux sens. En envoi, Hermes sait transmettre des images, des notes vocales, des vidéos et des documents, ainsi que des sondages ; la légende arrive dans une bulle séparée, après le média. En réception, l’agent voit seulement le nom et le type du fichier, sans pouvoir lire son contenu. Teste chaque type que tu comptes utiliser : image, document, message contenant plusieurs médias et fichier trop lourd.
Ton agent doit traiter une pièce jointe comme une donnée non fiable. Il ne doit pas exécuter un fichier reçu ni suivre automatiquement une instruction contenue dans un document.
Pour chaque média, conserve au minimum :
l’expéditeur
le type de fichier détecté
la taille
la date de réception
l’action réellement effectuée
Si le modèle ne sait pas analyser le type reçu, il doit l’annoncer plutôt qu’inventer son contenu.
Faire tourner la passerelle sans interruption
Pour un test de quelques minutes, une commande interactive suffit. Pour un usage quotidien, la passerelle doit être supervisée par un gestionnaire de service adapté à ton système.
Le service doit :
démarrer après le réseau
redémarrer en cas de crash limité
garder des logs consultables
charger le bon environnement
éviter plusieurs instances concurrentes
Une boucle de redémarrage infinie peut masquer une authentification cassée et saturer les journaux. Ajoute un délai et un nombre de tentatives raisonnables.
Surveille trois signaux simples : processus actif, connexion Photon établie et dernier message traité. Un processus vivant mais déconnecté n’est pas un service sain.
La checklist de mise en service
Avant de considérer l’intégration comme prête, vérifie :
Hermes répond correctement hors iMessage
le projet Photon est actif
les secrets sont stockés hors des dépôts
la passerelle établit une connexion gRPC stable
le premier message part du contact si la ligne partagée l’exige
la réponse revient dans le bon fil
un second message conserve le bon contexte
les contacts non autorisés sont rejetés
les sessions de plusieurs utilisateurs restent séparées
les pièces jointes sont testées sans exécution automatique
les logs permettent de diagnostiquer chaque couche
Photon retire une grosse partie de l’infrastructure nécessaire pour relier Hermes Agent à iMessage. Il ne retire pas le besoin de permissions, de supervision et de preuves. Monte d’abord un canal personnel limité, valide le routage, puis ouvre progressivement l’accès et les outils.
Pour comprendre le reste de l’installation, de la mémoire et des tâches planifiées, lis aussi notre guide complet de Hermes Agent.
Pour recevoir les prochains tutoriels sur les agents personnels et leurs intégrations, rejoins la newsletter Kryve.
Le vocabulaire utile pour diagnostiquer Photon
Dans les journaux et la documentation, certaines actions restent nommées en anglais : run Hermes, send messages, send attachments, group chats ou iMessage conversation. Repérer ces termes aide à distinguer un problème de lancement d’Hermes, d’envoi de message, de pièce jointe ou de conversation de groupe sans modifier la sécurité du compte.
Questions fréquentes
Photon est-il gratuit pour Hermes Agent ?
Oui pour la ligne partagée : aucun abonnement n’est demandé pour envoyer ton premier iMessage depuis Hermes. La formule Business, payante, donne un numéro dédié et identique pour tous tes utilisateurs.
Faut-il un Mac pour connecter Hermes à iMessage ?
Pas avec Photon : le service gère les lignes Apple. Il te faut une machine qui fait tourner Hermes et Node.js, plus un numéro qui reçoit iMessage pour lier ton compte.
Mon agent peut-il écrire le premier à un contact ?
Avec une ligne partagée, seulement si ce contact a déjà écrit à la ligne. Sinon, Photon refuse l’envoi. Pour qu’un agent lance des conversations, il faut un numéro dédié.
L’agent peut-il lire les photos qu’on lui envoie ?
Pas encore : il reçoit le nom et le type du fichier, sans son contenu. Il peut en revanche envoyer des images, des vocaux, des vidéos et des documents.
Sources
Hermes Agent Docs, Photon iMessage : prix, installation, appairage, variables, limites, consulté le 12 octobre 2026
