Grand Diomande Research · Full HTML Reader
AgentOS — System Architecture
``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ AgentOS Platform │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Dashboard │ │ CLI │ │ SDK │ │ Webhooks │ │ │ │ (Next.js) │ │ (agentos) │ │ (npm pkg) │ │ (inbound) │ │ │ └──────┬───────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ │ │ │ │ │ ═══════╪═════════════════╪═════════════════╪═════════════════╪══════════ │ │ │ API Gateway (Hono) │ │ │ │ │ ┌──────────────────────────────────┐ │ │ │ └─
Full Public Reader
AgentOS — System Architecture
> The operating system for autonomous AI agents.
---
1. High-Level Overview
┌─────────────────────────────────────────────────────────────────────────────┐
│ AgentOS Platform │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Dashboard │ │ CLI │ │ SDK │ │ Webhooks │ │
│ │ (Next.js) │ │ (agentos) │ │ (npm pkg) │ │ (inbound) │ │
│ └──────┬───────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │ │
│ ═══════╪═════════════════╪═════════════════╪═════════════════╪══════════ │
│ │ API Gateway (Hono) │ │ │
│ │ ┌──────────────────────────────────┐ │ │
│ └───────┤ Auth · Rate Limit · Tenant CTX ├──────────┘ │
│ └──────────────┬───────────────────┘ │
│ │ │
│ ══════════════════════════════╪═══════════════════════════════════════════ │
│ Control Plane │
│ ┌─────────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
│ │ Tenant Mgr │ │ Billing │ │ Auth │ │ Events │ │
│ │ (provision) │ │ (Stripe) │ │ (Supa) │ │ (Redis) │ │
│ └──────────────┘ └──────────┘ └──────────┘ └─────┬─────┘ │
│ │ │
│ ═════════════════════════════════════════════════════╪═════════════════════ │
│ Execution Plane │ │
│ ┌──────────────────┐ ┌────────────┐ ┌──────────────┐ │
│ │ Pulse Engine │ │ Heartbeat │ │ Dream Engine │ │
│ │ │ │ │ │ │ │
│ │ Sessions ────────┤ │ Scheduler──┤ │ Garden ─────┤ │
│ │ Chains ──────────┤ │ Checks ────┤ │ Evolution ──┤ │
│ │ Parallel ────────┤ │ Router ────┤ │ Compiler ───┤ │
│ │ Gates ───────────┤ │ Quiet Hrs ─┤ │ Collective ─┤ │
│ │ Rollback ────────┤ │ │ │ │ │
│ │ Cost Tracker ────┤ │ │ │ │ │
│ └────────┬──────────┘ └─────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ ═════════╪═══════════════════╪══════════════════╪═════════════════════════ │
│ │ Integration Layer │ │
│ ┌────────┴──────┐ ┌──────────────┐ ┌─────────┴────┐ ┌──────────────┐ │
│ │ Model Router │ │ Skill Mgr │ │ Workspace │ │ Tool Layer │ │
│ │ (multi-LLM) │ │ (registry) │ │ (storage) │ │ (sandboxed) │ │
│ └───────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ═══════════════════════════════════════════════════════════════════════════ │
│ Data Layer │
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
│ │ PostgreSQL │ │ Redis │ │ Object Store │ │
│ │ (Supabase) │ │ (Upstash) │ │ (S3/Supa) │ │
│ │ │ │ │ │ │ │
│ │ Tenants │ │ Event Bus │ │ Workspaces │ │
│ │ Sessions │ │ Session Q │ │ Checkpoints │ │
│ │ Skills │ │ Rate Limits │ │ Skill Pkgs │ │
│ │ Dreams │ │ Cache │ │ Artifacts │ │
│ │ Billing │ │ │ │ │ │
│ └───────────────┘ └───────────────┘ └───────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘---
2. Component Contracts
2.1 Pulse Engine
The core execution engine. Ports existing Pulse v3 to multi-tenant SaaS.
typescript
interface PulseEngine {
// Session lifecycle
createSession(tenant: TenantId, config: SessionConfig): Promise<Session>
runSession(sessionId: SessionId): Promise<SessionResult>
pauseSession(sessionId: SessionId): Promise<void>
resumeSession(sessionId: SessionId): Promise<void>
cancelSession(sessionId: SessionId): Promise<void>
// Chains
createChain(tenant: TenantId, chain: ChainConfig): Promise<Chain>
runChain(chainId: ChainId): Promise<ChainResult>
// Checkpoints
checkpoint(sessionId: SessionId): Promise<Checkpoint>
restore(checkpointId: CheckpointId): Promise<Session>
// Quality
runGate(sessionId: SessionId, gate: GateConfig): Promise<GateResult>
// Cost
getSessionCost(sessionId: SessionId): Promise<CostReport>
getTenantUsage(tenant: TenantId, period: DateRange): Promise<UsageReport>
}State Machine:
CREATED → QUEUED → RUNNING → CHECKPOINT → GATE_CHECK → COMPLETE
↓ ↓ ↓ ↓
FAILED PAUSED PAUSED FAILED
↓ ↓ ↓ ↓
(dead) RUNNING RUNNING ROLLBACK → ROLLED_BACK2.2 Heartbeat System
Proactive monitoring, ported from Heartbeat v2.
typescript
interface HeartbeatSystem {
// Configuration
configure(tenant: TenantId, config: HeartbeatConfig): Promise<void>
// Checks
registerCheck(check: CheckDefinition): void
runCheck(checkId: string): Promise<CheckResult>
// Scheduling
start(tenant: TenantId): Promise<void>
stop(tenant: TenantId): Promise<void>
// History
getHistory(tenant: TenantId, period: DateRange): Promise<HeartbeatLog[]>
// Notifications
getAlerts(tenant: TenantId, filter?: AlertFilter): Promise<Alert[]>
}Check Lifecycle:
REGISTERED → SCHEDULED → RUNNING → RESULT
├── OK → (silent or batch)
├── WARN → route by priority
└── ALERT → immediate notify2.3 Dream Engine
Idea incubation, evolved from Dream Weaver.
typescript
interface DreamEngine {
// Garden
plantSeed(tenant: TenantId, seed: DreamSeed): Promise<Dream>
getDream(dreamId: DreamId): Promise<Dream>
getGarden(tenant: TenantId): Promise<Dream[]>
// Evolution
evolve(dreamId: DreamId): Promise<EvolutionResult>
crossPollinate(dreamA: DreamId, dreamB: DreamId): Promise<Dream>
// Compilation
compile(dreamId: DreamId): Promise<SessionConfig> // Dream → Pulse session
// Collective
shareDream(dreamId: DreamId, targetTenant: TenantId): Promise<void>
getSharedDreams(filter?: DreamFilter): Promise<Dream[]>
}Growth Stages:
SPORE (0.0-0.2) → SEEDLING (0.2-0.4) → SAPLING (0.4-0.6) → BLOOM (0.6-0.8) → FRUIT (0.8-1.0)
↓
COMPILED → Session2.4 Model Router
Provider-agnostic model routing. Satisfies INV-2.
typescript
interface ModelRouter {
// Routing
route(request: ModelRequest, preferences: ModelPreferences): Promise<ModelResponse>
// Provider management
addProvider(tenant: TenantId, config: ProviderConfig): Promise<void>
removeProvider(tenant: TenantId, providerId: string): Promise<void>
// Fallback
setFallbackChain(tenant: TenantId, chain: string[]): Promise<void>
// Cost
estimateCost(request: ModelRequest): Promise<CostEstimate>
}
type ModelProvider = 'anthropic' | 'openai' | 'google' | 'mistral' | 'custom'2.5 Skill Manager
Skill lifecycle + marketplace.
typescript
interface SkillManager {
// Registry
install(tenant: TenantId, skill: SkillRef): Promise<InstalledSkill>
uninstall(tenant: TenantId, skillId: string): Promise<void>
list(tenant: TenantId): Promise<InstalledSkill[]>
// Marketplace
publish(skill: SkillPackage): Promise<PublishedSkill>
search(query: string): Promise<PublishedSkill[]>
// Runtime
loadForSession(sessionId: SessionId): Promise<SkillSet>
matchSkills(task: string): Promise<SkillRef[]>
}---
3. Data Flow
3.1 Session Execution Flow
User/API Control Plane Execution Plane Data Layer
│ │ │ │
│ POST /sessions │ │ │
│───────────────────────>│ │ │
│ │ validate tenant │ │
│ │ check budget │ │
│ │ enqueue session │ │
│ │───────────────────────>│ │
│ │ │ load skills │
│ │ │ load workspace │
│ │ │─────────────────────>│
│ │ │<─────────────────────│
│ │ │ route to model │
│ │ │ execute agent │
│ │ │ ··· │
│ WS: session.progress │ │ │
│<───────────────────────│<───────────────────────│ emit events │
│ │ │ │
│ │ │ run quality gates │
│ │ │ checkpoint │
│ │ │─────────────────────>│
│ │ │ │
│ │ │ complete │
│ WS: session.complete │ │ │
│<───────────────────────│<───────────────────────│ record cost │
│ │ update billing │─────────────────────>│
│ │─────────────────────────────────────────────>│3.2 Event Flow
All inter-component communication goes through the event bus:
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ Pulse Engine │────>│ Event Bus │────>│ Heartbeat │
│ │ │ (Redis) │ │ │
│ session.* │ │ │ │ check.* │
│ chain.* │ │ Pub/Sub │ │ alert.* │
│ gate.* │ │ + History │ │ │
└─────────────┘ │ │ └─────────────┘
│ │
┌─────────────┐ │ │ ┌─────────────┐
│ Dream Engine │────>│ │────>│ Dashboard │
│ │ │ │ │ (WS relay) │
│ dream.* │ │ │ │ │
│ garden.* │ │ │ │ UI updates │
└─────────────┘ └──────────────┘ └─────────────┘Core Event Types:
typescript
type AgentOSEvent =
// Pulse
| { type: 'session.created'; tenantId: string; sessionId: string; config: SessionConfig }
| { type: 'session.started'; tenantId: string; sessionId: string }
| { type: 'session.progress'; tenantId: string; sessionId: string; step: string; pct: number }
| { type: 'session.checkpoint'; tenantId: string; sessionId: string; checkpointId: string }
| { type: 'session.gate.passed'; tenantId: string; sessionId: string; gate: string }
| { type: 'session.gate.failed'; tenantId: string; sessionId: string; gate: string; reason: string }
| { type: 'session.completed'; tenantId: string; sessionId: string; result: SessionResult }
| { type: 'session.failed'; tenantId: string; sessionId: string; error: string }
// Heartbeat
| { type: 'heartbeat.check.ok'; tenantId: string; checkId: string }
| { type: 'heartbeat.check.warn'; tenantId: string; checkId: string; message: string }
| { type: 'heartbeat.alert'; tenantId: string; priority: number; message: string }
// Dreams
| { type: 'dream.planted'; tenantId: string; dreamId: string; seed: string }
| { type: 'dream.evolved'; tenantId: string; dreamId: string; stage: DreamStage; fitness: number }
| { type: 'dream.bloomed'; tenantId: string; dreamId: string }
| { type: 'dream.compiled'; tenantId: string; dreamId: string; sessionId: string }
// Skills
| { type: 'skill.installed'; tenantId: string; skillId: string; version: string }
| { type: 'skill.published'; skillId: string; author: string }---
4. Multi-Tenancy Design
4.1 Tenant Isolation Strategy
| Layer | Isolation Method |
|---|---|
| Database | Row-Level Security (RLS) — every table has `tenant_id`; policies enforce `auth.uid()` → `tenant_id` mapping |
| Compute | Session-level isolation — each session runs in sandboxed context with tenant-scoped filesystem |
| Secrets | Vault per tenant — encrypted at rest; decrypted only in session runtime |
| Events | Channel-per-tenant — Redis channels namespaced by `tenant:{id}:*` |
| Storage | Prefix-per-tenant — `{tenant_id}/` prefix in object storage |
| API | Middleware injection — `req.tenantId` set by auth; all queries scoped automatically |
4.2 Tenant Schema
sql
-- Core tenant table
CREATE TABLE tenants (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name TEXT NOT NULL,
slug TEXT UNIQUE NOT NULL,
plan TEXT NOT NULL DEFAULT 'free', -- free, pro, enterprise
settings JSONB DEFAULT '{}',
created_at TIMESTAMPTZ DEFAULT now(),
updated_at TIMESTAMPTZ DEFAULT now()
);
-- Tenant members (many-to-many with auth.users)
CREATE TABLE tenant_members (
tenant_id UUID REFERENCES tenants(id),
user_id UUID REFERENCES auth.users(id),
role TEXT NOT NULL DEFAULT 'member', -- owner, admin, member
PRIMARY KEY (tenant_id, user_id)
);
-- RLS: Users only see their tenants
ALTER TABLE tenants ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_access ON tenants
USING (id IN (
SELECT tenant_id FROM tenant_members WHERE user_id = auth.uid()
));---
5. Pricing Model
5.1 Tiers
| Feature | Free | Pro ($49/mo) | Enterprise (Custom) |
|---|---|---|---|
| Concurrent sessions | 2 | 20 | Unlimited |
| Session duration | 5 min | 30 min | Unlimited |
| Heartbeat checks | 5 | 50 | Unlimited |
| Dream garden | 10 dreams | 100 dreams | Unlimited |
| Skills | Public only | Public + private | Custom + self-hosted |
| Model providers | 1 | Unlimited | Unlimited |
| Team members | 1 | 10 | Unlimited |
| Support | Community | Dedicated | |
| SLA | None | 99.9 | |
| Token budget/mo | 1M | 50M | Custom |
5.2 Usage-Based Pricing (on top of tier)
| Metric | Rate |
|---|---|
| Tokens (pass-through + 15 | |
| Session compute (per min) | $0.005/min |
| Storage (per GB/mo) | $0.10/GB |
| API calls (over tier limit) | $0.001/call |
---
6. Security Architecture
┌─────────────────────────────────────────┐
│ Security Layers │
├─────────────────────────────────────────┤
│ 1. Edge: Cloudflare WAF + DDoS │
│ 2. Auth: Supabase JWT + API Keys │
│ 3. RBAC: Tenant → Role → Permission │
│ 4. RLS: PostgreSQL row-level policies │
│ 5. Secrets: Vault per tenant, AES-256 │
│ 6. Sandbox: Session compute isolation │
│ 7. Audit: Every mutation logged │
│ 8. Scan: No secrets in logs (INV-7) │
└─────────────────────────────────────────┘---
7. Migration Path from Clawdbot
Existing Clawdbot installations can migrate to AgentOS:
Clawdbot Component → AgentOS Package
─────────────────────────────────────────
pulse-v3/ → @agentos/engine
heartbeat-v2/ → @agentos/heartbeat
bot:dream-weaver/ → @agentos/dreams
enriched-spawn/ → @agentos/engine (sub-agents)
clawdhub skills/ → @agentos/skills (marketplace)
AGENTS.md + SOUL.md → Workspace config (API)
memory/*.md → Workspace storage (versioned)Migration CLI:
bash
agentos migrate --from-clawdbot [home-path]---
Architecture Version: 1.0.0 | Created: 2026-02-03 | Status: Phase Zero
Promotion Decision
Promote into a technical note or architecture paper with implementation anchors.
Source Anchor
unified-agent-os/ARCHITECTURE.md
Detected Structure
Method · References · Figures · Architecture