FastAPI + Multi-Model AI • Self-Hosted • GritWerk

M3SHD

Distributed AI Mesh Platform

Your AI agents. Your hardware. Your mesh. A FastAPI hub coordinates Claude, Grok, and Codex workers across Mac Minis, Raspberry Pis, cloud VPS, and mobile devices.

12 registered agents
4 hardware types
3 AI models
1,500+ tests passing
21 features shipped

Dispatch. Execute. Verify.

Three stages, zero babysitting. The mesh handles routing, execution, and multi-model validation automatically.

Stage 01

Dispatch

Tasks submitted via API, MCP tools, iMessage bridge, or the dashboard. Natural language prompts dispatched to capable workers based on declared capabilities and current load.

Stage 02

Execute

Workers pull tasks matched to their capabilities. Claude, Grok, or Codex processes the prompt. Results are signed with HMAC-SHA256 provenance by the hub on completion.

Stage 03

Verify & Learn

Multi-model review pipeline audits code_write outputs: a three-model gate (Sentinel, Codex, Grok) for production tasks, two-model flow for routine work. Agent memory stores learnings in FTS5-indexed encrypted storage. UCB reputation scoring ranks worker reliability over time.

M3SHD hub-and-spoke architecture: central hub with radiating worker nodes across multiple hardware types

Hub-and-spoke,
fully self-hosted

Central hub on Hetzner VPS running FastAPI + SQLite WAL. Workers self-register, declare capabilities, and report via heartbeat. The hub never pulls; workers drive their own lifecycle and request tasks when ready.

SSE streams real-time task events to the dashboard with no polling. The MCP server exposes the entire fleet as callable tools inside Claude Code and Claude Desktop: dispatch tasks without leaving your editor.

Federation links independent hubs into a wider mesh; tasks relay across hub boundaries with loop prevention. Stigmergy traces and Theory of Mind beliefs let the hub route intelligently without centralized planning.

FastAPI + SQLite WAL SSE real-time events MCP server HMAC provenance DAG pipelines RBAC auth iMessage bridge Federation Stigmergy Kill Switch Tool Forge Defense

12 agents across 4 hardware types

From Raspberry Pi 5s to cloud VPS: any machine that can run Python becomes a mesh worker.

Raspberry Pi 5 with holographic data projections representing the M3SHD mesh in hardware form

12 online  ·  0 offline  ·  0 busy  ·  Mac Mini M2  ·  Pi 5  ·  Hetzner VPS  ·  Mobile

Mac Minis

archon Mac Mini M2 / orchestration
opus-listener Mac Mini M2 / code write, review, voice
rex Mac Mini M2 / research, file ops, git

Hetzner VPS

cloud-1 research, web search, heavy tasks
codex-1 Codex review
grok-1 Grok review
sentinel-1 code review

Pi 5 Cluster

n0d3-0 Pi 5 2GB / research, web, code write
n0d3-1 Pi 5 1GB / research, web, code write
n0d3-2 Pi 5 1GB / research, web, code write
n0d3-3 Pi 5 1GB / research, web, code write

Mobile

Mobile-N0D3-3 Sonim XP8800 / research, summarize, triage

Everything you need to run a real mesh

Purpose-built primitives for distributed multi-model AI work.

Multi-Model AI

Claude, Grok, and Codex workers in a single mesh. Production code is reviewed by a three-model gate (Sentinel, Codex, and Grok in parallel) where all three must pass. A cost optimizer routes tasks across three Claude tiers (haiku for lightweight ops, sonnet for most work, opus for architecture and security) based on complexity signals in the prompt.

iMessage Bridge

Dispatch tasks from your phone by texting the hub. A Python daemon reads chat.db, routes through the hub, and replies via osascript. Natural-language commands also operate the entire fleet: trust levels, autonomy, kill switch, and memory consolidation all respond to plain-text chat. No cloud relay. No third-party service.

DAG Pipelines

Tasks declare dependencies forming execution graphs. Parent output flows into child prompts under explicit injection control: escaped, delimited, and author-authorized, so a compromised worker cannot steer downstream prompts. One API call chains research → summarize → notify.

Agent Memory

FTS5-indexed, Fernet-encrypted knowledge per agent. Extracted from task output and auto-injected into future prompts. MultiFernet key rotation re-encrypts the store to a new primary key without downtime or lost history. Twice-daily consolidation merges learnings across the fleet.

UCB Reputation

Upper Confidence Bound scoring balances task success history against exploring underutilized nodes. Circuit breakers remove failing workers from rotation without manual intervention.

MCP Integration

Expose the entire mesh as callable tools inside Claude Code and Claude Desktop. Dispatch tasks, poll status, query memory, all without leaving your editor. An event-driven plugin system hooks external modules into task lifecycle events, with optional FCM push to registered mobile devices.

RBAC Auth

Role-based access with scoped API tokens and multi-user support. 25 permissions across 4 role presets. Zero-permission tokens denied by default. Per-agent tokens scoped to declared capabilities only.

Cryptographic Provenance

Every result signed with HMAC-SHA256. Multi-step pipelines form a signed receipt chain; on-demand verification at /api/tasks/{id}/provenance detects tampering at any point in the chain. Optional per-agent Ed25519 keys provide worker-attributable authorship.

Daily Blog

The mesh writes its own blog post every day from real analytics. Task throughput, model performance, learnings from the last 24 hours, synthesized and published automatically. The fleet narrates itself.

Federation

Peer hub relay connects independent M3SHD instances into a federated mesh. Tasks route across hub boundaries with 3-hop loop prevention. Each hub retains sovereignty: federation is opt-in, not hierarchical.

Stigmergy

Ant Colony Optimization pheromone traces guide task routing without central planning. Workers deposit success signals that decay exponentially; the mesh learns which paths work by following the traces others leave behind.

Kill Switch

Three-mode emergency halt: graceful (finish current step and checkpoint), circuit-break (drain queues and hold new work), or hard-kill (stop immediately and capture forensic state). Engaged from dashboard, API, or iMessage. The mesh resumes exactly where it stopped.

Adaptive Defense

Four-tier threat posture (green, yellow, orange, red) with automated IP bans, rate limiting, and incident correlation. Threat events from workers feed a centralized response engine. Escalates autonomously, de-escalates on evidence.

Theory of Mind

Three-layer belief system tracks what each agent knows, can do, and is working on. Routing decisions factor in not just load and capability, but the hub's model of each agent's current cognitive state and strategic alignment.

Tool Forge

When no existing tool fits, the LLM writes one. Generated Python code is AST-validated and sandboxed with 5-second timeouts. Tools earn trust tiers (untrusted, trusted, verified) through successful execution history.

Fleet Watchdog

Rolling-window error rates and p95 latency per worker. Agents exceeding thresholds are automatically quarantined and probed for recovery. Mobile workers that lose connectivity hand off in-progress tasks; partial output is preserved and a continuation dispatched to the next available agent. SSE events stream all state changes in real time.

Blackboard

Shared working memory for multi-agent collaboration. Agents post typed entries to named boards, trigger synthesis when enough evidence accumulates, and read each other's findings. TTL-based garbage collection keeps boards clean.

Recursive Self-Improvement

Gap detection identifies missing capabilities. The LLM generates new skills to close them, gated by four safety checks and a circuit breaker. An Actor-Curator bandit selects which gaps to close first. Goal inference generates new objectives from live mesh state and automatically tasks idle workers; the mesh decides what to do next.

Voice Dispatch

Siri Shortcuts are a first-class task source: voice:siri tasks enter the same dispatch pipeline as API and iMessage submissions (one-time webhook configuration on the hub). An ntfy push notification delivers the result to your phone when the worker finishes.

Metacognition

Every dispatched task carries a confidence instruction: agents report 0.0-1.0 self-scores. Results below 0.5 automatically trigger a verification task. The confidence score feeds the worker's UCB reputation weight and Theory of Mind beliefs.

Multi-Agent Deliberation

Three primitives for collective decisions. Debate fans eligible tasks to two independent agents and synthesizes their analyses with a third; voting reaches majority consensus using lightweight haiku-class agents. Adversarial review automatically dispatches a challenger when confidence falls below threshold. A second agent audits the result and flaws trigger a revision back to the original agent.

Run it on your own hardware

M3SHD runs entirely on machines you own. Spare Macs, a Pi cluster, a cloud VPS, even a rugged phone: if it can run Python, it joins the mesh. Configure your workers and start dispatching from the terminal or your iMessage thread.

Get in Touch

Python · FastAPI · SQLite · Claude API · Grok API · Codex API