agentOS: A WebAssembly VM Library That Puts Agents Inside Your Backend

What agentOS Actually Solves

The core mechanism is a combination of V8 isolates and WebAssembly. Guest JavaScript runs inside V8 isolates, while compiled tools like coreutils and sed run as WebAssembly. This is not a full OS. There is no kernel, no system calls in the traditional sense, and no ability to run arbitrary native binaries. The README positions this as a feature: agents call your functions directly via bindings, which are ordinary JavaScript calls rather than network requests. Credentials stay on the host, and the guest only sees inputs and outputs. The security model relies on granular permissions that gate filesystem, network, process, and environment access. Network egress is denied by default. This is a fundamentally different trade-off from a sandbox: you get speed and integration, but you lose the hard isolation that a separate VM provides.

Bindings and Permissions: The Integration Model

The key architectural choice is that agents invoke your backend functions through bindings, not through a network service. The README describes bindings as ordinary JavaScript calls. This means an agent running in the VM can call a function you defined in your host process, passing data and receiving results, without serializing over HTTP. For example, a guest script could call a host function that queries a database, and the host retains control over the credentials. The permission system is the gatekeeper. It controls filesystem, network, process, and environment access. The README states that network egress is denied by default, which is a sensible default for untrusted code. However, the documentation does not detail the exact permission syntax or granularity in the provided material. You would need to consult the permissions documentation to understand how to grant specific capabilities. This is a critical area to verify before deployment, because an overly permissive configuration could expose host resources.

Getting Started: Commands and Configuration

The quickstart is straightforward. You install two packages: the runtime and an agent. The command is `npm install @rivet-dev/agentos @agentos-software/pi`. The Pi agent is one of several built-in agents; Claude Code, Codex, and OpenCode install the same way. The server-side setup imports `agentOS` and `setup` from the runtime, creates a VM with the Pi agent, and starts a registry. The client side uses `createClient` from the client module, pointing at an endpoint like `http://localhost:6420`. You then create or get an agent handle, open a session with environment variables such as `ANTHROPIC_API_KEY`, and send a prompt. The example shows reading a file the agent created with `readFile`. The README also shows running Node.js scripts and shell commands inside the VM using `writeFile` and `exec`. The server runs with `npx tsx server.ts`, and the client with `npx tsx client.ts`. The API is typed, with TypeScript inference for event payloads. The setup is minimal: no Docker, no cloud account, just an npm package.

Benchmarks: What the Numbers Claim

The README includes benchmark tables comparing agentOS to sandbox providers. Cold start times are reported at 4.8 ms p50, 5.6 ms p95, and 6.1 ms p99, versus E2B's 440 ms, 950 ms, and 3,150 ms. Memory per instance is about 131 MB for a full coding agent and 22 MB for a simple shell command, compared to Daytona's 1 GB minimum. Cost per execution-second is calculated for self-hosted scenarios on AWS and Hetzner, showing large multiples of savings. These numbers are impressive, but they come from the project's own benchmarks as of March 30, 2026. The README links to a methodology page, but that page is not included in the material. You cannot verify these figures without reproducing the tests. The comparison is also against sandbox providers that boot full Linux environments. If your workload requires native binaries, agentOS is not a substitute, and these benchmarks would not apply. Treat the numbers as directional, not as a guarantee for your infrastructure.

Limitations: When agentOS Is the Wrong Tool

The most obvious limitation is the lack of a full OS. The README explicitly states that sandboxes give you a full OS for browsers, native binaries, and dev servers. agentOS cannot run those. Guest code is limited to JavaScript and WebAssembly. If your agent needs to launch a headless browser, execute a compiled native tool, or run a dev server that binds to a port, agentOS will not work. The README acknowledges this by offering sandbox mounting: you can spin up a full sandbox on demand and mount its file system when the workload needs it. That hybrid approach adds complexity and reintroduces the latency you avoided. Another limitation is that the project is in preview. The API is subject to change, which means code written today may break with future releases. The README invites questions and issues on Discord, which suggests the project is still iterating. For production use, you should pin versions and be prepared for breaking changes.

Alternatives: Sandboxes and Embedded Runtimes

The direct alternative is a traditional sandbox provider like E2B or Daytona. These run full Linux environments in microVMs or containers. The approach is fundamentally different: you get complete OS compatibility, including native binaries and browsers, but you pay for it in cold start latency and memory overhead. The README's benchmark tables show that difference clearly. Another alternative is embedding a JavaScript runtime directly, such as using Node.js `worker_threads` or a V8 isolate library without the agentOS layer. That would give you script execution but not the agent-specific features like built-in agents, file system abstraction, or permission gating. The README also mentions `@rivet-dev/agentos-core`, which provides a lower-level API for embedding VM control in an existing Node.js application without the actor runtime. That is a different trade-off: more control, but you lose the built-in persistence, sleep/wake, and orchestration features that the full `@rivet-dev/agentos` package provides. The choice depends on whether you want an agent platform or just a runtime.

Maintenance and Licensing

The project is licensed under Apache-2.0, which is permissive for commercial use. The repository is active, with the last push on September 9, 2026, and recent releases including v0.2.19 and a release candidate for v0.2.20. The maintenance cadence appears regular, but the preview status means the API is not stable. The README does not document a migration path or a changelog in the provided material. You should expect to track releases and update your code accordingly. The dependency on `@rivet-dev/agentos` suggests that the npm package is the primary distribution. The runtime is written in Rust, but you interact with it through JavaScript/TypeScript. The maintenance cost is likely moderate: the project is open source, but you depend on the maintainers for security fixes and feature updates. Given the security-sensitive nature of running untrusted code, you should monitor the repository for vulnerability disclosures. The Apache-2.0 license gives you the freedom to fork and self-host, which is a fallback if the project stalls.

Editorial conclusion

Adopt agentOS if your agents need millisecond cold starts, direct in-process bindings to your backend functions, and you can accept guest code running as JavaScript or WebAssembly rather than a full Linux environment. Do not use it if you must execute native binaries, run a browser, or need the isolation guarantees of a separate kernel. Before adopting, verify the preview API stability against your expected workload, confirm the permission model covers your threat model, and reproduce the benchmark methodology on your own host hardware. The 92x cold-start claim is compelling, but the real test is whether your agent workloads fit the constrained runtime without sandbox mounting.

Official sources

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