- Give agents an operating system as a library. 92x faster cold starts, 47x less memory, 254x cheaper than sandboxes. Built-in ACP agents: Pi, Claude Code, Codex, and OpenCode
+ Give agents an operating system as a library.
+ Each agent gets a lightweight OS with filesystem, execution, and orchestration.
+ Runs in your existing backend – no sandboxes, VMs, or SaaS.
-
-## Why agentOS
-
-- **Runs inside your process**: No microVMs to boot, no containers to pull, no nested virtualization. Warm VM creation takes single-digit milliseconds and each VM costs tens of megabytes.
-- **Embeds in your backend**: Agents call your functions directly via [bindings](https://agentos-sdk.dev/docs/bindings) — ordinary JavaScript calls, not another network service. Credentials stay on the host; agents see only inputs and outputs.
-- **Granular security**: [Permissions](https://agentos-sdk.dev/docs/permissions) gate filesystem, network, process, and environment access, with outward-facing capabilities like network egress denied by default. Guest JavaScript runs in V8 isolates and compiled tools run as WebAssembly, all inside one compact runtime.
-- **Deploy anywhere**: Just an npm package. Run locally with `npx rivetkit dev`, then deploy to [Rivet Cloud](https://agentos-sdk.dev/docs/deployment) for managed infrastructure or self-host on your own.
-- **Open source**: Apache 2.0 licensed.
-
-### agentOS vs Sandbox
-
-agentOS is a lightweight VM that runs inside your process. Sandboxes are full Linux environments. agentOS integrates agents into your backend with [bindings](https://agentos-sdk.dev/docs/bindings) and granular permissions. Sandboxes give you a full OS for browsers, native binaries, and dev servers.
-
-You don't have to choose: agentOS works with sandboxes through [sandbox mounting](https://agentos-sdk.dev/docs/sandbox), spinning up a full sandbox on demand and mounting the sandbox's file system when the workload needs it.
-
-See [agentOS vs Sandbox](https://agentos-sdk.dev/docs/versus-sandbox) for a full comparison.
+
## Quick start
+**1. Install agentOS and the agents you want**
+
```bash
-npm install @rivet-dev/agentos @agentos-software/pi
+npm install @rivet-dev/agentos
+
+# Install the agent you want to run in agentOS
+npm install @agentos-software/pi # Pi
+npm install @agentos-software/claude-code # Claude Code (beta)
+npm install @agentos-software/codex # Codex (beta)
+npm install @agentos-software/opencode # OpenCode
```
-Common POSIX utilities (coreutils, sed, grep, gawk, findutils, diffutils, tar, gzip) ship out of the box. [Claude Code](https://agentos-sdk.dev/docs/agents/claude), [Codex](https://agentos-sdk.dev/docs/agents/codex), and [OpenCode](https://agentos-sdk.dev/docs/agents/opencode) install the same way as Pi.
+See more Linux software in the [registry](https://agentos-sdk.dev/registry). Also supports [Flue](https://agentos-sdk.dev/docs/frameworks/flue), [Eve](https://agentos-sdk.dev/docs/frameworks/vercel-eve), and [custom agents](https://agentos-sdk.dev/docs/agents/custom).
-Create the server:
+**2. Set up the server**
```ts
// server.ts
@@ -50,151 +50,307 @@ export const registry = setup({ use: { vm } });
registry.start();
```
-Create the client — any public frontend or another backend:
+**3. Connect to agentOS**
```ts
// client.ts
import { createClient } from "@rivet-dev/agentos/client";
import type { registry } from "./server";
-const client = createClient({
- endpoint: "http://localhost:6420",
-});
-const handle = client.vm.getOrCreate("my-agent");
+const client = createClient("http://localhost:6420");
+const vm = client.vm.getOrCreate("my-agent");
-// Subscribe to streaming events. The payload is inferred from the event schema.
-const conn = handle.connect();
+// Subscribe to streaming events.
+const conn = vm.connect();
conn.on("sessionEvent", (event) => {
console.log(event);
});
// Open a durable session and send a prompt.
-await handle.openSession({
+await vm.sessions.open({
agent: "pi",
env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});
-await handle.prompt({
+await vm.sessions.prompt({
content: [
{ type: "text", text: "Write a hello world script to /workspace/hello.js" },
],
});
-// Read the file the agent created
-const content = await handle.readFile("/workspace/hello.js");
+// Read the file the agent created.
+const content = await vm.filesystem.readFile("/workspace/hello.js");
console.log(new TextDecoder().decode(content));
```
-Run both:
-
```bash
-# Terminal 1: start the server
-npx tsx server.ts
-
-# Terminal 2: run the client
-npx tsx client.ts
+npx tsx server.ts # terminal 1
+npx tsx client.ts # terminal 2
```
-agentOS can run Node.js and shell scripts inside the VM:
+Deploy it wherever your backend already runs, on [Rivet Cloud](https://dashboard.rivet.dev), or
+self-hosted on Kubernetes, VMs, or bare metal. See [Deploy](https://agentos-sdk.dev/docs/deployment).
+
+**Alternative: direct VM API**
+
+Instead of a client-server architecture, install `@rivet-dev/agentos-core` and boot a VM
+directly inline:
```ts
-// Node.js
-await handle.writeFile("/hello.mjs", 'import fs from "fs"; fs.writeFileSync("/out.txt", "hi")');
-await handle.exec("node /hello.mjs");
+import { AgentOs } from "@rivet-dev/agentos-core";
+import pi from "@agentos-software/pi";
-// Bash
-const result = await handle.exec("cat /out.txt");
-console.log(result.stdout); // "hi"
+const vm = await AgentOs.create({ software: [pi] });
+
+const result = await vm.process.exec("echo hello");
+console.log(result.stdout); // "hello\n"
```
-`@rivet-dev/agentos` runs each VM as a Rivet Actor with built-in persistence, sleep/wake, multiplayer, preview URLs, and orchestration. For direct in-process VM control without the actor runtime, use [`@rivet-dev/agentos-core`](https://agentos-sdk.dev/docs/core) standalone: `AgentOs.create()` boots a VM and returns a handle you call directly.
+## The operating system
-See the [Quickstart guide](https://agentos-sdk.dev/docs/quickstart) for the full walkthrough. agentOS is in preview and the API is subject to change — questions and issues welcome on [Discord](https://rivet.dev/discord).
+A user-space kernel with its own filesystem, networking, and processes. No nested virtualization
+like microVMs, no elevated privileges like gVisor.
-## Benchmarks
+### Execution
-All benchmarks compare agentOS against the fastest/cheapest mainstream sandbox providers as of March 30, 2026. Methodology and reproduction steps: [Benchmarks](https://agentos-sdk.dev/docs/benchmarks).
+[Bash](https://agentos-sdk.dev/docs/bash) ·
+[Node.js](https://agentos-sdk.dev/docs/javascript) ·
+[Python](https://agentos-sdk.dev/docs/python)
-### Cold start
+Run Bash, Node.js, and Python with real processes, shells, and servers.
-| Percentile | agentOS | Fastest Sandbox (E2B) | Speedup |
-|---|---|---|---|
-| p50 | 4.8 ms | 440 ms | **92x faster** |
-| p95 | 5.6 ms | 950 ms | **170x faster** |
-| p99 | 6.1 ms | 3,150 ms | **516x faster** |
+```ts
+// Bash
+const ls = await vm.process.exec("ls -la /workspace", {
+ output: { capture: "all" },
+});
+console.log(ls.stdout);
-agentOS: measured on Intel i7-12700KF. Sandbox baseline: E2B, the fastest mainstream sandbox provider as of March 30, 2026.
+// JavaScript
+const sum = await vm.javascript.evaluate("1 + 2");
+console.log(sum.value); // 3
-### Memory per instance
+// Python
+const answer = await vm.python.evaluate("21 * 2");
+console.log(answer.value); // 42
+```
-| Workload | agentOS | Cheapest Sandbox (Daytona) | Reduction |
-|---|---|---|---|
-| Full coding agent (Pi + MCP + filesystem) | ~131 MB | ~1,024 MB | **8x smaller** |
-| Simple shell command | ~22 MB | ~1,024 MB | **47x smaller** |
+### Filesystem
+
+[Filesystem](https://agentos-sdk.dev/docs/filesystem) ·
+[Software](https://agentos-sdk.dev/docs/software) ·
+[Persistence & sleep](https://agentos-sdk.dev/docs/persistence)
-Sandbox baseline: Daytona minimum instance (1 vCPU + 1 GiB RAM), the cheapest mainstream sandbox provider as of March 30, 2026.
+Every VM gets a full POSIX-compliant filesystem. Mount S3, Google Drive, or a host directory for
+persistence.
-### Cost per execution-second (self-hosted)
+```ts
+// Mount S3 at a normal path.
+const vm = agentOS({
+ software: [pi],
+ mounts: [
+ {
+ path: "/workspace",
+ plugin: { id: "s3", config: { bucket: "my-bucket", region: "us-east-1" } },
+ },
+ ],
+});
-Full coding agent:
+// Read and write it like any other file.
+await vm.filesystem.writeFile("/workspace/config.json", JSON.stringify({ key: "value" }));
+const content = await vm.filesystem.readFile("/workspace/config.json");
+console.log(new TextDecoder().decode(content));
+```
-| Host tier | agentOS | Cheapest Sandbox (Daytona) | Difference |
-|---|---|---|---|
-| AWS ARM | $0.00000058/s | $0.000018/s | **32x cheaper** |
-| AWS x86 | $0.00000072/s | $0.000018/s | **26x cheaper** |
-| Hetzner ARM | $0.000000066/s | $0.000018/s | **281x cheaper** |
-| Hetzner x86 | $0.00000011/s | $0.000018/s | **171x cheaper** |
+### Orchestration
-Simple shell command:
+[Workflows & graphs](https://agentos-sdk.dev/docs/workflows) ·
+[Multiplayer](https://agentos-sdk.dev/docs/multiplayer) ·
+[Agent-to-agent](https://agentos-sdk.dev/docs/agent-to-agent) ·
+[Crons & loops](https://agentos-sdk.dev/docs/cron) ·
+[Approvals](https://agentos-sdk.dev/docs/approvals) ·
+[Apps](https://agentos-sdk.dev/docs/apps)
-| Host tier | agentOS | Cheapest Sandbox (Daytona) | Difference |
-|---|---|---|---|
-| AWS ARM | $0.000000073/s | $0.000018/s | **254x cheaper** |
-| AWS x86 | $0.000000090/s | $0.000018/s | **205x cheaper** |
-| Hetzner ARM | $0.000000011/s | $0.000018/s | **1738x cheaper** |
-| Hetzner x86 | $0.000000017/s | $0.000018/s | **1061x cheaper** |
-
-Sandbox baseline: Daytona at $0.0504/vCPU-h + $0.0162/GiB-h (1 vCPU + 1 GiB minimum). Assumes one agent per sandbox and 70% host utilization.
-
-## Features
-
-### Agents
-- **Built-in agents**: Run [Pi](https://agentos-sdk.dev/docs/agents/pi), [Claude Code](https://agentos-sdk.dev/docs/agents/claude) (beta), [Codex](https://agentos-sdk.dev/docs/agents/codex) (beta), and [OpenCode](https://agentos-sdk.dev/docs/agents/opencode) with a unified API, or [bring your own agent](https://agentos-sdk.dev/docs/agents/custom)
-- **[Sessions via ACP](https://agentos-sdk.dev/docs/sessions)**: Create, manage, and resume agent sessions over the [Agent Client Protocol](https://agentclientprotocol.com)
-- **Universal transcript format**: One transcript format across all agents for debugging, auditing, and comparison
-- **[Automatic persistence](https://agentos-sdk.dev/docs/persistence)**: Every conversation is saved and replayable without extra code
-- **Framework integrations**: Use agentOS as the sandbox backend for [Vercel Eve](https://agentos-sdk.dev/docs/frameworks/vercel-eve) (beta) and [Flue](https://agentos-sdk.dev/docs/frameworks/flue) (beta)
-
-### Infrastructure
-- **[Execution](https://agentos-sdk.dev/docs/processes)**: Run Bash, Node.js, Python, and registry software inside the VM with real processes, subprocesses, shells, and in-VM servers
-- **[Mount external storage as a filesystem](https://agentos-sdk.dev/docs/filesystem)**: S3-compatible storage, Google Drive, host directories, or in-memory mounts, attached at boot or dynamically at runtime
-- **[Bindings](https://agentos-sdk.dev/docs/bindings)**: Define JavaScript functions that agents call as CLI commands inside the VM
-- **[Cron](https://agentos-sdk.dev/docs/cron) and [webhooks](https://agentos-sdk.dev/docs/webhooks)**: Schedule tasks with built-in cron jobs, and trigger agents from external webhooks with your own HTTP server
-- **[Browser](https://agentos-sdk.dev/docs/browser)** (beta): Give agents a cloud browser via Browserbase
-- **[Sandbox mounting](https://agentos-sdk.dev/docs/sandbox)** (beta): Pair with full sandboxes (E2B, Daytona, etc.) for heavy workloads like browsers or native compilation
+VMs are durable and can be orchestrated to create complex multi-agent patterns.
-### Orchestration
-- **[Multiplayer](https://agentos-sdk.dev/docs/multiplayer)**: Multiple clients observe and collaborate with the same agent in real time
-- **[Agent-to-agent](https://agentos-sdk.dev/docs/agent-to-agent)**: Agents delegate work to other agents through host-defined bindings
-- **[Workflows](https://agentos-sdk.dev/docs/workflows)**: Chain agent tasks into durable workflows with retries, branching, and resumable execution
-- **[Authentication](https://agentos-sdk.dev/docs/authentication)**: Integrate with your existing auth model (API keys, OAuth, JWTs)
+```ts
+import { actor } from "rivetkit";
+import { workflow } from "rivetkit/workflow";
+
+// Each created actor is one durable workflow run. Steps checkpoint and resume.
+const bugFixer = actor({
+ run: workflow(async (ctx) => {
+ await ctx.step("clone-repo", () =>
+ vm.process.exec("git clone https://github.com/acme/api /home/agentos/repo"),
+ );
+
+ await ctx.step("fix-bug", () =>
+ vm.sessions.prompt({
+ content: [{ type: "text", text: "Fix the failing test in /home/agentos/repo" }],
+ }),
+ );
+
+ // A second VM reviews the work, isolated from the one that wrote it.
+ await ctx.step("review", () =>
+ reviewer.sessions.prompt({
+ content: [{ type: "text", text: "Review the diff in /home/agentos/repo" }],
+ }),
+ );
+ }),
+});
+```
+
+## Apps (preview)
-### Security
-- **[Granular permissions](https://agentos-sdk.dev/docs/permissions)**: Control filesystem, network, process, and environment access, with outward-facing capabilities denied by default
-- **[Programmatic network control](https://agentos-sdk.dev/docs/networking)**: Allow or deny any outbound connection with per-host rules, and proxy HTTP into VM services with preview URLs
-- **[Resource limits](https://agentos-sdk.dev/docs/resource-limits)**: Set precise CPU and memory limits per agent
-- **[VM isolation](https://agentos-sdk.dev/docs/security-model)**: Each agent runs in its own VM with no shared state
+Deploy AI-generated applications for your users. Supports use cases like HTTP servers, websites,
+SQLite, workflows, and multiplayer.
+
+Optionally works with [Rivet Actors](https://rivet.dev/docs/actors).
+
+```ts
+import { serve } from "@hono/node-server";
+import { appsRouter, deployApp } from "@rivet-dev/agentos-apps";
+import { Hono } from "hono";
+
+// An agent, an upload endpoint, or anything else can deploy the files it generated.
+await deployApp({
+ appId: "hello-world",
+ files: {
+ "package.json": JSON.stringify({ name: "hello-world-app", type: "module", main: "src/index.ts" }),
+ "src/index.ts": `
+ import { Hono } from "hono";
+ const app = new Hono();
+ app.get("/", (c) => c.html("
Hello from agentOS Apps
"));
+ export default app;
+ `,
+ },
+});
+
+// Mount every deployed application at /apps/:appId.
+const server = new Hono();
+server.route("/apps", appsRouter);
+serve({ fetch: server.fetch, port: 3000 });
+```
+
+[Documentation](https://agentos-sdk.dev/docs/apps)
## Architecture
-agentOS runs each agent in a fully virtualized VM. A trusted sidecar process owns every VM's kernel — virtual filesystem, process table, pipes, PTYs, and a virtual network stack — and brokers every guest syscall; nothing the guest does touches the host directly: no real host filesystem, no real host sockets, no real host processes. Guest JavaScript runs on native V8 with its full JIT ([JavaScript runtime](https://agentos-sdk.dev/docs/js-runtime)), and compiled tools run as WebAssembly. Many VMs share one sidecar process, so each additional VM costs a V8 isolate plus kernel state, not an OS process. With `@rivet-dev/agentos`, each VM is a Rivet Actor with durable state.
+
+
+
-See the [Architecture docs](https://agentos-sdk.dev/docs/architecture) for details.
+- **[Overview](https://agentos-sdk.dev/docs/architecture)**: the full tour of how the pieces fit
+ together.
+- **[Kernel](https://agentos-sdk.dev/docs/architecture/posix-syscalls)**: the trusted core. It owns
+ the virtual filesystem, process table, socket table, pipes, PTYs, and DNS, and every guest
+ operation goes through it.
+- **[Executor](https://agentos-sdk.dev/docs/architecture/javascript-executor)**: untrusted. Guest
+ JavaScript runs on native V8, compiled tools run as WebAssembly, and neither holds a real
+ capability of its own.
+- **[Processes](https://agentos-sdk.dev/docs/architecture/processes)**: real `fork`/`exec`, signals,
+ subprocesses, and a shell, so programs written for Linux run unmodified.
+- **[Filesystem](https://agentos-sdk.dev/docs/architecture/filesystem)**: a snapshot root plus a
+ write overlay, with mounts grafted onto guest paths.
+- **[Networking](https://agentos-sdk.dev/docs/architecture/networking)**: a virtual socket table and
+ DNS, with egress denied by default.
+- **[Permissions](https://agentos-sdk.dev/docs/permissions)**: enforced on every syscall, with
+ [approvals](https://agentos-sdk.dev/docs/approvals) to pause a turn for a human.
+- **[Sessions](https://agentos-sdk.dev/docs/architecture/agent-sessions)**: an agent is just another
+ guest process; a session keeps it alive across prompts and streams its output as events.
+- **[Actors](https://agentos-sdk.dev/docs/persistence)**: each VM is a Rivet Actor, which is where
+ durable state, sleep/wake, cron, and workflows come from.
+- **[Security model](https://agentos-sdk.dev/docs/security-model)**: the trust boundary, what is in
+ scope, and what is not.
-## Registry
+## Benchmarks
-Extend agentOS with agents, filesystems, browsers, and software from one registry. Browse the full catalog at the [agentOS Registry](https://agentos-sdk.dev/registry).
+Measured against the fastest and cheapest mainstream sandbox providers as of March 30, 2026.
-Common POSIX utilities ship out of the box. The registry adds agents (`@agentos-software/pi`, `@agentos-software/claude-code`, `@agentos-software/codex`, `@agentos-software/opencode`), command packages (`git`, `ripgrep`, `jq`, `sqlite3`, `duckdb`, `curl`, `vim`, and more), meta-packages (`common`, `build-essential`, `everything`), and integrations like the Browserbase cloud browser. Install any of them from npm and pass them via `software: [...]`.
+| | agentOS | Sandbox | |
+|---|---|---|---|
+| Cold start (p50) | 4.8 ms | 440 ms (E2B) | **92× faster** |
+| Memory per instance | ~22 MB | ~1,024 MB (Daytona) | **47× smaller** |
+| Cost per execution-second | $0.000000073/s | $0.000018/s (Daytona) | **254× cheaper** |
+
+agentOS cold start measured on Intel i7-12700KF. Memory and cost use the shell workload; a full
+coding agent (Pi + MCP + filesystem) is ~131 MB. Cost is self-hosted on AWS ARM at 70% utilization
+against Daytona's 1 vCPU + 1 GiB minimum.
+
+Methodology and reproduction: [Performance](https://agentos-sdk.dev/docs/performance)
+
+## agentOS vs Sandboxes
+
+| | agentOS | Sandbox |
+|---|---|---|
+| **Runs** | Inside your backend process | Vendor account plus API keys |
+| **Startup** | Single-digit ms | Seconds |
+| **Cost** | Whatever your process already costs | Per second of uptime |
+| **Backend integration** | Direct, via [bindings](https://agentos-sdk.dev/docs/bindings) | Network calls back to your backend |
+| **Credentials** | Stay on the host | Injected into the sandbox |
+| **Permissions** | Granular, deny by default | Container-level |
+| **Best for** | Coding, scripting, API calls, orchestration | x86-specific software, resource-intensive applications |
+
+The two compose: [sandbox mounting](https://agentos-sdk.dev/docs/sandbox) spins up a sandbox on
+demand and mounts its filesystem into the VM.
+
+[agentOS vs Sandbox](https://agentos-sdk.dev/docs/versus-sandbox) ·
+[Limitations](https://agentos-sdk.dev/docs/limitations)
+
+## Documentation
+
+**Getting Started**:
+[Quick Start](https://agentos-sdk.dev/docs/quickstart) ·
+[Crash Course](https://agentos-sdk.dev/docs/crash-course)
+
+**Agents**:
+[Pi](https://agentos-sdk.dev/docs/agents/pi) ·
+[Claude Code](https://agentos-sdk.dev/docs/agents/claude) ·
+[Codex](https://agentos-sdk.dev/docs/agents/codex) ·
+[OpenCode](https://agentos-sdk.dev/docs/agents/opencode) ·
+[Flue](https://agentos-sdk.dev/docs/frameworks/flue) ·
+[Eve](https://agentos-sdk.dev/docs/frameworks/vercel-eve)
+
+**Execution**:
+[Bash](https://agentos-sdk.dev/docs/bash) ·
+[Node.js](https://agentos-sdk.dev/docs/javascript) ·
+[Python](https://agentos-sdk.dev/docs/python)
+
+**Orchestration**:
+[Apps](https://agentos-sdk.dev/docs/apps) ·
+[Multiplayer](https://agentos-sdk.dev/docs/multiplayer) ·
+[Workflows](https://agentos-sdk.dev/docs/workflows) ·
+[Crons](https://agentos-sdk.dev/docs/cron) ·
+[Agent-to-Agent](https://agentos-sdk.dev/docs/agent-to-agent)
+
+**Operating System**:
+[Software](https://agentos-sdk.dev/docs/software) ·
+[Filesystem](https://agentos-sdk.dev/docs/filesystem) ·
+[Networking](https://agentos-sdk.dev/docs/networking) ·
+[Permissions](https://agentos-sdk.dev/docs/permissions) ·
+[Resource Limits](https://agentos-sdk.dev/docs/resource-limits)
+
+**Extension**:
+[Custom Bindings](https://agentos-sdk.dev/docs/bindings) ·
+[Browser Automation](https://agentos-sdk.dev/docs/browser) ·
+[External Sandboxes](https://agentos-sdk.dev/docs/sandboxes)
+
+**Reference**:
+[Deploy](https://agentos-sdk.dev/docs/deployment) ·
+[Custom Software](https://agentos-sdk.dev/docs/custom-software/definition)
+
+**Architecture**:
+[Overview](https://agentos-sdk.dev/docs/architecture) ·
+[Security Model](https://agentos-sdk.dev/docs/security-model) ·
+[Limitations](https://agentos-sdk.dev/docs/limitations)
+
+**More**:
+[Sessions & Transcripts](https://agentos-sdk.dev/docs/sessions) ·
+[Approvals](https://agentos-sdk.dev/docs/approvals) ·
+[Models & Credentials](https://agentos-sdk.dev/docs/models-and-credentials) ·
+[Authentication](https://agentos-sdk.dev/docs/authentication) ·
+[Persistence & Sleep](https://agentos-sdk.dev/docs/persistence) ·
+[Direct VM API](https://agentos-sdk.dev/docs/core) ·
+[Debugging](https://agentos-sdk.dev/docs/debugging)
## License
+