agentos

What it is

agentOS is a library that gives agents an operating system as a library. It runs inside your existing backend without sandboxes or external VMs, powered by WebAssembly and V8 isolates.

How it works

Agents run in in-process VMs (Rivet Actors) with a trusted sidecar kernel managing virtual filesystem, processes, and networking. JavaScript guest code runs on native V8 with JIT, while compiled tools run as WebAssembly. It supports bindings to expose CLI-style functions inside the VM, and it includes a registry for agents and packages.

Getting started

npm install @rivet-dev/agentos @agentos-software/pi

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();

Create the client — any public frontend or another backend:

// 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 durable 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));

Run both:

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

# Terminal 2: run the client
npx tsx client.ts

agentOS can run Node.js and shell scripts inside the VM:

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

// Bash
const result = await handle.exec("cat /out.txt");
console.log(result.stdout); // "hi"

@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 standalone: AgentOs.create() boots a VM and returns a handle you call directly.

See the Quickstart guide for the full walkthrough. agentOS is in preview and the API is subject to change.

Traction

All benchmarks and claims are in the README; see documented sections for performance benchmarks and comparisons.

License

Apache-2.0