rivet-dev/agentos

agentOS – AI 代理的「作業系統」（Node.js 函式庫）

這是什麼 – agentOS 是一個 npm 打包的執行階段，讓您可以在自己的 Node.js 行程內啟動微小且隔離的虛擬機，並在其中執行 AI 代理（Claude-Code、Codex、Pi、OpenCode 或您自己的代理）。這些 VM 建構於 side-car 核心之上，模擬類 POSIX 環境，提供真實的檔案系統、行程與網路堆疊，但絕不直接碰觸主機作業系統。您可以將它視為一個輕量級沙盒，在幾毫秒內啟動，僅使用數十 MB 的 RAM，並且可以像任何其他伺服器端元件一樣被持久化、排程或協調。

---

為什麼它很重要

宣稱	README 的說明
快速冷啟動	4.8 ms 中位數啟動時間，相較於最快的公開沙盒約 440 ms（快約 92 倍）。
低記憶體	執行簡單 shell 指令僅需 22 MB，相較於同類沙盒約 1 GiB（小約 47 倍）。
執行成本低	在 Hetzner ARM 上，每次執行秒數的成本比主流沙盒便宜高達 2,800 倍。
行程內執行	無需 micro-VM、容器或巢狀虛擬化 – 僅使用 V8 isolates 與 WebAssembly。
細粒度安全性	權限控制檔案系統、網路、行程與環境變數存取；預設拒絕對外網路連線。
隨處部署	作為普通 npm 套件使用，透過 npx rivetkit dev 在本機執行，或部署到 Rivet Cloud 或自行託管。

---

核心概念

概念	描述
VM	輕量級虛擬機（V8 isolate + side-car 核心），用於託管代理與您安裝的任何軟體。
Agent	由 LLM 驅動的「編碼」或「助理」模型（Pi、Claude-Code、Codex、OpenCode），透過 Agent Client Protocol (ACP) 與 VM 通訊。
Registry	基於 npm 的目錄（@agentos-software/*），包含可加入 VM 的代理、POSIX 工具、瀏覽器與其他軟體。
Bindings	暴露給 VM 作為 CLI 風格指令的主機端 JavaScript 函式，讓代理能安全地呼叫您自己的程式碼。
Persistence	每個對話/會話都會自動儲存；您可以稍後恢復或重播以進行除錯。
Orchestration	內建對多人觀察、代理間委派、帶有重試/分支的工作流程、cron 排程任務與 webhooks 的支援。

---

精選功能

• 內建代理 – Pi、Claude-Code（beta）、Codex（beta）、OpenCode，以及新增自訂代理的簡單方式。
• 統一的紀錄格式 – 所有代理使用相同的日誌結構描述，讓除錯與稽核追蹤變得容易。
• 完整的行程支援 – 在 VM 內執行 Bash、Node.js、Python 或任何已註冊的二進位檔案；您可以 exec、讀寫檔案等。
• 可掛載的儲存空間 – 附加 S3 相容儲存桶、Google Drive、主機目錄或記憶體內掛載作為 VM 的檔案系統。
• 瀏覽器存取（beta） – 可掛載基於雲端的 Browserbase 實例，讓代理控制無頭瀏覽器。
• 沙盒掛載（beta） – 當工作負載需要完整的 Linux 沙盒時，agentOS 可以啟動外部沙盒（E2B、Daytona 等）並按需掛載其檔案系統。
• 安全性 – 每個 VM 獨立的權限、網路出口控制、CPU/記憶體限制，以及透過 side-car 核心實現的完全隔離。
• Rivet Actor 整合 – 每個 VM 都是一個具有內建持久性、睡眠/喚醒與預覽 URL 的持久性 actor。

---

典型使用情境

1. AI 輔助編碼助理 – 部署一個編碼代理（Pi、Claude-Code），能夠讀寫檔案、執行 node、bash 或其他工具，並將結果回傳至 Web UI。
2. 伺服器端工具自動化 – 將內部函式暴露為綁定，讓 LLM 協調它們（例如：資料管線步驟、管理腳本）。
3. 多使用者協作代理 – 使用多人功能，讓多個前端可以觀看並與同一個代理會話互動。
4. 工作流程協調 – 將多個代理任務與重試和分支串連，在步驟之間持久化狀態。
5. 安全、低成本的沙盒 – 在隔離的 VM 內執行不受信任的程式碼（使用者提交的腳本、外掛），而無需承擔完整容器的開銷。

---

快速開始（節錄自 README）

# Install core library and a built‑in agent
npm install @rivet-dev/agentos @agentos-software/pi

伺服器（定義 VM）

// server.ts
import { agentOS, setup } from "@rivet-dev/agentos";
import pi from "@agentos-software/pi";

const vm = agentOS({ software: [pi] });
export const registry = setup({ use: { vm } });
registry.start();

客戶端（與 VM 通訊）

// client.ts
import { createClient } from "@rivet-dev/agentos/client";
import type { registry } from "./server";

const client = createClient<typeof registry>({ endpoint: "http://localhost:6420" });
const handle = client.vm.getOrCreate("my-agent");

const conn = handle.connect();
conn.on("sessionEvent", e => console.log(e));

await handle.openSession({ agent: "pi", env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! } });
await handle.prompt({ content: [{ type: "text", text: "Write a hello world script to /workspace/hello.js" }] });
const content = await handle.readFile("/workspace/hello.js");
console.log(new TextDecoder().decode(content));

使用 tsx（或任何 Node 相容的執行器）執行這兩個檔案，您就擁有一個存在於您行程內的全功能 AI 編碼助理。

---

延伸閱讀

• 文件與快速開始 – https://agentos-sdk.dev/docs
• 軟體目錄 – https://agentos-sdk.dev/registry
• 基準測試與方法論 – https://agentos-sdk.dev/docs/benchmarks
• Discord 社群 – https://rivet.dev/discord

---

授權條款

Apache-2.0（根據該儲存庫的 LICENSE 檔案）。