CLI、API 與 MCP

App 能做的一切，也都能在不開視窗的情況下操作。App 的執行檔——位於 Bromure Agentic Coding.app/Contents/MacOS/ 內的 bromure-ac——同時也是一個多指令 CLI、一個 HTTP 控制平面、一個供外部 AI 工具使用的 MCP 伺服器，以及一個 AppleScript 目標。在每台 VM 內部，一組內建的 MCP 伺服器讓代理程式擁有自己的 Bromure 視角。本章是這一切的參考資料。

由外而內，這些介面依序為：

• bromure-cli 命令列——類似 Docker/kubectl 的 CLI，用於機器、VM、終端機、指令、追蹤、模型、遠端存取與註冊。
• 控制平面——以 HTTP 上的 JSON 提供相同的操作，位於僅限擁有者的 Unix socket 上，並可選擇性地位於回送 TCP 連接埠上。
• AC MCP 伺服器（bromure-ac mcp）——讓你 Mac 上的 AI 工具（Claude Code、Claude Desktop）管理 App。
• 客體內的 MCP 伺服器——內建於每台 VM：瀏覽器、自動化、基礎架構、委派，以及供特定工作階段使用的任務看板與總機。
• AppleScript——Bromure AC Suite 字典。

在本章與 CLI 中，機器都稱為工作區（它在設定編輯器與命令列中的名稱）。代理程式對話意義上的工作階段，透過 /agent-sessions 路由存取；較舊的 /sessions 路由，以及 CLI 與 AppleScript 中的 session 一詞，指的是機器的視窗。

控制平面：socket 與 API

每個介面都透過以下兩種傳輸方式之一，以 HTTP 與執行中的 App 溝通：

CLI 永遠不會直接與 VM 溝通。每個子指令都是控制 socket 上的輕量 HTTP 用戶端，因此相同的指令在本機可用，而且——當 socket 經由 SSH 建立通道時——也能從完整用戶端對遠端實例使用。當你執行需要代理程式的指令、而沒有代理程式在執行時，CLI 會自動啟動一個無視窗的背景代理程式（bromure-ac run --headless），並等待最多 40 秒讓它回應 /health。唯讀指令（vm ls、describe、trace …）不會自動啟動；它們會改為顯示 No bromure-ac agent running.。

附註： 只要 App 在執行，控制 socket 就一直可用，且與 啟用自動化伺服器 開關無關。該開關只控制連接埠 9223 上的 TCP 監聽器。使用 CLI 不需要啟用自動化 API。

bromure-cli 命令列

你可以用套件內的完整路徑呼叫執行檔，但短名稱比較方便。在 App 選單中選擇 Bromure Agentic Coding › 安裝命令列工具…。警示 要安裝「bromure-cli」命令列工具嗎？ 會說明它會在 /usr/local/bin/bromure-cli 建立符號連結，並需要輸入一次管理者密碼；點按 安裝（或 取消）。成功後，命令列工具已安裝 會提示你執行 bromure-cli --help。App 啟動時不會再主動提供這項安裝——選單項目是唯一的途徑，而且你隨時都能再次執行（例如在移動 App 之後）。

同一個執行檔會依呼叫時使用的名稱而有不同行為：

• 以 bromure-cli 呼叫時，它會隱藏 App 內部指令——映像檔管理（init、info、reset 與發佈管線工具）、mcp 伺服器，以及 GUI 預設的 run——只公開面向終端機的群組（Workspaces、Tracing、Local inference、Enterprise features、remote）。單獨執行 bromure-cli 會顯示說明，而不會開啟 App。
• 以 bromure-ac 呼叫時（App 套件內的執行檔），所有功能都可用，預設子指令是會開啟 GUI 的 run。

以下範例使用 bromure-cli；只有它才公開的指令，請使用完整路徑 …/MacOS/bromure-ac。

凡是出現工作區引數的地方，指令都接受工作區的 ID、短 ID 前綴或其名稱。指令群組 vm 與 workspaces 互為別名。機器是什麼，以及它與工作階段的關係，請參閱機器。

應用程式與背景代理程式

映像檔管理

基礎映像檔只需安裝一次。這些指令只存在於 bromure-ac 名稱之下。

附註： 若不存在基礎映像檔，開啟 GUI 會帶你進入引導精靈，並就地安裝映像檔——請參閱安裝與首次執行。

工作區與 VM 控制

這是核心群組。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 會啟動 VM 後直接返回，而不附加。--rm 會在 VM 停止時刪除工作區及其磁碟。以 Ctrl-b d 從已附加的 tmux 分離——VM 會繼續執行。
• 代理程式來自模型。 工具與驗證旗標只會為新工作區提供初始值。每個代理程式實際使用的模型與供應商，來自 偏好設定 › 模型 以及工作區自己的模型窗格——請參閱模型與供應商。
• 感知 TTY。 將終端機交給 tmux 的 Docker 式預設行為只在真正的終端機上適用；以管線或指令碼呼叫時，行為就如同傳入了 -d。
• workspaces create 的值。 顏色為 blue、red、green、orange、purple、pink、teal 或 gray。
• 編輯時的留空即保留。 workspaces edit 會匯出整份組態並將密鑰清空；一份存回時密鑰為空白的文件會保留已儲存的值，因此往返一趟絕不會抹除你的金鑰。未變動的緩衝區不會儲存任何東西；無效的 JSON 會中止。
• Exec 等待。 vm exec 最多等待 10 秒以取得客體 shell 代理程式；502 表示 VM 可能未在執行，或名稱不符。在附掛的工作階段期間觸發的核准提示會呈現在你的終端機上（見 透過附掛終端機的同意），絕不會出現在客體內部。

從命令列檢查磁碟

vm fsck 是 ext4 瀏覽器中 執行 fsck…，以及開機因檔案系統錯誤而停止時 App 顯示的 修復磁碟 按鈕的可指令碼化對應版本。它使用 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 前門預設為停用，完整說明請見遠端存取與用戶端。所有操作都經由控制 socket 透過執行中的 App 進行。

企業註冊

Log in to bromure.io… 表單的 CLI 對應命令，用於指令碼化的裝置佈建。見 Enterprise。

整合與內部命令

遠端 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… 以文字表單提供設定編輯器的各個窗格；由於模型是在 App 中選擇的，其 Models 表單為唯讀（伺服器的供應商，以及工作區是否覆寫它們）。
• Models——已安裝的模型與下載目錄；挑選一個未安裝的模型時，會提供就地 model pull 並顯示即時進度。
• Trace——Summary / Hostnames / Leaks / Recent / Clear。

當你附加到工作區的 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. 開啟 Enable automation server。開啟後，該窗格顯示 Listening on 127.0.0.1:9223；關閉它會立即停止伺服器。
2. 視需要設定 連接埠（說明文字為 （預設：9223））與 繫結位址（預設為 127.0.0.1）。連接埠與繫結位址會在伺服器下次啟動時生效——關閉再開啟開關即可立即套用。

你也可以不透過 GUI 來切換該開關：

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

警告： 將 Bind address 設為 127.0.0.1 以外的任何值，都會將 API——以及它所支撐的 MCP 伺服器——暴露於網路，該窗格會警告 Non-loopback bind exposes the API to the network. The MCP server has no auth.。除了回送邊界與下方的 BROMURE_DEBUG_CLAUDE 關卡之外，TCP 監聽器沒有任何驗證。除非你有明確且可信賴的理由，否則請將綁定位址保留在回送上。

驗證模型

TCP 監聽器與控制 socket 服務相同的路由，但存取權不同：

換句話說：控制 socket 是完整存取、僅限擁有者的路徑；TCP API 只在回送介面上開放安全的子集，其他一切都放在除錯旗標之後。路徑區段只進行一次百分比編碼（因此含空格的工作區名稱也能運作）。

供指令碼使用的端點

最實用的路由：

由於控制 socket 路徑含空格，請先將它擷取到變數中：

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 工具管理 App。它包裝了 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 設定檔工具會外呼 osascript（對執行中應用程式使用 AppleScript），因此 GUI 應用程式必須在執行中，且 macOS 可能會就自動化權限提示一次。除非設有 BROMURE_DEBUG_CLAUDE，否則設定檔 JSON 傳輸時密鑰會被清空。

VM 內的 MCP 伺服器

與 AC MCP 伺服器無關，Bromure 會為每台 VM 內的代理程式提供一組內建的 MCP 伺服器——不需要任何設定。每一個都是小型的 Python stdio 墊片，以唯讀方式放在客體的 /mnt/bromure-meta/ 之下；墊片透過 vsock 連到主機，斷線時會無限重新連線，因此代理程式永遠不會失去其工具。工具由主機提供，每次呼叫都在主機上檢查：代理程式只能看到並操作其自身機器與工作階段有權存取的內容。

browser、automations、infrastructure 與 delegation 伺服器會寫入每個代理程式自己的 MCP 設定，與你在機器的 MCP 窗格中加入的伺服器並列（MCP 設定）。task board 與 switchboard 伺服器只會傳給需要它們的執行。

browser 伺服器

browser 伺服器操作機器內嵌的 Chromium，後者在自己的拋棄式 VM 中執行。它的 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 秒的互動式元素選取器）。

在瀏覽器關閉時呼叫工具，會開啟瀏覽器並等待冷開機。由於瀏覽器是獨立的 VM，伺服器的指示會告訴代理程式以機器的區域網路 IP（hostname -I）連到其機器上的開發伺服器，絕不要用 localhost。完整說明請見內嵌瀏覽器。

附註： 在完整用戶端上，代理程式的瀏覽器 MCP 串流可以經由 SSH 連線傳輸，讓遠端代理程式操作你在本機看到的瀏覽器窗格。請參閱遠端存取與用戶端。

你所加入 MCP 伺服器的 OAuth

你在編輯器中新增的 HTTP MCP 伺服器可以透過主機端的 OAuth 仲介進行驗證：它執行 RFC 8414 探索與 RFC 7591 動態用戶端註冊（以 Bromure AC 身分）、在你的系統瀏覽器中執行 PKCE 授權碼流程，並在回送監聽器（埠 28500–28599）上服務回呼。成功頁面顯示 Authorized — You can close this tab and return to Bromure AC.。整個流程在主機上執行，因此 VM 從不會看到真實的 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），外加 get ac app setting / set ac app setting，鍵有 automation.enabled、automation.port、automation.bindAddress、remoteAccess.enabled、remoteAccess.port、remoteAccess.bindAddress、managed.serverURL 與 managed.acIngestURL。設定 automation.enabled 會即時切換 HTTP 伺服器。

例如，開啟機器的視窗：

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

附註： 除非設有 BROMURE_DEBUG_CLAUDE，否則設定檔 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 傳入。若在提示逾時前沒有任何用戶端回應，它會解析為其安全的備援選項——絕不是破壞性的選項（例如入侵警示會退回關閉 VM）。若完全沒有用戶端連線，則會立即採用備援選項。完整用戶端會把這些提示呈現為一般警示。

附註： 自動化、委派與其他無人值守的啟動絕不會等待提示。需要你回答的啟動——被標記為遭入侵的機器，或仍在下載中的本機模型——會被拒絕，並在執行歷史中附上清楚的原因（「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 的情況下啟動 App，會解除 TCP 自動化 API 的除錯閘門，讓驗證表格中間列的路由也能透過 TCP 使用，包括下列除錯路由（除非另有說明，否則在控制 socket 上一律可用）：

• GET /debug/ui-shot?path=…&which=…——App 會把自己的視窗繪製成 PNG（不需要螢幕錄製權限），並回傳子視圖框架的傾印；預設輸出為 /tmp/bromure-ui-shot.png。
• POST /debug/editor——為截圖工具驅動設定編輯器。
• POST /detect/prompt-injection——執行真正的偵測器並回傳其判定（此路由即使在控制 socket 上也需要除錯旗標）。

此旗標也會讓密鑰原樣通過 AppleScript 與 MCP 的設定檔 JSON 橋接，且是 bromure-ac mcp --debug 的 VM 工具所必需。GET /health 會回報 debugEnabled，讓你知道 App 處於哪種模式。

警告： BROMURE_DEBUG_CLAUDE 會移除通常讓 exec、VM 控制與原始設定檔密鑰遠離回送 TCP API 的安全閘門。只在你能掌控的機器上以此旗標執行 App，且絕不要與非回送的繫結位址合併使用——那會讓任何能連到該連接埠的人取得完整的 VM shell 存取、未遮蔽的密鑰與視窗擷取。它不同於 BROMURE_AC_DEBUG（stderr 事件記錄）與 BROMURE_CLI_DEBUG（CLI socket 診斷），後兩者是無害的記錄開關。