agentOS

The @rivet-dev/agentos-node-pty package provides an implementation of the @lydell/node-pty JavaScript API specifically for AgentOS kernel PTYs.

Key characteristics:

• Environment: It is intended for use by packages running inside an AgentOS Virtual Machine (VM).
• No Native Addons: Unlike standard node-pty, this implementation does not load a native Node.js addon, making it compatible with the AgentOS runtime environment.

If no mounts are configured, every VM boots with an Alpine-based root filesystem that is persisted across sleep/wake. The default layout includes:

• /home/agentos: The agent's home directory ($HOME) and default working directory (pwd). Mounts typically land under this directory (e.g., /home/agentos/data).
• /bin, /sbin, /usr: Installed commands and POSIX utilities.
• /etc, /lib, /opt, /root, /run, /srv, /tmp, /var, /mnt: Standard system paths.

Note: Guest fs calls never touch the host disk; they are isolated within the VM's virtual filesystem.

Every VM runs inside a shared sidecar process rather than its own dedicated process.

• By default, all VMs use a single process-global sidecar (the default pool).
• Adding a new VM only adds a V8 isolate and its kernel state, keeping per-VM memory in the tens of MBs and creation times in single-digit milliseconds.
• Disposing a VM tears down only that specific VM; the sidecar process remains active for the host process lifetime.
• The direct VM API allows you to use explicit sidecar handles to isolate groups of VMs into their own processes.

agentOS uses a split architecture to separate trusted I/O from untrusted JavaScript execution:

• Sidecar Process (Tokio Runtime): A multithreaded Tokio runtime manages all shared subsystems, including socket readers/writers, DNS, TLS, HTTP/2, timers, and VM supervisors. These run as async tasks and do not create a dedicated OS thread per task.
• V8 Executor (JavaScript Execution): Each active JavaScript session has its own thread-affine V8 executor. This is a real OS thread outside of Tokio. It owns the isolate and is the only non-V8 platform thread allowed to enter it.

Key Isolation Property: Synchronous guest JavaScript or a synchronous bridge wait can block its specific V8 executor thread, but it cannot block a Tokio worker or any other VM's executor.

The browser demo exercises the full converged path in the browser using the agentos-sidecar-browser Wasm module. The workflow includes:

1. Booting: The agentos-sidecar-browser Wasm module boots in the page and reports a sidecarId.
2. Authentication: Authentication is performed over the BARE wire protocol using the @rivet-dev/agentos-runtime-core codec.
3. Request: An ACP get_session_state request is sent as a wire ExtEnvelope.
4. Routing: The frame is routed from BrowserAcpExtension to AcpCore (the host-free engine shared with the native sidecar).
5. Response: AcpCore returns a real ACP response.

This process demonstrates wire decoding, authentication, extension dispatch, and host-free ACP core execution without requiring host I/O or guest-side permission evaluation, as the Wasm kernel enforces permissions.

agentOS provides a POSIX syscall surface for WebAssembly (WASM) guests (such as sh, coreutils, or custom .wasm binaries) to allow them to behave like standard Linux tools. This is achieved through a two-layer model that routes all calls through the agentOS kernel rather than the host, ensuring security and isolation.

The Two-Layer Model

1. Layer 1: Custom Host Import Modules: Adds capabilities that standard WASI (wasip1) lacks, such as process management, user identity, and TCP sockets.
2. Layer 2: Kernel-backed WASI Shim: Adapts standard WASI calls so that a normal libc behaves correctly (e.g., routing stdio through the kernel, handling fcntl flags, and enforcing mount-based path confinement).

All WASM syscalls use the same kernel-owned virtual filesystem, process table, and socket table as JavaScript guests, meaning they do not grant extra host access.

The agentOS kernel uses a virtual process model where guest processes are entries in a kernel-owned virtual process table rather than real host OS processes.

Key characteristics:

• Isolation: Each VM has its own independent process table. PIDs are local to the VM and cannot be seen across VM boundaries.
• No Host Processes: Guest JavaScript runs in V8 isolates, and guest commands (like sh or coreutils) run as WebAssembly. No real host binaries are spawned for guest work.
• Syscall-based Operations: Every process operation (spawning, waiting, signaling, reading stdout, resizing PTYs) is a syscall into the kernel.
• Uniformity: Whether a process is a V8 isolate or a WASM binary, it uses the same kernel-owned stdio, PTYs, and permission-checked spawn paths.

agentOS Apps can leverage several durable capabilities. These capabilities use RivetKit and its DirectActor client. Note that agentOS Apps does not wrap the client; you use the standard RivetKit client to interact with these features.

Supported capabilities include:

• SQLite: Store durable data in an actor-owned SQLite database.
• Workflows: Run durable multi-step jobs that can sleep and resume.
• Multiplayer: Share realtime state between clients.
• Queues: Use actor queues for durable background work and ordered processing.
• Cron jobs: Schedule recurring work from an actor.