---
title: AgentOS
---
# AgentOS

> **Note**: For detailed configuration, see [AgentOS Configuration](/agentos-configuration).

## Overview

AgentOS is a V8 isolate + WASM-based virtual operating system by Rivet. It runs **inside each Rivet actor** and provides a POSIX-compatible environment for the Pi Agent instance.

- **Package**: `@rivet-dev/agentos` (npm)
- **Docs**: [agentos-sdk.dev](https://agentos-sdk.dev)
- **GitHub**: [rivet-dev/rivet](https://github.com/rivet-dev/rivet)
- **Tagline**: "Give agents an operating system as a library"

## Role in Architecture

```mermaid
graph TB
    subgraph "Rivet Actor"
        AOS[AgentOS<br/>V8 Isolate + WASM]
        PI[Pi Agent Core<br/>Python runtime]
        TOOLS[Extensions]
    end

    subgraph "Storage"
        S3[(S3 Mount)]
        MEM[(Memory Mount)]
    end

    AOS --> PI
    PI --> TOOLS
    AOS -.->|mounts| S3
    AOS -.->|mounts| MEM

    style AOS fill:#fff9c4,stroke:#f9a825,stroke-width:3px
    style PI fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
```

## Key Characteristics

| Characteristic | Value |
|----------------|-------|
| Isolation model | V8 isolate + WASM |
| Memory per isolate | ~22 MB |
| Cold start | 4.8 ms p50 |
| POSIX compatibility | Filesystem, network, processes, shell |
| Storage mounts | Host dir, S3, Google Drive, memory |
| Sandbox escalation | Can mount full Linux sandbox if needed |

## What It Provides

- **Virtual filesystem** — mount S3, host dirs, or memory
- **Virtual networking** — isolated outbound HTTP
- **Virtual processes** — optional subprocess support
- **Virtual shell** — command execution in sandbox
- **Resource limits** — per-isolate CPU, memory, file, socket caps
- **Preview URLs** — for debugging (optional)

## Integration with Rivet

```mermaid
flowchart LR
    MSG[Incoming message] --> RIVET[Rivet get_actor]
    RIVET --> ACTOR[Rivet Actor]
    ACTOR --> AOS[AgentOS Isolate]
    AOS --> PI[Pi Agent Core]
    PI --> TOOLS[Shopify MCP Tools]
    PI --> LLM[LLM Provider]
```

- Rivet manages the actor lifecycle (create, sleep, wake, terminate)
- AgentOS provides the isolated execution environment for each actor
- Pi Agent runs inside the AgentOS isolate

## Performance

| Metric | AgentOS | E2B | Daytona |
|--------|---------|-----|---------|
| Cold start | 4.8 ms | 440 ms | ~1s |
| Memory | 22 MB | 1024 MB | ~500 MB |
| Cost | 1× | 92× | 254× |

## Why AgentOS for This Bot

- **Per-user isolation** — each user's agent runs in its own isolate
- **Fast cold starts** — 4.8ms means instant scaling
- **Low memory** — 22 MB per user means thousands per cluster
- **Integrated with Rivet** — natural fit for actor-based architecture
- **Escalation** — can mount full Linux sandbox if native tools needed later

## See Also

- [AgentOS Configuration](/agentos-configuration) — Detailed setup, mounts, permissions
- [Rivet Actor Model](/rivet-actor-model) — Actor implementation
- [Agent Lifecycle](/agent-lifecycle) — State transitions