Conceptos y arquitectura

Bromure Agentic Coding ejecuta agentes de codificación con IA dentro de una máquina Linux virtualizada por hardware en tu propio Mac, y aplica todos los controles de seguridad en un único punto que el agente no puede eludir. Este capítulo define el vocabulario en el que se apoya el resto del manual — anfitrión e invitado, espacio de trabajo y sesión, el límite de red, almacenamiento persistente y efímero — y explica cómo encajan las piezas. Si solo lees un capítulo más allá del Inicio rápido, lee este.

El anfitrión y el invitado

Todo en Bromure Agentic Coding vive a un lado de una línea infranqueable:

• El anfitrión es tu Mac — macOS 14 o posterior en Apple Silicon — y el proceso de Bromure Agentic Coding que se ejecuta en él. El anfitrión posee todo lo sensible: tus credenciales reales (cifradas con una clave maestra en el Llavero de macOS), el proxy MITM que se comunica con internet en nombre del agente, la clave privada de la CA raíz de Bromure, el almacén de trazas y las ventanas, terminales y paneles de control de la app. El terminal en el que escribes se renderiza en el anfitrión, no dentro de la VM.
• El invitado es la máquina virtual Linux donde el agente se ejecuta realmente — Claude Code, Codex CLI, Grok CLI o herramientas de shell básicas, junto con todo lo que instalan y tocan: repositorios clonados, cachés de paquetes, contenedores Docker, entornos virtuales. El invitado se considera no confiable por construcción. No contiene secretos reales, solo credenciales falsas intencionadamente inválidas, y su HTTPS saliente se canaliza a través del proxy del anfitrión.

Ambos lados se comunican por dos canales estrechos: vsock (sockets virtio, un transporte de anfitrión a invitado que no necesita red alguna) para control, terminales y la ruta del proxy, y una red virtual privada (NAT vmnet) para el tráfico IP ordinario. Ambos se describen en detalle a continuación.

Esta separación es lo que hace concreta la afirmación de seguridad del producto: un agente con inyección de prompts o que se comporte de forma anómala puede hacer lo que quiera dentro del invitado, pero no puede leer una clave de API real, firmar con un secreto real de AWS ni extraer una clave privada SSH — ninguno de esos existe en su lado de la línea.

La arquitectura de un vistazo

Lee el diagrama de abajo arriba: el agente trabaja en la VM del espacio de trabajo; su HTTPS sale por vsock hacia el proxy del anfitrión, que es el único lugar donde las credenciales falsas se convierten en reales; la ventana de sesión se conecta a los terminales de la VM mediante puentes vsock independientes; y una VM opcional y desechable del navegador comparte la misma red privada para poder cargar los servidores de desarrollo del agente.

Espacio de trabajo, sesión y VM

Tres palabras tienen significados precisos y distintos a lo largo de este manual:

• Un espacio de trabajo es una configuración guardada junto con su almacenamiento duradero. Define qué agente se ejecuta (y cómo se autentica), las credenciales, las carpetas compartidas, el entorno, los servidores MCP, las salvaguardas, la apariencia y el dimensionamiento de la VM — todo lo que editas en la ventana Editar espacio de trabajo — y posee un directorio bajo ~/Library/Application Support/BromureAC/profiles/<uuid>/ que contiene su disco de sistema, imagen del home, claves SSH, puntos de control y estado guardado. Un espacio de trabajo existe esté o no ejecutándose algo. Internamente (en nombres de archivo como profile.json y en las opciones de la CLI) un espacio de trabajo se denomina perfil; ambos términos son intercambiables. La práctica habitual es un espacio de trabajo por proyecto o por límite de credenciales. Consulta Espacios de trabajo.
• La VM (máquina virtual) es la instancia Linux en ejecución arrancada desde el almacenamiento de un espacio de trabajo. Cada espacio de trabajo se corresponde con exactamente una VM — un invitado Ubuntu con sus propios discos, dirección MAC determinista, dirección IP y escucha del proxy MITM por espacio de trabajo. Dos espacios de trabajo nunca comparten una VM, y un espacio de trabajo nunca tiene dos.
• Una sesión es una ejecución continua de la VM de un espacio de trabajo: comienza cuando inicias (o reanudas) el espacio de trabajo y termina cuando la VM se apaga o se suspende. La ventana de sesión puede desconectarse de una sesión sin finalizarla — la acción de cierre Ejecutar en segundo plano deja la VM ejecutándose sin interfaz, y puedes volver a conectarte más tarde desde la barra lateral. Parte del estado tiene ámbito de sesión de forma deliberada: las concesiones y denegaciones de aprobación de credenciales viven solo en memoria y se revocan al desmontar la sesión, y las particiones compartidas de metadatos por lanzamiento se reconstruyen en cada arranque. Consulta Sesiones.

Un atajo útil: el espacio de trabajo es el sustantivo (persiste en disco), la VM es la máquina (existe mientras está encendida o suspendida) y la sesión es la ejecución (tiene un principio y un fin).

La VM del espacio de trabajo

Cada VM de espacio de trabajo es un invitado Ubuntu 24.04 que se ejecuta bajo Virtualization.framework de Apple — la misma tecnología de hipervisor que proporciona el propio macOS, que requiere Apple Silicon y admite únicamente invitados ARM64. La VM arranca con 4 vCPUs fijas y la cantidad de RAM establecida en el espacio de trabajo (dimensionada a tu Mac por defecto: 4, 6 u 8 GB), desde dos discos virtuales:

• disk.img — el disco de sistema. En el primer lanzamiento del espacio de trabajo se crea como un clon copy-on-write de APFS de la imagen base de Ubuntu compartida y firmada (consulta Instalación): el clon aparece al instante y no consume espacio en disco nuevo hasta que el invitado escribe en él. Los lanzamientos posteriores reutilizan el mismo clon, de modo que los paquetes que instalas con apt install, las imágenes de Docker que descargas y cualquier otro cambio a nivel de sistema sobreviven entre sesiones.
• home.img — una imagen ext4 dispersa y privada que contiene /home/ubuntu, adjuntada como un segundo dispositivo virtio-blk. Tiene un tamaño aparente de 64 GiB por defecto pero se asigna de forma diferida, y se reduce en el anfitrión a medida que se eliminan archivos en el invitado. El home sobrevive incluso a un Restablecer disco, razón por la cual tus repositorios, dotfiles e historial de shell perduran más allá de un restablecimiento del disco de sistema. (Los espacios de trabajo más antiguos pueden seguir usando un home heredado basado en carpeta compartida; la app ofrece una actualización única — consulta Espacios de trabajo).

El invitado también monta pequeñas particiones virtiofs por lanzamiento: una partición meta de solo lectura que transporta la configuración de ese arranque (archivos de entorno con tokens falsos, ajustes del proxy, el certificado de la CA de Bromure, agentes del invitado, configuraciones de MCP) y una bandeja de salida con permiso de escritura que el invitado usa para publicar eventos de vuelta al anfitrión (su dirección IP, el listado de pestañas de tmux, el estado del agente). Ambas se reconstruyen en cada arranque y no contienen estado duradero. Además, se pueden compartir hasta 8 carpetas de proyecto del anfitrión con el invitado, enlazadas simbólicamente en el directorio home.

Persistente por diseño — el contraste con Bromure (Web)

Bromure Agentic Coding se distribuye desde la misma base de código que su app hermana, Bromure — la variante de navegador web — y ambas toman decisiones de ciclo de vida opuestas a propósito:

El trabajo de codificación necesita estado duradero — repos clonados, cachés de paquetes, entornos virtuales, historial de shell — de modo que destruir la VM tras cada sesión haría inútiles a los agentes. En lugar de controlar el estado de la VM, Bromure Agentic Coding controla lo que la VM tiene permitido contener en algún momento: ningún secreto real y ninguna ruta sin mediación hacia internet. La efimeridad sigue existiendo como una vía de escape en lugar de un valor por defecto: Restablecer disco vuelve a clonar el disco de sistema desde la imagen base, los puntos de control de disco y home permiten la reversión, bromure-cli vm run --rm crea espacios de trabajo desechables al estilo Docker que se eliminan cuando la VM se detiene, y el flujo de compromiso borra un disco y home contaminados mientras preserva tus ajustes y claves.

La VM auxiliar del navegador

Una pieza de Bromure (Web) pervive dentro de Bromure Agentic Coding: el panel del navegador agéntico. Cuando tú (o el agente) lo abres, el espacio de trabajo obtiene una segunda VM efímera — un invitado Alpine + Chromium clonado en el directorio temporal y eliminado cuando se desmonta el panel. Esta VM auxiliar es la excepción que confirma la regla: el estado de navegación es desechable por defecto (a menos que el espacio de trabajo habilite Mantener sesión iniciada en sitios web, que conserva el perfil de Chromium en un disco cifrado por espacio de trabajo), mientras que la VM del espacio de trabajo contigua es duradera. Ambas VM se sitúan en el mismo segmento de red privada, de modo que el navegador puede cargar un servidor de desarrollo que el agente acaba de iniciar mediante la IP de la VM.

Ciclo de vida de la VM: Apagada, Suspendida y En ejecución

Cada espacio de trabajo se encuentra siempre en exactamente uno de tres estados duraderos, mostrados como una etiqueta junto al nombre del espacio de trabajo en la barra lateral y en el panel de control de la VM. (También verás brevemente estados transitorios — Iniciando… en la barra lateral y una indicación de arranque en el panel de control — mientras una VM se está levantando).

Al seleccionar el nombre de un espacio de trabajo se muestra su panel de control para cualquier estado: tarjetas en vivo de CPU, memoria, vCPU, disco y tiempo de actividad mientras se ejecuta, o la especificación de la máquina y el resumen de configuración mientras está apagada o suspendida — la captura de pantalla anterior muestra un espacio de trabajo que nunca se ha lanzado, razón por la cual la tarjeta de Disco todavía indica 0 MB (aún no existe ningún clon). El botón de la esquina superior derecha es Iniciar para un espacio de trabajo apagado y Reanudar para uno suspendido.

Algunas reglas del ciclo de vida que conviene interiorizar:

• La suspensión es una instantánea de RAM, no un archivo guardado. Restaurarla requiere que la configuración de la VM sea idéntica, razón por la cual cada espacio de trabajo persiste un identificador de máquina y una dirección MAC determinista. Si cambias el conjunto de carpetas compartidas mientras existe una instantánea, la app pide descartar el estado suspendido — el siguiente lanzamiento arranca en frío, y ningún archivo se ve afectado.
• Una instantánea nunca sobrevive a su disco. Restablecer o borrar el disco de sistema también descarta cualquier instantánea de RAM guardada y el estado de las pestañas, porque un disco nuevo junto con una RAM obsoleta se corrompería al instante.
• Apagada no significa borrada. Un espacio de trabajo apagado conserva su disco de sistema y home indefinidamente. La destrucción real de datos siempre es explícita (Restablecer disco, Borrar home, Eliminar espacio de trabajo) o forzada por el flujo de compromiso.

Acciones de cierre

Lo que ocurre cuando cierras una sesión es una elección por espacio de trabajo (Al cerrar la ventana en el editor del espacio de trabajo): Ejecutar en segundo plano (desconectar la ventana, mantener la VM en ejecución), Suspender, Apagar o Preguntar — el valor por defecto, que pregunta cada vez con las tres opciones. Cerrar la última pestaña de terminal se enruta a través de la misma elección. Consulta Sesiones para ver el flujo completo.

El límite de red

El límite de red es la idea central del producto: todo el HTTPS saliente del invitado pasa a través de un proxy man-in-the-middle (MITM) del lado del anfitrión, y todas las protecciones — custodia de secretos, delimitación de credenciales, análisis de la cadena de suministro, detección de inyección de prompts, trazado — se aplican en ese único punto. El agente no puede eludirlo, porque no hay nada útil en su lado de la línea.

El flujo, de principio a fin:

1. El invitado solo contiene falsificaciones. En el lanzamiento de la sesión, el anfitrión escribe credenciales de marcador de posición intencionadamente inválidas en la VM — variables de entorno como ANTHROPIC_API_KEY, y archivos de configuración como ~/.git-credentials, ~/.docker/config.json y ~/.kube/config. Las falsificaciones preservan la estructura (sk-ant-api03-brm-…, con forma de ghp_…, brm_…) para que los validadores del lado del cliente las acepten, y son deterministas por instalación, de modo que las herramientas nunca ven que una clave "rota" entre sesiones. Los valores reales correspondientes se cargan en el mapa de intercambio en memoria del proxy del anfitrión, cada uno asociado al host de destino al que pertenece.
2. El TLS del invitado termina en el proxy. Cada shell del invitado exporta HTTPS_PROXY=http://127.0.0.1:8080, un endpoint dentro de la VM que hace túnel sobre vsock (puerto 8443) hacia el proxy del anfitrión. El proxy presenta un certificado de hoja falsificado por host, firmado por la CA raíz de Bromure, inspecciona la solicitud y la vuelve a cifrar hacia el upstream real.
3. Las falsificaciones se convierten en reales solo a la salida. El proxy intercambia cada falsificación por su valor real — intercambios de cabecera para claves de API y tokens, intercambios de cuerpo para flujos de actualización OAuth, re-firma SigV4 completa para AWS (el invitado firma con un secreto falso; el anfitrión elimina esa firma y vuelve a firmar con el real), firma ssh-agent sobre vsock para SSH. Los intercambios se delimitan exacto-o-subdominio al host registrado, nunca por subcadena, de modo que una credencial registrada para api.anthropic.com nunca se inyecta hacia un dominio de aspecto similar.

La CA raíz de Bromure

El proxy solo puede terminar el TLS del invitado porque el invitado confía en él para hacerlo. En el primer lanzamiento, la app genera una autoridad de certificación por instalación — la CA raíz de Bromure Agentic Coding — cuyo certificado público se monta en el almacén de confianza de cada VM en el arranque a través de la partición meta. La clave privada nunca abandona el anfitrión (vive bajo ~/Library/Application Support/BromureAC/ca/, legible solo por su propietario). Nada fuera de tus VM de Bromure confía en esta CA: no puede usarse para interceptar el propio tráfico de tu Mac, y eliminar el directorio ca/ simplemente genera una CA nueva en el siguiente lanzamiento.

Fail-closed por construcción

El diseño es fail-closed: si el tráfico del invitado alguna vez evade el proxy — una herramienta que ignora las variables del proxy, un socket sin procesar, un intento deliberado de eludirlo — la única credencial que puede presentar es una falsificación que ningún upstream acepta. AWS devuelve InvalidSignatureException; los proveedores de API rechazan la clave de marcador de posición. Eludir el límite no le aporta nada a un atacante, porque el límite no es donde se comprueban los secretos — es el único lugar donde los secretos existen.

El detector de compromiso

El límite también vigila la dirección opuesta del abuso: la exfiltración. El proxy escanea cada solicitud saliente en busca de cualquiera de los tokens falsos registrados del espacio de trabajo. Una falsificación tiene exactamente un destino legítimo — el host para el que fue generada — de modo que una falsificación observada dirigiéndose a cualquier otro lugar es la firma de un agente intentando filtrar credenciales. El proxy rechaza la solicitud sin reenviar un solo byte, pausa la VM y te alerta; el espacio de trabajo se marca como comprometido y se niega a arrancar de nuevo hasta que su disco y home (presuntamente contaminados) se borren. Tus ajustes, tokens y claves SSH se conservan — y, dado que solo la falsificación se filtró alguna vez, la credencial real nunca necesita rotación. El modelo completo de credenciales, incluidos los avisos de aprobación por credencial y las concesiones limitadas por TTL, se aborda en Credenciales y el límite de red.

Qué persiste y qué no

Bromure Agentic Coding es explícito sobre la vida útil. Todo lo que posee un espacio de trabajo vive bajo ~/Library/Application Support/BromureAC/profiles/<uuid>/; la tabla siguiente es el mapa definitivo de qué sobrevive a qué.

Persistente — sobrevive al apagado y a los reinicios de la app:

Efímero — reconstruido o destruido automáticamente:

De este mapa se derivan dos consecuencias. Primera, "cerrar la ventana" nunca es destructivo por sí solo — los verbos destructivos son todos explícitos y confirmados. Segunda, cuando quieres desechabilidad, tienes opciones graduadas: revertir un punto de control, Restablecer disco (el home sobrevive), Borrar home, eliminar el espacio de trabajo, o empezar con uno desechable mediante bromure-cli vm run --rm desde el principio.

Nota: Las carpetas compartidas del anfitrión son directorios de proyecto en tu Mac, fuera del almacenamiento de Bromure. Ninguna acción de Bromure las borra jamás — incluido el borrado por compromiso — y el aviso de borrado lo indica explícitamente.

Puentes anfitrión–invitado (vsock)

La integración interactiva entre el Mac y el invitado circula por sockets virtio — canales punto a punto de anfitrión a invitado que existen con independencia de la red de la VM. Nunca los configuras, pero saber que existen ayuda al leer trazas o el capítulo de Solución de problemas. Cada puente escucha en un puerto vsock numerado:

Puentes de la VM del espacio de trabajo:

Puentes de la VM auxiliar del navegador: configuración (5000), transferencia de archivos (5100), Chrome DevTools Protocol (5200), relé de enlaces (5300), webcam (5400), barra de pestañas nativa (5810) y traza de red (5900).

Portapapeles

No hay un demonio de portapapeles independiente para los terminales del espacio de trabajo — el portapapeles circula por el propio protocolo del terminal. Copiar dentro del invitado (una selección de tmux, o cualquier programa que emita OSC 52) aterriza automáticamente en el portapapeles de macOS; ⌘C copia la selección del terminal del lado del anfitrión; ⌘V pega en el invitado mediante pegado entre corchetes. En el panel del navegador, un agente de portapapeles del invitado más la captura de ⌘C/⌘V proporcionan copiar y pegar entre el Mac y Chromium.

Transferencia de archivos

Los archivos se mueven entre el Mac y un espacio de trabajo de tres maneras, todas cubiertas en Sesiones: carpetas compartidas (virtiofs, la ruta normal para archivos de proyecto), la ventana del explorador de archivos tipo Finder (arrastrar dentro y fuera sobre el servicio de archivos vsock en el puerto 5800) y el pegado de imágenes (⌘V con una imagen la sube al invitado y pega su ruta). El protocolo dedicado de transferencia de archivos en el puerto 5100 pertenece a la VM auxiliar del navegador.

Redes

Modo NAT (el valor por defecto)

Todas las VM de espacio de trabajo en modo NAT se conectan a un único conmutador L2 de software de ámbito de proceso, multiplexado sobre una interfaz vmnet compartida/NAT. Las consecuencias:

• Una subred privada — 192.168.64.0/24 por defecto (puerta de enlace .1, direcciones arrendadas de .2 a .254 durante 24 horas). Si la propia LAN de tu Mac ya usa ese rango, Bromure elige automáticamente otro 192.168.x.0/24.
• Bromure ejecuta su propio servidor DHCP en ese conmutador (el integrado de Apple solo puede rastrear un único arrendamiento por interfaz), y los arrendamientos persisten en dhcp-leases.sqlite en el anfitrión.
• Direccionamiento estable — cada espacio de trabajo obtiene una dirección MAC determinista y administrada localmente, persistida en profile-macs.json, y combinada con arrendamientos persistentes un espacio de trabajo suele mantener la misma IP entre reinicios de la app (con el mejor esfuerzo posible: mientras la dirección siga libre). La IP actual siempre se muestra en la cabecera del panel de control de la VM y en la etiqueta de la barra de herramientas.
• Las VM pueden alcanzarse entre sí. Cada VM en modo NAT — tanto las VM de espacio de trabajo como las auxiliares del navegador — se sitúa en el mismo segmento L2 por diseño, de modo que el panel del navegador puede cargar un servidor de desarrollo que se ejecuta en la VM del espacio de trabajo, y dos espacios de trabajo pueden comunicarse con los servicios del otro. La tarjeta de Puertos en escucha del panel de control lista cada socket del invitado alcanzable externamente como el endpoint <VM-IP>:<port> al que realmente te conectarías desde el Mac.
• Aislamiento del exterior. NAT significa que las VM son alcanzables desde tu Mac pero no están expuestas en tu LAN física, y las conexiones entrantes desde otros lugares no son posibles a menos que publiques explícitamente un servicio (túneles rápidos de Cloudflare por servicio, desde la tarjeta de Puertos en escucha).

El MTU de la NIC del invitado se fija en 1280 por defecto — un valor conservador que sobrevive a entornos de VPN y de path-MTU corporativos — y puede elevarse con defaults write io.bromure.agentic-coding vm.mtu -int <value>.

Recuerda que el tráfico IP ordinario en esta red no es cómo fluyen las credenciales: el HTTPS del invitado se dirige a través del endpoint del proxy dentro de la VM y sobre vsock hacia el límite de red. La red NAT transporta todo lo demás — y cualquier cosa que sortee el proxy transporta solo credenciales falsas, que es exactamente la propiedad fail-closed descrita anteriormente.

Modo puente (por espacio de trabajo)

Un espacio de trabajo puede, en cambio, unirse a tu LAN física: el modo puente conecta la VM a una interfaz del anfitrión elegida mediante puenteo vmnet, haciéndola aparecer como un dispositivo en la red local (útil cuando otras máquinas deben alcanzar la VM directamente). Si la interfaz elegida no está disponible en el lanzamiento, la VM recurre a NAT. El modo de red se establece por espacio de trabajo en el editor del espacio de trabajo; consulta Espacios de trabajo.

Inicio instantáneo y precalentamiento

Dos mecanismos diferentes hacen que las sesiones se sientan instantáneas, y vale la pena saber cuál aplica dónde:

• Las VM de espacio de trabajo no se agrupan. Cada espacio de trabajo arranca su propia VM persistente directamente. El primer lanzamiento es rápido porque el disco de sistema es un clon CoW instantáneo en lugar de una imagen copiada; los arranques en frío posteriores son arranques Linux ordinarios (cubiertos por la superposición animada de arranque); y un espacio de trabajo Suspendido se salta el arranque por completo — su instantánea de RAM se restaura y la sesión se reanuda en su sitio, con terminales y todo, casi al instante.
• La VM auxiliar del navegador usa un grupo caliente. El motor mantiene una VM del navegador pre-arrancada lista en segundo plano, de modo que abrir el panel del navegador agéntico tarda menos de 1 segundo. Cuando esa VM se reclama, un reemplazo comienza a calentarse; mientras está inactiva, el globo de memoria de la VM caliente se infla (el invitado conserva aproximadamente 512 MB) y la VM se suspende tras 30 segundos para seguir siendo económica, luego se reanuda y el globo se desinfla (memoria completa restaurada al invitado) en el momento de reclamarla.

La distinción se deriva directamente de la filosofía del ciclo de vida: las VM agrupadas solo tienen sentido cuando cada instancia es intercambiable, lo cual es cierto para las VM desechables del navegador y falso para las máquinas persistentes por espacio de trabajo.