🌌 ORION

Autonomous AI Orchestrator

Self-Hosted · Multi-Platform · Sovereign

A local-first, multi-agent intelligence engine built in Go — runs on any hardware, answers to no one but you.

Architecture · Capabilities · Deployment · Roadmap · Quick Setup

---

🌌 The Vision

Orion is a self-hosted, sovereign, multi-agent AI orchestrator designed to provide a robust, private intelligence framework that runs entirely on your own hardware.

Drawing upon modern distributed enterprise architectures, Orion utilizes Hexagonal (Ports & Adapters) principles to seamlessly coordinate an ecosystem of autonomous agents. Through powerful local Small Language Models (SLMs) running via Ollama, Orion achieves fast, private, and deterministic reasoning at the edge.

When tasks demand deeper research, complex synthesis, or heavier computational lifting, Orion's built-in High-Fidelity Router autonomously escalates workloads to state-of-the-art cloud LLMs (like Gemini) precisely when needed. It orchestrates context across deep, FTS5 RAG-backed memory, providing a personal, capable, and highly secure AI companion.

---

🧬 Architecture

Built on Hexagonal Architecture (Ports & Adapters) — every component is swappable, every boundary is explicit.

┌─────────────────────────────────────────────────────────────┐
│                      INGRESS LAYER                          │
│   Telegram (Primary) ·  Matrix E2EE (Experimental)          │
└────────────────────────┬────────────────────────────────────┘
                         │ Whitelisted · Rate-Limited
┌────────────────────────▼────────────────────────────────────┐
│                    ORCHESTRATOR                             │
│   Intent Classification · Agent Routing · Approval Engine   │
│   Session Context Buffer · Policy Engine (policies.yaml)    │
└────┬─────────────┬──────────────┬───────────────────────────┘
     │             │              │
┌────▼────┐  ┌─────▼──────┐  ┌────▼──────────────────────────┐
│  LOCAL  │  │   CLOUD    │  │        ACTION TOOLS           │
│  BRAIN  │  │ ESCALATION │  │  Memory · Research · Files    │
│ Ollama  │  │   Gemini   │  │  Git Sync · Health Monitor    │
└────┬────┘  └─────┬──────┘  └───────────────────────────────┘
     │             │
┌────▼─────────────▼──────────────────────────────────────────┐
│                  MEMORY LAYER                               │
│   SQLCipher AES-256 · FTS5 RAG · Memories, Tasks, Alarms    │
└─────────────────────────────────────────────────────────────┘

• Multi-Agent Hierarchy — Orchestrator classifies intent and delegates to specialized Sub-Agents (BaseAssistant, WebDev, etc.)
• Autonomous Escalation — Edge models know their limits. The cortex tool routes complex workloads to cloud LLMs natively.
• RAG Memory Tissue — SQLite FTS5 indexes every memory, reminder, and task for rapid semantic retrieval across sessions.
• Approval Engine — Sensitive tool calls require explicit human approval via policies.yaml rules, with session-aware re-execution.
• Proactive Heartbeat — Time-series pulse wakes the agent autonomously to monitor sites, run research, and deliver alerts.
• Zero Trust Ingress — Cloudflare Tunnel webhooks. Token-bucket rate limiting. Geometric whitelist fingerprinting.

---

🚀 Capabilities

Module	Stack	What It Does
Brain	Ollama + Gemini REST	Local-first reasoning with automatic cloud escalation via cortex
Memory	SQLCipher (AES-256) + FTS5	Persistent memories, reminders, tasks, and semantic RAG retrieval
Prompting	SOUL.md · AGENTS.md · TOOLS.md	Hot-reloadable persona and agent prompts — no binary recompile needed
Relay	go-telegram · mautrix-go	Webhook ingress with human-in-the-loop approval flows
Actuators	Go interfaces	Web research, file I/O sandbox, git sync, health monitoring
Networking	Cloudflare Zero Trust	Exposes webhooks securely — no port-forwarding, no static IP required

---

🖥️ Deploy Anywhere

Important

Primary Tested Platform: Orion is actively developed and rigorously tested against the Raspberry Pi 5. While the orchestration engine is built natively in Go to run anywhere, the deployment guides below for alternative platforms (NUC, VPS, macOS, Windows, NAS) are provided as architectural possibilities and community-driven references to showcase Orion's cross-platform portability.

Orion runs on your hardware — any hardware. The same binary, the same config, across every platform.

Platform	Guide	Local AI Model
🥧 Raspberry Pi 5	DEPLOY_PI.md	qwen3.5:2b — silent, fanless, always-on
🖥️ Intel NUC / Mini-PC	DEPLOY_NUC.md	Up to deepseek-r1:32b / qwen3.5:32b — desktop-class reasoning
☁️ Cloud VPS	DEPLOY_VPS.md	Up to qwen3.5:32b — always-on, zero hardware
🍎 macOS Apple Silicon	DEPLOY_MACOS.md	Metal-accelerated — fastest local inference
🪟 Windows (Native)	DEPLOY_WINDOWS.md	NVIDIA GPU acceleration optional
💾 NAS (Synology / Unraid)	DEPLOY_NAS.md	Zero extra hardware — NAS already always-on

👉 Start here: Deployment Master Guide — shared prerequisites, build commands, platform selection.

---

🗺️ Roadmap & Phase Status

The Orion Roadmap: An 8-Phase Journey

• ✅ Phase 1–2: Foundation, RAG & Multi-Agent Logic (DONE) Hexagonal Architecture, agentic routing, SQLite RAG memory.

• ✅ Phase 3–4: Logging, Heartbeat & Dockerization (DONE) Structured request logging, context propagation, graceful shutdown, secret management, prompt tuning.

• ✅ Phase 5: Production Deployment & Zero Trust Networking (DONE) Multi-platform deployment, local-first Qwen3.5/DeepSeek deterministic reasoning, Cloudflare Zero Trust webhook ingress, Telegram primary integration, experimental E2EE Matrix integration via Conduit (Rust).

• ✅ Phase 6: Modular Prompting, Context & Approval Framework (DONE) 6.1: Dynamic prompt loading (SOUL.md, AGENTS.md, TOOLS.md), hot-reload assembler with TTL caching. 6.2: Tool/skill decoupling, enhanced memory with FTS5 RAG, research cortex with deep mode, file I/O sandbox, git sync, health monitoring. 6.3: Approval framework with policies.yaml policy engine, session context buffer, approval history persistence, and re-execution flows. *6.4: Deep Audit & Hardening — pre-SIT pass covering security hardening (path traversal, rate limiting, message chunking), core architecture fixes (unified DB connection, FTS tokenizer extraction, Assembler consolidation, goroutine lifecycle), Gemini native tool calling, Dockerfile correctness, and version injection.

• ⏳ Phase 7: The "Face" — Dashboard & Web UI (NEXT) Interactive visual dashboard, execution trace graphing, multi-tool chains, Prometheus observability metrics, NUC distributed cluster computing, and full test coverage.

• ⏳ Phase 8: The "Evolution" — LoRA Fine-tuning & Data Export (UPCOMING) Continuous learning pipelines, data export layers, hot-reloadable policies, structured error types, and local model fine-tuning.

---

🛠️ Developer Quick Setup

⚙️ Prerequisites

• Go 1.26+
• CGO compiler — gcc (Linux/macOS: build-essential / Xcode CLT; Windows: TDM-GCC)
• Ollama — running locally

1️⃣ Configure the Environment

cp .env.example .env
cp configs/config.yaml.example configs/config.yaml
cp configs/providers.yaml.example configs/providers.yaml

Populate .env with your API keys. Edit config.yaml for app settings (pulse interval, whitelisted IDs). Edit providers.yaml to configure AI models, roles, and agent-to-provider mapping. You can run go run ./cmd/listmodels/main.go to fetch the latest available Gemini models after setting your API key.

2️⃣ Customize the Persona (Optional)

Edit the USER PRIME DIRECTIVE section at the bottom of prompts/SOUL.md to change how Orion speaks and behaves. Changes take effect on the next message — no restart required.

3️⃣ Build & Run

make tidy
make build
make run

Cross-platform builds:

make build-linux    # → bin/orion-linux
make build-macos    # → bin/orion-darwin
make build-windows  # → bin/orion.exe

---

🤝 Contributing

Interested in building new skills for Orion or improving existing tools? See the Contributing Guide for testing standards, architecture conventions, and how to run the test suite.

---

⚖️ License

MIT License. Open logic for open autonomy.