Architecture

How Core, the sidecar, kernel, VFS, and executors fit together.

@rivet-dev/agentos-core controls the runtime from a trusted Node.js process. It may retain host-only state such as host function handlers, mount plugins, local package paths, and custom scheduling.

Runtime boundary

The trusted sidecar owns the kernel, VFS, process and socket tables, permissions, resource policy, package acquisition and projection, and language executors. Untrusted JavaScript, Python, WASM, and third-party package code runs on the guest side of that boundary.

The native sidecar binary uses fd 0 for requests, stdout for ordinary events, and inherited fd 3 for responses, callbacks, heartbeats, and shutdown control.

Durability

The VM database has independent schema owners:

Each owner advances only its own migration ladder. There is no legacy storage adoption path.

The default VM root is an ephemeral in-memory overlay over the bundled base image. Store the root filesystem in the VM’s SQLite database for files that must survive VM recreation; see Persistence.