Conceitos e Arquitetura

O Bromure Agentic Coding executa agentes de programação com IA dentro de máquinas Linux virtualizadas por hardware no seu Mac, e aplica cada controlo de segurança num ponto que o agente não consegue contornar. Este capítulo define as palavras em que o resto do manual assenta — sessão, máquina, sala, ramo, anfitrião e convidado, a fronteira de transmissão — e explica como as peças encaixam. Se ler só um capítulo além do Início rápido, leia este.

Sessões, máquinas, salas e ramos

Quatro objetos compõem quase tudo o que faz na aplicação.

Sessão

Uma sessão é uma conversa com um agente, numa pasta, numa máquina. Inicia-a a partir do ecrã de nova sessão; tem um título (o agente define um a partir da sua primeira mensagem, e pode mudar-lhe o nome), um agente (Claude Code, Codex, Grok, Kimi Code ou Oh My Pi), uma máquina e uma pasta de trabalho dentro dessa máquina. As sessões são o que a barra lateral lista e o que o chat mostra.

Dentro da máquina, uma sessão é um agente a correr no seu próprio separador de terminal. Raramente precisa de ver esse separador, mas pode: a pílula Linux na barra de ferramentas (⌥⌘U) ou Abrir no terminal Linux no menu da sessão muda para ele, e a pílula (que passa a dizer Sessão) volta atrás.

Uma sessão sobrevive ao processo do agente. Quando o agente termina, ou a sua máquina se desliga, a sessão fica na barra lateral com a sua conversa, e a sua próxima mensagem volta a iniciar o agente na mesma conversa. Consulte O início das sessões.

Máquina

Uma máquina é uma VM Linux isolada, com as suas definições e o seu armazenamento duradouro. A janela principal diz máquina; o editor de definições, vários menus (Novo espaço de trabalho…, Espaços de trabalho) e a linha de comandos dizem espaço de trabalho (internamente, e em nomes de ficheiros como profile.json, um perfil). As três palavras significam o mesmo.

Uma máquina define as credenciais, as pastas partilhadas, o ambiente, os servidores MCP, as salvaguardas, as substituições de modelos, o aspeto e o tamanho da VM que se aplicam a todas as sessões nela — tudo o que edita no editor de definições. Todos os agentes estão disponíveis em todas as máquinas. Uma máquina existe esteja ou não em execução, e muitas sessões podem correr na mesma máquina ao mesmo tempo, cada uma na sua pasta e no seu separador de terminal.

A prática habitual é uma máquina por projeto ou por fronteira de credenciais: as sessões na mesma máquina partilham o seu disco, as suas credenciais e a sua identidade de rede. As máquinas estão listadas em Máquinas virtuais na barra lateral; consulte Máquinas.

Uma execução de máquina é um período contínuo durante o qual a VM de uma máquina está ligada: começa quando a máquina arranca ou é retomada, e termina quando se desliga ou é suspensa. Algum estado pertence à execução e não à máquina: as aprovações de credenciais que concede ficam em memória e são revogadas quando a execução termina, e as partilhas de configuração por arranque são reconstruídas a cada arranque.

Sala

Uma sala agrupa sessões que trabalham na mesma coisa. Abrir uma sala mostra as suas sessões lado a lado como uma grelha de chats ao vivo, e um compositor que pode enviar para qualquer uma delas ou para todas de uma vez. Uma sala pode ter a sua própria Central, uma sessão que acompanha as sessões dessa sala e só essas. As sessões de uma sala podem correr em máquinas diferentes. Consulte Salas.

Sessão de ramo

Uma sessão de ramo é uma sessão iniciada a partir de outra sessão no seu próprio ramo git, num checkout separado (uma worktree git) do mesmo repositório na mesma máquina. Trabalha sem tocar na pasta da sessão original e, quando estiver satisfeito com o resultado, revê-o e integra-o de volta. Consulte Ramos e revisão.

Sessões que outras sessões iniciam

Dois tipos de sessão são iniciados por outros, e não por si:

• Delegados. Um agente pode entregar uma tarefa a uma nova sessão filha — no seu próprio ramo, ou noutra máquina — e esperar pelo resultado. A filha aparece listada por baixo da sessão que a iniciou. Um agente também pode enviar um pedido a uma sessão existente pela sua @alcunha. Consulte Agentes a trabalhar em conjunto.
• A Central. Uma sessão Claude Code que acompanha todas as outras sessões. Aparece na barra lateral assim que há duas ou mais sessões em curso, trabalha na pasta ~/.bromure/switchboard na última máquina que usou, e pode ler, responder e iniciar sessões por si, com regras rigorosas. A Central própria de uma sala trabalha em ~/.bromure/rooms/<room> e só vê essa sala. Consulte Central e mensagens.

As execuções de automações e as tarefas de código também correm como sessões, arquivadas quando terminam; consulte Automatizações e Tarefas de código.

Estados das sessões

A barra lateral agrupa as sessões pelo que precisam de si, nunca pela máquina em que correm:

Há mais dois sítios com sessões fora destes grupos:

• Arquivadas é uma secção recolhida no fundo da lista de sessões para as conversas que arrumou. Uma sessão arquivada continua legível, e uma mensagem basta para a trazer de volta. As sessões concluídas há mais de três dias são arquivadas automaticamente, exceto as sessões numa sala e as Centrais. Os delegados, as tarefas de código e as execuções de automações são arquivados assim que terminam.
• Uma sessão cuja máquina ou pasta já não existe aparece esbatida, como «Máquina removida» ou «Pasta removida». As sessões de máquinas eliminadas são reunidas numa linha no fim da lista, com um botão Eliminar.

O anfitrião guarda uma cópia da conversa de cada sessão (em ~/Library/Application Support/BromureAC/transcripts/), atualizada enquanto o agente corre, para que uma sessão em pausa, concluída ou arquivada possa ser lida sem arrancar a sua máquina.

O anfitrião e o convidado

Tudo no Bromure Agentic Coding vive de um dos lados de uma linha rígida:

• O anfitrião é o seu Mac — macOS 14 ou posterior em Apple Silicon — e a aplicação Bromure Agentic Coding que nele corre. O anfitrião guarda tudo o que é sensível: as suas credenciais reais (encriptadas com uma chave-mestra no Keychain do macOS), os seus inícios de sessão, o proxy MITM que fala com a Internet em nome do agente, a chave privada da CA raiz do Bromure, o rastreio e a Linha do tempo de segurança, e as janelas, chats e terminais da aplicação. O chat e os terminais onde escreve são desenhados no anfitrião, não dentro da VM.
• O convidado é a VM Linux onde o agente realmente corre — Claude Code, Codex, Grok, Kimi Code, Oh My Pi ou simples ferramentas da shell, com tudo o que instalam e tocam: repositórios clonados, caches de pacotes, contentores Docker, virtualenvs. O convidado é tratado como não fidedigno por conceção. Não guarda segredos reais, apenas credenciais falsas intencionalmente inválidas, e o seu tráfego web de saída passa pelo proxy do anfitrião.

Os dois lados comunicam por dois canais estreitos: vsock (sockets virtio, um canal anfitrião–convidado que não precisa de rede) para controlo, terminais, servidores MCP e o caminho do proxy; e uma rede virtual privada para o tráfego IP comum. Ambos são descritos abaixo.

É esta separação que torna concreta a garantia de segurança: um agente vítima de injeção de prompt ou mal comportado pode fazer o que quiser dentro do convidado, mas não consegue ler uma chave de API real, assinar com um segredo AWS real nem extrair uma chave privada SSH — nada disso existe do seu lado da linha.

Arquitetura em resumo

Leia o diagrama de baixo para cima: o agente trabalha na VM da máquina; o seu HTTPS sai por vsock para o proxy do anfitrião, que é o único sítio onde as credenciais falsas se tornam reais; a aplicação liga-se aos terminais da VM por pontes vsock separadas; e uma VM de navegador descartável opcional partilha a mesma rede privada, para poder carregar os servidores de desenvolvimento do agente.

Além das máquinas e das VMs de navegador, a aplicação pode executar três tipos de VM geridas próprias, todas na mesma rede privada: nós de cluster Kubernetes e um registo de contentores (consulte Clusters Kubernetes e registos), e o conector de mensagens que liga a Central ao Signal, WhatsApp ou Slack (consulte Central e mensagens). Aparecem em Máquinas virtuais na barra lateral, mas não são máquinas: nenhum agente corre nelas.

A VM da máquina

A VM de cada máquina é um convidado Ubuntu 24.04 a correr sob a Virtualization.framework da Apple, que exige Apple Silicon e só suporta convidados ARM64. Arranca com 4 vCPUs e a quantidade de memória definida no painel Recursos da máquina, a partir de dois discos virtuais:

• disk.img — o disco de sistema. No primeiro arranque da máquina, é criado como um clone APFS copy-on-write da imagem base Ubuntu partilhada e assinada (consulte Instalação e primeira execução): o clone aparece de imediato e não usa espaço novo em disco até o convidado escrever nele. Os arranques seguintes reutilizam o mesmo clone, por isso os pacotes que instala com apt install, as imagens Docker que obtém e outras alterações ao nível do sistema sobrevivem.
• home.img — um disco ext4 privado que contém /home/ubuntu, ligado como segundo disco. Tem 16 GiB por predefinição, mas só usa espaço à medida que se enche, e encolhe no anfitrião quando se apagam ficheiros no convidado. A pasta pessoal sobrevive a um Redefinir disco, e é por isso que os seus repositórios, dotfiles, histórico da shell e a pasta de cada sessão sobrevivem a uma redefinição do disco de sistema.

O convidado também monta pequenas partilhas por arranque: uma partilha meta só de leitura com a configuração desse arranque (ficheiros de ambiente com credenciais falsas, definições do proxy, o certificado da CA do Bromure, agentes do convidado, configuração MCP) e uma caixa de saída com escrita que o convidado usa para reportar ao anfitrião (o seu endereço IP, os seus separadores de terminal, o estado dos agentes). Ambas são reconstruídas a cada arranque e não guardam estado duradouro. Também é possível partilhar com o convidado até 8 pastas do seu Mac; aparecem na pasta pessoal.

Persistente por conceção — o contraste com o Bromure (Web)

O Bromure Agentic Coding partilha a base de código com a sua aplicação irmã, o Bromure, o navegador web, e as duas fazem de propósito escolhas opostas quanto à duração:

Programar precisa de estado duradouro — repositórios clonados, caches de pacotes, virtualenvs, histórico da shell — por isso deitar fora a VM depois de cada sessão tornaria os agentes inúteis. Em vez de controlar o estado da VM, o Bromure Agentic Coding controla o que a VM alguma vez pode conter: nenhum segredo real, e nenhum caminho sem mediação para a Internet. As máquinas descartáveis continuam a existir como opção: Redefinir disco volta a clonar o disco de sistema a partir da imagem base, Rebobinar a pasta pessoal… leva a pasta pessoal de volta a um ponto de controlo anterior, bromure-cli vm run --rm cria uma máquina descartável eliminada quando para, e o fluxo de comprometimento apaga um disco e uma pasta pessoal contaminados, mantendo as suas definições e chaves.

A VM do navegador

Um pedaço do Bromure (Web) continua vivo dentro do Bromure Agentic Coding: o navegador integrado ao lado de uma sessão. Quando o utilizador (ou o agente) o abre, a máquina recebe uma segunda VM, descartável, com Ubuntu e Chromium, clonada numa pasta temporária e eliminada quando o navegador fecha. O estado da navegação é deitado fora por predefinição, a menos que a máquina ative Manter-se conectado aos sites, que guarda o perfil do Chromium num disco encriptado por máquina. A VM do navegador fica na mesma rede privada que as máquinas, para poder carregar um servidor de desenvolvimento que o agente acabou de iniciar. Consulte O Navegador Incorporado.

Estados das máquinas: desligada, suspensa e em execução

Cada máquina está sempre num de três estados duradouros. Também verá brevemente A arrancar… enquanto uma máquina arranca.

Expanda Máquinas virtuais no fundo da barra lateral para ver as suas máquinas. Clicar numa máquina mostra o seu painel: CPU, memória, disco e tempo de atividade em direto enquanto corre, ou a sua especificação e configuração quando está desligada, com um botão Iniciar ou Retomar. Iniciar uma sessão numa máquina desligada arranca-a por si.

Algumas regras que convém conhecer:

• Suspender é um instantâneo de memória, não um ficheiro guardado. Restaurá-lo exige que a configuração da VM seja a mesma de quando foi guardado. Se alterar algo de que o instantâneo depende — por exemplo, o tamanho da memória ou as pastas partilhadas — a máquina arranca de raiz, e nenhum ficheiro é afetado. O registo da aplicação indica o que mudou.
• Um instantâneo nunca sobrevive ao seu disco. Redefinir ou apagar o disco de sistema também descarta qualquer instantâneo de memória guardado, porque um disco novo com memória antiga corromper-se-ia de imediato.
• Desligada não significa apagada. Uma máquina desligada mantém o seu disco de sistema e a sua pasta pessoal indefinidamente. A eliminação efetiva é sempre explícita (Redefinir disco, Rebobinar a pasta pessoal…, Eliminar espaço de trabalho) ou imposta pelo fluxo de comprometimento.

Ações de fecho

O que acontece quando fecha a janela de uma máquina é uma escolha por máquina (Ao fechar a janela no painel Geral): Correr em segundo plano (a máquina continua a correr sem janela), Suspender, Desligar ou Perguntar — a predefinição, que pergunta de cada vez. Consulte Máquinas.

A fronteira de transmissão

A fronteira de transmissão é a ideia central do produto: todo o tráfego web de saída do convidado passa por um proxy man-in-the-middle (MITM) do lado do anfitrião, e cada proteção — guardar segredos, limitar credenciais, analisar a cadeia de fornecimento, detetar injeção de prompt, proteger dados pessoais, rastrear — é aplicada nesse único ponto. O agente não a consegue contornar, porque não há nada útil do seu lado da linha.

O fluxo, de ponta a ponta:

1. O convidado só tem valores falsos. Quando uma máquina arranca, o anfitrião escreve na VM credenciais de substituição intencionalmente inválidas — variáveis de ambiente como ANTHROPIC_API_KEY, e ficheiros como ~/.git-credentials, ~/.docker/config.json e ~/.kube/config. Os valores falsos mantêm a forma dos verdadeiros (sk-ant-api03-brm-…, com forma de ghp_…, brm_…) para que as verificações do lado do cliente os aceitem, e são estáveis para uma dada instalação, por isso as ferramentas nunca veem uma chave mudar entre execuções. Os valores reais correspondentes são carregados na memória do proxy no anfitrião, cada um associado ao anfitrião a que pertence.
2. O TLS do convidado termina no proxy. Cada shell no convidado exporta HTTPS_PROXY=http://127.0.0.1:65534, um endpoint dentro da VM que faz túnel por vsock (porta 8443) até ao proxy do anfitrião. Além disso, o switch de rede virtual do anfitrião desvia para o mesmo proxy as ligações de saída do convidado para as portas 80 e 443, pelo que uma ferramenta que ignore as variáveis de proxy passa por ele na mesma. O proxy apresenta um certificado por anfitrião assinado pela CA raiz do Bromure, inspeciona o pedido e reencripta-o para o servidor real.
3. Os valores falsos só se tornam reais à saída. O proxy troca cada valor falso pelo real — troca de cabeçalhos para chaves de API e tokens, as chaves substitutas por trás dos inícios de sessão em subscrições, reassinatura SigV4 completa para a AWS (o convidado assina com um segredo falso; o anfitrião remove essa assinatura e assina de novo com o verdadeiro) e assinatura ssh-agent por vsock para SSH. As trocas aplicam-se só ao anfitrião registado e aos seus subdomínios, nunca a um sósia, por isso uma credencial registada para api.anthropic.com nunca é injetada noutro domínio.

Uma máquina pode desligar o desvio transparente no seu painel Salvaguardas; as variáveis de proxy, a troca de credenciais, o rastreio e as salvaguardas continuam a aplicar-se. Consulte Credenciais e a fronteira de transmissão.

A CA raiz do Bromure

O proxy só consegue ler o TLS do convidado porque o convidado confia nele. Na primeira execução, a aplicação cria uma autoridade de certificação por instalação — a CA raiz do Bromure Agentic Coding — cujo certificado público é instalado no repositório de confiança de cada VM no arranque, através da partilha meta. A chave privada nunca sai do anfitrião (vive em ~/Library/Application Support/BromureAC/ca/, legível só por si). Nada fora das suas VMs Bromure confia nesta CA: não pode ser usada para intercetar o tráfego do próprio Mac, e apagar a pasta ca/ apenas cria uma CA nova no arranque seguinte.

À prova de falhas por conceção

O desenho falha de forma fechada: se o tráfego do convidado alguma vez escapar ao proxy — um socket em bruto numa porta invulgar, uma tentativa deliberada de contorno — a única credencial que pode apresentar é um valor falso que nenhum servidor aceita. A AWS devolve InvalidSignatureException; os fornecedores de API rejeitam a chave substituta. Contornar a fronteira não dá nada a um atacante, porque a fronteira não é onde os segredos são verificados — é o único sítio onde os segredos existem.

O detetor de comprometimento

A fronteira também vigia o abuso contrário: a exfiltração. O proxy analisa cada pedido de saída à procura de qualquer um dos tokens falsos registados para a máquina. Um valor falso tem exatamente um destino legítimo — o anfitrião para o qual foi criado — por isso um valor falso a caminho de qualquer outro sítio é a assinatura de um agente a tentar vazar credenciais. O proxy trava o pedido, põe a máquina em pausa e alerta-o, dando-lhe a escolha de desligar a máquina, bloquear o pedido ou permitir esse destino durante o resto da sessão. Como só saiu um valor falso, a credencial real nunca precisa de ser rodada. O modelo completo de credenciais, incluindo os pedidos de aprovação por credencial e as autorizações com limite de tempo, está em Credenciais e a fronteira de transmissão.

O que persiste e o que não persiste

O Bromure Agentic Coding é explícito sobre o que dura. Os ficheiros de cada máquina vivem em ~/Library/Application Support/BromureAC/profiles/<uuid>/; as suas sessões vivem ao lado, na pasta de suporte.

Persistente — sobrevive a encerramentos e reinícios da aplicação:

Temporário — reconstruído ou eliminado automaticamente:

Daqui decorrem duas coisas. Primeiro, fechar uma janela ou encerrar uma sessão nunca apaga nada por si só — as ações destrutivas são todas explícitas e confirmadas. Eliminar uma sessão remove a sua conversa da aplicação, mas deixa a pasta na máquina. Segundo, quando quer começar do zero, tem várias opções: Rebobinar a pasta pessoal…, Redefinir disco (a pasta pessoal sobrevive), eliminar a máquina, ou uma máquina descartável com bromure-cli vm run --rm.

Nota: As pastas partilhadas a partir do seu Mac são pastas comuns no seu disco, fora do armazenamento do Bromure. Nenhuma ação do Bromure as elimina — nem mesmo a limpeza por comprometimento — e o pedido de limpeza di-lo.

Pontes anfitrião–convidado (vsock)

Tudo o que é interativo entre o Mac e o convidado passa por sockets virtio — canais diretos entre anfitrião e convidado que existem independentemente da rede da VM. Nunca os configura, mas saber que existem ajuda quando lê rastreios ou a Resolução de problemas. Cada ponte usa uma porta vsock numerada:

Pontes da VM da máquina:

Servidores MCP integrados — ferramentas que o anfitrião oferece a cada agente na máquina, cada uma alcançada através de um pequeno shim no convidado:

Pontes da VM do navegador: configuração (5000), transferência de ficheiros (5100), Chrome DevTools Protocol (5200), relé de ligações (5300), webcam (5400), barra de separadores (5810) e rastreio de rede (5900).

Área de transferência

Os separadores de terminal não têm um serviço de área de transferência à parte — a área de transferência viaja pelo próprio terminal. Copiar dentro do convidado (uma seleção do tmux, ou qualquer programa que use OSC 52) chega à área de transferência do macOS; ⌘C copia a seleção num terminal; ⌘V cola no convidado. No navegador, um agente de área de transferência no convidado trata do copiar e colar entre o Mac e o Chromium.

Transferência de ficheiros

Os ficheiros circulam entre o Mac e uma máquina de três formas, todas descritas em Máquinas: pastas partilhadas (o caminho normal para ficheiros de projeto que vivem no seu Mac), o painel Ficheiros (arrastar para dentro e para fora, pela ponte da shell na porta 5800) e anexos — qualquer ficheiro até 512 MB largado ou colado num chat ou terminal é copiado para a máquina, e o seu caminho é entregue ao agente.

Rede

Modo NAT (predefinição)

Todas as máquinas em modo NAT ligam-se a um único switch de rede por software dentro da aplicação, que chega à Internet através de uma única interface NAT vmnet do macOS. Em consequência:

• Uma sub-rede privada. Uma instalação nova escolhe ao acaso um /24 privado dentro de 172.16.0.0/12 e mantém-no, evitando qualquer rede 172.x em que o seu Mac já esteja (como a do Docker). O interruptor em Preferências › Recursos (Sub-rede do espaço de trabalho — Usar uma sub-rede privada (evita conflitos entre remotos)) mostra a sub-rede, e Sortear escolhe uma nova; as alterações aplicam-se no próximo arranque das suas máquinas. Com o interruptor desligado, a aplicação usa 192.168.64.0/24, ou outro 192.168.x.0/24 livre se a sua rede local já usar esse intervalo.
• A aplicação executa o seu próprio servidor DHCP nesse switch, e as concessões são guardadas em dhcp-leases.sqlite. Cada máquina tem um endereço MAC estável (em profile-macs.json), por isso normalmente mantém o mesmo endereço IP entre reinícios. Copiar endereço IP no menu da máquina e o painel da máquina mostram o endereço atual.
• As VMs alcançam-se umas às outras. As máquinas, as VMs de navegador, os nós de cluster e o registo estão na mesma rede por conceção, por isso o navegador pode carregar um servidor de desenvolvimento que corre numa máquina, e duas máquinas podem usar os serviços uma da outra. A lista de portas à escuta do painel mostra cada serviço alcançável como o <IP>:<porta> a que se ligaria a partir do Mac.
• Isoladas do exterior. As VMs são alcançáveis a partir do seu Mac, mas não da sua rede local física, e nada mais se pode ligar a elas a menos que publique explicitamente um serviço (por exemplo, através de um túnel rápido Cloudflare a partir da lista de portas à escuta).
• Só IPv4. O IPv6 está desligado dentro do convidado, e localhost resolve para 127.0.0.1.

A MTU de rede do convidado é 1280 por predefinição — um valor seguro atrás de VPNs e redes empresariais — e pode ser aumentada com defaults write io.bromure.agentic-coding vm.mtu -int <valor>.

Lembre-se de que o tráfego IP comum não é o caminho das credenciais: o tráfego web é encaminhado para o proxy, e tudo o que o contorne leva apenas credenciais falsas — a propriedade de falha fechada descrita acima.

Modo em ponte (por máquina)

Em alternativa, uma máquina pode juntar-se à sua rede local física: defina Rede como ponte no seu painel Recursos e escolha uma interface, e a VM aparece na rede local com o seu próprio endereço atribuído pelo router (útil quando outros dispositivos têm de a alcançar diretamente). Se a interface escolhida não estiver disponível no arranque, a máquina recorre ao NAT. Consulte Definições › Recursos.

Arranques rápidos

Duas coisas mantêm as máquinas rápidas a arrancar:

• Discos copy-on-write. O disco de sistema de uma máquina nova é um clone instantâneo da imagem base e não uma cópia, por isso o primeiro arranque não espera que se escrevam gigabytes. Os arranques a frio seguintes são arranques Linux comuns.
• Suspender e retomar. Uma máquina Suspensa salta completamente o arranque: o seu instantâneo de memória é restaurado e ela continua onde parou, incluindo separadores de terminal e agentes.

As máquinas não são agrupadas nem pré-arrancadas: cada máquina é um computador persistente próprio, por isso não há nada intercambiável para manter aquecido. A VM de navegador descartável é a exceção; vem do mesmo mecanismo de pool que o Bromure Web.