Self-improving, multi-agent AI coding assistant with natural language understanding, autonomous role execution, persistent memory, and governed security.
Getting Started | NLA | ARA | Skills | Web UI | AEGIS Governance | Network Security | Documentation | Contributing
v10.0.4 -- Orion Agent's full governed execution pipeline is operational and proven (3,000+ passing tests, 26/26 operational validation, 17/17 E2E live tests). The Digital Agent Architecture (Phase 2), Graduated Services (Phase 3), and Execution Pipeline (Phase 4) are complete: execution steps with feedback and memory, container infrastructure with stack detection, performance metrics, full pipeline integration wiring, and messaging bridge -- all verified with real Ollama LLM generating real code through governed infrastructure. We welcome feedback and bug reports via GitHub Issues.
| Component | Status | Tests |
|---|---|---|
| BYOK (11 LLM Providers) | Shipped | 1,702+ |
| AEGIS Governance (7 Invariants) | Shipped | Included |
| Digital Agent Architecture | Shipped | 26 operational + 17 E2E |
| Egress Proxy ("The Narrow Door") | Shipped | Domain whitelist, content inspection, rate limiting, JSONL audit |
| DNS Filter | Shipped | Container DNS isolation |
| Approval Queue | Shipped | Human-gated write operations |
| Sandbox Orchestrator | Shipped | 6-step governed boot, Docker isolation |
| Graduated Google Services | Shipped | Per-service toggle, hot reload |
| LLM Web Search Routing | Shipped | Search API auto-allow, research domain GET-only |
| Execution Pipeline (Phase 4A) | Shipped | ExecutionStep, feedback, memory, proactive learner, ruff tool |
| Container Infrastructure (Phase 4B) | Shipped | SandboxConfig, SessionContainer, StackDetector, RegistryWhitelist |
| Performance Metrics (Phase 4C) | Shipped | PerformanceMetrics, CLI dashboard, API routes, activity persistence |
| Pipeline Integration (Phase 4D) | Shipped | TaskExecutor wiring, CLI commands, API routes, settings manager |
| Messaging Bridge (Phase 4E) | Shipped | MessageBridge, notifications, activity streaming, review summaries |
| CLI (REPL) | Working | Interactive, Ollama + cloud providers |
| Web UI | Working | Network dashboard, service toggles |
Proven end-to-end: Task -> LLM (Ollama qwen2.5:7b) -> Builder -> Reviewer -> Governor -> Sandbox -> Workspace -> pytest 4/4 pass.
Orion is an AI coding assistant that goes beyond simple code generation. It combines:
- Natural Language Architecture (NLA) -- Intent classification, clarification detection, and adaptive prompt engineering
- Autonomous Role Architecture (ARA) -- Background task execution with configurable roles, AEGIS-gated promotion, and daemon management
- Multi-Agent Deliberation -- Three specialized agents deliberate on every task
- Persistent Memory -- Learns and remembers across sessions, projects, and time
- AEGIS Governance -- Hardened security gate that prevents unsafe operations (7 invariants)
- Network Security -- Egress proxy, DNS filter, content inspection, and approval queue in Docker sandbox
- Slim Persona System -- Tiered prompt engineering (50–120 tokens) matched to intent complexity
Unlike single-shot AI tools, Orion develops understanding of your codebase, your patterns, and your preferences over time.
Orion understands what you mean, not just what you type:
| Component | Purpose |
|---|---|
| ExemplarBank | 200+ seed exemplars for intent matching with cosine similarity |
| IntentClassifier | Embedding + keyword hybrid classification (coding, question, conversational) |
| ClarificationDetector | Detects ambiguous requests and generates targeted follow-up questions |
| BriefBuilder | Converts natural language into structured TaskBrief objects |
| RequestAnalyzer | Full pipeline: classify → clarify → brief → route |
| EnglishFoundation | Linguistic pre-processing (contractions, negation, entity extraction) |
| LearningBridge | Feedback loop: user ratings → new exemplars → improved classification |
Orion can work autonomously in the background with configurable roles (37+ modules, 750+ ARA tests):
| Component | Purpose |
|---|---|
| RoleProfile | YAML-based role configuration with 3-tier authority, confidence thresholds, competencies, risk tolerance |
| AegisGate | Pre-promotion security: secret scanning, write limits, scope checks, auth |
| SessionEngine | State machine with heartbeat, cost tracking, and 5 stop conditions |
| GoalEngine | LLM-powered task DAG decomposition with action validation |
| ExecutionLoop | Sequential task runner with confidence gating and checkpointing |
| TaskExecutor | File generation/editing in sandbox with context-aware LLM calls |
| PromotionManager | Sandbox branch creation, file diff, conflict detection, git-tagged promote/reject/undo |
| GoalQueue | Multi-goal FIFO queue with priority interrupts, dependencies, and reorder |
| MorningDashboard | 7-section CLI TUI: overview, approvals, tasks, files, budget, AEGIS, actions |
| PromptGuard | 12-pattern prompt injection defence with sanitization |
| AuditLog | HMAC-SHA256 hash chain, append-only JSONL, tamper detection |
| KeychainStore | OS-native credential storage (Windows/macOS) with encrypted fallback |
| UserIsolation | Multi-user OS-user scoping, per-user containers and branches |
| SkillLibrary | AgentSkills-compatible SKILL.md system with CRUD, integrity verification, and role assignment |
| SkillGuard | 22+ pattern security scanner with NFKC normalization and evasion hardening |
| Daemon + CLI | Background process with 37 commands including setup wizard |
| Notifications | Email (SMTP), webhook, and desktop toast delivery with rate limiting |
| REST + WebSocket API | 106+ endpoints for web UI integration and real-time updates |
Starter roles included: game-developer, night-coder, researcher, devops-runner, full-auto
Orion uses the AgentSkills open standard for extensible agent capabilities (8 bundled skills, 145 tests):
| Component | Purpose |
|---|---|
| SKILL.md Format | YAML frontmatter + markdown instructions, compatible with Claude Code and Windsurf |
| SkillLibrary | Central registry with CRUD, import, rescan, role resolution, integrity verification (SHA-256) |
| SkillGuard | Security scanner: 22+ patterns, NFKC normalization, prompt injection detection |
| Skill Groups | Organize skills into assignable groups with role mapping |
| 8 Bundled Skills | code-review, write-tests, write-documentation, deploy-to-staging, docker-setup, git-workflow, debug-issue, refactor-safely |
A full-featured React (Next.js) dashboard for managing ARA sessions:
| Feature | Description |
|---|---|
| Dashboard | Stats grid, status hero, activity feed, task queue, progress ring |
| Consent Gates | Approve/reject with GitHub-PR-style diff viewer (file tree + unified diffs) |
| New Session | Start work sessions from the UI with role selection and goal input |
| Job Roles | Inline accordion expansion -- click to view/edit scope, auth, description; assign/remove skills directly |
| Skills | Inline accordion expansion -- click to view metadata, SKILL.md content, edit instructions, assign to roles; bundled skills read-only |
| Chat | WebSocket chat sidebar connected to Orion's full NLA pipeline |
| Settings | ARA settings, API keys, workspace configuration |
| Notifications | Real-time notification badge with unread count |
Every request flows through three specialized agents:
| Agent | Role | Responsibility |
|---|---|---|
| Builder | Creator | Generates code solutions using your chosen LLM |
| Reviewer | Critic | Analyzes Builder's output for correctness, quality, and edge cases |
| Governor | Authority | Makes final decisions using memory, quality gates, and governance rules |
This "Table of Three" approach catches errors that single-agent systems miss.
Orion remembers -- not just within a conversation, but across your entire development history:
| Tier | Storage | Duration | Purpose |
|---|---|---|---|
| Session | RAM | Current session | Immediate context and conversation state |
| Project | JSON | Days to weeks | Workspace patterns, decisions, and preferences |
| Institutional | SQLite | Months to years | Cross-project wisdom and proven patterns |
AEGIS (Autonomous Execution Governance and Integrity System) is Orion's security core (v7.0.0, 7 invariants):
- Invariant 1: Workspace Confinement -- Cannot operate outside your project directory
- Invariant 2: Mode Enforcement -- Graduated permissions (safe -> pro -> project)
- Invariant 3: Action Validation -- Every file operation is checked before execution
- Invariant 4: Risk Validation -- Risk scoring with configurable thresholds
- Invariant 5: Command Execution -- Shell injection prevention, dangerous pattern blocking
- Invariant 6: External Access Control -- Network operations require explicit approval
- Invariant 7: Network Access Control -- Hardcoded domain whitelist, blocked Google services, protocol enforcement
Phase 2 introduces Docker-based network isolation with defence in depth:
| Layer | Component | Purpose |
|---|---|---|
| L1 | Egress Proxy | Domain whitelist with hardcoded LLM endpoints, rate limiting |
| L2 | DNS Filter | NXDOMAIN for non-whitelisted domains |
| L3 | Content Inspector | 12 credential patterns blocked in outbound payloads |
| L4 | Approval Queue | Human-in-the-loop gate for write operations |
| L5 | AEGIS Invariant 7 | Hardcoded blocked Google services (Drive, Gmail, Calendar, YouTube) |
| L6 | Docker Isolation | Dual-network architecture (orion-internal + orion-egress) |
| L7 | Google Credentials | Scope-enforced OAuth with blocked-scope rejection |
Orion learns from every interaction:
- You rate responses (1-5 stars)
- Good patterns (4-5) are stored as success templates
- Bad patterns (1-2) are stored as anti-patterns to avoid
- Evolution tracking monitors improvement over time
| Feature | Orion |
|---|---|
| Natural language understanding | NLA: intent classification, clarification, adaptive prompts |
| Autonomous background tasks | ARA: roles, daemon, checkpoints, drift detection, recovery |
| Web UI | Full React dashboard with consent gates, diff viewer, session management |
| Skills system | AgentSkills-compatible SKILL.md, 8 bundled, SkillGuard security |
| Multi-agent deliberation | 3 specialized agents (Builder, Reviewer, Governor) |
| Persistent memory | 3 tiers (session, project, institutional) |
| Learns from feedback | Evolves based on your approval/rejection patterns |
| Governance/safety gate | AEGIS v7.0.0 -- 7 hardened security invariants |
| Network firewall | Egress proxy + DNS filter + content inspection in Docker sandbox |
| Edit validation | Pre-write confidence scoring + auto-recovery |
| LLM providers | 11 providers including local Ollama (BYOK) |
| Self-hosted | Runs entirely on your machine |
| Open source | AGPL-3.0 |
# Basic installation
pip install orion-agent
# With all integrations
pip install orion-agent[all]orion> /workspace /path/to/your/project
Workspace set: /path/to/your/project
> /mode pro
Mode set: pro (read + write with approval)
> Explain what the main function does
[Orion analyzes your code and provides explanation]
> Add error handling to the database connection
[Orion proposes changes, waits for your approval]
# Set your API key
/settings key openai sk-your-key-here
# Choose your model
/settings model gpt-4o
# Or use local Ollama (free)
/settings provider ollama
/settings model llama3When Docker Desktop is installed, Orion automatically boots its governed sandbox environment on startup. No manual commands needed -- the egress proxy, DNS filter, and approval queue start in the background.
If Docker is not available, Orion runs in BYOK-only mode (no network governance).
# Just start Orion -- sandbox boots automatically if Docker is available
orion
# Check sandbox status
> /sandbox status
# Manual control (overrides auto-boot)
> /sandbox stop
> /sandbox start
> /sandbox restartAEGIS is what makes Orion safe for production use. It's a pure-function security gate with seven invariants (v7.0.0):
- Workspace Confinement -- All file operations must stay within the workspace
- Mode Enforcement -- Actions must be permitted by the current mode
- Action Scope -- Only approved operation types are allowed
- Risk Validation -- High-risk operations require human confirmation
- Command Execution -- Shell commands are validated for safety
- External Access -- Network operations follow read/write approval rules
- Network Access Control -- Hardcoded domain whitelist, blocked Google services, protocol enforcement
AEGIS cannot be bypassed, disabled, or reconfigured by AI agents.
Complete AEGIS documentation ->
Orion's security model is built on one architectural invariant: Orion cannot modify its own governance. AEGIS configuration lives on the host filesystem, mounted read-only into the Docker sandbox. No prompt injection, no code execution, no agent behavior can change the rules.
| Layer | Location | Purpose |
|---|---|---|
| 1. AEGIS Configuration | Host filesystem (read-only mount) | Governance rules, invariants |
| 2. Docker Network Isolation | Kernel namespaces | Container cannot reach internet directly |
| 3. Egress Proxy | Host-side process | Domain whitelist, content inspection, credential leak detection |
| 4. Filesystem Isolation | Docker volumes | Read-only mounts for config, sandboxed workspace |
| 5. Approval Queue | Host-side process | Human gate for write operations |
| 6. Credential Isolation | Read-only mount | Access token only -- no refresh token in container |
| 7. Orion Self-Governance | Software layer | AEGIS invariant checks (least trusted layer) |
Orion is the only open-source AI agent framework where the agent architecturally cannot modify its own governance. This isn't a feature flag -- it's a physical boundary enforced by Docker container isolation. No other agent framework (OpenClaw, Claude Code, Copilot, Cursor) has this property.
Network Security documentation ->
Orion connects to 79+ external services:
| Category | Count | Examples |
|---|---|---|
| LLM Providers | 11 | OpenAI, Anthropic, Google, Ollama, Groq, Mistral, Cohere |
| Voice TTS | 8 | ElevenLabs, OpenAI TTS, Edge-TTS, Piper |
| Voice STT | 6 | Whisper, Vosk, Deepgram, AssemblyAI |
| Image Generation | 8 | DALL-E 3, Stability AI, Midjourney, Replicate |
| Messaging | 15 | Slack, Discord, Telegram, Teams, WhatsApp |
| Dev Tools | 10+ | GitHub, GitLab, Jira, Linear, Notion |
Complete integration catalog ->
| Document | Description |
|---|---|
| Getting Started | Quick start guide for new users |
| Installation | Detailed installation instructions |
| User Guide | Complete user documentation |
| CLI Reference | All commands and options |
| API Reference | REST and WebSocket API |
| Architecture | System design deep-dive |
| AEGIS | Governance system documentation |
| Memory System | Three-tier memory explained |
| Security | Security model and practices |
| Network Security | Egress proxy, DNS filter, approval queue, audit logging |
| Deployment | Production deployment guide |
| FAQ | Frequently asked questions |
┌─────────────────────────────────────────────────────────────────┐
│ USER INTERFACES │
│ ┌─────────┐ ┌───────────┐ ┌───────────┐ ┌──────────────┐ │
│ │ CLI │ │ Web UI │ │ WebSocket │ │ ARA Daemon │ │
│ │ (REPL) │ │ (Next.js) │ │ (realtime)│ │ (background) │ │
│ └────┬────┘ └─────┬─────┘ └─────┬─────┘ └──────┬───────┘ │
└───────┼─────────────┼──────────────┼───────────────┼───────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ FastAPI Server (10 route modules, 106+ endpoints) │
│ REST API │ WebSocket │ CORS │ Auth │
└───────────────────────────┬─────────────────────────────────────┘
│
┌───────────────────┼───────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐
│ NLA Pipeline │ │ ARA Engine │ │ Skills System │
│ ExemplarBank │ │ Sessions │ │ SkillLibrary │
│ IntentClassify │ │ Daemon │ │ SkillGuard (22+) │
│ BriefBuilder │ │ TaskExecutor │ │ 8 bundled skills │
│ FastPath/ToT │ │ Promotion │ │ SKILL.md format │
└────────┬────────┘ │ GoalQueue │ └─────────────────────┘
│ │ Dashboard │
▼ └────────┬────────┘
┌─────────────────────────────┼───────────────────────────────────┐
│ AEGIS GOVERNANCE GATE │
│ Workspace Confinement │ Secret Scanning │ Write Limits │
│ Mode Enforcement │ Risk Validation │ Auth (PIN/TOTP) │
│ PromptGuard │ AuditLog (HMAC) │ KeychainStore │
└───────────────────────────┬─────────────────────────────────────┘
│
┌───────────────────┼───────────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ LLM Layer │ │ Memory │ │ Integrations │
│ (11 provs) │ │ (3-tier) │ │ 79 connectors │
│ + Ollama │ │ Institutional │ │ LLM, voice, │
│ │ │ Teaching │ │ image, msg, dev │
└─────────────┘ └─────────────────┘ └─────────────────┘
Complete architecture documentation ->
src/orion/
├── cli/ # Interactive REPL and commands
├── core/
│ ├── agents/ # Builder, Reviewer, Governor, Table of Three, FastPath
│ ├── understanding/ # NLA: intent, clarification, brief, analyzer, english
│ ├── memory/ # Three-tier memory engine + institutional memory + teaching
│ ├── learning/ # Evolution engine, feedback, patterns, learning bridge
│ ├── editing/ # Edit validator, format selector, git safety
│ ├── context/ # Repo map (tree-sitter), Python AST, code quality
│ ├── governance/ # AEGIS safety gate, execution authority
│ ├── llm/ # Provider routing, model config, slim persona prompts
│ └── production/ # Health probes, metrics, shutdown, logging
├── ara/ # Autonomous Role Architecture (28 modules)
│ ├── role_profile # YAML role configuration + 3-tier authority + 5 starter templates
│ ├── auth # PIN + TOTP authentication
│ ├── aegis_gate # Pre-promotion security gate
│ ├── session # State machine with heartbeat + cost tracking
│ ├── goal_engine # LLM-powered task DAG decomposition
│ ├── execution # Sequential task runner with checkpointing
│ ├── task_executor # Context-aware file generation/editing in sandbox
│ ├── daemon # Background process + IPC control
│ ├── daemon_launcher# Session launcher from pending state
│ ├── cli_commands # 37 commands: work/status/review/promote/skills/roles/setup/...
│ ├── promotion # Sandbox → workspace merge with git tags + undo
│ ├── dashboard # Morning Dashboard TUI (7 sections) + pending review detection
│ ├── goal_queue # Multi-goal FIFO queue with priority interrupts
│ ├── prompt_guard # Prompt injection defence (12 patterns)
│ ├── audit_log # HMAC-SHA256 hash chain tamper-proof log
│ ├── keychain # OS-native credential storage
│ ├── user_isolation # Multi-user OS-user scoping
│ ├── notifications # Email, webhook, desktop, messaging providers
│ ├── message_bridge # Inbound/outbound messaging with intent classification
│ ├── feedback_store # Outcome recording + confidence calibration
│ ├── execution_step # Structured execution steps with validation
│ ├── execution_config# Pipeline configuration and defaults
│ ├── execution_feedback# Step-level feedback collection
│ ├── execution_memory# Execution history and pattern recall
│ ├── proactive_learner# Autonomous learning from execution outcomes
│ ├── ruff_tool # Ruff linter integration for code quality
│ ├── performance_metrics# Execution timing, cost, and quality tracking
│ ├── skill # Skill + SkillGroup dataclasses, SKILL.md parser, validation
│ ├── skill_guard # SkillGuard security scanner (22+ patterns, NFKC hardening)
│ ├── skill_library # Central skill registry with CRUD, import, integrity verification
│ ├── ollama_provider# Local LLM integration for task execution
│ ├── checkpoint # Git-based session snapshots
│ ├── drift_monitor # External workspace change detection
│ ├── recovery # Failure handling + retry policy
│ └── lifecycle # Session cleanup + health reporting
├── api/ # FastAPI REST + WebSocket server (10 route modules, 106+ endpoints)
│ └── routes/ # ara, auth, chat, gdpr, health, models, platforms, settings, tools, training
├── integrations/ # 79 connectors (LLM, voice, image, messaging, ...)
├── security/ # Encrypted store, Docker sandbox, secret scanner
│ ├── sandbox_config # Container resource limits and security policies
│ ├── session_container# Per-session Docker container lifecycle
│ ├── stack_detector # Language/framework auto-detection for containers
│ ├── registry_whitelist# Approved container image registry
│ └── egress/ # Egress proxy, DNS filter, approval queue, content inspector, config
└── plugins/ # Plugin lifecycle API (8 hooks)
orion-web/ # React (Next.js) Web UI
├── src/app/
│ ├── page.tsx # Home page
│ ├── ara/page.tsx # ARA Dashboard (consent gates, diff viewer, sessions, roles, skills)
│ ├── chat/page.tsx # Chat interface
│ ├── aegis/page.tsx # AEGIS governance info
│ └── settings/page.tsx # Full settings panel
└── src/components/ # ChatInterface, SettingsPanel, AegisApprovalModal
# Backend
git clone https://github.com/phoenixlink-cloud/orion-agent.git
cd orion-agent
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
pytest # 1,702+ tests
# API Server
uvicorn orion.api.server:app --port 8001
# Web UI
cd orion-web
npm install
npm run dev # http://localhost:3000We welcome contributions! Please read our guidelines first:
- CONTRIBUTING.md -- How to contribute
- CLA.md -- Contributor License Agreement (required)
- COPYRIGHT.md -- Ownership and IP terms
- CODE_OF_CONDUCT.md -- Community guidelines
Note: All contributions require a signed CLA before code can be merged.
Copyright (C) 2025 Phoenix Link (Pty) Ltd. All Rights Reserved.
Orion Agent is dual-licensed:
| License | Use Case | Requirements |
|---|---|---|
| AGPL-3.0 | Open source, personal use, AGPL-compatible projects | Copyleft -- share modifications under AGPL-3.0 |
| Commercial | Proprietary software, SaaS, enterprise | Contact Phoenix Link for licensing |
Using Orion in a commercial product or SaaS? Contact info@phoenixlink.co.za
Orion is free and open-source. If it has benefited you and you'd like to see continued development, please consider making a voluntary financial contribution.
| Tier | Amount | Description | Link |
|---|---|---|---|
| One-Time Support | R400 | Supports ongoing development, documentation, and testing of Orion Agent and governed AI tooling. |  |
| Development Sponsor | R1,500 | Supports feature development, performance improvements, integrations, and security hardening. |  |
| Infrastructure Sponsor | R8,000 | Helps fund infrastructure, CI/CD pipelines, security audits, and long-term sustainability. |  |
This is a voluntary contribution, not a purchase. See FUNDING.md for full details.
Other ways to help: Star the repo | Report bugs | Improve docs | Contribute code
| Purpose | Contact |
|---|---|
| General inquiries, licensing, partnerships | info@phoenixlink.co.za |
| Technical support | support@phoenixlink.co.za |
Website: phoenixlink.co.za
Built by Phoenix Link (Pty) Ltd
Governed AI for the real world.