概念与架构

Bromure Agentic Coding 在你 Mac 上的硬件虚拟化 Linux 机器中运行 AI 编程代理，并在代理无法绕过的单一点上实施每一项安全管控。本章定义手册其余部分所依赖的术语——会话、机器、房间、分支、宿主机与客户机、传输边界——并说明各部分如何组合在一起。除了快速上手之外，如果你只读一章，就读这一章。

会话、机器、房间与分支

你在应用中所做的几乎一切，都由四种对象构成。

会话

会话是与一个代理、在一个文件夹、在一台机器上的一段对话。你从新建会话界面开始它；它有一个标题（代理会根据你的第一条消息设置，你也可以重命名）、一个代理（Claude Code、Codex、Grok、Kimi Code 或 Oh My Pi）、一台机器，以及该机器中的一个工作文件夹。侧边栏列出的、聊天显示的，都是会话。

在机器内部，会话就是在自己的终端标签页中运行的代理。你很少需要看到那个标签页，但也可以看：工具栏上的 Linux 胶囊（⌥⌘U）或会话菜单中的 在 Linux 终端中打开 会切换过去，而胶囊（此时显示 会话）会切换回来。

会话比代理进程存续得更久。当代理退出，或其机器关机时，会话会连同对话留在侧边栏中，而你的下一条消息会在同一段对话上重新启动代理。参见会话主页。

机器

机器是一台隔离的 Linux 虚拟机，连同它的设置和持久存储。主窗口称之为机器；设置编辑器、几个菜单（新建工作区…、工作区）和命令行则称之为工作区（在内部以及 profile.json 等文件名中称为配置文件）。这三个词指的都是同一样东西。

机器定义了适用于其上每个会话的凭据、共享文件夹、环境、MCP 服务器、护栏、模型覆盖、外观和虚拟机大小——也就是你在设置编辑器中编辑的一切。每个代理在每台机器上都可用。无论是否在运行，机器都存在，而且同一台机器上可以同时运行许多会话，每个都有自己的文件夹和终端标签页。

常见的做法是每个项目或每个凭据边界一台机器：同一台机器上的会话共享其磁盘、凭据和网络身份。机器列在侧边栏的虚拟机下；参见机器。

机器运行期是机器的虚拟机持续开机的一段时间：从机器启动或恢复时开始，到关机或挂起时结束。有些状态属于运行期而不属于机器：你授予的凭据批准保存在内存中，会在运行期结束时撤销，而每次开机的配置共享会在每次启动时重建。

房间

房间把处理同一件事的会话归在一起。打开房间时，会以实时聊天网格的形式并排显示其会话，并提供一个可以发给其中任意一个或同时发给全部的输入区。房间可以有自己的总机，这是一个只掌握该房间会话的会话。房间中的会话可以在不同的机器上运行。参见房间。

分支会话

分支会话是从另一个会话开始、位于自己 git 分支上的会话，存在于同一台机器上同一个仓库的另一份检出（git 工作树）中。它在不碰原会话文件夹的情况下工作，而当你对结果满意时，就审查并合并回去。参见分支与审查。

由其他会话启动的会话

有两种会话是替你启动的，而不是由你启动：

• 受托会话。 代理可以把一项工作交给新的子会话——在它自己的分支上，或另一台机器上——并等待结果。子会话会列在启动它的会话下面。代理也可以通过 @昵称 向已有的会话发送请求。参见代理协同工作。
• 总机。 一个掌握所有其他会话的 Claude Code 会话。当有两个或更多会话在进行时，它就会出现在侧边栏中，在你上次使用的机器上的 ~/.bromure/switchboard 文件夹中工作，并能在严格的规则下替你阅读、回答和启动会话。房间专属的总机在 ~/.bromure/rooms/<room> 中工作，只能看到该房间。参见总机与消息。

自动化运行和编码任务也以会话的形式运行，完成时归档；参见自动化和编码任务。

会话状态

侧边栏按会话需要你做什么来分组，而不是按它们运行在哪台机器上：

另有两处存放不属于这些分组的会话：

• 已归档 是会话列表底部的折叠区，用来存放你收起的对话。已归档的会话仍然可以阅读，一条消息就能让它回来。完成超过三天的会话会自动归档，但房间中的会话和总机除外。受托会话、编码任务和自动化运行一完成就会归档。
• 如果会话的机器或文件夹已不存在，它会以淡色显示为“机器已移除”或“文件夹已移除”。已删除机器的会话会集中在列表末尾的一行中，并附有 删除 按钮。

宿主机会保存每个会话对话的副本（在 ~/Library/Application Support/BromureAC/transcripts/ 中），并在代理运行时更新，因此已暂停、已完成或已归档的会话无需启动其机器即可阅读。

宿主机与客户机

Bromure Agentic Coding 中的一切都处于一条明确界线的某一侧：

• 宿主机是你的 Mac——搭载 Apple 芯片的 macOS 14 或更高版本——以及在其上运行的 Bromure Agentic Coding 应用。宿主机保存所有敏感内容：你的真实凭据（用 macOS 钥匙串中的主密钥加密）、你的登录、替代理与互联网通信的 MITM 代理服务器、Bromure 根 CA 的私钥、追踪记录和安全时间线，以及应用的窗口、聊天和终端。你输入内容的聊天和终端是在宿主机上绘制的，而不是在虚拟机内部。
• 客户机是代理实际运行的 Linux 虚拟机——Claude Code、Codex、Grok、Kimi Code、Oh My Pi 或普通的 shell 工具，以及它们安装和接触的一切：克隆的仓库、软件包缓存、Docker 容器、virtualenv。客户机在设计上被视为不可信。它不持有任何真实机密，只有刻意设为无效的伪造凭据，而它的出站网页流量会经过宿主机的代理服务器。

两端通过两条狭窄的通道通信：vsock（virtio 套接字，一条不需要网络的宿主机–客户机通道），用于控制、终端、MCP 服务器和代理服务器路径；以及一个私有虚拟网络，用于普通的 IP 流量。两者都会在下文介绍。

正是这种划分让安全承诺变得具体：遭到提示注入或行为异常的代理，可以在客户机内部为所欲为，但它无法读取真实的 API 密钥、无法用真实的 AWS 秘密签名，也无法提取 SSH 私钥——这些东西在它那一侧根本不存在。

架构一览

请从下往上阅读这张图：代理在机器的虚拟机中工作；它的 HTTPS 通过 vsock 离开，送到宿主机的代理服务器，那是伪造凭据变成真实凭据的唯一地方；应用通过另外的 vsock 桥接连接到虚拟机的终端；而可选的用完即弃浏览器虚拟机共享同一个私有网络，因此能加载代理的开发服务器。

除了机器和浏览器虚拟机，应用还能运行三种它自己管理的虚拟机，全都位于同一个私有网络上：Kubernetes 集群节点和一个容器镜像仓库（参见 Kubernetes 集群与注册表），以及把总机连接到 Signal、WhatsApp 或 Slack 的消息连接器（参见总机与消息）。它们列在侧边栏的虚拟机下，但不是机器：其中没有代理在运行。

机器的虚拟机

每台机器的虚拟机都是在 Apple 的 Virtualization.framework 下运行的 Ubuntu 24.04 客户机；该框架需要 Apple 芯片，并且只支持 ARM64 客户机。它以 4 个 vCPU 和机器 资源 面板中设置的内存大小，从两个虚拟磁盘启动：

• disk.img——系统磁盘。机器第一次启动时，它会作为共享、已签名的 Ubuntu 基础镜像的 APFS 写时复制克隆创建（参见安装与首次运行）：克隆瞬间出现，在客户机写入之前不占用新的磁盘空间。之后的启动会复用同一个克隆，因此你用 apt install 安装的软件包、拉取的 Docker 镜像以及其他系统级更改都会保留下来。
• home.img——存放 /home/ubuntu 的私有 ext4 磁盘，作为第二块磁盘挂载。默认大小为 16 GiB，但只会随着内容的填入占用空间，并会在客户机中删除文件时在宿主机上缩小。主目录在 重置磁盘 后仍会保留，这就是为什么你的仓库、点文件、shell 历史和每个会话的文件夹，在系统磁盘重置后依然存在。

客户机还会挂载一些每次开机的小型共享：一个只读的元数据共享，载有该次开机的配置（伪造凭据的环境文件、代理服务器设置、Bromure CA 证书、客户机代理程序、MCP 配置），以及一个可写的发件箱，供客户机向宿主机报告（其 IP 地址、终端标签页、代理状态）。两者都会在每次启动时重建，不保存任何持久状态。你 Mac 上最多 8 个文件夹也可以共享给客户机；它们会出现在主目录中。

设计上的持久化——与 Bromure（Web）的对比

Bromure Agentic Coding 与它的姊妹应用——网页浏览器 Bromure——共享代码库，而两者有意在生命周期上做出相反的选择：

写代码需要持久的状态——克隆的仓库、软件包缓存、virtualenv、shell 历史——因此每个会话结束就丢掉虚拟机，会让代理毫无用处。Bromure Agentic Coding 不去管控虚拟机的状态，而是管控虚拟机被允许持有什么：没有任何真实机密，也没有未经中介的互联网通路。用完即弃的机器仍然是一种选择：重置磁盘 会从基础镜像重新克隆系统磁盘，回退主目录… 会把主目录回退到较早的检查点，bromure-cli vm run --rm 会创建一台停止时即删除的一次性机器，而入侵处理流程会清除受污染的磁盘和主目录，同时保留你的设置和密钥。

浏览器虚拟机

Bromure（Web）有一部分在 Bromure Agentic Coding 中延续了下来：会话旁边的内置浏览器。当你（或代理）打开它时，机器会得到第二台用完即弃的虚拟机，运行 Ubuntu 和 Chromium，克隆到临时文件夹中，并在浏览器关闭时删除。浏览状态默认会被丢弃，除非机器开启了 保持网站登录状态，这会把 Chromium 的配置文件保存在每台机器专属的加密磁盘上。浏览器虚拟机与机器位于同一个私有网络上，因此能加载代理刚刚启动的开发服务器。参见嵌入式浏览器。

机器状态：关闭、已挂起和运行中

每台机器始终处于三种持续状态之一。机器开机时，你还会短暂看到 正在启动…。

展开侧边栏底部的虚拟机即可看到你的机器。点按一台机器会显示其仪表板：运行时实时显示 CPU、内存、磁盘和运行时长，关机时则显示其规格和配置，并附有 启动 或 恢复 按钮。在关机的机器上开始会话，会替你启动它。

几条值得了解的规则：

• 挂起是内存快照，不是存档文件。 要恢复它，虚拟机的配置必须与保存时相同。如果你更改了快照所依赖的设置——例如内存大小或共享文件夹——机器就会改为全新启动，而且不会影响任何文件。应用日志会指出更改了什么。
• 快照绝不会比它的磁盘存在得更久。 重置或清除系统磁盘时，也会一并丢弃任何已保存的内存快照，因为全新的磁盘加上过时的内存会立刻损坏。
• 关闭不等于清除。 已关机的机器会无限期保留其系统磁盘和主目录。真正的删除始终是明确的操作（重置磁盘、回退主目录…、删除工作区），或由入侵处理流程强制执行。

关闭操作

关闭机器窗口时会发生什么，是每台机器各自的选择（通用 面板中的 关闭窗口时）：在后台运行（机器在没有窗口的情况下继续运行）、挂起、关机，或 询问——默认值，每次都会询问。参见机器。

传输边界

传输边界是这个产品的核心理念：客户机所有的出站网页流量都会经过宿主机侧的中间人（MITM）代理服务器，而每一项保护——保管机密、限定凭据范围、供应链扫描、提示注入检测、个人数据保护、追踪——都在这一点上实施。代理无法绕过它，因为在它那一侧没有任何有用的东西。

端到端的流程：

1. 客户机只持有伪造值。 机器启动时，宿主机会把刻意设为无效的替代凭据写入虚拟机——例如 ANTHROPIC_API_KEY 之类的环境变量，以及 ~/.git-credentials、~/.docker/config.json、~/.kube/config 之类的文件。伪造值保留真实值的形状（sk-ant-api03-brm-…、ghp_… 形式、brm_…），让客户端的检查接受它们，而且在同一次安装中保持不变，因此工具永远不会在两次运行之间看到密钥改变。对应的真实值会加载到宿主机上代理服务器的内存中，各自绑定到所属的主机。
2. 客户机的 TLS 终结于代理服务器。 客户机中的每个 shell 都会导出 HTTPS_PROXY=http://127.0.0.1:65534，这是虚拟机内的一个端点，通过 vsock（端口 8443）以隧道连到宿主机的代理服务器。此外，宿主机的虚拟网络交换机会把客户机发往 80 和 443 端口的出站连接转向同一个代理服务器，因此即使某个工具忽略代理变量，也照样要经过它。代理服务器会出示由 Bromure 根 CA 签名的逐主机证书，检查请求，并重新加密后发往真实的服务器。
3. 伪造值只在离开时才变成真实值。 代理服务器会把每个伪造值换成真实值——API 密钥和令牌通过请求头替换、订阅登录背后的替身密钥、AWS 用完整的 SigV4 重新签名（客户机用假的秘密签名；宿主机去掉该签名，再用真的重新签名），以及 SSH 通过 vsock 用 ssh-agent 签名。替换只应用于已注册的主机及其子域名，绝不应用于长得相似的域名，因此为 api.anthropic.com 注册的凭据绝不会被注入到其他域名。

机器可以在其 防护栏 面板中关闭透明转向；代理变量、凭据替换、追踪和护栏仍然生效。参见凭据与传输边界。

Bromure 根 CA

代理服务器之所以能读取客户机的 TLS，是因为客户机信任它。首次启动时，应用会创建一个每次安装专属的证书颁发机构——Bromure Agentic Coding 根 CA——其公开证书会在开机时通过元数据共享安装到每台虚拟机的信任存储中。私钥永远不会离开宿主机（它位于 ~/Library/Application Support/BromureAC/ca/，只有你能读取）。你的 Bromure 虚拟机之外没有任何东西信任这个 CA：它不能用来拦截你 Mac 自身的流量，而删除 ca/ 文件夹只会在下次启动时创建一个新的 CA。

设计上的故障关闭

设计是失败即关闭的：万一客户机流量绕过了代理服务器——例如在不常见端口上的原始套接字，或蓄意的绕过尝试——它唯一能出示的凭据也只是没有服务器会接受的伪造值。AWS 会返回 InvalidSignatureException；API 提供方会拒绝替身密钥。绕过边界对攻击者毫无好处，因为边界不是检查机密的地方——它是机密唯一存在的地方。

失陷检测器

边界还会留意相反方向的滥用：数据外泄。代理服务器会扫描每个出站请求，查找为该机器注册的任何伪造令牌。伪造值只有一个正当的目的地——为它生成的那台主机——因此伪造值如果被发往别处，就是代理企图泄露凭据的特征。代理服务器会拦下请求、暂停机器并提醒你，让你选择关闭机器、阻止请求，或在会话剩余时间内允许该目的地。由于外流的只是伪造值，真实凭据根本无需轮换。完整的凭据模型，包括逐个凭据的批准提示和有时限的授权，见凭据与传输边界。

什么会持久化，什么不会

Bromure Agentic Coding 明确界定哪些内容会保留。每台机器的文件位于 ~/Library/Application Support/BromureAC/profiles/<uuid>/；你的会话则位于旁边的支持文件夹中。

持久——关机和应用重启后仍会保留：

临时——自动重建或删除：

由此可以得出两点。第一，关闭窗口或结束会话本身绝不会删除任何东西——具有破坏性的操作都是明确的，并且需要确认。删除会话会把其对话从应用中移除，但会把其文件夹留在机器上。第二，当你想要从头开始时，有一系列选择：回退主目录…、重置磁盘（主目录会保留）、删除机器，或用 bromure-cli vm run --rm 创建一次性机器。

注意： 从你 Mac 共享的文件夹是你磁盘上的普通文件夹，位于 Bromure 的存储之外。任何 Bromure 操作都不会删除它们——包括入侵清除在内——清除提示也会说明这一点。

宿主机与客户机桥接（vsock）

Mac 与客户机之间所有交互式的内容都通过 virtio 套接字传递——这是直接连接宿主机与客户机、独立于虚拟机网络之外的通道。你永远不需要配置它们，但知道它们的存在，有助于阅读追踪记录或故障排除。每个桥接都使用一个编号的 vsock 端口：

机器虚拟机的桥接：

内置 MCP 服务器——宿主机提供给机器上每个代理的工具，各自通过客户机中的一个小型垫片连接：

浏览器虚拟机的桥接： 配置（5000）、文件传输（5100）、Chrome DevTools Protocol（5200）、链接中继（5300）、摄像头（5400）、标签栏（5810）和网络追踪（5900）。

剪贴板

终端标签页没有单独的剪贴板服务——剪贴板通过终端本身传递。在客户机中拷贝（tmux 选区，或任何使用 OSC 52 的程序）会进入 macOS 剪贴板；在终端中 ⌘C 拷贝选区；⌘V 粘贴到客户机中。在浏览器中，客户机的剪贴板代理程序负责在 Mac 与 Chromium 之间拷贝和粘贴。

文件传输

文件在 Mac 与机器之间有三种传递方式，都在机器中介绍：共享文件夹（存放在你 Mac 上的项目文件的常规途径）、文件窗格（通过端口 5800 的 shell 桥接拖入拖出），以及附件——任何拖放或粘贴到聊天或终端中、最大 512 MB 的文件，都会拷贝到机器中，并把其路径交给代理。

网络

NAT 模式（默认）

所有 NAT 模式的机器都连接到应用内的单个软件网络交换机，再通过单个 macOS vmnet NAT 接口连上互联网。因此：

• 一个私有子网。 全新安装会在 172.16.0.0/12 中随机挑选一个私有 /24 并保留下来，避开你的 Mac 已经在用的任何 172.x 网络（例如 Docker 的）。偏好设置 › 资源 中的开关（工作区子网——使用私有子网（避免多个远程实例之间的冲突））会显示子网，而 随机生成 会挑选一个新的子网；更改会在你的机器下次启动时生效。开关关闭时，应用使用 192.168.64.0/24，如果你的局域网已在使用该范围，则改用另一个空闲的 192.168.x.0/24。
• 应用在该交换机上运行自己的 DHCP 服务器，租约保存在 dhcp-leases.sqlite 中。每台机器都有固定的 MAC 地址（在 profile-macs.json 中），因此重启后通常会保持相同的 IP 地址。机器菜单中的 拷贝 IP 地址 和机器的仪表板会显示当前地址。
• 虚拟机之间可以互通。 机器、浏览器虚拟机、集群节点和镜像仓库在设计上位于同一个网络，因此浏览器可以加载在机器上运行的开发服务器，两台机器也能使用彼此的服务。仪表板的监听端口列表会把每个可访问的服务显示为你从 Mac 连接时要用的 <IP>:<端口>。
• 与外界隔离。 从你的 Mac 可以访问这些虚拟机，但从物理局域网则不行，而且除非你明确发布某项服务（例如从监听端口列表通过 Cloudflare 快速隧道），否则其他任何东西都无法连接到它们。
• 仅限 IPv4。 客户机中的 IPv6 已关闭，localhost 解析为 127.0.0.1。

客户机的网络 MTU 默认为 1280——在 VPN 和企业网络后面都安全的值——可以用 defaults write io.bromure.agentic-coding vm.mtu -int <数值> 调高。

请记住，普通的 IP 流量并不是凭据移动的途径：网页流量会被引向代理服务器，而任何绕过它的流量都只带着伪造凭据——也就是上文所述的失败即关闭特性。

桥接模式（按机器）

机器也可以改为加入你的物理局域网：在其 资源 面板中把 网络 设为桥接并选择一个接口，虚拟机就会以路由器分配的自有地址出现在局域网上（适用于其他设备必须直接访问它的情况）。如果所选接口在启动时不可用，机器会回退到 NAT。参见设置 › 资源。

快速启动

有两件事让机器能够快速启动：

• 写时复制磁盘。 新机器的系统磁盘是基础镜像的即时克隆而非完整拷贝，因此第一次启动不必等待写入数 GB 的数据。之后的冷启动就是普通的 Linux 开机。
• 挂起与恢复。 已挂起 的机器会完全跳过开机：恢复其内存快照后，就从停下的地方继续，包括终端标签页和代理。

机器不会被池化或预先开机：每台机器都是一台独立的持久计算机，因此没有可以互换、需要预热的东西。用完即弃的浏览器虚拟机是例外；它来自与 Bromure Web 相同的池机制。