rivet-dev/agentos

agentOS – an “operating system” for AI agents (Node.js library)

What it is – agentOS is an npm‑packaged runtime that lets you spin up tiny, isolated virtual machines inside your own Node.js process and run AI agents (Claude‑Code, Codex, Pi, OpenCode, or your own) inside them. The VMs are built on a side‑car kernel that emulates a POSIX‑like environment, offers a real filesystem, processes, and network stack, but never touches the host OS directly. Think of it as a lightweight sandbox that starts in a few milliseconds, uses only tens of megabytes of RAM, and can be persisted, scheduled, or orchestrated just like any other server‑side component.

---

Why it matters

Claim	What the README says
Fast cold‑starts	4.8 ms median start vs ~440 ms for the fastest public sandbox (≈92× faster).
Low memory	22 MB for a simple shell command vs ~1 GiB for a comparable sandbox (≈47× smaller).
Cheap to run	Up to 2 800× cheaper per execution‑second on Hetzner ARM compared with mainstream sandboxes.
Runs in‑process	No micro‑VMs, containers, or nested virtualization – just V8 isolates and WebAssembly.
Granular security	Permissions control filesystem, network, process, and env access; outbound network is denied by default.
Deploy anywhere	Use as a plain npm package, run locally with npx rivetkit dev, or deploy to Rivet Cloud or self‑host.

---

Core concepts

Concept	Description
VM	A lightweight virtual machine (V8 isolate + side‑car kernel) that hosts an agent and any software you install.
Agent	An LLM‑backed “coding” or “assistant” model (Pi, Claude‑Code, Codex, OpenCode) that talks to the VM via the Agent Client Protocol (ACP).
Registry	An npm‑based catalog (@agentos-software/*) of agents, POSIX utilities, browsers, and other software you can add to a VM.
Bindings	Host‑side JavaScript functions exposed to the VM as CLI‑style commands, letting agents call your own code safely.
Persistence	Every conversation/session is automatically saved; you can resume later or replay for debugging.
Orchestration	Built‑in support for multiplayer observation, agent‑to‑agent delegation, workflows with retries/branching, cron jobs, and webhooks.

---

Highlighted features

• Built‑in agents – Pi, Claude‑Code (beta), Codex (beta), OpenCode, plus a simple way to add custom agents.
• Unified transcript format – Same log schema for all agents, making debugging and audit trails easy.
• Full process support – Run Bash, Node.js, Python, or any registered binary inside the VM; you can exec, read/write files, etc.
• Mountable storage – Attach S3‑compatible buckets, Google Drive, host directories, or in‑memory mounts as the VM’s filesystem.
• Browser access (beta) – Cloud‑based Browserbase instance can be mounted, letting agents control a headless browser.
• Sandbox mounting (beta) – When a workload needs a full Linux sandbox, agentOS can spin up an external sandbox (E2B, Daytona, etc.) and mount its filesystem on demand.
• Security – Per‑VM permissions, network egress control, CPU/memory limits, and complete isolation via the side‑car kernel.
• Rivet Actor integration – Each VM is a durable actor with built‑in persistence, sleep/wake, and preview URLs.

---

Typical use cases

1. AI‑assisted coding assistants – Deploy a coding‑agent (Pi, Claude‑Code) that can read/write files, run node, bash, or other tools, and return results to a web UI.
2. Server‑side tool automation – Expose internal functions as bindings and let an LLM orchestrate them (e.g., data‑pipeline steps, admin scripts).
3. Multi‑user collaborative agents – Use the multiplayer feature so several front‑ends can watch and interact with the same agent session.
4. Workflow orchestration – Chain multiple agent tasks with retries and branching, persisting state between steps.
5. Secure, low‑cost sandboxing – Run untrusted code (user‑submitted scripts, plugins) inside an isolated VM without the overhead of a full container.

---

Quick‑start (from the README)

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

Server (defines the 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();

Client (talks to the 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));

Run the two files with tsx (or any Node‑compatible runner) and you have a fully functional AI coding assistant that lives inside your process.

---

Where to learn more

• Docs & quick‑start – https://agentos-sdk.dev/docs
• Registry of software – https://agentos-sdk.dev/registry
• Benchmarks & methodology – https://agentos-sdk.dev/docs/benchmarks
• Discord community – https://rivet.dev/discord

---

License

Apache‑2.0 (per the repository’s LICENSE file).