website · architecture · quickstart · workers

---

§ 01 · Thesis

AgentOS isn't another agent framework. It's what's left when the runtime becomes someone else's problem.

65 narrow workers — one Rust binary per domain — register Functions and Triggers on the iii engine. Every capability is one shape: register_function(...). The engine carries routing, retries, state, and traces.

not	yes
assemble a runtime from category-shaped pieces	collapse the categories onto one bus
teach the model your DSL	teach it three nouns
bespoke agent runtime	narrow workers on iii

§ 02 · Three primitives

Primitive	What it does	Examples
Worker	One Rust binary per domain. Connects to the engine over WebSocket.	agent-core, llm-router, realm
Function	A named handler registered by a Worker.	agent::chat, llm::route, memory::search
Trigger	Binds a Function to HTTP, cron, or pub/sub.	POST /v1/chat → agent::chat

That's the whole protocol. Workers stay narrow; everything else lives in the engine.

§ 03 · Quickstart

curl -fsSL https://install.iii.dev/iii/main/install.sh | sh
git clone https://github.com/iii-experimental/agentos && cd agentos
cargo build --workspace --release
iii --config config.yaml &
for w in target/release/agentos-*; do "./$w" & done

Engine boots on port 49134. 64 Rust workers connect. 257 functions register. Then:

curl -X POST http://127.0.0.1:3111/v1/realms \
  -H 'Content-Type: application/json' \
  -d '{"name":"prod","description":"production"}'

§ 04 · Calling a function

use iii_sdk::{register_worker, InitOptions, TriggerRequest};
use serde_json::json;

let iii = register_worker("ws://localhost:49134", InitOptions::default());

let result = iii.trigger(TriggerRequest {
    function_id: "memory::recall".to_string(),
    payload: json!({"agentId": "alice", "query": "..."}),
    action: None,
    timeout_ms: None,
}).await?;

This is the only inter-worker contract. There is no shared in-process state.

§ 05 · Registering one

use iii_sdk::{register_worker, InitOptions, RegisterFunction};
use iii_sdk::error::IIIError;
use serde_json::{json, Value};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let iii = register_worker("ws://localhost:49134", InitOptions::default());

    iii.register_function(
        RegisterFunction::new_async("analyst::summarize", |input: Value| async move {
            let topic = input["topic"].as_str().unwrap_or("");
            Ok::<Value, IIIError>(json!({ "summary": format!("on {}", topic) }))
        })
        .description("Summarize a topic"),
    );

    tokio::signal::ctrl_c().await?;
    iii.shutdown_async().await;
    Ok(())
}

§ 06 · Workers

64 Rust + 1 Python, grouped by responsibility.

Group	Workers
Reasoning	agent-core llm-router council swarm directive mission
State	realm memory ledger vault context-manager context-cache
Coordination	orchestrator workflow hierarchy coordination task-decomposer
Execution	wasm-sandbox browser code-agent hand-runner lsp-tools
Safety	security security-headers security-map security-zeroize skill-security approval approval-tiers rate-limiter loop-guard
Surfaces	a2a a2a-cards mcp-client skillkit-bridge bridge streaming
Channels	channel-{bluesky,discord,email,linkedin,mastodon,matrix,reddit,signal,slack,teams,telegram,twitch,webex,whatsapp}
Telemetry	telemetry pulse session-lifecycle session-replay feedback eval evolve hashline hooks cron
Embeddings	embedding (Python)

Each worker ships iii.worker.yaml declaring its registry shape. CI validates conformance on every PR.

§ 07 · Sandbox surfaces

Two distinct namespaces, never overlap:

Namespace	Worker	Semantics
sandbox::*	builtin iii-sandbox (engine)	Ephemeral microVMs from OCI rootfs
wasm::*	agentos wasm-sandbox	wasmtime, fuel-metered, sub-millisecond cold start

CI's no sandbox::* clash with builtin job greps the workspace to enforce the boundary.

§ 08 · Layout

workers/         64 Rust + 1 Python (embedding)
crates/          cli, tui — surfaces (HTTP clients, not workers)
e2e/             vitest end-to-end suite (live engine + workers)
tests/           Rust integration tests
hands/           agent personas (TOML, consumed by hand-runner)
integrations/    MCP server configs (TOML, consumed by mcp-client)
agents/          agent templates
workflows/       workflow definitions (YAML)
plugin/          reusable agent/command/skill/hook bundles
config.yaml      iii engine boot config
website/         agentsos.sh — design.md aesthetic, three themes

See ARCHITECTURE.md for the full primitive flow and worker manifest spec.

§ 09 · Build and test

cargo build --workspace --release   # all 64 Rust workers
cargo test --workspace --release    # 1,281 tests
npm install && npm run test:e2e     # live engine + workers (requires AGENTOS_API_KEY)

§ 10 · Versioning

	version
iii engine	v0.11.6
iii-sdk (Rust)	pinned at =0.11.6 in workspace
iii-sdk (Node)	0.11.6 for the e2e harness
iii-sdk (Python)	>=0.11.6 for the embedding worker
agentos	0.0.1 — pre-1.0; reserved for behavioral proof against live infra, not feature completeness

§ 11 · License

Apache-2.0. Same family as iii-sdk and the rest of the iii ecosystem.