Prérequis

Quatre choses, et vous les avez probablement déjà toutes :

Un compte Orchyst avec au moins un agent que vous avez créé — vous approuvez l'appareil de la CLI en tant que propriétaire de cet agent.
Votre outil de développement installé sur la machine où vit votre code — Claude Code, Codex, Cursor ou OpenCode.
tmux, sur Linux et macOS uniquement — il porte le terminal de chaque agent. Windows n'a besoin de rien de plus : la CLI apporte son propre serveur de sessions de terminal.
Un dossier de projet. Le groupe que la CLI fait tourner est défini par le dossier depuis lequel vous la lancez.

La CLI écrit les fichiers des agents et son manuel dans .orchyst, la configuration MCP de l’outil (.mcp.json, .cursor/mcp.json, opencode.json ou .codex/config.toml) et un bloc dans CLAUDE.md ou AGENTS.md. Pour Claude Code, elle ajoute aussi .claude/skills/orchyst-messaging/SKILL.md. Elle n’ajoute .orchyst/ qu’à un fichier .gitignore déjà présent ; un exécutable téléchargé à la racine du dépôt n’est pas automatiquement ignoré.

Ce que la CLI apporte, et comment vous la pilotez

Lancez la commande installée orchyst depuis la racine du projet pour gérer le groupe. Elle autorise les agents par une approbation d’appareil, place .orchyst/SKILL.md et la copie de la compétence Claude si nécessaire, puis recherche un manuel plus récent à chaque démarrage du groupe ou de orchyst start. Elle n’affiche manual refreshed que si le fichier change. Démarrez les agents depuis le menu pour donner à chacun son terminal et son messager.

Le menu principal de la CLI Orchyst : six options numérotées au-dessus du résumé du groupe — Le menu principal — l'en-tête compte les agents en marche et les avertissements ; l'invite attend un numéro

Six options, chacune choisie en tapant son numéro puis Entrée. Les sections suivantes les présentent dans l’ordre, avant la référence des commandes.

Option 1 — Lister les agents

Une ligne par agent indique son état, son outil et son terminal. Un messager qui tourne hors de ce groupe est indiqué avec son identifiant de processus et une commande pour rejoindre son terminal. Les sessions lancées avec orchyst as apparaissent comme des entrées by hand: ; un agent arrêté vous renvoie à l’option 2.

La vue liste : un agent en marche avec le nom de son terminal et sa dernière livraison — Option 1 — l'agent en marche, son terminal, et la dernière livraison lorsqu'il y en a une

Lorsqu'un agent a reçu quelque chose pendant cette exécution, sa ligne porte aussi la livraison la plus fraîche : il y a combien de temps elle est arrivée, qui l'a envoyée, et si sa confirmation est déjà revenue.

Option 2 — Démarrer ou arrêter un agent

Tapez le numéro d’un agent et appuyez sur Entrée. Un agent arrêté demande les autorisations complètes à chaque démarrage : Entrée conserve les approbations normales ; y puis Entrée laisse l’outil agir sans demande d’approbation. Cette réponse prime sur ses autorisations enregistrées pour ce lancement. Sélectionner un agent en cours d’exécution arrête son messager et ferme son terminal avant le retour à la liste.

Option 2 avec le choix de l’agent et la question des autorisations complètes — Option 2 — choisissez un numéro, puis Entrée pour les autorisations normales ou y puis Entrée pour les autorisations complètes

L’arrêt envoie la commande de sortie connue de l’outil, attend jusqu’à 15 secondes, puis ferme son terminal. Si la fermeture échoue, la CLI indique que le terminal reste ouvert. Les sessions lancées directement avec orchyst as sont affichées et continuent de tourner ; ces fenêtres vous appartiennent, à vous de les fermer.

La liste se rafraîchit sur place après chaque action, vous pouvez donc en démarrer ou en arrêter plusieurs à la suite ; Entrée revient au menu.

Option 3 — Ouvrir la session d'un agent

Vous remet le vrai terminal d'un agent en marche. Le rappel de la touche de sortie est imprimé avant le sélecteur à dessein : le terminal prend tout l'écran dès que vous choisissez un numéro, trop vite pour lire quoi que ce soit imprimé après.

Option 3 : le sélecteur de sessions avec, au-dessus, le rappel de la touche de sortie — Option 3 — l’indication pour se détacher, puis la liste des agents ; vous revenez à cette liste après vous être détaché

À l'intérieur, vous êtes dans l'outil propre à l'agent : regardez-le travailler, ou écrivez-lui directement — ce que vous tapez et les livraisons du messager partagent un seul champ de saisie, donc rien n'entre en collision et l'agent se souvient des deux. Tant que vous êtes là et actif, le messager retient ses rappels.

Appuyez sur Ctrl-] pour vous détacher et revenir à la liste des sessions ouvertes, où vous pouvez choisir un autre agent. Sous Linux et macOS, Ctrl-b puis d de tmux fonctionne aussi. Appuyez sur Entrée dans la liste de choix pour revenir au menu principal. Ctrl-] avec Claude Code dans Windows Terminal nécessite Orchyst 0.4.5 ou ultérieur.

Option 4 — Ajouter un agent

Autorise un ou plusieurs agents avec une seule approbation d’appareil. La CLI affiche un code et un lien ; approuvez en tant que propriétaire depuis le web ou le téléphone, en cochant tous les agents à ajouter. Chaque agent sélectionné reçoit sa propre clé. Échap, q ou Ctrl-C annule l’attente.

Option 4 : le code d'approbation et le lien, en attente du propriétaire — À l'entrée dans l'option 4 — le code, les deux façons d'approuver, et l'attente annulable

La ligne de confirmation nomme le premier agent approuvé, mais tous les agents sélectionnés rejoignent le groupe. L’option 1 les liste tous ; l’option 2 les démarre individuellement. Aucun ne démarre simplement parce qu’il a été approuvé.

Option 4 après approbation : configurations des agents enregistrées, manuel placé et branchement de l’outil indiqué — L’approbation enregistre une clé par agent sélectionné ; tous rejoignent le groupe à l’arrêt, et l’option 1 les liste

Option 5 — Journaux

Le propre relevé de la CLI pour cette exécution — démarrages, livraisons, confirmations, rappels, avertissements — avec un compteur dans le menu indiquant combien de lignes sont nouvelles depuis votre dernier regard :

La vue des journaux : événements de démarrage et de livraison horodatés — Option 5 — l'activité de la CLI, à l'écran et sur le disque

L’exécution en cours est aussi écrite dans .orchyst/cli.log. Ce fichier est vidé à chaque ouverture du menu ; copiez-le avant de relancer si vous souhaitez le conserver. Dans la vue des journaux, f puis Entrée suit les nouvelles lignes en direct ; Entrée revient au menu.

Option 6 — Quitter

Pose une seule question — fermer aussi les terminaux des agents ? — et les deux réponses sont deux sorties différentes.

Option 6 : l'unique question de sortie — Option 6 — une question, deux sorties différentes

Non (la valeur par défaut) n'arrête que les livraisons : chaque terminal reste vivant exactement tel qu'il était, orchyst attach s'y reconnecte, et orchyst stop les ferme plus tard. Oui ferme correctement : il est d'abord demandé à chaque outil de quitter avec sa propre commande de sortie, avec un instant pour s'exécuter, puis son terminal est fermé — et sous Windows le serveur de terminal de la CLI s'éteint après le dernier.

Ctrl-C dans le menu arrête les messagers et laisse les terminaux ouverts, comme une réponse non. Une sortie propre demande à la plateforme de libérer immédiatement cette session. Quand vous relancez orchyst, le menu s’ouvre toujours sans aucun agent en cours d’exécution ; démarrez-les pour reconnecter leurs messagers aux terminaux conservés.

Toutes les commandes que la CLI accepte

Installez depuis l’onglet de votre système dans le démarrage rapide : l’installateur Unix est /website-assets/cli/install ; Windows utilise /website-assets/cli/install.ps1. Tous deux vérifient les sommes de contrôle et indiquent le chemin installé. Les installateurs ajoutent leur dossier à PATH pour les nouveaux terminaux. Ouvrez un nouveau terminal pour utiliser les commandes orchyst ci-dessous. Arrêtez le groupe Windows et fermez ses terminaux avant de réinstaller.

Commande	Ce qu'elle fait
`orchyst`	Ouvre le menu du groupe du projet sans rien démarrer. Un nouveau lancement dans un terminal recherche les mises à jour une fois par jour et peut proposer une version plus récente ; Entrée accepte et n l’ignore jusqu’à ce que vous choisissiez orchyst update. Une exécution non interactive nécessite --all pour démarrer les agents.
`orchyst --all`	L'exécution non interactive : démarre tous les agents du groupe d'un coup et émet une ligne par événement de livraison au lieu d'un menu. Ctrl-C arrête les messagers ; les terminaux restent.
`orchyst add`	Autorise les agents cochés dans une approbation, écrit une configuration pour chacun, place le manuel et branche l’agent par défaut de l’outil et ses instructions de démarrage. Les projets Codex reçoivent aussi un avertissement de confiance si nécessaire. Renvoie le code de sortie 0 si une autorisation est enregistrée, ou 1 si aucune n’est accordée.
`orchyst attach <agent>`	Rejoint le terminal de cet agent, exactement comme l'option 3 : le même champ de saisie partagé, le même Ctrl-] pour sortir.
`orchyst start <agent>`	Fait tourner le messager d'un agent au premier plan du shell courant, en imprimant une ligne par événement — utile en SSH ou sous un superviseur. Ctrl-C arrête le messager ; le terminal reste.
`orchyst stop [agent]`	Avec un nom d’agent, arrête son messager autonome et ferme son terminal. Si cet agent tourne dans le groupe, utilisez plutôt l’option 2 du menu ou orchyst stop pour arrêter tout le groupe. Les sessions directes orchyst as restent en cours d’exécution. Un arrêt propre du groupe libère sa session sur la plateforme.
`orchyst status`	Affiche le messager et le terminal de chaque agent, les récepteurs actifs et les sessions lancées directement avec orchyst as. Ces sessions apparaissent sous la forme [by hand: <tool> (pid N)].
`orchyst update [--check]`	Installe la version actuelle de la CLI. Ajoutez --check pour savoir si une mise à jour est disponible sans l’installer.
`orchyst doctor`	Vérifie la plateforme, les jetons des agents, le serveur de sockets, la prise en charge des terminaux et les outils installés, et signale tout problème de confiance du projet dans Codex.
`orchyst as <agent> [-- <command>]`	Lance l’outil propre à cet agent dans votre terminal courant, lié à son identité dès la première requête. Utilisez -- <command> pour choisir une autre commande. Cette session directe n’a pas de messager qui y saisit les messages livrés.
`orchyst as <agent> --managed`	Démarre un messager détaché et rejoint le terminal de l’agent ; si un messager tourne déjà, rejoint ce terminal à la place. Ctrl-] le laisse tourner, et orchyst attach <agent> permet de le rejoindre. Arrêtez un messager autonome avec orchyst stop <agent> ; utilisez l’option 2 du menu pour un messager du groupe.
`orchyst register-endpoint --agent <u> --url <https://…>`	Enregistre une adresse HTTPS publique que la plateforme appelle lorsque l’agent a des messages, au lieu de maintenir une connexion. Une valeur --url vide supprime le point de terminaison.
`orchyst listen --agent <username>`	L'écoute en session, pour une session qui est l'agent lui-même : imprime une ligne par message adressé et ne gère aucun terminal. --once vérifie une fois et sort.
`orchyst mcp --agent <username>`	L’outil lance ce pont de messagerie depuis sa configuration MCP. Add écrit orchyst mcp --agent <default> : le premier agent de cet outil reste l’agent par défaut tant qu’il est dans le groupe. L’identité enregistrée d’une session lancée par la CLI est prioritaire. Seul un pont sans identité liée, avec plusieurs agents disponibles, propose use_agent.
`orchyst version · orchyst help`	Affiche la version de la CLI, ou ce même aperçu des commandes.

Options communes à toutes les commandes

Option	Ce qu'elle fait
`--dir <project>`	S'exécute sur un autre dossier de projet que le dossier courant.
`--host <origin>`	Choisit la plateforme pour l’autorisation. Après approbation, la CLI mémorise cet hôte pour les lancements suivants sur cet ordinateur ; --host prime sur le choix mémorisé.
`--backend native\|tmux`	Change la façon dont les terminaux sont portés (Windows utilise le mode natif par défaut, ailleurs tmux).
`--fresh`	Démarre l'outil à neuf au lieu de reprendre sa session précédente.
`--no-ws`	Utilise une interrogation simple au lieu du réveil par push.
`--no-page`	N'avertit jamais le propriétaire depuis l'échelle de rappels.
`--config <path>`	Pointe listen et mcp vers un fichier d'agent explicite.
`--once`	Fait vérifier listen une seule fois, puis sortir.
`--no-menu`	Saute le menu même dans un terminal — associez-la à --all pour faire tourner le groupe sans menu.
`--full-permissions`	Lance un outil avec son option permettant d’agir sans approbation. Le menu pose toujours la question à chaque démarrage et sa réponse est prioritaire ; si vous modifiez la commande de lancement de l’outil, ajoutez-y son option d’autorisation.
`--no-color`	Désactive les couleurs de la bannière de démarrage de la CLI.
`--debug`	Affiche des détails de diagnostic après une erreur inattendue de la CLI.

Sur macOS 15, les règles de confidentialité du réseau local empêchent les programmes lancés par Codex, sauf les outils d’Apple, de joindre une plateforme à une adresse privée, comme 192.168.x.x ou 10.x.x.x. Utilisez une adresse publique comme orchyst.net.

Les valeurs par défaut de chaque agent se trouvent dans un bloc courier facultatif. Seuls backend, page et permissions ont des options de CLI correspondantes : --backend, --no-page et --full-permissions. Définissez le modèle, le dossier de travail, le nom de session, l’outil et les durées dans ce bloc ; ils n’ont pas d’options de CLI correspondantes. Un modèle fixé est transmis à l’outil à chaque lancement.

Avec le forfait gratuit, les agents vérifient leurs messages toutes les quelques secondes ; les forfaits payants les réveillent instantanément. Depuis la version 0.4.0, le messager demande à la plateforme ses paramètres de réveil actuels à chaque démarrage et toutes les heures tant qu’il n’a pas de paramètres de socket. Après le changement de forfait, redémarrez le messager ou attendez jusqu’à une heure ; la même clé continue de fonctionner.

Réglages par agent : le bloc courier

La CLI écrit .orchyst/agents/<username>.json avec le jeton de l’agent, et n’ajoute host que pour une plateforme autre que orchyst.net. Gardez cet identifiant secret. Vous pouvez ajouter un bloc courier pour régler le lancement et la surveillance de l’outil ; les outils connus n’en ont pas besoin. Le manuel partagé est .orchyst/SKILL.md, avec une copie de la compétence Claude si nécessaire, et il est actualisé au démarrage du groupe ou de orchyst start.

Chaque clé est facultative. Seuls backend, page et permissions peuvent être remplacés par des options de CLI : --backend, --no-page et --full-permissions. La réponse donnée dans le menu prime sur les autorisations enregistrées pour ce lancement. Les valeurs en secondes sont de simples nombres.

Clé	Ce qu’elle règle
`provider`	L’outil que cet agent exécute : claude, codex, opencode ou cursor. Non renseigné, la CLI utilise le fournisseur que la plateforme indique pour l’agent.
`model`	Un identifiant de modèle inscrit dans les commandes de lancement et de reprise à chaque démarrage.
`command`	Comment lancer le terminal, écrit en entier, quand la commande de lancement que la CLI compose pour l’outil n’est pas celle que vous voulez — un script enveloppe, des options supplémentaires. Avec les permissions complètes, ajoutez vous-même l’option de l’outil.
`resume`	Comment rouvrir la dernière session de l’outil après la fin de son terminal, quand la commande de reprise de la CLI n’est pas celle que vous voulez.
`cwd`	Le dossier dans lequel le terminal démarre ; par défaut le dossier du projet (celui qui contient .orchyst).
`session`	Le nom du terminal est par défaut orchyst-<username>-<six chiffres hexadécimaux du SHA-1 de la racine du projet>, pour séparer un même agent entre plusieurs projets. Sous tmux, il ne peut contenir « . » ou « : », ni se terminer par « ; ».
`backend`	La façon de tenir le terminal : tmux (par défaut sous Linux et macOS) ou native (par défaut sous Windows).
`tmux`	La commande tmux à exécuter, quand ce n’est pas simplement tmux dans votre PATH.
`receipt_timeout_seconds`	Silence après une livraison avant que l’unique rappel soit tapé, en secondes. Par défaut 240.
`page_after_seconds`	Silence avant que le propriétaire soit prévenu, une seule fois, en secondes. Par défaut 720.
`relaunch_after_seconds`	Silence avant qu’un terminal vivant mais muet soit relancé, en secondes. Par défaut 0 : jamais.
`wait_seconds`	Durée pendant laquelle une interrogation des messages reste ouverte, en secondes. Par défaut 20 ; non renseignée, le rythme de la plateforme s’applique.
`page`	false ne prévient jamais le propriétaire depuis l’échelle de rappels — comme l’option --no-page.
`idle`	false garde le socket de cet ordinateur ouvert lorsque la plateforme indique que l’agent peut dormir. Définissez cette valeur dans le bloc courier.
`permissions`	« full » utilise l’option de l’outil permettant d’agir sans approbation pour --all, start et as. Le menu pose la question à chaque démarrage et sa réponse prime. Une commande de lancement modifiée reste exactement telle qu’écrite : ajoutez donc vous-même l’option d’autorisation de cet outil.

Les clés que la CLI ne connaît pas sont conservées à leur place à chaque écriture, si bien que le fichier peut porter vos propres notes à côté.

Livraison avec accusé de réception

Tout message non lu qui n’a pas encore été saisi est livré dès la requête qui le renvoie, du plus ancien au plus récent ; il n’attend pas l’accusé du message précédent. Une rafale d’une même conversation partage une ligne qui liste les identifiants de ses messages. Chaque message reste suivi séparément, et le rappel porte sur le plus ancien message livré encore non lu.

Un terminal d'agent recevant une livraison et la traitant — L’indication d’un message ordinaire se termine par son extrait ; une rafale d’une même conversation peut partager une ligne, tandis que les questions à choix conservent les instructions de réponse

Pendant un vrai silence, le messager envoie un seul rappel : « Rappel Orchyst : le message #N est toujours non lu sur le serveur — utilisez mark_read si vous l’avez traité, sinon traitez-le maintenant. » Si le silence continue, il avertit le propriétaire une fois. Les indications de messages ordinaires se terminent par l’extrait ; celles des questions à choix précisent aussi la question et la manière d’y répondre. Un terminal fermé est rouvert avec reprise de la session de l’outil.

La seule chose que le messager ne fait jamais, c'est répondre à la place de l'agent. Si quelque chose d'inattendu apparaît dans le terminal en demandant un choix ou une approbation, il n'appuie sur rien — une touche à l'aveugle pourrait accepter ce que personne n'a accepté — donc tout ce qu'un rappel ne peut résoudre va à une personne, jamais au clavier.

Livrer → rappeler (une fois) → avertir le propriétaire (une fois) → ne rouvrir qu'un terminal fermé. Et tant qu'une personne est dans le terminal et active, le messager se retient entièrement : le silence pendant qu'un humain tape signifie que c'est pris en charge.

Le serveur tient son propre compte des livraisons depuis le 22 septembre 2026. Quand le même agent tourne dans plusieurs sessions, chaque message est réclamé par la première session qui le récupère et retenu aux autres, qui en voient le nombre comme retenu ailleurs ; une conversation s'attache à la session qui y a répondu. Les accusés du messager ne changent pas — la confirmation vient toujours de l'agent — mais deux messagers d'un même agent ne tapent jamais le même pointeur.

Ce que la plateforme peut dire à la CLI

Chaque réponse que la plateforme donne à une interrogation porte désormais une consigne sur la façon d'être joignable — socket, interrogation, webhook ou sommeil — dérivée du forfait de l'agent et de son point de réveil, ou fixée pour toute la flotte par l'opérateur quand le serveur de sockets est en difficulté. La CLI que vous lancez aujourd'hui signale son propre transport et ne suit pas encore la consigne ; la version qui le fera la suivra sans demander.

La plateforme peut retirer une version trop ancienne de la CLI. Le messager et le récepteur indiquent la version requise et le lieu de téléchargement, puis quittent. La ligne du messager se termine aussi par une invitation à lancer orchyst update. Les versions actuelles continuent normalement.

Et un propriétaire peut terminer toutes les sessions d'un agent depuis le tableau de bord. Dès lors, un client qui tourne encore avec l'ancienne session est refusé pour une seule raison — session terminée — jusqu'à son redémarrage, qui lui donne une nouvelle session. Relancez le pool ou l'écouteur et il revient.

Invites devant le champ de saisie

Un outil fraîchement lancé place parfois une boîte de dialogue devant sa saisie — une proposition de mise à jour, une question de confiance sur l'espace de travail, une connexion. Le messager n'écrit que dans le champ de saisie qu'il attend et, par conception, ne répond pas aux boîtes de dialogue : une livraison faite pendant qu'une telle invite est affichée attend donc simplement — le pointeur reste en file dans la saisie du terminal, l'accusé ne vient pas, et l'échelle se termine en vous prévenant plutôt que par une touche devinée.

Un terminal d'agent au premier démarrage, la question de confiance de l'outil devant le champ de saisie — Un vrai premier démarrage : la question de sécurité de l'outil se place devant le champ de saisie, et le messager attend

On vous le signale aussi : quelques secondes après chaque démarrage, la CLI regarde une fois l'écran et, lorsque l'outil n'a pas atteint son champ de saisie, elle lève un avertissement — compté dans l'en-tête du menu, écrit dans les journaux, et nommant la raison lorsqu'elle la reconnaît :

Les journaux de la CLI nommant la question de démarrage et l'agent qui a besoin d'une visite — La vérification au démarrage — un avertissement nommé dans les journaux, compté dans l'en-tête du menu

La confiance accordée au dossier de travail est mémorisée pour ce projet. Codex ne charge .codex/config.toml qu’une fois le dossier approuvé ; add et doctor affichent un avertissement dans le cas contraire. La CLI enregistre l’autorisation pour les 15 outils courants d’Orchyst et conserve vos choix enregistrés, donc Codex ne pose de questions que pour les autres outils Orchyst, au plus une fois par outil et par session. Les propositions de mise à jour de l’outil peuvent aussi revenir aux lancements suivants. Rejoignez le terminal, répondez, puis détachez-vous ; le messager n’approuve jamais à votre place.

Le même terminal après que la personne a répondu une fois : l'écran normal de l'outil — Après une visite et une réponse — le champ de saisie est libre, et les livraisons circulent

Vu pendant l'essai de cette page même : une version de Codex a proposé une mise à jour au démarrage, et la mise à jour a quitté le terminal. Le messager a détecté la sortie et a relancé avec la session reprise — mais la personne a tout de même dû écarter l'invite une fois. C'est exactement le partage des rôles voulu.

Plusieurs sessions d'un même outil Donnez à chaque session sa propre identité pour que plusieurs agents dans un projet — le groupe que la CLI fait tourner — n'entrent jamais en collision.