Conceitos e Arquitetura

O Bromure Agentic Coding executa agentes de programação de IA dentro de uma máquina Linux virtualizada por hardware no seu próprio Mac, e aplica todos os controlos de segurança num único ponto que o agente não consegue contornar. Este capítulo define o vocabulário em que o resto do manual assenta — anfitrião e convidado, espaço de trabalho e sessão, a fronteira de transmissão, armazenamento persistente e efémero — e explica como as peças se encaixam. Se ler apenas um capítulo para além do Início rápido, leia este.

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 o processo do Bromure Agentic Coding em execução nele. O anfitrião detém tudo o que é sensível: as suas credenciais reais (cifradas com uma chave-mestra no Keychain do macOS), o proxy MITM que fala com a internet em nome do agente, a chave privada da CA raiz do Bromure, o armazenamento de rastreios e as janelas, terminais e painéis de controlo da aplicação. O terminal onde escreve é apresentado no anfitrião, não dentro da VM.
• O convidado é a máquina virtual Linux onde o agente efetivamente corre — Claude Code, Codex CLI, Grok CLI ou ferramentas de shell simples, juntamente com tudo o que instalam e tocam: repositórios clonados, caches de pacotes, contentores Docker, virtualenvs. O convidado é tratado como não fiável por conceção. Não contém segredos reais, apenas credenciais falsas intencionalmente inválidas, e o seu HTTPS de saída é canalizado através do proxy do anfitrião.

Os dois lados comunicam por dois canais estreitos: vsock (sockets virtio, um transporte anfitrião-para-convidado que não precisa de rede alguma) para controlo, terminais e o caminho do proxy, e uma rede virtual privada (NAT vmnet) para tráfego IP normal. Ambos são descritos em detalhe mais abaixo.

Esta divisão é o que torna concreta a garantia de segurança do produto: um agente com injeção de prompt ou que se comporte mal de outra forma 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 — nenhum desses existe do seu lado da linha.

Arquitetura em resumo

Leia o diagrama de baixo para cima: o agente trabalha na VM do espaço de trabalho; o seu HTTPS sai por vsock para o proxy do anfitrião, que é o único local onde as credenciais falsas se tornam reais; a janela da sessã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.

Espaço de trabalho, sessão e VM

Três palavras carregam significados precisos e distintos ao longo deste manual:

• Um espaço de trabalho é uma configuração guardada mais o seu armazenamento durável. Define qual o agente que corre (e como se autentica), as credenciais, as pastas partilhadas, o ambiente, os servidores MCP, as salvaguardas, a aparência e o dimensionamento da VM — tudo o que edita na janela Editar espaço de trabalho — e detém um diretório em ~/Library/Application Support/BromureAC/profiles/<uuid>/ que contém o seu disco de sistema, imagem de home, chaves SSH, pontos de verificação e estado guardado. Um espaço de trabalho existe quer algo esteja a correr quer não. Internamente (em nomes de ficheiro como profile.json e em flags da CLI) um espaço de trabalho é designado por perfil; os dois termos são intercambiáveis. A prática típica é um espaço de trabalho por projeto ou por fronteira de credenciais. Consulte Espaços de trabalho.
• A VM (máquina virtual) é a instância Linux em execução arrancada a partir do armazenamento de um espaço de trabalho. Cada espaço de trabalho mapeia para exatamente uma VM — um convidado Ubuntu com os seus próprios discos, endereço MAC determinístico, endereço IP e listener de proxy MITM por espaço de trabalho. Dois espaços de trabalho nunca partilham uma VM, e um espaço de trabalho nunca tem duas.
• Uma sessão é uma execução contínua da VM de um espaço de trabalho: começa quando inicia (ou retoma) o espaço de trabalho e termina quando a VM é encerrada ou suspensa. A janela da sessão pode desligar-se de uma sessão sem a terminar — a ação de fecho Executar em segundo plano deixa a VM a correr sem interface, e pode voltar a ligar-se a partir da barra lateral mais tarde. Algum estado é deliberadamente delimitado à sessão: as aprovações e recusas de credenciais vivem apenas em memória e são revogadas ao desmontar a sessão, e as partilhas de metadados por arranque são reconstruídas a cada boot. Consulte Sessões.

Uma abreviatura útil: o espaço de trabalho é o substantivo (persiste em disco), a VM é a máquina (existe enquanto está ligada ou suspensa), e a sessão é a execução (tem um início e um fim).

A VM do espaço de trabalho

Cada VM de espaço de trabalho é um convidado Ubuntu 24.04 a correr sob a Virtualization.framework da Apple — a mesma tecnologia de hipervisor que o próprio macOS fornece, que requer Apple Silicon e suporta apenas convidados ARM64. A VM arranca com 4 vCPUs fixos e a quantidade de RAM definida no espaço de trabalho (dimensionada ao seu Mac por predefinição: 4, 6 ou 8 GB), a partir de dois discos virtuais:

• disk.img — o disco de sistema. No primeiro arranque do espaço de trabalho é criado como um clone APFS copy-on-write da imagem base Ubuntu partilhada e assinada (consulte Instalação): o clone aparece instantaneamente e não consome novo espaço em disco até o convidado escrever nele. Os arranques seguintes reutilizam o mesmo clone, pelo que os pacotes que faz apt install, as imagens Docker que puxa e qualquer outra alteração ao nível do sistema sobrevivem entre sessões.
• home.img — uma imagem ext4 esparsa privada que contém /home/ubuntu, anexada como um segundo dispositivo virtio-blk. Tem um tamanho aparente de 64 GiB por predefinição, mas é alocada de forma preguiçosa, e encolhe no anfitrião à medida que os ficheiros são eliminados no convidado. A home sobrevive mesmo a um Repor disco, razão pela qual os seus repositórios, dotfiles e histórico de shell sobrevivem a uma reposição do disco de sistema. (Espaços de trabalho mais antigos podem ainda usar uma home legada em pasta partilhada; a aplicação oferece uma atualização única — consulte Espaços de trabalho.)

O convidado também monta pequenas partilhas virtiofs por arranque: uma meta share só de leitura que transporta a configuração desse boot (ficheiros de ambiente de tokens falsos, definições do proxy, o certificado da CA do Bromure, agentes do convidado, configurações MCP) e uma outbox gravável que o convidado usa para publicar eventos de volta ao anfitrião (o seu endereço IP, a lista de separadores tmux, o estado do agente). Ambas são reconstruídas a cada boot e não carregam qualquer estado durável. Até 8 pastas de projeto do anfitrião podem ainda ser partilhadas para o convidado, ligadas por symlink no diretório home.

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

O Bromure Agentic Coding é distribuído a partir da mesma base de código que a sua aplicação-irmã, o Bromure — a variante de navegador web — e as duas fazem escolhas de ciclo de vida opostas de propósito:

O trabalho de programação precisa de estado durável — repositórios clonados, caches de pacotes, virtualenvs, histórico de shell — pelo que destruir a VM após cada sessão tornaria os agentes inúteis. Em vez de controlar o estado da VM, o Bromure Agentic Coding controla aquilo que a VM alguma vez pode conter: sem segredos reais, e sem caminho não mediado para a internet. A efemeridade continua a existir como uma saída de emergência em vez de uma predefinição: Repor disco volta a clonar o disco de sistema a partir da imagem base, os pontos de verificação de disco e de home permitem reversão, bromure-cli vm run --rm cria espaços de trabalho descartáveis ao estilo docker eliminados quando a VM para, e o fluxo de comprometimento apaga um disco e uma home contaminados preservando as suas definições e chaves.

A VM sidecar do navegador

Uma peça do Bromure (Web) sobrevive dentro do Bromure Agentic Coding: o painel do navegador agêntico. Quando o abre (ou o agente o abre), o espaço de trabalho ganha uma segunda VM, efémera — um convidado Alpine + Chromium clonado para o diretório temporário e eliminado quando o painel é desmontado. Esta VM sidecar é a exceção que confirma a regra: o estado de navegação é descartável por predefinição (a menos que o espaço de trabalho ative Manter sessão iniciada nos sites, que mantém o perfil do Chromium num disco cifrado por espaço de trabalho), enquanto a VM do espaço de trabalho ao seu lado é durável. Ambas as VMs assentam no mesmo segmento de rede privada, pelo que o navegador pode carregar um servidor de desenvolvimento que o agente acabou de iniciar através do IP da VM.

Ciclo de vida da VM: Desligada, Suspensa e Em execução

Cada espaço de trabalho está sempre em exatamente um de três estados duráveis, mostrado como uma etiqueta ao lado do nome do espaço de trabalho na barra lateral e no painel de controlo da VM. (Verá também brevemente estados transitórios — A iniciar… na barra lateral e uma indicação de arranque no painel de controlo — enquanto uma VM está a subir.)

Selecionar o nome de um espaço de trabalho mostra o seu painel de controlo para qualquer estado: cartões ao vivo de CPU, memória, vCPU, disco e tempo de atividade enquanto está em execução, ou a especificação e o resumo de configuração da máquina enquanto está desligada ou suspensa — a captura de ecrã acima mostra um espaço de trabalho que nunca foi iniciado, razão pela qual o cartão de Disco ainda lê 0 MB (ainda não existe clone). O botão no canto superior direito é Iniciar para um espaço de trabalho desligado e Retomar para um suspenso.

Algumas regras de ciclo de vida que vale a pena interiorizar:

• A suspensão é um instantâneo de RAM, não um ficheiro guardado. Restaurá-lo exige que a configuração da VM seja idêntica, razão pela qual cada espaço de trabalho persiste um identificador de máquina e um endereço MAC determinístico. Se alterar o conjunto de pastas partilhadas enquanto existe um instantâneo, a aplicação pergunta se pode descartar o estado suspenso — o próximo arranque é a frio, e nenhum ficheiro é afetado.
• Um instantâneo nunca sobrevive ao seu disco. Repor ou apagar o disco de sistema também descarta qualquer instantâneo de RAM guardado e o estado dos separadores, porque um disco novo mais RAM obsoleta corromperiam instantaneamente.
• Desligada não significa apagada. Um espaço de trabalho encerrado mantém o seu disco de sistema e a sua home indefinidamente. A destruição efetiva de dados é sempre explícita (Repor disco, Apagar home, Eliminar espaço de trabalho) ou forçada pelo fluxo de comprometimento.

Ações de fecho

O que acontece quando fecha uma sessão é uma escolha por espaço de trabalho (Ao fechar a janela no editor de espaços de trabalho): Executar em segundo plano (desligar a janela, manter a VM em execução), Suspender, Encerrar ou Perguntar — a predefinição, que pergunta de cada vez com as três opções. Fechar o último separador de terminal segue a mesma escolha. Consulte Sessões para o fluxo completo.

A fronteira de transmissão

A fronteira de transmissão é a ideia central do produto: todo o HTTPS de saída do convidado passa por um proxy man-in-the-middle (MITM) do lado do anfitrião, e todas as proteções — guardar segredos, delimitar credenciais, análise da cadeia de fornecimento, deteção de injeção de prompt, rastreio — são aplicadas nesse único ponto. O agente não consegue contorná-lo, porque não há nada de útil do seu lado da linha.

O fluxo, de ponta a ponta:

1. O convidado contém apenas falsas. No arranque da sessão, o anfitrião escreve na VM credenciais de marcador de posição intencionalmente inválidas — variáveis de ambiente como ANTHROPIC_API_KEY, e ficheiros de configuração como ~/.git-credentials, ~/.docker/config.json e ~/.kube/config. As falsas preservam a estrutura (sk-ant-api03-brm-…, com a forma de ghp_…, brm_…) para que os validadores do lado do cliente as aceitem, e são determinísticas por instalação, para que as ferramentas nunca vejam uma chave "rodar" entre sessões. Os valores reais correspondentes são carregados no mapa de troca em memória do proxy no anfitrião, cada um associado ao anfitrião de destino a que pertence.
2. O TLS do convidado termina no proxy. Cada shell no convidado exporta HTTPS_PROXY=http://127.0.0.1:8080, um endpoint dentro da VM que faz túnel por vsock (porta 8443) para o proxy do anfitrião. O proxy apresenta um certificado folha forjado por anfitrião assinado pela CA raiz do Bromure, inspeciona o pedido e volta a cifrá-lo em direção ao upstream real.
3. As falsas só se tornam reais no caminho de saída. O proxy troca cada falsa pelo seu valor real — trocas de cabeçalho para chaves de API e tokens, trocas de corpo para fluxos de renovação OAuth, re-assinatura SigV4 completa para a AWS (o convidado assina com um segredo falso; o anfitrião remove essa assinatura e volta a assinar com a real), assinatura ssh-agent por vsock para SSH. As trocas são delimitadas exata-ou-subdomínio ao anfitrião registado, nunca por substring, pelo que uma credencial registada para api.anthropic.com nunca é injetada em direção a um domínio semelhante.

A CA raiz do Bromure

O proxy só consegue terminar o TLS do convidado porque o convidado confia nele para isso. No primeiro arranque, a aplicação gera uma autoridade de certificação por instalação — a CA raiz do Bromure Agentic Coding — cujo certificado público é montado no armazenamento de confiança de cada VM no boot através da meta share. A chave privada nunca sai do anfitrião (vive em ~/Library/Application Support/BromureAC/ca/, legível apenas pelo proprietário). Nada fora das suas VMs do Bromure confia nesta CA: não pode ser usada para intercetar o próprio tráfego do seu Mac, e eliminar o diretório ca/ simplesmente cunha uma CA nova no próximo arranque.

À prova de falhas por conceção

O design é à prova de falhas: se alguma vez o tráfego do convidado evadir o proxy — uma ferramenta que ignora as variáveis de proxy, um socket em bruto, uma tentativa deliberada de contorno — a única credencial que pode apresentar é uma falsa que nenhum upstream aceita. A AWS devolve InvalidSignatureException; os fornecedores de API rejeitam a chave de marcador de posição. Contornar a fronteira nada dá a um atacante, porque a fronteira não é onde os segredos são verificados — é o único local onde os segredos existem.

O detetor de comprometimento

A fronteira também vigia a direção oposta de abuso: a exfiltração. O proxy analisa cada pedido de saída em busca de qualquer um dos tokens falsos registados do espaço de trabalho. Uma falsa tem exatamente um destino legítimo — o anfitrião para o qual foi cunhada — pelo que uma falsa observada a seguir para qualquer outro lado é a assinatura de um agente a tentar vazar credenciais. O proxy recusa o pedido sem reencaminhar um único byte, pausa a VM e alerta-o; o espaço de trabalho é marcado como comprometido e recusa arrancar de novo até que o seu disco e home (presumivelmente contaminados) sejam apagados. As suas definições, tokens e chaves SSH são mantidos — e, como apenas a falsa alguma vez vazou, a credencial real nunca precisa de rotação. O modelo de credenciais completo, incluindo pedidos de aprovação por credencial e concessões limitadas por TTL, é abordado em Credenciais e a fronteira de transmissão.

O que persiste e o que não persiste

O Bromure Agentic Coding é explícito quanto ao tempo de vida. Tudo o que um espaço de trabalho detém vive em ~/Library/Application Support/BromureAC/profiles/<uuid>/; a tabela abaixo é o mapa definitivo do que sobrevive a quê.

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

Efémero — reconstruído ou destruído automaticamente:

Duas consequências decorrem deste mapa. Primeiro, "fechar a janela" nunca é destrutivo por si só — os verbos destrutivos são todos explícitos e confirmados. Segundo, quando quer descartabilidade, tem opções graduadas: reverter para um ponto de verificação, Repor disco (a home sobrevive), Apagar home, eliminar o espaço de trabalho ou começar logo com um descartável via bromure-cli vm run --rm.

Nota: As pastas partilhadas do anfitrião são diretórios de projeto no seu Mac, fora do armazenamento do Bromure. Nunca são apagadas por qualquer ação do Bromure — incluindo a limpeza de comprometimento — e o pedido de confirmação da limpeza diz isso explicitamente.

Pontes anfitrião–convidado (vsock)

A integração interativa entre o Mac e o convidado assenta em sockets virtio — canais anfitrião-para-convidado ponto a ponto que existem independentemente da rede da VM. Nunca configura estes canais, mas saber que existem ajuda ao ler rastreios ou o capítulo Resolução de problemas. Cada ponte escuta numa porta vsock numerada:

Pontes da VM do espaço de trabalho:

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

Área de transferência

Não existe um daemon de área de transferência separado para os terminais do espaço de trabalho — a área de transferência assenta no próprio protocolo do terminal. Copiar dentro do convidado (uma seleção tmux, ou qualquer programa que emita OSC 52) aterra automaticamente na área de transferência do macOS; ⌘C copia a seleção do terminal do lado do anfitrião; ⌘V cola no convidado usando colagem entre parênteses. No painel do navegador, um agente de área de transferência do convidado mais ⌘C/⌘V capturados fornecem copiar e colar entre o Mac e o Chromium.

Transferência de ficheiros

Os ficheiros movem-se entre o Mac e um espaço de trabalho de três formas, todas abordadas em Sessões: pastas partilhadas (virtiofs, o caminho normal para ficheiros de projeto), a janela do navegador de ficheiros ao estilo Finder (arrastar para dentro e para fora sobre o serviço de ficheiros vsock na porta 5800) e a colagem de imagem (⌘V com uma imagem carrega-a para o convidado e cola o seu caminho). O protocolo dedicado de transferência de ficheiros na porta 5100 pertence à VM sidecar do navegador.

Rede

Modo NAT (predefinição)

Todas as VMs de espaço de trabalho em modo NAT ligam-se a um único comutador L2 de software ao nível do processo, multiplexado numa interface partilhada/NAT vmnet. As consequências:

• Uma sub-rede privada — 192.168.64.0/24 por predefinição (gateway .1, endereços atribuídos de .2 a .254 durante 24 horas). Se a própria LAN do seu Mac já usar esse intervalo, o Bromure escolhe automaticamente outro 192.168.x.0/24.
• O Bromure corre o seu próprio servidor DHCP nesse comutador (o da Apple só consegue seguir uma única atribuição por interface), e as atribuições persistem em dhcp-leases.sqlite no anfitrião.
• Endereçamento estável — cada espaço de trabalho recebe um endereço MAC determinístico e administrado localmente, persistido em profile-macs.json, e, combinado com atribuições persistentes, um espaço de trabalho normalmente mantém o mesmo IP entre reinícios da aplicação (melhor esforço: desde que o endereço permaneça livre). O IP atual é sempre mostrado no cabeçalho do painel de controlo da VM e na etiqueta da barra de ferramentas.
• As VMs conseguem alcançar-se umas às outras. Cada VM em modo NAT — VMs de espaço de trabalho e sidecars de navegador por igual — assenta no mesmo segmento L2 por conceção, pelo que o painel do navegador pode carregar um servidor de desenvolvimento a correr na VM do espaço de trabalho, e dois espaços de trabalho podem falar com os serviços um do outro. O cartão Portas em Escuta do painel de controlo lista cada socket do convidado alcançável externamente como o endpoint <IP-da-VM>:<porta> a que efetivamente se ligaria a partir do Mac.
• Isolamento do exterior. O NAT significa que as VMs são alcançáveis a partir do seu Mac, mas não estão expostas na sua LAN física, e não são possíveis ligações de entrada de outros locais a menos que publique explicitamente um serviço (túneis rápidos Cloudflare por serviço, a partir do cartão Portas em Escuta).

A MTU da NIC do convidado é fixada em 1280 por predefinição — um valor conservador que sobrevive a ambientes de VPN e de MTU de caminho corporativo — e pode ser aumentada com defaults write io.bromure.agentic-coding vm.mtu -int <value>.

Lembre-se de que o tráfego IP normal nesta rede não é como as credenciais fluem: o HTTPS do convidado é direcionado através do endpoint de proxy dentro da VM e por vsock até à fronteira de transmissão. A rede NAT transporta tudo o resto — e qualquer coisa que contorne o proxy transporta apenas credenciais falsas, que é exatamente a propriedade à prova de falhas descrita acima.

Modo em ponte (por espaço de trabalho)

Em alternativa, um espaço de trabalho pode juntar-se à sua LAN física: o modo em ponte liga a VM a uma interface anfitriã escolhida via bridging vmnet, fazendo-a aparecer como um dispositivo na rede local (útil quando outras máquinas precisam de alcançar a VM diretamente). Se a interface escolhida estiver indisponível no arranque, a VM recorre ao NAT. O modo de rede é definido por espaço de trabalho no editor de espaços de trabalho; consulte Espaços de trabalho.

Arranque instantâneo e pré-aquecimento

Dois mecanismos diferentes fazem as sessões parecerem instantâneas, e vale a pena saber qual se aplica onde:

• As VMs de espaço de trabalho não são agrupadas. Cada espaço de trabalho arranca diretamente a sua própria VM persistente. O primeiro arranque é rápido porque o disco de sistema é um clone CoW instantâneo em vez de uma imagem copiada; os arranques a frio subsequentes são arranques Linux normais (cobertos pela sobreposição animada de boot); e um espaço de trabalho Suspenso dispensa por completo o arranque — o seu instantâneo de RAM é restaurado e a sessão retoma no lugar, terminais e tudo, quase instantaneamente.
• A sidecar do navegador usa um conjunto pré-aquecido. O motor mantém uma VM de navegador pré-arrancada pronta em segundo plano para que abrir o painel do navegador agêntico demore menos de 1 segundo. Quando essa VM é reclamada, começa a aquecer uma substituta; enquanto inativa, o balão de memória da VM aquecida é insuflado (o convidado mantém cerca de 512 MB) e a VM é suspensa ao fim de 30 segundos para se manter barata, sendo depois retomada e o balão esvaziado (memória total restaurada ao convidado) no momento da reclamação.

A distinção decorre diretamente da filosofia de ciclo de vida: as VMs agrupadas só fazem sentido quando cada instância é intercambiável, o que é verdade para as VMs de navegador descartáveis e falso para as máquinas persistentes por espaço de trabalho.