Introduction
Run tiny, fast, Linux-compatible VMs powered by WebAssembly and V8 isolates.
agentOS gives each agent a lightweight VM with files, processes, a shell, and networking. It is powered by WebAssembly and V8 isolates, the same technology behind Chrome and Cloudflare Workers, and exposes Linux-style POSIX files, processes, and sockets.
Quickstart (Hosted)
Create durable VMs by ID and control them over RivetKit or HTTP.
Quickstart (Library)
Run a VM inside a trusted Node.js backend.
Architecture
See how the sidecar, kernel, and guest code fit together.
Security Model
Understand the trust boundary and what a VM can reach by default.
Why agentOS
- Library, not extra infrastructure. Install agentOS from npm and run it inside the backend process you already operate.
- WebAssembly and V8, not a microVM. V8 isolates run JavaScript, and WebAssembly runs compiled tools such as the shell, coreutils, and Python in the same compact runtime.
- Direct function calls, not extra APIs. Connect agents to your application with host functions instead of another network service.
- Scoped access, not exposed credentials. Bind trusted host functions without giving the agent your raw secrets.
- One process, not a VM per agent. Many isolated VMs share one runtime instead of each duplicating a full microVM stack.
- Runs anywhere. Deploy on standard Linux infrastructure without a hypervisor or nested virtualization.
A cold start takes about 5 ms and a shell workload uses about 22 MB of memory. See Performance for the benchmarks and how to run them yourself.
Library or hosted
- Library:
@rivet-dev/agentos-coreruns VMs inside your Node.js backend. Your application owns the VM’s lifecycle, persistence, and access to host resources such as host functions and mounts. - Hosted: the prebuilt
agentOSRivet Actor gives each VM a durable ID, versioned configuration, replayable output, and expiring previews. Control it from@rivet-dev/agentosor plain HTTP.
| Library | Hosted | |
|---|---|---|
| Runs | Inside your process | Durable instance on Rivet Cloud or self-hosted |
| Lifecycle | Runs until dispose() or process exit | Sleeps when idle unless a process is running |
| Clients | Your backend | Your backend, or browsers with a scoped JWT |
| Preview URLs | None | Expiring preview URLs |
| Host access | Host functions, host directory mounts, local software | Serializable configuration only |
What’s in a VM
| Group | What it does |
|---|---|
process and terminal | Run commands, manage child processes, and open interactive PTY sessions. See Processes & Shells. |
filesystem | Read, write, and list files, and attach mounts. See Filesystem. |
javascript, typescript, python | Run code, install npm and pip packages, and type-check. See Node.js and Python. |
network | Reach servers running in the VM and create preview URLs. See Networking & Previews. |
software | Install .aospkg command packages. See Software. |
cron | Run scheduled commands. See Crons & Schedules. |
Embedded API
import { AgentOs } from "@rivet-dev/agentos-core";
// Boots a VM inside this process. It runs until dispose() or process exit.
const vm = await AgentOs.create();
try {
// Bash
const result = await vm.process.exec("echo hello && ls /home/agentos", {
output: { capture: "all" },
});
console.log(result.stdout);
// Filesystem
await vm.filesystem.writeFile("/home/agentos/hello.txt", "Hello, world!");
const file = await vm.filesystem.readFile("/home/agentos/hello.txt");
console.log(new TextDecoder().decode(file));
// JavaScript
await vm.javascript.execute("console.log(1 + 2)");
// Python
const answer = await vm.python.evaluate<number>("21 * 2");
console.log(answer.outcome === "succeeded" ? answer.value : answer.error);
} finally {
await vm.dispose();
}
Read more in the embedded API quickstart.