安装

本章将带你从一台空白的 Mac 走到完整安装好 Bromure Agentic Coding：应用对你机器的要求、如何下载并安装某个发行版、首次启动时会发生什么、Linux 基础镜像如何下载、验证并保持更新，以及如何干净地移除所有内容。安装完成后，请继续阅读快速上手，创建你的第一个工作区。

系统要求

没有 Intel 版本，将来也不会有：应用在 Apple 的 Virtualization.framework 上运行其 Linux 虚拟机，而该框架仅支持在 Apple Silicon 宿主机上运行 ARM64 客户机。

内置了两项磁盘空间保护机制：

• 每次安装镜像前都会先检查存放应用支持目录的卷上至少有 8 GB 可用空间，否则会快速失败并给出清晰的提示。
• 在本地构建镜像期间，如果可用空间降至 1 GB 以下，监控程序会中止构建并给出明确的磁盘已满错误，而不是让安装程序莫名其妙地超时。

如果你打算在工作区内使用可选的嵌入式网页浏览器，请为其单独的 Alpine/Chromium 镜像预留额外空间（下载时约 500 MB 压缩包）；该安装过程详见 设置 → 浏览器。

安装发行版构建

发行版构建以经过签名、公证的磁盘映像（BromureAgenticCoding.dmg）的形式发布于 bromure.io。

1. 从 bromure.io 下载页面下载该 DMG。
2. 打开该 DMG。窗口会显示应用图标以及一个指向 应用程序 符号链接的箭头。
3. 将 Bromure Agentic Coding 拖到 应用程序 符号链接上。
4. 弹出该 DMG，并从 /Applications 启动应用。

由于发布的 DMG 已经过公证并加盖公证票据，Gatekeeper 会毫无警告地将其打开。如果你从 bromure.io 以外的地方获得了某个 DMG，并且 Gatekeeper 发出了警告，应将其视为危险信号，而不是想办法绕过。

首次启动

欢迎窗口

在你的 Mac 上存在 Linux 基础镜像之前，应用无法运行代理工作区。当你第一次启动它时（尚无基础镜像），它会打开一个欢迎窗口，而不是工作区浏览器：

该窗口——标题为 Bromure Agentic Coding——显示应用图标、标题 欢迎使用 Bromure Agentic Coding、一段简短说明（“首次设置会下载一个预构建的 Ubuntu 24.04 镜像（在无法下载时则在本地构建），并在一个隔离的虚拟机内安装 Node.js、Claude Code、Codex 以及终端工具链。每个基础镜像版本只会发生一次。”），以及一个醒目的 开始使用 按钮。

点击 开始使用（或按回车键——它是默认按钮）即可开始。这与 bromure-cli init CLI 命令运行的安装完全相同。

注意： 欢迎文本以 Node.js、Claude Code 和 Codex 作为示例。完整而言，Node.js 和免费工具链已经预置在预构建镜像中，设置过程还会额外安装 Grok CLI 和 Google Cloud SDK——参见下文的首次设置做了什么。

当应用纯粹作为远程镜像客户端（参见远程访问）或作为无窗口的无头代理启动时，欢迎窗口会被跳过，因为两者都不需要本地基础镜像。

设置进度窗口

点击 开始使用 后，窗口会切换到一个进度界面，标题为 Bromure Agentic Coding — Setup，标头为“正在构建基础镜像” / “这是一次性安装。请勿关闭窗口。”。它会显示：

• 一个状态胶囊标签，标示当前步骤——就下载路径而言：“正在获取镜像目录…”、“正在下载 Ubuntu 24.04 镜像（… GB）…”、“正在校验校验和…”、“正在展开镜像…”、“正在安装推荐软件包（N 个步骤，约 2-5 分钟）…”，最后是“基础镜像已就绪，位于 …（vNNN）”。
• 一个带数字百分比的单一确定型进度条。在下载路径上，进度条按阶段加权：镜像下载占 0–60%，展开占 60–80%，安装后步骤占其余部分。
• 一个默认折叠的 控制台输出 展开区，实时输出原始安装程序日志（辅助虚拟机的串行控制台）。文本可选中，一个复制图标按钮可将整个日志复制到剪贴板。屏幕上仅保留最后 100 行。

如果出现任何失败，状态胶囊标签会被替换为一行红色错误信息，并出现一个 关闭 按钮。

在安装进行到一半时尝试关闭窗口会弹出一个警告——取消重建基础镜像？（“镜像将处于不完整状态。你需要在启动新会话之前重新运行重建。”）——并带有 取消重建 和 继续构建 按钮。如果你取消并且此前已存在一个可用镜像，应用会返回正常的主窗口；否则返回欢迎界面。

注意： 在镜像安装或修订运行期间，可选的 SSH 远程访问入口会暂停，之后自动恢复（参见远程访问）。

bromure-cli 提示

在从已安装的应用程序包首次进行 GUI 启动时，应用会提议安装其命令行入口：安装 “bromure-cli” 命令行工具？——“这会在 /usr/local/bin/bromure-cli 处创建一个符号链接，以便你从终端驱动 Bromure（vm、exec、trace、…）。它需要你输入一次管理员密码。”

• 安装 会通过一次性的管理员密码提示在 /usr/local/bin/bromure-cli 处创建符号链接（不会安装任何特权辅助程序）。
• 暂不 会推迟；下次启动时会再次询问。
• 不再询问 会永久抑制该提示（存储在 cliSymlinkDeclined UserDefaults 键中）。

当二进制文件通过 bromure-cli 这个名称被调用时，镜像管理命令（init、info、reset 以及发布方一侧的动词）、GUI 默认行为和 MCP 服务器都会被隐藏；直接运行 bromure-cli 会打印帮助信息。完整的命令参考见自动化与 CLI。对于无头代理、开发（swift run）和远程镜像启动，该提示会被跳过。

首次设置做了什么

首次设置会生成基础镜像：一个 24 GB 的稀疏磁盘，包含带 EFI/GRUB 引导的 Ubuntu 24.04（“noble”），每个工作区虚拟机都从中克隆。有两条路径可以生成它；下载是首选，本地构建是回退方案。两者都写入 .partial 文件并以原子方式提升结果，因此被中断的安装绝不会用一个写了一半的镜像取代一个可用的镜像。

预构建镜像下载

首选路径会下载每周发布到 https://dl.bromure.io 的预构建镜像：

1. 获取目录。 应用会获取位于 https://dl.bromure.io/images/img-catalog.json 的经过签名的镜像目录，其中标明当前镜像（UUID、版本、SHA-256、大小）并列出安装后步骤。该目录带有一个用与签名应用更新相同的密钥（Sparkle 的 SUPublicEDKey）生成的 ed25519 签名；签名覆盖镜像标识、其校验和以及每一条安装后命令。未签名或无效的目录会被拒绝，而签名时间早于应用已采用目录的目录绝不会被接受（回滚保护）。
2. 下载。 会下载经过 gzip 压缩的镜像（压缩后约 3 GB）并校验其 SHA-256。失败的下载会重试最多 3 次，并在两次尝试之间重新获取目录——这消除了与每周发布在下载中途删除上一个构建之间的竞态。
3. 展开。 镜像会以稀疏方式展开到 base.img.partial：逻辑大小 24 GB，但仅占用约 6–8 GB 的物理磁盘空间。
4. 安装后处理。 应用会引导一个小型的 Alpine netboot 安装程序辅助虚拟机，它在镜像上的一个 chroot 中以 root 身份运行目录中的安装后步骤（参见下一节）。
5. 提升。 会创建一个全新的 EFI 变量存储，并以原子方式提升 base.img、efivars.bin、base.version 和 image-state.json。

安装后步骤：推荐软件包

已发布的镜像必须可以合法地再分发，因此它只包含严格意义上的免费软件（Node.js、docker、kitty、gh、glab、kubectl、doctl、awscli、azure-cli 等都已预置）。所有非免费的内容都在目录中声明为经过签名的安装后步骤，并安装到 你的 机器上、你的 镜像副本中。4.3.0 版本的基线步骤为：

许可机制如下：在全新安装时，所有基线步骤都无需额外提示即会运行——从欢迎界面开始设置（或输入 bromure-cli init）即为 许可。之后发布的步骤需要通过基础镜像更新与版本控制下所述的 新推荐软件包 提示进行明确批准。由于目录签名覆盖了每个步骤的命令文本，被入侵的 CDN 无法改变在你的镜像中以 root 身份运行的内容。

本地构建回退方案

如果下载因下载端原因失败——离线、CDN 中断、校验和或展开失败——应用会显示一个 镜像下载失败 警告，带有 本地构建 和 取消 按钮。它绝不会静默回退。（相比之下，bromure-cli init CLI 命令会自动回退而不提示。）

本地构建会在你自己的 Mac 上生成相同的镜像：

1. 下载 Alpine 3.22 netboot 内核和 initramfs（约 25 MB，缓存在支持目录中）。
2. 分配一个全新的 24 GB 稀疏磁盘。
3. 引导一个一次性的 Alpine 安装程序虚拟机（4 个 vCPU、4 GB 内存），通过其串行控制台驱动，该虚拟机会 debootstrap 出 Ubuntu noble，安装免费工具链和 GRUB。
4. 应用与下载路径相同的目录安装后步骤。

进度消息包括“正在下载 Alpine netboot 安装程序…”、“正在分配 24GB 稀疏磁盘…”、“正在引导 Alpine 安装程序（它驱动 Ubuntu 安装）…”，以及“正在运行 setup.sh…”。此路径上的进度条由安装程序日志行驱动，并在最后一次跳转到“基础镜像已就绪”之前封顶在 97%。

本地构建包含 VPN 弹性机制：所有客户机软件包获取都通过一个进程内的宿主机侧代理服务器路由，安装程序在任何下载之前会钳制虚拟机网卡的 MTU，DHCP 会获得第二次机会，无网络状态会提前中止，而客户机内核崩溃会触发一次自动的干净重试。两个相关的应急出口：

• 如果安装程序虚拟机未获得 DHCP 租约，构建会失败并显示一个 基础镜像构建期间的网络问题 警告，提供 修复并重试（重启 macOS 网络守护进程；会要求你输入管理员密码）或 取消。
• 在会将大型传输黑洞化的 VPN 上（例如 MTU 1420 的 WireGuard），你可以固定安装程序虚拟机的 MTU：defaults write io.bromure.agentic-coding vm.mtu -int 1400。

你也可以随时显式选择本地构建——应用菜单中的 重建基础镜像… → 本地重建，或 bromure-cli init --build-local。

设置期间使用的网络端点

对于防火墙和代理服务器管理员，安装过程会与以下端点通信：

安装本身不会打开任何监听的 TCP 端口；构建期间使用的宿主机侧软件包代理服务器为每次构建绑定一个临时的、仅限 localhost 的端口。

设置时间与磁盘用量

磁盘用量：

• 开始时： 存放 ~/Library/Application Support/BromureAC/ 的卷上至少需 8 GB 可用空间。
• 安装后： 基础镜像物理上占用约 6–8 GB（逻辑 24 GB——稀疏块只有在写入后才占用空间）。
• 每个工作区： 每个工作区的磁盘一开始都是基础镜像的 APFS 写时复制克隆，因此初始时几乎不占空间，仅随着工作区写入数据而增长。

设置在每个基础镜像版本只发生一次——后续启动会直接进入工作区浏览器。

所有内容的存储位置

应用写入的所有内容都存放在你的用户账户下；除了可选的 bromure-cli 符号链接外，不会在系统范围内安装任何内容。

有两项内容出于必要而存放在别处：

• 凭据主密钥存储在 macOS 数据保护钥匙串中（标记为 仅限本设备——它绝不离开这台 Mac），而不是存放在支持目录中。磁盘上的机密是 AES-256-GCM 密文；参见凭据。
• 应用程序包内嵌了一个特权 launchd 守护进程 plist（io.bromure.fatclient-tunnel），由远程镜像网络辅助程序使用。它按需注册，首次注册会在“系统设置 › 通用 › 登录项”下显示一个批准开关；参见远程访问。

bromure-cli info 命令可随时打印已安装镜像的版本戳、其逻辑和物理大小以及其路径。

基础镜像更新与版本控制

版本戳与点修订号

已安装镜像在 base.version 中记录其版本。主 部分来自应用捆绑的版本常量（4.3.0 版本时为 200）；在同一主版本下的任何重建、重新下载或修订都会附加一个点修订号（200 → 200.1 → 200.2）。附属的 image-state.json 记录镜像来自何处以及已应用了哪些安装后步骤 UUID。

有两处比较会用到这些版本戳：

• 应用级别的更新检查仅比较主版本，因此你只会在有意发布的镜像发行时收到提示。
• 每个工作区的 偏移检测 会将克隆工作区时记录的完整版本戳与当前版本戳进行比较；任何变化（包括点修订号）都会使该工作区提供一个重置到新基础镜像的选项。镜像更新本身绝不会触碰现有的工作区磁盘——偏移重置始终由你决定（参见工作区）。

预构建镜像每周会用最新的 Ubuntu 软件包重新发布，但每周重新发布 不会 提升版本——只有应用发行版中有意的版本提升才会触发更新提示，因此你不会每周都被打扰。过期的 CDN 目录绝不会提供降级：只有严格更新的版本才算数。

更新提示

当有更新的主镜像版本可用时——无论是因为某次应用更新捆绑了它，还是因为目录发布了它——启动时会显示一个非阻塞警告 基础镜像更新可用：“你的基础镜像为版本 X，但版本 Y 已可用。当前镜像仍可使用——更新会下载新的预构建镜像（几 GB；以本地重建作为回退方案）并重新应用推荐软件包。”

• 立即更新 会在设置窗口中启动优先下载的重新安装。
• 稍后 会在本次启动中将其忽略；下次启动时会再次询问。无论哪种方式，现有镜像都会继续可用。

新推荐软件包

当目录新增了尚未在 image-state.json 中记录为已应用的安装后步骤时，启动时会显示一个许可警告 新推荐软件包，列出这些新步骤：“建议安装新软件包：… Bromure 会将它们安装到基础镜像中（几分钟，在后台虚拟机中）。现有工作区会继续运行；每个工作区的偏移提示都会提供一个重置选项以采纳它们。”

• 安装 会将这些步骤应用到 base.img 的一个 APFS 写时复制克隆上，并以原子方式换入修订后的镜像——现有工作区在整个过程中会继续运行。版本戳会得到一次点修订号提升（例如 200 → 200.1）。进度显示在设置窗口中，标题为“正在安装推荐软件包” / “正在修订基础镜像。现有工作区会继续工作。”。
• 稍后 会推迟；下次启动时会再次询问。

未经此许可，任何内容都绝不会执行——安装后步骤会在基础镜像内以 root 身份运行。早于 image-state.json 的安装会在启动时迁移：所有捆绑的基线步骤都被标记为已应用。

手动重建

若要随时强制重新安装，请从应用程序菜单（位于 远程访问… 下方）中选择 重建基础镜像…。它会询问 更新基础镜像？——“下载最新的预构建镜像（或重新运行完整的本地安装程序，约 5–10 分钟）并重新应用推荐软件包。现有工作区的磁盘不会被触碰——下次启动时，每个工作区的偏移提示都会提供重置到新基础镜像的选项。”——并带有 下载预构建、本地重建 和 取消。

旧镜像在新镜像完全构建好之前会保持可用（得益于 .partial 文件和原子交换），因此在重建期间会话仍可启动。CLI 等效命令为 bromure-cli init（优先下载）或 bromure-cli init --build-local。

保持应用更新

应用通过 Sparkle 进行自我更新：它每天自动检查一次 https://bromure.io/api/v1/release-agentic-coding，更新会针对签名镜像目录所用的同一个固定公钥进行验证。应用程序菜单中 关于 正下方有一个手动的 检查更新… 项。（在开发构建中该项不存在，因为更新程序未被初始化。）

应用更新和基础镜像更新是相互独立的：更新应用只有在新应用版本有意提升捆绑的镜像版本时才会提示进行镜像更新。

迁移到新 Mac

没有内置的迁移助理。推荐的路径是全新安装加上有选择地复制你的工作区数据：

1. 在新 Mac 上安装应用并完成首次设置（重新下载基础镜像比复制它更快、更干净——base.img 和 efivars.bin 是每台机器各自的产物，应用会免费重新创建它们）。
2. 在两台 Mac 上都退出应用。
3. 将 ~/Library/Application Support/BromureAC/profiles/ 从旧 Mac 复制到新 Mac 上的相同位置。每个子目录都是一个工作区：它的定义（profile.json）、它的虚拟机磁盘（disk.img——你克隆的仓库、缓存和 shell 历史）、它的 home 卷以及它的 SSH 密钥。
4. 在新 Mac 上启动应用。你的工作区会出现在工作区浏览器中。如果某个工作区是从与当前已安装版本不同的基础镜像修订版克隆而来的，它的偏移提示会提供重置选项——拒绝它即可保留工作区当前的磁盘（参见工作区）。

有三样东西被有意设计为不迁移：

• 凭据。 加密所存储机密的主密钥存放在 Mac 的数据保护钥匙串中，并标记为 仅限本设备。来自旧 Mac 的加密机密数据块在新 Mac 上无法读取；每个 profile.json 中的非敏感元数据会保留下来，因此只需在凭据窗格中重新输入你的 API 密钥和令牌即可（参见凭据）。
• 企业注册。 安装身份（mTLS 叶证书）是每次安装各自的，且仅存储于设备本地；请在新 Mac 上重新注册（参见企业版）。
• 应用设置，位于 io.bromure.agentic-coding 默认域中，除非你自行迁移它们。

提示： 工作区 disk.img 文件是稀疏的，而它们的写时复制节省无法在网络复制后保留下来——一个在旧 Mac 上仅占几 GB 的工作区，在传输过程中可能会实体化为其完整的已写入大小。请使用可感知稀疏的复制方式（例如 rsync -aS），并先检查目标位置的可用空间。

Apple 的迁移助理会将整个支持目录作为普通文件复制过去；这行得通，但你仍会面临上述凭据和注册的情况，而且复制过去的基础镜像会失去它与工作区磁盘之间的写时复制关系（在你重建之前会占用额外的物理空间）。

彻底卸载

若只想重置基础镜像而保留应用和你的工作区，请运行 bromure-cli reset（加上 --yes 可跳过确认）。它会删除 base.img、efivars.bin、base.version 和 image-state.json，因此下次启动会从头开始设置。它绝不会触碰工作区，并会保留缓存的 Alpine netboot 文件和缓存的目录。

没有捆绑的卸载程序。彻底移除需手动进行：

1. 退出应用（以及任何无头代理：用 pgrep -fl bromure-cli 检查）。

2. 将 Bromure Agentic Coding 从 /Applications 拖到废纸篓。

3. 删除支持目录——基础镜像、所有工作区及其磁盘、缓存以及每次安装的 CA：

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

4. 删除登录时启动的 LaunchAgent（如果存在）：

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

5. 在“系统设置 › 通用 › 登录项与扩展”下移除应用的条目（如果你曾经启用过，则包括远程镜像隧道守护进程的批准开关）。

6. 移除 CLI 符号链接（如果你安装过它）：

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

7. 可选地清除应用的设置：

   defaults delete io.bromure.agentic-coding
   

警告： 第 3 步会永久删除每个工作区的磁盘——克隆的仓库、未提交的工作、软件包缓存、shell 历史。请先推送或导出任何你在意的内容。

钥匙串中的凭据主密钥一旦其密文被删除便会成为孤立项；它是无害的，但你可以在钥匙串访问中搜索 io.bromure.agentic-coding.master-key 来移除它。