Powernode Platform

Open-source mission control for AI agent fleets — chat to provision, agents to operate, humans to approve.

Powernode turns AI agents into accountable operators of real infrastructure. Describe what you need in plain English, an agent fleet provisions it, and an autonomous control loop keeps it healthy — with every consequential action gated through an approval workflow you configure.

It's the full operational substrate underneath: authentication, permissions, multi-provider LLM routing, knowledge graph reasoning, real-time communication, DevOps pipelines, container orchestration, and a fleet sensor + intervention policy framework that lets agents observe, propose, and act within safety guardrails you define. Every component is designed to work together: agents share memory, learn from execution history, and operate within boundaries that keep them auditable.

Why Powernode

• AI Agent Orchestration — Deploy agents with trust scoring, autonomy tiers, and 5 team strategies. Kill switch, goal tracking, proposals, escalations, and behavioral fingerprinting keep agents operating within defined boundaries.
• Multi-Provider LLM Routing — 10+ providers (Anthropic, OpenAI, Ollama, Azure, Google, Groq, Grok, Mistral, Cohere), 145+ models, cost-optimized selection with per-agent budgets and ROI tracking.
• Knowledge Infrastructure — GraphRAG over 1,190+ nodes and 1,670+ edges, 4-tier memory system (working → STM → LTM → shared), compound learning with decay and reinforcement, RAG pipeline with pgvector embeddings and 3-round agentic retrieval.
• MCP-Native Platform — 431 tool actions across 57 tool classes spanning knowledge, memory, skills, autonomy, DevOps, Docker, and content management. Full A2A protocol support for agent-to-agent communication.
• DevOps Automation — CI/CD pipelines with 13 step types (including AI-powered), Docker Swarm orchestration, multi-provider Git integration (GitHub, GitLab, Gitea), supply chain security with SBOM generation.
• Production Foundation — 543+ granular permissions, 17 WebSocket channels, JWT + OAuth 2.0 authentication, and 20,600+ tests across backend, frontend, and E2E.

Built with Rails 8.1.2, React 19.1 TypeScript, Sidekiq 7.2, and PostgreSQL + pgvector.

Key Features

Core Platform

• Authentication & Security - JWT + OAuth 2.0, 2FA, account lockout, rate limiting, CORS, CSP
• Permission-Based Access - 543+ granular permissions across 30+ categories, role-to-permission mapping
• Real-time Communication - 17 ActionCable WebSocket channels for live updates, cross-tab sync
• Modern UI - React 19.1 with Tailwind CSS v4.1, theme system, 10 feature modules
• Content Management - Knowledge base articles, content pages, CMS
• Analytics - Customer health scoring, usage tracking, platform telemetry

AI & Automation (145 models, 431 MCP tool actions)

• AI Agents - Create, deploy, and manage agents with trust scoring and autonomy tiers
• Agent Teams - Multi-agent orchestration (5 strategies: manager_led, consensus, auction, round_robin, priority_based)
• AI Workflows - Visual builder with 35+ node types and circuit breakers
• AI Autonomy - Kill switch, goals, proposals, escalations, feedback, intervention policies, observations, duty cycle
• Code Factory - PRD generation, automated code review, remediation loops
• Ralph Loops - Recursive agent learning with 15-round tool calling
• Model Router - Cost-optimized provider selection across 10+ providers (Anthropic, OpenAI, Ollama, Azure, Google, Groq, Grok, Mistral, Cohere)
• MCP Integration - 431 tool actions for knowledge, memory, skills, RAG, autonomy, Docker, and DevOps
• A2A Protocol - Agent-to-Agent communication with agent cards
• Memory System - 4-tier architecture (working, STM, LTM, shared) with consolidation
• Knowledge Graph - 1,190+ nodes, 1,670+ edges with hybrid search and GraphRAG
• RAG Pipeline - Document chunking, pgvector embeddings, agentic retrieval (3-round reformulation)
• Security Guardrails - Behavioral fingerprinting, 5 input rails, 7 output rails, quarantine
• FinOps - Agent budgets, cost attribution, ROI metrics, optimization logging
• AI Monitoring - Execution traces, telemetry events, circuit breakers, performance benchmarks

DevOps & Infrastructure (43 models)

• Git Integration - GitHub, GitLab, Gitea, Jenkins provider support
• CI/CD Pipelines - 13 step types including AI-powered steps, approval gates
• Container Orchestration - Docker host management, container templates, sandboxed execution
• Docker Swarm - Cluster, node, service, and stack management with deployment tracking
• Integration Framework - 5 integration types (GitHub Actions, webhooks, MCP servers, REST API, custom)
• Supply Chain Security - SBOM generation, attestations, license compliance
• Secrets Management - Vault-backed secrets with rotation tracking

Multi-Platform Chat

• 5 Platforms - WhatsApp, Telegram, Discord, Slack, Mattermost
• AI-Powered Routing - Automatic agent assignment with escalation
• Prompt Injection Protection - Content sanitization with delimiter wrapping

Worker System (220+ jobs, 33 queues)

• Standalone Sidekiq 7.2 - Fully isolated, API-only communication with backend
• 3 Priority Tiers - Critical (weight 3), standard (weight 2), background (weight 1)
• Circuit Breakers - 600s AI workflows, 120s backend API timeouts
• 54 Scheduled Jobs - Maintenance, decay, consolidation, health checks, autonomy, trading

Extensions (4 modules)

Extensions are loaded dynamically via FeatureGateService. When no extensions are present, Powernode runs in core mode — single-user self-hosted with all platform features unlocked.

• Business (extensions/business/) - Billing engine (Stripe/PayPal), BaaS multi-tenancy, reseller system, AI publisher marketplace, predictive analytics
• Trading (extensions/trading/) - Algorithmic trading with strategies, portfolios, risk monitoring, and evolution
• Supply Chain (extensions/supply-chain/) - Supply chain management and logistics
• Marketing (extensions/marketing/) - Campaign management and marketing automation

Distribution & Cloning

Powernode is MIT-licensed throughout. Publicly available components:

• powernode-platform (this repo) — core platform
• powernode-system (github.com/rett/powernode-system) — fleet, mesh, signed module supply chain, on-node Go agent. Mounted at extensions/system/.
• powernode-supply-chain (github.com/rett/powernode-supply-chain) — supply-chain security extension (SBOM workflows, attestations). Mounted at extensions/supply-chain/.
• powernode-marketing (github.com/rett/powernode-marketing) — marketing extension (campaigns, calendar, email lists, social, public landing pages). Mounted at extensions/marketing/.

The business and trading extensions are MIT-licensed but currently maintained in private repositories. Public clones run in core mode — single-user self-hosted, all platform features unlocked — without those extensions.

# Public clone with all public submodules initialized
git clone <repo-url>
cd powernode-platform
git submodule update --init extensions/system extensions/supply-chain extensions/marketing

Running git submodule update --init without the path arguments will additionally attempt to clone the private extensions (business, trading) and produce permission-denied errors. These are safe to ignore if you only need core mode.

Architecture Overview

powernode-platform/
├── server/              - Rails 8.1.2 API (340+ models, 311+ controllers, 634+ services)
│   ├── app/models/      - 10 namespaces (Ai, Devops, Chat, KnowledgeBase, ...)
│   ├── app/services/    - 22+ service namespaces (634+ files)
│   └── app/channels/    - 17 ActionCable channels
├── frontend/            - React 19.1 TypeScript (10 feature modules)
│   └── src/features/    - account, admin, ai, business, content, delegations,
│                          developer, devops, missions, privacy
├── worker/              - Sidekiq 7.2 (220+ jobs, 45 services, 4 API clients)
├── extensions/          - 4 extensions (business, trading, supply-chain, marketing)
├── docs/                - 111 documentation files
└── scripts/             - 48 automation scripts

Technology Stack

• Backend: Rails 8.1.2 | PostgreSQL | UUIDv7 | JWT + OAuth 2.0 | Redis
• Frontend: React 19.1 | TypeScript 5.9 | Vite 7.2 | Tailwind CSS v4.1 | Redux Toolkit + React Query
• Worker: Sidekiq 7.2 | Redis | Faraday | Circuit breakers
• AI/ML: 10+ providers | MCP Protocol | A2A Protocol | pgvector (HNSW)
• Testing: RSpec | Jest 30 | Cypress 15 | 20,600+ tests
• Database: 396+ tables | 10 model namespaces | pgvector embeddings

Prerequisites

• Ruby 3.2.8
• Node.js 18+
• PostgreSQL 15+ (with pgvector extension)
• Redis 7+

Quick Start

For detailed setup instructions, see the Quick Start Guide.

# 1. Install dependencies
cd server && bundle install
cd ../frontend && npm install
cd ../worker && bundle install
cd ..

# 2. Setup database
cd server && rails db:create db:migrate db:seed
cd ..

# 3. Install systemd services (one-time)
sudo scripts/systemd/powernode-installer.sh install

# 4. Start all services
sudo systemctl start powernode.target

# 5. Check status
sudo scripts/systemd/powernode-installer.sh status

Services:

• Frontend: http://localhost:3001
• API: http://localhost:3000
• Worker Web UI: http://localhost:4567

Documentation

Getting Started

• Development Guide - Architecture, namespaces, setup
• Quick Start - Fast setup guide
• CLAUDE.md - Development patterns and rules
• TODO - Current status and roadmap (auto-generated from MCP shared knowledge)

Backend

• Rails Architect - API architecture (Rails 8.1.2, 10 namespaces)
• Data Modeler - Database & ActiveRecord
• Database Schema - 396 tables, namespace reference
• Service Architecture - 634 services, 22 namespaces
• Background Jobs - Job patterns
• Payment Integration - Stripe/PayPal

Frontend

• React Architect - React 19.1, Vite 7.2, Tailwind v4.1
• State Management - Redux Toolkit + React Query
• UI Components - Design system
• Dashboard - Analytics & charts
• WebSocket Integration - Real-time patterns

AI Platform

• AI Orchestration Guide - Complete AI system overview
• AI API Reference - 73 AI controllers
• Code Factory - PRD generation, code review
• Ralph Loops - Recursive agent learning
• Missions - Mission pipeline, 12 phases
• Model Router - Cost-optimized routing
• Agent Autonomy - Kill switch, goals, proposals, escalations, feedback, intervention policies
• Memory System - 4-tier memory architecture
• Security Guardrails - Behavioral fingerprinting
• RAG System - Knowledge bases, hybrid search
• Skill Graph - Skills registry, gap detection
• Cost Attribution - FinOps, budgets, ROI
• Provider Routing - Multi-provider management
• AI Operations - Monitoring, incident runbooks

DevOps & Infrastructure

• DevOps Platform - 43 models, pipelines, containers, Swarm
• Docker Swarm - Cluster operations
• Docker Deployment - Container setup
• Configuration - Env vars, secrets
• Scripts Reference - 48 automation scripts
• DevOps Engineer - CI/CD specialist

Worker

• Worker Architecture - Isolation, API clients, circuit breakers
• Worker Operations - 220+ jobs, 33 queues, scheduling
• CI/CD Architecture - Pipeline execution
• File Processing - File handling subsystem

Platform References

• Changelog - Release history
• Permission System - 543+ permissions, 30+ categories
• WebSocket Channels - 17 channels reference
• Chat System - Multi-platform chat
• Content Management - KB articles, pages, CMS
• Theme System - Tailwind v4.1 theming
• API Standards - API conventions
• UUID System - UUIDv7 across 340+ models
• MCP Configuration - MCP server setup and OAuth
• MCP Tool Catalog - 431 tool actions across 57 tool classes
• Workflow System - Workflow patterns
• Node Executors - 35+ workflow node types

Security

• Security Specialist - Security architecture
• Supply Chain Security - SBOM, attestations, compliance

Testing

• Backend Testing - RSpec strategies
• Frontend Testing - Jest + React Testing Library
• E2E Testing - Playwright patterns

Business

• Business Overview - Billing, BaaS, reseller, AI publisher

Contributing

Powernode follows strict architectural patterns and enforces them through automated tooling.

Getting Oriented

1. Read CLAUDE.md for development guidelines and conventions
2. Check docs/TODO.md for current priorities (auto-generated from MCP shared knowledge)
3. Review the specialist documentation for your area (see Documentation above)

Branch Strategy

develop → feature/* → release/* → master

• Create feature branches from develop
• Release branches follow release/x.y.z naming (no "v" prefix)
• Tags use bare semver: 0.2.0, not v0.2.0

Before Submitting

# Backend: run specs
cd server && bundle exec rspec --format progress

# Frontend: run tests + type check
cd frontend && CI=true npm test
cd frontend && npx tsc --noEmit

# Full validation (specs + TS + pattern checks)
./scripts/validate.sh

All tests must pass. Permissions must use the permission system (never role-based checks). Frontend must use theme classes (bg-theme-*, text-theme-*) — no hardcoded colors.

License

MIT License — see LICENSE for full text.