agentos

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.

§ 02 · Three primitives

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

§ 03 · Quickstart

# 1. install the iii engine binary
curl -fsSL https://install.iii.dev/iii/main/install.sh | sh

# 2. clone + add your model key (workers auto-load this on connect)
git clone https://github.com/iii-experimental/agentos && cd agentos
cp .env.example .env
$EDITOR .env   # set ANTHROPIC_API_KEY=sk-ant-…

# 3. build the workspace
cargo build --workspace --release

# 4. boot engine + workers (in two terminals, or one with `&`)
iii --config config.yaml &
bash scripts/dev-up.sh

# 5. open the chat
cargo run --release -p agentos-tui

Engine boots on port 49134. 64 Rust workers connect. 257 functions register. The TUI opens on Chat — type a message, hit Enter, the agent replies. /help shows the full keymap. Ctrl+W browses the worker catalog.

Prefer driving by HTTP? Same thing without the TUI:

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.

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

§ 07 · Sandbox surfaces

Two distinct namespaces, never overlap:

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 · TUI

Chat-first terminal UI lives in crates/tui:

cargo run --release -p agentos-tui

If the engine is offline or no workers are connected, the TUI shows a first-run overlay with copy-paste commands instead of an empty list. Slash completions pull from GET /iii/functions so anything a worker registers is immediately discoverable.

§ 10 · Build and test

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

§ 11 · Versioning

§ 12 · License

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