快速入門

本章帶您完成 Bromure Agentic Coding 的第一次完整工作階段：建立工作區、選擇代理程式及其驗證方式、將專案資料夾分享至沙箱、執行第一個任務、檢視代理程式透過網路送出的內容，以及關閉工作階段以便日後重新接續。請預留約十分鐘。

本導覽刻意在所有可行之處使用預設值。您在此接觸的每一項設定，稍後在手冊中都有完整的參考說明——沿途都會提供連結，並彙整於後續延伸閱讀。

開始之前

您需要：

  • 已安裝並至少啟動過一次的 Bromure Agentic Coding，且基底作業系統映像檔已就緒——請參閱安裝。（需要一台搭載 Apple Silicon 並執行 macOS 14 或更新版本的 Mac。）
  • 一種驗證編碼代理程式的方式。對於 Claude Code——預設的代理程式——這可以是 Anthropic API 金鑰，或是您可登入的 Claude 訂閱。以下步驟 4 會涵蓋這兩種途徑。
  • 選擇性地，準備一個您希望代理程式處理的、位於 Mac 上的專案資料夾。小型的 git 儲存庫最適合作為首次測試，但任何資料夾皆可。

開始之前，請先掌握一個概念：代理程式在一個可拋棄式的 Ubuntu VM 內執行，而您真正的憑證從不進入該 VM。該 VM 僅持有假的佔位權杖；當請求離開您的 Mac 那一刻，主機端的代理伺服器會將其換成真正的值。這就是傳輸邊界，也是本導覽要求您將 API 金鑰貼入應用程式、而非貼入終端機的原因。

建立第一個工作區

工作區是隔離的單位：一個 Ubuntu VM，擁有自己的系統磁碟、自己的持久化家目錄、自己的代理程式、憑證與安全政策。您可以視需要建立任意多個；本導覽建立一個。

  1. 開啟主視窗。左側邊欄的標題為 WORKSPACES；底部有一個黑色圓形的 + 按鈕（工具提示：新增工作區）。按下它。

  2. 設定編輯器會在一個標題為 New workspace 的視窗中開啟，內容依您的偏好設定範本預先填入，並命名為「Default workspace」（若該名稱已被使用則自動編號）。此時顯示的是 一般 窗格。輸入您自訂的名稱——例如 My First Project。名稱是唯一的必填欄位；本導覽中的其他一切皆為選擇性的潤飾。若您願意，可挑選一個 顏色——它會為側邊欄中該工作區的圖塊上色。

先別急著按 Create——有兩個窗格值得先看看。

選擇代理程式與驗證方式

  1. 在編輯器的類別側邊欄中按一下 代理程式。此窗格為每個支援的代理程式顯示一張卡片——Claude Code、Codex 與 Grok Build——每張卡片都有一個啟用開關。Claude Code 開箱即為啟用狀態，並帶有橘色的 Primary 標籤：主要代理程式是在工作階段第一個分頁中自動啟動的那一個。其他已啟用的代理程式同樣已安裝並完成驗證，但您需自行從新分頁啟動它們。
工作區編輯器的代理程式窗格，顯示帶有 Primary 標籤的 Claude Code 卡片、四種驗證模式、Anthropic API 金鑰欄位，以及已停用的 Codex 與 Grok Build 卡片

在 Claude Code 卡片內，您會看到四種驗證模式：API token、附有 Register… 連結的 Subscription (interactive login)、Bedrock (AWS)，以及 Local model（在安裝本機模型之前會呈灰色並顯示「— download a model in Local Models」）。請從前兩者中擇一：

  1. 如果您有 Anthropic API 金鑰： 選擇 API token 並將金鑰貼入 Anthropic API key 欄位。金鑰會以加密方式儲存在主機上；VM 只會收到一個結構保留的假值，而代理伺服器僅在對 Anthropic 的請求上——別無他處——替換為真正的金鑰。目前請讓 Require approval to use 核取方塊維持關閉；開啟它會使應用程式在每個工作階段首次使用該金鑰時徵求您的同意（請參閱憑證）。

  2. 如果您有 Claude 訂閱： 選擇 Subscription (interactive login)——原廠預設值——並按一下 Register…。Bromure 會啟動一個臨時、用完即棄的 VM，該 VM 無法存取您的資料夾或憑證，在其中執行真正的 Claude 登入，並在您 Mac 的預設瀏覽器中開啟供應商的登入頁面。請在該處登入；您有幾分鐘的時間，之後流程便會逾時。成功後，擷取到的權杖會以加密方式儲存在主機上，用完即棄的 VM 隨即銷毀，接著應用程式會詢問要將此註冊分享給 Every workspace 或 Just this workspace。註冊完成後，卡片會顯示綠色印記以及 Re-register… 和 Forget 控制項。您的工作區 VM 從不自行執行 OAuth，也從不持有真正的權杖——主機會在傳輸過程中注入它們並處理更新。

  3. 這就是代理程式窗格在首次工作階段所需的全部設定。（一併啟用 Codex 或 Grok Build 的方式相同——每張卡片都有自己的驗證模式——但今天用一個代理程式就綽綽有餘。）

分享專案資料夾

  1. 在類別側邊欄中按一下 資料夾。此窗格列出將被掛載進 VM 的主機資料夾。如同說明文字所述，每個資料夾都以其真實名稱掛載——例如您 Mac 上的 ~/Documents 會在 VM 中顯示為 ~ubuntu/Documents——且一個工作區最多可掛載 8 個資料夾。全新的工作區會顯示「No folders shared.」。
工作區編輯器的資料夾窗格，內容為空，並顯示 Add folder… 按鈕
  1. 按一下 Add folder… 並在目錄選擇器中挑選您的專案資料夾。它會連同完整的主機路徑出現在清單中（若您改變主意，稍後可用減號按鈕移除它）。在 VM 內，它將即時存在於 /home/ubuntu/<basename>——是同一批檔案，而非複本，因此代理程式所做的變更會立即反映在您的 Mac 上。

附註： 分享資料夾是選擇性的。VM 的 /home/ubuntu 底下的一切內容在每個工作區中都是持久化的，因此您也可以在 VM 內複製（clone）一個儲存庫，讓沙箱與您 Mac 的檔案系統完全分離。刪除工作區絕不會影響已分享的主機資料夾。

  1. 按一下 Create。編輯器關閉後，您的工作區便會出現在側邊欄中，狀態標籤為 Off。

啟動工作階段

  1. 在側邊欄中按一下該工作區的列。右側的舞台會顯示工作區的儀表板：名稱下方的 Off 標籤、CPU、Memory、vCPUs、Disk 與 Uptime 的卡片（首次啟動前大多是破折號與零——磁碟會在首次啟動時建立）、列出您的代理程式與驗證模式的 CONFIGURATION 摘要、防護欄與提示注入掃描狀態，以及您分享的資料夾。按一下右上角的 啟動 按鈕。
主視窗：WORKSPACES 側邊欄含兩個工作區與 + 按鈕，以及一個已停止工作區的儀表板，顯示 CPU、Memory、vCPUs、Disk 與 Uptime 卡片、CONFIGURATION 摘要，以及啟動按鈕

  1. 首次啟動時，Bromure 會將工作區的私有系統磁碟建立為共用基底映像檔的寫入時複製（copy-on-write）複本——這是即時的，且幾乎不佔用磁碟空間——並以 4 個 vCPU 和儀表板上顯示的 RAM 啟動 VM（預設依您的 Mac 而定：4、6 或 8 GB）。VM 啟動期間，一個帶有工作區名稱與進度列的動畫覆蓋層會蓋住窗格；當客體的第一個終端機出現時它便會淡出，通常在數秒內完成。若 30 秒內沒有終端機出現，覆蓋層會切換為 DIVE FAILED 面板，並附有 Keep Waiting 與 Reset Base Image… 按鈕——若發生此情況，請參閱疑難排解。

  2. 啟動完成後，您會在舞台上看到一個終端機，而主要代理程式——Claude Code——已在其中執行，準備好接收提示。您絕不需在 VM 內執行 claude login；驗證已在傳輸邊界處理完畢。在側邊欄中，該工作區的狀態圓點現在呈綠色，狀態標籤顯示為 Running，而其第一個分頁（以前景程式標示，例如 claude）連同一個 Docker 節點巢狀於工作區列之下。視窗工具列現在會顯示此 VM 的一組控制項：其 IP 位址呈現為可點按複製的標籤，以及用於瀏覽檔案、重新開機、檢視追蹤記錄、編輯工作區、將工作階段彈出為獨立視窗，以及切換瀏覽器與儲存庫檔案窗格的按鈕。

執行第一個任務

  1. 在 Claude Code 提示處輸入一個任務，並以共享資料夾在 VM 內的路徑來引用它。例如：

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

    留意側邊欄中分頁圖示上的狀態圓點：代理程式工作時它會呈橘色脈動，完成時轉為綠色，需要您輸入時則轉為紅色。

  2. 由於共享資料夾是即時掛載，代理程式寫入的 README.md 會立即出現在您的 Mac 上——若您願意，可在 Finder 中查看。如果您的資料夾是一個 git 儲存庫，當使用中分頁的工作目錄進入該儲存庫時，儲存庫檔案總管窗格會自動開啟，以類似 IDE 的樹狀結構顯示 git 狀態與各檔案的差異；您也可以隨時以 ⌃⌘E 切換它。按 ⌘T 可在代理程式旁另開一個純粹的 shell 分頁——每個分頁都是同一個 VM 內 tmux 工作階段的一扇視窗。

  3. 代理程式所做的其他一切——apt install、npm install、在 VM 家目錄寫入用完即棄的檔案——都留在沙箱內。系統磁碟與家目錄會在工作階段之間持久保留，且兩者稍後皆可獨立重設（工作區）。

檢視追蹤記錄

  1. 按 ⇧⌘I（或按一下 檢視追蹤 工具列按鈕）以開啟追蹤檢視器。新的工作區以 AI request details 層級記錄：代理程式發出的每個網路請求都會連同主機、狀態與延遲一併列出，而對於已知的 LLM 主機，還會擷取完整的請求與回應主體。選取其中一個對 Anthropic 的請求，檢視器便會將其呈現為一段對話——含權杖計數的供應商與模型標頭、系統提示，以及以聊天氣泡呈現的使用者、助理與工具訊息。

  2. 在您的第一份追蹤記錄中，有兩件事值得留意。首先是替換報告：VM 持有的假 API 權杖在傳輸過程中被換成您真正的憑證，每個請求恰好一次，並限定於該供應商的主機。其次，所有擷取到的內容都留在您的 Mac 上，並在靜態時加密。追蹤層級、保留上限與洩漏警告詳見追蹤。

關閉與恢復

  1. 關閉工作階段：將滑鼠懸停在側邊欄的工作區列上並按一下其 × 按鈕（或在其最後一個分頁上按 ⌘W）。新的工作區的關閉動作設定為 Ask，因此會出現一個提示——「Close "My First Project"?」——並附有 Run in the Background、Suspend、Shut Down 與 Cancel 按鈕，以及說明：「Run in the background keeps the VM running so you can reattach later. Suspend saves its state to disk. Shut down powers it off.」。

  2. 按一下 Suspend。VM 的 RAM 會被快照到磁碟，側邊欄該列的狀態標籤變更為 Suspended。沒有任何東西遺失——代理程式的對話、您的 shell 歷史記錄、分頁配置皆完好無損。

  3. 恢復：按一下該工作區並在其儀表板上按 Resume（或使用該列的 ⋯ 選單 →Resume）。工作階段幾乎即時還原，完全停在您離開的位置——相同的終端機，而 Claude Code 正處於對話進行中。

  4. 若您希望關閉時總是採取相同的行為，開啟該列的 ⋯ 選單 →Edit…，並在一般窗格中將 When closing the window 設為 Suspend（或 Run in the background / Shut down），如此提示便不會再出現。請參閱設定 — 一般。

提示： 已暫停或已關閉的工作區會保留其系統磁碟與家目錄。銷毀資料永遠是明確的行為——Reset disk、Erase home… 或 Delete workspace——而且即使刪除工作區，也絕不會影響您分享進去的主機資料夾。

後續延伸閱讀

  • 概念 — 您方才所做一切背後的思維模型：工作區、VM 生命週期、傳輸邊界，以及各部分如何協同運作。
  • 工作區 — 複製、重設與刪除工作區；儲存層、檢查點，以及每個新工作區據以分支而來的偏好設定範本。
  • 工作階段 — 分頁與 git 工作樹、終端機 Grid、代理式瀏覽器窗格、進出 VM 的檔案傳輸，以及每個鍵盤快速鍵。
  • 設定參考 — 每個設定窗格各佔一頁，包括本導覽中提到的代理程式與資料夾。
  • 憑證 — 完整的憑證目錄（git 權杖、SSH 金鑰、AWS、Kubernetes、容器登錄檔、資料庫等）、核准提示，以及假值換真值的替換機制詳解。
  • 追蹤 — 追蹤層級、追蹤檢視器與洩漏偵測。
  • 供應鏈與提示注入 — 在讓代理程式接觸不受信任的程式碼之前，您可為工作區疊加的防護措施。
  • Fusion與本機模型 — 同時以多個模型回應提示，以及在您的 Mac 上而非雲端執行模型。
  • 自動化與 CLI — 透過指令碼、HTTP API 與 bromure-cli mcp 伺服器驅動工作區。