【2026 最新】Pi pod 自架教學：遠端 Coding Agent 的隔離與續跑怎麼驗？

想讓 Coding Agent 在遠端跑到你關掉筆電之後，還能回來接著看？Pi pod 自架把 Pi 放進伺服器上的 pod，但「有 pod」不等於你已驗證檔案、網路、憑證與任務續跑的邊界。

這篇寫給第一次管理遠端 Coding Agent 的讀者。你會先用官方自架路徑啟動低權限測試環境，再用同一份假資料做三組檢查；每一步都寫出應記錄什麼，讓你能判斷它相對普通 Docker 是否值得多維護一套服務。以下是依 2026 年 10 月 4 日官方文件與原始碼整理的驗收流程，文中沒有宣稱 AlphaLab 已在 Linux 主機執行這些測試。

先說結論：Pi pod 自架到底多了什麼？

一句話：Pi pod＝共享 Linux 核心的隔離工作區＋帳號與 pod 管理＋遠端連線；普通 Docker＝你自行組裝這些能力的容器基礎。Pi pod 的比較重點是管理和預設邊界，不能把它寫成每個 pod 都有獨立核心的 microVM。

官方 README 把服務分成 CLI、控制平面、原生 sandbox 和自架 Compose 專案。自架指南明說 sandbox service 以 privileged 運行、操作 cgroup 與網路命名空間，隔離邊界是主機核心。Docker 官方也把 namespace、cgroup、掛載與權限列為容器安全邊界。

Pi pod 自架前，先畫出四層邊界

1. 控制平面：server 管 pod 生命週期，Postgres 保存產品資料，Zitadel 管身分。它們和執行程式的 pod 不是同一個角色。
2. 工作區：每個 pod 在 sandbox service 中有自己的工作區；檔案是否可見，還要看種子資料、掛載及後續同步。
3. 網路：pod 需要連到 server 與模型服務。官方預設限制私有、共享與保留位址的出口，但管理員能用 PI_POD_SANDBOX_PRIVATE_EGRESS 加例外。
4. 憑證：提供者認證與使用者自行設定的 org/user/template secrets 是不同路徑。官方 CLI 文件說，獲授權的 pod 程式可讀繼承的 secret 值；因此「秘密有加密儲存」不代表執行中的 pod 看不到。

把 pod 想成遠端工作桌：桌上只放這次需要的檔案，門禁決定誰能進來，網路規則決定能打給誰。驗收時要分別看桌面、門禁、電話線；單看 docker ps 不能得出完整結論。

Pi pod 自架：先用低權限帳號開一個測試 Pod

官方自架指南要求 Linux、cgroup v2、Docker Compose、Git、OpenSSL，以及供 CLI 使用的 Node 22.19 以上；建議 8 GB RAM。下面指令在你自己的測試 Linux 主機操作，先限制主機對外的 8080，再考慮對外開放。

1. 取得固定版本。執行 git clone https://github.com/pi-pod/pipod.git && cd pipod，用 git rev-parse HEAD 記下 commit；不要讓兩次比較默默換版本。
2. 安裝服務。執行 selfhost/upgrade；首次執行會建立 selfhost/.env、建置服務與 pod 基底映像。把 ZITADEL_MASTERKEY 和 SECRETS_KEK 另行離線備份，勿貼到測試紀錄。
3. 建立測試成員。管理員可執行 selfhost/add-user tester@example.com；刻意不加 --owner。請把範例信箱換成自己控制的測試帳號，並用它登入。
4. 安裝同版 CLI。在該 checkout 執行 (cd cli && npm ci && npm run build) && npm install -g ./cli，接著 pipod login --server http://127.0.0.1:8080、pipod doctor、pipod credentials connect，使用可撤銷的測試模型憑證。遠端 SSH 登入時依官方文件轉送 Zitadel 的 8081 連接埠。
5. 建立無機密測試目錄。新建一個只含 public.txt 與假代號的目錄，先執行 pipod --dry-run 看 CLI 將上傳或 clone 哪些內容，再執行 pipod 建 pod。別從含真實憑證的工作樹開始。

依照CLI 文件區分 provider credentials 和一般 secrets；本輪只放可撤銷的測試憑證與假資料。如果 pod 啟動失敗，先看 pipod doctor、cd selfhost && docker compose ps 和 docker compose logs -f server，把錯誤訊息與 commit 一起記下。

Pi pod 與普通 Docker：同一組任務怎麼比較？

別拿預設 Pi pod 和故意開放所有權限的 Docker 比。建立一份相同的假檔案，為兩邊記錄同一張四欄工作表：操作、預期可見範圍、實際觀察、設定差異。Docker 對照組可依Pi 的官方容器文件建立；其範例使用 Dockerfile.pi、工作目錄 bind mount，以及保存 Pi 設定的 named volume。

① 檔案：工作區以外看得見什麼？

在兩邊只放 public.txt，另於主機的另一個資料夾放 outside-sentinel.txt。在 pod 裡使用 Pi 的 shell 命令 !pwd、!ls -la，再請它嘗試讀取事先選定的外部路徑。記錄成功、拒絕或「路徑不存在」，不要只記一個「安全」。普通 Docker 同樣只掛載測試目錄，並分別記錄唯讀掛載與可寫掛載的結果；Docker bind mount 文件說明主機路徑會直接成為容器可用的路徑。

② 網路：限制的是內網還是所有出口？

先準備你控制的 HTTP 測試端點，再選一個不含資料的內網測試位址。記錄 pod 對兩者的連線結果，以及 PI_POD_SANDBOX_PRIVATE_EGRESS 是否設定例外。對照 Docker 時把 --network、DNS 與出口規則逐一寫下；只寫「都在容器」沒有比較意義。不要把連線成功推論成可讀取任意主機資料，也不要把單次連線失敗推論成永久禁止。

③ 憑證：讀到的是值、metadata，還是完全沒有？

先使用無效的假值，不要試真實金鑰。分別記錄 pod 的環境變數、Pi 設定目錄與可見檔案。Pi pod 官方Secrets 章節指出 org/user/template secret 可被獲授權 pod 內的程式讀取，而 provider credentials 有不同處理；Docker 官方run 文件指出 -e 會把環境變數帶入容器。你的結論必須註明當次設定和憑證類型。

中斷與續跑：分清「檔案還在」和「工作真的接上」

官方自架指南說，升級重建 sandbox 會結束當下 session，但 sandbox_state volume 留住工作區，重新 attach 可再看到 pod 檔案。這只能支持檔案持久性，不能直接證明任何進行中的外部副作用會恰好執行一次。

1. 留下檔案檢查點。在測試 pod 建立 checkpoint.txt，寫入唯一假代號，記下 pod ID、時間與目前對話位置。
2. 先測斷線。關閉客戶端連線，再用 pipod attach <pod-id> 返回；記錄檔案、對話、正在執行的命令各自狀態。
3. 再測停機。執行 pipod stop <pod-id>，接著 pipod attach <pod-id>；重讀 checkpoint.txt，並與 pipod list 顯示的 pod 狀態對照。
4. 最後測服務重啟。在可回復的測試主機，記錄 docker compose logs -f sandbox 和 server 日誌，按官方維運指令重啟服務，再 attach。比較的是檔案、會話上下文和外部動作三欄，不要合併成一句「能續跑」。

想深入理解「程序重啟後，工具呼叫是否重複」的驗收方法，可看 Pi Durable 的中斷續跑三關；那是另一套任務持久化機制，不能把它的 SQLite 行為直接算到 Pi pod 身上。

何時選 Pi pod？何時先用普通 Docker？

• 選 Pi pod：你要從不同裝置連回同一套遠端 Pi、管理多位成員和 pod，願意維護 Postgres、Zitadel、server 與 sandbox。
• 先用普通 Docker：你只要在單一主機隔離一個 Pi 工作區，能自行設計掛載、網路、密鑰和重啟流程。
• 要更強的核心隔離：你的威脅模型要求獨立核心時，應評估 microVM 或 VM 路線；Pi pod 自架文件明說目前的邊界是共享主機核心。可接著看 Docker Sandboxes 與 microVM 的差別。

成本也要算整套：Pi pod 的服務、備份、主機資源、身分系統與你使用的模型額度。官方指南以 8 GB 主機跑一個標準 pod 作為容量例子，但你的可用數量會隨 pod 規格及其他服務負載改變。

Pi pod 自架常見問題

Pi pod 是 microVM 嗎？

不是依官方自架架構所能稱的 microVM。官方文件把隔離邊界寫成主機核心，並說明 sandbox service 使用 cgroup 與網路命名空間。

普通 Docker 可以做到同樣的檔案限制嗎？

可以設計相近的掛載策略。請用相同的唯讀／可寫掛載、同一份假資料測，並把設定成本一起比較。

Pi pod 的 secrets 對 pod 程式保密嗎？

依 secret 類型與授權而定。官方 CLI 文件明確說，獲授權的 pod 程式能讀繼承的 org/user/template 值。

關閉筆電會停掉 pod 嗎？

斷線與 pod 停止是兩個事件。用 pipod list 和重新 attach 核對，不要只憑客戶端畫面推論。

停止 pod 後檔案還在嗎？

官方文件描述 stopped pod 保留檔案。依上面檢查點步驟驗收你自己的部署；刪除 volume 則是不同操作。

升級會不會打斷目前工作？

會打斷當下 live session。官方升級指南說 sandbox 重建會結束 live sessions，工作區由 sandbox_state volume 保存。

可以把測試服務直接暴露在網路上嗎？

先按官方 HTTPS 與防火牆路徑設定。初次安裝的 8080 對所有介面監聽；跨裝置使用須依自架指南配置 HTTPS 與身分服務。

怎樣知道 Pi pod 比 Docker 值得？

看你是否需要遠端會話與多人管理。三組邊界測試和中斷紀錄填完後，再衡量維護四個服務的代價。

新手帶走的三個重點

1. 先記下版本、掛載、網路、secret 類型，再比較產品。
2. 把續跑拆成檔案、對話、外部動作三種證據。
3. 把 Pi pod 看成遠端 Agent 管理系統；它的容器邊界仍須按共享核心的威脅模型評估。