安裝

本章帶您從一台空白的 Mac 一路走到完整安裝好的 Bromure Agentic Coding：應用程式對您機器的需求為何、如何下載並安裝發行版本、首次啟動時會發生什麼、Linux 基底映像檔如何被下載、驗證並保持在最新狀態，以及如何乾淨地移除所有內容。安裝完成後，請接著閱讀快速上手來建立您的第一個工作區。

系統需求

沒有 Intel 版本，未來也不會有：應用程式在 Apple 的 Virtualization.framework 上執行其 Linux VM，而該框架僅支援 Apple Silicon 主機上的 ARM64 客體。

內建兩項磁碟空間防護措施：

• 每次映像檔安裝都會先檢查存放應用程式支援目錄的磁碟區至少有 8 GB 可用空間，否則會以清楚的訊息快速失敗。
• 在本機建置映像檔期間，若可用空間降至 1 GB 以下，監控機制會以明確的磁碟已滿錯誤中止建置，而非讓安裝程式莫名逾時。

如果您打算在工作區內使用選用的內嵌網頁瀏覽器，請為其獨立的 Alpine/Chromium 映像檔預留額外空間（下載時約 500 MB 壓縮大小）；該安裝說明請見 設定 → 瀏覽器。

安裝發行版本

發行版本以已簽署、已公證的磁碟映像檔（BromureAgenticCoding.dmg）發佈於 bromure.io。

1. 從 bromure.io 的下載頁面下載 DMG。
2. 開啟 DMG。視窗會顯示應用程式圖示，以及一個指向 應用程式 符號連結的箭頭。
3. 將 Bromure Agentic Coding 拖曳到 應用程式 符號連結上。
4. 退出 DMG，並從 /Applications 啟動應用程式。

由於發佈的 DMG 已公證並加蓋戳記，Gatekeeper 會在沒有警告的情況下開啟它。如果您從 bromure.io 以外的來源取得 DMG 且 Gatekeeper 發出警告，請將其視為警訊，而非需要繞過的障礙。

首次啟動

歡迎視窗

在您的 Mac 上存在 Linux 基底映像檔之前，應用程式無法執行代理程式工作區。當您第一次啟動它（尚無基底映像檔）時，它會開啟一個歡迎視窗，而非工作區瀏覽器：

這個視窗——標題為 Bromure Agentic Coding——顯示應用程式圖示、標題 歡迎使用 Bromure Agentic Coding、一段簡短說明（「初次設定會下載預建的 Ubuntu 24.04 映像檔（或在無法下載時於本機建置），並在隔離的 VM 內安裝 Node.js、Claude Code、Codex 及終端機工具。每個基底映像檔版本只會執行一次。」），以及一個醒目的 開始使用 按鈕。

按一下 開始使用（或按下 Return 鍵——它是預設按鈕）即可開始。這與 bromure-cli init CLI 命令執行完全相同的安裝程序。

附註： 歡迎文字以 Node.js、Claude Code 與 Codex 作為範例。完整來說，Node.js 與免費工具已預先烘焙進預建映像檔中，而設定另外還會安裝 Grok CLI 與 Google Cloud SDK——請見下方初次設定會做什麼。

當應用程式純粹作為遠端鏡像用戶端（見遠端存取）或作為無視窗的無頭代理程式啟動時，會略過歡迎視窗，因為兩者都不需要本機基底映像檔。

設定進度視窗

在 開始使用 之後，視窗會切換到標題為 Bromure Agentic Coding — Setup 的進度畫面，標頭為「Building base image」/「This is the one-time install. Don't close the window.」它會顯示：

• 一個狀態標籤，指出目前的步驟——以下載路徑為例：「Fetching image catalog…」、「Downloading Ubuntu 24.04 image (… GB)…」、「Verifying checksum…」、「Expanding image…」、「Installing recommended packages (N step(s), ~2-5 min)…」，最後是「Base image ready at … (vNNN)」。
• 一條帶有數字百分比的確定式進度列。在下載路徑上，該進度列按階段加權：映像檔下載填滿 0–60%、展開 60–80%，其餘由安裝後步驟填滿。
• 一個預設收合的 Console output 揭露區塊，會串流原始安裝程式記錄（輔助 VM 的序列主控台）。文字可選取，且一個複製圖示按鈕可將整份記錄複製到剪貼簿。畫面上僅保留最後 100 行。

如果發生任何失敗，狀態標籤會被一行紅色錯誤訊息取代，並出現 Close 按鈕。

若嘗試在安裝進行到一半時關閉視窗，會出現警告——Cancel base-image rebuild?（「The image will be left in an incomplete state. You'll need to re-run the rebuild before launching new sessions.」）——並附有 Cancel rebuild 與 Keep building 按鈕。如果您取消且存在先前可用的映像檔，應用程式會返回正常的主視窗；否則會返回歡迎畫面。

附註： 當映像檔安裝或修訂正在執行時，選用的 SSH 遠端存取入口會暫停，並在之後自動恢復（見遠端存取）。

bromure-cli 提示

在從已安裝的應用程式套件首次啟動 GUI 時，應用程式會提議安裝其命令列進入點：Install the "bromure-cli" command-line tool?——「This creates a symlink at /usr/local/bin/bromure-cli so you can drive Bromure from the terminal (vm, exec, trace, …). It needs your admin password once.」

• Install 會透過一次性的管理員密碼提示，在 /usr/local/bin/bromure-cli 建立符號連結（不會安裝任何具特權的輔助程式）。
• Not Now 會延後；下次啟動時會再次詢問。
• Don't Ask Again 會永久隱藏此提示（儲存在 cliSymlinkDeclined UserDefaults 鍵中）。

當透過 bromure-cli 名稱叫用該二進位檔時，映像檔管理命令（init、info、reset 以及發佈者端的動詞）、GUI 預設值與 MCP 伺服器會被隱藏；直接執行 bromure-cli 會列印說明。完整的命令參考請見自動化與 CLI。無頭代理程式、開發（swift run）與遠端鏡像啟動會略過此提示。

初次設定會做什麼

初次設定會產出基底映像檔：一個 24 GB 的稀疏磁碟，內含具備 EFI/GRUB 開機的 Ubuntu 24.04（「noble」），每個工作區 VM 都由此複製而來。有兩條路徑可產出它；下載是優先方式，本機建置則是備援。兩者都會寫入 .partial 檔案並以原子方式提升結果，因此中斷的安裝絕不會讓寫到一半的映像檔取代可用的映像檔。

預建映像檔下載

優先路徑會下載每週發佈到 https://dl.bromure.io 的預建映像檔：

1. 目錄擷取。 應用程式會擷取位於 https://dl.bromure.io/images/img-catalog.json 的已簽署映像檔目錄，其中指明目前的映像檔（UUID、版本、SHA-256、大小）並列出安裝後步驟。該目錄帶有以簽署應用程式更新相同金鑰（Sparkle SUPublicEDKey）製作的 ed25519 簽章；該簽章涵蓋映像檔身分、其總和檢查碼，以及每個安裝後命令。未簽署或無效的目錄會被拒絕，而簽署時間早於應用程式已採用者的目錄絕不會被接受（回復保護）。
2. 下載。 會下載 gzip 壓縮的映像檔（約 3 GB 壓縮大小）並驗證其 SHA-256。失敗的下載最多重試 3 次，並在每次嘗試之間重新擷取目錄——這消除了與每週發佈在下載途中刪除先前建置之間的競爭狀況。
3. 展開。 映像檔會以稀疏方式展開至 base.img.partial：邏輯上 24 GB，但實體磁碟空間僅約 6–8 GB。
4. 安裝後。 應用程式會啟動一個小型的 Alpine netboot 安裝程式輔助 VM，它會在映像檔的 chroot 中以 root 身分執行目錄的安裝後步驟（見下一節）。
5. 提升。 會建立全新的 EFI 變數存放區，並以原子方式提升 base.img、efivars.bin、base.version 與 image-state.json。

安裝後步驟：推薦的套件

發佈的映像檔在法律上必須可再散佈，因此它只包含嚴格意義上的自由軟體（Node.js、docker、kitty、gh、glab、kubectl、doctl、awscli、azure-cli 等皆已烘焙進去）。所有非自由軟體都在目錄中宣告為已簽署的安裝後步驟，並安裝到 您的 機器上、安裝進 您的 映像檔副本中。版本 4.3.0 的基準步驟為：

同意的運作方式如下：在全新安裝時，所有基準步驟都會執行而不需額外提示——從歡迎畫面開始設定（或輸入 bromure-cli init）就是 同意。之後才發佈的步驟則需要透過基底映像檔更新與版本管理下所述的 New recommended packages 提示明確核准。由於目錄簽章涵蓋每個步驟的命令文字，遭入侵的 CDN 無法變更在您映像檔中以 root 身分執行的內容。

本機建置備援

如果下載因下載端的原因失敗——離線、CDN 中斷、總和檢查碼或展開失敗——應用程式會顯示一個 Image download failed 警示，附有 Build Locally 與 Cancel 按鈕。它絕不會靜默地退回備援方式。（相對地，bromure-cli init CLI 命令會自動退回而不提示。）

本機建置會在您自己的 Mac 上產出相同的映像檔：

1. 下載 Alpine 3.22 netboot 核心與 initramfs（約 25 MB，快取於支援目錄中）。
2. 配置一個全新的 24 GB 稀疏磁碟。
3. 啟動一次性的 Alpine 安裝程式 VM（4 個 vCPU、4 GB RAM），透過其序列主控台驅動，它會以 debootstrap 建立 Ubuntu noble、安裝免費工具與 GRUB。
4. 套用與下載路徑相同的目錄安裝後步驟。

進度訊息包括「Downloading Alpine netboot installer…」、「Allocating 24GB sparse disk…」、「Booting Alpine installer (this drives the Ubuntu install)…」與「Running setup.sh…」。此路徑上的進度列由安裝程式記錄行驅動，並在最後跳至「Base image ready」之前上限為 97%。

本機建置包含 VPN 韌性機制：所有客體套件擷取都會經由一個處理程序內的主機端代理伺服器路由、安裝程式會在任何下載之前箝制 VM NIC 的 MTU、DHCP 會有第二次機會、無網路狀況會提早中止，而客體核心恐慌（panic）會觸發一次自動的乾淨重試。兩個相關的逃生出口：

• 如果安裝程式 VM 未取得 DHCP 租約，建置會失敗並顯示 Network Issue During Base-Image Build 警示，提供 Repair and Retry（重新啟動 macOS 網路常駐程式；會要求您的管理員密碼）或 Cancel。
• 在會將大型傳輸黑洞化的 VPN 上（例如 MTU 1420 的 WireGuard），您可以固定安裝程式 VM 的 MTU：defaults write io.bromure.agentic-coding vm.mtu -int 1400。

您也可以隨時明確選擇本機建置——在應用程式選單中選擇 Rebuild Base Image… → Rebuild Locally，或執行 bromure-cli init --build-local。

設定期間使用的網路端點

供防火牆與代理伺服器管理員參考，安裝過程會與以下端點通訊：

安裝本身不會開啟任何監聽的 TCP 連接埠；建置期間使用的主機端套件代理伺服器會為每次建置繫結一個僅限本機的臨時連接埠。

設定時間與磁碟用量

磁碟用量：

• 開始時： 存放 ~/Library/Application Support/BromureAC/ 的磁碟區至少需 8 GB 可用空間。
• 安裝後： 基底映像檔實體上約佔 6–8 GB（邏輯上 24 GB——稀疏區塊只有在寫入後才會佔用空間）。
• 每個工作區： 每個工作區的磁碟一開始都是基底映像檔的 APFS 寫入時複製（copy-on-write）複本，因此初期幾乎不佔空間，只會隨著工作區寫入資料而增長。

設定每個基底映像檔版本只會發生一次——後續啟動會直接進入工作區瀏覽器。

所有內容的儲存位置

應用程式寫入的所有內容都存放在您的使用者帳號下；除了選用的 bromure-cli 符號連結外，不會有任何內容安裝於系統層級。

有兩項內容基於必要性存放於他處：

• 憑證主金鑰儲存在 macOS 資料保護鑰匙圈（Data Protection Keychain）中（標記為 僅限此裝置——它絕不會離開這台 Mac），而非支援目錄中。磁碟上的密鑰是 AES-256-GCM 密文；見憑證。
• 應用程式套件內嵌一個具特權的 launchd 常駐程式 plist（io.bromure.fatclient-tunnel），供遠端鏡像網路輔助程式使用。它會在需要時註冊，而首次註冊會在「系統設定 › 一般 › 登入項目」下浮現一個核准切換開關；見遠端存取。

bromure-cli info 命令可隨時列印已安裝映像檔的版本戳記、其邏輯與實體大小，以及其路徑。

基底映像檔更新與版本管理

版本戳記與點修訂號

已安裝的映像檔會在 base.version 中記錄其版本。主要 部分來自應用程式所綑綁的版本常數（版本 4.3.0 時為 200）；任何在相同主要版本下的重建、重新下載或修訂都會附加一個點修訂號（200 → 200.1 → 200.2）。附屬的 image-state.json 會記錄映像檔的來源，以及已套用哪些安裝後步驟 UUID。

有兩種比較會使用這些戳記：

• 應用程式層級的更新檢查僅比較主要版本，因此您只會在刻意的映像檔發行時才收到提示。
• 各工作區的 偏移偵測 會將工作區複製時記錄的完整戳記與目前的戳記比較；任何變更（包括點修訂號）都會使工作區提供重設到新基底的選項。映像檔更新本身絕不會動到現有工作區的磁碟——偏移重設一律由您決定（見工作區）。

預建映像檔會每週以最新的 Ubuntu 套件重新發佈，但每週重新發佈 不會 提升版本——只有應用程式發行中刻意的版本提升才會觸發更新提示，因此您不會每週被打擾。過期的 CDN 目錄絕不會提供降級：只有嚴格意義上較新的版本才算數。

更新提示

當有較新的主要映像檔版本可用時——無論是因為應用程式更新綑綁了一個，或是因為目錄發佈了一個——啟動時會顯示一個非阻斷式警示 Base image update available：「Your base image is at version X but version Y is available. The current image still works — updating downloads the new prebuilt image (a few GB; local rebuild as fallback) and re-applies the recommended packages.」

• Update Now 會在設定視窗中開始下載優先的重新安裝。
• Later 會在本次啟動中關閉它；下次啟動時會再次詢問。無論哪種方式，現有映像檔都會繼續運作。

新的推薦套件

當目錄新增了尚未在 image-state.json 中記錄為已套用的安裝後步驟時，啟動時會顯示一個同意警示 New recommended packages，列出這些新步驟：「New packages are recommended to be installed: … Bromure installs them into the base image (a few minutes, in the background VM). Existing workspaces keep running; each one's drift prompt will offer a reset to pick them up.」

• Install 會將這些步驟套用到 base.img 的 APFS 寫入時複製複本，並以原子方式換入修訂後的映像檔——現有工作區在整個過程中持續運作。版本戳記會獲得一個點修訂號提升（例如 200 → 200.1）。進度會出現在設定視窗中，標題為「Installing recommended packages」/「The base image is being amended. Existing workspaces keep working.」
• Later 會延後；下次啟動時會再次詢問。

沒有這項同意就絕不會執行任何內容——安裝後步驟會在基底映像檔內以 root 身分執行。早於 image-state.json 的安裝會在啟動時遷移：所有綑綁的基準步驟都會被標記為已套用。

手動重建

若要隨時強制重新安裝，請從應用程式選單（在 Remote Access… 下方）選擇 Rebuild Base Image…。它會詢問 Update the base image?——「Downloads the latest prebuilt image (or re-runs the full local installer, ~5–10 min) and re-applies the recommended packages. Existing workspaces' disks aren't touched — on next launch each one's drift prompt will offer to reset to the new base.」——並附有 Download Prebuilt、Rebuild Locally 與 Cancel。

舊映像檔會保持啟用狀態，直到新映像檔完全建置完成（歸功於 .partial 檔案與原子交換），因此在重建期間工作階段仍可啟動。CLI 的對應命令是 bromure-cli init（下載優先）或 bromure-cli init --build-local。

讓應用程式保持在最新狀態

應用程式使用 Sparkle 自我更新：它會每天自動檢查一次 https://bromure.io/api/v1/release-agentic-coding，且更新會針對簽署映像檔目錄的同一個固定公開金鑰進行驗證。應用程式選單中、緊接在 About 下方，有一個手動的 Check for Updates… 項目。（在開發版本中，因為更新程式未初始化，此項目不存在。）

應用程式更新與基底映像檔更新是獨立的：更新應用程式時，只有在新的應用程式版本刻意提升所綑綁的映像檔版本時，才會提示進行映像檔更新。

遷移到新的 Mac

沒有內建的遷移助理。建議的方式是全新安裝再加上選擇性複製您的工作區資料：

1. 在新的 Mac 上安裝應用程式並完成初次設定（重新下載基底映像檔比複製它更快也更乾淨——base.img 與 efivars.bin 是應用程式會免費重新建立的各機器專屬產物）。
2. 在兩台 Mac 上都退出應用程式。
3. 將 ~/Library/Application Support/BromureAC/profiles/ 從舊 Mac 複製到新 Mac 上的相同位置。每個子目錄都是一個工作區：其定義（profile.json）、其 VM 磁碟（disk.img——您複製的儲存庫、快取與 shell 歷史記錄）、其家目錄磁碟區，以及其 SSH 金鑰。
4. 在新的 Mac 上啟動應用程式。您的工作區會出現在工作區瀏覽器中。如果某個工作區是從與目前安裝不同的基底映像檔修訂複製而來，其偏移提示會提供重設選項——拒絕它以保留工作區目前的磁碟（見工作區）。

有三項內容刻意不會轉移：

• 憑證。 加密已儲存密鑰的主金鑰存放在 Mac 的資料保護鑰匙圈中，並標記為 僅限此裝置。來自舊 Mac 的加密密鑰區塊在新 Mac 上無法讀取；每個 profile.json 中的非敏感中繼資料則會保留，因此只需在憑證窗格中重新輸入您的 API 金鑰與權杖即可（見憑證）。
• 企業註冊。 安裝身分（mTLS 葉憑證）是各安裝專屬且僅限裝置儲存的；請重新註冊新的 Mac（見企業）。
• 應用程式設定（位於 io.bromure.agentic-coding 預設值網域中），除非您自行遷移它們。

提示： 工作區 disk.img 檔案是稀疏的，且其寫入時複製所節省的空間無法在網路複製後保留——一個在舊 Mac 上只佔幾 GB 的工作區，在傳輸途中可能會實體化為其完整的已寫入大小。請使用能感知稀疏的複製方式（例如 rsync -aS），並先檢查目的地的可用空間。

Apple 的「移轉輔助程式」會將整個支援目錄當作一般檔案複製；那樣做可行，但您仍會遇到上述的憑證與註冊狀況，而且複製的基底映像檔會失去它與工作區磁碟之間的寫入時複製關係（在您重建之前會佔用額外的實體空間）。

完整解除安裝

若只想重設基底映像檔而保留應用程式與您的工作區，請執行 bromure-cli reset（加上 --yes 可略過確認）。它會刪除 base.img、efivars.bin、base.version 與 image-state.json，因此下次啟動會從頭開始設定。它絕不會動到工作區，且會保留快取的 Alpine netboot 檔案與快取的目錄。

沒有綑綁的解除安裝程式。完整移除需手動進行：

1. 退出應用程式（以及任何無頭代理程式：用 pgrep -fl bromure-cli 檢查）。

2. 將 Bromure Agentic Coding 從 /Applications 拖曳到垃圾桶。

3. 刪除支援目錄——基底映像檔、所有工作區及其磁碟、快取，以及各安裝專屬的 CA：

   rm -rf ~/Library/Application\ Support/BromureAC
   

4. 刪除登入時開機的 LaunchAgent（若存在）：

   rm -f ~/Library/LaunchAgents/io.bromure.agentic-coding.boot.plist
   

5. 在「系統設定 › 一般 › 登入項目與延伸功能」下移除應用程式的項目（若您曾啟用過遠端鏡像通道常駐程式的核准切換開關）。

6. 移除 CLI 符號連結（若您曾安裝它）：

   sudo rm -f /usr/local/bin/bromure-cli
   

7. 可選擇性清除應用程式的設定：

   defaults delete io.bromure.agentic-coding
   

警告： 步驟 3 會永久刪除每個工作區的磁碟——複製的儲存庫、未提交的工作、套件快取、shell 歷史記錄。請先推送或匯出您在意的任何內容。

一旦其密文消失，鑰匙圈中的憑證主金鑰便會成為孤立項目；它無害，但您可以在「鑰匙圈存取」中搜尋 io.bromure.agentic-coding.master-key 來移除它。