BLUX Lite Banner

Ubuntu/Debian Recommended Termux Supported Windows (WSL2) macOS License

Personal AI orchestrator for trust, sovereignty, and speed.

Local-first AI orchestration framework — install, route, and run multiple models with one unified CLI. Portable across Linux, macOS, WSL2, and Termux. Trust, sovereignty, and speed. (( • ))

BLUX Lite is a local-first AI orchestration framework designed to give you complete control over your AI infrastructure. Install and manage multiple AI engines and models, route queries intelligently based on capabilities and requirements, and maintain full data sovereignty—all from a single, portable command-line interface.

• 🔒 Privacy First: Your data never leaves your machine. No cloud dependencies required.
• 🎯 Intelligent Routing: Automatic model selection based on capabilities, cost, latency, and task requirements
• 📝 Full Auditability: Append-only audit logs track every decision and interaction
• 🔌 Modular Architecture: Plugin-based system for easy extensibility
• 🌍 Cross-Platform: Works on Linux, macOS, WSL2, and even Android (Termux)
• 🚀 Production Ready: Built with safety, governance, and explainability from the ground up

• Explainable AI: Every routing decision includes scores, breakdowns, and alternatives
• Liberation Framework (.libf): Project memory and context that you own and control
• Unified Shell: Manage engines, models, and plugins without context switching
• Mobile-First: Developed and tested on Android/Termux for true portability

# Clone the repository
git clone https://github.com/Outer-Void/blux-lite.git
cd blux-lite
# Initialize (creates virtual environment and sets up configs)
chmod +x first_start.sh
./first_start.sh
# Launch BLUX
./auto-start.sh

# Activate the virtual environment
source .venv/bin/activate
# View available commands
python -m blux --help
# Run orchestrator demo (routing + audit)
blux demo orchestrator
# Run toolbox demo (chained plugins)
blux demo toolbox
# View audit logs
blux audit view
blux audit tail
# Install engines and models
python -m blux.catalog_install engines
python -m blux.catalog_install models
python -m blux.catalog_install plan llama-3.1-8b
# Launch integrated shell
python -m blux.ish

For a fully scripted setup and demo run:

make bootstrap
make doctor
make demo

blux-lite/
├── blux/ # Core orchestration framework
│ ├── orchestrator/ # Registry, router, controller
│ ├── cli/ # Command-line interface
│ └── tui/ # Terminal UI (alpha)
├── engines/ # AI engine adapters
├── models/ # Model definitions and metadata
├── plugins/ # Extensible plugin system
├── docs/ # Documentation and guides
└── scripts/ # Utility scripts

1. Clarity Pass (optional): BLUX-cA bridge analyzes intent, language, task, and safety
2. Model Registry: Tracks capabilities, provider types, and resource requirements
3. Intelligent Router: Scores and selects optimal model based on multiple criteria
4. Controller Loop: Implements with feedback and evaluation
5. Audit Trail: Records all decisions and outcomes in append-only log

BLUX uses a manifest-based plugin system. Plugins declare capabilities through orchestrator.json:

• Capabilities: Languages, tasks, and domain expertise
• Dependencies: Required system packages and Python modules
• Platform Support: OS-specific compatibility
• Safety Level: Security and governance classifications
• Router Hints: Performance and cost guidance

See docs/plugin_authoring.md for detailed plugin development guide.

Every routing decision and model interaction is logged to an append-only JSONL audit file:

# View specific trace
blux audit view --trace <trace-id>
# Stream recent events
blux audit tail
# Analyze routing decisions
blux audit analyze routing

Audit logs include:

• Routing scores and alternatives considered
• Controller iterations and evaluator feedback
• Safety checks and governance decisions
• Resource utilization and performance metrics

Connect BLUX-cA for enhanced clarity and governance:

# Set clarity bridge endpoint
export BLUX_CA_ENDPOINT="http://localhost:8000"
# Or use local executable
export BLUX_CA_PATH="/path/to/blux-ca"
# Enable doctrine/guardian checks
export BLUX_DOCTRINE_PATH="/path/to/doctrine"

BLUX includes packaged default catalogs under blux/orchestrator/default_catalogs/:

• Engine Catalog: Ollama, llama.cpp, vLLM, and more
• Model Catalog: Pre-configured model definitions with capability metadata
• Plugin Catalog: Curated plugins for common tasks

Install from catalogs:

# View available engines
python -m blux.catalog_install engines --list
# Install specific engine
python -m blux.catalog_install engines --name ollama
# Plan model installation (dry-run)
python -m blux.catalog_install plan llama-3.1-8b
# Execute installation
python -m blux.catalog_install apply llama-3.1-8b

Demonstrates the complete routing and decision-making pipeline:

blux demo orchestrator

What it shows:

• Clarity pass with cA bridge (or local fallback)
• Model scoring against capabilities, cost, and latency
• Explainable routing decision with alternatives
• Append-only audit log entries
• Graceful offline handling with stubbed responses

Exercises the living toolbox plugin chain:

blux demo toolbox

What it shows:

• Plugin manifest validation
• Dependency checking (doctor plugin)
• Environment verification
• Model registry queries
• Chained tool execution with feedback

• Installation Guide - Platform-specific installation instructions
• Quick Start Guide - Get up and running in 5 minutes
• Platform Guides - OS-specific setup and optimization

• Plugin Authoring Guide - Create your own plugins
• Architecture Overview - System design and components
• API Reference - Programmatic usage

• Model Management - Installing and configuring models
• Security Guide - Best practices and threat model
• Troubleshooting - Common issues and solutions

BLUX uses environment variables and config files for customization:

# Configuration directory (default: ~/.config/blux-lite-gold)
export BLUX_CONFIG_HOME="/path/to/config"
# Clarity bridge
export BLUX_CA_ENDPOINT="http://localhost:8000"
# Governance
export BLUX_DOCTRINE_PATH="/path/to/doctrine"
# Model storage
export BLUX_MODELS_DIR="/path/to/models"

See .env.example for full configuration options.

• ✅ Complete installation chain: first_start.sh → auto-start.sh → blux-lite.sh
• ✅ Python and shell syntax validation passing
• ✅ Core orchestration: registry, router, controller
• ✅ Audit logging and trace analysis
• ✅ Plugin system with manifest validation
• ✅ Catalog-based installation
• ✅ Termux/Android support (stable)

• ⚠️ TUI (Terminal UI) - alpha quality, navigation rough
• ⚠️ Cross-platform testing - Linux, WSL2, macOS
• 🚧 Native Windows support - planned

• TUI navigation requires refinement
• Some platform-specific edge cases being resolved
• Documentation being expanded

We welcome bug reports and contributions!

We welcome contributions! Areas where help is especially valuable:

• Testing: Platform-specific testing and bug reports
• Documentation: Guides, tutorials, and examples
• Plugins: New capabilities and integrations
• Engines: Additional AI engine adapters
• Models: Curated model definitions and benchmarks

Please see CONTRIBUTING.md for guidelines.

• Stabilize TUI with improved navigation
• Expand platform testing coverage
• Enhanced plugin discovery and marketplace
• Performance optimization for low-resource devices

• Native Windows support
• Web-based management interface
• Distributed orchestration across devices
• Model fine-tuning integration

• Federation and peer-to-peer capabilities
• Advanced governance and compliance features
• Enterprise deployment tools
• Cloud-hybrid modes (optional)

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: outervoid.blux@gmail.com

• FAQ
• Changelog
• Credits

BLUX Lite is dual-licensed to balance open collaboration and commercial adoption:

• Open source: Available under the Apache License 2.0 for open use, modification, and redistribution with proper attribution and notice retention.
• Commercial: For embedding in paid products, hosted services, or other commercial use cases, a separate commercial license is required (see LICENSE-COMMERCIAL).

You may use the software under Apache 2.0 if your use complies with its terms (permitted redistribution, inclusion of notices, and allowance for contributions back). Commercial agreements are available for organizations that need broader rights or assurances.

For commercial licensing inquiries, contact theoutervoid@outlook.com . See COMMERCIAL.md for examples of when a commercial license is needed.

This software exists to support growth, healing, and autonomy — not harm.

BLUX Lite is built on principles of:

• Transparency: All decisions are explainable and auditable
• Sovereignty: Your data and AI infrastructure belong to you
• Safety: Built-in governance and safeguards
• Accessibility: Works on devices you already own
• Healing: Technology should empower, not exploit

We are committed to the responsible development and deployment of AI technology.

See CREDITS.md for a full list of contributors, dependencies, and acknowledgments.

Built mobile-first, auditable by design. Healing path only.

(( • ))

Links:

• 🌐 Website: github.com/Outer-Void
• 📧 Contact: outervoid.blux@gmail.com
• 📖 Documentation: docs/
• 🐛 Issues: github.com/Outer-Void/blux-lite/issues