oxios-0.3.0 is not a library.

⬡ Oxios

Agent Operating System

Where AI agents don't just talk — they work.

Built with

Getting Started · Architecture · Core Concepts · CLI Reference · REST API · Ecosystem

Why Oxios?
Getting Started
Architecture
Core Concepts
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.

The Problem	What Oxios Does
Agents die when the chat closes	Supervisor manages agent lifecycle: fork, exec, wait, kill
No specification → unreliable output	Ouroboros: interview → seed → execute → evaluate → evolve
Every app reinvents browser/execution	Built-in engine: headless browser, host exec, MCP bridge, programs
Agents have no memory between sessions	Vector memory: persistent, searchable knowledge with semantic recall
No security boundary between agents	Access Manager: RBAC, path sandboxing, Merkle-chain audit trail
LLM provider outages cascade	Circuit Breaker: 3-state protection against cascading failures
No protocol for agent-to-agent work	A2A: Google's agent-to-agent protocol for horizontal communication

~52,000 lines of Rust. 179+ 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   │  │
│  │  programs · 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 11 typed APIs (Agent, Space, Security, Persona, Exec, Browser, MCP, Extension, Infra, A2A, State).

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 ◄────────────────────┘
│                                             │
└─────────────────────────────────────────────┘

Phase	What Happens
Interview	Agent asks clarifying questions to understand the task
Seed	Generates a formal specification (the "seed")
Execute	Implements the spec using available tools
Evaluate	Validates the output against the specification
Evolve	Refines the spec based on results, then loops

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.

📦 Programs

OS-level installable capabilities — like apps for the agent OS. Each program is a self-contained directory with metadata, dependencies, and instructions.

oxios pkg install ./my-program          # Install from directory
oxios pkg list                          # List installed programs
oxios pkg search                        # Detailed listing with descriptions
oxios program code-review               # View program details & SKILL.md

Built-in programs include: code-review, debug, deploy, guardian, refactor, and program-creator (a program that creates programs).

🧠 Vector Memory

Agents remember across sessions. The memory subsystem provides persistent, searchable knowledge:

Component	Purpose
TF-IDF Embeddings	Term-frequency based vector representations
HNSW Indexing	Fast approximate nearest-neighbor search
Reasoning Bank	Stores and retrieves agent reasoning chains
Semantic Search	Meaning-based recall, not just keyword matching
Budget-aware Curation	Evicts low-value memories when limits are reached

🗂️ 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:

Layer	Mechanism	Details
Tool Access	RBAC per agent	Capability-based permissions
File System	Workspace path sandboxing	Agents can't escape their workspace
Network	SSRF protection	Private IP blocking, robots.txt obedience
Execution	Command allowlist	`shell` mode (RBAC) and `structured` mode (binary allowlist + metacharacter blocking)
Audit	Merkle-chain audit trail	Tamper-evident, blake3-hashed, cryptographically linked entries
Identity	Authentication manager	Token-based identity verification for all API calls
Sandbox	WASM sandbox	Execute untrusted code in isolated WebAssembly environment

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:

Persona	Role
Dev	Software development, coding, implementation
Review	Code review, quality analysis, best practices
Research	Investigation, analysis, information gathering

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 program <name>     View program details & SKILL.md
oxios pkg                Package management (install, list, search)
oxios models             List available LLM models
oxios backup             Backup workspace
oxios restore            Restore from backup
oxios onboard            Re-run setup wizard
oxios reset              Reset workspace to defaults
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

Method	Endpoint	Description
`POST`	`/api/chat`	Send a message
`GET`	`/api/chat/stream`	WebSocket streaming

Agents

Method	Endpoint	Description
`GET`	`/api/agents`	List running agents
`POST`	`/api/agents/{id}/kill`	Kill an agent
`GET`	`/api/agent-groups`	List agent groups
`GET`	`/api/agent-groups/{id}`	Get group details

System

Method	Endpoint	Description
`GET`	`/health`	Health check (no auth)
`GET`	`/api/status`	System status
`GET`	`/api/config`	Get configuration
`PUT`	`/api/config`	Update configuration
`GET`	`/api/metrics`	Prometheus metrics

Workspace

Method	Endpoint	Description
`GET`	`/api/workspace/tree`	File tree
`GET`	`/api/workspace/file/{path}`	Read file
`PUT`	`/api/workspace/file/{path}`	Write file

Seeds & Skills

Method	Endpoint	Description
`GET`	`/api/seeds`	List seeds
`GET`	`/api/seeds/{id}`	Get seed details
`GET`	`/api/seeds/{id}/evolution`	Seed evolution history
`GET`	`/api/skills`	List skills
`GET`	`/api/skills/{name}`	Get skill details
`POST`	`/api/skills`	Create skill
`DELETE`	`/api/skills/{name}`	Delete skill

Memory

Method	Endpoint	Description
`GET`	`/api/memory`	List memories
`POST`	`/api/memory`	Create memory
`GET`	`/api/memory/{name}`	Get memory
`POST`	`/api/memory/search`	Keyword search
`POST`	`/api/memory/semantic`	Semantic search

Programs

Method	Endpoint	Description
`GET`	`/api/programs`	List programs
`POST`	`/api/programs`	Install program
`GET`	`/api/programs/{name}`	Get program details
`DELETE`	`/api/programs/{name}`	Uninstall program
`POST`	`/api/programs/{name}/enable`	Enable program
`POST`	`/api/programs/{name}/disable`	Disable program
`GET`	`/api/programs/{name}/host-requirements`	Check requirements
`GET`	`/api/host-tools`	Check host tool availability

Scheduler & Audit

Method	Endpoint	Description
`GET`	`/api/scheduler/stats`	Scheduler statistics
`GET`	`/api/scheduler/tasks`	List scheduled tasks
`GET`	`/api/audit/entries`	Audit log entries
`GET`	`/api/audit/verify`	Verify audit chain integrity
`GET`	`/api/audit/agent/{id}`	Audit entries by agent
`POST`	`/api/audit/export`	Export audit log
`POST`	`/api/audit/flush`	Flush audit log

Permissions

Method	Endpoint	Description
`GET`	`/api/permissions/{agent}`	Get agent permissions
`PUT`	`/api/permissions/{agent}`	Update agent permissions

Sessions & Events

Method	Endpoint	Description
`GET`	`/api/sessions`	List sessions
`GET`	`/api/sessions/{id}`	Get session details
`DELETE`	`/api/sessions/{id}`	Delete session
`GET`	`/api/events`	SSE event stream

Personas

Method	Endpoint	Description
`GET`	`/api/personas`	List personas
`POST`	`/api/personas`	Create persona
`GET`	`/api/personas/{id}`	Get persona
`PUT`	`/api/personas/{id}`	Update persona
`DELETE`	`/api/personas/{id}`	Delete persona
`GET`	`/api/personas/active`	Get active persona
`PUT`	`/api/personas/active`	Set active persona

Cron Jobs

Method	Endpoint	Description
`GET`	`/api/cron-jobs`	List cron jobs
`POST`	`/api/cron-jobs`	Create cron job
`GET`	`/api/cron-jobs/{id}`	Get cron job
`DELETE`	`/api/cron-jobs/{id}`	Delete cron job
`POST`	`/api/cron-jobs/{id}/edit`	Edit cron job
`POST`	`/api/cron-jobs/{id}/trigger`	Trigger cron job

Approvals (Human-in-the-Loop)

Method	Endpoint	Description
`GET`	`/api/approvals`	List pending approvals
`POST`	`/api/approvals/{id}/approve`	Approve request
`POST`	`/api/approvals/{id}/reject`	Reject request

Git

Method	Endpoint	Description
`GET`	`/api/git/log`	Commit log
`GET`	`/api/git/tags`	List tags
`POST`	`/api/git/verify`	Verify repository integrity
`POST`	`/api/git/restore`	Restore from commit

Budget

Method	Endpoint	Description
`GET`	`/api/budget/{agent_id}`	Get agent budget
`POST`	`/api/budget/{agent_id}`	Set agent budget
`DELETE`	`/api/budget/{agent_id}`	Remove agent budget
`POST`	`/api/budget/{agent_id}/reserve`	Reserve budget
`POST`	`/api/budget/{agent_id}/reset`	Reset budget

Resources

Method	Endpoint	Description
`GET`	`/api/resources`	Current resource snapshot
`GET`	`/api/resources/history`	Historical resource usage
`GET`	`/api/resources/overload`	Check overload status

Project Structure

oxios/                          # Main binary (src/main.rs)
├── crates/
│   ├── oxios-kernel/           # Core: supervisor, scheduler, event bus, state store, tools, memory
│   ├── oxios-ouroboros/        # Spec-first protocol (interview → seed → execute → evaluate → evolve)
│   └── oxios-gateway/          # Channel-agnostic message hub
├── channels/
│   ├── oxios-web/              # Web dashboard (Axum backend + Dioxus/WASM frontend)
│   ├── oxios-cli/              # CLI channel
│   └── oxios-telegram/         # Telegram channel
├── .programs/                  # Built-in programs (code-review, debug, deploy, guardian, refactor, program-creator)
├── share/                      # Default skills, programs, config
└── docs/                       # Architecture docs, RFCs, design documents

Dependency graph:

oxios ──► oxios-kernel ──► oxi-sdk (crates.io)
                       ──► oxi-ai (provider construction)
                       ──► oxios-ouroboros
      ──► oxios-gateway
      ──► oxios-web / oxios-cli / oxios-telegram (feature-gated channels)

File locations:

Path	Purpose
`~/.oxios/`	Oxios home directory
`~/.oxios/config.toml`	Main configuration
`~/.oxios/workspace/`	Agent working directory
`~/.oxios/workspace/sessions/`	Session data
`~/.oxios/workspace/seeds/`	Ouroboros seed specifications
`~/.oxios/workspace/programs/`	Installed programs
`~/.oxios/workspace/skills/`	Skill definitions

Ecosystem

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

Project	Purpose
oxi	LLM engine + agent runtime (multi-provider, tool-calling loop)
oxibrowser	Pure Rust headless browser (~10MB, no Chromium)
ouroboros	Specification-first agent framework
oxios	Agent Operating System (you are here)

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

Built by a7garden

oxios 0.3.0