🧠 Cortex Hub: Autonomous AI Agent Mesh & Orchestrator

Cortex Hub is a state-of-the-art, modular AI orchestration platform that bridges the gap between Large Language Models (LLMs) and local execution via a distributed Agent Node Mesh. It features a modern React-based workspace, a powerful Skill System, and advanced RAG (Retrieval-Augmented Generation) capabilities.

✨ Key Features

• 🌐 Distributed Agent Mesh: Connect multiple local or remote nodes (Linux, macOS, Windows) to your Hub. Each node can execute tasks, manage files, and provide terminal access.
• 🌍 Dedicated Browser Service: High-performance browser automation (Playwright) running as a dedicated system service. Centralized execution for reduced latency and reduced node footprint.
• 🛠️ Extensible Skill System: Orchestrate AI capabilities via "Skills" (Terminal Control, File Management, System Analysis). Dynamic permissioning allows granular control over which users or groups can access specific nodes and skills.
• 📂 Private RAG Pipeline: Securely ingest documents into a FAISS vector store to ground AI responses in factual, local data.
• 🔐 Industrial-Grade Security: Integrated with OIDC (OpenID Connect) for secure user authentication and Role-Based Access Control (RBAC).
• 🖥️ Unified Command Center: A sleek, premium React frontend for managing sessions, configuring nodes, and monitoring the swarm in real-time.

🆕 Recent Updates (v2 Architecture)

• Backend Refactoring: Split monolithic API files into cleanly decoupled services, routing modules, and a flexible plugin-based tool repository for robust scaling.
• Frontend Modularization: Componentized sprawling React files into dedicated views, reusable UI components, and distinct feature directories for significantly enhanced maintainability.
• Browser Service Concurrency: Integrated a dynamic worker pool with a ParallelFetch gRPC pipeline and clean Markdown Document Extraction for high-speed AI web scraping.
• Mesh Stability & GC: Advanced swarm-level file synchronization and background garbage collection now guarantees instant removal of zombie nodes, orphaned ffmpeg/playwright processes, and stale temporary directories across all worker drives.

💬 How to Use

1. Connecting Nodes

Download the Agent Node Bundle from the "Nodes" page in the dashboard. Unzip and run ./run.sh (Linux/macOS) or run.bat (Windows). The node will automatically connect to your Hub using the pre-configured security token.

2. Using Skills

Skills like Browser Automation and Terminal Control are available directly in your chat sessions. You can attach specific nodes to a session to give the AI hands-on access to those environments.

🚀 Quick Start (Local Development)

The easiest way to get started is using the pre-configured Dev Container or local Docker Compose.

Prerequisites

• Docker & Docker Compose
• Python 3.11+ (if running without Docker)
• Node.js 18+ (for frontend development)

1. Configure Secrets & Keys

Most configurations and API Keys (Gemini, DeepSeek, TTS, STT) can be set dynamically via the visual Settings pane within the Web UI after booting. For deeper system overrides (like database location or custom proxy headers), you may review and edit ai-hub/app/config.yaml.

2. Launch the Stack

Initialize the Hub (Backend, Frontend, Browser Service, and SQLite Database) in one command:

docker compose up -d --build

• Frontend: http://localhost:8002
• API Docs: http://localhost:8000/docs

🏗️ Deployment Architecture

Cortex Hub uses a layered deployment strategy to keep the core codebase clean while supporting specific production environments.

📂 Folder Structure

• ai-hub/: The Core Python (FastAPI) backend.
• frontend/: The React-based unified dashboard.
• agent-node/: The lightweight client software for distributed nodes.
• skills/: Source for AI capabilities (Shell, Browser, etc.).
• deployment/: Environment-specific overrides (e.g., jerxie-prod with NFS support).
• scripts/: Centralized automation for sync, rebuilding, and maintenance.

🚢 Production Deployment

For Jerxie AI production instances, we use the centralized remote deployer:

# Sync local changes and rebuild on the production server
REMOTE_PASS='<PASSWORD>' bash scripts/remote_deploy.sh

🏛️ Project Layout

.
├── ai-hub/             # Backend API & Orchestrator
├── frontend/           # Frontend Workspace (React)
├── agent-node/         # Distributed Node Client (Lightweight)
├── browser-service/    # Dedicated Browser Automation Service (Playwright)
├── skills/             # AI Skill Definitions
├── deployment/         # Env Overrides (NFS, SSL, OIDC)
├── scripts/            # CI/CD & Maintenance Scripts
├── cortex.db           # Local SQLite Cache
└── docker-compose.yml  # Generic Development Entrypoint

🧪 Testing

• Backend: pytest ai-hub/tests/
• Frontend Health: scripts/frontend_tester
• Connectivity: scripts/test_ws.js

⚖️ License

Distributed under the MIT License. See LICENSE for more information.