Overview

agentOS runs AI agents and untrusted code safely inside fully virtualized Linux VMs. Nothing the guest does touches your host directly: there is no real host filesystem, no real host network socket, and no real host process. Every guest operation is serviced by a kernel that agentOS owns.

This page is a high-level tour. It walks through the overall shape, the parts that make up a VM, how agent sessions work, and the orchestration layer underneath. Each section links out to a detailed page when you want to go deeper.

The big picture

A running agentOS system has three roles: your app (the client), your server (which runs the sidecar that hosts the VMs), and the VM where guest code actually runs. Your app never runs guest code itself, it asks the server to.

The client speaks to the agentOS server over the wire. The server runs the sidecar, the trusted core that hosts every VM: it owns each VM’s kernel and brokers every guest syscall the agent makes (filesystem, processes, network, permissions) before carrying it out. Each VM is a fully isolated world, so agents are isolated from one another and from your host.

Your app (the client)

• Trusted caller. Your app drives agentOS. It creates VMs, opens sessions, sends prompts, and reads results back.
• Never runs guest code. The agent and any code it generates run in the VM, not in your app’s process.
• Available everywhere. There is a TypeScript client and a Rust client, and the same VM is reachable from a Node script, a browser/React app, or a separate backend.
• Owns the configuration. Everything you send (VM setup, permission policy, resource limits, mounts) is trusted input. See the Security Model for why your configuration is not an attack surface.

Your server (the sidecar)

• The trusted core. The sidecar is the part of the system that owns everything: the kernel, the virtual filesystem, the process and socket tables, pipes, PTYs, the permission policy, and DNS.
• The enforcement point. Every request the VM makes is serviced here. The sidecar decides what is allowed before carrying it out.
• Hosts every VM. A single sidecar manages many VMs side by side, each with its own kernel, filesystem, and process table, so every agent runs in its own isolated world. A crash or runaway in one VM never affects another.

The VM

• A fully virtualized Linux environment. Each VM has its own filesystem, process table, and network policy. Two VMs share nothing.
• The unit of isolation. Put one tenant or one task per VM to control the blast radius. A crash or runaway in one VM never affects another.
• Where guest code lives. The agent, the shell, npm packages, and any generated code all run inside the VM, behind the kernel’s boundary.

Anatomy of a Linux VM

Inside every VM there are two halves. The kernel is the trusted core that owns all the resources and rules. The executor is where untrusted guest code actually runs. Guest code can only ask the kernel for things, it never holds a real capability of its own.

Kernel: the trusted core

The kernel is the single chokepoint. Each kind of guest operation is serviced by a kernel-owned subsystem, never by a real host capability.

• Virtual filesystem. A per-VM filesystem. Guest reads and writes hit the VFS, not your host disk.
• Process table. A virtual process table. Child processes are kernel-managed and visible only inside their VM. No real host process is ever spawned for guest work.
• Socket table and DNS. A virtual network stack. Outbound traffic is gated by the network allowlist.
• Pipes and PTYs. Kernel-owned IPC and terminal devices, so shells and pipelines behave like real Linux.
• Policy and limits. The kernel checks the applied permission policy, network allowlist, and resource limits on every request.

Executor: where guest code runs

The executor is the untrusted half of the VM. It runs the guest code and reaches the kernel for everything else.

• JavaScript Acceleration. Guest JavaScript runs on a native V8 runtime (the same engine in Chrome and Node.js, with the full JIT compiler) inside an isolate. This is what we call JavaScript Acceleration: the guest’s JavaScript executes at native speed, not through an interpreter or a translation shim. It is genuinely fast, and it presents normal Node.js semantics. See JavaScript Runtime.
• WASM alongside it. The shell (sh) and the coreutils behind process execution ship as WebAssembly modules, and you can run your own WASM too. See POSIX Syscalls and the Compiler Toolchain.
• Native binaries. Tools mounted into the VM run inside the same boundary as everything else.
• No host fallthrough. The executor holds no capability of its own. For every file read, process spawn, or socket open, it issues a syscall and blocks for the kernel’s reply.

Processes & shell

• A real process model. exec() and run() start fresh guest processes; you can also spawn long-running ones and open interactive shells.
• Kernel-managed. Every process lives in the virtual process table, with stdio bridged through kernel-owned pipes and PTYs.
• Fresh each run. Each exec() / run() starts a brand new guest process, so in-memory state never leaks from one run into the next.
• See Processes for the internals.

Virtual filesystem

• Layered engines. The VFS is a tree of engines: a root layer bootstrapped from a snapshot, an overlay for writes, and mount points that graft other backends onto guest paths.
• Host-backed mounts. A guest path can be backed by a host directory, S3, or a cloud store. The kernel confines all guest I/O to the mount root, even against symlink and .. tricks.
• Persisted. The /home/user filesystem survives sleep/wake.
• See Filesystem for the internals.

Networking

• One authoritative transport. Guest fetch(), node:http, node:net, and WASM sockets all target the same kernel socket table. No part of guest networking opens a real host socket on its own.
• Egress policy. Outbound traffic is gated by the network allowlist; loopback traffic stays confined to the VM.
• Preview URLs. Servers a guest starts can be exposed through signed preview URLs.
• See Networking for the internals.

Note

The security boundary that matters is between the trusted sidecar and the untrusted executor. Everything the guest tries to do crosses into the kernel, where the policy is checked before the operation runs. See the Security Model for the full threat model.

Agents & sessions

An agent (such as Pi) is just another guest process running inside a VM, behind the same boundary as any other code. A session keeps that agent alive across many prompts and streams its output back to your app as events.

Sessions & transcripts

• Long-lived. Where a bare exec() runs once and exits, a session keeps an agent alive across many prompts.
• Streamed. The agent’s output flows back to your app in real time as sessionEvents.
• Replayable. Each session persists a transcript (with sequence numbers) that survives sleep/wake, so you can replay the conversation later.
• Context injected. agentOS adds a system prompt describing the VM environment and available tools, layered on top of the agent’s own instructions. See System Prompt.
• See Agent Sessions for the internals.

Permissions & approvals

• Two layers, different jobs. The lower-level permission policy is enforced by the kernel on every guest syscall (nothing is allowed until you opt in). On top of that, approvals are about an agent asking before it uses a tool.
• Human-in-the-loop or automatic. Subscribe to permissionRequest and respond per request, or use a server-side hook to decide without a client round-trip.
• Blocks until answered. If neither your hook nor your client responds, the agent waits rather than proceeding.

Orchestration (Rivet Actors)

The agentOS() actor (from @rivet-dev/agentos) wraps the raw VM in a Rivet Actor, which adds durable state, scheduling, and orchestration. This is what gives you persistence, cron, and workflows out of the box.

What are actors?

• Durable server objects. A Rivet Actor is a long-lived, addressable object with its own state. You reach a specific VM by name (vm.getOrCreate("my-agent")).
• Stateful by default. Unlike the bare core package, the actor keeps its filesystem and sessions persistent and handles distributed state for you.
• The portable runtime. Actors give you a consistent way to run agentOS() on any infrastructure, with persistence, networking, and orchestration built in.

Cron

• Recurring work. Schedule a shell command or an agent session on a cron expression.
• Overlap control. Choose what happens when a run is still going when the next is due (allow, skip, or queue).
• Observable. Stream cronEvents to watch executions. See Cron Jobs.

Workflows

• Durable multi-step tasks. A workflow is the actor’s run handler wrapped in workflow(), where each ctx.step() is recorded, retried, and resumed independently.
• Crash-proof. If the process dies mid-run, replay skips completed steps and continues where it left off.
• Composable. The output of one step feeds the next: clone a repo, let an agent fix a bug, run the tests. See Workflow Automation.

Persistence & sleep/wake

• Sleeps when idle. After a grace period (15 minutes by default) with no activity, the VM sleeps to free resources.
• Wakes on demand. It wakes automatically when a client connects or a cron job fires.
• What survives. The /home/user filesystem, session records, transcripts, preview tokens, and cron definitions all persist. In-memory kernel state (running processes, open shells) does not. See Persistence & Sleep.

Going deeper

This page is the map. Each subsystem has its own detailed page in the Advanced architecture section:

• Agent Sessions: how a session is bound to a VM, and how prompts and events flow end to end.
• Processes: the virtual process table, exec() / run(), child processes, and PTYs.
• Filesystem: the per-VM virtual filesystem, overlays, and host-backed mounts.
• Networking: the virtual socket table, DNS, the allowlist, and guest fetch().
• POSIX Syscalls: how WebAssembly guests behave like normal POSIX programs on top of the kernel.
• Compiler Toolchain: how the shell and coreutils are compiled to WebAssembly and mounted into the VM.
• System Prompt: the context agentOS injects into every agent session.
• Persistence & Sleep: what survives sleep/wake, and how VMs sleep and wake.

For the trust model and what counts as a sandbox escape, see the Security Model.