Skip to main content

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.

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

LIBRARYYour backendagentOS VMAgentOs.create()orHOSTEDYour backendYour frontendHTTPagentOS VMclient.agentOS.getOrCreate(["my-vm"])
  • Library: @rivet-dev/agentos-core runs 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 agentOS Rivet Actor gives each VM a durable ID, versioned configuration, replayable output, and expiring previews. Control it from @rivet-dev/agentos or plain HTTP.
LibraryHosted
RunsInside your processDurable instance on Rivet Cloud or self-hosted
LifecycleRuns until dispose() or process exitSleeps when idle unless a process is running
ClientsYour backendYour backend, or browsers with a scoped JWT
Preview URLsNoneExpiring preview URLs
Host accessHost functions, host directory mounts, local softwareSerializable configuration only

What’s in a VM

GroupWhat it does
process and terminalRun commands, manage child processes, and open interactive PTY sessions. See Processes & Shells.
filesystemRead, write, and list files, and attach mounts. See Filesystem.
javascript, typescript, pythonRun code, install npm and pip packages, and type-check. See Node.js and Python.
networkReach servers running in the VM and create preview URLs. See Networking & Previews.
softwareInstall .aospkg command packages. See Software.
cronRun 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.

Edit this page Last updated November 18, 2026