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
• GitHub: 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

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

Configuration

AgentOS Setup Inside Actor

# 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

Permissions

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

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:

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):

sandbox_escalation_keywords=["run_binary", "compile_code", "system_command"]

Lifecycle Inside Actor

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

Summary

See Also

• Rivet Actor Model — Actor implementation
• Agent Lifecycle — State transitions
• Pi Agent Setup — Pi Agent inside the isolate