realize-os 5.2.1

AI-native personal operations system — coordinated agents for your business

RealizeOS

The AI operations system for your business.
Coordinated AI agents that understand your venture, remember your preferences,
and execute multi-step workflows — not just another chatbot.

⚡ Quickstart · 🏗️ Architecture · ✨ Features · 🔌 MCP Server · 💻 CLI Reference · 🚀 Self-Host · 🤝 Contribute

---

What is RealizeOS?

RealizeOS is a self-hosted AI operations system that gives your business a coordinated team of AI agents. Unlike generic chatbots, RealizeOS agents know your venture, run multi-step workflows, route to the optimal model, and respect governance with approval gates and audit logs.

---

⚡ Quick Start

🐳 Docker (recommended)

git clone https://github.com/SufZen/RealizeOS-5.git && cd RealizeOS-5
cp .env.example .env       # Add your API key(s)
docker compose up --build   # Dashboard → http://localhost:8080

Or standalone:

docker run -d -p 8080:8080 -v realizeos-data:/app/data ghcr.io/sufzen/realizeos-5:latest

🐍 pip (no Docker)

pip install realize-os
realize-os init --template consulting
realize-os serve
# Dashboard → http://localhost:8080

Requires Python 3.11+. Works on Windows, macOS, and Linux.

📦 NPX

npx @realize-os/cli init my-business
cd my-business && npx @realize-os/cli start

Requires Node.js 18+ and Docker.

🖥️ One-Liner Install

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/SufZen/RealizeOS-5/main/scripts/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/SufZen/RealizeOS-5/main/scripts/install.ps1 | iex

Method	Requires	Best For
Docker	Docker	Production, isolated deployments
pip	Python 3.11+	Local dev, no Docker needed
NPX	Node.js 18+ + Docker	Fastest project scaffolding
One-liner	bash / PowerShell	Server deployment, CI/CD

📖 Full setup guide: QUICKSTART.md · Production: Self-Hosting Guide

---

✨ Key Features

🧠 FABRIC Knowledge System

Every venture's AI knowledge is organized into six layers:

Layer	Purpose
Foundations	Venture identity, voice, core standards
Agents	AI team definitions and routing guide
Brain	Domain knowledge, market data, expertise
Routines	Skills, workflows, state maps, SOPs
Insights	Memory: learning log, feedback, decisions
Creations	Output: deliverables, drafts, final assets

🤖 Multi-LLM Routing

The engine classifies every task and selects the optimal model:

Task Type	Model	Examples
Simple	Gemini Flash	Status checks, formatting, lookups
Content	Claude Sonnet	Writing, analysis, summarization
Complex	Claude Opus	Strategy, multi-step reasoning

Providers auto-discovered at startup. Supports Claude, Gemini, OpenAI, and Ollama (local).

🔧 Agent System

• Composable agents with scope, inputs, outputs, guardrails, and tools
• Pipelines — sequential execution with Dev-QA retry loops
• 7 handoff types — standard, QA-pass/fail, escalation, phase-gate, sprint, incident
• Hot-reload — filesystem-watched agent registry
• Per-agent SOUL — persistent identity: role, personality, expertise, communication style
• Tool gating — per-agent allowlists/denylists

🧩 Extension System

Type	Purpose	Example
tool	New capabilities	Stripe, Twilio, custom APIs
channel	Communication	Slack, Discord, WhatsApp
integration	Backend sync	CRM, analytics
hook	Event reactions	Notifications, logging

🛠️ Tool Ecosystem

Category	Capabilities
Google Workspace	Gmail (8 tools), Calendar (4), Drive (9), Sheets (3)
Financial	Stripe charges, subscriptions, invoices
Web	Search (Brave API), page scraping, headless browser
MCP	Connect to any MCP-compatible tool server
Messaging	Agent-to-agent bus, human notifications, channels
Governance	Human-in-the-loop approval workflows

📋 Business Templates

Pre-built venture configurations:

consulting · agency · portfolio · saas · ecommerce · accounting · coaching · freelance

realize-os init --template consulting

---

🔌 MCP Server

RealizeOS ships a built-in MCP server so any MCP-speaking agent can use it as a second brain:

• 24 tools across 4 families: Chat & Status, KB Read, Ops, Admin
• HTTP+SSE transport — works with Claude Desktop, Cursor, n8n, cloud routines
• Same auth — Bearer JWT or API key, same roles and audit logs
• Gated access — KB, ops, and admin tools independently toggleable

realize-os mcp serve --port 8080        # Start API + MCP together
realize-os mcp token --user owner       # Issue a bearer token

📖 Full details: docs/mcp-server.md

---

💻 Operator CLI

The realize-os CLI is a first-class operator interface:

realize-os serve                                # Start API + dashboard
realize-os chat "What's the pipeline status?"   # Quick query
realize-os repl --system realization-il          # Interactive REPL
realize-os kb search "investment thesis"         # Search knowledge base
realize-os config profile add prod --endpoint https://my-vps:8080

Both realize-os (pip-installed) and python cli.py (source checkout) work identically.

📖 Full command reference: docs/cli-reference.md

---

🛡️ Security & Governance

• 5-layer security middleware: Security headers → Audit → Rate limiting → Injection guard → JWT auth
• RBAC with 6 roles: owner, admin, operator, user, viewer, guest
• Prompt injection scanner — pattern + heuristic + Unicode normalization
• Human-in-the-loop approval gates for consequential actions
• Audit logging — JSONL persistent logs with SSE streaming
• Secret redaction in error responses and logs

---

📖 Documentation

Guide	Description
⚡ Quickstart	Zero to running in 10 minutes
🏗️ Architecture	FABRIC, message flow, modules
💻 CLI Reference	Full operator CLI command tree
🔌 MCP Server	Built-in MCP server: tools, security, integration
📖 Getting Started	First steps after setup
🔧 Configuration	Customize your deployment
🚀 Self-Hosting	Production deployment
✍️ Skill Authoring	Create custom skills
📡 API Reference	REST + MCP API documentation
📋 Upgrade from 5.0	Migration guide: 5.0.x → 5.1.0
🤝 Contributing	Developer guide

---

Requirements

• Python 3.11+ (3.12+ recommended)
• At least one LLM API key (Anthropic, Google, OpenAI, or Ollama)
• Docker 24.0+ (optional, for containerized deployment)
• Node.js 20+ (optional, for dashboard development)

---

Community

• 🐛 Report a Bug
• 💡 Request a Feature
• 📖 Read the Docs
• ⭐ Star the Repo

---

License

RealizeOS is licensed under the Business Source License 1.1.

• ✅ Free to use, modify, and self-host
• ✅ Free for internal business operations
• ✅ Converts to Apache 2.0 on March 26, 2030
• ❌ Cannot offer as a hosted/managed service without a commercial license

For commercial licensing inquiries, contact [e-mail].