AgentOS

Replay any AI agent run — offline, deterministically, for $0.00.

Runtime infrastructure for AI agents: supervision, journaling, deterministic replay, and time-travel debugging. Written in Rust.

---

Your agent did something wrong on step 7. Reproducing it costs real API calls, and it never behaves the same way twice.

agentOS run --agent my_agent.toml     # every step is journaled as it happens
agentOS replay --session agent_123    # re-run it offline: no API key, no cost
agentOS fork --from ckpt_4 --prompt "try the other path"

That is the idea. Everything else in this repository exists to make those three commands trustworthy.

Why this is not another agent framework

• Frameworks help you build a workflow. AgentOS handles what happens after it has to run as a long-lived process: fail clearly, restart carefully, and be inspected after the fact.
• Every LLM exchange and tool result is journaled at the provider boundary, so a replay is a real re-execution against recorded responses — not a log viewer.
• It sits underneath LangGraph, AutoGen, CrewAI, or your own agent loop. It does not replace them.

Created and maintained by WAHIB EL KHADIRI — founder and architect.

See it run

Real output from a fresh clone — no API key required to bring the runtime up:

$ cargo run -p agentos-cli -- run --agent examples/simple_agent.toml

INFO agentos_kernel::supervisor: agent spawned and running agent_id=agent_simple_agent state=Running name=simple-agent
INFO agentos_kernel::agent: agent loop started agent_id=agent_simple_agent
INFO agentos_kernel::events: system event emitted event=agent.spawned seq=0
INFO agentOS::run: AgentOS runtime started agent_id=agent_simple_agent host=127.0.0.1 http_port=8080 grpc_port=50051 sse_port=8081
INFO agentos_kernel::health: health server listening on 127.0.0.1:8080
INFO agentos_bus::grpc: gRPC bus server listening on 127.0.0.1:50051
INFO agentos_bus::grpc: SSE event stream listening on http://127.0.0.1:8081/events

AgentOS runtime is live
  http:       127.0.0.1:8080
  grpc:       127.0.0.1:50051
  sse:        http://127.0.0.1:8081/events
  auth:       open (set AGENTOS_API_TOKEN to protect)
  vault:      in-memory only (set AGENTOS_VAULT_KEY to persist)
  agent id:   agent_simple_agent
  status:     running
  trace:      294dab79-e626-4e42-97ad-8deee2c43e18
  (press Ctrl+C to stop)

One process gives you a supervised agent, a health endpoint, a gRPC message bus, a live SSE event stream, and a recorded trace you can replay later.

Time-Travel Debugging

Your agent did something weird on step 7. Reproducing it costs real API calls — and never behaves the same twice. AgentOS journals every LLM exchange and tool result at the provider boundary, so any run can be replayed deterministically:

agentOS run --agent my_agent.toml     # every execution step is journaled automatically
agentOS replay --session agent_123    # re-run offline: no API key, no cost, drift-checked

Branching a checkpoint into an alternate timeline is the next step on this path. The journal already records per-exchange checkpoints as fork anchors, but agentOS fork is currently a placeholder: it reports that forking is not implemented yet.

The dashboard's Recordings view turns journals into a scrubbable timeline: step through the prompt, every exchange, tool calls and their results exactly as they happened, with per-exchange checkpoints as fork anchors.

What AgentOS Is

• A Rust-first runtime layer for agent processes.
• A CLI-first developer workflow for running, listing, logging, tracing, and replaying agents.
• A supervision, bus, state, trace, vault, registry, and dashboard codebase.
• A place to make agent behavior more observable and reproducible.
• Infrastructure that can sit underneath LangGraph, AutoGen, CrewAI, custom agents, and other agent frameworks.

What AgentOS Is Not

• Not another prompt framework.
• Not a chatbot UI.
• Not a replacement for LangGraph, AutoGen, CrewAI, or Semantic Kernel.
• Not a production-hardened distributed control plane yet.
• Not a project that should claim recovery, replay, or security guarantees without tests and reproducible demos.

Official Demo

The official local demo flow is:

run -> ps -> logs -> trace -> replay

Start with:

• Demo guide: docs/demo.md
• Demo config: .agentos/demo/agentos.demo.toml
• Demo script: scripts/demo.sh

Smoke-check the demo without inventing output:

bash scripts/demo.sh --check

Quick Start

The most reliable path during early development is building from source:

git clone https://github.com/WAHIB-EL-KHADIRI/agentOS
cd agentOS
cargo build --workspace
cargo run -p agentos-cli -- run --agent examples/simple_agent.toml

Prebuilt binaries ship with the tagged alpha releases (Linux x64/arm64, macOS Intel/Apple Silicon, Windows). Alpha releases are GitHub prereleases, so pin the tag when using the one-liner installers:

# Linux / macOS
AGENTOS_VERSION=v0.1.0-alpha.3 curl -fsSL https://raw.githubusercontent.com/WAHIB-EL-KHADIRI/AgentOS/main/install.sh | sh

# Windows
$env:AGENTOS_VERSION="v0.1.0-alpha.3"; iwr -useb https://raw.githubusercontent.com/WAHIB-EL-KHADIRI/AgentOS/main/install.ps1 | iex

Building from source remains the most reliable path for contributors.

Current Status

AgentOS is active infrastructure work. It has a working local runtime and developer workflow, but it is not claiming to be a production-hardened platform.

Stable enough to use locally:

• CLI flows for run, ps, logs, trace, and replay.
• Rust workspace checks and tests.
• Local state inspection, export, import, and cleanup flows.
• Core crates for kernel, bus, trace, memory, vault, registry, SDK, and CLI.
• SSE event stream started by agentOS run (default 127.0.0.1:8081/events) feeding the dashboard live agent and trace events.
• Demo smoke checks that reject known fake-output fallback patterns.

Experimental:

• Dashboard as a live debugging surface.
• WASM plugin runtime and plugin templates.
• Docker Compose packaging.
• LLM provider integrations.
• LLM tool execution loop: tools registered through the SDK are executed when the model requests them, with every call and result recorded as trace checkpoints, logs, and live dashboard events (capped rounds, provider-agnostic result passing).
• Deterministic session replay: every execution step is journaled (LLM exchanges + tool results); agentOS replay --session <agent_id> re-executes it with recorded responses (no API key needed) and reports drift.
• Dashboard Recordings view: a time-travel scrubber over recorded sessions (slider and step controls across the prompt, exchanges, tool calls and results, with per-exchange checkpoints shown as fork anchors).
• Python and TypeScript SDK packaging.
• Marketplace commands and plugin distribution ideas.

Planned or still being hardened:

• Stronger restart and recovery guarantees with explicit tests.
• Trace forking: replaying a prefix from a checkpoint, then continuing live. agentOS fork exists as a command but reports that this is not implemented yet.
• Dashboard diff view between an original run and its forks.
• Published SDK packages.
• More integration examples for existing agent frameworks.

Architecture

flowchart TD
    subgraph Clients["Entry points"]
        CLI["CLI - crates/cli"]
        SDK["Rust SDK - crates/sdk"]
        DASH["React Dashboard"]
    end
    Clients -->|"HTTP / gRPC / SSE / WS"| KERNEL

    subgraph Runtime["AgentOS Runtime"]
        KERNEL["Kernel + Supervisor<br/>lifecycle / restart / health"]
        BUS["Message Bus<br/>in-mem / gRPC / SSE / WS"]
        TRACE["Trace<br/>record / replay / diff / checkpoint"]
        VAULT["Vault<br/>secrets / encryption / scopes / audit"]
        MEM["Memory<br/>store / embeddings"]
        REG["Registry<br/>discovery / health"]
        LLM["LLM<br/>provider abstractions"]
    end

    KERNEL --> BUS
    KERNEL --> VAULT
    KERNEL --> REG
    KERNEL --> TRACE
    BUS <--> AGENTS["Agents and Tools"]
    AGENTS --> MEM
    AGENTS --> LLM
    TRACE -.->|"time-travel replay"| KERNEL

Loading

Repository layout:

crates/kernel      lifecycle, agent handles, supervisor, system integration
crates/bus         in-memory, gRPC, SSE, and WebSocket messaging
crates/trace       recording, replay, diff, and checkpoint model
crates/memory      memory store and embedding abstraction
crates/vault       secret isolation, encryption, scopes, and audit
crates/registry    service discovery and health metadata
crates/llm         provider abstractions
crates/cli         agentOS command-line interface
crates/sdk         Rust SDK
dashboard/         React dashboard
docs/              architecture, CLI, security, demo, and contributor docs
scripts/           check.sh, check.ps1, and demo scripts

Read the deeper architecture guide: docs/architecture.md

CLI Shape

Common commands:

agentOS run --agent my_agent.toml
agentOS ps
agentOS logs --id agent_123
agentOS trace --id agent_123
agentOS replay --session agent_123
agentOS fork --from ckpt_456 --prompt "explore the alternative"   # placeholder, see above
agentOS status
agentOS doctor
agentOS repl
agentOS dev --path examples

See the full CLI reference: docs/cli-reference.md

Development

cargo fmt --all --check
cargo check --workspace
cargo test --workspace
cargo check --workspace --benches
bash scripts/demo.sh --check

Or run the unified check:

# Linux / macOS
bash scripts/check.sh

# Windows PowerShell
powershell -File scripts/check.ps1

Design Principles

• Runtime first: AgentOS is infrastructure, not a prompt framework.
• Lifecycle correctness before feature volume.
• Replayability and observability over opaque success claims.
• Honest demos over polished fake output.
• Interop over lock-in.
• Small crates with clear ownership.

Contributing

Start here:

• CONTRIBUTING.md
• AGENTS.md
• docs/ai-development.md
• docs/contributor-map.md
• docs/issue-roadmap.md

Good first areas include docs, CLI polish, demo reliability, focused tests, dashboard inspection views, and SDK examples.

Before opening a large PR, open an issue or discussion so the design can be aligned with the roadmap.

Documentation

• Project overview: PROJECT_OVERVIEW.md
• Demo: docs/demo.md
• Architecture: docs/architecture.md
• Runtime walkthrough: docs/runtime-walkthrough.md
• Security model: docs/security-model.md
• Trace replay debugging: docs/time-travel-debugging.md
• Glossary: docs/project-glossary.md
• Pitch: docs/pitch.md
• Roadmap: ROADMAP.md

Ownership

AgentOS was created and is led by WAHIB EL KHADIRI. Contributions are welcome and credited, while the project identity and technical direction remain stewarded by WAHIB EL KHADIRI.

Read more: FOUNDER.md

Ownership and trademark

AgentOS was created, designed, and is maintained by WAHIB EL KHADIRI. Authorship and copyright of the original work stay with the author; see AUTHORS, NOTICE, and FOUNDER.md.

The code is open source. The name is not. The marks AgentOS and agentOS, the project identity, and the associated branding are reserved by the author and are not granted by the MIT or Apache-2.0 licence. Those licences cover copyright and patents — never trademarks (see Apache-2.0 §6).

This means anyone may use, fork, and build on the code, including commercially. Nobody may present a fork, product, or service as AgentOS, imply it is the official project, or use the name in a way that suggests endorsement by the author. For any use of the name beyond plain factual reference ("built on AgentOS"), ask first.

Contributions are accepted under the project's licence terms (CONTRIBUTING.md), which keeps the licensing history of the project clean and under the maintainer's control.

License

Licensed under either of:

• MIT License
• Apache License, Version 2.0

at your option.

Copyright (c) 2026 WAHIB EL KHADIRI and contributors.