agentOS：把 agent 執行環境當成函式庫塞進你的後端

agentOS 想解的是沙箱啟動的固定成本

多數 agent 執行環境的預設做法是開一台微 VM 或拉一個容器。這個做法換來完整 Linux 環境，但每次執行都要付開機成本。README 把 agentOS 定位成另一條路線：一個跑在你行程內的輕量 VM，沒有 microVM 要開機、沒有容器要拉、沒有巢狀虛擬化。它鎖定的讀者是已經有 Node.js 後端、想把 agent 當成函式呼叫而不是另一個網路服務的團隊。

這個定位排除了某些人。如果你要的是瀏覽器、原生二進位或 dev server，README 自己說了那是 sandbox 的領域。agentOS 的目標是那些 agent 工作內容以 JavaScript、shell 與文字處理為主的場景。它內建 coreutils、sed、grep、gawk、findutils、diffutils、tar、gzip，這個清單透露了它預期的使用型態：檔案操作、文字轉換、腳本執行。

README 開頭列出 92x 冷啟動、47x 記憶體、254x 成本的數字。這些是專案自己提供的 benchmark，對照組是 2026 年 3 月 30 日當時主流沙箱供應商，方法是 agentOS 跑在 Intel i7-12700KF。我沒有重跑這些數字，它們只能當成專案方的宣稱，不能當成你的環境會得到的結果。真正該帶走的訊息不是倍數，而是架構差異：行程內執行與跨網路呼叫，本質上不是同一個量級的東西。

V8 isolate 加 WebAssembly：兩個隔離層如何分工

agentOS 的隔離由兩層組成。客端 JavaScript 跑在 V8 isolate 裡，編譯過的工具跑成 WebAssembly，兩者共用同一個精簡 runtime。這個切法有實際後果：V8 isolate 提供的是 JavaScript 層級的隔離，不是核心層級的隔離。它擋得住 JS 之間的互相干擾，但不像 microVM 那樣給你一個獨立核心。

權限因此變成主要防線，而不是附加功能。README 說明 permissions 會管制檔案系統、網路、行程與環境變數存取，其中像 network egress 這種對外能力預設是拒絕的。這個預設值很重要：預設拒絕意味著你必須主動開啟才能連外，而不是反過來。

bindings 是另一條界線。agent 透過 bindings 直接呼叫你的函式，README 的措辭是「ordinary JavaScript calls, not another network service」。憑證留在 host 上，agent 只看得到輸入與輸出。這對處理 API key 的場景是實質差別：agent 不需要持有憑證，也就不會把憑證寫進它產生的檔案或日誌。

要注意的是，這套模型的前提是你的信任邊界畫在「agent 不該拿到憑證」而不是「agent 不該碰到核心」。如果你需要的是後者，這個架構不提供。

從 npm install 到第一個 prompt

安裝是兩個套件：`npm install @rivet-dev/agentos @agentos-software/pi`。Pi 是內建 agent 之一，Claude Code、Codex、OpenCode 用同樣方式安裝，其中後三者 README 標示為 beta。

伺服器端用 `agentOS({ software: [pi] })` 建立 VM，再以 `setup({ use: { vm } })` 註冊並呼叫 `registry.start()`。客戶端從 `@rivet-dev/agentos/client` 匯入 `createClient`，帶入 `endpoint`，預設埠是 `http://localhost:6420`。取得 handle 的方式是 `client.vm.getOrCreate("my-agent")`。

串流事件走 `handle.connect()` 回傳的連線，用 `conn.on("sessionEvent", ...)` 訂閱，README 說 payload 型別會從 event schema 推導出來。開啟 session 用 `handle.openSession({ agent: "pi", env: { ANTHROPIC_API_KEY: ... } })`，送 prompt 用 `handle.prompt({ content: [{ type: "text", text: ... }] })`。檔案讀寫是 `handle.readFile` 與 `handle.writeFile`，執行指令是 `handle.exec`。

本機啟動的指令是 `npx rivetkit dev`，README 的 quickstart 則用 `npx tsx server.ts` 與 `npx tsx client.ts` 分別跑兩個終端機。要注意 `env` 是把 `ANTHROPIC_API_KEY` 傳進 VM，這與 bindings 把憑證留在 host 的說法方向不同，實作時值得確認這條路徑的可見範圍。

部署形態有兩種。`@rivet-dev/agentos` 把每個 VM 當成 Rivet Actor 跑，附帶持久化、sleep/wake、multiplayer、preview URL 與 orchestration。若要把 VM 控制嵌進既有 Node.js 應用而不引入 actor runtime，改用 `@rivet-dev/agentos-core`，以 `AgentOs.create()` 開機並取得 handle 直接呼叫。這個二選一要先決定，因為它影響你後面所有的部署與維運安排。

preview 標籤與 API 變動風險

README 明確寫著 agentOS is in preview and the API is subject to change。這不是客套話，而是採用決策的核心變數。從 release 清單看，v0.2.19 之後接著 v0.2.20-rc.1，版本號還在 0.2 系列，rc 標籤出現的頻率高。這表示介面仍在調整期。

實務上的意思是：把 agentOS 放進正式路徑之前，你要有能力吸收升級帶來的改動。如果 `handle.openSession`、`handle.prompt` 這類呼叫的參數形狀在 0.3 改動，你的整合層要跟著改。這對內部工具或實驗性功能是可接受的成本，對外販售的產品則需要更嚴謹的版本鎖定策略。

另一個限制來自架構本身。行程內執行意味著 agent 的資源消耗與你的後端共用同一個位址空間。README 給的記憶體數字是每個實例約 131 MB（完整 coding agent）與約 22 MB（簡單 shell 指令）。這些是專案方量測值，但你應該把它當成量級參考而不是容量規劃依據，因為你的 agent 載入多少工具、處理多大的檔案都會改變這個數字。當單一行程內同時跑多個 VM，累加起來的記憶體壓力會直接反映在你的服務上，而不是被 hypervisor 吸收掉。

與 sandbox 的差異，以及兩者並用的方式

README 自己做了對照：agentOS 是跑在行程內的輕量 VM，sandbox 是完整 Linux 環境。這個差異不是效能數字，而是能力邊界。sandbox 給你完整作業系統，所以瀏覽器、原生二進位、dev server 都能跑。agentOS 給你的是 JavaScript 與 WebAssembly 兩個執行層，加上一組內建 POSIX 工具。

選擇的判準因此很清楚。如果你的 agent 工作是把資料轉成檔案、跑腳本、做文字處理，agentOS 的啟動與記憶體優勢是實的。如果工作內容需要一個真正的 Linux 使用者空間，agentOS 不是替代品，硬套會撞牆。

README 也給了並用路徑：sandbox mounting 讓 agentOS 按需開一台完整 sandbox，並把 sandbox 的檔案系統掛進來。這個設計承認了兩者不是互斥選項。實際架構上，你可以把常用路徑留在 agentOS 內，把少數需要完整環境的工作卸載到掛載的 sandbox。代價是你同時維運兩套東西，掛載點的檔案一致性與生命週期要自己想清楚，README 沒有交代這部分的細節。

與 E2B、Daytona 這類沙箱供應商的比較，README 用的是冷啟動、記憶體與成本三組數字。這些數字有明確的方法論連結與對照組設定，但仍是單方面提供的 benchmark。要判斷是否適用於你，唯一可靠的方式是在自己的硬體與工作負載上量一次。

授權、維護成本與升級路徑

授權是 Apache-2.0，對於要嵌進商業後端的函式庫來說是寬鬆的選擇，專利授權條款也在其中。這裡不談法律意見，只指出採用時該確認的事：你的法務或開源政策是否接受 Apache-2.0，以及你會不會修改原始碼後再散布。

維護成本主要來自兩處。第一是版本節奏。從 release 時間看，v0.2.19 在 9 月 2 日，v0.2.20-rc.1 在 9 月 9 日，一週內就有新版本進入 rc。這種節奏下，把版本固定在特定 minor 並定期評估升級，比跟著最新版跑更可控。

第二是內建 agent 的版本綁定。Pi、Claude Code、Codex、OpenCode 是以獨立套件形式安裝，像 `@agentos-software/pi`。這意味著 agent 本身的行為變更與 agentOS 核心的變更可以分開發生。你的升級計畫要同時考慮這兩條線，否則可能出現核心沒動但 agent 行為改變的情況。

部署上還有一個要自己驗的數字：Docker 映像大小。README 說 coreutils、sed、grep、gawk、findutils、diffutils、tar、gzip 隨附，但沒有給出打包後的體積。如果你的部署環境對映像大小敏感，這是要在導入前量測的項目。

該不該採用：三個具體的驗證動作

先確認部署形態。如果你已經有 Rivet Actor 的基礎設施，用 `@rivet-dev/agentos` 可以拿到持久化、sleep/wake 與 preview URL。如果你只是想在既有 Node.js 服務裡開一個 VM，用 `@rivet-dev/agentos-core` 的 `AgentOs.create()`，避免引入整個 actor runtime。這個決定會影響你後面所有的維運安排，值得先花時間想清楚。

再驗權限設定。README 說 network egress 預設拒絕，但 quickstart 的範例把 `ANTHROPIC_API_KEY` 透過 `env` 傳進 VM。你要確認自己場景裡哪些環境變數真的需要進到 VM，以及 permissions 的實際顆粒度能否對應你的需求。文件對 permissions 的說明在 README 中只有一段，細節要看 agentos-sdk.dev/docs/permissions。

最後量測你自己的數字。README 的 131 MB 與 22 MB 是特定工作負載的結果，你的 agent 載入多少工具、處理多大的檔案都會改變它。在你的硬體上跑一輪，觀察單一行程內多個 VM 並存時的記憶體曲線，再對照你的容量規劃。這一步沒有替代方案。

編輯結論

如果你的 agent 只需要跑 JavaScript、shell 與內建 POSIX 工具，而且你願意接受 preview 期 API 變動，agentOS 值得在 staging 環境先跑一輪：先確認 @rivet-dev/agentos 與 @rivet-dev/agentos-core 哪個符合你的部署形態，再用 permissions 把 network egress 明確關掉，量測你自己工作負載下的常駐記憶體。需要瀏覽器、原生二進位或 dev server 的工作負載不要用它，改用 sandbox mounting 把完整 Linux 環境掛進來。最後要驗的是 Docker 映像大小與 actor 喚醒延遲，這兩項 README 沒有給數字。

官方來源

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. rivet-dev/agentos on GitHub