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 文件）。