Architecture Overview
Note: this document mixes current implementation details with target architecture. For the most code-accurate view of local routes and workflows, prefer
README.md,docs/README.md, andsrc/api/routes/.
mutx.dev is "The Vercel for production AI agents" — a platform that deploys autonomous agents to dedicated VPCs with zero-trust security and zero token markup.
High-Level Architecture
┌─────────────────────────────────────────────────────────────────────────────────┐
│ CLIENTS │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────┐ │
│ │ Web Dashboard │ │ Mobile App │ │ API Clients (SDK/CLI) │ │
│ │ (Next.js) │ │ (React) │ │ │ │
│ └────────┬────────┘ └────────┬────────┘ └──────────────┬──────────────┘ │
└───────────┼──────────────────────┼──────────────────────────────┼───────────────┘
│ │ │
│ HTTPS/WSS │ HTTPS │ HTTPS
│ │ │
▼ ▼ ▼
┌───────────────────────────────────────────────────────────────────────────────────┐
│ EDGE LAYER │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ Vercel CDN + Railway Load Balancer │ │
│ │ - TLS termination │ │
│ │ - Rate limiting │ │
│ │ - DDoS protection │ │
│ └──────────────────────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────────────────────┐
│ CONTROL PLANE (mutx API) │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ FastAPI Backend (Python) │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────────────────┐│ │
│ │ │ Auth │ │ Agents │ │ Deployments│ │ Webhooks ││ │
│ │ │ Service │ │ Service │ │ Service │ │ Handler ││ │
│ │ └────────────┘ └────────────┘ └────────────┘ └──────────────────────┘│ │
│ │ │ │
│ │ ┌────────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Core Services │ │ │
│ │ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────────────┐ │ │ │
│ │ │ │ Agent Runtime │ │ Self-Healing │ │ Monitoring │ │ │ │
│ │ │ │ Service │ │ Service │ │ Service │ │ │ │
│ │ │ └────────────────┘ └────────────────┘ └────────────────────────┘ │ │ │
│ │ └────────────────────────────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────┴─────────┐ │
│ │ PostgreSQL │ Redis Cache │
│ │ (Metadata) │ (Sessions, Queue) │
│ └───────────────────┘ └─────────────────┘ │
└───────────────────────────────────────────────────────────────────────────────────┘
│
│ Terraform Provisioning
▼
┌───────────────────────────────────────────────────────────────────────────────────┐
│ TENANT VPCs (Per-Customer) │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ 10.0.1.0/24 - Agent Subnet │ │
│ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Dedicated Agent 10 Cluster │ │ │
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │
│ │ │ │ Agent 01 │ │ Agent 02 │ │ Agent 03 │ │ Agent N │ │ │ │
│ │ │ │ (LangChain)│ │ (OpenClaw) │ │ (n8n) │ │ │ │ │ │
│ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ └────────────────┴────────────────┴────────────────┘ │ │ │
│ │ │ │ │ │ │
│ │ │ ┌──────┴──────┐ │ │ │
│ │ │ │ EvalView │ ─── Local LLM Judge │ │ │
│ │ │ │ Guardrail │ (Hypervisor-level security) │ │ │
│ │ │ └─────────────┘ │ │ │
│ │ └─────────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────────┐ │ │
│ │ │ PostgreSQL │ │ Redis │ │ Tailscale │ │ │
│ │ │ (pgvector) │ │ Cache │ │ ZTNA Mesh │ │ │
│ │ └────────────────────┘ └────────────────────┘ └────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────────────────────┘
Core Components
1. Control Plane (mutx API)
| Component | Technology | Purpose |
|---|---|---|
| API Gateway | FastAPI | REST/WS endpoints, auth, rate limiting |
| Agent Runtime | Python/AsyncIO | Agent lifecycle, execution, tool routing |
| Self-Healing Service | Python | Auto-recovery, health checks, version management |
| Monitoring Service | Python | Metrics, alerting, uptime tracking |
| Auth Service | JWT + bcrypt | Token management, OAuth2 |
Autonomous Dev Lane
MUTX v1.4 ships an autonomous dev lane for agentic workflows. This enables coding agents to operate against the MUTX platform with role-scoped credentials, RBAC-enforced boundaries, and OIDC-validated identity — allowing safe autonomous execution, PR creation, and deployment workflows.
2. Agent Runtime
The AgentRuntime class (src/api/services/agent_runtime.py:98) manages:
- Agent Creation: Factory pattern for LangChain, OpenClaw, n8n agents
- Execution: Async/sync execution with timeout control
- Tool Routing: Dynamic tool registration and execution
- State Management: Runtime state, execution context, metrics
3. Agent Types
| Type | Framework | Use Case |
|---|---|---|
| LangChain Agent | LangChain + LangGraph | General-purpose LLM agents |
| OpenClaw Agent | OpenClaw | Multi-agent orchestration |
| n8n Agent | n8n | Workflow automation |
4. Data Layer
- PostgreSQL: Metadata, agent configs, pgvector for semantic search
- Redis: Caching, session storage, message queue
- Vector Store: pgvector embeddings for RAG
Data Flow
Agent Execution Flow
┌──────────┐ ┌──────────┐ ┌───────────────┐ ┌─────────────────┐
│ Client │────▶│ API │────▶│ Agent Runtime │────▶│ Tool Handler │
│ Request │ │ Gateway │ │ (AsyncIO) │ │ (Tools/RAG) │
└──────────┘ └──────────┘ └───────┬───────┘ └────────┬────────┘
│ │
▼ ▼
┌───────────────┐ ┌─────────────────┐
│ EvalView │◀────│ LLM Provider │
│ Guardrail │ │ (OpenAI/Anthropic/
│ (Local Judge) │ │ Ollama) │
└───────────────┘ └─────────────────┘
│
▼
┌───────────────┐
│ Response to │
│ Client │
└───────────────┘
Deployment Flow
┌──────────┐ ┌──────────────┐ ┌───────────────┐ ┌─────────────────┐
│ User │────▶│ API Request │────▶│ Terraform │────▶│ Ansible │
│ Deploy │ │ (Create VPC)│ │ Provisioner │ │ (Configure) │
└──────────┘ └──────────────┘ └───────┬───────┘ └─────────────────┘
│ │
▼ ▼
┌──────────────┐ ┌─────────────────┐
│ VPC Created │ │ Agent Deployed │
│ (DigitalOC) │ │ (Docker + ZTNA) │
└──────────────┘ └─────────────────┘
Kubernetes/Helm Deployment
For Kubernetes environments, MUTX ships a Helm chart in infrastructure/helm/mutx/:
helm install mutx infrastructure/helm/mutx \
--set secrets.databaseUrl=$DATABASE_URL \
--set secrets.oidcIssuer=$OIDC_ISSUER
See infrastructure/helm/mutx/README.md for full configuration options.
Security Model
Zero-Trust Architecture
- ZTNA Mesh: Tailscale-based zero-trust networking
- No exposed ports to public internet
- WireGuard encrypted tunnels
- mTLS for service-to-service auth
- EvalView Guardrails: Hypervisor-level security
- Local LLM judge evaluates all inputs/outputs
- Prompt injection detection
- Output sanitization
- Behavioral anomaly detection
- BYOK (Bring Your Own Keys)
- Customer provides their own API keys
- Zero token markup
- Keys never stored in plaintext (HashiCorp Vault)
- Network Isolation
- Single-tenant VPCs
- Firewall rules (UFW)
- Security groups per subnet
- No cross-tenant communication
Security Layers
| Layer | Technology | Protection |
|---|---|---|
| Network | Tailscale, UFW, VPC | Port isolation, encrypted tunnels |
| Application | JWT, OAuth2, RBAC, OIDC | Authentication, authorization |
| Data | Vault, encryption at rest | Secret management, key protection |
| Runtime | EvalView, containers | Input/output validation, sandboxing |
| Monitoring | Auditd, fail2ban | Intrusion detection, logging |
Infrastructure Provisioning
Terraform + Ansible Pipeline
- Terraform: Creates VPC, networking, compute
- Ansible: Configures OS, Docker, services
┌─────────────────┐
│ Terraform │
│ ┌───────────┐ │
│ │ VPC │ │
│ │ Subnets │ │
│ │ Security │ │
│ │ Groups │ │
│ └───────────┘ │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Ansible │
│ ┌───────────┐ │
│ │ Docker │ │
│ │ PostgreSQL│ │
│ │ Redis │ │
│ │ Tailscale│ │
│ │ UFW │ │
│ └───────────┘ │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Agent 10 │
│ Swarm Ready │
└─────────────────┘
Technology Stack
| Layer | Technology |
|---|---|
| Frontend | Next.js 16, React 18, TypeScript, Tailwind CSS |
| Backend | FastAPI, Python, SQLAlchemy, AsyncIO |
| Database | PostgreSQL 15, Redis, pgvector |
| Agents | LangChain, OpenClaw, n8n, LangGraph |
| IaC | Terraform, Ansible |
| Cloud | DigitalOcean |
| Orchestration | Kubernetes, Helm |
| Networking | Tailscale ZTNA |
| Security | HashiCorp Vault, UFW, fail2ban |
| Deploy | Railway, Vercel |