Skip to main content
The Control Plane provides enterprise-grade agent orchestration through 8 specialized Rust workers, exposing 45 functions via 44 HTTP endpoints and 2 PubSub triggers.

​
Architecture

All 8 crates are built on iii-engine using the iii-sdk, connecting via WebSocket to register functions and triggers. Every component follows the same pattern: 
let iii = III::new("ws://localhost:49134");
iii.register_function_with_description(
    "crate::function",
    "Description",
    move |input: Value| { /* handler */ },
);
iii.register_trigger("http", "crate::function", json!({ ... }))?;

​
The 8 Crates

CratePurposeLOCFunctionsEndpoints
realmMulti-tenant isolation domains~28077 REST
hierarchyAgent org structure (cycle-safe DFS)~25055 REST
directiveHierarchical goal alignment~28055 REST
missionTask lifecycle with state machine~35077 REST
ledgerBudget enforcement (soft/hard limits)~30044 REST + 1 PubSub
councilGovernance with SHA-256 audit chain~45066 REST + 1 PubSub
pulseScheduled agent invocation~25044 REST
bridgeExternal runtime adapters (6 types)~30055 REST
Total: 8 crates, 45 functions, 44 HTTP endpoints, 2 PubSub triggers

​
Key Features

Multi-Tenant Isolation

Realms provide complete isolation with export/import capabilities and secret scrubbing.

Organizational Hierarchy

Cycle-safe org charts with capability search and chain-of-command resolution.

Goal Alignment

Hierarchical directives with ancestry tracing and optimistic concurrency control.

Task Management

State machine-driven missions with atomic checkout and comment threads.

Budget Enforcement

Soft/hard limits with per-agent/model/provider spend tracking and alerts.

Governance

Proposal-based governance with merkle-chained audit trail and agent overrides.

Scheduled Invocation

Cron-based agent activation with context-aware ticks and budget gating.

Runtime Adapters

Bridge to 6 external runtimes: Process, HTTP, ClaudeCode, Codex, Cursor, OpenCode.

​
Usage Example

// Create realm
trigger("realm::create", json!({
    "name": "production",
    "description": "Production environment",
    "owner": "admin",
    "defaultModel": "claude-sonnet-4",
    "maxAgents": 100
}))

// Build hierarchy
trigger("hierarchy::set", json!({
    "realmId": "r-1",
    "agentId": "agent-ceo",
    "title": "CEO",
    "capabilities": ["leadership", "strategy"],
    "rank": 10
}))

// Create directive
trigger("directive::create", json!({
    "realmId": "r-1",
    "title": "Ship v2.0",
    "level": "realm",
    "priority": "critical"
}))

// Create mission
trigger("mission::create", json!({
    "realmId": "r-1",
    "title": "Build authentication",
    "directiveId": "dir-1",
    "priority": "high",
    "createdBy": "agent-pm"
}))

// Set budget
trigger("ledger::set_budget", json!({
    "realmId": "r-1",
    "monthlyCents": 500000,
    "softThreshold": 0.8,
    "hardLimit": true
}))

// Submit proposal
trigger("council::submit", json!({
    "realmId": "r-1",
    "kind": "hire_agent",
    "title": "Hire research agent",
    "requestedBy": "agent-lead"
}))

// Schedule pulse
trigger("pulse::register", json!({
    "realmId": "r-1",
    "agentId": "agent-ops",
    "cron": "0 */5 * * * *",
    "contextMode": "full"
}))

// Register runtime
trigger("bridge::register", json!({
    "kind": "process",
    "name": "Python Agent",
    "command": "python",
    "args": ["agent.py"],
    "timeoutSecs": 300
}))

​
Starting Workers

​
Via CLI

agentos start  # Starts all workers including control plane

​
Manual

cargo run --release -p agentos-realm &
cargo run --release -p agentos-hierarchy &
cargo run --release -p agentos-directive &
cargo run --release -p agentos-mission &
cargo run --release -p agentos-ledger &
cargo run --release -p agentos-council &
cargo run --release -p agentos-pulse &
cargo run --release -p agentos-bridge &

​
REST API

All endpoints are exposed via iii-engine’s REST API module on port 3111: 
# Realm endpoints
POST   /api/realms
GET    /api/realms
GET    /api/realms/:id
PATCH  /api/realms/:id
DELETE /api/realms/:id
POST   /api/realms/:id/export
POST   /api/realms/import

# Hierarchy endpoints
POST   /api/hierarchy
GET    /api/hierarchy/:realmId/tree
GET    /api/hierarchy/:realmId/find
GET    /api/hierarchy/:realmId/chain/:agentId
DELETE /api/hierarchy/:realmId/:agentId

# ...and 34 more endpoints

​
PubSub Integration

Two functions subscribe to topics for reactive processing: 
// Ledger listens for cost events
iii.register_trigger("subscribe", "ledger::spend", 
    json!({ "topic": "cost.incurred" }))?;

// Council listens for audit events
iii.register_trigger("subscribe", "council::activity", 
    json!({ "topic": "council.audit" }))?;

​
Design Principles

1

Function-Based Architecture

Every capability is a pure function registered on the iii-engine bus. No frameworks, no classes, no inheritance.
2

State via iii-engine

All state is stored using state::set, state::get, state::list functions. No direct database access.
3

Event-Driven Communication

Workers publish lifecycle events to topics. Other workers can subscribe and react.
4

Fail-Safe Defaults

Missing budget? Allow by default. Missing directive? Continue. The system degrades gracefully.
5

Optimistic Concurrency

Versioned CAS (Compare-And-Swap) prevents race conditions on critical updates.

​
Next Steps

Realm

Learn about multi-tenant isolation

Hierarchy

Build organizational structures

Directive

Align agent goals

Mission

Manage tasks and workflows

Ledger

Track and enforce budgets

Council

Govern your agent fleet

Pulse

Schedule agent invocations

Bridge

Connect external runtimes

Build docs developers (and LLMs) love

Get started for freeTalk to us