Open infrastructure to deploy, operate, and study governed, long-lived (“alive”) AI systems.
Matrix-Infra is the deployment and operations reference for the Agent-Matrix ecosystem.
Its purpose is to make alive AI systems practical to run, inspect, govern, and evolve in real environments.
This repository does not define new algorithms or models; it defines how a complex, long-running AI system is assembled and operated safely.
Matrix-Infra focuses on:
- Continuous, long-lived operation (not one-shot pipelines)
- Governance-first autonomy with human oversight
- Explicit, auditable infrastructure and configuration
- Reproducible deployments across local and cloud environments
- Clear separation of responsibilities between system components
This is an open-source infrastructure and research project.
It is not a commercial product, not a hosted service, and not marketed for sale.
The intent is to provide a serious, public reference implementation for building and operating alive AI systems in a disciplined, inspectable way.
An alive AI system is not simply an inference endpoint or a workflow runner.
It is a governed, continuously operating system that can:
- Discover agents, tools, and capabilities dynamically
- Reason and plan based on goals, failures, and system state
- Make decisions under explicit policy and risk constraints
- Execute actions with controlled automation and approvals
- Verify outcomes and retain reusable knowledge over time
Agent-Matrix decomposes these responsibilities into specialized services, each with a clearly defined role and trust boundary.
Matrix-Infra orchestrates the deployment of the following services:
| Component | Responsibility in the alive loop | Primary repository |
|---|---|---|
| Matrix Hub | Catalog, registry, discovery, install plans (“system memory”) | agent-matrix/matrix-hub |
| Matrix Guardian | Governance, policy enforcement, approvals, health monitoring | agent-matrix/matrix-guardian |
| Matrix AI | Planning, remediation, and reasoning | agent-matrix/matrix-ai |
| Matrix Architect | High-risk execution, system evolution, controlled automation | agent-matrix/matrix-architect |
| Matrix Treasury | Resource accounting and economic constraints | agent-matrix/matrix-treasury |
| Admin UI & Network | Operational visibility and agent discovery | matrix-hub-admin, network.matrixhub |
Matrix-Infra does not redefine these services; it codifies how they are built, deployed, and operated coherently.
Matrix-Infra supports two complementary deployment modes.
Intended for:
- end-to-end development
- integration testing
- architecture exploration
- governance and safety experiments
Characteristics:
- Kubernetes manifests with Kustomize overlays
- Optional local LLM inference using Ollama
- No external cloud dependencies required
Intended for:
- early production-like environments
- long-running validation
- CI-driven image builds
Characteristics:
- Docker Compose for operational simplicity
- GitHub Actions for reproducible image builds (GHCR / Docker Hub)
- Designed to evolve toward full Kubernetes clusters later
Once you've deployed the Agent-Matrix infrastructure, you'll interact with it using two complementary tools:
Matrix CLI is the client-side command-line interface for discovering, installing, and running agents, tools, and MCP servers.
Use Matrix CLI for:
- 🔍 Discovery: Search and explore available agents, tools, and MCP servers
- 📦 Installation: Install and manage packages locally
▶️ Execution: Run MCP servers and agents locally or attach to remote services- 🔧 Interaction: Probe and invoke tools via CLI commands
- 📊 Process Management: Monitor running services with
matrix ps
Installation:
# Recommended: Install with pipx for isolation
pipx install matrix-cli
# Or with pip
pip install matrix-cliQuick Usage:
# Search for MCP servers
matrix search "hello" --type mcp_server
# Install an MCP server
matrix install hello-sse-server --alias hello-sse
# Run the server
matrix run hello-sse --port 6288
# Interact with tools
matrix do hello-sse "Your question"
# View running services
matrix ps
# Stop a service
matrix stop hello-sseMatrix System SDK is a production-ready Python SDK and CLI for monitoring and managing your deployed infrastructure services.
Use Matrix System for:
- 💚 Health Monitoring: Check service health with scoring and status assessment
- 📋 Event Tracking: Monitor plan creation and system actions
- ✅ Proposal Management: Handle risk assessment for automated decisions
- 🔐 Governance: Manage approvals and policy enforcement
- 🐍 Python Integration: Embed Matrix operations in Python applications
Installation:
# Recommended: Install with uv
uv pip install matrix-system
# Or with pip
pip install matrix-systemQuick Usage:
# Configure environment variables
export MATRIX_HUB_URL="http://your-matrix-hub-url"
export MATRIX_AI_URL="http://your-matrix-ai-url"
export MATRIX_GUARDIAN_URL="http://your-matrix-guardian-url"
export ADMIN_TOKEN="your-admin-token"
# Check health of all services
matrix health check --all
# List registered agents
matrix agent list
# Register a new agent
matrix agent register --name my-agent --type generalPython SDK Usage:
from matrix_system import MatrixHub, MatrixAI, MatrixGuardian
# Initialize clients
hub = MatrixHub()
ai = MatrixAI()
guardian = MatrixGuardian()
# Register an agent
agent = hub.register_agent(name="my-agent", agent_type="general")
# Check health
health = hub.health_check()
print(f"Hub health score: {health.score}")
# Track events
events = hub.get_events(limit=10)| Task | Tool |
|---|---|
| Search and install MCP servers/agents | Matrix CLI |
| Run local MCP servers | Matrix CLI |
| Monitor infrastructure health | Matrix System |
| Manage governance proposals | Matrix System |
| Track system events | Matrix System |
| Python automation scripts | Matrix System SDK |
For comprehensive documentation, see: docs/client-tools.md
Get Agent-Matrix running in 15-30 minutes:
# 1. Check your system
make preflight
# 2. Deploy (choose one)
make deploy-minikube # Local development (MiniKube)
make deploy-docker-compose # Cloud VM (Docker Compose)
# 3. Verify
make health-check# MiniKube (legacy)
make install-minikube
# Docker Compose (legacy)
make install-oracle📖 For detailed step-by-step instructions, see: QUICKSTART.md
Documentation:
- Quick Start: QUICKSTART.md - Get running in 15-30 minutes
- MiniKube:
docs/quickstart-local-minikube.md- Detailed local deployment - Cloud VM:
docs/quickstart-oracle.md- Detailed cloud deployment - Scripts: scripts/README.md - Script documentation
Matrix-Infra provides structured workflows for operators and contributors:
Production Workflows (Recommended):
make preflight— validate system requirements before deploymentmake deploy-minikube— one-command deployment to MiniKube with validationmake deploy-docker-compose— one-command deployment to Docker Compose with validationmake health-check— verify deployment and service healthmake generate-secrets— generate production-ready secure secrets
Legacy Workflows:
make help— discover available commands and workflowsmake build— build all Agent-Matrix container images locallyscripts/install.sh— interactive installer (local vs cloud)scripts/setup_minikube.sh— dependency checks and local setup
See: scripts/README.md for detailed script documentation
The goal is to reduce ambiguity and make system behavior reproducible.
This repository includes a MkDocs configuration and a professional documentation skeleton.
- Serve documentation locally:
mkdocs serve- Build static documentation:
mkdocs buildDocumentation covers architecture, deployment, governance, and roadmap.
See mkdocs.yml and the docs/ directory.
Matrix-Infra is structured for environments where inspection and control matter:
- Explicit configuration (no hidden runtime defaults)
- Clear separation of concerns between services
- Least-privilege networking and secret scopes
- Reproducible builds via CI workflows
- Human-in-the-loop enforcement by default
This repository should be reviewed and treated as infrastructure code.
matrix-infra/
apps/ # Kubernetes manifests per service
platforms/ # Environment overlays (minikube, oracle)
scripts/ # Install and build helpers
docs/ # MkDocs content and operational guides
todo/ # Known gaps and hardening checklist
Matrix-Infra is an open research and infrastructure effort.
High-value contributions include:
- hardening Kubernetes overlays
- improving security defaults
- strengthening CI reproducibility
- clarifying audit trails and runbooks
- improving documentation clarity
Apache-2.0 (unless a sub-repository states otherwise).