快速上手

本章将引导你完成使用 Bromure Agentic Coding 的第一个完整会话：创建工作区、选择代理及其身份验证方式、将项目文件夹共享到沙盒中、运行第一个任务、检查代理通过网络发送的内容，以及关闭会话以便日后再次继续。请预留约十分钟。

本演练在所有可能之处都刻意采用默认设置。你在此处接触的每一项设置，在手册后文都有完整的参考——沿途会提供链接，并在后续去向中汇总。

开始之前

你需要：

  • 已安装并至少启动过一次 Bromure Agentic Coding，且基础操作系统镜像已就绪——参见安装。（需要一台运行 macOS 14 或更高版本的 Apple Silicon Mac。）
  • 一种为编码代理进行身份验证的方式。对于 Claude Code——默认代理——可以是 Anthropic API 密钥，也可以是你能够登录的 Claude 订阅。这两种途径都会在下文第 4 步中介绍。
  • 可选地，你希望代理处理的 Mac 上的项目文件夹。一个小型 git 仓库是最理想的首次测试对象，但任何文件夹都可以。

在开始之前有一个理念值得牢记：代理运行在一个一次性的 Ubuntu 虚拟机内，而你的真实凭据永远不会进入该虚拟机。虚拟机始终只持有伪造的占位令牌；当请求离开你的 Mac 时，宿主机端的代理服务器会在那一刻将其替换为真实值。这就是传输边界，也正是本演练要求你将 API 密钥粘贴到应用中、而非粘贴到终端里的原因。

创建你的第一个工作区

工作区是隔离的基本单元：一个 Ubuntu 虚拟机，拥有自己的系统磁盘、自己的持久化主文件夹、自己的代理、凭据和安全策略。你可以创建任意数量的工作区；本演练创建一个。

  1. 打开主窗口。左侧边栏标题为 工作区；其底部有一个黑色圆形 + 按钮（工具提示：新建工作区）。点击它。

  2. 一个设置编辑器会在标题为 新建工作区 的窗口中打开，它根据你的偏好模板预填充，并命名为“Default workspace”（若该名称已被占用则自动编号）。当前显示的是 通用 窗格。输入你自己的名称——例如 My First Project。名称是唯一必填的字段；本演练中的其他一切都是可选的润色。如果愿意，可以选择一个 颜色——它会为侧边栏中该工作区的图块着色。

先别急着点击 创建——有两个窗格值得先看一看。

选择代理与身份验证

  1. 点击编辑器分类侧边栏中的 代理。该窗格为每个受支持的代理显示一张卡片——Claude Code、Codex 和 Grok Build——每张卡片都带有一个启用开关。Claude Code 默认已启用，并带有橙色的 主 标签：主代理是在会话的第一个标签页中自动启动的那一个。其他已启用的代理也都已安装并完成身份验证，但需要你自己从新标签页中启动它们。
工作区编辑器的“代理”窗格，显示带有“主”标签的 Claude Code 卡片、四种身份验证模式、Anthropic API 密钥字段，以及被禁用的 Codex 和 Grok Build 卡片

在 Claude Code 卡片内，你会看到四种身份验证模式：API 令牌、带有 注册… 链接的 订阅（交互式登录）、Bedrock (AWS) 和 本地模型（在安装本地模型之前，它会显示为灰色并附注“— 在“本地模型”中下载模型”）。从前两种中选择一种：

  1. 如果你有 Anthropic API 密钥： 选择 API 令牌，并将密钥粘贴到 Anthropic API 密钥 字段中。密钥以加密形式存储在宿主机上；虚拟机只接收一个保留结构的伪造值，而代理服务器仅在向 Anthropic 发出的请求上替换为真实密钥——不会在其他任何地方替换。目前请保持 使用前需要批准 复选框关闭；开启它会让应用在每个会话首次使用该密钥时请求你的许可（参见凭据）。

  2. 如果你有 Claude 订阅： 选择 订阅（交互式登录）——这是出厂默认设置——并点击 注册…。Bromure 会启动一个临时的、用完即弃的虚拟机，该虚拟机无法访问你的文件夹或凭据，在其中运行真实的 Claude 登录，并在你 Mac 的默认浏览器中打开提供商的登录页面。在那里登录；在流程超时之前你有几分钟时间。成功后，捕获到的令牌会以加密形式存储在宿主机上，用完即弃的虚拟机被销毁，应用会询问要将该注册共享给 所有工作区 还是 仅此工作区。完成注册后，卡片会显示一个绿色印章以及 重新注册… 和 忘记 控件。你的工作区虚拟机从不自行执行 OAuth，也从不持有真实令牌——宿主机在传输过程中注入它们并处理刷新。

  3. 首次会话所需的“代理”窗格配置到此为止。（同时启用 Codex 或 Grok Build 的方式相同——每张卡片都有自己的身份验证模式——但今天用一个代理就足够了。）

共享项目文件夹

  1. 点击分类侧边栏中的 文件夹。该窗格列出将被挂载到虚拟机中的宿主机文件夹。正如说明所述，每个文件夹都以其真实名称挂载——例如你 Mac 上的 ~/Documents 在虚拟机中显示为 ~ubuntu/Documents——每个工作区最多可挂载 8 个文件夹。全新的工作区会显示“未共享任何文件夹”。
工作区编辑器的“文件夹”窗格，为空，带有“添加文件夹…”按钮
  1. 点击 添加文件夹…，并在目录选择器中选择你的项目文件夹。它会连同完整的宿主机路径出现在列表中（如果你改变主意，稍后可用减号按钮将其移除）。在虚拟机内，它将实时位于 /home/ubuntu/<basename>——是同一批文件，而非副本，因此代理所做的更改会即时反映在你的 Mac 上。

注意： 共享文件夹是可选的。虚拟机 /home/ubuntu 下的所有内容都会按工作区持久化，因此你也可以在虚拟机内克隆一个仓库，让沙盒与你 Mac 的文件系统完全隔离。删除工作区绝不会触及共享的宿主机文件夹。

  1. 点击 创建。编辑器关闭，你的工作区会以状态标签 关闭 出现在侧边栏中。

启动会话

  1. 点击侧边栏中该工作区所在的行。右侧舞台会显示该工作区的仪表板：名称下方有一个 关闭 标签，以及 CPU、内存、vCPU、磁盘 和 运行时间 的卡片（首次启动前大多是横杠和零——磁盘在首次启动时创建）、一份列出你的代理和身份验证模式的 配置 摘要、护栏和提示注入扫描的状态，以及你共享的文件夹。点击右上角的 启动 按钮。
主窗口：带有两个工作区和 + 按钮的“工作区”侧边栏，以及一个已停止工作区的仪表板，显示 CPU、内存、vCPU、磁盘和运行时间卡片、一份“配置”摘要以及“启动”按钮

  1. 首次启动时，Bromure 会将工作区的私有系统磁盘创建为共享基础镜像的写时复制克隆——这是瞬时完成的，几乎不占用磁盘空间——并以 4 个 vCPU 和仪表板上显示的内存（默认按你的 Mac 配置：4、6 或 8 GB）启动虚拟机。虚拟机启动期间，一个带有工作区名称和进度条的动画叠层会覆盖窗格；当客户机的第一个终端出现时它便会淡出，通常在数秒内完成。如果 30 秒内没有终端出现，叠层会翻转为一个 DIVE FAILED 面板，带有 继续等待 和 重置基础镜像… 按钮——如遇此情况请参见故障排除。

  2. 启动完成后，你会在舞台上看到一个终端，主代理——Claude Code——已经在其中运行，等待接收提示。你无需在虚拟机内运行 claude login；身份验证已在传输边界处理完毕。在侧边栏中，工作区的状态圆点现已变为绿色，状态标签显示为运行中，其第一个标签页（以前台程序标记，例如 claude）与一个 Docker 节点一起嵌套在工作区行下方。窗口工具栏现在会显示这个虚拟机的一组控件：以可点击复制的标签形式显示的 IP 地址，以及用于浏览文件、重启、检查追踪、编辑工作区、将会话弹出为独立窗口、切换浏览器和仓库文件窗格的按钮。

运行你的第一个任务

  1. 在 Claude Code 提示符处输入一个任务，通过共享文件夹在虚拟机内的路径引用它。例如：

    Read the code in ~/my-project and summarize what it does.
Then add a README.md with build instructions.

    留意侧边栏中标签页图标上的状态圆点：代理工作时它会脉动橙色，代理完成时变为绿色，代理需要你输入时变为红色。

  2. 由于共享文件夹是实时挂载，代理写入的 README.md 会立即出现在你的 Mac 上——如果愿意，可在访达中查看。如果你的文件夹是一个 git 仓库，当活动标签页的工作目录进入该仓库时，仓库文件浏览器窗格会自动打开，以 IDE 风格的树状结构显示 git 状态和逐文件差异；你也可以随时用 ⌃⌘E 切换它。按 ⌘T 可在代理旁边额外打开一个纯 shell 标签页——每个标签页都是同一个虚拟机内 tmux 会话的一个窗口。

  3. 代理所做的其他任何事情——apt install、npm install、在虚拟机主文件夹中写入临时文件——都停留在沙盒内部。系统磁盘和主文件夹在会话之间持久化，且两者稍后都可以独立重置（工作区）。

检查追踪

  1. 按 ⇧⌘I（或点击 检查追踪 工具栏按钮）打开追踪检查器。新工作区以 AI 请求详情 级别记录：代理发出的每个网络请求都会列出主机、状态和延迟，对于已知的 LLM 主机，还会捕获完整的请求和响应正文。选择其中一个发往 Anthropic 的请求，检查器会将其呈现为一段对话——带有令牌计数的提供商和模型标头、系统提示，以及以聊天气泡形式呈现的用户、助手和工具消息。

  2. 在你的第一份追踪中有两点值得注意。第一，替换报告：虚拟机持有的伪造 API 令牌在传输过程中被替换为你的真实凭据，每个请求恰好替换一次，且范围限定于该提供商的主机。第二，所有捕获的内容都保留在你的 Mac 上，静态加密。追踪级别、保留上限和泄露警告详见追踪。

关闭与恢复

  1. 关闭会话：将鼠标悬停在侧边栏的工作区行上并点击其 × 按钮（或在其最后一个标签页上按 ⌘W）。新工作区的关闭操作被设为 询问，因此会出现一个提示——“关闭“My First Project”？”——带有 在后台运行、挂起、关机 和 取消 按钮，以及说明：“在后台运行会保持虚拟机运行，以便你稍后重新连接。挂起会将其状态保存到磁盘。关机会将其断电。”

  2. 点击 挂起。虚拟机的内存被快照到磁盘，侧边栏行的状态标签变为 已挂起。什么都不会丢失——代理的对话不会丢，你的 shell 历史不会丢，标签页布局也不会丢。

  3. 恢复：点击该工作区，并在其仪表板上按 恢复（或使用该行的 ⋯ 菜单 → 恢复）。会话几乎瞬时恢复，正是你离开时的样子——相同的终端，Claude Code 正处于对话中途。

  4. 如果你希望关闭时始终采用相同的行为，打开该行的 ⋯ 菜单 → 编辑…，并在通用窗格中将 关闭窗口时 设为 挂起（或 在后台运行 / 关机），这样提示便不会再出现。参见设置——通用。

提示： 已挂起或已关机的工作区会保留其系统磁盘和主文件夹。销毁数据始终是一项明确的操作——重置磁盘、清除主文件夹… 或 删除工作区——即便删除工作区也绝不会触及你共享进去的宿主机文件夹。

后续去向

  • 概念 —— 你刚才所做操作背后的思维模型：工作区、虚拟机生命周期、传输边界，以及各部分如何协同。
  • 工作区 —— 复制、重置和删除工作区；存储层、检查点，以及每个新工作区所派生自的偏好模板。
  • 会话 —— 标签页和 git 工作树、终端网格、代理浏览器窗格、进出虚拟机的文件传输，以及所有键盘快捷键。
  • 设置参考 —— 每个设置窗格各占一页，包括本演练中提到的代理和文件夹。
  • 凭据 —— 完整的凭据目录（git 令牌、SSH 密钥、AWS、Kubernetes、容器注册表、数据库等等）、批准提示，以及伪造到真实的替换如何详细运作。
  • 追踪 —— 追踪级别、追踪检查器和泄露检测。
  • 供应链和提示注入 —— 在让代理面对不受信任的代码之前，你可以叠加到工作区上的各项防护。
  • Fusion和本地模型 —— 同时用多个模型回应提示，以及在你的 Mac 上而非云端运行模型。
  • 自动化与 CLI —— 从脚本、HTTP API 和 bromure-cli mcp 服务器驱动工作区。