CLI, Automatização e MCP

Tudo o que pode fazer na aplicação, também pode fazer sem a janela. O mesmo binário que aloja a GUI — bromure-cli, dentro de Bromure Agentic Coding.app/Contents/MacOS/ — é uma CLI multicomando completa, um plano de controlo HTTP, dois servidores MCP, um dicionário AppleScript e um agendador. Este capítulo é a referência para todos eles.

Quatro superfícies de automatização assentam sobre um único plano de controlo:

• A linha de comandos bromure-cli — uma CLI ao estilo Docker/kubectl para criar espaços de trabalho, arrancar VMs, anexar terminais, executar comandos e ler rastreios.
• A API de automatização — o mesmo plano de controlo exposto como JSON sobre HTTP na interface de loopback, para criar scripts a partir de qualquer linguagem.
• Servidores MCP — um servidor stdio que permite a um agente de IA (Claude Code, Claude Desktop) gerir a aplicação, e um servidor browser que permite a um agente controlar o Chromium incorporado do seu espaço de trabalho.
• AppleScript — o dicionário Bromure AC Suite, para scripting no macOS e ferramentas de captura de ecrã.

As automatizações agendadas — execuções de agente recorrentes e não assistidas — assentam no mesmo plano de controlo e são abordadas no final do capítulo.

O plano de controlo: socket e API

Todas estas superfícies acabam por comunicar via HTTP com a aplicação em execução através de um de dois transportes:

A CLI nunca comunica 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 é encaminhado por túnel sobre SSH — contra uma instância remota a partir de um cliente nativo. Se nenhum agente estiver em execução quando invoca um comando que precisa de um, a CLI arranca automaticamente um agente de segundo plano sem janela (bromure-cli run --headless) e aguarda até 40 segundos que este responda a /health. Os comandos só de leitura (vm ls, describe, trace …) não arrancam automaticamente; em vez disso, imprimem No bromure-cli agent running.

Nota: O socket de controlo está sempre disponível enquanto a aplicação estiver em execução e é independente do interruptor Ativar servidor de automatização. Esse interruptor governa apenas o recetor TCP na porta 9223. Não precisa de ativar a API de automatização para usar a CLI bromure-cli.

A linha de comandos bromure-cli

Pode invocar o binário pelo seu caminho completo no pacote, mas a aplicação oferece uma instalação única de um atalho curto. No arranque, apresenta um alerta — Instalar a ferramenta de linha de comandos "bromure-cli"? — com os botões Instalar / Agora não / Não perguntar novamente. Escolher Instalar cria um symlink de /usr/local/bin/bromure-cli para o binário da aplicação (um pedido de administrador). Sob o nome bromure-cli, o binário oculta os comandos internos da aplicação — gestão de imagens, o servidor mcp e a predefinição run da GUI — e expõe apenas os grupos voltados para o terminal (Espaços de trabalho, Rastreio, Inferência local, Empresa, remote); um bromure-cli sozinho imprime a ajuda em vez de iniciar a aplicação. Invocado como bromure-cli, tudo fica disponível e o subcomando predefinido é run (a GUI). Os exemplos abaixo usam bromure-cli; substitua livremente por bromure-cli para os comandos que este expõe.

Os comandos aceitam um id de espaço de trabalho, um prefixo de id curto ou o seu nome sempre que é mostrado um argumento de espaço de trabalho. Os espaços de trabalho são as configurações persistentes de VM descritas em Espaços de trabalho; os grupos de comandos vm e workspaces são aliases um do outro.

A aplicação e o agente de segundo plano

Gestão de imagens

A imagem base é instalada uma vez. Estes comandos estão ocultos sob o alias bromure-cli.

Nota: Não existe um subcomando setup — esse pertence ao produto irmão Bromure (navegador). O comando de instalação da imagem do Agentic Coding é init. Se não existir nenhuma imagem base, iniciar a GUI encaminha-o antes para o fluxo de configuração dentro da aplicaçã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:

• Flags de vm run. --tool é claude, codex ou grok; --auth é token, subscription ou bedrock. -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 — isso deixa a VM em execução.
• Consciente do TTY. A predefinição ao estilo Docker de entregar o terminal ao tmux aplica-se apenas num terminal real; as invocações canalizadas ou por script comportam-se silenciosamente como se tivesse passado -d.
• Autenticação em workspaces create. Para create, --auth também aceita local. 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.

Modelos, encaminhamento e Fusion

A inferência local é abordada em profundidade em Modelos locais e a síntese multimodelo em Fusion; os interruptores da CLI são:

fusion também aceita on/engage e off/disengage como sinónimos.

Inspeção de rastreios

Estes leem os rastreios de sessão MITM por espaço de trabalho. Não devolvem nada a menos que o espaço de trabalho tenha o rastreio ativado — ver Definições de rastreio — e toda a história está em Rastreio.

Acesso remoto

A porta de entrada SSH opcional está desativada por predefinição e totalmente documentada em Acesso remoto. 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 Inscrever 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 SSH está ativado, cada início de sessão remoto é forçado (via ForceCommand) para uma interface de terminal ANSI feita à mão em vez de uma shell — uma minishell de ecrã alternativo e 256 cores, controlada por teclas de setas e dígitos, que funciona sobre qualquer PTY de SSH (use ssh -t). Espelha toda a CLI em forma de menus:

• Espaços de trabalho — criar com um formulário de ecrã único (Nome, Ferramenta, Autenticação, Chave de API, Memória, Cor, Pastas, Gerar SSH, Definições completas…, Criar), ações por espaço de trabalho (Anexar, Novo separador, Descrever, Configurar…, Fusion, Encaminhamento, Worktrees…, Reiniciar…, Suspender, Terminar para espaços de trabalho em execução; Iniciar, Descrever, Configurar…, Eliminar para os desligados) e uma vista de tabela em bruto. Configurar… reproduz nativamente todos os painéis do editor da GUI.
• 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, um acorde de teclas mágico (predefinição Ctrl-], mostrado no banner) faz surgir uma sobreposição do controlador desenhada pelo anfitrião: uma árvore de separadores, Novo separador, Worktrees…, Fusion, Encaminhamento, Editar definições…, Reiniciar…, Suspender, Desligar. 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-se do tmux e regressa ao menu. Toda a história do acesso remoto e do cliente nativo, incluindo a sobreposição e a configuração da ligação, está em Acesso remoto.

A API de automatização em loopback

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

Como ativá-la

Abra Bromure → 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 (o campo tem a legenda (predefinição: 9223)) e o Endereço de bind (predefinição 127.0.0.1). A porta e o endereço de bind entram em vigor na próxima vez que o servidor arranca — desative e reative o interruptor para os aplicar agora.

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, apenas para o proprietário; a API TCP abre o subconjunto seguro em loopback e restringe as rotas poderosas por trás da flag de depuração. Os segmentos de caminho são codificados em percentagem uma única vez (para que os nomes de espaços de trabalho com espaços funcionem) e são aceites corpos de pedido até 8 MB.

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 (control socket — no debug flag needed here)
curl --unix-socket "$SOCK" http://localhost/vms

# Boot a workspace by name
curl --unix-socket "$SOCK" -X POST http://localhost/vms \
  -d '{"profile":"Claude Dev"}'

# 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 sobre a API TCP depois de a ter ativado — por exemplo, listar e abrir sessões não precisa de flag de depuração:

# List sessions
curl http://127.0.0.1:9223/sessions

# Open a session for a workspace
curl -X POST http://127.0.0.1:9223/sessions -d '{"profile":"Claude Dev"}'

Nota: GET /vms (listar VMs em execução) está disponível através da API de automatização TCP sem qualquer flag de depuração. As rotas de mutação de VM — POST /vms (arrancar uma VM) e POST /vms/<id>/exec — requerem BROMURE_DEBUG_CLAUDE sobre TCP; controle-as através do socket de controlo (como acima) quando não quiser executar a aplicação em modo de depuração. Toda a superfície de endpoints — incluindo as ações de worktree e separador, /trace, /remote e as rotas de espelho do cliente nativo — está resumida no Apêndice.

O servidor MCP do AC (bromure-cli mcp)

bromure-cli mcp executa um servidor MCP JSON-RPC em stdio (nome do servidor bromure-cli) que permite a uma ferramenta de IA 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 sessão e de listagem de perfis chamam a API HTTP em --api-url (predefinição http://127.0.0.1:9223).

As ferramentas que expõe:

• bromure_ac_list_profiles, bromure_ac_list_sessions
• bromure_ac_open_session (aguarda até 30 segundos pela janela), 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 (as chaves incluem name, color, comments, tool, authMode, apiKey, closeAction, memoryGB, folderPathsCount, mcpServerCount, keyboardLayoutOverride, keyRepeatDelayMs, keyRepeatRateHz)

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, adicione o seguinte a ~/.config/claude-code/.mcp.json (ou o equivalente do seu cliente). Este é o excerto exato que a secção Configuração do cliente MCP do painel de Preferências oferece para copiar:

{
  "mcpServers": {
    "bromure-cli": {
      "command": "/Applications/Bromure Agentic Coding.app/Contents/MacOS/bromure-cli",
      "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.

O servidor MCP do navegador no espaço de trabalho

Separadamente do servidor MCP do AC, cada agente de espaço de trabalho recebe automaticamente um servidor MCP browser — sem configuração. Este controla o Chromium incorporado do espaço de trabalho, que corre na sua própria VM descartável. O painel MCP do editor do espaço de trabalho descreve os servidores MCP do próprio espaço de trabalho; o servidor de navegador integrado está sempre presente por cima de tudo o que ali adicionar.

O servidor expõe 23 ferramentas para navegação e 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 uma opção 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 e browser_pick_element (um seletor de elementos interativo de 60 segundos).

O transporte é um shim stdio em Python gerado, bromure-browser-mcp.py, colocado apenas para leitura no convidado em /mnt/bromure-meta/. Liga-se ao anfitrião pela porta 5830 de vsock e religa-se indefinidamente em caso de quedas, para que o cliente MCP nunca retire as ferramentas. Uma chamada de ferramenta contra um navegador fechado abre-o e aguarda o arranque a frio. Como o navegador é uma VM separada, as instruções do servidor avisam os agentes para alcançarem um servidor de desenvolvimento do espaço de trabalho através do IP de LAN do espaço de trabalho (hostname -I), nunca localhost.

Nota: Num cliente nativo, o fluxo browser-MCP do agente pode ser encaminhado por um canal SSH para que um agente remoto controle o painel do navegador que vê localmente. Está ativo um relé de cada vez. Ver Acesso remoto.

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, é uma terceira superfície de automatização — útil para orquestração e para ferramentas de captura de ecrã que necessitam de IDs de janela. Aponte para application "Bromure Agentic Coding" a partir do Script Editor 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 de documento completo via get profile json / set profile json (todo o perfil Codable; id preservado; segredos armazenados fundidos sob 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).
• Sessões — 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 uma sessão:

osascript -e 'tell application "Bromure Agentic Coding" to open ac session "Claude Dev"'

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 não assistida vinculada a um espaço de trabalho: quando dispara, cria uma nova worktree do git e inicia aí o agente escolhido com o seu prompt, e a execução aparece como um separador de worktree normal. 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 toda a funcionalidade — gatilhos, sintaxe de agendamento, encadeamento, o ecrã de injeção obrigatório, o histórico de execuções e onde as automatizações persistem — está documentada em Automatizações. Esta secção abrange apenas a superfície do plano de controlo que a funcionalidade expõe: controlar automatizações através da API, responder aos pedidos de decisão que uma execução não assistida pode levantar e como funciona o consentimento sobre um terminal anexado.

Controlar automatizações através da API

Toda a funcionalidade é espelhada no socket de controlo para o cliente nativo:

Responder a pedidos pendentes

Algumas decisões de ciclo de vida — uma atualização de armazenamento, uma reposição por desvio, uma limpeza por comprometimento — normalmente aparecem como um alerta local. Quando são desencadeadas por um cliente nativo remoto, ficam em fila em vez de serem mostradas no anfitrião: surgem em GET /state sob pendingPrompts (cada uma com um id, profileID, title, message e etiquetas de botão) e são respondidas 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":"Upgrade"}'

Passe uma das etiquetas de botão do próprio pedido como choice. Se nenhum cliente responder dentro de 180 segundos, o pedido resolve-se para o seu recurso seguro (cancelar / agora não — nunca a opção destrutiva); se nenhum cliente tiver consultado /state dentro de 10 segundos, recorre imediatamente ao mesmo. Estas rotas são apenas de socket de controlo. Um cliente nativo apresenta estes pedidos como alertas locais normais.

Consentimento em terminais anexados

Enquanto um terminal está interativamente anexado a uma sessão — através de vm exec -it, vm attach ou de uma anexação SSH — os pedidos de aprovação do lado do anfitrião (uso de credenciais, e semelhantes) são apresentados no seu terminal, não dentro do convidado. O pedido indica 🔒 Bromure — aprovação necessária com opções numeradas e Escolha [1-N] (Enter ou tempo limite = negar). Enter, tempo limite, EOF ou desanexar significam todos negar, pelo que um convidado comprometido nunca pode forjar uma aprovação. O tmux do convidado é redesenhado em seguida.

Endpoints de depuração (BROMURE_DEBUG_CLAUDE)

Iniciar a aplicação com BROMURE_DEBUG_CLAUDE definido desbloqueia rotas adicionais na API de automatização TCP e remove o controlo de depuração no controlo de VM:

• POST /sessions/<id>/exec e as rotas de controlo /vms/… sem o socket de controlo.
• GET /app/state.
• GET /debug/ui-shot?path=…&which=unified|picker|editor — a aplicação renderiza a sua própria janela para um PNG (sem necessidade de permissão de Gravação de Ecrã) e devolve um despejo de molduras de 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).

A flag também permite que os segredos viajem literalmente através das pontes de JSON de perfil do AppleScript e do MCP e é exigida pelas ferramentas de VM de bromure-cli mcp --debug. GET /health reporta debugEnabled para que possa saber em que modo a aplicação se encontra.

Aviso: BROMURE_DEBUG_CLAUDE remove o controlo de segurança que normalmente mantém exec, o controlo de VM e os segredos de perfil em bruto fora da API TCP de loopback. Execute a aplicação com ele apenas numa máquina que controle e nunca o combine com um endereço de bind fora do loopback — fazê-lo exporia o acesso total à shell da VM, os segredos não redigidos e as capturas de janela a qualquer pessoa que consiga alcançar a porta. É distinto de BROMURE_AC_DEBUG (registo de eventos em stderr) e de BROMURE_CLI_DEBUG (diagnósticos de socket da CLI), que são interruptores de registo inofensivos. Os endpoints de depuração, todas as variáveis de ambiente e cada localização de ficheiro abordada neste capítulo estão catalogados no Apêndice.