安裝與首次執行

本章帶你從一台空白的 Mac 走到可以使用的 Bromure Agentic Coding：應用程式需要什麼、如何安裝、首次啟動時引導精靈會做什麼、Linux 基礎映像檔如何下載、檢查並保持最新、應用程式把檔案存放在哪裡，以及如何乾淨地移除一切。讀完本章後，請接著閱讀快速入門。

系統需求

沒有 Intel 版本，未來也不會有：應用程式在 Apple 的 Virtualization.framework 上執行其 Linux VM，而該框架只支援 Apple Silicon 上的 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 VM 中執行你的程式設計代理程式，而精靈會先安裝基礎映像檔，接著提議匯入你在這台 Mac 上已有的憑證。

點按 開始使用（或按下 Return）開始安裝。如果已經有基礎映像檔，按鈕會顯示 繼續，並直接帶你到憑證步驟。

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 重新登入；這會建立一個屬於 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. 自訂映像檔。 應用程式會下載一小組隨映像檔發佈的映像檔工具，並在一台暫時的輔助 VM 中啟動它們，由它在映像檔內執行目錄中的設定步驟（見下一節）。進度會顯示「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. 啟動一次性的建置 VM（4 個 vCPU、4 GB RAM），安裝 Ubuntu noble、自由工具與 GRUB。
4. 套用與下載路徑相同的目錄設定步驟。

進度會顯示「Building the image: downloading tools…」、「Allocating 24GB sparse disk…」、「Building the image: starting…」等等。在此路徑上，進度列會依照安裝程式的記錄前進，並停在 97%，直到最後跳至「Base image ready」。

本機建置的設計能在 VPN 環境下存活：所有套件下載都經過主機端代理伺服器、建置 VM 的網路 MTU 會在任何下載前調低、沒有網路時建置會及早停止，而客體核心當機會觸發一次在全新磁碟上的自動重試。兩個相關的應急做法：

• 如果建置 VM 取得不到網路位址，建置會以 建置基礎映像檔時出現網路問題 失敗，並提供 修復並重試（重新啟動 macOS 的網路服務；會要求你的管理者密碼）或 取消。
• 在會丟棄大型封包的 VPN 上（例如 MTU 1420 的 WireGuard），你可以自行設定建置 VM 的 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。要立即升級嗎？升級會重置工作區的磁碟——VM 內安裝的一切都會被清除；你的專案檔案夾不受影響。」

• 是，升級 會把機器的系統磁碟重置到新的基礎上，然後啟動它。家目錄磁碟（以及 /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 來刪除它。