---
title: AgentOS Configuration
---
# AgentOS Configuration

## Overview

AgentOS is a V8 isolate + WASM-based virtual OS that runs **inside each Rivet actor**. It provides a POSIX-compatible environment (filesystem, network, processes) 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)
- **Runs inside**: Each Rivet actor (one isolate per actor)

> **Architectural context**: Each Rivet actor contains one AgentOS isolate. The isolate runs the Python Pi Agent Core runtime. AgentOS provides the sandbox; Rivet provides the actor lifecycle; Pi Agent provides the LLM orchestration.

## Architecture

```mermaid
graph TB
    subgraph "Rivet Cluster"
        subgraph "Actor: User A"
            AOS_A[AgentOS Isolate<br/>~22 MB]
            PY_A[Python Pi Agent]
            FS_A[Virtual Filesystem]
            NET_A[Virtual Network]
        end
        subgraph "Actor: User B"
            AOS_B[AgentOS Isolate<br/>~22 MB]
            PY_B[Python Pi Agent]
            FS_B[Virtual Filesystem]
            NET_B[Virtual Network]
        end
        subgraph "Actor: User N"
            AOS_N[AgentOS Isolate<br/>~22 MB]
            PY_N[Python Pi Agent]
            FS_N[Virtual Filesystem]
            NET_N[Virtual Network]
        end
    end

    subgraph "Mounted Storage"
        S3[(S3 Bucket)]
        MEM[(In-Memory)]
        HOST[(Host Directory)]
    end

    FS_A -.->|mount| S3
    FS_B -.->|mount| MEM
    FS_N -.->|mount| HOST

    style AOS_A fill:#fff9c4,stroke:#f9a825
    style AOS_B fill:#fff9c4,stroke:#f9a825
    style AOS_N fill:#fff9c4,stroke:#f9a825
```

## Performance

| Metric | AgentOS | Traditional Sandbox |
|--------|---------|---------------------|
| Cold start (p50) | **4.8 ms** | 440 ms (92× slower) |
| Memory per isolate | **~22 MB** | ~1024 MB (47× more) |
| Cost (vs Daytona) | **254× cheaper** | Baseline |

## Configuration

### AgentOS Setup Inside Actor

```python
# AgentOS is configured when the actor starts
from rivet import AgentOsConfig

@rivet.actor
class ShoppingAgentActor(Actor):
    class Config:
        agentos = AgentOsConfig(
            permissions=AgentOsPermissions(
                network=True,        # Shopify MCP + WhatsApp API + LLM
                filesystem=True,     # Session state + MCP operations
                processes=False,     # Not needed (security)
                max_memory_mb=128,
            ),
            mounts=[
                # User state (cart, preferences, conversation)
                MountConfig(
                    type="s3",
                    bucket="whatsapp-bot-state",
                    prefix="users/{actor_id}/",
                    target="/state",
                ),
                # Temporary workspace
                MountConfig(type="memory", target="/tmp"),
                # Read-only config
                MountConfig(
                    type="host",
                    source="/app/shared-config",
                    target="/config",
                ),
            ],
            limits=AgentOsLimits(
                max_processes=5,
                max_files=50,
                max_sockets=10,
                max_execution_time_ms=60000,
            ),
        )
```

### Mount Strategy

| Mount | Type | Purpose | Access |
|-------|------|---------|--------|
| `/state` | S3 | User state (cart, prefs, conversation) | Read/Write |
| `/tmp` | Memory | Temporary MCP operations | Read/Write (ephemeral) |
| `/config` | Host | Store policies, catalog cache | Read-only |

### Permissions

```python
AgentOsPermissions(
    network=True,        # Allow outbound HTTP (Shopify, WhatsApp, LLM)
    filesystem=True,     # Allow FS operations (state persistence)
    processes=False,     # No subprocess creation (security)
    max_memory_mb=128,   # Generous for agent state + MCP client
)
```

### Resource Limits

```python
AgentOsLimits(
    max_processes=5,         # MCP client + agent runtime
    max_files=50,            # Session files + cache
    max_sockets=10,          # Shopify + WhatsApp + LLM + Redis
    max_execution_time_ms=60000,  # 60s max per message
)
```

## Sandbox Escalation

AgentOS can escalate from V8 isolate to full Linux sandbox when needed:

```mermaid
stateDiagram-v2
    [*] --> V8Isolate: Normal operation
    V8Isolate --> V8Isolate: Standard tool calls
    V8Isolate --> LinuxSandbox: Escalation keyword triggered
    LinuxSandbox --> V8Isolate: Task complete

    note right of V8Isolate
        ~22 MB memory
        4.8 ms cold start
        No native binaries
    end note

    note right of LinuxSandbox
        Full Linux environment
        Native binary support
        Higher resource cost
    end note
```

For the shopping bot, escalation is **unlikely** — we only need:
- HTTP calls (Shopify MCP, WhatsApp API, LLM)
- File read/write (session state)
- JSON parsing (product data)

Escalation triggers (if needed):
```python
sandbox_escalation_keywords=["run_binary", "compile_code", "system_command"]
```

## Lifecycle Inside Actor

```mermaid
stateDiagram-v2
    [*] --> ActorCreated: Rivet creates actor
    ActorCreated --> AgentOsInit: on_init()
    AgentOsInit --> AgentRunning: Isolate ready
    AgentRunning --> AgentRunning: on_message() calls
    AgentRunning --> AgentSleeping: 5 min idle
    AgentSleeping --> AgentRunning: Wake on message
    AgentSleeping --> ActorTerminated: 1 hr idle
    ActorTerminated --> [*]
```

The AgentOS isolate follows the actor's lifecycle:
- Created when actor is created
- Active when actor is running
- Frozen when actor sleeps
- Destroyed when actor terminates

## Deployment Templates

| Platform | Template |
|----------|----------|
| Docker | `agentos-docker` |
| AWS (ECS/Lambda) | `agentos-aws` |
| GCP (Cloud Run) | `agentos-gcp` |
| Azure | `agentos-azure` |
| Vercel | `agentos-vercel` |
| Railway | `agentos-railway` |
| Fly.io | `agentos-fly` |
| Kubernetes | `agentos-helm` |

## Summary

| Requirement | AgentOS Solution |
|------------|-----------------|
| Per-user isolation | V8 isolate (~22 MB each) |
| Fast cold starts | 4.8 ms p50 |
| Persistent state | S3 mount |
| Network access | Virtual networking |
| Low cost | 254× cheaper than traditional sandboxes |
| Scalability | Runs inside Rivet actors, thousands per cluster |
| Native tools | Sandbox escalation (if needed) |

## See Also

- [Rivet Actor Model](/rivet-actor-model) — Actor implementation
- [Agent Lifecycle](/agent-lifecycle) — State transitions
- [Pi Agent Setup](/pi-agent-setup) — Pi Agent inside the isolate