Table of Contents

• Why Oxios?
• Getting Started
• Architecture
• Core Concepts
  • Ouroboros Protocol
  • Supervisor
  • Scheduler
  • Built-in Browser
  • Skills
  • Vector Memory
  • Spaces
  • Security Model
  • MCP & A2A
  • Persona System
  • Circuit Breaker
  • Git Integration
  • Cron Scheduler
  • Budget Manager
  • Resource Monitor
• CLI Reference
• REST API
• Project Structure
• Ecosystem
• Contributing
• License

Why Oxios?

Large language models are powerful, but they're stuck in chat boxes. Oxios gives them an operating system — lifecycle management, tool execution, state persistence, security boundaries, and an orchestration protocol — so agents can autonomously complete real tasks.

~67,000 lines of Rust. 196+ source files. Zero containers. Zero subprocess browsers. Everything runs in-process.

Getting Started

Install

cargo install oxios

Configure

Set your LLM provider key:

# Anthropic (Claude)
export ANTHROPIC_API_KEY=sk-ant-...

# or OpenAI (GPT)
export OPENAI_API_KEY=sk-...

On first run, Oxios launches an interactive setup wizard to configure your workspace, credentials, and preferences.

Run

oxios                    # Start the daemon (background by default)
oxios --foreground       # Run in foreground (for debugging)

Open http://127.0.0.1:4200 — start talking to your agent.

Quick Commands

oxios run --json "review this code"        # Single-shot with JSON output
oxios chat                                 # Interactive chat session
oxios status                               # Check daemon status
oxios doctor                               # Diagnose configuration issues
oxios models                               # List available LLM models

That's it. The OS handles the rest.

Architecture

┌───────────────────── Channels ─────────────────────┐
│                                                     │
│   Web (Axum)  ·  CLI  ·  Telegram  ·  Discord  …   │
│              (plugin-based, feature-gated)           │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│                    Gateway                           │
│          Channel-agnostic message hub                │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│                    Kernel                            │
│                                                      │
│  ┌─────────────┐ ┌──────────────┐ ┌──────────────┐  │
│  │  Supervisor  │ │  Ouroboros   │ │  Scheduler   │  │
│  │ fork/exec/   │ │  Orchestrator│ │ Priority queue│  │
│  │ wait/kill    │ │  (protocol)  │ │ (AIOS-style) │  │
│  └─────────────┘ └──────────────┘ └──────────────┘  │
│                                                      │
│  ┌─────────────┐ ┌──────────────┐ ┌──────────────┐  │
│  │   Memory     │ │ Access Mgr   │ │  AuditTrail  │  │
│  │ Vector store │ │ RBAC + paths │ │ Merkle-chain │  │
│  │ HNSW + TF-IDF│ │ + sandboxing │ │ (blake3)     │  │
│  └─────────────┘ └──────────────┘ └──────────────┘  │
│                                                      │
│  ┌─────────────┐ ┌──────────────┐ ┌──────────────┐  │
│  │    Budget    │ │    Cron      │ │  Resource    │  │
│  │ Token/cost   │ │  Scheduler   │ │   Monitor    │  │
│  │ enforcement  │ │  (jobs)      │ │  (system)    │  │
│  └─────────────┘ └──────────────┘ └──────────────┘  │
│                                                      │
│  ┌────────────────────────────────────────────────┐  │
│  │              Agent Runtime                      │  │
│  │  oxi-agent + oxi-ai (multi-provider)            │  │
│  │  read · write · edit · bash · grep · browser   │  │
│  │  skills · MCP · memory · A2A · git             │  │
│  └────────────────────────────────────────────────┘  │
│                                                      │
│  ┌─────────────┐ ┌──────────────┐ ┌──────────────┐  │
│  │OxiBrowser   │ │  GitLayer    │ │ CircuitBreaker│  │
│  │In-process   │ │  (gix)       │ │ 3-state LLM  │  │
│  │~10MB        │ │  version ctrl│ │  protection  │  │
│  └─────────────┘ └──────────────┘ └──────────────┘  │
└──────────────────────────────────────────────────────┘
         │
    ┌────▼────┐
    │  Host   │
    │  Exec   │
    └─────────┘

No containers. No subprocess browser. Everything runs in-process, sandboxed by workspace rules and RBAC. The kernel exposes all functionality through KernelHandle — a facade with typed APIs (Agent, Space, Security, Persona, Exec, Browser, MCP, Extension, Infra, A2A, State, KnowledgeBase, KnowledgeLens).

Core Concepts

🔄 Ouroboros Protocol

Powered by the Ouroboros specification framework. Agents never execute blindly — every task starts with a specification that evolves through cycles.

┌─────────────────────────────────────────────┐
│                                             │
│  Interview ──► Seed ──► Execute ──► Evaluate│
│       ▲                            │        │
│       │                            ▼        │
│       └──────── Evolve ◄────────────────────┘
│                                             │
└─────────────────────────────────────────────┘

The Ouroboros protocol is the heart of Oxios. It ensures agents produce reliable, spec-driven output rather than improvising solutions.

🧭 Supervisor

Agent lifecycle as Unix-style process management. The Supervisor is the "init" of Oxios — it manages the full lifecycle of every agent process.

fork() → register(A2A) → check_permissions() → schedule() → run() → cleanup()

Operations: fork, exec, wait, kill. The AgentLifecycleManager orchestrates the complete flow from agent creation through A2A registration, permission checks, scheduling, execution, and cleanup.

📊 Scheduler

Priority-based task queue inspired by AIOS and AgentRM. Features:

• Rate-limit-aware admission control
• Zombie agent detection and cleanup
• Maximum concurrent agent enforcement
• Priority-based scheduling for multi-agent workloads

🌐 Built-in Browser

OxiBrowser — a pure Rust headless browser running in-process. ~10MB memory footprint. No Chromium. No CDP overhead.

"Read this URL"    →  browse(url)              →  Markdown (one-shot)
"Fill this form"   →  goto → click → type      →  Interactive tab session
"Run this JS"      →  evaluate(code)            →  JSON result
"Extract data"     →  extract(selector)         →  Structured output

Agents can browse the web, fill forms, extract data, and execute JavaScript — all without leaving the process.

🛠️ Skills

Unified skill system — every capability is a SKILL.md with YAML frontmatter. Skills unify the former Programs and Skills concepts, providing a single model for agent instructions with requirements, install specs, and invocation policy.

---
name: code-review
description: Deep code review with quality domain analysis
requires:
  bins: ["git"]
  env: ["GITHUB_TOKEN"]
install:
  - kind: brew
    formula: git
---

Skill sources (highest to lowest priority): agent-specific → workspace → global user → bundled. Built-in bundled skills include: code-review, debug, and refactor.

🧠 Tiered Memory

Agents remember across sessions with a 3-tier memory system (Hot/Warm/Cold) and automatic Dream-time consolidation:

🗂️ Spaces

Conversation context management with intelligent auto-detection:

• Space Manager — CRUD for conversation contexts
• Conversation Buffer — Manages context window and history
• Knowledge Bridge — Auto-extracts knowledge from conversations
• Detection — Intent classification for automatic space routing

Spaces let agents maintain focused, topic-specific conversations without cross-contamination.

🔒 Security Model

Defense in depth — multiple security layers working together:

The AccessManager follows OWASP-inspired least-privilege principles. Every tool call passes through permission checks.

🔌 MCP & A2A

MCP (Model Context Protocol) — Connect to external tool servers using Anthropic's open protocol. Oxios includes a full MCP client, protocol handler, and server integration.

A2A (Agent-to-Agent) — Google's protocol for inter-agent communication. Agents can discover, negotiate, and collaborate with each other horizontally — no central orchestrator required.

🎭 Persona System

Multiple AI characters, each with their own personality and expertise:

Personas are fully customizable — create your own via the API or CLI.

⚡ Circuit Breaker

3-state protection against LLM provider failures:

Closed ──(errors exceed threshold)──► Open ──(timeout)──► Half-Open
   ▲                                    │                    │
   └──────(success)─────────────────────┘◄──(probe)─────────┘

Prevents cascading failures when an LLM provider goes down. Automatically recovers via probing.

🔧 Git Integration

In-process version control powered by gix:

• Commits, logs, tags, restore
• No external git binary required
• All operations run in-process
• Workspace changes are tracked automatically

⏰ Cron Scheduler

Scheduled job execution with persistent state:

# Cron jobs are managed via config.toml and API
oxios config show                         # View cron config section
curl http://127.0.0.1:4200/api/cron-jobs   # List scheduled jobs

💰 Budget Manager

Token and cost budget enforcement per agent:

• Set spending limits per agent
• Reserve budget before expensive operations
• Automatic enforcement and reset
• Prevent runaway API costs

📈 Resource Monitor

System resource tracking for agent budget enforcement:

• CPU and memory snapshots
• Historical resource usage
• Overload detection

CLI Reference

oxios                    Start the daemon (background by default)
oxios start              Start the daemon
oxios stop               Stop the daemon
oxios restart            Restart the daemon
oxios status             Show daemon status
oxios doctor             Diagnose configuration issues
oxios run <prompt>       Single-shot execution
oxios chat <prompt>      Interactive chat session
oxios config             View/edit configuration
oxios pkg                Package management
oxios agent              Agent management
oxios audit              Audit trail inspection
oxios git                Git operations (log, tags, restore, verify)
oxios budget             Budget management
oxios daemon             Daemon management (install as system service)
oxios log                View logs
oxios skill <name>       View skill details & SKILL.md
oxios skills             List all skills with eligibility status
oxios models             List available LLM models
oxios backup             Backup workspace
oxios restore            Restore from backup
oxios onboard            Re-run setup wizard
oxios reset              Reset all Oxios data (config, workspace, credentials, services)
                            Prompts for confirmation and shows what will be deleted before proceeding
oxios completion         Generate shell completions

Programmatic Usage

oxios run is designed for scripts and agents:

# JSON output — parse response, session_id, evaluation status
oxios run --json "review this code"

# Pass file as context (stdin)
cat file.rs | oxios run --json --context-file - "describe this"

# Exit codes for CI: 0=passed, 1=failed
oxios run --exit-code --json "run all tests"
echo $?

# Multi-turn sessions
SID=$(oxios run --json "initial prompt" | jq -r '.session_id')
oxios run --json --session "$SID" "follow-up question"

JSON output shape:

{
  "response": "...",
  "session_id": "uuid",
  "space_id": "uuid | null",
  "space_tag": "[emoji label] | null",
  "seed_id": "uuid | null",
  "agent_id": "uuid | null",
  "phase_reached": "Execute",
  "evaluation_passed": true,
  "exit_code": 0,
  "duration_ms": 3500
}

REST API

Full REST API on port 4200 with 76 endpoints. Auth middleware on all /api/* routes.

Chat & Streaming

Agents

System

Workspace

Seeds & Skills

Memory

Skills

Scheduler & Audit

Permissions

Sessions & Events

Personas

Cron Jobs

Approvals (Human-in-the-Loop)

Git

Budget

Resources

Project Structure

oxios/                          # Main binary (src/main.rs)
├── crates/
│   ├── oxios-kernel/           # Core: supervisor, scheduler, event bus, state store, tools, tiered memory
│   ├── oxios-ouroboros/        # Spec-first protocol (interview → seed → execute → evaluate → evolve)
│   ├── oxios-markdown/         # Knowledge base (VirtualFs, BacklinkIndex)
│   ├── oxios-gateway/          # Channel-agnostic message hub
│   ├── oxios-mcp/              # MCP client (JSON-RPC 2.0 over stdio)
│   ├── oxios-memory/           # Tiered agent memory (Hot/Warm/Cold, Dream, HNSW, hyperbolic)
│   └── oxios-calendar/         # .ics-based calendar event management
├── surface/oxios-web/          # Web dashboard (Axum backend + React frontend)
├── channels/
│   ├── oxios-cli/              # CLI channel
│   └── oxios-telegram/         # Telegram channel
├── share/                      # Default skills, config, migration scripts
└── docs/                       # Architecture docs, RFCs, design documents

Dependency graph:

oxios ──► oxios-kernel ──► oxios-memory
                       ──► oxios-ouroboros
                       ──► oxios-markdown
                       ──► oxios-calendar
                       ──► oxios-mcp
                       ──► oxi-sdk (crates.io)
      ──► oxios-calendar
      ──► oxios-gateway ──► oxios-kernel
      ──► oxios-web / oxios-cli / oxios-telegram (feature-gated channels)
                                 └──► oxios-gateway

File locations:

Ecosystem

Oxios is part of the a7garden Rust AI stack — a collection of focused crates that compose into a complete agent platform:

Layered architecture:

oxi-ai ──── LLM abstraction (multi-provider: Anthropic, OpenAI, ...)
oxi-agent ── Tool-calling agent loop
  │
ouroboros ── Specification-first protocol
  │
oxios-kernel ── Supervisor, scheduler, tools, state, security, memory
  │
oxios ── Binary + channels (Web, CLI, Telegram, ...)

Contributing

Contributions are welcome! The project follows these conventions:

• Language: Code, comments, docs, commits — English
• Rust: #![warn(missing_docs)] on public crates. anyhow for apps, thiserror for libs
• Testing: cargo test --workspace must pass at every commit
• Commits: <type>(<scope>): <description> — scopes: kernel, ouroboros, gateway, web, cli, docs
• CI: GitHub Actions (macOS-latest, fmt + clippy + test + audit)

See AGENTS.md for detailed onboarding documentation.

License

MIT · Third-Party Notices