Instalação

Este capítulo leva-o de um Mac vazio a uma cópia totalmente instalada do Bromure Agentic Coding: o que a aplicação precisa da sua máquina, como descarregar e instalar uma versão, o que acontece na primeira vez que a inicia, como a imagem base de Linux é descarregada, verificada e mantida atualizada, e como remover tudo de forma limpa. Assim que a instalação estiver concluída, continue com o guia de início rápido para criar o seu primeiro espaço de trabalho.

Requisitos do sistema

Não existe uma compilação para Intel nem virá a existir: a aplicação executa as suas VMs de Linux na Virtualization.framework da Apple, que apenas suporta convidados ARM64 em anfitriões Apple Silicon.

Existem duas salvaguardas de espaço em disco integradas:

• Cada instalação de imagem começa por verificar que há pelo menos 8 GB livres no volume que contém o diretório de suporte da aplicação, falhando de imediato com uma mensagem clara caso contrário.
• Durante uma compilação local de imagem, um monitor aborta a compilação com um erro explícito de disco cheio se o espaço livre descer abaixo de 1 GB, em vez de deixar o instalador expirar misteriosamente.

Se planeia usar o navegador web incorporado opcional dentro dos espaços de trabalho, reserve espaço adicional para a sua imagem Alpine/Chromium separada (cerca de 500 MB comprimidos a descarregar); essa instalação é abordada em Definições → Navegador.

Instalar a compilação de versão

As compilações de versão são publicadas como uma imagem de disco assinada e autenticada (BromureAgenticCoding.dmg) em bromure.io.

1. Descarregue o DMG a partir da página de descarregamentos de bromure.io.
2. Abra o DMG. A janela mostra o ícone da aplicação e uma seta a apontar para uma ligação simbólica de Aplicações.
3. Arraste o Bromure Agentic Coding para a ligação simbólica de Aplicações.
4. Ejete o DMG e inicie a aplicação a partir de /Applications.

Como o DMG publicado está autenticado e agrafado, o Gatekeeper abre-o sem avisos. Se obteve um DMG de outro local que não bromure.io e o Gatekeeper reclamar, trate isso como um sinal de alerta em vez de algo a contornar.

Primeiro arranque

A janela de Boas-vindas

A aplicação não pode executar espaços de trabalho de agentes até existir uma imagem base de Linux no seu Mac. Quando a inicia pela primeira vez (ainda sem imagem base), abre uma janela de boas-vindas em vez do navegador de espaços de trabalho:

A janela — intitulada Bromure Agentic Coding — mostra o ícone da aplicação, o título Bem-vindo ao Bromure Agentic Coding, uma breve explicação ("A configuração inicial descarrega uma imagem Ubuntu 24.04 pré-compilada (ou compila-a localmente quando o descarregamento não está disponível) e instala o Node.js, o Claude Code, o Codex e as ferramentas de terminal dentro de uma VM isolada. Só acontece uma vez por versão da imagem base."), e um botão Começar em destaque.

Clique em Começar (ou prima Return — é o botão predefinido) para iniciar. Isto executa exatamente a mesma instalação que o comando de CLI bromure-cli init.

Nota: O texto de boas-vindas nomeia o Node.js, o Claude Code e o Codex como exemplos. Na totalidade, o Node.js e as ferramentas gratuitas já estão incorporados na imagem pré-compilada, e a configuração instala adicionalmente o Grok CLI e o Google Cloud SDK — ver O que a configuração inicial faz abaixo.

A janela de boas-vindas é ignorada quando a aplicação é iniciada puramente como um cliente de espelhamento remoto (ver Acesso remoto) ou como o agente headless sem janela, uma vez que nenhum precisa de uma imagem base local.

A janela de progresso da configuração

Depois de Começar, a janela muda para um ecrã de progresso intitulado Bromure Agentic Coding — Configuração, com o cabeçalho "A compilar a imagem base" / "Esta é a instalação única. Não feche a janela." Mostra:

• Um indicador de estado a nomear o passo atual — para o percurso de descarregamento: "A obter o catálogo de imagens…", "A descarregar a imagem Ubuntu 24.04 (… GB)…", "A verificar a soma de verificação…", "A expandir a imagem…", "A instalar os pacotes recomendados (N passo(s), ~2-5 min)…", e por fim "Imagem base pronta em … (vNNN)".
• Uma única barra de progresso determinada com uma percentagem numérica. No percurso de descarregamento, a barra é ponderada por fase: o descarregamento da imagem preenche 0–60%, a expansão 60–80%, e os passos de pós-instalação o restante.
• Uma secção Saída da consola, recolhida por predefinição, que transmite o registo em bruto do instalador (a consola série da VM auxiliar). O texto é selecionável, e um botão com ícone de cópia copia todo o registo para a área de transferência. Apenas as últimas 100 linhas são mantidas no ecrã.

Se algo falhar, o indicador de estado é substituído por uma linha de erro a vermelho e aparece um botão Fechar.

Tentar fechar a janela a meio da instalação levanta um aviso — Cancelar a recompilação da imagem base? ("A imagem ficará num estado incompleto. Terá de voltar a executar a recompilação antes de iniciar novas sessões.") — com os botões Cancelar recompilação e Continuar a compilar. Se cancelar e existir uma imagem funcional anterior, a aplicação regressa à janela principal normal; caso contrário, regressa ao ecrã de boas-vindas.

Nota: Enquanto uma instalação ou alteração de imagem está em curso, a porta de entrada opcional de acesso remoto por SSH é pausada e retomada automaticamente depois (ver Acesso remoto).

O pedido do bromure-cli

No primeiro arranque da interface gráfica a partir de um pacote de aplicação instalado, a aplicação oferece-se para instalar o seu ponto de entrada de linha de comandos: Instalar a ferramenta de linha de comandos "bromure-cli"? — "Isto cria uma ligação simbólica em /usr/local/bin/bromure-cli para que possa controlar o Bromure a partir do terminal (vm, exec, trace, …). Precisa da sua palavra-passe de administrador uma vez."

• Instalar cria a ligação simbólica em /usr/local/bin/bromure-cli através de um pedido único de palavra-passe de administrador (nenhum auxiliar privilegiado é instalado).
• Agora não adia; ser-lhe-á perguntado novamente no próximo arranque.
• Não perguntar novamente suprime o pedido permanentemente (armazenado na chave UserDefaults cliSymlinkDeclined).

Quando o binário é invocado através do nome bromure-cli, os comandos de gestão de imagens (init, info, reset, e os verbos do lado do editor), a predefinição da interface gráfica e o servidor MCP ficam ocultos; executar bromure-cli sem argumentos imprime a ajuda. A referência completa de comandos está em Automatização e CLI. O pedido é ignorado nos arranques de agente headless, de desenvolvimento (swift run) e de espelhamento remoto.

O que a configuração inicial faz

A configuração inicial produz a imagem base: um disco esparso de 24 GB que contém o Ubuntu 24.04 ("noble") com arranque EFI/GRUB, a partir do qual cada VM de espaço de trabalho é clonada. Dois percursos a produzem; o descarregamento é o preferido e a compilação local é a alternativa. Ambos escrevem para ficheiros .partial e promovem os resultados de forma atómica, pelo que uma instalação interrompida nunca deixa uma imagem escrita a meio no lugar de uma funcional.

O descarregamento da imagem pré-compilada

O percurso preferido descarrega uma imagem pré-compilada publicada semanalmente em https://dl.bromure.io:

1. Obtenção do catálogo. A aplicação obtém o catálogo de imagens assinado em https://dl.bromure.io/images/img-catalog.json, que nomeia a imagem atual (UUID, versão, SHA-256, tamanhos) e lista os passos de pós-instalação. O catálogo carrega uma assinatura ed25519 feita com a mesma chave que assina as atualizações da aplicação (a SUPublicEDKey do Sparkle); a assinatura cobre a identidade da imagem, a sua soma de verificação e cada comando de pós-instalação. Catálogos não assinados ou inválidos são recusados, e um catálogo assinado mais cedo do que um que a aplicação já adotou nunca é aceite (proteção contra reversão).
2. Descarregamento. A imagem comprimida com gzip (cerca de 3 GB comprimidos) é descarregada e o seu SHA-256 verificado. Descarregamentos falhados voltam a tentar até 3 vezes, obtendo novamente o catálogo entre tentativas — isto elimina a condição de corrida em que a publicação semanal apaga a compilação anterior a meio de um descarregamento.
3. Expansão. A imagem é expandida de forma esparsa para base.img.partial: 24 GB lógicos, mas apenas cerca de 6–8 GB de espaço físico em disco.
4. Pós-instalação. A aplicação arranca uma pequena VM auxiliar do instalador netboot Alpine que executa os passos de pós-instalação do catálogo como root num chroot sobre a imagem (ver a secção seguinte).
5. Promoção. É criado um novo armazenamento de variáveis EFI, e base.img, efivars.bin, base.version e image-state.json são promovidos de forma atómica.

Passos de pós-instalação: os pacotes recomendados

A imagem publicada tem de ser legalmente redistribuível, pelo que contém estritamente software livre (Node.js, docker, kitty, gh, glab, kubectl, doctl, awscli, azure-cli, e mais estão incorporados). Tudo o que não é livre é declarado como passos de pós-instalação assinados no catálogo e instalado na sua máquina, na sua cópia da imagem. Os passos de base na versão 4.3.0 são:

O consentimento funciona da seguinte forma: numa nova instalação, todos os passos de base são executados sem um pedido extra — iniciar a configuração a partir do ecrã de boas-vindas (ou escrever bromure-cli init) é o consentimento. Os passos publicados posteriormente exigem aprovação explícita através do pedido Novos pacotes recomendados descrito em Atualizações e versionamento da imagem base. Como a assinatura do catálogo cobre o texto do comando de cada passo, uma CDN comprometida não pode alterar o que é executado como root na sua imagem.

A alternativa de compilação local

Se o descarregamento falhar por um motivo do lado do descarregamento — offline, indisponibilidade da CDN, falha de soma de verificação ou de expansão — a aplicação mostra um alerta Falha no descarregamento da imagem com os botões Compilar localmente e Cancelar. Nunca recorre à alternativa silenciosamente. (O comando de CLI bromure-cli init, em contraste, recorre à alternativa automaticamente sem perguntar.)

A compilação local produz a mesma imagem no seu próprio Mac:

1. Descarrega o kernel e o initramfs de netboot do Alpine 3.22 (cerca de 25 MB, em cache no diretório de suporte).
2. Aloca um novo disco esparso de 24 GB.
3. Arranca uma VM instaladora Alpine de uso único (4 vCPUs, 4 GB de RAM), controlada pela sua consola série, que faz o debootstrap do Ubuntu noble, instala as ferramentas gratuitas e o GRUB.
4. Aplica os mesmos passos de pós-instalação do catálogo que o percurso de descarregamento.

As mensagens de progresso incluem "A descarregar o instalador netboot Alpine…", "A alocar disco esparso de 24GB…", "A arrancar o instalador Alpine (isto controla a instalação do Ubuntu)…", e "A executar setup.sh…". A barra de progresso neste percurso é controlada pelas linhas de registo do instalador e limita-se a 97% até ao salto final de "Imagem base pronta".

A compilação local inclui mecanismos de resiliência a VPN: todas as obtenções de pacotes do convidado são encaminhadas através de um proxy do lado do anfitrião em processo, o instalador limita a MTU da placa de rede da VM antes de qualquer descarregamento, o DHCP tem uma segunda oportunidade, uma condição de ausência de rede aborta cedo, e um kernel panic do convidado despoleta uma nova tentativa limpa automática. Duas válvulas de escape relacionadas:

• Se a VM instaladora não obtiver uma concessão DHCP, a compilação falha com um alerta Problema de rede durante a compilação da imagem base que oferece Reparar e tentar novamente (reinicia os daemons de rede do macOS; pede a sua palavra-passe de administrador) ou Cancelar.
• Em VPNs que descartam transferências grandes (por exemplo, WireGuard com MTU 1420), pode fixar a MTU da VM instaladora: defaults write io.bromure.agentic-coding vm.mtu -int 1400.

Também pode escolher a compilação local explicitamente a qualquer momento — Recompilar imagem base… → Recompilar localmente no menu da aplicação, ou bromure-cli init --build-local.

Pontos de extremidade de rede usados durante a configuração

Para administradores de firewall e proxy, a instalação comunica com:

A instalação em si não abre portas TCP à escuta; o proxy de pacotes do lado do anfitrião usado durante as compilações liga-se a uma porta efémera exclusiva de localhost por compilação.

Tempo de configuração e utilização de disco

Utilização de disco:

• Para começar: pelo menos 8 GB livres no volume que contém ~/Library/Application Support/BromureAC/.
• Após a instalação: a imagem base ocupa aproximadamente 6–8 GB fisicamente (24 GB lógicos — os blocos esparsos só ocupam espaço depois de escritos).
• Por espaço de trabalho: o disco de cada espaço de trabalho começa como um clone copy-on-write APFS da imagem base, pelo que é quase gratuito inicialmente e só cresce à medida que o espaço de trabalho escreve dados.

A configuração acontece uma vez por versão da imagem base — os arranques subsequentes vão diretamente para o navegador de espaços de trabalho.

Onde tudo é armazenado

Tudo o que a aplicação escreve reside na sua conta de utilizador; nada é instalado a nível do sistema, exceto a ligação simbólica opcional bromure-cli.

Dois itens residem noutro local por necessidade:

• A chave-mestra de credenciais é armazenada no Keychain de Proteção de Dados do macOS (marcada como apenas neste dispositivo — nunca sai do Mac), e não no diretório de suporte. Os segredos em disco são texto cifrado AES-256-GCM; ver Credenciais.
• O pacote da aplicação incorpora um plist de daemon launchd privilegiado (io.bromure.fatclient-tunnel) usado pelo auxiliar de rede de espelhamento remoto. É registado a pedido, e o primeiro registo faz surgir um interruptor de aprovação em Definições do Sistema › Geral › Itens de Início de Sessão; ver Acesso remoto.

O comando bromure-cli info imprime o carimbo de versão da imagem instalada, os seus tamanhos lógico e físico, e o seu caminho a qualquer momento.

Atualizações e versionamento da imagem base

Carimbos de versão e revisões decimais

A imagem instalada regista a sua versão em base.version. A parte principal provém da constante de versão incluída na aplicação (200 na versão 4.3.0); qualquer recompilação, novo descarregamento ou alteração no mesmo principal acrescenta uma revisão decimal (200 → 200.1 → 200.2). O ficheiro complementar image-state.json regista de onde a imagem veio e quais os UUIDs dos passos de pós-instalação que foram aplicados.

Duas comparações usam estes carimbos:

• A verificação de atualização ao nível da aplicação compara apenas os principais, pelo que só lhe é pedido para versões de imagem deliberadas.
• A deteção de desvio por espaço de trabalho compara o carimbo completo registado quando um espaço de trabalho foi clonado com o atual; qualquer alteração (incluindo uma revisão decimal) faz com que o espaço de trabalho ofereça uma reposição sobre a nova base. Uma atualização de imagem nunca toca por si só nos discos de espaços de trabalho existentes — as reposições por desvio são sempre uma decisão sua (ver Espaços de trabalho).

As imagens pré-compiladas são republicadas semanalmente com pacotes Ubuntu novos, mas as republicações semanais não incrementam a versão — apenas um incremento de versão deliberado numa versão da aplicação despoleta um pedido de atualização, pelo que não é incomodado todas as semanas. Um catálogo de CDN desatualizado nunca pode oferecer uma retrogradação: apenas as versões estritamente mais recentes contam.

O pedido de atualização

Quando uma versão principal mais recente da imagem está disponível — seja porque uma atualização da aplicação inclui uma ou porque o catálogo publica uma — o arranque mostra um alerta não bloqueante, Atualização da imagem base disponível: "A sua imagem base está na versão X mas a versão Y está disponível. A imagem atual continua a funcionar — a atualização descarrega a nova imagem pré-compilada (alguns GB; recompilação local como alternativa) e volta a aplicar os pacotes recomendados."

• Atualizar agora inicia a reinstalação com prioridade ao descarregamento na janela de configuração.
• Mais tarde dispensa-o neste arranque; ser-lhe-á perguntado novamente no próximo arranque. A imagem existente continua a funcionar de qualquer forma.

Novos pacotes recomendados

Quando o catálogo ganha passos de pós-instalação que ainda não estão registados como aplicados em image-state.json, o arranque mostra um alerta de consentimento, Novos pacotes recomendados, listando os novos passos: "Recomenda-se a instalação de novos pacotes: … O Bromure instala-os na imagem base (alguns minutos, na VM em segundo plano). Os espaços de trabalho existentes continuam a funcionar; o pedido de desvio de cada um oferecerá uma reposição para os adotar."

• Instalar aplica os passos a um clone copy-on-write APFS de base.img e troca a imagem alterada de forma atómica — os espaços de trabalho existentes continuam a funcionar durante todo o processo. O carimbo de versão recebe um incremento de revisão decimal (por exemplo, 200 → 200.1). O progresso aparece na janela de configuração, intitulada "A instalar os pacotes recomendados" / "A imagem base está a ser alterada. Os espaços de trabalho existentes continuam a funcionar."
• Mais tarde adia; ser-lhe-á perguntado novamente no próximo arranque.

Nada é jamais executado sem este consentimento — os passos de pós-instalação são executados como root dentro da imagem base. As instalações anteriores a image-state.json são migradas no arranque: todos os passos de base incluídos são marcados como já aplicados.

Recompilação manual

Para forçar uma reinstalação a qualquer momento, escolha Recompilar imagem base… no menu da aplicação (abaixo de Acesso remoto…). Pergunta Atualizar a imagem base? — "Descarrega a imagem pré-compilada mais recente (ou volta a executar o instalador local completo, ~5–10 min) e volta a aplicar os pacotes recomendados. Os discos dos espaços de trabalho existentes não são tocados — no próximo arranque, o pedido de desvio de cada um oferecerá a reposição para a nova base." — com Descarregar pré-compilada, Recompilar localmente e Cancelar.

A imagem antiga permanece ativa até a nova estar totalmente compilada (graças aos ficheiros .partial e à troca atómica), pelo que as sessões ainda podem ser iniciadas durante a recompilação. O equivalente na CLI é bromure-cli init (prioridade ao descarregamento) ou bromure-cli init --build-local.

Manter a aplicação atualizada

A aplicação atualiza-se a si própria com o Sparkle: verifica https://bromure.io/api/v1/release-agentic-coding automaticamente uma vez por dia, e as atualizações são verificadas contra a mesma chave pública fixada que assina os catálogos de imagens. Um item manual Verificar atualizações… encontra-se no menu da aplicação, mesmo por baixo de Acerca de. (O item está ausente nas compilações de desenvolvimento, onde o atualizador não é inicializado.)

As atualizações da aplicação e as atualizações da imagem base são independentes: atualizar a aplicação só pede uma atualização de imagem quando a nova versão da aplicação incrementa deliberadamente a versão da imagem incluída.

Mudar para um novo Mac

Não existe um assistente de migração integrado. O percurso recomendado é uma instalação de raiz mais uma cópia seletiva dos dados dos seus espaços de trabalho:

1. No novo Mac, instale a aplicação e complete a configuração inicial (voltar a descarregar a imagem base é mais rápido e limpo do que copiá-la — base.img e efivars.bin são artefactos específicos de cada máquina que a aplicação recria gratuitamente).
2. Encerre a aplicação em ambos os Macs.
3. Copie ~/Library/Application Support/BromureAC/profiles/ do Mac antigo para o mesmo local no novo. Cada subdiretório é um espaço de trabalho: a sua definição (profile.json), o seu disco de VM (disk.img — os seus repositórios clonados, caches e histórico da shell), o seu volume home e as suas chaves SSH.
4. Inicie a aplicação no novo Mac. Os seus espaços de trabalho aparecem no navegador de espaços de trabalho. Se um espaço de trabalho foi clonado a partir de uma revisão de imagem base diferente da agora instalada, o seu pedido de desvio oferece uma reposição — recuse-a para manter o disco atual do espaço de trabalho (ver Espaços de trabalho).

Três coisas intencionalmente não são transferidas:

• Credenciais. A chave-mestra que cifra os segredos armazenados reside no Keychain de Proteção de Dados do Mac e está marcada como apenas neste dispositivo. Os blocos cifrados de segredos do Mac antigo são ilegíveis no novo; os metadados não sensíveis em cada profile.json sobrevivem, pelo que voltar a introduzir as suas chaves de API e tokens no painel de credenciais é tudo o que é necessário (ver Credenciais).
• Inscrição empresarial. A identidade de instalação (certificado folha mTLS) é específica de cada instalação e armazenada apenas no dispositivo; volte a inscrever o novo Mac (ver Empresa).
• Definições da aplicação no domínio de predefinições io.bromure.agentic-coding, a menos que as migre você mesmo.

Dica: Os ficheiros disk.img dos espaços de trabalho são esparsos, e as suas poupanças de copy-on-write não sobrevivem a uma cópia pela rede — um espaço de trabalho que custa alguns GB no Mac antigo pode materializar-se com o seu tamanho total escrito durante a transferência. Use uma cópia com reconhecimento de esparsos (por exemplo rsync -aS) e verifique primeiro o espaço livre no destino.

O Assistente de Migração da Apple copia todo o diretório de suporte como ficheiros normais; isso funciona, mas continua a deparar-se com as situações de credenciais e inscrição acima, e a imagem base copiada perde a sua relação de copy-on-write com os discos dos espaços de trabalho (custando espaço físico extra até recompilar).

Desinstalar completamente

Para repor apenas a imagem base mantendo a aplicação e os seus espaços de trabalho, execute bromure-cli reset (adicione --yes para ignorar a confirmação). Elimina base.img, efivars.bin, base.version e image-state.json, pelo que o próximo arranque inicia a configuração de raiz. Nunca toca nos espaços de trabalho, e deixa os ficheiros netboot Alpine em cache e o catálogo em cache no lugar.

Não existe um desinstalador incluído. A remoção completa é manual:

1. Encerre a aplicação (e qualquer agente headless: verifique com pgrep -fl bromure-cli).

2. Arraste o Bromure Agentic Coding de /Applications para o Lixo.

3. Elimine o diretório de suporte — imagem base, todos os espaços de trabalho e os seus discos, caches e a CA por instalação:

   rm -rf ~/Library/Application\ Support/BromureAC
   

4. Elimine o LaunchAgent de arranque ao iniciar sessão, se presente:

   rm -f ~/Library/LaunchAgents/io.bromure.agentic-coding.boot.plist
   

5. Remova as entradas da aplicação em Definições do Sistema › Geral › Itens de Início de Sessão e Extensões (o interruptor de aprovação do daemon de túnel de espelhamento remoto, se alguma vez o ativou).

6. Remova a ligação simbólica da CLI, se a instalou:

   sudo rm -f /usr/local/bin/bromure-cli
   

7. Opcionalmente, limpe as definições da aplicação:

   defaults delete io.bromure.agentic-coding
   

Aviso: O passo 3 elimina permanentemente o disco de cada espaço de trabalho — repositórios clonados, trabalho não submetido, caches de pacotes, histórico da shell. Envie ou exporte tudo o que lhe importa primeiro.

A chave-mestra de credenciais no Keychain fica órfã assim que o seu texto cifrado desaparece; é inofensiva, mas pode removê-la com o Acesso a Porta-chaves procurando por io.bromure.agentic-coding.master-key.