# 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. OS Client JS · Browser · Backend Server OS = an isolated VM 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](/agentos/docs/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. The VM Kernel trusted core, every operation goes through here virtual filesystem process table socket table pipes / PTYs DNS permission policy · network allowlist · resource limits syscalls / replies Executor untrusted, runs guest code, holds no capabilities guest JavaScript (native V8) WASM shell · coreutils · npm packages · native binaries ### Kernel: the trusted core guest request Kernel filesystem processes network & DNS policy & limits 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 Executor untrusted · no capabilities JS (V8) WASM nativebinaries syscall reply Kernel 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](/agentos/docs/javascript). - **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](/agentos/docs/architecture/posix-syscalls) and the [Compiler Toolchain](/agentos/docs/architecture/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 exec() / run() spawn / shell process table virtual · per-VM pipes & PTYs - **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](/agentos/docs/architecture/processes) for the internals. ### Virtual filesystem overlay (guest writes) root layer (snapshot) host dir mount S3 mount cloud store mount points grafted onto guest paths - **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/agentos` filesystem survives sleep/wake. - See [Filesystem](/agentos/docs/architecture/filesystem) for the internals. ### Networking fetch() node:http node:net WASM sockets socket table kernel-owned egress allowlist - **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](/agentos/docs/architecture/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](/agentos/docs/security-model) for the full threat model. ## Agents & sessions An agent (such as [Pi](https://github.com/mariozechner/pi-coding-agent)) 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. Client your app prompt events The VM Agent session long-lived agent process Filesystem SQLite over UDS ### Sessions & durable files - **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 `sessionEvent`s. - **Durable semantic events.** Completed ACP updates and interactive permission request/response records are sequenced in SQLite; streaming message deltas remain live-only. - **Durable files.** Files under `/home/agentos` survive sleep through the sidecar's direct SQLite-over-UDS connection. - **Context injected.** agentOS adds a system prompt describing the VM environment and available commands and bindings, layered on top of the agent's own instructions. See [System Prompt](/agentos/docs/system-prompt). - See [Agent Sessions](/agentos/docs/architecture/agent-sessions) for the internals. ### Permissions & approvals - **Two layers, different jobs.** The lower-level [permission policy](/agentos/docs/permissions) is enforced by the kernel on every guest syscall (nothing is allowed until you opt in). On top of that, [approvals](/agentos/docs/approvals) are about an agent asking before it uses a tool. - **Human-in-the-loop or automatic.** Use the default `allow_all`, explicit `reject_all`, or subscribe to `permission_request` variants on the ordinary session-event stream with `permissionPolicy: "ask"`. - **Blocks until answered.** An `ask` request has no expiry and keeps the active turn awake until a response or explicit lifecycle transition wins the race. ## Orchestration (Rivet Actors) The `agentOS()` actor (from `@rivet-dev/agentos`) wraps the raw VM in a [Rivet Actor](/agentos/docs/core), which adds durable state, scheduling, and orchestration. This is what gives you persistence, cron, and workflows out of the box. It also registers the [inspector](/agentos/docs/inspector) tabs in the Rivet dashboard, so every actor comes with a live view of its transcript, filesystem, and processes. Rivet Actor durable, addressable server object agentOS VM the virtual Linux VM Cron Workflows Persistence · sleep / wake Durablestate ### 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.** The actor persists its filesystem, actor state, durable session metadata, and completed ACP history. Active adapter processes remain runtime state. - **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 `cronEvent`s to watch executions. See [Crons & Loops](/agentos/docs/cron). ### 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 [Workflows & Graphs](/agentos/docs/workflows). ### 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/agentos` filesystem, actor state, preview tokens, durable session metadata, and completed ACP history persist. On wake, `openSession` restores the adapter when possible and otherwise starts it with AgentOS history as context. In-flight deltas, running processes, and open shells do not survive. See [Persistence & Sleep](/agentos/docs/persistence). ## Going deeper This page is the map. Each subsystem has its own detailed page in the Advanced architecture section: - **[Agent Sessions](/agentos/docs/architecture/agent-sessions)**: how a session is bound to a VM, and how prompts and events flow end to end. - **[Processes](/agentos/docs/architecture/processes)**: the virtual process table, `exec()` / `run()`, child processes, and PTYs. - **[Filesystem](/agentos/docs/architecture/filesystem)**: the per-VM virtual filesystem, overlays, and host-backed mounts. - **[Networking](/agentos/docs/architecture/networking)**: the virtual socket table, DNS, the allowlist, and guest `fetch()`. - **[JavaScript Executor & Socket Reactor](/agentos/docs/architecture/javascript-executor)**: how the shared Tokio runtime, V8 executor threads, coalesced readiness, bounded channels, and Node stream backpressure fit together. - **[POSIX Syscalls](/agentos/docs/architecture/posix-syscalls)**: how WebAssembly guests behave like normal POSIX programs on top of the kernel. - **[Compiler Toolchain](/agentos/docs/architecture/compiler-toolchain)**: how the shell and coreutils are compiled to WebAssembly and mounted into the VM. - **[System Prompt](/agentos/docs/system-prompt)**: the context agentOS injects into every agent session. - **[Persistence & Sleep](/agentos/docs/persistence)**: 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](/agentos/docs/security-model).