CLI, API e MCP

Tudo o que a aplicação faz também pode ser conduzido sem a sua janela. O binário da aplicação — bromure-ac, dentro de Bromure Agentic Coding.app/Contents/MacOS/ — é também uma CLI com vários comandos, um plano de controlo HTTP, um servidor MCP para ferramentas de IA externas e um alvo de AppleScript. Dentro de cada VM, um conjunto de servidores MCP integrados dá aos agentes a sua própria vista do Bromure. Este capítulo é a referência de todos eles.

As superfícies, de fora para dentro:

• A linha de comandos bromure-cli — uma CLI ao estilo Docker/kubectl para máquinas, VMs, terminais, comandos, rastos, modelos, acesso remoto e inscrição.
• O plano de controlo — as mesmas operações em JSON sobre HTTP, num socket Unix exclusivo do proprietário e, opcionalmente, numa porta TCP de loopback.
• O servidor MCP do AC (bromure-ac mcp) — permite que uma ferramenta de IA no seu Mac (Claude Code, Claude Desktop) faça a gestão da aplicação.
• Os servidores MCP dentro do convidado — integrados em cada VM: o navegador, as automatizações, a infraestrutura, a delegação e, para sessões específicas, o quadro de tarefas e a Central.
• AppleScript — o dicionário Bromure AC Suite.

Ao longo deste capítulo, e na CLI, uma máquina chama-se espaço de trabalho (o seu nome no editor de definições e na linha de comandos). As sessões no sentido de conversas de agente são alcançadas através das rotas /agent-sessions; as rotas mais antigas /sessions e o termo session na CLI e no AppleScript referem-se à janela de uma máquina.

O plano de controlo: socket e API

Cada superfície fala HTTP com a aplicação em execução através de um de dois transportes:

A CLI nunca fala diretamente com uma VM. Cada subcomando é um cliente HTTP leve sobre o socket de controlo, pelo que os mesmos comandos funcionam localmente e — quando o socket passa em túnel por SSH — contra uma instância remota a partir de um cliente nativo. Se nenhum agente estiver em execução quando invoca um comando que precise de um, a CLI arranca automaticamente um agente em segundo plano sem janela (bromure-ac run --headless) e aguarda até 40 segundos que responda a /health. Os comandos só de leitura (vm ls, describe, trace …) não arrancam nada automaticamente; em vez disso, mostram No bromure-ac agent running..

Nota: O socket de controlo está sempre disponível enquanto a aplicação corre e é independente do interruptor Ativar servidor de automatização. Esse interruptor controla apenas o listener TCP na porta 9223. Não precisa de ativar a API de automatização para usar a CLI.

A linha de comandos bromure-cli

Pode chamar o binário pelo caminho completo dentro do pacote, mas o nome curto é mais prático. Escolha Bromure Agentic Coding › Instalar ferramenta de linha de comando… no menu da aplicação. O alerta Instalar a ferramenta de linha de comando “bromure-cli”? explica que cria uma ligação simbólica em /usr/local/bin/bromure-cli e precisa da sua palavra-passe de administrador uma vez; clique em Instalar (ou Cancelar). Em caso de sucesso, Ferramenta de linha de comando instalada indica-lhe que execute bromure-cli --help. A aplicação já nunca oferece isto ao arrancar — o item de menu é a única forma, e pode executá-lo novamente a qualquer momento (por exemplo, depois de mover a aplicação).

O mesmo binário comporta-se de forma diferente consoante o nome com que é chamado:

• Como bromure-cli, oculta os comandos internos da aplicação — gestão de imagens (init, info, reset e as ferramentas do pipeline de publicação), o servidor mcp e a predefinição run da interface gráfica — e expõe apenas os grupos destinados ao terminal (Workspaces, Tracing, Local inference, Enterprise features, remote). Um bromure-cli sozinho mostra a ajuda em vez de abrir a aplicação.
• Como bromure-ac (o binário dentro do pacote da aplicação), está tudo disponível e o subcomando predefinido é run, que abre a interface gráfica.

Os exemplos abaixo usam bromure-cli; use o caminho completo …/MacOS/bromure-ac para os comandos que só ele expõe.

Os comandos aceitam o id de um espaço de trabalho, um prefixo curto do id ou o seu nome sempre que aparece um argumento de espaço de trabalho. Os grupos de comandos vm e workspaces são aliases um do outro. O que é uma máquina, e como se relaciona com as sessões, é explicado em Máquinas.

A aplicação e o agente de segundo plano

Gestão de imagens

A imagem base é instalada uma única vez. Estes comandos só existem com o nome bromure-ac.

Nota: Se não existir imagem base, abrir a interface gráfica leva-o ao assistente de configuração inicial, que instala a imagem no local — consulte Instalação e primeira execução.

Controlo de espaços de trabalho e VM

Este é o grupo central. vm run foi deliberadamente modelado ao estilo do Docker: arranca um espaço de trabalho e entrega o seu terminal à sessão tmux bromure partilhada do convidado.

Alguns detalhes operacionais que vale a pena conhecer:

• Opções de vm run. --tool recebe um id de agente: claude, codex, grok, kimi ou omp. --auth é token, subscription, bedrock ou local. Um valor não reconhecido é um erro que lista os valores válidos, por exemplo Invalid --tool “gpt” — expected one of: claude | codex | grok | kimi | omp.; workspaces create verifica --tool e --auth da mesma forma. -v/--volume <hostdir> monta uma pasta do anfitrião em ~/<basename> no convidado (repetível, até 8). -d/--detach arranca a VM e regressa em vez de anexar. --rm elimina o espaço de trabalho e o seu disco quando a VM para. Desanexe-se de um tmux anexado com Ctrl-b d — a VM continua em execução.
• Os agentes vêm de Modelos. As opções de ferramenta e autenticação apenas inicializam um espaço de trabalho novo. O modelo e o fornecedor que cada agente usa de facto vêm de Preferências › Modelos e do painel Modelos do próprio espaço de trabalho — consulte Modelos e fornecedores.
• Sensível ao TTY. O comportamento predefinido ao estilo Docker, de entregar o terminal ao tmux, só se aplica num terminal real; invocações por pipe ou em scripts comportam-se como se tivesse passado -d.
• Valores de workspaces create. As cores são blue, red, green, orange, purple, pink, teal ou gray.
• Manter-em-branco na edição. workspaces edit exporta toda a configuração com os segredos em branco; um documento guardado de volta com um segredo em branco mantém o valor armazenado, pelo que uma ida-e-volta nunca pode apagar as suas chaves. Um buffer inalterado não guarda nada; JSON inválido aborta.
• Esperas do exec. vm exec aguarda até 10 segundos pelo agente de shell do convidado; um 502 significa que a VM pode não estar em execução ou que o nome não correspondeu. Os pedidos de aprovação que surgem durante uma sessão anexada são apresentados no seu terminal (ver Consentimento em terminais anexados), nunca dentro do convidado.

Verificar um disco a partir da linha de comandos

vm fsck é o gémeo scriptável de Executar fsck… no navegador ext4 e do botão Reparar disco que a aplicação mostra quando um arranque para devido a erros do sistema de ficheiros. Usa o verificador ext4 do próprio Bromure, por isso não é preciso 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

Recusa-se a correr enquanto o espaço de trabalho estiver em execução. A saída termina com um destes resumos: "Filesystem is clean.", "Filesystem repaired; it is now consistent." ou "Filesystem has errors this checker cannot repair.". Uma verificação sem --repair que encontre problemas sugere voltar a executar com --repair. O comando termina com o estado 4 enquanto houver erros. O âmbito e os limites do verificador estão descritos em Avançado.

Modelos, encaminhamento e Fusion

As definições de modelos e fornecedores são tratadas em Modelos e fornecedores e a síntese multimodelo em Fusion; os comandos da CLI são:

Inspeção de rastreios

Estes leem os rastos do proxy por espaço de trabalho. Não devolvem nada a menos que o espaço de trabalho tenha o rastreio ativado — consulte Definições de rastreio — e a história completa está em Rastreio e Auditoria.

Acesso remoto

A porta de entrada SSH opcional está desativada por predefinição e documentada por completo em Acesso remoto e clientes. Todas as operações passam pela aplicação em execução através do socket de controlo.

Inscrição empresarial

Equivalentes na CLI da folha Iniciar sessão em bromure.io…, para o aprovisionamento de dispositivos por script. Ver Empresa.

Comandos de integração e internos

A TUI remota (__remote-menu)

Quando o acesso remoto por SSH está ativo, cada início de sessão remoto é forçado (via ForceCommand) para uma interface de terminal ANSI feita à medida, em vez de uma shell — um menu em ecrã alternativo, de 256 cores, conduzido pelas setas e pelos algarismos, que funciona em qualquer PTY SSH (use ssh -t). Espelha a CLI sob a forma de menus:

• Espaços de trabalho — criação com um formulário de ecrã único (Name, Tool, Auth, API key, Memory, Color, Folders, Generate SSH, Full settings…, Create), ações por espaço de trabalho (Attach, New tab, Describe, Configure…, Fusion, Routing, Worktrees…, Reboot…, Suspend, Kill para os que estão em execução; Start, Describe, Configure…, Delete para os desligados) e uma vista de tabela em bruto. Configure… oferece os painéis do editor de definições como formulários de texto; o seu formulário Models é só de leitura (os fornecedores do servidor e se o espaço de trabalho os substitui), já que os modelos se escolhem na aplicação.
• Modelos — os modelos instalados e o catálogo de transferências; selecionar um modelo não instalado oferece-se para fazer model pull do mesmo em linha com progresso ao vivo.
• Rastreio — Resumo / Anfitriões / Fugas / Recentes / Limpar.

Enquanto está anexado ao tmux de um espaço de trabalho, uma combinação de teclas mágica (por predefinição Ctrl-], mostrada no cabeçalho) faz surgir uma sobreposição de controlo desenhada pelo anfitrião: uma árvore de separadores, New tab, Worktrees…, Fusion, Routing, Edit settings…, Reboot…, Suspend, Disconnect. O convidado nunca vê a tecla de ativação — substitua-a com o ficheiro remote/overlay-key ou $BROMURE_OVERLAY_KEY. Ctrl-b d desliga do tmux e regressa ao menu. A TUI remota trabalha sobre as máquinas e os seus terminais; as sessões de agente, as salas e a Central alcançam-se antes a partir do cliente nativo. A história completa do acesso remoto está em Acesso remoto e clientes.

A API de automatização em loopback

O plano de controlo também pode ser exposto em JSON sobre HTTP por TCP, para scripts em qualquer linguagem. Está desativado por predefinição.

Como ativá-la

Abra Preferências… › Automatização (⌘,) — o painel API de automatização e servidor MCP.

1. Ative Ativar servidor de automatização. Quando está ativado, o painel indica A escutar em 127.0.0.1:9223; desativá-lo para o servidor imediatamente.
2. Opcionalmente, defina a Porta (com a legenda (padrão: 9223)) e o Endereço de bind (por predefinição 127.0.0.1). A porta e o endereço de bind têm efeito no próximo arranque do servidor — desligue e volte a ligar o interruptor para os aplicar já.

Também pode acionar o interruptor sem a GUI:

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

Aviso: Definir o Endereço de bind para algo diferente de 127.0.0.1 expõe a API — e o servidor MCP que a suporta — à rede, e o painel avisa O bind fora do loopback expõe a API à rede. O servidor MCP não tem autenticação. Não existe autenticação no recetor TCP para além da fronteira de loopback e do controlo BROMURE_DEBUG_CLAUDE abaixo. Deixe o endereço de bind em loopback a menos que tenha uma razão específica e de confiança para não o fazer.

Modelo de autenticação

O recetor TCP e o socket de controlo servem as mesmas rotas, mas com acessos diferentes:

Por outras palavras: o socket de controlo é o caminho de acesso total, exclusivo do proprietário; a API TCP abre o subconjunto seguro em loopback e coloca tudo o resto atrás do indicador de depuração. Os segmentos de caminho são codificados em percentagem uma única vez (para que nomes de espaços de trabalho com espaços funcionem).

Endpoints para scripting

As rotas mais úteis:

Como o caminho do socket de controlo contém espaços, capture-o primeiro numa variável:

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"}'

O subconjunto seguro funciona pela API TCP depois de a ativar — por exemplo, listar os espaços de trabalho e abrir a janela de uma máquina não precisa do indicador de depuração:

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

Nota: As rotas do plano de controlo são uma superfície de integração partilhada com o cliente nativo, não uma API pública versionada; a forma dos pedidos e respostas pode mudar entre versões. Os comandos da CLI acima são a forma estável de automatizar o Bromure com scripts. As rotas só de depuração, as variáveis de ambiente e as localizações de ficheiros estão catalogadas no Apêndice.

O servidor MCP do AC (bromure-ac mcp)

bromure-ac mcp executa um servidor MCP JSON-RPC em stdio (nome do servidor bromure-ac) que permite a uma ferramenta de IA no seu Mac gerir a aplicação. Envolve a API HTTP de automatização e o AppleScript, por isso ative primeiro o servidor de automatização — as ferramentas de listagem e de janelas chamam a API HTTP em --api-url (por predefinição http://127.0.0.1:9223). Não está disponível com o nome bromure-cli.

As ferramentas que expõe:

• bromure_ac_list_profiles, bromure_ac_list_sessions
• bromure_ac_open_session (abre a janela de um espaço de trabalho; aguarda até 30 segundos), bromure_ac_close_session
• bromure_ac_get_profile, bromure_ac_set_profile (substituição JSON atómica, id preservado)
• bromure_ac_get_profile_setting, bromure_ac_set_profile_setting

Com --debug (e BROMURE_DEBUG_CLAUDE definido na aplicação) acrescenta bromure_ac_app_state, bromure_ac_vm_exec, bromure_ac_vm_read_file e bromure_ac_vm_write_file.

Para o ligar ao Claude Code, acrescente o seguinte a ~/.config/claude-code/.mcp.json (ou ao equivalente do seu cliente). É exatamente o excerto que a secção Configuração do cliente MCP do painel Automatização mostra:

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

Nota: As ferramentas de perfil get/set recorrem ao osascript (AppleScript contra a aplicação em execução), pelo que a aplicação GUI tem de estar em execução e o macOS pode pedir uma vez a permissão de Automatização. O JSON de perfil viaja com os segredos em branco a menos que BROMURE_DEBUG_CLAUDE esteja definido.

Servidores MCP dentro das VMs

Independentemente do servidor MCP do AC, o Bromure dá aos agentes dentro de cada VM um conjunto de servidores MCP integrados — sem qualquer configuração. Cada um é um pequeno adaptador Python stdio colocado só de leitura no convidado em /mnt/bromure-meta/; o adaptador liga ao anfitrião por vsock e volta a ligar indefinidamente em caso de quebra, pelo que o agente nunca perde as suas ferramentas. O anfitrião serve as ferramentas e cada chamada é verificada lá: um agente só pode ver e atuar sobre aquilo a que a sua própria máquina e sessão têm direito.

Os servidores browser, automations, infrastructure e delegation são escritos na configuração MCP de cada agente, ao lado dos servidores que adiciona no painel MCP da máquina (Definições de MCP). Os servidores task board e switchboard são passados apenas às execuções que precisam deles.

O servidor browser

O servidor browser conduz o Chromium incorporado da máquina, que corre na sua própria VM descartável. As suas 23 ferramentas cobrem a navegação e a inspeção — browser_navigate, browser_new_tab, browser_list_tabs, browser_activate_tab, browser_close_tab, browser_back, browser_forward, browser_reload, browser_screenshot (com opção de página inteira), 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 e browser_pick_element (um seletor interativo de elementos de 60 segundos).

Uma chamada de ferramenta com o navegador fechado abre-o e aguarda o arranque a frio. Como o navegador é uma VM separada, as instruções do servidor dizem aos agentes que alcancem um servidor de desenvolvimento na sua máquina pelo IP LAN da máquina (hostname -I), nunca por localhost. A história completa está em O Navegador Incorporado.

Nota: Num cliente nativo, o fluxo browser-MCP dos agentes pode seguir pela ligação SSH, para que um agente remoto conduza o painel de navegador que vê localmente. Consulte Acesso remoto e clientes.

OAuth para os servidores MCP que adiciona

Os servidores MCP HTTP que adiciona no editor podem autenticar-se através do broker OAuth do lado do anfitrião: este realiza a descoberta RFC 8414 e o registo dinâmico de cliente RFC 7591 (como Bromure AC), executa um fluxo de código de autorização PKCE no navegador do seu sistema e serve o callback num recetor de loopback (portas 28500–28599). A página de sucesso indica Autorizado — Pode fechar este separador e regressar ao Bromure AC. Todo o fluxo corre no anfitrião, pelo que a VM nunca vê credenciais OAuth reais.

AppleScript (Bromure AC Suite)

Um dicionário de scripting, o Bromure AC Suite, é outra superfície de automatização — útil para orquestração e para ferramentas de captura de ecrã que precisam de IDs de janela. Aponte para application "Bromure Agentic Coding" a partir do Editor de Scripts ou do osascript. Abrange:

• Perfis — list profiles, create ac profile <name> [color <c>] (devolve um UUID), delete ac profile <name|uuid>, e ida e volta do documento completo via get profile json / set profile json (o perfil inteiro; id preservado; segredos guardados reintegrados nos campos em branco).
• Definições por campo — get profile setting … key … / set profile setting … key … to value ….
• Janelas do editor — open profile manager, open ac profile editor, close ac profile editor, select editor category <key> e get editor window id / get main window id (um CGWindowID para screencapture -l).
• Janelas de máquina — open ac session, close ac session, list ac sessions.
• Estado e definições da aplicação — get app state (JSON), mais get ac app setting / set ac app setting para as chaves automation.enabled, automation.port, automation.bindAddress, remoteAccess.enabled, remoteAccess.port, remoteAccess.bindAddress, managed.serverURL e managed.acIngestURL. Definir automation.enabled aciona o servidor HTTP em tempo real.

Por exemplo, para abrir a janela de uma máquina:

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

Nota: O JSON de perfil viaja com os segredos removidos a menos que BROMURE_DEBUG_CLAUDE esteja definido. Definir apiKey como uma cadeia vazia via set profile setting limpa a chave em vez de a manter — ao contrário do comportamento de manter-em-branco das pontes de ida-e-volta de JSON. A mudança de idioma não é deliberadamente programável; em vez disso, reinicie a aplicação com, por exemplo, -AppleLanguages "(fr)".

Automatizações agendadas

Uma automatização agendada é uma execução de agente recorrente e sem supervisão, associada a uma máquina. As automatizações são criadas e geridas a partir do quadro de automatizações (⇧⌘A, ou a secção Automatizações da barra lateral), e os agentes podem gerir as automatizações da própria máquina através do servidor MCP automations acima. A funcionalidade completa — acionadores, agendamentos, encadeamento, o ecrã de injeção obrigatório, o histórico de execuções — está documentada em Automatizações. Esta secção aborda a superfície do plano de controlo: conduzir automatizações através da API, responder aos pedidos de decisão que um arranque sem supervisão pode levantar e o funcionamento do consentimento num terminal anexado.

Controlar automatizações através da API

Responder a pedidos pendentes

Algumas decisões de ciclo de vida — a oferta de atualização da imagem base, um disco que falha a verificação no arranque, um alerta de comprometimento, uma limpeza por comprometimento — aparecem normalmente como um alerta local. Quando não está ninguém ao Mac para responder (um agente sem interface, ou um arranque pedido por um cliente nativo remoto), ficam em fila: surgem em GET /state sob pendingPrompts (cada um com id, profileID, title, message e rótulos de botões) e respondem-se com 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"}'

Passe um dos próprios rótulos de botão do pedido como choice. Se nenhum cliente responder antes do tempo limite do pedido, este resolve-se para a sua alternativa segura — nunca a opção destrutiva (um alerta de comprometimento, por exemplo, recorre a desligar a VM). Se não houver nenhum cliente ligado, recorre à alternativa de imediato. Um cliente nativo mostra estes pedidos como alertas normais.

Nota: As automatizações, as delegações e os outros arranques sem supervisão nunca ficam à espera de um pedido. Um arranque que precisaria de uma resposta sua — uma máquina marcada como comprometida, ou um modelo local ainda a ser transferido — é recusado, com um motivo claro no histórico da execução ("The workspace is marked compromised — start it yourself to confirm the wipe."). Uma máquina suspensa cujo estado guardado não possa ser reposto arranca do zero.

Consentimento em terminais anexados

Enquanto um terminal está anexado de forma interativa a uma máquina — através de vm exec -it, vm attach ou de um attach SSH — os pedidos de aprovação do lado do anfitrião (uso de credenciais e semelhantes) são mostrados no seu terminal, não dentro do convidado. O pedido diz 🔒 Bromure — approval required com escolhas numeradas e Choice [1-N] (Enter or timeout = deny). Enter, tempo esgotado, EOF ou desanexar significam todos recusa, pelo que um convidado comprometido nunca consegue forjar uma aprovação. O tmux do convidado é redesenhado a seguir.

Endpoints de depuração (BROMURE_DEBUG_CLAUDE)

Abrir a aplicação com BROMURE_DEBUG_CLAUDE definido levanta a barreira de depuração da API de automatização TCP, pelo que as rotas da linha do meio da tabela de autenticação também funcionam por TCP, incluindo estas rotas de depuração (sempre disponíveis no socket de controlo, salvo indicação em contrário):

• GET /debug/ui-shot?path=…&which=… — a aplicação desenha a sua própria janela num PNG (não é preciso a autorização de Gravação de ecrã) e devolve um despejo das molduras das subvistas; a saída predefinida é /tmp/bromure-ui-shot.png.
• POST /debug/editor — controla o editor de definições para a ferramenta de captura de ecrã.
• POST /detect/prompt-injection — executa os detetores reais e devolve o seu veredicto (esta rota requer a flag de depuração mesmo no socket de controlo).

O indicador também permite que os segredos passem tal como estão pelas pontes de JSON de perfil do AppleScript e do MCP, e é exigido pelas ferramentas de VM de bromure-ac mcp --debug. GET /health indica debugEnabled para que saiba em que modo está a aplicação.

Aviso: BROMURE_DEBUG_CLAUDE remove a barreira de segurança que normalmente mantém exec, o controlo das VMs e os segredos de perfil em bruto fora da API TCP de loopback. Execute a aplicação com ele apenas numa máquina que controla, e nunca o combine com um endereço de bind que não seja de loopback — isso exporia acesso total à shell das VMs, segredos não ocultados e capturas de janelas a qualquer pessoa que consiga chegar à porta. É distinto de BROMURE_AC_DEBUG (registo de eventos em stderr) e de BROMURE_CLI_DEBUG (diagnóstico do socket da CLI), que são interruptores de registo inofensivos.