---
title: Rivet Agent Isolation
---
# Rivet Agent Isolation

> **Note**: This document is superseded by [Rivet Actor Model](/rivet-actor-model) which contains the full implementation. This document covers the conceptual model of per-user isolation.

## Overview

Each WhatsApp user gets an **isolated Rivet actor** — a durable, self-contained unit of execution that owns its own state, tools, and conversation history. There is zero shared state between users.

## Isolation Model

```mermaid
graph TB
    subgraph "Message Ingestion"
        MSG[Incoming Message]
        PHONE[Phone Number ID]
    end

    subgraph "Rivet Orchestration"
        LOOKUP{Actor exists?}
    end

    subgraph "Rivet Cluster"
        A1["Actor +94771234567<br/>(isolated)"]
        A2["Actor +94719876543<br/>(isolated)"]
        A3["Actor +94765555555<br/>(isolated)"]
    end

    MSG --> PHONE
    PHONE --> LOOKUP
    LOOKUP -->|Yes| A1
    LOOKUP -->|Yes| A2
    LOOKUP -->|No| A3

    style A1 fill:#c8e6c9
    style A2 fill:#c8e6c9
    style A3 fill:#c8e6c9
```

## Why Actor Isolation?

### Security
- User data is never visible to other users
- No cross-user state leakage
- Each user has their own rate limit, abuse tracking, injection violation count

### State Management
- Each actor owns its conversation history
- Cart state is per-user
- Preferences are per-user
- Durable state survives sleep/wake/restarts

### Concurrency
- Rivet serializes `on_message()` per actor — no race conditions
- No shared resources to protect
- No locks needed

### Scalability
- Actors distribute across cluster automatically
- No sticky sessions required
- Horizontal scaling by adding Rivet nodes

## Actor State

```mermaid
stateDiagram-v2
    [*] --> Created: First message
    Created --> Running: on_init() complete
    Running --> Active: Processing messages
    Active --> Idle: 5 min no activity
    Idle --> Active: New message arrives
    Idle --> Terminated: 1 hr idle
    Active --> Terminated: User blocks/deletes

    note right of Active
        Isolated state
        Per-user conversation
        Per-user tools
    end note
```

## Resource Allocation

| Resource | Per-Actor | How |
|----------|-----------|-----|
| Memory | ~22 MB | AgentOS V8 isolate |
| CPU | Shared | Rivet schedules across cluster |
| Filesystem | Isolated | AgentOS virtual FS |
| Network | Isolated | AgentOS virtual network |
| State | Isolated | Rivet Durable State |
| Conversation | Isolated | Pi Agent Core per actor |
| Cart | Isolated | State per actor |
| Rate limits | Per-user | Stored in actor state |
| Abuse tracking | Per-user | Stored in actor state |

## Integration with AgentOS

```mermaid
flowchart LR
    A[WhatsApp Webhook] --> B[FastAPI Gateway]
    B --> C[Rivet get_actor]
    C --> D[Rivet Actor]
    D --> E[AgentOS V8 Isolate]
    E --> F[Pi Agent Core]
    F --> G[Shopify MCP Tools]
    F --> H[Rivet Durable State]
```

Each actor contains:
- An AgentOS V8 isolate (sandboxed OS)
- A Pi Agent Core instance (LLM orchestration)
- Registered Shopify MCP tools
- Durable state (conversation + security + user state)

## What Rivet Handles

| Concern | Rivet's Solution |
|---------|------------------|
| Actor creation | `get_actor()` creates if missing |
| Routing | Routes message to correct actor by ID |
| Serialization | `on_message()` runs one at a time per actor |
| Queuing | Messages queue during execution |
| State | Durable state persists across sleep/wake |
| Sleep | Auto-sleep after idle timeout |
| Wake | `on_wake()` called on new message |
| Terminate | Auto-terminate after extended idle |
| Distribution | Actors spread across cluster |
| Recovery | Resume from last state on crash |

## See Also

- [Rivet Actor Model](/rivet-actor-model) — Full implementation with code
- [Agent Lifecycle](/agent-lifecycle) — Message flow
- [AgentOS Configuration](/agentos-configuration) — Sandbox details
- [Concurrency & Security](/concurrency-security) — Rate limiting, injection prevention