agentOS – Tiny, fast Linux‑compatible sandboxes for AI agents

What it is – agentOS is a JavaScript/TypeScript library (and hosted service) that lets you run isolated, lightweight Linux‑like environments inside a single process. Each agent gets its own filesystem, processes, shell, networking and can execute JavaScript, TypeScript, Python and compiled WebAssembly tools. Isolation is provided by V8 isolates and WebAssembly, not by full VMs, giving extremely fast cold‑starts and tiny memory footprints.

Key points

Feature	Why it matters
WebAssembly + V8 isolates	Runs guest code (shell, coreutils, Python, etc.) in a sandbox that shares the same runtime, avoiding heavyweight micro‑VMs.
Library mode	Install `@rivet-dev/agentos-core` from npm and spin up a VM inside your own backend process.
Hosted mode	Use Rivet Cloud (or self‑host) to run durable VMs that can be addressed over HTTP, with optional preview URLs for exposing services.
Cold‑start speed	~5 ms (p50) vs. ~440 ms for a typical container sandbox – 92× faster.
Memory efficiency	~22 MiB per VM vs. >1 GiB for a full Linux container – 47× less.
Fine‑grained permissions	Network, filesystem and resource limits are declarative; secrets never leave the host.
Persisted storage	Mount SQLite, host directories, or S3 buckets; choose in‑memory or durable roots.
Rich API	Process, filesystem, networking, language runtimes (JS/TS, Python), cron, software packages, and interactive PTY are all exposed via a clean TypeScript API or plain HTTP calls.

Typical use cases

AI‑agent back‑ends – give each LLM‑driven agent its own sandboxed OS so it can run shell commands, fetch data, or execute custom Python/JS code safely.
Serverless‑style workloads – spin up a VM on demand for a short task (e.g., data transformation) and dispose of it instantly.
Testing & CI – run isolated build steps or security‑sensitive scripts without spawning full containers.
Edge or low‑cost compute – run many agents on a single VM/instance, saving memory and cloud spend.

Quick start (library mode)

npm install @rivet-dev/agentos-core

import { AgentOs } from "@rivet-dev/agentos-core";

const vm = await AgentOs.create();
await vm.process.exec("echo hello && ls /home/agentos", {output:{capture:"all"}});
await vm.filesystem.writeFile("/home/agentos/hello.txt", "Hello, world!");
await vm.javascript.execute("console.log(1+2)");
const answer = await vm.python.evaluate<number>("21*2");
await vm.dispose();

Configuration (persistent FS, mounts, env vars, network rules, resource caps) is passed to AgentOs.create() – see the README for the full schema.

Quick start (hosted mode)

npm install @rivet-dev/agentos

import { createAgentOsClient } from "@rivet-dev/agentos";
const client = createAgentOsClient({endpoint:"https://api.rivet.dev"});
const vm = client.agentOS.getOrCreate(["my-vm"]);
const res = await vm.v1.process.run({command:"sh", args:["-c","echo hi"] , options:{captureStdio:true}});
console.log(res.stdout);

All actions are also available via plain HTTP (POST /gateway/{vm_id}/action/v1.<group>.<action>), so you can call from any language.

Architecture at a glance

Sidecar kernel (Rust) – a separate process that owns the virtual kernel, filesystem, process table, sockets and permission system.
Guest code – runs in V8 isolates (JS/TS) or as WebAssembly modules (shell, coreutils, Python).
Library – the @rivet-dev/agentos-core package spawns the sidecar, talks to it over stdio/Unix socket, and presents a TypeScript API.
Hosted service – Rivet Cloud runs the same sidecar and exposes a REST/JSON API; you can also self‑host the sidecar.
Isolation model – every system call from guest code is a sandboxed syscall; host resources are only reachable through explicit mounts, host functions, or network allow‑lists.

License

The project is released under the license found in the repository’s LICENSE file (the README points to it).

Where to learn more – Documentation, benchmarks, and detailed API reference are hosted at https://rivet.dev/agentos and the repo’s docs/ folder.

rivet-dev/agentos