安装与首次运行

本章带你从一台空白的 Mac 走到一套可用的 Bromure Agentic Coding：应用需要什么、如何安装、首次启动时引导向导会做什么、Linux 基础镜像如何下载、校验并保持最新、应用把文件存放在哪里，以及如何干净地移除一切。读完本章后，请继续阅读快速上手。

系统要求

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

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

• 每次安装镜像前，都会先检查存放应用支持文件夹的卷上至少有 8 GB 可用空间，不足时会停止并给出清晰的提示。
• 在本地构建镜像期间，如果可用空间降到 1 GB 以下，监控程序会停止构建并给出明确的磁盘已满错误，而不是任其超时。

在会话旁边打开的可选内置浏览器使用自己的 Ubuntu + Chromium 镜像，会在你第一次安装它时单独下载；参见设置 › 浏览器。

安装应用

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

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

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

首次运行：引导向导

第一次打开应用时，会打开一个标题为 Bromure Agentic Coding 的设置窗口，而不是主窗口。这是一个六步向导：左侧一栏列出各步骤并勾选已完成的步骤，当前步骤占据右侧，该步骤的按钮位于底部。

每当应用还没有基础镜像，或有基础镜像却没有任何机器时（例如重新安装之后，或镜像是从命令行构建的），向导就会打开。如果基础镜像已经存在，安装步骤会从列表中去掉。当应用仅为镜像远程 Mac 而启动（参见远程访问与客户端），或作为没有窗口的无头代理启动时，向导不会打开。

各步骤为 欢迎、安装、凭据、选择、模型 和 完成。

1. 欢迎

第一步的标题是 欢迎使用 Bromure——“让我们开始吧。”一段简短的文字说明 Bromure 会在用完即弃的 Linux 虚拟机中运行你的编程代理，而向导会先安装基础镜像，然后提议导入你在这台 Mac 上已有的凭据。

点按 开始使用（或按回车键）开始安装。如果已经有基础镜像，按钮会显示 继续，并直接带你进入凭据步骤。

2. 安装

安装步骤在向导中运行基础镜像的安装。它的标题是 正在设置基础镜像——“正在下载镜像并应用补丁。这是一次性安装——请勿关闭窗口。”它会显示：

• 一行说明当前阶段的状态行。在常规的下载路径上，你会看到“Fetching image catalog…”，接着是“Downloading … (… GB)…”、“Verifying … checksum…”和“Expanding …”等行，安装推荐软件包期间显示“Customizing the image: …”（参见首次设置会做什么），最后是“Base image ready at … (v201)”。
• 一个带百分比的进度条。
• 一个默认折叠的 控制台输出 区域，显示安装程序的原始日志。文字可以选择，拷贝 会拷贝整份日志。屏幕上只保留最后 100 行。

如果出现错误，状态行会变成红色错误信息，并出现 关闭 按钮。

如果你在安装进行时尝试关闭窗口，应用会询问 取消重建基础镜像？——“镜像将处于不完整状态。启动新会话前你需要重新运行重建。”——并提供 取消重建 和 继续构建。

安装完成后，向导会自动进入凭据步骤。

注意： 安装镜像期间，可选的 SSH 远程访问服务器会暂停，并在之后重新启动（参见远程访问与客户端）。

3. 凭据

向导会提议查找你已经在用的凭据和配置文件：导入现有凭据？——“Bromure 可以读取这台 Mac 上已有的配置文件，并建议将其导入。”一个方框列出它会读取的内容：

• git 配置、已保存的密码、GitHub 和 GitLab CLI
• Docker、npm、PyPI、crates.io
• AWS、Kubernetes、DigitalOcean
• Claude、ChatGPT、Grok 和 Kimi 的 API 密钥与设置
• SSH 密钥、.env 文件

下方的注释重申了让这件事安全的原则：“真实值绝不会离开这台 Mac。虚拟机只会收到伪造值，由代理在外发请求时换回真实值。”

• 扫描这台 Mac 会读取这些文件，并进入选择步骤。在你于该步骤确认之前，不会导入任何内容。
• 暂不 会跳过扫描，不导入任何内容。你会直接进入模型步骤。

4. 选择

这是我找到的内容 会列出扫描找到的每个文件，每行一个，附有复选框、文件路径，以及其内容的简短说明（例如一个 git 身份和其中内嵌的令牌数量）。“勾选要导入的项目。每个密钥都留在这台 Mac 上；虚拟机只会看到伪造值。”如果什么都没找到，列表会显示“未找到配置文件。”

除了凭据文件之外，列表中还可能为每个代理列出一行，对应其自己的设置文件夹——例如你的 Claude Code 斜杠命令、子代理和记忆文件。这些会原样拷贝到机器中；其中不含任何机密。

• 添加 .env 文件… 让你手动选择一个 .env 文件。其中的变量会加入列表。
• 导入 n 项（没有勾选任何项目时显示 继续）会导入勾选的行并进入下一步。
• 跳过 不导入任何内容并进入下一步。

你导入的内容会成为第一台机器以及之后创建的每台机器的起点：git 身份和配置，以及镜像仓库、云和 git 的凭据，会放进每台新机器起始时所用的设置中。SSH 密钥是例外——它们只会拷贝到第一台机器。在代理设置中找到的代理 API 密钥会加入全局模型设置，让每台机器都能运行该代理。

注意： 扫描不会拷贝你的代理 CLI 在这台 Mac 上保有的登录（例如 Claude Code 自己的登录）。这些登录会自行续期，如果与 Bromure 共用，每当一方续期时另一方就会被登出。请改为在下一步从 Bromure 重新登录；这会创建一个属于它自己的独立登录。

5. 模型

此步骤只在首次运行时出现。你的模型——“登录你要使用的提供商，或粘贴 API 密钥。每个代理随后使用其提供商的默认模型——如有需要，可在右侧选择特定模型，现在或以后在“偏好设置 → 模型”中设置。”下方是与 偏好设置 › 模型 中相同的模型看板，左侧为 提供方 栏，右侧为 代理 栏。扫描导入的任何内容都已显示为已配置。

如果使用订阅（Claude、ChatGPT、Grok 或 Kimi），请选择该提供方的登录。登录在你的 Mac 上一台隐藏的临时机器中进行；你永远不会看到终端。看板上方的一张卡片会跟踪进度：

• “正在设置私有登录机器…”，接着是“请在浏览器中完成登录…”之类的进度行。
• 当提供方的登录不会自动打开浏览器时，卡片会显示 打开登录页面 按钮；如果是设备代码登录，则会显示 你的代码： 以及要输入的代码。
• 成功后，卡片会显示 已登录 提供方——“你的账号保存在这台 Mac 上；每台机器都可以使用。”点按 OK 关闭它。
• 取消 会停止登录并移除临时机器。

一次只能进行一个登录：在当前登录完成或取消之前，看板和 继续 按钮都会被停用。对于使用 API 密钥的提供方，请改为把密钥粘贴到该提供方的条目中。模型与提供方介绍了此看板上的每个提供方和选项。

你不必在这里设置任何内容。点按 继续 即可进入下一步；没有任何配置的代理会在你第一次启动它时提议登录。

6. 完成

全部就绪 确认设置已完成。如果你导入了文件，下方会显示导入内容的摘要；否则此步骤会显示“你的第一台机器已就绪——开始一个会话并选择任意代理。”

点按 开始使用 Bromure。向导会关闭，并且：

• 如果你还没有任何机器，应用会根据向导刚收集的设置创建一台名为 默认工作区 的机器。它的默认代理是你实际能启动的第一个：依次为 Claude Code、Codex、Grok、Kimi Code 和 Oh My Pi；如果都没有设置，则保持为 Claude Code，它会在启动时提议登录。
• 主窗口会在新建会话界面上打开，准备好开始你的第一个会话。快速上手从这里接着讲。

此后，应用会直接打开主窗口。

提示： 向导的凭据部分之后仍然可用。在侧边栏中按住 Option 键点按 虚拟机 旁边的 +，即可用向导创建新机器：它从凭据步骤开始、跳过模型步骤，并在完成时打开新机器的设置。应用菜单项 从我的配置新建工作区…（⇧⌥⌘N）作用相同。

首次设置做了什么

安装步骤会生成基础镜像：一个 24 GB 的稀疏磁盘，包含带 EFI/GRUB 引导的 Ubuntu 24.04（“noble”），每台机器都从它克隆而来。生成它的方式有两种；下载是首选，本地构建是回退方案。两者都写入临时的 .partial 文件，并一次性把结果替换到位，因此被中断的安装绝不会用一个写了一半的镜像取代一个可用的镜像。

预构建镜像下载

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

1. 目录。 应用会从 https://dl.bromure.io/images/201/img-catalog.json 获取对应其镜像版本的经过签名的镜像目录。目录标明当前镜像（ID、版本、SHA-256、大小）并列出设置步骤。它带有一个用签名应用更新的同一个密钥生成的 ed25519 签名；签名覆盖镜像的身份、其校验和以及每一条设置命令。未签名或无效的目录会被拒绝，而签名时间早于应用已接受目录的目录绝不会被使用（回滚保护）。
2. 下载。 下载压缩后的镜像并校验其 SHA-256。下载失败时最多重试 3 次，并在两次尝试之间重新获取目录。
3. 展开。 镜像会展开到 base.img.partial：大小为 24 GB，但实际只占用约 6–8 GB 的磁盘空间。
4. 定制镜像。 应用会下载一小组随镜像一起发布的镜像工具，并在一台临时辅助虚拟机中启动它们，由它在镜像内运行目录中的设置步骤（参见下一节）。进度会显示“Customizing the image: waiting for the prompt…”、“…: installing packages…”等等。
5. 替换到位。 创建一个全新的 EFI 变量存储，并把 base.img、efivars.bin、base.version 和 image-state.json 一起替换到位。

设置步骤：推荐软件包

已发布的镜像必须可以合法地再分发，因此只包含自由软件（Node.js、Docker、kitty、gh、glab、kubectl、doctl、awscli、azure-cli 等）。其他一切都在目录中声明为经过签名的设置步骤，并安装在你的 Mac 上、你的镜像副本中。5.0.0 版本附带的步骤为：

全新安装时，所有附带的步骤都会运行而无需额外提示：从向导开始设置（或运行 bromure-ac init）即为你的许可。之后发布的步骤需要你通过基础镜像更新中所述的 新的推荐软件包 提示明确批准。由于目录签名覆盖了每个步骤的命令，被篡改的下载服务器无法改变在你的镜像中以 root 身份运行的内容。

本地构建回退方案

如果下载因下载端的原因失败——你处于离线状态、服务器宕机，或者校验和或展开失败——应用会显示 镜像下载失败，附上错误信息和“Bromure 可以改为在本地构建镜像（约 10 分钟，结果相同）。”，并提供 本地构建 和 取消 按钮。它绝不会悄悄改用本地构建。（相比之下，bromure-ac init 命令会自动回退。）

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

1. 下载镜像构建工具，并缓存在支持文件夹中。
2. 创建一个全新的 24 GB 稀疏磁盘。
3. 启动一台一次性的构建虚拟机（4 个 vCPU、4 GB 内存），安装 Ubuntu noble、自由工具和 GRUB。
4. 应用与下载路径相同的目录设置步骤。

进度会显示“Building the image: downloading tools…”、“Allocating 24GB sparse disk…”、“Building the image: starting…”等等。在此路径上，进度条跟随安装程序的日志前进，并停在 97%，直到最后跳到“Base image ready”。

本地构建的设计能够扛住 VPN：所有软件包下载都经过宿主机侧代理服务器、构建虚拟机的网络 MTU 会在任何下载之前调低、没有网络时构建会尽早停止，而客户机内核崩溃会触发一次在全新磁盘上的自动重试。两个相关的应急手段：

• 如果构建虚拟机获取不到网络地址，构建会以 构建基础镜像时出现网络问题 失败，并提供 修复并重试（重启 macOS 的网络服务；会要求你输入管理员密码）或 取消。
• 在会丢弃大型数据包的 VPN 上（例如 MTU 1420 的 WireGuard），你可以自己设置构建虚拟机的 MTU：defaults write io.bromure.agentic-coding vm.mtu -int 1400。

你也可以随时特意选择本地构建：应用菜单中的 重新构建基础镜像… › 本地重建，或 bromure-ac init --build-local。

设置期间使用的网络端点

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

安装本身不会打开任何监听的网络端口；构建期间使用的宿主机侧软件包代理服务器只在一个临时的 localhost 端口上监听。

设置时间与磁盘用量

磁盘用量：

• 开始时： 存放 ~/Library/Application Support/BromureAC/ 的卷上至少需 8 GB 可用空间。
• 安装后： 基础镜像实际占用约 6–8 GB 空间（大小为 24 GB——稀疏磁盘中未使用的部分不占空间）。
• 每台机器： 每台机器的系统磁盘一开始都是基础镜像的 APFS 写时复制克隆，因此起初几乎不占空间，只会随着机器写入数据而增长。它的主目录磁盘也以同样的方式增长。

每个基础镜像版本只需设置一次。

命令行工具

应用不会主动在你的用户账户之外安装任何东西。要从终端操控 Bromure，请在应用菜单（Bromure Agentic Coding 菜单）中选择 安装命令行工具…。应用会询问 安装“bromure-cli”命令行工具？——“这会在 /usr/local/bin/bromure-cli 创建一个符号链接，让你可以从终端操控 Bromure（vm、exec、trace、…）。需要输入一次管理员密码。”点按 安装 并输入管理员密码即可；不会安装任何后台辅助程序。

此菜单项只能从已安装的应用程序包中使用。完整的命令参考见 CLI、API 与 MCP。

所有内容的存储位置

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

有两样东西有意存放在别处：

• 凭据主密钥保存在 macOS 数据保护钥匙串中，并标记为仅限本设备，因此绝不会离开这台 Mac。磁盘上的机密是 AES-256-GCM 密文；参见凭据。
• 应用程序包内含一个系统守护进程（io.bromure.fatclient-tunnel），在你镜像远程 Mac 时使用。它只在需要时注册，首次注册时会在 系统设置 › 通用 › 登录项 下显示一个批准开关；参见远程访问与客户端。

bromure-ac info 可随时打印已安装镜像的版本戳、大小和路径。

基础镜像更新

版本戳

已安装的镜像会把版本记录在 base.version 中。应用 5.0.0 版使用基础镜像 201。在同一版本上的任何重建、重新下载或补充应用都会加上一个点修订号（201 → 201.1 → 201.2）。image-state.json 会记录镜像的来源，以及已应用了哪些设置步骤。

应用会在其自身镜像版本的目录中查找更新，因此较旧的应用绝不会取用为较新版本制作的镜像。预构建镜像每周都会用最新的 Ubuntu 软件包重新发布，但这些每周重新发布会沿用相同的版本号，所以不会每周都要你更新。

更新提示

当你 Mac 上的镜像旧于应用期望的版本，或目录发布了更新的版本时，应用会在启动时显示 基础镜像有可用更新：“你的基础镜像是 X 版，而 Y 版已可用。当前镜像仍能工作 — 更新会下载新的预构建镜像（几 GB；本地重建作为备选）并重新应用推荐软件包。”

• 现在更新 会开始重新安装，优先下载。
• 稍后 会关闭提示，直到下次启动。无论选哪一个，当前镜像都能继续工作。

比应用期望更新的镜像仍然可以使用，也不会触发提示。

升级每台机器

安装新的基础镜像不会改变你已有的机器：每台机器都保留它所克隆自的系统磁盘。下次你启动一台磁盘来自较旧基础的机器时，应用会询问 有更新的基础镜像可用。——“这个工作区运行的是基础 v201；磁盘上已有 v201.1。现在升级吗？升级会重置工作区的磁盘——虚拟机内安装的一切都会被清除；你的项目文件夹不受影响。”

• 是，升级 会把机器的系统磁盘重置到新的基础上，然后启动它。主目录磁盘（以及 /home/ubuntu 中的一切）都会保留。
• 否 会照原样启动机器，并且在安装不同的基础镜像之前不再询问。
• 稍后提醒我 会照原样启动机器，并在一天后的第一次启动时再次询问。

每台机器的回答会分别记住。

新推荐软件包

当目录列出尚未应用到你镜像的设置步骤时，应用会在启动时以 新的推荐软件包 询问并列出它们：“推荐安装新的软件包：… Bromure 会把它们安装到基础镜像中（几分钟，在后台虚拟机中）。现有工作区继续运行；每个工作区的偏移提示将提供重置以获取它们。”

• 安装 会把步骤应用到 base.img 的写时复制克隆上，完成后把补充过的镜像替换到位；运行中的机器会继续运行。版本戳会加上一个点修订号（例如 201 → 201.1），因此之后每台机器都会提供上述升级。
• 稍后 会在下次启动时再次询问。

未经这项许可，任何内容都不会运行——设置步骤会在基础镜像内以 root 身份运行。

手动重建

要随时重新安装镜像，请在应用菜单中选择 重新构建基础镜像…。它会询问 要更新基础镜像吗？，并提供 下载预构建镜像、本地重建 和 取消。已有机器的磁盘不受影响。新镜像完成之前会继续使用旧镜像，因此重建期间你仍可以继续启动机器。对应的命令行命令是 bromure-ac init（优先下载）和 bromure-ac init --build-local。

下载会保留一份已安装推荐软件包的已发布镜像副本（stock.img，与基础镜像共享磁盘块）。只要目录仍指向同一个镜像，下载预构建镜像 就会从这份副本开始：跳过下载和智能体安装，只应用此后发布的软件包，并运行你的自定义脚本。因此重试或修改自定义脚本都很快。如果仍想从头开始（例如为了获取更新的智能体版本），请开启 重新下载并重新安装智能体，或运行 bromure-ac init --fresh。

保持应用更新

应用通过 Sparkle 进行自我更新。它每天检查一次 https://bromure.io/api/v1/release-agentic-coding，更新会用签名镜像目录的同一个公钥进行验证。要立即检查，请在应用菜单中 关于 下方选择 检查更新…。（开发构建没有此项。）

应用更新和基础镜像更新是分开的：只有当新版应用期望更新的基础镜像时，更新应用才会带来镜像更新。

迁移到新 Mac

没有内置的迁移助理。推荐的做法是全新安装，再拷贝你的机器数据：

1. 在新 Mac 上安装应用并走完向导。重新下载基础镜像比拷贝它更快、更干净。
2. 在两台 Mac 上都退出应用。
3. 把 ~/Library/Application Support/BromureAC/profiles/ 从旧 Mac 拷贝到新 Mac 的相同位置。每个子文件夹就是一台机器：它的设置（profile.json）、系统磁盘（disk.img）、主目录磁盘（home.img——你克隆的仓库、缓存和 shell 历史）以及 SSH 密钥。如果还想保留会话列表和对话，请一并拷贝 sessions.json、rooms.json 和 transcripts/ 文件夹。
4. 在新 Mac 上打开应用。你的机器会出现在 虚拟机 下。如果某台机器是从与当前安装的不同的基础镜像克隆而来，它会提供上述升级；选择 否 即可保留它当前的磁盘。

有三样东西有意不迁移：

• 凭据。 加密已存储机密的主密钥保存在 Mac 的数据保护钥匙串中，并标记为仅限本设备，因此旧 Mac 上加密的机密和登录无法在新 Mac 上读取。它们在各 profile.json 中的非机密信息会保留下来；请在每台机器的 凭据 面板中重新输入密钥，并在 偏好设置 › 模型 中重新登录（参见凭据）。
• 企业注册。 安装的身份证书只属于一次安装；请重新注册新 Mac（参见企业）。
• io.bromure.agentic-coding defaults 域中的 应用设置，除非你自己拷贝过去。

提示： 机器磁盘是稀疏文件，普通的网络拷贝会丢失写时复制节省的空间——在旧 Mac 上只占几 GB 的机器，在传输途中可能膨胀到它写入过的完整大小。请使用支持稀疏文件的拷贝方式（例如 rsync -aS），并先检查新 Mac 上的可用空间。

彻底卸载

若只想重置基础镜像而保留应用和你的机器，请运行 bromure-ac reset（加上 --yes 可跳过确认）。它会删除 base.img、efivars.bin、base.version、image-state.json，以及保存的下载（stock.img、stock-state.json），因此下次启动会重新运行设置。它绝不会触碰你的机器。

没有附带的卸载程序。要移除一切：

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

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

3. 删除支持文件夹——基础镜像、每台机器及其磁盘、会话、缓存，以及每次安装专属的 CA：

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

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

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

5. 删除日志文件夹：

   rm -rf ~/Library/Logs/BromureAC
   

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

7. 移除命令行工具（如果你安装过它）：

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

8. 可选：清除应用的设置：

   defaults delete io.bromure.agentic-coding
   

警告： 第 3 步会永久删除每台机器的磁盘——克隆的仓库、尚未提交的工作、软件包缓存、shell 历史——以及每个会话的对话。请先推送或导出任何你想保留的内容。

密文删除之后，钥匙串中的凭据主密钥会被留下。它是无害的，但你可以在钥匙串访问中搜索 io.bromure.agentic-coding.master-key 来删除它。