DEV Community

Cover image for Open Source Project #137: agentOS — An Operating System as a Library for AI Agents
WonderLab
WonderLab

Posted on

Open Source Project #137: agentOS — An Operating System as a Library for AI Agents

#rust #ai #opensource #agents

Introduction

"Give agents an operating system as a library. 92x faster cold starts, 47x less memory, 254x cheaper than sandboxes."

This is article #137 in the "One Open Source Project a Day" series. Today's project is agentOS — an AI agent runtime distributed as an npm package, letting you run AI coding agents inside your own Node.js backend without spinning up any external sandbox, microVM, or container.

Giving AI agents an execution environment is becoming an infrastructure problem: E2B, Daytona, Modal and similar sandbox services typically have cold starts in the hundreds of milliseconds to seconds range, at least 1 GB of memory per instance, and per-minute billing. agentOS's entry point: if an agent's VM is built on V8 isolates + WebAssembly rather than a full Linux environment, that VM can be embedded inside your process — cold starts in milliseconds, tens of megabytes of memory, and cost two orders of magnitude lower.

4,265 Stars. Apache 2.0. Maintained by Rivet Dev.

What You'll Learn

  • agentOS's VM isolation model: V8 isolates + WebAssembly, and the core difference from full sandboxes
  • Performance benchmarks: cold start, memory, and cost comparisons against E2B and Daytona
  • Core features: bindings, filesystem mounts, permissions, sessions via ACP
  • Built-in agent support: Pi, Claude Code, Codex, OpenCode
  • Which scenarios call for agentOS, and when you actually need a full sandbox

Prerequisites

  • Basic Node.js/TypeScript familiarity
  • General understanding of AI agent tool-calling
  • Knowing what V8 or WebAssembly is helps, but isn't required

Project Background

Overview

agentOS is an npm package (@rivet-dev/agentos). After installing, you create VM instances directly in TypeScript/Node.js code, run AI agents inside those VMs, and agents call your JavaScript functions via bindings — no network hop required.

Architecture: each VM is owned by a trusted sidecar process that manages a virtual kernel — virtual filesystem, process table, pipes, PTYs, and a virtual network stack. Every guest syscall is proxied through this sidecar; nothing the guest does touches the real host. Guest JavaScript runs on native V8 (full JIT), and compiled tools run as WebAssembly. Multiple VMs share one sidecar process, so each additional VM costs one V8 isolate plus kernel state — not a new OS process.

Author / Team

  • Company: Rivet Dev
  • Primary language: Rust (core runtime) + TypeScript (SDK)
  • License: Apache-2.0
  • Website: agentos-sdk.dev

Project Stats

  • ⭐ GitHub Stars: 4,265+
  • 🍴 Forks: 214+
  • 📄 License: Apache-2.0
  • 📅 Created: 2024-02-07

Quick Start 

npm install @rivet-dev/agentos @agentos-software/pi
Enter fullscreen mode Exit fullscreen mode

Create the server (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();
Enter fullscreen mode Exit fullscreen mode

Create the client (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");

// Subscribe to streaming events
const conn = handle.connect();
conn.on("sessionEvent", (event) => console.log(event));

// Open a session and send a prompt
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" }],
});

// Read the file the agent created
const content = await handle.readFile("/workspace/hello.js");
console.log(new TextDecoder().decode(content));
Enter fullscreen mode Exit fullscreen mode

Run both:

# Terminal 1: start the server
npx tsx server.ts

# Terminal 2: run the client
npx tsx client.ts
Enter fullscreen mode Exit fullscreen mode

Execute Node.js and shell directly inside the VM:

await handle.writeFile("/hello.mjs", 'import fs from "fs"; fs.writeFileSync("/out.txt", "hi")');
await handle.exec("node /hello.mjs");

const result = await handle.exec("cat /out.txt");
console.log(result.stdout); // "hi"
Enter fullscreen mode Exit fullscreen mode

Performance Benchmarks

The benchmark data was measured on March 30, 2026:

Cold Start

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

agentOS measured on Intel i7-12700KF. E2B is the fastest mainstream sandbox as of March 30, 2026.

Memory Per Instance

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

Cost Per Execution-Second (Self-Hosted, Full Coding Agent)

Host agentOS Daytona Factor
AWS ARM $0.00000058/s $0.000018/s 32x cheaper
Hetzner ARM $0.000000066/s $0.000018/s 281x cheaper

Daytona baseline: $0.0504/vCPU-h + $0.0162/GiB-h (1 vCPU + 1 GiB minimum).

Why the gap is this large: Sandbox services have a minimum instance of 1 vCPU + 1 GiB — even running a single ls command requires paying for the whole instance. agentOS's VM floor is one V8 isolate plus kernel state. A simple shell command uses 22 MB. That's a structural gap from the isolation-layer choice, not an optimization.

Core Features

Bindings: Agents Call Your Functions Directly

This is the most fundamental architectural difference from traditional sandboxes.

In a traditional sandbox, an agent accessing your data or calling your logic has to go through a network API: sandbox → HTTP → your backend. Credentials travel into the sandbox, latency increases, and there's an extra attack surface.

agentOS bindings:

const vm = agentOS({
  software: [pi],
  bindings: {
    // This function is exposed to agents inside the VM as a CLI command
    get_user_data: async (userId: string) => {
      return await db.users.findById(userId); // Direct database access on the host
    },
  },
});
Enter fullscreen mode Exit fullscreen mode

When the agent inside the VM runs get_user_data 123, it executes like any shell command — but it's actually calling the TypeScript function you defined on the host. Credentials and database connections never enter the VM.

Filesystem Mounts

Mount at boot or dynamically at runtime:

const vm = agentOS({
  software: [pi],
  mounts: [
    { type: "s3", bucket: "my-bucket", mountpoint: "/data" },
    { type: "host", path: "./local-dir", mountpoint: "/workspace" },
    { type: "memory", mountpoint: "/tmp" },
    { type: "gdrive", mountpoint: "/drive" },  // Google Drive (after OAuth)
  ],
});
Enter fullscreen mode Exit fullscreen mode

Granular Permissions

Network egress is denied by default; open it as needed:

const vm = agentOS({
  software: [pi],
  permissions: {
    network: {
      outbound: [
        { host: "api.github.com", allow: true },
        { host: "*", allow: false }, // deny everything else
      ],
    },
    filesystem: {
      read: ["/workspace", "/data"],
      write: ["/workspace"],
    },
  },
});
Enter fullscreen mode Exit fullscreen mode

Sessions via ACP

agentOS manages agent sessions through ACP (Agent Client Protocol):

  • Sessions auto-persist with no extra code
  • Interrupted sessions can be resumed
  • Unified transcript format across all agents for debugging and comparison

Cron and Webhooks 

// Schedule agent tasks
registry.cron("0 9 * * *", async () => {
  const handle = client.vm.getOrCreate("daily-report");
  await handle.openSession({ agent: "pi" });
  await handle.prompt({ content: [{ type: "text", text: "Generate today's report" }] });
});

// External webhook triggers
registry.webhook("/github-events", async (req) => {
  // handle GitHub webhook, delegate to agent
});
Enter fullscreen mode Exit fullscreen mode

Multiplayer

Multiple clients can observe and collaborate with the same agent in real time:

const conn1 = handleA.connect(); // read-only observer
const conn2 = handleB.connect(); // can also send prompts
Enter fullscreen mode Exit fullscreen mode

Agent-to-Agent Delegation 

const vm = agentOS({
  software: [pi, claudeCode],
  bindings: {
    // Pi can call this binding to spin up a Claude Code agent for a subtask
    run_code_review: async (prUrl: string) => {
      const reviewHandle = client.vm.getOrCreate(`review-${prUrl}`);
      await reviewHandle.openSession({ agent: "claude-code" });
      await reviewHandle.prompt({
        content: [{ type: "text", text: `Review PR: ${prUrl}` }],
      });
      return await reviewHandle.getResult();
    },
  },
});
Enter fullscreen mode Exit fullscreen mode

Built-In Agent Registry

Agents and tools are distributed as npm packages:

Agent / Package npm package Notes
Pi @agentos-software/pi Primary general-purpose coding agent
Claude Code @agentos-software/claude-code Anthropic Claude Code (beta)
Codex @agentos-software/codex OpenAI Codex (beta)
OpenCode @agentos-software/opencode OpenCode (beta)

CLI tools (also npm packages): git, ripgrep, jq, sqlite3, duckdb, curl, vim, plus meta-packages common, build-essential, everything.

Common POSIX utilities (coreutils, sed, grep, gawk, findutils, diffutils, tar, gzip) ship out of the box.

agentOS vs Full Sandboxes: When to Use Which

agentOS's own documentation is explicit: the two are complementary, not competing.

Dimension agentOS Full sandbox (E2B/Daytona)
Cold start 4.8ms (p50) 440ms+ (p50)
Minimum memory ~22 MB ~1,024 MB
Host process integration ✅ (in-process, direct bindings) ✗ (network API required)
Native binary compilation Partial (WebAssembly format) ✅ (full Linux)
Browser automation Via Browserbase (beta) ✅
Dev server (HTTP server inside) ✗ ✅
Cost Very low Per-minute billing

Choose agentOS when:

  • Agents need to call your backend's database or functions (direct bindings, no network hop)
  • High concurrency or high-frequency agent tasks (lower memory = more instances per host)
  • Cold start latency matters (user-facing real-time workflows)
  • Self-hosted, don't want sandbox vendor billing

Choose a full sandbox when:

  • Need to run native compilation (C/C++/Rust toolchains)
  • Need to start a full dev server (Node/Python HTTP server inside)
  • Need a real browser (not just a headless API)
  • Workload is already heavy and sandbox cost is acceptable

Using both together (sandbox mounting):

const vm = agentOS({
  software: [pi],
  // Spin up a full sandbox on demand, mount its filesystem
  sandbox: { provider: "e2b", mountpoint: "/sandbox" },
});
Enter fullscreen mode Exit fullscreen mode

Use the lightweight agentOS VM by default; mount a full sandbox when the workload genuinely needs real Linux.

Resources

Official Links

Summary

agentOS answers a specific engineering question: "I want to run AI agents in my product, but I don't want to accept sandbox cold start latency, high memory overhead, and per-minute billing." The answer: implement a good-enough VM using V8 isolates + WebAssembly, package it as an npm library, and let developers npm install it directly into their backend.

Three design decisions worth remembering:

Bindings are the core insight: Not "agents call your HTTP API" but "agents call TypeScript functions you defined, exposed as CLI commands inside the VM." Credentials never enter the VM, latency is near-zero, and the agent's capability surface is entirely under your control.

The performance gap is structural, not optimized: Full sandbox minimum instances are 1 vCPU + 1 GiB — you pay that floor no matter what you're running. A V8 isolate's floor is tens of megabytes. This isn't a gap created by clever optimization; it's a consequence of choosing a different isolation layer.

Complementary to full sandboxes, not a replacement: The sandbox mounting feature signals that the team understands agentOS's boundary. When a workload genuinely needs a real Linux environment, mount the sandbox's filesystem into the VM rather than trying to emulate a full OS in WebAssembly.

If you're building a product that needs AI agent capabilities but are unsatisfied with sandbox service costs and latency, npm install @rivet-dev/agentos is worth evaluating seriously.

Explore PrimeSkills — a curated marketplace of AI agents and skills, each validated against real enterprise workflows. No hype, just what actually works.

Visit my personal site for more insights and interesting products.

Top comments (0)