CLI, API y MCP

Todo lo que hace la app también se puede manejar sin su ventana. El binario de la app — bromure-ac, dentro de Bromure Agentic Coding.app/Contents/MacOS/ — es también una CLI de varios comandos, un plano de control HTTP, un servidor MCP para herramientas de IA externas y un destino de AppleScript. Dentro de cada VM, un conjunto de servidores MCP integrados da a los agentes su propia vista de Bromure. Este capítulo es la referencia de todos ellos.

Las superficies, de fuera hacia dentro:

• La línea de comandos bromure-cli — una CLI al estilo Docker/kubectl para máquinas, VM, terminales, comandos, trazas, modelos, acceso remoto e inscripción.
• El plano de control — las mismas operaciones como JSON sobre HTTP, en un socket Unix solo para el propietario y, opcionalmente, en un puerto TCP de loopback.
• El servidor MCP de AC (bromure-ac mcp) — permite que una herramienta de IA en tu Mac (Claude Code, Claude Desktop) gestione la app.
• Los servidores MCP dentro del invitado — integrados en cada VM: el navegador, las automatizaciones, la infraestructura, la delegación y, para sesiones concretas, el tablero de tareas y la Centralita.
• AppleScript — el diccionario Bromure AC Suite.

A lo largo de este capítulo, y en la CLI, una máquina se llama espacio de trabajo (su nombre en el editor de ajustes y en la línea de comandos). Las sesiones en el sentido de conversaciones de agente se alcanzan mediante las rutas /agent-sessions; las rutas antiguas /sessions y el término session en la CLI y en AppleScript se refieren a la ventana de una máquina.

El plano de control: socket y API

Cada superficie habla HTTP con la app en ejecución mediante uno de dos transportes:

La CLI nunca habla directamente con una VM. Cada subcomando es un cliente HTTP ligero sobre el socket de control, así que los mismos comandos funcionan en local y — cuando el socket se tuneliza por SSH — contra una instancia remota desde un cliente enriquecido. Si no hay ningún agente en ejecución cuando invocas un comando que lo necesita, la CLI arranca automáticamente un agente en segundo plano sin ventana (bromure-ac run --headless) y espera hasta 40 segundos a que responda a /health. Los comandos de solo lectura (vm ls, describe, trace …) no arrancan nada; en su lugar muestran No bromure-ac agent running..

Nota: El socket de control está siempre disponible mientras la app se ejecuta y es independiente del interruptor Activar servidor de automatización. Ese interruptor solo controla el listener TCP en el puerto 9223. No necesitas activar la API de automatización para usar la CLI.

La línea de comandos bromure-cli

Puedes llamar al binario por su ruta completa dentro del paquete, pero el nombre corto es más cómodo. Elige Bromure Agentic Coding › Instalar herramienta de línea de comandos… en el menú de la app. La alerta ¿Instalar la herramienta de línea de comandos “bromure-cli”? explica que crea un enlace simbólico en /usr/local/bin/bromure-cli y que necesita tu contraseña de administrador una vez; haz clic en Instalar (o Cancelar). Si todo va bien, Herramienta de línea de comandos instalada te indica que ejecutes bromure-cli --help. La app ya nunca lo ofrece al arrancar — el elemento de menú es la única vía, y puedes volver a ejecutarlo en cualquier momento (por ejemplo, tras mover la app).

El mismo binario se comporta de forma distinta según el nombre con el que se le llame:

• Como bromure-cli, oculta los comandos internos de la app — la gestión de imágenes (init, info, reset y las herramientas del pipeline de publicación), el servidor mcp y el run predeterminado de la interfaz gráfica — y expone solo los grupos pensados para el terminal (Workspaces, Tracing, Local inference, Enterprise features, remote). Un bromure-cli a secas muestra la ayuda en lugar de abrir la app.
• Como bromure-ac (el binario dentro del paquete de la app), todo está disponible y el subcomando predeterminado es run, que abre la interfaz gráfica.

Los ejemplos de abajo usan bromure-cli; usa la ruta completa …/MacOS/bromure-ac para los comandos que solo él expone.

Los comandos aceptan el id de un espacio de trabajo, un prefijo corto del id o su nombre allí donde aparece un argumento de espacio de trabajo. Los grupos de comandos vm y workspaces son alias el uno del otro. Qué es una máquina, y cómo se relaciona con las sesiones, se explica en Máquinas.

La app y el agente en segundo plano

Gestión de imágenes

La imagen base se instala una sola vez. Estos comandos solo existen con el nombre bromure-ac.

Nota: Si no existe imagen base, al abrir la interfaz gráfica llegas al asistente de configuración inicial, que instala la imagen en el sitio — consulta Instalación y primer arranque.

Control de espacios de trabajo y VM

Este es el grupo central. vm run tiene forma deliberadamente de Docker: arranca un espacio de trabajo y entrega tu terminal a la sesión tmux compartida bromure del invitado.

Vale la pena conocer algunos detalles operativos:

• Opciones de vm run. --tool recibe un id de agente: claude, codex, grok, kimi u omp. --auth es token, subscription, bedrock o local. Un valor no reconocido es un error que enumera los valores válidos, por ejemplo Invalid --tool “gpt” — expected one of: claude | codex | grok | kimi | omp.; workspaces create comprueba --tool y --auth de la misma manera. -v/--volume <hostdir> monta una carpeta del anfitrión en ~/<basename> dentro del invitado (repetible, hasta 8). -d/--detach arranca la VM y vuelve en lugar de adjuntarse. --rm elimina el espacio de trabajo y su disco cuando la VM se detiene. Desconéctate de un tmux adjunto con Ctrl-b d — la VM sigue en ejecución.
• Los agentes vienen de Modelos. Las opciones de herramienta y autenticación solo inicializan un espacio de trabajo nuevo. El modelo y el proveedor que usa realmente cada agente vienen de Preferencias › Modelos y del panel Modelos del propio espacio de trabajo — consulta Modelos y proveedores.
• Sensible al TTY. El comportamiento predeterminado al estilo Docker, que entrega el terminal a tmux, solo se aplica en un terminal real; las invocaciones por tubería o desde scripts se comportan como si hubieras pasado -d.
• Valores de workspaces create. Los colores son blue, red, green, orange, purple, pink, teal o gray.
• Conservar en blanco al editar. workspaces edit exporta toda la configuración con los secretos en blanco; un documento guardado con un secreto en blanco conserva el valor almacenado, de modo que un viaje de ida y vuelta nunca puede borrar tus claves. Un búfer sin cambios no guarda nada; un JSON no válido aborta.
• Esperas de exec. vm exec espera hasta 10 segundos al agente de shell del invitado; un 502 significa que la VM puede no estar en ejecución o que el nombre no coincidió. Los avisos de aprobación que se disparan durante una sesión conectada se muestran en tu terminal (véase Consentimiento en terminales adjuntas), nunca dentro del invitado.

Comprobar un disco desde la línea de comandos

vm fsck es el gemelo programable de Ejecutar fsck… en el navegador ext4 y del botón Reparar disco que la app muestra cuando un arranque se detiene por errores del sistema de archivos. Usa el comprobador ext4 propio de Bromure, así que no hay que instalar nada.

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

Se niega a ejecutarse mientras el espacio de trabajo está en marcha. La salida termina con uno de estos resúmenes: «Filesystem is clean.», «Filesystem repaired; it is now consistent.» o «Filesystem has errors this checker cannot repair.». Una comprobación sin --repair que encuentra problemas sugiere volver a ejecutarla con --repair. El comando termina con el estado 4 mientras queden errores. El alcance y los límites del comprobador se describen en Avanzado.

Modelos, enrutamiento y Fusion

Los ajustes de modelos y proveedores se tratan en Modelos y proveedores y la síntesis multimodelo en Fusion; los interruptores de la CLI son:

Inspección de trazas

Estos leen las trazas del proxy por espacio de trabajo. No devuelven nada salvo que el espacio de trabajo tenga el trazado activado — consulta Ajustes de trazado — y la historia completa está en Trazado y auditoría.

Acceso remoto

La puerta de entrada SSH opcional está desactivada por defecto y documentada por completo en Acceso remoto y clientes. Todas las operaciones pasan por la app en ejecución a través del socket de control.

Inscripción en Enterprise

Contrapartes en la CLI de la hoja Iniciar sesión en bromure.io…, para el aprovisionamiento de dispositivos mediante script. Véase Enterprise.

Comandos de integración e internos

La TUI remota (__remote-menu)

Cuando el acceso remoto por SSH está activado, cada inicio de sesión remoto se fuerza (mediante ForceCommand) a una interfaz de terminal ANSI hecha a mano en lugar de una shell — un menú de pantalla alternativa, de 256 colores, manejado con las flechas y los dígitos, que funciona sobre cualquier PTY de SSH (usa ssh -t). Refleja la CLI en forma de menús:

• Espacios de trabajo — creación con un formulario de una sola pantalla (Name, Tool, Auth, API key, Memory, Color, Folders, Generate SSH, Full settings…, Create), acciones por espacio de trabajo (Attach, New tab, Describe, Configure…, Fusion, Routing, Worktrees…, Reboot…, Suspend, Kill para los que están en ejecución; Start, Describe, Configure…, Delete para los apagados) y una vista de tabla en bruto. Configure… ofrece los paneles del editor de ajustes como formularios de texto; su formulario Models es de solo lectura (los proveedores del servidor, y si el espacio de trabajo los sobrescribe), ya que los modelos se eligen en la app.
• Modelos — los modelos instalados y el catálogo de descarga; al elegir un modelo no instalado se ofrece hacer model pull en línea con progreso en vivo.
• Trazas — Resumen / Nombres de host / Fugas / Recientes / Borrar.

Mientras estás adjunto al tmux de un espacio de trabajo, una combinación de teclas mágica (por defecto Ctrl-], mostrada en el banner) hace aparecer una superposición de control dibujada por el anfitrión: un árbol de pestañas, New tab, Worktrees…, Fusion, Routing, Edit settings…, Reboot…, Suspend, Disconnect. El invitado nunca ve la tecla de activación — cámbiala con el archivo remote/overlay-key o $BROMURE_OVERLAY_KEY. Ctrl-b d te desconecta de tmux y vuelve al menú. La TUI remota trabaja con las máquinas y sus terminales; las sesiones de agente, las salas y la Centralita se alcanzan en cambio desde el cliente enriquecido. La historia completa del acceso remoto está en Acceso remoto y clientes.

La API de automatización de loopback

El plano de control también puede exponerse como JSON sobre HTTP por TCP, para scripts en cualquier lenguaje. Está desactivado por defecto.

Activarla

Abre Preferencias… › Automatización (⌘,) — el panel API de automatización y servidor MCP.

1. Activa Activar servidor de automatización. Cuando está activo, el panel indica Escuchando en 127.0.0.1:9223; desactivarlo detiene el servidor de inmediato.
2. Opcionalmente, define el Puerto (con la leyenda (predeterminado: 9223)) y la Dirección de enlace (por defecto 127.0.0.1). El puerto y la dirección de enlace surten efecto la próxima vez que arranque el servidor — apaga y vuelve a encender el interruptor para aplicarlos ya.

También puedes accionar el interruptor sin la interfaz gráfica:

defaults write io.bromure.agentic-coding automation.enabled -bool true

Advertencia: Establecer la Dirección de enlace en algo distinto de 127.0.0.1 expone la API —y el servidor MCP que la respalda— a la red, y el panel advierte Un enlace fuera de loopback expone la API a la red. El servidor MCP no tiene autenticación. No hay autenticación en el listener TCP más allá del límite de loopback y de la puerta BROMURE_DEBUG_CLAUDE que se describe abajo. Deja la dirección de enlace en loopback a menos que tengas una razón específica y de confianza para no hacerlo.

Modelo de autenticación

El listener TCP y el socket de control sirven las mismas rutas, pero con acceso distinto:

Dicho de otro modo: el socket de control es la vía de acceso total, solo para el propietario; la API TCP abre el subconjunto seguro en loopback y deja todo lo demás tras el indicador de depuración. Los segmentos de ruta se codifican en porcentaje una sola vez (para que funcionen los nombres de espacios de trabajo con espacios).

Endpoints para scripting

Las rutas más útiles:

Como la ruta del socket de control contiene espacios, captúrala primero en una 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"}'

El subconjunto seguro funciona por la API TCP una vez que la activas — por ejemplo, listar los espacios de trabajo y abrir la ventana de una máquina no necesita el indicador de depuración:

curl http://127.0.0.1:9223/profiles
curl -X POST http://127.0.0.1:9223/sessions -d '{"profile":"Web app"}'

Nota: Las rutas del plano de control son una superficie de integración compartida con el cliente enriquecido, no una API pública versionada; la forma de sus peticiones y respuestas puede cambiar entre versiones. Los comandos de la CLI de arriba son la forma estable de automatizar Bromure con scripts. Las rutas solo de depuración, las variables de entorno y las ubicaciones de archivos están catalogadas en el Apéndice.

El servidor MCP de AC (bromure-ac mcp)

bromure-ac mcp ejecuta un servidor MCP JSON-RPC sobre stdio (nombre del servidor bromure-ac) que permite a una herramienta de IA en tu Mac gestionar la app. Envuelve la API HTTP de automatización y AppleScript, así que activa primero el servidor de automatización — las herramientas de listado y de ventanas llaman a la API HTTP en --api-url (por defecto http://127.0.0.1:9223). No está disponible con el nombre bromure-cli.

Las herramientas que expone:

• bromure_ac_list_profiles, bromure_ac_list_sessions
• bromure_ac_open_session (abre la ventana de un espacio de trabajo; espera hasta 30 segundos), bromure_ac_close_session
• bromure_ac_get_profile, bromure_ac_set_profile (reemplazo JSON atómico, se conserva el id)
• bromure_ac_get_profile_setting, bromure_ac_set_profile_setting

Con --debug (y BROMURE_DEBUG_CLAUDE establecido en la app) añade bromure_ac_app_state, bromure_ac_vm_exec, bromure_ac_vm_read_file y bromure_ac_vm_write_file.

Para conectarlo a Claude Code, añade lo siguiente a ~/.config/claude-code/.mcp.json (o al equivalente de tu cliente). Es exactamente el fragmento que muestra la sección Configuración del cliente MCP del panel Automatización:

{
  "mcpServers": {
    "bromure-ac": {
      "command": "/Applications/Bromure Agentic Coding.app/Contents/MacOS/bromure-ac",
      "args": ["mcp"]
    }
  }
}

Nota: Las herramientas de perfil get/set invocan osascript (AppleScript contra la app en ejecución), por lo que la app gráfica debe estar en ejecución y macOS puede pedir una vez el permiso de Automatización. El JSON de perfil viaja con los secretos en blanco a menos que BROMURE_DEBUG_CLAUDE esté establecido.

Servidores MCP dentro de las VM

Aparte del servidor MCP de AC, Bromure da a los agentes de cada VM un conjunto de servidores MCP integrados — sin configuración alguna. Cada uno es un pequeño adaptador Python stdio colocado en solo lectura dentro del invitado en /mnt/bromure-meta/; el adaptador se conecta al anfitrión por vsock y se reconecta indefinidamente si se corta, así que el agente nunca pierde sus herramientas. El anfitrión sirve las herramientas, y cada llamada se comprueba allí: un agente solo puede ver y tocar aquello a lo que tienen derecho su propia máquina y su sesión.

Los servidores browser, automations, infrastructure y delegation se escriben en la configuración MCP propia de cada agente, junto a los servidores que añades en el panel MCP de la máquina (Ajustes de MCP). Los servidores task board y switchboard solo se pasan a las ejecuciones que los necesitan.

El servidor browser

El servidor browser maneja el Chromium integrado de la máquina, que se ejecuta en su propia VM desechable. Sus 23 herramientas cubren la navegación y la inspección — browser_navigate, browser_new_tab, browser_list_tabs, browser_activate_tab, browser_close_tab, browser_back, browser_forward, browser_reload, browser_screenshot (con opción de página completa), 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 y browser_pick_element (un selector interactivo de elementos de 60 segundos).

Una llamada a una herramienta con el navegador cerrado lo abre y espera al arranque en frío. Como el navegador es una VM aparte, las instrucciones del servidor indican a los agentes que lleguen a un servidor de desarrollo de su máquina por la IP de LAN de la máquina (hostname -I), nunca por localhost. La historia completa está en El navegador integrado.

Nota: En un cliente enriquecido, el flujo browser-MCP de los agentes puede ir por la conexión SSH, de modo que un agente remoto maneja el panel de navegador que ves en local. Consulta Acceso remoto y clientes.

OAuth para los servidores MCP que añades

Los servidores MCP HTTP que añades en el editor pueden autenticarse a través del intermediario OAuth del lado del anfitrión: realiza el descubrimiento RFC 8414 y el registro dinámico de cliente RFC 7591 (como Bromure AC), ejecuta un flujo de código de autorización PKCE en el navegador de tu sistema y sirve la retrollamada en un listener de loopback (puertos 28500–28599). La página de éxito dice Autorizado — Puedes cerrar esta pestaña y volver a Bromure AC. Todo el flujo se ejecuta en el anfitrión, de modo que la VM nunca ve credenciales OAuth reales.

AppleScript (Bromure AC Suite)

Un diccionario de scripting, la Bromure AC Suite, es otra superficie de automatización — útil para la orquestación y para herramientas de capturas de pantalla que necesitan ID de ventana. Apunta a application "Bromure Agentic Coding" desde Editor de Scripts o con osascript. Abarca:

• Perfiles — list profiles, create ac profile <name> [color <c>] (devuelve un UUID), delete ac profile <name|uuid> y el viaje de ida y vuelta del documento completo mediante get profile json / set profile json (el perfil entero; se conserva el id; los secretos guardados se reintegran en los campos en blanco).
• Ajustes por campo — get profile setting … key … / set profile setting … key … to value ….
• Ventanas del editor — open profile manager, open ac profile editor, close ac profile editor, select editor category <key> y get editor window id / get main window id (un CGWindowID para screencapture -l).
• Ventanas de máquina — open ac session, close ac session, list ac sessions.
• Estado y ajustes de la app — get app state (JSON), más get ac app setting / set ac app setting para las claves automation.enabled, automation.port, automation.bindAddress, remoteAccess.enabled, remoteAccess.port, remoteAccess.bindAddress, managed.serverURL y managed.acIngestURL. Establecer automation.enabled acciona el servidor HTTP en vivo.

Por ejemplo, para abrir la ventana de una máquina:

osascript -e 'tell application "Bromure Agentic Coding" to open ac session "Web app"'

Nota: El JSON de perfil viaja con los secretos depurados a menos que BROMURE_DEBUG_CLAUDE esté establecido. Establecer apiKey en una cadena vacía mediante set profile setting borra la clave en lugar de conservarla — a diferencia del comportamiento de conservar-en-blanco de los puentes de ida y vuelta JSON. El cambio de idioma deliberadamente no es scriptable; relanza la app con, por ejemplo, -AppleLanguages "(fr)" en su lugar.

Automatizaciones programadas

Una automatización programada es una ejecución de agente recurrente y desatendida, vinculada a una máquina. Las automatizaciones se crean y gestionan desde el tablero de automatizaciones (⇧⌘A, o la sección Automatizaciones de la barra lateral), y los agentes pueden gestionar las automatizaciones de su propia máquina mediante el servidor MCP automations de arriba. Toda la función — disparadores, programaciones, encadenamiento, la pantalla de inyección obligatoria, el historial de ejecuciones — está documentada en Automatizaciones. Esta sección cubre la superficie del plano de control: manejar las automatizaciones mediante la API, responder a los prompts de decisión que puede plantear un arranque desatendido y cómo funciona el consentimiento en un terminal adjunto.

Controlar las automatizaciones a través de la API

Responder a los prompts pendientes

Algunas decisiones de ciclo de vida — la oferta de actualización de la imagen base, un disco que no supera su comprobación de arranque, una alerta de compromiso, un borrado por compromiso — aparecen normalmente como una alerta local. Cuando no hay nadie frente al Mac para responder (un agente sin interfaz, o un arranque pedido por un cliente enriquecido remoto), se ponen en cola: aparecen en GET /state bajo pendingPrompts (cada uno con id, profileID, title, message y etiquetas de botones) y se responden con 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"}'

Pasa como choice una de las propias etiquetas de botón del prompt. Si ningún cliente responde antes de que caduque el prompt, se resuelve con su alternativa segura — nunca la opción destructiva (una alerta de compromiso, por ejemplo, recurre a apagar la VM). Si no hay ningún cliente conectado, recurre a ella de inmediato. Un cliente enriquecido muestra estos prompts como alertas normales.

Nota: Las automatizaciones, las delegaciones y otros arranques desatendidos nunca esperan a un prompt. Un arranque que necesitaría tu respuesta — una máquina marcada como comprometida, o un modelo local que aún se está descargando — se rechaza, con un motivo claro en el historial de la ejecución («The workspace is marked compromised — start it yourself to confirm the wipe.»). Una máquina suspendida cuyo estado guardado no se puede restaurar arranca de cero.

Consentimiento en terminales adjuntas

Mientras un terminal está adjunto de forma interactiva a una máquina — mediante vm exec -it, vm attach o un attach por SSH — los prompts de aprobación del lado del anfitrión (uso de credenciales y similares) se muestran en tu terminal, no dentro del invitado. El prompt dice 🔒 Bromure — approval required con opciones numeradas y Choice [1-N] (Enter or timeout = deny). Enter, tiempo agotado, EOF o desconectarse significan denegar, así que un invitado comprometido nunca puede falsificar una aprobación. Después se vuelve a dibujar el tmux del invitado.

Endpoints de depuración (BROMURE_DEBUG_CLAUDE)

Abrir la app con BROMURE_DEBUG_CLAUDE definido levanta la barrera de depuración de la API de automatización TCP, de modo que las rutas de la fila central de la tabla de autenticación también funcionan por TCP, incluidas estas rutas de depuración (siempre disponibles en el socket de control, salvo que se indique lo contrario):

• GET /debug/ui-shot?path=…&which=… — la app dibuja su propia ventana en un PNG (sin necesidad del permiso de Grabación de pantalla) y devuelve un volcado de los marcos de las subvistas; la salida predeterminada es /tmp/bromure-ui-shot.png.
• POST /debug/editor — controla el editor de ajustes para la herramienta de captura de pantalla.
• POST /detect/prompt-injection — ejecuta los detectores reales y devuelve su veredicto (esta ruta requiere el flag de depuración incluso en el socket de control).

El indicador también deja que los secretos pasen tal cual por los puentes JSON de perfiles de AppleScript y MCP, y lo requieren las herramientas de VM de bromure-ac mcp --debug. GET /health informa de debugEnabled para que sepas en qué modo está la app.

Advertencia: BROMURE_DEBUG_CLAUDE elimina la barrera de seguridad que normalmente mantiene exec, el control de las VM y los secretos de perfil en bruto fuera de la API TCP de loopback. Ejecuta la app con él solo en una máquina que controles, y nunca lo combines con una dirección de enlace que no sea de loopback — eso expondría acceso completo a la shell de las VM, secretos sin ocultar y capturas de ventanas a cualquiera que pueda llegar al puerto. Es distinto de BROMURE_AC_DEBUG (registro de eventos en stderr) y de BROMURE_CLI_DEBUG (diagnóstico del socket de la CLI), que son interruptores de registro inofensivos.