Skip to content
Mahoosuc OS Documentation

Mahoosuc OS Architecture Overview

Mahoosuc Operating System (MOS) is the AI infrastructure a company runs on — tunable to any business vertical, operated in natural language, and proved first on itself.

This page explains the runtime architecture: how a customer request enters MOS, how it is classified and routed, and how it becomes a working solution or a deployed update.

The Five-Layer Picture

Customer (natural language)
        │
        ▼
┌───────────────────────────────┐
│       CX Chat Sidecar         │  ← natural-language front door
│  Port 3060 / mos-network only │     fields, logs, classifies
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│         Agent Mahoo (V2)      │  ← orchestrator / classifier
│   deployment orchestrator      │     replaced Agent Jumbo (V1)
└───────┬───────────────┬───────┘
        │               │
  UPDATE PATH     BUILD PATH
        │               │
        ▼               ▼
┌───────────┐   ┌───────────────────┐
│  Mahoo    │   │  Maestro (ODD)    │  ← net-new build conductor
│  handles  │   │  idea→PRD→plan→   │     inspired by Archon
│  end-to-  │   │  implement→verify │
│  end      │   │  →PR→ship         │
└───────────┘   └───────────────────┘

The CX Sidecar

The CX Chat Sidecar (services/cx-chat-sidecar/) is the natural-language front door to MOS. Every customer request — whether typed in a portal, submitted via API, or uploaded as a screenshot — enters through the sidecar.

The sidecar:

  • Fields every request and logs it against customer + product + deployment context
  • Classifies the request using AI (Claude Haiku by default, Ollama for local/CI)
  • Exposes four tools: search_knowledge_base, create_support_ticket, get_ticket_status, analyze_screenshot
  • Runs on port 3060, accessible only within the Docker network — no external port binding
  • Holds Anthropic API keys in isolation (per-tenant keys via x-anthropic-key header, resolved from Vault by aios-backend)
  • Enforces rate limits independently from the main backend (MAX_AI_RPM=50)

The sidecar never writes to the main database directly. create_support_ticket returns an action payload that aios-backend executes, preserving the sidecar’s isolation.

Agent Mahoo — The V2 Orchestrator

Agent Mahoo is the orchestration layer that replaced Agent Jumbo (V1). Mahoo receives the classified request from the sidecar and decides the routing path.

Mahoo’s two paths:

ClassificationWhat Mahoo does
Update to existing deploymentMahoo handles end-to-end via its deployment orchestrator. Changes are applied, validated, and confirmed without leaving Mahoo’s runtime.
Net-new build-outMahoo hands the request to Maestro, the ODD conductor, which scaffolds the idea-to-ship workflow.

The same routing loop governs onboarding: as a customer’s employees are led through event-driven workflows, MOS is stood up around them. Each workflow activation is an update or a build — routed by Mahoo identically.

Maestro and Outcome Driven Development

Maestro is the conductor for net-new product build-outs. It implements Outcome Driven Development (ODD) — inspired by Archon — which governs how MOS turns architectural intent into a working solution.

ODD principles:

  • Every unit of work traces to a named outcome
  • Each task is independently deliverable (no hidden dependencies)
  • Convergence gates run before any task ships (test pass, contract validation, security check)
  • The customer gives architectural direction; Maestro and its sub-agents handle technical choices

Maestro’s idea-to-ship stages:

  1. Intake — Customer describes what they need in natural language
  2. PRD — Maestro generates a Product Requirements Document from the intake
  3. Plan — ODD task plan with named outcomes and convergence criteria
  4. Implement — Sub-agents execute tasks (implementer agent, qa-engineer, etc.)
  5. Verify — Convergence gate: tests pass, contracts validate, security gates clear
  6. PR — Pull request created with full audit trail
  7. Ship — Deployment via Mahoo’s deployment orchestrator

Interview-Driven Onboarding

MOS onboards customers by conducting an interview through its own agents — the onboard:business skill, the business-ops agent, and interview surfaces in aios-backend. The interview produces live configuration, not a static plan.

This is dogfooding applied to customer onboarding: the same agent infrastructure that runs customer businesses is the same infrastructure used to onboard them.

As each employee completes their interview steps, event-driven workflows activate and the operating system extends itself around them. The result is a running system, not a requirements document.

Per-Product Vertical Agents

Each MOS product (ContentStudio, SalesOS, DevFlow, BookingFlow, etc.) can host a customer-scoped agent that holds the customer’s business context for that product’s concerns.

Combined with the per-role Board of Advisors (CFO, COO, CMO, CTO, Legal, Strategic, Life Coach, Second Brain), this creates a role × vertical matrix of context. Each agent has:

  • Scope-limited tool access enforced by the MCP Gateway
  • Per-deployment memory (customer’s data, not shared)
  • Audit logging for every action taken

Security Architecture

ComponentSecurity property
CX SidecarPer-tenant API keys via Vault; read-only DB; rate-limited; internal-network-only
MCP GatewayTool allowlists per agent scope; enforcement at the tool boundary
MahooActions logged before and after execution; convergence gates before ship
MaestroEach ODD task is an auditable unit; convergence gate before PR
All agentsRBAC-scoped; consent checked before any data access; tamper-evident audit log

The Full Loop

Customer types a request
        │
        ▼
CX Sidecar (port 3060)
  ├── search_knowledge_base  → direct answer
  ├── create_support_ticket  → action handed to aios-backend
  ├── get_ticket_status      → lookup + response
  └── analyze_screenshot     → structured analysis + ticket offer
        │
        ▼
cxProblemReportPipeline.ts (aios-backend)
  └── categorize → enrich → dispatch to AgentMesh
        │
        ▼
Agent Mahoo (V2)
  ├── UPDATE: Mahoo deployment orchestrator → deploy → confirm
  └── BUILD:  Maestro (ODD) → PRD → plan → implement → verify → PR → ship
        │
        ▼
SSE stream back to customer portal
(real-time progress: CX_PROBLEM_ANALYZING → … → CX_PROBLEM_VERIFIED)