R-AI-OS Kernel

  ╔═╗ ══════════════════════════════════════════ ╔═╗
  ║ ╚╗                                          ╔╝ ║
  ╚═╗║         ▄█████████████▄                  ║╔═╝
    ║║      ▄█▀  ┌─────────┐  ▀█▄               ║║
    ║║   ▄█▀  ───│   · │ · │───  ▀█▄            ║║
    ║║   █ ─────│   │ R │  │ ───── █           ║║
    ║║   ▀█▄  ───│   · │ · │───  ▄█▀            ║║
    ║║      ▀█▄  └─────────┘  ▄█▀               ║║
  ╔═╝║         ▀█████████████▀                  ║╚═╗
  ║ ╔╝   · · ·   R - A I - O S   KERNEL  v2.0   ╚╗ ║
  ╚═╝ ══════════════════════════════════════════ ╚═╝

A Hardened, LLM-Native OS Kernel for Autonomous Agent Swarms

Vision • Security • Protocols • Modules • VS Code • Quick Start • CLI • Roadmap

---

🔭 The Vision

R-AI-OS is not a CLI tool — it is a Kernel. While traditional operating systems manage hardware, R-AI-OS manages the AI layer: a decentralized swarm of 90+ autonomous specialists running across Claude Code, Gemini CLI, and any MCP-compatible agent.

It solves the fundamental problem of unsupervised agent execution: agents that run unchecked can leak secrets, corrupt files, and make unauthorized network calls. R-AI-OS sits between the human and the swarm as a hardened control plane — enforcing policies, auditing every action, and managing context economics.

Human → [ R-AI-OS Kernel ] → Agent Swarm (Claude / Gemini / MCP)
              ↓
    ┌──────────────────────────────────────────────┐
    │  Security Kernel  │  Cortex  │  Swarm Mesh  │
    │  Policy Gate      │  BM25+V  │  Lock Mgr    │
    │  Audit Ledger     │  Sigmap  │  Factory Mode│
    └──────────────────────────────────────────────┘
         ↓ TCP :42069   ↓ MCP :42070   ↓ HTTP :42071

---

🛡️ Security Kernel

The Security Kernel is the core of R-AI-OS. It enforces a zero-trust model for all agent tool calls: every action is policy-gated, logged, and auditable. All 4 phases are implemented and tested.

Architecture

src/security/
├── sandbox.rs       # Phase 1 — Filesystem Jail (canonicalize + boundary)
├── policy.rs        # Phase 2 — Policy Manager (TOML allow/deny/confirm)
├── verify_chain.rs  # Phase 3 — Audit Chain (SHA-256 hash-chained SQLite)
└── egress.rs        # Phase 4 — Egress Filter (domain allowlist, fail-closed)

Phase 1 — Filesystem Jail

Prevents agents from reading or writing outside their designated workspace boundary. Uses path canonicalization to defeat traversal attacks.

# raios-policy.toml
[sandbox]
enabled = true
workspace_root = "/home/user/projects/my-app"

Phase 2 — Policy Manager

Every MCP tool call passes through a policy gate before execution. Rules are defined in raios-policy.toml and evaluated in order. Fail-closed by design: confirm rules in headless mode deny without an interactive prompt.

[tools]
default = "allow"

[[tools.rules]]
tool = "bash"
action = "confirm"   # requires human approval

[[tools.rules]]
tool = "write_file"
path_glob = "/etc/**"
action = "deny"

Phase 3 — Audit Chain

Every allow/deny decision is written to a tamper-evident, SHA-256 hash-chained SQLite ledger. Each entry links to the previous entry's hash — any tampering is immediately detectable.

raios verify-chain          # verify full chain integrity
raios verify-chain -n 50    # show last 50 entries then verify

Phase 4 — Egress Filter

Domain-level allowlist/blocklist for HTTP/HTTPS calls made via MCP tools. Fail-closed: unrecognized domains are denied unless explicitly allowed.

[egress]
mode = "allowlist"
allowed = ["api.anthropic.com", "api.openai.com", "*.github.com"]

Redaction Engine

Automatically masks sensitive values (API keys, GCP secrets, PII patterns) before they appear in logs or telemetry. Built on regex with 20+ detection patterns.

Session Token Auth

All HTTP API calls require a Bearer token stored in the OS config directory under raios/.session_token (SHA-256, 8h TTL). The Host header is additionally validated to block DNS rebinding attacks.

---

🔌 Tri-Protocol Interface

All three protocols share one event bus and one security kernel:

Protocol	Port	Purpose
Daemon TCP	:42069	IPC between CLI and background daemon — UUID token auth, mandatory handshake
MCP-over-TCP	:42070	Agent tool calls — policy-gated, every call logged to audit ledger
HTTP / WebSocket	:42071	VS Code extension + external integrations — Bearer auth + Host validation

HTTP API Endpoints

Method	Path	Description
GET	/api/health	Daemon health + active agent count
GET	/api/projects	All tracked projects from DaemonState
GET	/api/tasks	Tasks from SQLite (grouped by project)
GET	/api/usage	Local usage/quota signals for Codex, Claude, Gemini, Antigravity
GET	/api/plans	Plans from docs/superpowers/plans/*.md with checkbox progress
GET	/api/git-status?path=<dir>	Git branch + dirty/staged/modified/untracked for a workspace
GET	/api/swarm	Active (non-terminal) swarm tasks
POST	/api/approve	Approve a swarm task (merge branch) or pending diff (write file)
GET	/api/stream	WebSocket — real-time kernel event stream

---

🧠 Core Modules

📉 Cortex — Token Budgeter & Context Manager

• Sigmap: Up to 97% token reduction via high-density signature mapping (SIGMAP.md)
• BM25 persistence: Index survives restarts via mtime-based invalidation
• Vector store: Binary SQLite BLOBs — transaction-safe, no JSON drift
• Session memory: Per-agent memory.md auto-append

🎯 Unified Agent Router

Maps natural-language task descriptions to the right specialist using local BM25 + vector hybrid indexing. Bridges Maestro (39 agents) and ECC (48 agents) ecosystems natively.

🔄 Agent Swarm Mesh

Parallel worktree-based agent execution with coordination primitives:

• SwarmStore: SQLite-backed task registry. States: Initializing → Running → AwaitingReview → Merged / Rejected / Failed
• Lock Manager: File and task-level locks with priority levels (User > Agent > Automation)
• Radar Whispers: Real-time context hints pushed to all connected agents
• Factory Mode: Submit heavy jobs async; completion fires broadcast + optional webhook

📊 Portfolio Intelligence

• Neural Search: Semantic search across 140+ projects with BM25 + embeddings
• Health Scanner: Background scan for memory.md compliance, security leaks, git drift
• GitHub Sync: Live star counts and last-commit timestamps
• Auto-Discovery: Detects new workspace directories and updates entities.json

---

🖥️ VS Code Extension (v0.5.1)

R-AI-OS ships a native VS Code extension that turns the IDE into a Hybrid UI — the control panel for your agent swarm directly in your sidebar.

vscode-extension/
├── src/
│   ├── extension.ts              # Activation + provider wiring
│   ├── ipc/
│   │   ├── DaemonClient.ts       # TCP :42069 connection
│   │   ├── TokenBridge.ts        # Session token proxy (XSS-safe)
│   │   └── DaemonManager.ts      # Auto-spawn aiosd, poll token file
│   └── providers/
│       ├── SidebarProvider.ts    # Main WebviewView control panel
│       ├── StatusBarProvider.ts  # Live daemon indicator
│       ├── DiagnosticProvider.ts # File-save security scan
│       ├── RefactorProvider.ts   # Refactor surface analysis
│       └── DiffInboxProvider.ts  # Pending diff approvals

Control Panel Cards

Card	Source	Features
Git Status	/api/git-status	Branch name, dirty/clean badge, staged/modified/untracked counts
Plans	/api/plans	Live progress bars per plan file, status chips
Tasks	/api/tasks	Grouped by project, inline completion indicators
Swarm	/api/swarm	Active agent tasks, status dots, inline Approve button for awaiting_review
Quick Actions	Extension host	cargo build and cargo test via VS Code terminal

Security Properties

• TokenBridge proxy: The session token never enters the Webview context — all API calls go through the extension host. XSS in the webview cannot exfiltrate the token.
• Auto-spawn: DaemonManager starts aiosd automatically if the socket isn't listening. Polls the token file and triggers sidebar refresh when ready.
• Host validation: All HTTP calls include the Host: localhost header, enforced by the Axum auth middleware.

Install

# From packaged VSIX
code --install-extension vscode-extension/raios-0.5.1.vsix

# Or build from source
cd vscode-extension && npm run compile && vsce package
code --install-extension raios-*.vsix

Keyboard shortcuts:

Action	Windows / Linux	macOS
Security Scan	Ctrl+Shift+R S	Cmd+Shift+R S
Health Check	Ctrl+Shift+R H	Cmd+Shift+R H
Scan Current File	Ctrl+Shift+R F	Cmd+Shift+R F

---

🚀 Quick Start

git clone https://github.com/alazndy/R-AI-OS.git
cd R-AI-OS
cargo install --path . --force

Start the daemon (powers the TUI, MCP server, and HTTP API):

aiosd

Tune background load in ~/.config/raios/config.toml when needed, especially on Windows:

[daemon]
startup_bm25_indexing = true
startup_cortex_indexing = false
enable_health_worker = true
health_interval_secs = 900
git_interval_secs = 300
enable_sentinel_worker = false
sentinel_interval_secs = 300
enable_port_monitor = true
port_monitor_interval_secs = 30
port_probe_timeout_ms = 75

Windows defaults are now intentionally calmer: no eager Cortex indexing, no periodic Sentinel compile loop, slower health/git/port polling.

Launch the TUI:

raios

Bootstrap your AI factory (replicates 90+ agents and 180+ skills):

raios bootstrap

---

💻 CLI Reference

Core Operations

Command	Description
raios health	Portfolio health dashboard — scans all projects
raios health <project>	Single-project health scan
raios usage	Show local usage/quota signals across AI tools
raios search "<query>"	Semantic search across portfolio
raios new "ProjectName"	Scaffold a new project (follows MASTER rules)
raios task "<description>"	Route task to best agent
raios bootstrap	Replicate AI factory on a new machine

Security

Command	Description
raios verify-chain	Verify audit log hash-chain integrity
raios verify-chain -n <N>	Show last N entries then verify
raios security	OWASP security scan

Agent Swarm

Command	Description
raios swarm start	Start a parallel agent worktree
raios swarm list	List active swarm tasks
raios swarm approve <id>	Approve a pending swarm diff (merge branch)

Git Operations

Command	Description
raios git status	Git status across portfolio
raios git log	Recent commits
raios git commit	Intelligent bulk commit

Build & Dev

Command	Description
raios build	Build current project
raios test	Run test suite
raios deps	Dependency audit
raios env	Environment variable scan

raios usage intentionally separates exact quota data from local auth metadata. If a provider does not expose remaining/reset counters locally, R-AI-OS prints unknown instead of guessing.

---

📁 Project Structure

src/
├── bin/
│   ├── raios.rs          # CLI entrypoint
│   └── aiosd.rs          # Daemon entrypoint
├── app/
│   └── events/           # Event handling (actions, keyboard, commands)
│       └── keyboard/     # Keyboard module (6 sub-modules)
├── cli/                  # CLI command implementations
├── core/
│   ├── build/            # Build logic (language-specific, 10 sub-modules)
│   └── deps/             # Dependency management (10 sub-modules)
├── cortex/               # Vector store, BM25 index, session memory
├── daemon/               # aiosd background daemon
├── intelligence/         # Agent routing, instinct engine, RBJ
├── mcp/                  # MCP server — policy-gated tool call handler
├── search/               # Neural search (BM25 + vector hybrid)
├── security/             # Security Kernel (sandbox, policy, chain, egress)
├── sentinel/             # Redaction engine, Sentry integration
├── server/               # HTTP/WebSocket server (Axum, :42071)
├── swarm/                # Parallel worktree agent management + SQLite store
└── ui/
    └── panels/           # TUI panels (13 modules — dashboard, security, etc.)

vscode-extension/
├── src/
│   ├── extension.ts      # Extension activation
│   ├── ipc/              # DaemonClient, TokenBridge, DaemonManager
│   ├── providers/        # Sidebar, StatusBar, Diagnostics, Refactor, Diffs
│   ├── commands/         # CommandBridge
│   └── bridge/           # JumpToCode
├── icon.svg              # Master logo (512×512, source of truth)
├── icon.png              # Extension marketplace icon (512×512)
└── icon128.png           # Extension sidebar icon (128×128)

---

🗺️ Roadmap

• Phase 1–7: Core TUI, workspace mapping, health dashboard, BM25 search
• Phase 8: Universal Kernel — Tri-protocol, Lock Manager, Radar Whispers, Factory Mode
• Phase 9: Refactor & Modularization — all large files split into focused modules
• Phase 10: Hardened Kernel Alpha — Sentry, Redaction Engine, Audit Ledger
• Phase 10B: Security Kernel (Phases 1–4) — Sandbox + Policy + Audit Chain + Egress
• Phase IDE: VS Code Extension — Sidebar WebView + TokenBridge + DaemonManager + Refactor Tree
• Phase IDE v0.5: Sidebar v2 — Git Status card, Swarm card with Approve, Quick Actions
• Phase 11: Tool Pinning & Drift Detection — SHA-256 manifest pin, -32028 on mismatch, raios pin-reset / pin-status
• Phase 12: Secret Leasing — raios secret grant <tool> <ENV_VAR> with TTL-based auto-revoke
• Phase 13: Rate Limiting — Fixed-window counter per tool, -32029 on exceed, raios rate-status
• Phase 14: Quarantine Mode — Pattern-matched quarantine queue, -32027 on block, raios quarantine list/approve/deny
• Phase 15: Write-Back Bridge — Sidebar Kanban → memory.md task state sync

---

R-AI-OS is the bridge between human creativity and autonomous execution.