CLI, API et MCP
Tout ce que fait l'application peut aussi être piloté sans sa fenêtre. Le binaire de l'application — bromure-ac, dans Bromure Agentic Coding.app/Contents/MacOS/ — est aussi une CLI multi-commandes, un plan de contrôle HTTP, un serveur MCP pour les outils d'IA externes et une cible AppleScript. À l'intérieur de chaque VM, un ensemble de serveurs MCP intégrés donne aux agents leur propre vue de Bromure. Ce chapitre est la référence de tous ces éléments.
Les surfaces, de l'extérieur vers l'intérieur :
- La ligne de commande
bromure-cli— une CLI à la Docker/kubectl pour les machines, les VM, les terminaux, les commandes, les traces, les modèles, l'accès à distance et l'inscription. - Le plan de contrôle — les mêmes opérations en JSON sur HTTP, sur un socket Unix réservé au propriétaire et, en option, sur un port TCP loopback.
- Le serveur MCP d'AC (
bromure-ac mcp) — permet à un outil d'IA sur votre Mac (Claude Code, Claude Desktop) de gérer l'application. - Les serveurs MCP intégrés à l'invité — présents dans chaque VM : le navigateur, les automatisations, l'infrastructure, la délégation et, pour certaines sessions, le tableau des tâches et le Standard.
- AppleScript — le dictionnaire Bromure AC Suite.
Dans tout ce chapitre, comme dans la CLI, une machine est appelée espace de travail (son nom dans l'éditeur de réglages et en ligne de commande). Les sessions au sens de conversations d'agent sont accessibles via les routes /agent-sessions ; les anciennes routes /sessions et le terme session dans la CLI et AppleScript désignent la fenêtre d'une machine.
Le plan de contrôle : socket et API
Chaque surface parle HTTP à l'application en cours d'exécution via l'un de deux transports :
| Transport | Où | Contrôle d'accès | Activé par défaut |
|---|---|---|---|
| Socket de contrôle | ~/Library/Application Support/BromureAC/control.sock (domaine Unix, HTTP/1.1) | Permissions de fichier — le socket est en mode 0600, réservé au propriétaire. Atteindre le fichier constitue l'autorisation, à la manière du socket Docker. | Oui, dès que l'application ou un agent sans interface s'exécute |
| API d'automatisation | 127.0.0.1:9223 (TCP) | Loopback uniquement par défaut ; la plupart des routes de contrôle nécessitent en outre la variable d'environnement BROMURE_DEBUG_CLAUDE, et certaines ne sont jamais servies sur TCP (voir Modèle d'authentification) | Non — activation explicite dans Préférences › Automatisation |
La CLI ne parle jamais directement à une VM. Chaque sous-commande est un client HTTP léger sur le socket de contrôle, de sorte que les mêmes commandes fonctionnent localement et — lorsque le socket est tunnelé via SSH — sur une instance distante depuis un client riche. Si aucun agent ne s'exécute lorsque vous invoquez une commande qui en nécessite un, la CLI démarre automatiquement un agent d'arrière-plan sans fenêtre (bromure-ac run --headless) et attend jusqu'à 40 secondes qu'il réponde à /health. Les commandes en lecture seule (vm ls, describe, trace …) ne déclenchent pas de démarrage automatique ; elles affichent No bromure-ac agent running. à la place.
Remarque : Le socket de contrôle est toujours disponible tant que l'application s'exécute et est indépendant du commutateur Activer le serveur d'automatisation. Ce commutateur ne régit que l'écouteur TCP sur le port 9223. Vous n'avez pas besoin d'activer l'API d'automatisation pour utiliser la CLI.
La ligne de commande bromure-cli
Vous pouvez appeler le binaire par son chemin complet dans le paquet, mais le nom court est plus pratique. Choisissez Bromure Agentic Coding › Installer l’outil en ligne de commande… dans le menu de l'application. L'alerte Installer l’outil en ligne de commande « bromure-cli » ? explique qu'elle crée un lien symbolique à /usr/local/bin/bromure-cli et qu'elle a besoin de votre mot de passe administrateur une fois ; cliquez sur Installer (ou Annuler). En cas de succès, Outil en ligne de commande installé vous invite à exécuter bromure-cli --help. L'application ne le propose plus jamais au lancement — l'élément de menu est le seul moyen, et vous pouvez le relancer à tout moment (par exemple après avoir déplacé l'application).
Le même binaire se comporte différemment selon le nom sous lequel il est appelé :
- Sous le nom
bromure-cli, il masque les commandes internes de l'application — la gestion des images (init,info,resetet les outils du pipeline de publication), le serveurmcpet la valeur par défautrunde l'interface graphique — et n'expose que les groupes destinés au terminal (Workspaces, Tracing, Local inference, Enterprise features,remote). Unbromure-cliseul affiche l'aide au lieu de lancer l'application. - Sous le nom
bromure-ac(le binaire dans le paquet de l'application), tout est disponible et la sous-commande par défaut estrun, qui lance l'interface graphique.
Les exemples ci-dessous utilisent bromure-cli ; utilisez le chemin complet …/MacOS/bromure-ac pour les commandes qu'il est seul à exposer.
Les commandes acceptent l'id d'un espace de travail, un préfixe d'id court ou son nom partout où un argument d'espace de travail apparaît. Les groupes de commandes vm et workspaces sont des alias l'un de l'autre. Ce qu'est une machine, et son rapport avec les sessions, est expliqué dans Machines.
L'application et l'agent d'arrière-plan
| Synopsis | Ce qu'elle fait |
|---|---|
bromure-ac run [--headless] | Sous-commande par défaut (masquée) — lance l'interface graphique. --headless exécute un agent accessoire de barre de menus sans fenêtre ; c'est ce que la CLI démarre automatiquement pour servir le socket de contrôle. |
Gestion des images
L'image de base est installée une seule fois. Ces commandes n'existent que sous le nom bromure-ac.
| Synopsis | Ce qu'elle fait |
|---|---|
bromure-ac init [--build-local] | Installe l'image de base Ubuntu : télécharge l'image préconstruite, avec repli sur une compilation locale en cas d'échec du téléchargement. --build-local force la compilation locale. |
bromure-ac info | Affiche la version de l'image de base, sa taille virtuelle, sa taille sur disque et son chemin. |
bromure-ac reset [--yes] | Supprime l'image de base (disque, variables EFI, marqueur de version, état) pour que le prochain init reparte de zéro ; demande confirmation sauf avec --yes. |
bromure-ac init-foss-image --output <dir> | Pipeline de publication uniquement — compile dans <dir> l'image de base redistribuable composée uniquement de logiciels libres. |
bromure-ac verify-image --disk <path> [--timeout 300] | Pipeline de publication uniquement — démarre sans interface un clone jetable et exige l'invite de connexion série dans le délai imparti. |
Remarque : S'il n'existe aucune image de base, lancer l'interface graphique vous dirige vers l'assistant d'accueil, qui installe l'image sur place — voir Installation et premier lancement.
Contrôle des espaces de travail et des VM
C'est le groupe principal. vm run est délibérément calqué sur Docker : il démarre un espace de travail et confie votre terminal à la session tmux bromure partagée de l'invité.
| Synopsis | Ce qu'elle fait |
|---|---|
bromure-cli vm ls | Liste chaque espace de travail avec son état en direct (off / suspended / booting / running), sa durée de fonctionnement, l'état d'attache de fenêtre, les onglets tmux sous forme d'arborescence (* marque l'onglet actif) et les conteneurs Docker en cours d'exécution. |
bromure-cli vm run [<workspace>] [-v <dir>]… [--name N --tool T --auth A --api-key K] [--memory GB] [-d] [--rm] | Démarre la VM d'un espace de travail, ou en crée un jetable à la volée. Par défaut : attache votre terminal au tmux de l'invité. |
bromure-cli vm attach <vm> [<tab#> | containers:<name> [-- <shell>]] [-w] | Attache le terminal au tmux de la VM (avec saut optionnel vers un onglet), lance docker exec -it dans un conteneur en cours d'exécution (shell par défaut bash), ou ouvre/rattache la fenêtre de l'interface graphique avec -w/--window. |
bromure-cli vm exec <vm> [-i] [-t] [--timeout 600] -- <command…> | Exécute une commande à l'intérieur de la VM (style kubectl, après --). -it ouvre un pty interactif ; omettez la commande avec -it pour obtenir un shell. Les codes de sortie de l'invité se propagent. |
bromure-cli vm kill <vm> [--suspend] | Arrête une VM : arrêt gracieux, ou suspension (RAM sauvegardée sur disque) avec --suspend. |
bromure-cli vm reboot <workspace> [--hard] | Redémarre sur place un espace de travail en cours d'exécution ; gracieux par défaut, --hard le détruit immédiatement. |
bromure-cli vm describe <workspace> | Affiche les paramètres de l'espace de travail ainsi que les détails d'exécution en direct lorsqu'il fonctionne (état, IP, vCPU, état de Fusion, utilisation du disque via le df de l'invité, onglets, conteneurs, mémoire utilisée). |
bromure-cli vm ports <workspace> (ou vm <workspace> -L) | Affiche les ports en écoute d'un espace de travail en cours d'exécution (ss en direct en tant que root) : PORT, PROTO, ADDRESS, PROCESS, avec les liaisons loopback uniquement signalées. |
bromure-cli vm fsck <workspace> [--repair] [--home] | Vérifie le disque système d'un espace de travail arrêté — ou son image home avec --home — depuis le Mac, sans VM ni outil supplémentaire. --repair rejoue le journal du système de fichiers et efface un indicateur d'erreur obsolète. Voir Vérifier un disque en ligne de commande. |
bromure-cli workspaces create [--name N] [--tool T] [--auth A] [--api-key K] [--memory GB] [--color C] [-v <dir>]… [--generate-ssh] [--from-json <file|->] | Crée un espace de travail sans interface. --from-json applique un document JSON de profil complet (les options prennent le pas sur les champs correspondants) ; --generate-ssh génère une clé SSH côté hôte et affiche la clé publique. |
bromure-cli workspaces edit <workspace> [--from-json <file|->] | Récupère la configuration complète de l'espace de travail, l'ouvre dans $VISUAL/$EDITOR (repli sur vi) et enregistre les modifications. Les secrets s'affichent vides — laissez vide pour conserver, saisissez pour remplacer. Supprimer une clé dans l'éditeur efface ce champ. --from-json applique un document de manière non interactive ; il peut être partiel — une clé absente garde sa valeur, un null explicite l'efface. |
bromure-cli workspaces rm <workspace> [-f] | Supprime un espace de travail et TOUTES ses données (disque + home) après une confirmation y/N, ignorée avec -f. |
bromure-cli workspaces ssh-keygen <workspace> | Génère une nouvelle clé SSH côté hôte pour l'espace de travail et affiche la clé publique pour votre hôte Git. |
Quelques détails opérationnels utiles à connaître :
- Options de
vm run.--toolprend un id d'agent :claude,codex,grok,kimiouomp.--authvauttoken,subscription,bedrockoulocal. Une valeur non reconnue est une erreur qui liste les valeurs valides, par exempleInvalid --tool “gpt” — expected one of: claude | codex | grok | kimi | omp.;workspaces createvérifie--toolet--authde la même façon.-v/--volume <hostdir>monte un dossier de l'hôte à~/<basename>dans l'invité (répétable, jusqu'à 8).-d/--detachdémarre la VM et rend la main au lieu de s'attacher.--rmsupprime l'espace de travail et son disque à l'arrêt de la VM. Détachez-vous d'un tmux attaché avecCtrl-b d— la VM continue de tourner. - Les agents viennent de Modèles. Les options d'outil et d'authentification ne font qu'amorcer un nouvel espace de travail. Le modèle et le fournisseur réellement utilisés par chaque agent viennent de Préférences › Modèles et du volet Modèles propre à l'espace de travail — voir Modèles et fournisseurs.
- Sensible au TTY. Le comportement par défaut à la Docker, qui confie le terminal à tmux, ne s'applique que sur un vrai terminal ; les invocations en pipe ou scriptées se comportent comme si vous aviez passé
-d. - Valeurs de
workspaces create. Les couleurs sontblue,red,green,orange,purple,pink,tealougray. - Conservation via champ vide à l'édition.
workspaces editexporte toute la configuration avec les secrets vidés ; un document réenregistré avec un secret vide conserve la valeur stockée, de sorte qu'un aller-retour ne peut jamais effacer vos clés. Un tampon inchangé n'enregistre rien ; un JSON invalide interrompt l'opération. - Attentes de
exec.vm execattend jusqu'à 10 secondes l'agent shell de l'invité ; un502signifie que la VM n'est peut-être pas en cours d'exécution ou que le nom ne correspondait pas. Les invites d'approbation qui se déclenchent pendant une session attachée sont affichées sur votre terminal (voir Consentement sur les terminaux attachés), jamais à l'intérieur de l'invité.
Vérifier un disque en ligne de commande
vm fsck est le jumeau scriptable de Exécuter fsck… dans le navigateur ext4 et du bouton Réparer le disque que l'application affiche lorsqu'un démarrage s'arrête sur des erreurs du système de fichiers. Il utilise le vérificateur ext4 propre à Bromure : rien n'est à installer.
bromure-cli vm kill "Web app" # the workspace must be stopped
bromure-cli vm fsck "Web app" # check the system disk, report only
bromure-cli vm fsck "Web app" --repair # replay the journal, clear the error flag
bromure-cli vm fsck "Web app" --home # check the home image instead
Il refuse de s'exécuter tant que l'espace de travail tourne. La sortie se termine par l'un de ces résumés : « Filesystem is clean. », « Filesystem repaired; it is now consistent. » ou « Filesystem has errors this checker cannot repair. ». Une vérification sans --repair qui trouve des problèmes suggère de relancer avec --repair. La commande se termine avec le code 4 tant que des erreurs subsistent. La portée et les limites du vérificateur sont décrites dans Avancé.
Modèles, routage et Fusion
Les réglages de modèles et de fournisseurs sont traités dans Modèles et fournisseurs et la synthèse multi-modèles dans Fusion ; les commutateurs de la CLI sont :
| Synopsis | Ce qu'elle fait |
|---|---|
bromure-cli model catalog|ls|pull|use|rm … | Gère les modèles MLX sur l'appareil — parcourir le catalogue sélectionné (avec badges d'adéquation à la RAM et d'appel d'outils), télécharger avec progression en direct, définir le modèle actif de l'espace de travail d'une VM en cours d'exécution, supprimer. |
bromure-cli vm fusion enable|disable <vm> | Enclenche ou désenclenche Fusion sur une VM en cours d'exécution. L'espace de travail doit avoir au moins deux modèles configurés. on/engage et off/disengage sont acceptés comme synonymes. |
bromure-cli vm routing cloud|local <vm> | Définit le routage du backend LLM d'une VM en cours d'exécution : les fournisseurs cloud des agents, ou le modèle local. |
Inspection des traces
Celles-ci lisent les traces du proxy par espace de travail. Elles ne renvoient rien tant que le traçage n'est pas activé pour l'espace de travail — voir Réglages de traçage — et le détail complet figure dans Traçage et audit.
| Synopsis | Ce qu'elle fait |
|---|---|
bromure-cli trace ls [workspace] [--limit 50] | Liste les requêtes récentes : TIME / HOST / METHOD / STATUS / REQ / RESP / LAT / FLAGS (les indicateurs incluent swap×N, LEAK×N, conv). |
bromure-cli trace summary [workspace] | Agrège les totaux, les classes de statut, les décomptes de swap/leak/conversation et les principaux hôtes. |
bromure-cli trace hostnames [workspace] | Liste les hôtes distincts et leur nombre de requêtes. |
bromure-cli trace leaks [workspace] | Affiche les requêtes présentant des fuites d'identifiants suspectées (en-tête, aperçu, suspicion). |
bromure-cli trace clear [-f] | Efface l'historique des traces en mémoire et sur disque après une confirmation y/N. |
Accès à distance
La porte d'entrée SSH optionnelle est désactivée par défaut et entièrement documentée dans Accès à distance et clients. Toutes les opérations passent par l'application en cours d'exécution via le socket de contrôle.
| Synopsis | Ce qu'elle fait |
|---|---|
bromure-cli remote [status] | Sous-commande par défaut — affiche l'état activé/en cours d'exécution, la liaison et le port, les méthodes d'authentification, l'empreinte de la clé d'hôte, l'utilisateur de connexion, une ligne de connexion toute prête et les clés autorisées. |
bromure-cli remote enable [--port 2222] [--bind 0.0.0.0] [--[no-]password] [--[no-]pubkey] | Active le serveur SSH. Au moins une méthode d'authentification doit rester active. |
bromure-cli remote disable | Désactive le serveur SSH. |
bromure-cli remote key add <key|path> / key [ls] / key rm <index|fingerprint> | Gère les clés publiques autorisées (ls est la valeur par défaut). |
Inscription en entreprise
Contreparties CLI de la feuille Se connecter à bromure.io…, pour le provisionnement scripté d'appareils. Voir Entreprise.
| Synopsis | Ce qu'elle fait |
|---|---|
bromure-cli enroll --code <6-word-code> [--server-url URL] [--device-name NAME] | Inscrit ce Mac sur un espace de travail bromure.io à l'aide d'un code généré par un administrateur. Le serveur prend par défaut la valeur de $BROMURE_MANAGED_URL ou https://bromure.io/api ; le nom de l'appareil prend par défaut le nom d'hôte du Mac. |
bromure-cli unenroll [--force] | Se déconnecte de l'espace de travail inscrit (y/N sauf avec --force). |
bromure-cli enrollment-status | Affiche l'état d'inscription (espace de travail, utilisateur, id d'installation, appareil, serveur, date d'inscription, présence du bearer/leaf-cert). « not enrolled » sort avec 0 pour que l'automatisation ne le traite pas comme un échec. |
Commandes d'intégration et internes
| Synopsis | Ce qu'elle fait |
|---|---|
bromure-ac mcp [--debug] [--api-url http://127.0.0.1:9223] | Exécute le serveur MCP d'AC sur stdio pour les outils d'IA. Voir Le serveur MCP d'AC. |
__remote-menu, __attach-window, __fatclient…, __forward…, __dial, __tunnel-helper | Points d'entrée internes (l'interface TUI ForceCommand SSH, la pompe d'octets du terminal et les assistants de tunnel du client riche). Non destinés à un usage interactif. |
L'interface TUI distante (__remote-menu)
Lorsque l'accès distant SSH est activé, chaque connexion distante est forcée (via ForceCommand) vers une interface terminal ANSI artisanale plutôt qu'un shell — un menu en écran alternatif, 256 couleurs, piloté par les touches fléchées et les chiffres, qui fonctionne sur n'importe quel PTY SSH (utilisez ssh -t). Elle reflète la CLI sous forme de menus :
- Espaces de travail — création via un formulaire sur un seul écran (Name, Tool, Auth, API key, Memory, Color, Folders, Generate SSH, Full settings…, Create), actions par espace de travail (Attach, New tab, Describe, Configure…, Fusion, Routing, Worktrees…, Reboot…, Suspend, Kill pour les espaces de travail en cours d'exécution ; Start, Describe, Configure…, Delete pour ceux à l'arrêt) et une vue en tableau brut. Configure… propose les volets de l'éditeur de réglages sous forme de formulaires texte ; son formulaire Models est en lecture seule (les fournisseurs du serveur, et si l'espace de travail les remplace), puisque les modèles se choisissent dans l'application.
- Modèles — les modèles installés et le catalogue de téléchargement ; sélectionner un modèle non installé propose de le récupérer via
model pullen ligne avec progression en direct. - Trace — Résumé / Noms d'hôtes / Fuites / Récentes / Effacer.
Pendant que vous êtes attaché au tmux d'un espace de travail, un raccourci magique (par défaut Ctrl-], indiqué dans la bannière) fait apparaître une superposition de contrôle dessinée par l'hôte : une arborescence d'onglets, New tab, Worktrees…, Fusion, Routing, Edit settings…, Reboot…, Suspend, Disconnect. L'invité ne voit jamais la touche de déclenchement — remplacez-la avec le fichier remote/overlay-key ou $BROMURE_OVERLAY_KEY. Ctrl-b d déconnecte de tmux et revient au menu. La TUI distante travaille sur les machines et leurs terminaux ; les sessions d'agent, les salles et le Standard s'atteignent plutôt depuis le client riche. Le récit complet de l'accès distant figure dans Accès à distance et clients.
L'API d'automatisation en loopback
Le plan de contrôle peut aussi être exposé en JSON sur HTTP via TCP, pour le scripting depuis n'importe quel langage. Il est désactivé par défaut.
L'activer
Ouvrez Préférences… › Automatisation (⌘,) — le volet API d'automatisation et serveur MCP.
- Activez Activer le serveur d'automatisation. Lorsqu'il est activé, le volet affiche Écoute sur 127.0.0.1:9223 ; le désactiver arrête le serveur immédiatement.
- Définissez éventuellement le Port (légendé (par défaut : 9223)) et l'Adresse d'écoute (par défaut
127.0.0.1). Le port et l'adresse d'écoute prennent effet au prochain démarrage du serveur — désactivez puis réactivez le commutateur pour les appliquer maintenant.
Vous pouvez aussi actionner le commutateur sans l'interface graphique :
defaults write io.bromure.agentic-coding automation.enabled -bool true
Avertissement : Définir l'Adresse de liaison sur autre chose que
127.0.0.1expose l'API — et le serveur MCP qu'elle soutient — au réseau, et le volet avertit Une liaison non-loopback expose l'API au réseau. Le serveur MCP n'a pas d'authentification. Il n'y a aucune authentification sur l'écouteur TCP au-delà de la frontière loopback et du contrôleBROMURE_DEBUG_CLAUDEci-dessous. Laissez l'adresse de liaison sur loopback à moins d'avoir une raison spécifique et de confiance de ne pas le faire.
Modèle d'authentification
L'écouteur TCP et le socket de contrôle servent les mêmes routes, mais avec des accès différents :
| Groupe de routes | Socket de contrôle | API d'automatisation (loopback TCP) |
|---|---|---|
GET /health, GET /profiles, GET /vms, GET/POST /sessions | Autorisé | Autorisé |
Création et modification d'espaces de travail (POST /profiles, /profiles/<id>…), contrôle des VM et exec (POST /vms, /vms/<id>/…), /trace, /app/state, /preferences, /models/settings, sessions d'agent, salles, délégations, tâches, automatisations, clusters et registres | Autorisé | Nécessite BROMURE_DEBUG_CLAUDE sur l'application |
/state, /state/subscribe, /remote…, /grid-layout, /workspaces, /subscriptions/…, /models/<action>, /connector | Autorisé | Jamais — socket de contrôle uniquement |
Autrement dit : le socket de contrôle est la voie à accès complet, réservée au propriétaire ; l'API TCP ouvre le sous-ensemble sûr sur loopback et place tout le reste derrière l'indicateur de débogage. Les segments de chemin sont encodés une seule fois en pourcentage (pour que les noms d'espaces de travail avec espaces fonctionnent).
Points de terminaison pour le scripting
Les routes les plus utiles :
| Point de terminaison | Rôle |
|---|---|
GET /health | Vivacité, plus debugEnabled. |
GET /state | Instantané de miroir ponctuel : espaces de travail, VM, disposition de la grille, automatisations, pendingPrompts, etc. |
GET /state/subscribe | La forme push de /state : la connexion reste ouverte et un nouvel instantané est diffusé à chaque changement d'état. Les clients riches l'utilisent au lieu d'interroger. |
GET /vms / POST /vms | Liste les VM en cours d'exécution ; démarre une VM à partir d'une référence d'espace de travail ou d'une spécification en ligne avec montages (ce qu'appelle vm run). |
POST /vms/<id>/exec | Exécute une commande dans une VM ; interactive détourne la connexion en un flux pty brut tramé. |
GET /profiles / POST /profiles | Liste les espaces de travail ; en crée un à partir d'un document JSON. |
GET / PUT /preferences | Lit ou remplace le modèle Defaults des Préférences (secrets masqués en lecture, conservés s'ils sont laissés vides en écriture). C'est ce que modifie la fenêtre Préférences d'un client riche sur un hôte distant. |
GET / PUT /models/settings | Lit ou remplace les réglages de modèles globaux (Préférences › Modèles), clés expurgées. |
POST /subscriptions/register / POST /subscriptions/forget | Lance sur cet hôte une connexion à un fournisseur pour un client ({"provider": …, "profileId": …} ; l'URL de connexion revient via /state), ou oublie une connexion enregistrée. |
POST /agent-sessions/start | Démarre une session d'agent (profile, tool, et en option un dossier, un dépôt ou un message d'ouverture). |
POST /agent-sessions/<id>/<action> | Agit sur une session : send, keys, resume, close, rename, nickname, archive, unarchive, delete, review, et les actions de branche (worktree, branch-merge, branch-pr, branch-discard, branch-keep, branch-decline). |
GET /agent-sessions/<id>/transcript, GET /agent-sessions/<id>/pending | La conversation d'une session (JSONL en base64), et ce qu'elle attend (une question et ses options). |
POST /agent-sessions/switchboard | Démarre ou affiche le Standard. |
POST /agent-rooms/create|move|group, POST /agent-rooms/<id>/rename|color|layout|archive|unarchive|ungroup|delete|switchboard | Crée et modifie les salles. |
POST /delegations/request, POST /delegations/<id>/<action>, GET /delegations/<id>/file | Délégation entre hôtes : la session d'un hôte sollicite une session sur un autre, puis envoie, répond, réoriente, clôt ou annule, et récupère les fichiers joints. |
GET / POST /tasks, /tasks/<id>/… | Lit et pilote le tableau des Tâches de code. |
GET / POST /k8s, /k8s/<id>/<action>, POST /registries, /registries/<id>/<action> | Crée et pilote les clusters Kubernetes et registres. |
GET /automations / POST /automations/<id>/run | Lit et pilote les automatisations planifiées (voir Contrôler les automatisations via l'API). |
POST /prompts/<id>/answer | Répond à une invite de cycle de vie en file d'attente (voir Répondre aux invites en attente). |
Comme le chemin du socket de contrôle contient des espaces, capturez-le d'abord dans une variable :
SOCK="$HOME/Library/Application Support/BromureAC/control.sock"
# Full mirror snapshot (control socket only)
curl --unix-socket "$SOCK" http://localhost/state
# List running VMs
curl --unix-socket "$SOCK" http://localhost/vms
# Boot a workspace by name
curl --unix-socket "$SOCK" -X POST http://localhost/vms \
-d '{"profile":"Web app"}'
# Answer a queued lifecycle prompt with one of its offered button labels
curl --unix-socket "$SOCK" -X POST http://localhost/prompts/PROMPT_ID/answer \
-d '{"choice":"Not Now"}'
Le sous-ensemble sûr fonctionne sur l'API TCP une fois que vous l'avez activée — par exemple, lister les espaces de travail et ouvrir la fenêtre d'une machine ne nécessite aucun indicateur de débogage :
curl http://127.0.0.1:9223/profiles
curl -X POST http://127.0.0.1:9223/sessions -d '{"profile":"Web app"}'
Remarque : Les routes du plan de contrôle sont une surface d'intégration partagée avec le client riche, pas une API publique versionnée ; la forme de leurs requêtes et réponses peut changer d'une version à l'autre. Les commandes de la CLI ci-dessus sont le moyen stable de scripter Bromure. Les routes réservées au débogage, les variables d'environnement et les emplacements de fichiers sont répertoriés dans l'Annexe.
Le serveur MCP d'AC (bromure-ac mcp)
bromure-ac mcp exécute un serveur MCP JSON-RPC sur stdio (nom du serveur bromure-ac) qui permet à un outil d'IA sur votre Mac de gérer l'application. Il enveloppe l'API HTTP d'automatisation et AppleScript, alors activez d'abord le serveur d'automatisation — les outils de liste et de fenêtre appellent l'API HTTP à --api-url (par défaut http://127.0.0.1:9223). Il n'est pas disponible sous le nom bromure-cli.
Les outils qu'il expose :
bromure_ac_list_profiles,bromure_ac_list_sessionsbromure_ac_open_session(ouvre la fenêtre d'un espace de travail ; attend jusqu'à 30 secondes),bromure_ac_close_sessionbromure_ac_get_profile,bromure_ac_set_profile(remplacement JSON atomique, id préservé)bromure_ac_get_profile_setting,bromure_ac_set_profile_setting
Avec --debug (et BROMURE_DEBUG_CLAUDE défini sur l'application), il ajoute bromure_ac_app_state, bromure_ac_vm_exec, bromure_ac_vm_read_file et bromure_ac_vm_write_file.
Pour le connecter à Claude Code, ajoutez ce qui suit à ~/.config/claude-code/.mcp.json (ou l'équivalent de votre client). C'est l'extrait exact qu'affiche la section Configuration du client MCP du volet Automatisation :
{
"mcpServers": {
"bromure-ac": {
"command": "/Applications/Bromure Agentic Coding.app/Contents/MacOS/bromure-ac",
"args": ["mcp"]
}
}
}
Remarque : Les outils de profil
get/setappellentosascript(AppleScript contre l'application en cours d'exécution), donc l'application graphique doit être en cours d'exécution et macOS peut demander une fois l'autorisation d'Automatisation. Le JSON de profil circule avec les secrets vidés sauf siBROMURE_DEBUG_CLAUDEest défini.
Les serveurs MCP à l'intérieur des VM
Indépendamment du serveur MCP d'AC, Bromure donne aux agents de chaque VM un ensemble de serveurs MCP intégrés — aucune configuration nécessaire. Chacun est une petite cale Python stdio déposée en lecture seule dans l'invité sous /mnt/bromure-meta/ ; la cale joint l'hôte via vsock et se reconnecte indéfiniment en cas de coupure, si bien que l'agent ne perd jamais ses outils. L'hôte sert les outils, et chaque appel y est vérifié : un agent ne peut voir et toucher que ce à quoi sa propre machine et sa session ont droit.
| Port vsock | Serveur | Qui le reçoit | Outils |
|---|---|---|---|
| 5830 | browser | Chaque agent | Les 23 outils browser_* qui pilotent le Chromium intégré de la machine (voir ci-dessous). |
| 5831 | task board | Uniquement les agents exécutant une tâche de code | board_get_task, board_set_plan, board_create_subtasks, board_set_dependencies, board_ready_for_review, board_report_landing. |
| 5832 | plan stream | Exécutions de planification des tâches de code | Pas un serveur MCP : le canal par lequel l'exécution de planification d'une tâche diffuse son plan vers le tableau. |
| 5833 | automations | Chaque agent | automation_list, automation_get, automation_create, automation_update, automation_delete, automation_run — limité aux automatisations de la propre machine de l'agent. Voir Automatisations. |
| 5834 | infrastructure | Chaque agent | infrastructure_overview, cluster_status, cluster_create, cluster_start, registry_status, registry_create, registry_start — limité aux clusters et registres auxquels la machine a accès. Voir Clusters Kubernetes et registres. |
| 5835 | delegation | Chaque session d'agent | delegate, request, list_peers, list_delegations, read_inbox, wait, ask, report, deliver, answer, steer, close_delegation, cancel, worktree_create, worktree_status, worktree_merge. La cale indique à l'hôte dans quelle fenêtre tmux elle tourne, si bien qu'un agent ne peut pas se faire passer pour une autre session. Voir Des agents qui travaillent ensemble. |
| 5836 | switchboard | Uniquement la session du Standard | list_sessions, read_session, pending_question, list_workspaces, next_events, send_to_session, answer_question, press_keys, start_session, resume_session, message_user, archive_session. |
Les serveurs browser, automations, infrastructure et delegation sont écrits dans la configuration MCP propre à chaque agent, aux côtés des serveurs que vous ajoutez dans le volet MCP de la machine (Réglages MCP). Les serveurs task board et switchboard ne sont transmis qu'aux exécutions qui en ont besoin.
Le serveur browser
Le serveur browser pilote le Chromium intégré de la machine, qui s'exécute dans sa propre VM jetable. Ses 23 outils couvrent la navigation et l'inspection — browser_navigate, browser_new_tab, browser_list_tabs, browser_activate_tab, browser_close_tab, browser_back, browser_forward, browser_reload, browser_screenshot (avec une option pleine page), browser_evaluate, browser_get_text, browser_get_html, browser_get_links, browser_click, browser_fill, browser_type, browser_press_key, browser_wait_for, browser_network, browser_network_summary, browser_clear_network, browser_console et browser_pick_element (un sélecteur d'éléments interactif de 60 secondes).
Un appel d'outil sur un navigateur fermé l'ouvre et attend son démarrage à froid. Comme le navigateur est une VM séparée, les instructions du serveur demandent aux agents d'atteindre un serveur de développement sur leur machine via l'IP LAN de la machine (hostname -I), jamais localhost. Le récit complet figure dans Le navigateur intégré.
Remarque : Sur un client riche, le flux browser-MCP des agents peut transiter par la connexion SSH, de sorte qu'un agent distant pilote le volet de navigateur que vous voyez localement. Voir Accès à distance et clients.
OAuth pour les serveurs MCP que vous ajoutez
Les serveurs MCP HTTP que vous ajoutez dans l'éditeur peuvent s'authentifier via le courtier OAuth côté hôte : il effectue la découverte RFC 8414 et l'enregistrement dynamique de client RFC 7591 (en tant que Bromure AC), exécute un flux de code d'autorisation PKCE dans votre navigateur système et sert le rappel sur un écouteur loopback (ports 28500–28599). La page de succès indique Authorized — You can close this tab and return to Bromure AC. Tout le flux s'exécute sur l'hôte, de sorte que la VM ne voit jamais les véritables identifiants OAuth.
AppleScript (Bromure AC Suite)
Un dictionnaire de scripting, le Bromure AC Suite, est une autre surface d'automatisation — utile pour l'orchestration et pour l'outillage de capture d'écran qui a besoin d'ID de fenêtre. Ciblez application "Bromure Agentic Coding" depuis Script Editor ou osascript. Il couvre :
- Profils —
list profiles,create ac profile <name> [color <c>](renvoie un UUID),delete ac profile <name|uuid>, et aller-retour de document complet viaget profile json/set profile json(le profil entier ; id préservé ; secrets stockés fusionnés sous les champs vides). - Paramètres par champ —
get profile setting … key …/set profile setting … key … to value …. - Fenêtres d'éditeur —
open profile manager,open ac profile editor,close ac profile editor,select editor category <key>, etget editor window id/get main window id(unCGWindowIDpourscreencapture -l). - Fenêtres de machine —
open ac session,close ac session,list ac sessions. - État et paramètres de l'application —
get app state(JSON), plusget ac app setting/set ac app settingpour les clésautomation.enabled,automation.port,automation.bindAddress,remoteAccess.enabled,remoteAccess.port,remoteAccess.bindAddress,managed.serverURLetmanaged.acIngestURL. Définirautomation.enabledactionne le serveur HTTP en direct.
Par exemple, pour ouvrir la fenêtre d'une machine :
osascript -e 'tell application "Bromure Agentic Coding" to open ac session "Web app"'
Remarque : Le JSON de profil circule avec les secrets nettoyés sauf si
BROMURE_DEBUG_CLAUDEest défini. DéfinirapiKeysur une chaîne vide viaset profile settingefface la clé au lieu de la conserver — contrairement au comportement de conservation par champ vide des ponts d'aller-retour JSON. Le changement de langue n'est délibérément pas scriptable ; relancez plutôt l'application avec, par exemple,-AppleLanguages "(fr)".
Automatisations planifiées
Une automatisation planifiée est une exécution d'agent récurrente et sans surveillance liée à une machine. Les automatisations se créent et se gèrent depuis le tableau des automatisations (⇧⌘A, ou la section Automatisations de la barre latérale), et les agents peuvent gérer les automatisations de leur propre machine via le serveur MCP automations ci-dessus. L'ensemble de la fonctionnalité — déclencheurs, planifications, chaînage, l'écran d'injection obligatoire, l'historique des exécutions — est documenté dans Automatisations. Cette section couvre la surface du plan de contrôle : piloter les automatisations via l'API, répondre aux invites de décision que peut soulever un démarrage sans surveillance, et le fonctionnement du consentement sur un terminal attaché.
Contrôler les automatisations via l'API
| Point de terminaison | Objet |
|---|---|
GET /automations | Liste les automatisations et leur historique d'exécution. |
POST /automations | Crée ou met à jour (upsert) une automatisation. |
DELETE /automations/<id> | Supprime une automatisation. |
POST /automations/<id>/run | La déclenche maintenant (ne change pas la planification). |
POST /automations/<id>/toggle | La met en pause ou la reprend. |
POST /automation-runs/<run-id>/acknowledge | Retire une exécution échouée ou bloquée de la colonne Attention requise du tableau. |
GET /automation-runs/<run-id>/transcript | La transcription archivée d'une exécution terminée (base64). |
Répondre aux invites en attente
Certaines décisions de cycle de vie — l'offre de mise à niveau de l'image de base, un disque qui échoue à sa vérification au démarrage, une alerte de compromission, un effacement pour compromission — apparaissent normalement sous forme d'alerte locale. Lorsque personne n'est devant le Mac pour y répondre (un agent sans interface, ou un lancement demandé par un client riche distant), elles sont mises en file d'attente : elles apparaissent dans GET /state sous pendingPrompts (chacune avec un id, un profileID, un title, un message et des libellés de boutons) et on y répond avec POST /prompts/<id>/answer :
SOCK="$HOME/Library/Application Support/BromureAC/control.sock"
curl --unix-socket "$SOCK" -X POST http://localhost/prompts/PROMPT_ID/answer \
-d '{"choice":"Remind me later"}'
Passez l'un des propres libellés de bouton de l'invite comme choice. Si aucun client ne répond avant l'expiration de l'invite, elle se résout vers son repli sûr — jamais l'option destructrice (une alerte de compromission, par exemple, se replie sur l'arrêt de la VM). Si aucun client n'est connecté, elle se replie immédiatement. Un client riche affiche ces invites comme des alertes ordinaires.
Remarque : Les automatisations, les délégations et les autres démarrages sans surveillance n'attendent jamais une invite. Un démarrage qui nécessiterait votre réponse — une machine marquée comme compromise, ou un modèle local encore en téléchargement — est refusé, avec une raison claire dans l'historique de l'exécution (« The workspace is marked compromised — start it yourself to confirm the wipe. »). Une machine suspendue dont l'état enregistré ne peut pas être restauré démarre à neuf.
Consentement sur les terminaux attachés
Pendant qu'un terminal est attaché de manière interactive à une machine — via vm exec -it, vm attach ou une attache SSH — les invites d'approbation côté hôte (utilisation d'identifiants, et similaires) s'affichent sur votre terminal, pas à l'intérieur de l'invité. L'invite indique 🔒 Bromure — approval required avec des choix numérotés et Choice [1-N] (Enter or timeout = deny). Entrée, expiration, EOF ou détachement signifient tous refus, de sorte qu'un invité compromis ne peut jamais falsifier une approbation. Le tmux de l'invité est ensuite redessiné.
Points de terminaison de débogage (BROMURE_DEBUG_CLAUDE)
Lancer l'application avec BROMURE_DEBUG_CLAUDE défini lève la barrière de débogage sur l'API d'automatisation TCP, de sorte que les routes de la ligne du milieu du tableau d'authentification fonctionnent aussi sur TCP, y compris ces routes de débogage (toujours disponibles sur le socket de contrôle, sauf indication contraire) :
GET /debug/ui-shot?path=…&which=…— l'application rend sa propre fenêtre en PNG (aucune autorisation d'Enregistrement de l'écran nécessaire) et renvoie un vidage des cadres de sous-vues ; la sortie par défaut est/tmp/bromure-ui-shot.png.POST /debug/editor— pilote l'éditeur de paramètres pour l'outil de capture d'écran.POST /detect/prompt-injection— exécute les véritables détecteurs et renvoie leur verdict (cette route nécessite l'indicateur de débogage même sur le socket de contrôle).
L'indicateur permet également aux secrets de circuler tels quels à travers les ponts JSON de profil d'AppleScript et de MCP, et il est requis par les outils de VM de bromure-ac mcp --debug. GET /health signale debugEnabled pour que vous sachiez dans quel mode se trouve l'application.
Avertissement :
BROMURE_DEBUG_CLAUDEsupprime la barrière de sécurité qui maintient normalementexec, le contrôle des VM et les secrets bruts de profil hors de l'API TCP loopback. N'exécutez l'application avec cet indicateur que sur une machine que vous contrôlez, et ne le combinez jamais avec une adresse d'écoute non loopback — cela exposerait un accès shell complet aux VM, des secrets non expurgés et des captures de fenêtre à quiconque peut atteindre le port. Il est distinct deBROMURE_AC_DEBUG(journalisation d'événements sur stderr) et deBROMURE_CLI_DEBUG(diagnostics de socket de la CLI), qui sont des commutateurs de journalisation inoffensifs.