CLI、API 与 MCP

应用能做的一切，也都能在不打开窗口的情况下操作。应用的二进制文件——位于 Bromure Agentic Coding.app/Contents/MacOS/ 内的 bromure-ac——同时也是一个多命令 CLI、一个 HTTP 控制平面、一个供外部 AI 工具使用的 MCP 服务器，以及一个 AppleScript 目标。在每台虚拟机内部，一组内置的 MCP 服务器让代理拥有自己的 Bromure 视图。本章是这一切的参考资料。

由外而内，这些接口依次为：

• bromure-cli 命令行——类似 Docker/kubectl 的 CLI，用于机器、虚拟机、终端、命令、追踪、模型、远程访问和注册。
• 控制平面——以 HTTP 上的 JSON 提供相同的操作，位于仅限所有者的 Unix 套接字上，并可选择位于环回 TCP 端口上。
• AC MCP 服务器（bromure-ac mcp）——让你 Mac 上的 AI 工具（Claude Code、Claude Desktop）管理应用。
• 客户机内的 MCP 服务器——内置于每台虚拟机：浏览器、自动化、基础设施、委派，以及供特定会话使用的任务看板和总机。
• AppleScript——Bromure AC Suite 字典。

在本章和 CLI 中，机器都称为工作区（它在设置编辑器和命令行中的名称）。代理对话意义上的会话，通过 /agent-sessions 路由访问；较旧的 /sessions 路由，以及 CLI 和 AppleScript 中的 session 一词，指的是机器的窗口。

控制平面：套接字与 API

每个接口都通过以下两种传输方式之一，以 HTTP 与运行中的应用通信：

CLI 永远不会直接与虚拟机通信。每个子命令都是控制套接字上的轻量 HTTP 客户端，因此相同的命令在本地可用，而且——当套接字通过 SSH 隧道传输时——也能从富客户端对远程实例使用。当你运行需要代理的命令、而没有代理在运行时，CLI 会自动启动一个无窗口的后台代理（bromure-ac run --headless），并等待最多 40 秒让它响应 /health。只读命令（vm ls、describe、trace …）不会自动启动；它们会改为显示 No bromure-ac agent running.。

注： 只要应用在运行，控制套接字就始终可用，且与 启用自动化服务器 开关无关。该开关只控制端口 9223 上的 TCP 监听器。使用 CLI 不需要启用自动化 API。

bromure-cli 命令行

你可以用包内的完整路径调用二进制文件，但短名称更方便。在应用菜单中选择 Bromure Agentic Coding › 安装命令行工具…。警告 安装“bromure-cli”命令行工具？ 会说明它会在 /usr/local/bin/bromure-cli 创建符号链接，并需要输入一次管理员密码；点按 安装（或 取消）。成功后，命令行工具已安装 会提示你运行 bromure-cli --help。应用启动时不会再主动提供此安装——菜单项是唯一的途径，而且你随时都能再次运行（例如在移动应用之后）。

同一个二进制文件会根据调用时使用的名称而表现不同：

• 以 bromure-cli 调用时，它会隐藏应用内部命令——镜像管理（init、info、reset 和发布流水线工具）、mcp 服务器，以及 GUI 默认的 run——只公开面向终端的组（Workspaces、Tracing、Local inference、Enterprise features、remote）。单独运行 bromure-cli 会显示帮助，而不会打开应用。
• 以 bromure-ac 调用时（应用包内的二进制文件），所有功能都可用，默认子命令是会打开 GUI 的 run。

以下示例使用 bromure-cli；只有它才公开的命令，请使用完整路径 …/MacOS/bromure-ac。

凡是出现工作区参数的地方，命令都接受工作区的 ID、短 ID 前缀或其名称。命令组 vm 和 workspaces 互为别名。机器是什么，以及它与会话的关系，请参阅机器。

应用与后台代理

镜像管理

基础镜像只需安装一次。这些命令只存在于 bromure-ac 名称下。

注： 如果不存在基础镜像，打开 GUI 会带你进入引导向导，并就地安装镜像——请参阅安装与首次运行。

工作区与虚拟机控制

这是核心命令组。vm run 刻意采用 Docker 风格：它启动一个工作区，并将你的终端交给客户机共享的 bromure tmux 会话。

一些值得了解的操作细节：

• vm run 标志。 --tool 接受代理 ID：claude、codex、grok、kimi 或 omp。--auth 为 token、subscription、bedrock 或 local。无法识别的值会产生错误并列出有效值，例如 Invalid --tool “gpt” — expected one of: claude | codex | grok | kimi | omp.；workspaces create 也以相同方式检查 --tool 和 --auth。-v/--volume <hostdir> 会把宿主机文件夹挂载到客户机的 ~/<basename>（可重复，最多 8 个）。-d/--detach 会启动虚拟机后直接返回，而不附加。--rm 会在虚拟机停止时删除工作区及其磁盘。用 Ctrl-b d 从已附加的 tmux 分离——虚拟机会继续运行。
• 代理来自模型。 工具和认证标志只会为新工作区提供初始值。每个代理实际使用的模型和提供方，来自 偏好设置 › 模型 以及工作区自己的模型面板——请参阅模型与提供方。
• 感知 TTY。 将终端交给 tmux 的 Docker 式默认行为只在真正的终端上适用；以管道或脚本调用时，行为就如同传入了 -d。
• workspaces create 的值。 颜色为 blue、red、green、orange、purple、pink、teal 或 gray。
• 编辑时留空保留。 workspaces edit 导出整个配置并将机密置空；保存回去的文档中若某机密为空白，则保留已存储的值，因此往返操作绝不会清除你的密钥。未改动的缓冲区不会保存任何内容；无效的 JSON 会中止操作。
• Exec 等待。 vm exec 最多等待 10 秒等待客户机 shell 代理；返回 502 意味着虚拟机可能未运行，或名称不匹配。在已附加会话期间触发的批准提示会呈现在你的终端上（参见附加终端上的许可），绝不会出现在客户机内部。

从命令行检查磁盘

vm fsck 是 ext4 浏览器中 运行 fsck…，以及启动因文件系统错误而停止时应用显示的 修复磁盘 按钮的可脚本化对应版本。它使用 Bromure 自己的 ext4 检查器，因此无需安装任何东西。

bromure-cli vm kill "Web app"            # the workspace must be stopped
bromure-cli vm fsck "Web app"            # check the system disk, report only
bromure-cli vm fsck "Web app" --repair   # replay the journal, clear the error flag
bromure-cli vm fsck "Web app" --home     # check the home image instead

工作区运行时，它会拒绝运行。输出会以下列其中一个摘要结尾：“Filesystem is clean.”、“Filesystem repaired; it is now consistent.”或“Filesystem has errors this checker cannot repair.”。未加 --repair 的检查如果发现问题，会建议加上 --repair 重新运行。只要仍有错误，命令就会以状态 4 退出。检查器的范围和限制，请参阅高级。

模型、路由与 Fusion

模型和提供方设置在模型与提供方中说明，多模型综合则在 Fusion 中说明；CLI 的开关如下：

追踪检查

这些命令读取各工作区的代理服务器追踪。除非工作区已启用追踪，否则不会返回任何内容——请参阅追踪设置——完整说明请见追踪与审计。

远程访问

可选的 SSH 前门默认关闭，完整说明请见远程访问与客户端。所有操作都经由控制套接字通过运行中的应用进行。

企业注册

登录到 bromure.io… 表单的 CLI 对应命令，用于脚本化的设备置备。参见企业。

集成与内部命令

远程 TUI (__remote-menu)

启用 SSH 远程访问后，每次远程登录都会（通过 ForceCommand）被强制导入一个手工打造的 ANSI 终端 UI，而不是 shell——一个用方向键和数字操作的备用屏幕、256 色菜单，可在任何 SSH PTY 上工作（请使用 ssh -t）。它以菜单形式呈现 CLI：

• 工作区——用单屏表单创建（Name、Tool、Auth、API key、Memory、Color、Folders、Generate SSH、Full settings…、Create）、各工作区的操作（运行中的工作区有 Attach、New tab、Describe、Configure…、Fusion、Routing、Worktrees…、Reboot…、Suspend、Kill；已关闭的有 Start、Describe、Configure…、Delete），以及原始表格视图。Configure… 以文本表单提供设置编辑器的各个面板；由于模型是在应用中选择的，其 Models 表单为只读（服务器的提供方，以及工作区是否覆盖它们）。
• 模型 — 已安装的模型和下载目录；选择未安装的模型时会提供带实时进度的内联 model pull。
• 追踪 — 摘要 / 主机名 / 泄漏 / 最近 / 清除。

当你附加到工作区的 tmux 时，一组神奇组合键（默认为 Ctrl-]，显示在横幅中）会调出由宿主机绘制的控制器覆盖层：标签页树、New tab、Worktrees…、Fusion、Routing、Edit settings…、Reboot…、Suspend、Disconnect。客户机永远看不到触发键——可用 remote/overlay-key 文件或 $BROMURE_OVERLAY_KEY 覆盖。Ctrl-b d 会断开 tmux 并返回菜单。远程 TUI 操作的是机器及其终端；代理会话、房间和总机则改由富客户端访问。完整的远程说明请见远程访问与客户端。

环回自动化 API

控制平面也可以通过 TCP 以 HTTP 上的 JSON 暴露，供任何语言编写脚本使用。它默认关闭。

启用它

打开 偏好设置… › 自动化（⌘,）——即 自动化 API 与 MCP 服务器 面板。

1. 打开 启用自动化服务器。开启时，窗格显示 正在监听 127.0.0.1:9223；关闭它会立即停止服务器。
2. 根据需要设置 端口（说明文字为 （默认：9223））和 绑定地址（默认为 127.0.0.1）。端口和绑定地址会在服务器下次启动时生效——关闭再打开开关即可立即应用。

你也可以不使用 GUI 来切换该开关：

defaults write io.bromure.agentic-coding automation.enabled -bool true

警告： 将 绑定地址 设置为 127.0.0.1 以外的任何值都会将 API——以及它所支撑的 MCP 服务器——暴露到网络，窗格会警告 非环回绑定会将 API 暴露到网络。MCP 服务器没有认证。 除了环回边界和下文的 BROMURE_DEBUG_CLAUDE 门控之外，TCP 监听器上没有任何认证。除非你有明确且可信的理由，否则请将绑定地址保持在环回上。

认证模型

TCP 监听器和控制套接字提供相同的路由，但访问权限不同：

换句话说：控制套接字是完全访问、仅限所有者的路径；TCP API 只在环回接口上开放安全的子集，其他一切都放在调试标志之后。路径段只进行一次百分号编码（因此含空格的工作区名称也能工作）。

用于脚本编写的端点

最有用的路由：

由于控制套接字路径包含空格，请先将其捕获到一个变量中：

SOCK="$HOME/Library/Application Support/BromureAC/control.sock"

# Full mirror snapshot (control socket only)
curl --unix-socket "$SOCK" http://localhost/state

# List running VMs
curl --unix-socket "$SOCK" http://localhost/vms

# Boot a workspace by name
curl --unix-socket "$SOCK" -X POST http://localhost/vms \
  -d '{"profile":"Web app"}'

# Answer a queued lifecycle prompt with one of its offered button labels
curl --unix-socket "$SOCK" -X POST http://localhost/prompts/PROMPT_ID/answer \
  -d '{"choice":"Not Now"}'

启用 TCP API 之后，安全的子集就能通过它工作——例如，列出工作区和打开机器的窗口都不需要调试标志：

curl http://127.0.0.1:9223/profiles
curl -X POST http://127.0.0.1:9223/sessions -d '{"profile":"Web app"}'

注： 控制平面的路由是与富客户端共享的集成接口，而不是有版本管理的公开 API；其请求和响应的格式可能在版本之间变化。上述 CLI 命令才是用脚本操作 Bromure 的稳定方式。仅供调试的路由、环境变量和文件位置都整理在附录中。

AC MCP 服务器 (bromure-ac mcp)

bromure-ac mcp 会运行一个 stdio JSON-RPC MCP 服务器（服务器名称 bromure-ac），让你 Mac 上的 AI 工具管理应用。它封装了 HTTP 自动化 API 和 AppleScript，因此请先启用自动化服务器——列表和窗口工具会调用位于 --api-url（默认 http://127.0.0.1:9223）的 HTTP API。它无法以 bromure-cli 名称使用。

它暴露的工具：

• bromure_ac_list_profiles、bromure_ac_list_sessions
• bromure_ac_open_session（打开工作区的窗口；最多等待 30 秒）、bromure_ac_close_session
• bromure_ac_get_profile、bromure_ac_set_profile（原子 JSON 替换，保留 id）
• bromure_ac_get_profile_setting、bromure_ac_set_profile_setting

使用 --debug（并在应用上设置 BROMURE_DEBUG_CLAUDE）时，它会额外添加 bromure_ac_app_state、bromure_ac_vm_exec、bromure_ac_vm_read_file 和 bromure_ac_vm_write_file。

若要接入 Claude Code，请将以下内容添加到 ~/.config/claude-code/.mcp.json（或你客户端的对应文件）。这正是自动化面板的 MCP 客户端配置 部分所显示的片段：

{
  "mcpServers": {
    "bromure-ac": {
      "command": "/Applications/Bromure Agentic Coding.app/Contents/MacOS/bromure-ac",
      "args": ["mcp"]
    }
  }
}

注意： get/set profile 工具会调用 osascript（针对运行中应用的 AppleScript），因此 GUI 应用必须在运行，且 macOS 可能会为自动化权限提示一次。除非设置了 BROMURE_DEBUG_CLAUDE，否则 profile JSON 在传输时机密会被置空。

虚拟机内的 MCP 服务器

与 AC MCP 服务器无关，Bromure 会为每台虚拟机内的代理提供一组内置的 MCP 服务器——无需任何配置。每一个都是小型的 Python stdio 垫片，以只读方式放在客户机的 /mnt/bromure-meta/ 下；垫片通过 vsock 连接宿主机，断线时会无限重连，因此代理永远不会失去其工具。工具由宿主机提供，每次调用都在宿主机上检查：代理只能看到并操作其自身机器和会话有权访问的内容。

browser、automations、infrastructure 和 delegation 服务器会写入每个代理自己的 MCP 配置，与你在机器的 MCP 面板中添加的服务器并列（MCP 设置）。task board 和 switchboard 服务器只会传给需要它们的运行。

browser 服务器

browser 服务器操作机器内嵌的 Chromium，后者在自己的一次性虚拟机中运行。它的 23 个工具涵盖浏览和检查——browser_navigate、browser_new_tab、browser_list_tabs、browser_activate_tab、browser_close_tab、browser_back、browser_forward、browser_reload、browser_screenshot（含整页选项）、browser_evaluate、browser_get_text、browser_get_html、browser_get_links、browser_click、browser_fill、browser_type、browser_press_key、browser_wait_for、browser_network、browser_network_summary、browser_clear_network、browser_console，以及 browser_pick_element（60 秒的交互式元素选择器）。

在浏览器关闭时调用工具，会打开浏览器并等待冷启动。由于浏览器是独立的虚拟机，服务器的指示会告诉代理用机器的局域网 IP（hostname -I）访问其机器上的开发服务器，绝不要用 localhost。完整说明请见嵌入式浏览器。

注： 在富客户端上，代理的浏览器 MCP 流可以通过 SSH 连接传输，让远程代理操作你在本地看到的浏览器窗格。请参阅远程访问与客户端。

你所添加 MCP 服务器的 OAuth

你在编辑器中添加的 HTTP MCP 服务器可以通过宿主机端的 OAuth 代理进行认证：它执行 RFC 8414 发现和 RFC 7591 动态客户端注册（以 Bromure AC 身份），在你的系统浏览器中运行 PKCE 授权码流程，并在环回监听器上（端口 28500–28599）提供回调。成功页面显示 已授权 — 您可以关闭此标签页并返回 Bromure AC。 整个流程在宿主机上运行，因此虚拟机永远看不到真正的 OAuth 凭据。

AppleScript (Bromure AC Suite)

脚本字典 Bromure AC Suite 是另一个自动化接口——适用于编排，以及需要窗口 ID 的截图工具。从脚本编辑器或 osascript 以 application "Bromure Agentic Coding" 为目标。它涵盖：

• 配置文件——list profiles、create ac profile <name> [color <c>]（返回 UUID）、delete ac profile <name|uuid>，以及通过 get profile json / set profile json 进行完整文档的往返（整个配置文件；保留 ID；空白字段会并入已存储的机密）。
• 按字段设置 — get profile setting … key … / set profile setting … key … to value …。
• 编辑器窗口 — open profile manager、open ac profile editor、close ac profile editor、select editor category <key>，以及 get editor window id / get main window id（用于 screencapture -l 的 CGWindowID）。
• 机器窗口——open ac session、close ac session、list ac sessions。
• 应用状态和设置 — get app state（JSON），以及针对键 automation.enabled、automation.port、automation.bindAddress、remoteAccess.enabled、remoteAccess.port、remoteAccess.bindAddress、managed.serverURL 和 managed.acIngestURL 的 get ac app setting / set ac app setting。设置 automation.enabled 会实时切换 HTTP 服务器。

例如，打开机器的窗口：

osascript -e 'tell application "Bromure Agentic Coding" to open ac session "Web app"'

注意： 除非设置了 BROMURE_DEBUG_CLAUDE，否则 profile JSON 在传输时机密会被清除。通过 set profile setting 将 apiKey 设置为空字符串会清除该密钥，而不是保留它——这与 JSON 往返桥接的留空保留行为不同。语言区域切换刻意不可脚本化；请改为使用例如 -AppleLanguages "(fr)" 重新启动应用。

计划自动化

计划自动化是绑定到一台机器、周期性且无人值守的代理运行。自动化从自动化看板（⇧⌘A，或边栏的 自动化 部分）创建和管理，代理也能通过上述 automations MCP 服务器管理其自身机器的自动化。整个功能——触发条件、计划、串联、强制的注入检查屏幕、运行历史——在自动化中说明。本节涵盖控制平面的接口：通过 API 操作自动化、回应无人值守启动可能引发的决策提示，以及在已附加终端上的同意机制。

通过 API 控制自动化

回应待处理的提示

某些生命周期决策——基础镜像升级提议、启动检查失败的磁盘、入侵警报、因入侵而清除——通常会以本地警报显示。当 Mac 前没有人能回应时（无界面代理，或由远程富客户端请求的启动），它们会改为进入队列：出现在 GET /state 的 pendingPrompts 下（每个都有 id、profileID、title、message 和按钮标签），并用 POST /prompts/<id>/answer 回应：

SOCK="$HOME/Library/Application Support/BromureAC/control.sock"
curl --unix-socket "$SOCK" -X POST http://localhost/prompts/PROMPT_ID/answer \
  -d '{"choice":"Remind me later"}'

将提示本身的其中一个按钮标签作为 choice 传入。如果在提示超时前没有任何客户端回应，它会解析为其安全的后备选项——绝不是破坏性的选项（例如入侵警报会回退到关闭虚拟机）。如果完全没有客户端连接，则会立即采用后备选项。富客户端会把这些提示呈现为普通警报。

注： 自动化、委派和其他无人值守的启动绝不会等待提示。需要你回答的启动——被标记为遭入侵的机器，或仍在下载中的本地模型——会被拒绝，并在运行历史中附上清楚的原因（“The workspace is marked compromised — start it yourself to confirm the wipe.”）。已保存状态无法恢复的挂起机器，会以全新状态启动。

附加终端上的许可

当终端以交互方式附加到机器时——通过 vm exec -it、vm attach 或 SSH 附加——宿主机端的批准提示（凭据使用等）会显示在你的终端上，而不是客户机内。提示内容为 🔒 Bromure — approval required，附有编号选项和 Choice [1-N] (Enter or timeout = deny)。Enter、超时、EOF 或分离都表示拒绝，因此遭入侵的客户机永远无法伪造批准。之后会重绘客户机的 tmux。

调试端点 (BROMURE_DEBUG_CLAUDE)

在设置了 BROMURE_DEBUG_CLAUDE 的情况下启动应用，会解除 TCP 自动化 API 的调试闸门，让认证表格中间一行的路由也能通过 TCP 使用，包括下列调试路由（除非另有说明，否则在控制套接字上始终可用）：

• GET /debug/ui-shot?path=…&which=…——应用会把自己的窗口绘制成 PNG（无需屏幕录制权限），并返回子视图框架的转储；默认输出为 /tmp/bromure-ui-shot.png。
• POST /debug/editor — 为截图工具驱动设置编辑器。
• POST /detect/prompt-injection — 运行真实的检测器并返回其判定（此路由即使在控制套接字上也需要调试标志）。

此标志还会让机密原样通过 AppleScript 和 MCP 的配置文件 JSON 桥接，且是 bromure-ac mcp --debug 的虚拟机工具所必需。GET /health 会报告 debugEnabled，让你知道应用处于哪种模式。

警告： BROMURE_DEBUG_CLAUDE 会移除通常让 exec、虚拟机控制和原始配置文件机密远离环回 TCP API 的安全闸门。只在你能掌控的机器上用此标志运行应用，且绝不要与非环回的绑定地址一起使用——那会让任何能访问该端口的人获得完整的虚拟机 shell 访问、未遮蔽的机密和窗口截图。它不同于 BROMURE_AC_DEBUG（stderr 事件日志）和 BROMURE_CLI_DEBUG（CLI 套接字诊断），后两者是无害的日志开关。