rivet-dev/agentos: an agent OS as an npm package for your own backend

The problem agentOS solves, and who it is actually for

If you want an LLM agent to write files, run shell commands and call your own functions, the usual answer is to give it a machine. That machine is a container or a microVM somewhere else, and your backend talks to it over a network. The agent's credentials live in that remote environment, latency is a network round trip, and you pay for a full Linux image whether the agent needs it or not. The README frames agentOS as the alternative: "Runs inside your process", with warm VM creation "in single-digit milliseconds" and each VM costing "tens of megabytes". The intended reader is a backend team that already has Node.js in production and wants agent execution to be a library call rather than a service dependency. The project ships built-in support for Pi, Claude Code (beta), Codex (beta) and OpenCode behind what the README calls a unified API, so the choice of agent is a configuration detail rather than a rewrite.

WebAssembly, V8 isolates and bindings: how the runtime is put together

There are two execution paths inside one runtime. Guest JavaScript runs in V8 isolates, and compiled tools run as WebAssembly. The repository layout matches that split: the Cargo workspace lists crates/v8-runtime, crates/kernel, crates/execution, crates/vfs, crates/vfs-store and crates/vm-config as default members, alongside crates/native-sidecar and crates/native-sidecar-core. Filesystem state lives in the vfs crates rather than in a host directory tree, which is why the client API can expose readFile and writeFile as first-class calls. The second mechanism is bindings. An agent calls your functions directly, described in the README as "ordinary JavaScript calls, not another network service", and the security consequence it draws is that "credentials stay on the host; agents see only inputs and outputs". Permissions gate filesystem, network, process and environment access, and the README states that outward-facing capabilities such as network egress are denied by default. That default matters more than the benchmark table: an agent that cannot reach the network without an explicit grant is a different risk profile from one that can. The Cargo.toml comment notes that browser support is "intentionally retained in-tree but disabled", with two browser crates excluded from default workspace commands, so the browser story is dormant rather than absent.

Installing agentOS and running a first agent session

The package is published on npm, and the README's quickstart is two packages: the runtime and one agent. Common POSIX utilities (coreutils, sed, grep, gawk, findutils, diffutils, tar, gzip) ship out of the box, and the README says Claude Code, Codex and OpenCode install the same way as Pi.

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

The server side registers a VM with a software list. This is the file the README names server.ts, and registry.start() is what brings it up.

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

The client can be any public frontend or another backend. Note the endpoint port and the two-step pattern: openSession picks the agent and passes the API key as an environment variable, then prompt sends the text.

// 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", (event) => {
  console.log(event);
});

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 in separate terminals. The README uses tsx for both, and the server must be listening before the client connects to port 6420.

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

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

What you should see is the assistant's streamed session events in the first terminal's log, then the decoded contents of /workspace/hello.js printed by the client. The README also shows Node.js and shell execution inside the same VM, which is the quickest way to confirm the runtime is working before you wire up an agent.

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"

If you want VM control inside an existing Node.js application without the actor runtime, the README points at @rivet-dev/agentos-core and AgentOs.create(), which boots a VM and returns a handle you call directly.

The preview API and the toolchain are the two things most likely to bite

The README states plainly that agentOS "is in preview and the API is subject to change". Treat that as a real constraint on adoption timing, not boilerplate. The release history supports it: v0.2.19 shipped on 2026-09-02, and v0.2.20-rc.1 landed on 2026-09-09, so the tree is moving at a release-candidate cadence. The second sharp edge is the WASM command set. The justfile exposes a toolchain-preflight target whose own comment says it catches "socket/netdb programs missing from PATCHED_PROGRAMS before CI does", and it builds against the vanilla wasi-sdk sysroot to reproduce a fresh CI runner. In other words, some C programs need a patched sysroot and are not in the default set. If your agent's workflow depends on a specific utility, confirm it is in the shipped command list before you design around it. The third limitation is scope. agentOS is a lightweight VM, and the README is explicit that sandboxes "give you a full OS for browsers, native binaries, and dev servers". If that is your workload, agentOS alone is the wrong tool, and the documented answer is sandbox mounting, which spins up a full sandbox on demand and mounts its filesystem when the workload needs it.

agentOS compared with a sandbox provider such as E2B or Daytona

The difference is where the boundary sits. A sandbox provider gives you a remote Linux environment and an API to drive it; isolation comes from the VM or container boundary, and the cost is a boot, a network hop and a full guest image. agentOS puts the boundary inside your process: V8 isolates for JavaScript, WebAssembly for compiled tools, a virtual filesystem in the vfs crates, and bindings for calls back into your code. The README's comparison tables use E2B as the fastest mainstream sandbox for cold start and Daytona as the cheapest for memory and cost, with figures such as 4.8 ms p50 against 440 ms, roughly 131 MB against about 1,024 MB for a full coding agent, and self-hosted cost per execution-second on AWS and Hetzner tiers. Those numbers come from the project's own benchmark pages, dated March 30, 2026, and the README points to methodology and reproduction steps rather than asserting them without a source. The honest reading is that the numbers describe the architecture, not your workload: a sandbox still wins whenever you need a real kernel, a browser, or a native binary that was never compiled to WASM. The two are not mutually exclusive, which is why sandbox mounting exists.

Maintenance, licensing and what an upgrade actually costs

The repository is not archived and the last push was on 2026-09-09, with v0.2.20-rc.1 published the same day. That is recent enough to call the project under current development, and the release cadence suggests the maintainers are iterating quickly. The licence is Apache-2.0 at the repository root, and the Cargo workspace declares license = "Apache-2.0" for its crates, so the same terms cover the Rust side. Apache-2.0 is permissive and includes a patent grant, which is the usual reason teams pick it over MIT for infrastructure code; it also carries notice and attribution obligations when you redistribute. That is a description of the licence text, not legal advice, and if you ship agentOS inside a product you should have counsel read the NOTICE requirements rather than take this paragraph as clearance. The practical upgrade cost is the preview API. Pinning to a released version such as v0.2.19 and reading the changelog before moving is cheaper than tracking main. The Rust workspace also matters if you build from source: the Cargo.toml comment states that browser crates are held out of ordinary workspace commands while a unified native sidecar reactor lands, so a from-source build is not the same surface as the npm package.

Editorial conclusion

Adopt agentOS if you are a Node.js team that wants Pi, Claude Code, Codex or OpenCode running inside your own process, with credentials kept on the host and permissions gating filesystem, network, process and environment access. Do not adopt it if your workload needs a full Linux userland, a real browser, native binaries or a dev server; the project's own comparison says sandboxes cover those, and sandbox mounting is the escape hatch it offers. Before you build on it, verify three things: that the preview API surface you depend on has not moved since v0.2.19, that the WASM command set you need is in the default toolchain rather than the PATCHED_PROGRAMS list, and that the readFile path you use matches the workspace layout your agent actually writes to.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. rivet-dev/agentos on GitHub