Concepts et architecture

Bromure Agentic Coding exécute des agents de codage IA à l'intérieur d'une machine Linux virtualisée matériellement sur votre propre Mac, et applique chaque contrôle de sécurité en un point unique que l'agent ne peut pas contourner. Ce chapitre définit le vocabulaire sur lequel repose le reste du manuel — hôte et invité, espace de travail et session, la frontière du fil, le stockage persistant et éphémère — et explique comment les pièces s'assemblent. Si vous ne lisez qu'un seul chapitre au-delà du Démarrage rapide, lisez celui-ci.

L'hôte et l'invité

Tout dans Bromure Agentic Coding se trouve d'un côté d'une ligne infranchissable :

• L'hôte est votre Mac — macOS 14 ou ultérieur sur Apple Silicon — et le processus Bromure Agentic Coding qui y est exécuté. L'hôte possède tout ce qui est sensible : vos véritables identifiants (chiffrés avec une clé maîtresse dans le Trousseau macOS), le proxy MITM qui parle à Internet au nom de l'agent, la clé privée de l'autorité de certification racine Bromure, le magasin de traces, ainsi que les fenêtres, terminaux et tableaux de bord de l'application. Le terminal dans lequel vous tapez est rendu sur l'hôte, et non à l'intérieur de la VM.
• L'invité est la machine virtuelle Linux où l'agent s'exécute réellement — Claude Code, Codex CLI, Grok CLI ou de simples outils shell, ainsi que tout ce qu'ils installent et manipulent : dépôts clonés, caches de paquets, conteneurs Docker, environnements virtuels. L'invité est traité comme non fiable par construction. Il ne détient aucun véritable secret, seulement des identifiants factices intentionnellement invalides, et son trafic HTTPS sortant est canalisé à travers le proxy de l'hôte.

Les deux côtés communiquent par deux canaux étroits : vsock (sockets virtio, un transport hôte-vers-invité qui ne nécessite aucun réseau) pour le contrôle, les terminaux et le chemin du proxy, et un réseau virtuel privé (NAT vmnet) pour le trafic IP ordinaire. Les deux sont décrits en détail ci-dessous.

Cette séparation est ce qui rend concrète l'affirmation de sécurité du produit : un agent victime d'une injection de prompt ou se comportant mal de toute autre manière peut faire tout ce qu'il veut à l'intérieur de l'invité, mais il ne peut pas lire une véritable clé d'API, signer avec un véritable secret AWS, ni extraire une clé privée SSH — aucun de ces éléments n'existe de son côté de la ligne.

L'architecture en un coup d'œil

Lisez le schéma de bas en haut : l'agent travaille dans la VM d'espace de travail ; son trafic HTTPS sort via vsock vers le proxy de l'hôte, qui est le seul endroit où les identifiants factices deviennent réels ; la fenêtre de session se rattache aux terminaux de la VM via des ponts vsock distincts ; et une VM de navigateur jetable optionnelle partage le même réseau privé afin de pouvoir charger les serveurs de développement de l'agent.

Espace de travail, session et VM

Trois mots portent des significations précises et distinctes tout au long de ce manuel :

• Un espace de travail est une configuration enregistrée et son stockage durable. Il définit quel agent s'exécute (et comment il s'authentifie), les identifiants, les dossiers partagés, l'environnement, les serveurs MCP, les garde-fous, l'apparence et le dimensionnement de la VM — tout ce que vous modifiez dans la fenêtre Modifier l'espace de travail — et il possède un répertoire sous ~/Library/Application Support/BromureAC/profiles/<uuid>/ contenant son disque système, son image de home, ses clés SSH, ses points de contrôle et son état enregistré. Un espace de travail existe qu'un élément soit en cours d'exécution ou non. En interne (dans des noms de fichiers tels que profile.json et dans les indicateurs CLI), un espace de travail est appelé profil ; les deux termes sont interchangeables. La pratique courante consiste à avoir un espace de travail par projet ou par frontière d'identifiants. Voir Espaces de travail.
• La VM (machine virtuelle) est l'instance Linux en cours d'exécution amorcée à partir du stockage d'un espace de travail. Chaque espace de travail correspond à exactement une VM — un invité Ubuntu avec ses propres disques, son adresse MAC déterministe, son adresse IP et son écouteur de proxy MITM propre à l'espace de travail. Deux espaces de travail ne partagent jamais une VM, et un espace de travail n'en a jamais deux.
• Une session est une exécution continue de la VM d'un espace de travail : elle commence lorsque vous démarrez (ou reprenez) l'espace de travail et se termine lorsque la VM s'arrête ou se suspend. La fenêtre de session peut se détacher d'une session sans la terminer — l'action de fermeture Exécuter en arrière-plan laisse la VM s'exécuter sans interface, et vous pouvez vous y rattacher depuis la barre latérale plus tard. Certains états sont délibérément limités à la session : les octrois et refus d'approbation d'identifiants ne vivent qu'en mémoire et sont révoqués au démantèlement de la session, et les partages de métadonnées par lancement sont reconstruits à chaque démarrage. Voir Sessions.

Un raccourci utile : l'espace de travail est le nom (il persiste sur le disque), la VM est la machine (elle existe tant qu'elle est allumée ou suspendue), et la session est l'exécution (elle a un début et une fin).

La VM d'espace de travail

Chaque VM d'espace de travail est un invité Ubuntu 24.04 s'exécutant sous Virtualization.framework d'Apple — la même technologie d'hyperviseur que macOS lui-même fournit, nécessitant Apple Silicon et ne prenant en charge que les invités ARM64. La VM démarre avec 4 vCPU fixes et la quantité de RAM définie dans l'espace de travail (dimensionnée selon votre Mac par défaut : 4, 6 ou 8 Go), à partir de deux disques virtuels :

• disk.img — le disque système. Au premier lancement de l'espace de travail, il est créé sous la forme d'un clone copie-sur-écriture APFS de l'image de base Ubuntu partagée et signée (voir Installation) : le clone apparaît instantanément et ne consomme aucun nouvel espace disque tant que l'invité n'y écrit pas. Les lancements ultérieurs réutilisent le même clone, de sorte que les paquets que vous installez avec apt install, les images Docker que vous récupérez et toute autre modification au niveau système survivent d'une session à l'autre.
• home.img — une image ext4 clairsemée privée contenant /home/ubuntu, attachée comme second périphérique virtio-blk. Elle a une taille apparente de 64 GiB par défaut mais est allouée paresseusement, et elle se réduit sur l'hôte à mesure que des fichiers sont supprimés dans l'invité. Le home survit même à une Réinitialisation du disque, ce qui explique pourquoi vos dépôts, dotfiles et historique de shell survivent à une réinitialisation du disque système. (Les anciens espaces de travail peuvent encore utiliser un home hérité basé sur un dossier partagé ; l'application propose une mise à niveau ponctuelle — voir Espaces de travail.)

L'invité monte également de petits partages virtiofs par lancement : un partage meta en lecture seule portant la configuration de ce démarrage (fichiers d'environnement de jetons factices, paramètres du proxy, certificat de l'autorité de certification Bromure, agents invités, configurations MCP) et une boîte d'envoi accessible en écriture que l'invité utilise pour publier des événements vers l'hôte (son adresse IP, la liste des onglets tmux, l'état de l'agent). Les deux sont reconstruits à chaque démarrage et ne portent aucun état durable. Jusqu'à 8 dossiers de projet de l'hôte peuvent en outre être partagés dans l'invité, liés symboliquement dans le répertoire home.

Persistant par conception — le contraste avec Bromure (Web)

Bromure Agentic Coding est livré à partir de la même base de code que son application sœur, Bromure — la variante navigateur web — et les deux font des choix de cycle de vie opposés à dessein :

Le travail de codage a besoin d'un état durable — dépôts clonés, caches de paquets, environnements virtuels, historique de shell — de sorte que détruire la VM après chaque session rendrait les agents inutiles. Au lieu de contrôler l'état de la VM, Bromure Agentic Coding contrôle ce que la VM est autorisée à détenir : aucun véritable secret, et aucun chemin non médiatisé vers Internet. L'éphémérité existe toujours comme échappatoire plutôt que par défaut : Réinitialiser le disque re-clone le disque système à partir de l'image de base, les points de contrôle de disque et de home permettent le retour arrière, bromure-cli vm run --rm crée des espaces de travail jetables de style docker supprimés à l'arrêt de la VM, et le flux de compromission efface un disque et un home contaminés tout en préservant vos paramètres et vos clés.

La VM annexe de navigateur

Une partie de Bromure (Web) survit à l'intérieur de Bromure Agentic Coding : le volet de navigateur agentique. Lorsque vous (ou l'agent) l'ouvrez, l'espace de travail obtient une seconde VM éphémère — un invité Alpine + Chromium cloné dans le répertoire temporaire et supprimé lorsque le volet est démantelé. Cette VM annexe est l'exception qui confirme la règle : l'état de navigation est jetable par défaut (sauf si l'espace de travail active Rester connecté aux sites web, ce qui conserve le profil de Chromium sur un disque chiffré propre à l'espace de travail), tandis que la VM d'espace de travail à côté est durable. Les deux VM se trouvent sur le même segment de réseau privé, de sorte que le navigateur peut charger un serveur de développement que l'agent vient de démarrer via l'adresse IP de la VM.

Cycle de vie de la VM : Arrêté, Suspendu et En cours d'exécution

Chaque espace de travail est toujours dans exactement l'un de trois états durables, affiché sous forme de pastille à côté du nom de l'espace de travail dans la barre latérale et sur le tableau de bord des VM. (Vous verrez également brièvement des états transitoires — Démarrage… dans la barre latérale et une indication d'amorçage sur le tableau de bord — pendant qu'une VM démarre.)

Sélectionner le nom d'un espace de travail affiche son tableau de bord pour tout état : les cartes en direct de CPU, mémoire, vCPU, disque et durée de fonctionnement pendant l'exécution, ou le résumé des spécifications et de la configuration de la machine lorsqu'elle est arrêtée ou suspendue — la capture d'écran ci-dessus montre un espace de travail qui n'a jamais été lancé, ce qui explique pourquoi la carte Disque affiche toujours 0 MB (aucun clone n'existe encore). Le bouton dans le coin supérieur droit est Démarrer pour un espace de travail arrêté et Reprendre pour un espace suspendu.

Quelques règles de cycle de vie qu'il vaut la peine d'intérioriser :

• La suspension est un instantané de RAM, pas un fichier de sauvegarde. Le restaurer nécessite que la configuration de la VM soit identique, ce qui explique pourquoi chaque espace de travail conserve un identifiant de machine et une adresse MAC déterministe. Si vous modifiez l'ensemble des dossiers partagés alors qu'un instantané existe, l'application demande à écarter l'état suspendu — le lancement suivant démarre à froid, et aucun fichier n'est affecté.
• Un instantané ne survit jamais à son disque. Réinitialiser ou effacer le disque système supprime aussi tout instantané de RAM enregistré et l'état des onglets, car un disque neuf associé à une RAM obsolète corromprait instantanément.
• Arrêté ne signifie pas effacé. Un espace de travail arrêté conserve son disque système et son home indéfiniment. La destruction réelle des données est toujours explicite (Réinitialiser le disque, Effacer le home, Supprimer l'espace de travail) ou forcée par le flux de compromission.

Actions de fermeture

Ce qui se produit lorsque vous fermez une session est un choix par espace de travail (À la fermeture de la fenêtre dans l'éditeur d'espace de travail) : Exécuter en arrière-plan (détacher la fenêtre, maintenir la VM en cours d'exécution), Suspendre, Éteindre ou Demander — l'option par défaut, qui propose à chaque fois les trois options. La fermeture du dernier onglet de terminal passe par le même choix. Voir Sessions pour le flux complet.

La frontière du fil

La frontière du fil est l'idée centrale du produit : tout le trafic HTTPS sortant de l'invité passe à travers un proxy man-in-the-middle (MITM) côté hôte, et chaque protection — conservation des secrets, cadrage des identifiants, analyse de la chaîne d'approvisionnement, détection d'injection de prompt, traçage — est appliquée en ce point unique. L'agent ne peut pas le contourner, car il n'y a rien d'utile de son côté de la ligne.

Le flux, de bout en bout :

1. L'invité ne détient que des factices. Au lancement de la session, l'hôte écrit dans la VM des identifiants d'espace réservé intentionnellement invalides — des variables d'environnement telles que ANTHROPIC_API_KEY, et des fichiers de configuration tels que ~/.git-credentials, ~/.docker/config.json et ~/.kube/config. Les factices préservent la structure (sk-ant-api03-brm-…, en forme de ghp_…, brm_…) de sorte que les validateurs côté client les acceptent, et sont déterministes par installation, de sorte que les outils ne voient jamais une clé « pivoter » entre les sessions. Les véritables valeurs correspondantes sont chargées dans la table d'échange en mémoire du proxy sur l'hôte, chacune associée à l'hôte de destination auquel elle appartient.
2. Le TLS de l'invité se termine au proxy. Chaque shell de l'invité exporte HTTPS_PROXY=http://127.0.0.1:8080, un point de terminaison intra-VM qui tunnelise via vsock (port 8443) vers le proxy de l'hôte. Le proxy présente un certificat feuille falsifié propre à l'hôte, signé par l'autorité de certification racine Bromure, inspecte la requête et la re-chiffre vers le véritable serveur amont.
3. Les factices ne deviennent réels qu'à la sortie. Le proxy échange chaque factice contre sa véritable valeur — échanges d'en-tête pour les clés d'API et les jetons, échanges de corps pour les flux de rafraîchissement OAuth, re-signature complète SigV4 pour AWS (l'invité signe avec un secret factice ; l'hôte retire cette signature et re-signe avec la véritable), signature ssh-agent via vsock pour SSH. Les échanges sont cadrés exact-ou-sous-domaine vers l'hôte enregistré, jamais par sous-chaîne, de sorte qu'un identifiant enregistré pour api.anthropic.com n'est jamais injecté vers un domaine ressemblant.

L'autorité de certification racine Bromure

Le proxy ne peut terminer le TLS de l'invité que parce que l'invité lui fait confiance pour cela. Au premier lancement, l'application génère une autorité de certification propre à l'installation — la Bromure Agentic Coding Root CA — dont le certificat public est monté dans le magasin de confiance de chaque VM au démarrage via le partage meta. La clé privée ne quitte jamais l'hôte (elle réside sous ~/Library/Application Support/BromureAC/ca/, lisible par le propriétaire uniquement). Rien en dehors de vos VM Bromure ne fait confiance à cette autorité de certification : elle ne peut pas être utilisée pour intercepter le propre trafic de votre Mac, et supprimer le répertoire ca/ génère simplement une nouvelle autorité de certification au lancement suivant.

À défaillance sûre par construction

La conception est à défaillance sûre : si le trafic de l'invité échappe un jour au proxy — un outil qui ignore les variables de proxy, un socket brut, une tentative de contournement délibérée — le seul identifiant qu'il peut présenter est un factice qu'aucun serveur amont n'accepte. AWS renvoie InvalidSignatureException ; les fournisseurs d'API rejettent la clé d'espace réservé. Contourner la frontière n'apporte rien à un attaquant, car la frontière n'est pas l'endroit où les secrets sont vérifiés — c'est le seul endroit où les secrets existent.

Le détecteur de compromission

La frontière surveille aussi la direction opposée de l'abus : l'exfiltration. Le proxy analyse chaque requête sortante à la recherche de l'un des jetons factices enregistrés de l'espace de travail. Un factice a exactement une destination légitime — l'hôte pour lequel il a été frappé — de sorte qu'un factice observé se dirigeant ailleurs est la signature d'un agent tentant de divulguer des identifiants. Le proxy refuse la requête sans transmettre un seul octet, met la VM en pause et vous alerte ; l'espace de travail est marqué comme compromis et refuse de redémarrer tant que son disque et son home (présumés contaminés) ne sont pas effacés. Vos paramètres, jetons et clés SSH sont conservés — et comme seul le factice a fui, le véritable identifiant n'a jamais besoin d'être renouvelé. Le modèle complet des identifiants, y compris les invites d'approbation par identifiant et les octrois limités par TTL, est traité dans Identifiants et frontière du fil.

Ce qui persiste et ce qui ne persiste pas

Bromure Agentic Coding est explicite quant à la durée de vie. Tout ce qu'un espace de travail possède réside sous ~/Library/Application Support/BromureAC/profiles/<uuid>/ ; le tableau ci-dessous est la carte définitive de ce qui survit à quoi.

Persistant — survit à l'arrêt et aux redémarrages de l'application :

Éphémère — reconstruit ou détruit automatiquement :

Deux conséquences découlent de cette carte. Premièrement, « fermer la fenêtre » n'est jamais destructeur en soi — les verbes destructeurs sont tous explicites et confirmés. Deuxièmement, lorsque vous voulez la disposabilité, vous disposez d'options graduées : revenir à un point de contrôle, Réinitialiser le disque (le home survit), Effacer le home, supprimer l'espace de travail, ou commencer d'emblée avec un espace jetable via bromure-cli vm run --rm.

Remarque : Les dossiers partagés de l'hôte sont des répertoires de projet sur votre Mac, en dehors du stockage de Bromure. Ils ne sont jamais effacés par aucune action de Bromure — y compris l'effacement de compromission — et l'invite d'effacement le dit explicitement.

Ponts hôte–invité (vsock)

L'intégration interactive entre le Mac et l'invité passe par les sockets virtio — des canaux point à point hôte-vers-invité qui existent indépendamment du réseau de la VM. Vous ne les configurez jamais, mais savoir qu'ils existent aide à la lecture des traces ou du chapitre Dépannage. Chaque pont écoute sur un port vsock numéroté :

Ponts de la VM d'espace de travail :

Ponts de la VM annexe de navigateur : configuration (5000), transfert de fichiers (5100), Chrome DevTools Protocol (5200), relais de liens (5300), webcam (5400), bande d'onglets native (5810) et trace réseau (5900).

Presse-papiers

Il n'y a pas de démon de presse-papiers distinct pour les terminaux d'espace de travail — le presse-papiers passe par le protocole de terminal lui-même. Copier à l'intérieur de l'invité (une sélection tmux, ou tout programme émettant OSC 52) atterrit automatiquement sur le presse-papiers de macOS ; ⌘C copie la sélection du terminal côté hôte ; ⌘V colle dans l'invité en utilisant le collage entre crochets. Dans le volet de navigateur, un agent de presse-papiers invité plus la capture de ⌘C/⌘V assurent le copier-coller entre le Mac et Chromium.

Transfert de fichiers

Les fichiers se déplacent entre le Mac et un espace de travail de trois façons, toutes traitées dans Sessions : les dossiers partagés (virtiofs, le chemin normal pour les fichiers de projet), la fenêtre du navigateur de fichiers à la manière du Finder (glisser à l'intérieur et à l'extérieur via le service de fichiers vsock sur le port 5800), et le collage d'image (⌘V avec une image la téléverse dans l'invité et en colle le chemin). Le protocole de transfert de fichiers dédié sur le port 5100 appartient à la VM annexe de navigateur.

Réseau

Mode NAT (par défaut)

Toutes les VM d'espace de travail en mode NAT s'attachent à un unique commutateur L2 logiciel à l'échelle du processus, multiplexé sur une interface partagée/NAT vmnet. Les conséquences :

• Un sous-réseau privé — 192.168.64.0/24 par défaut (passerelle .1, adresses louées de .2 à .254 pendant 24 heures). Si le propre réseau local de votre Mac utilise déjà cette plage, Bromure choisit automatiquement un autre 192.168.x.0/24.
• Bromure exécute son propre serveur DHCP sur ce commutateur (celui intégré à Apple ne peut suivre qu'un seul bail par interface), et les baux persistent dans dhcp-leases.sqlite sur l'hôte.
• Adressage stable — chaque espace de travail obtient une adresse MAC déterministe administrée localement, persistée dans profile-macs.json, et combinée à des baux persistants, un espace de travail conserve généralement la même IP d'un redémarrage de l'application à l'autre (au mieux : tant que l'adresse reste libre). L'IP actuelle est toujours affichée dans l'en-tête du tableau de bord des VM et dans la pastille de la barre d'outils.
• Les VM peuvent se joindre entre elles. Chaque VM en mode NAT — VM d'espace de travail et VM annexes de navigateur — se trouve sur le même segment L2 par conception, de sorte que le volet de navigateur peut charger un serveur de développement s'exécutant dans la VM d'espace de travail, et deux espaces de travail peuvent dialoguer avec les services l'un de l'autre. La carte Ports en écoute du tableau de bord répertorie chaque socket invité accessible de l'extérieur sous la forme du point de terminaison <VM-IP>:<port> auquel vous vous connecteriez réellement depuis le Mac.
• Isolation de l'extérieur. Le NAT signifie que les VM sont accessibles depuis votre Mac mais ne sont pas exposées sur votre réseau local physique, et les connexions entrantes provenant d'ailleurs ne sont pas possibles sauf si vous publiez explicitement un service (tunnels rapides Cloudflare par service, depuis la carte Ports en écoute).

La MTU de la carte réseau de l'invité est plafonnée à 1280 par défaut — une valeur prudente qui survit aux environnements VPN et d'entreprise avec découverte de MTU de chemin — et peut être augmentée avec defaults write io.bromure.agentic-coding vm.mtu -int <value>.

Rappelez-vous que le trafic IP ordinaire sur ce réseau n'est pas la manière dont circulent les identifiants : le trafic HTTPS de l'invité est dirigé à travers le point de terminaison du proxy intra-VM et via vsock vers la frontière du fil. Le réseau NAT transporte tout le reste — et tout ce qui contourne le proxy ne transporte que des identifiants factices, ce qui est exactement la propriété à défaillance sûre décrite ci-dessus.

Mode ponté (par espace de travail)

Un espace de travail peut plutôt rejoindre votre réseau local physique : le mode ponté attache la VM à une interface hôte choisie via le pontage vmnet, la faisant apparaître comme un périphérique sur le réseau local (utile lorsque d'autres machines doivent joindre directement la VM). Si l'interface choisie est indisponible au lancement, la VM revient au NAT. Le mode réseau est défini par espace de travail dans l'éditeur d'espace de travail ; voir Espaces de travail.

Démarrage instantané et préchauffage

Deux mécanismes différents donnent aux sessions une sensation d'instantanéité, et il vaut la peine de savoir lequel s'applique où :

• Les VM d'espace de travail ne sont pas mises en pool. Chaque espace de travail démarre directement sa propre VM persistante. Le premier lancement est rapide parce que le disque système est un clone CoW instantané plutôt qu'une image copiée ; les démarrages à froid ultérieurs sont des démarrages Linux ordinaires (couverts par la superposition de démarrage animée) ; et un espace de travail Suspendu saute entièrement le démarrage — son instantané de RAM est restauré et la session reprend sur place, terminaux compris, presque instantanément.
• La VM annexe de navigateur utilise un pool chaud. Le moteur maintient une VM de navigateur pré-démarrée prête en arrière-plan, de sorte que l'ouverture du volet de navigateur agentique prend moins d'une seconde. Lorsque cette VM est réclamée, un remplaçant commence à chauffer ; pendant qu'elle est inactive, le ballon de mémoire de la VM chaude est gonflé (l'invité conserve environ 512 Mo) et la VM est suspendue après 30 secondes pour rester économique, puis reprise et le ballon dégonflé (mémoire complète restaurée à l'invité) au moment de la réclamation.

La distinction découle directement de la philosophie du cycle de vie : les VM mises en pool n'ont de sens que lorsque chaque instance est interchangeable, ce qui est vrai des VM de navigateur jetables et faux des machines persistantes propres à chaque espace de travail.