M3SHD

How It Works

Text a command. The mesh handles the rest.

N0D3S self-register with the Commander, report capacity in real time, and pull tasks matched to their capabilities. The iMessage bridge makes the whole fleet reachable from a text message.

Step 01

Natural Language Control

A daemon on the primary Mac watches chat.db and relays your iMessage to the Commander. No third-party services. No cloud intermediary. Direct SQLite read, osascript reply.

Step 02

Capability-Aware Dispatch

The Commander matches tasks to N0D3S by declared capabilities and open slot count. N0D3S push heartbeats on their own schedule. Circuit breakers pull unhealthy nodes from rotation automatically, without manual intervention.

Step 03

Execute and Reply

The N0D3 runs Claude CLI, captures output, and POSTs the signed result back to the Commander. The Commander relays to your iMessage thread. Token usage is logged per task, per agent, with configurable daily caps and spend alerts.

╔══════════════════════════════════╗
║  m3shd.gritwerk.com               ║
║  M3SHD Commander  ·  SQLite WAL      ║
║  RBAC · SSE · DAG Pipelines      ║
║  Plugins · Federation · MCP      ║
╚══╤══════╤══════╤══════╤════════╝
   │      │      │      │
   ▼      ▼      ▼      ▼
Primary  Rex  Crucible  N0D3×Pi
M2 Mac  Intel  iMac    Pi 5
5 slots 2 slots 3 slots 2 slots
   │
   ▼
╔═════════════╗
║ iMessage     ║  ←── osascript
║ Bridge       ║  ←── chat.db
╚═════════════╝

Hub-and-spoke, fully self-hosted

The Commander is the single source of truth. N0D3S self-register on boot, declare their capabilities, and report open slots via heartbeat. The Commander never pulls — N0D3S drive their own lifecycle and request tasks when ready. SSE streams real-time task events to the dashboard.

The iMessage bridge runs as a multi-threaded daemon, routing bidirectionally via the Commander. The MCP server exposes the entire fleet as callable tools inside Claude Code and Claude Desktop — dispatch tasks without leaving your editor.

Primary Mac Mini M2 · iMessage bridge · 5 slots

Rex Mac Mini Intel · Research & file ops · 2 slots

Crucible iMac 27" · Overflow compute · 3 slots

N0D3-HUB Pi 5 2GB · Hub node · custom enclosure

N0D3 ×3 Pi 5 1GB · N0D3S · provisioning

Features

Everything you need to run a real mesh

Purpose-built primitives for distributed AI work: task dispatch, agent memory, dependency pipelines, federation, and a plugin system to extend any of it.

iMessage Bridge

Multi-threaded Python daemon reads chat.db and relays to the Commander, replies via osascript. Image attachments dispatched with magic-byte verification. Schema version detection handles macOS differences.

Agent Memory

FTS5-indexed, Fernet-encrypted key/value memory per agent. Extracted from [REMEMBER] blocks in task output and auto-injected into future prompts. Nightly consolidation merges duplicates across agents.

DAG Pipelines

Tasks declare dependencies forming execution graphs. When a parent completes, its output is injected into child prompts and they dispatch automatically. One API call defines a chained research → summarize → notify pipeline.

Adaptive Agents

Agents track their own performance over a rolling window. Periodically, Claude Haiku analyzes outcomes and proposes prompt amendments. Operator reviews and applies with one click. Performance data persists in the agent memory store.

UCB Reputation Scoring

Workers accumulate a reputation score using the Upper Confidence Bound formula, balancing task success history against exploration of underutilized nodes. Circuit breakers remove failing workers from rotation without manual intervention.

Plugin System

Agents invoke tools mid-task via [TOOL_CALL] markers. Built-in plugins: web search, file summary, ntfy notifications, memory enhancement. Custom plugins via setup(manager).

RBAC + Multi-User Auth

17 permissions across 4 role presets (worker / mobile / commander / admin). PBKDF2-SHA256 accounts with configurable session TTL. Per-agent API tokens with scoped permissions. Zero-permission tokens denied access by default.

Federation Relay

Hub-to-hub task relay for overflow routing. Register peer hubs and tasks dispatch across mesh boundaries when local capacity is exhausted. Max hop limit prevents relay loops. Cost accounting tracks cross-hub overhead.

Cryptographic Provenance

Every task result signed with HMAC-SHA256. Multi-step pipelines form a Merkle chain — any tampered output breaks verification. GET /api/tasks/{id}/provenance reconstructs the full chain.

MCP Server (17 Tools)

Claude Code and Claude Desktop treat the entire agent fleet as callable tools. Dispatch tasks, poll status, query memory, approve actions — without leaving your editor. The mesh becomes a native part of the AI's toolset.

Token Budget Control

Input and output tokens logged per task, per agent. Configurable daily caps with ntfy spend alerts. Spend analytics by agent, capability, and date. Budget commands available directly from iMessage.

Real-Time Dashboard

SSE-driven live view of task queue, worker capacity, and agent status. No page refreshes. Webhook integrations with GitHub and Uptime Kuma feed events directly into the task pipeline for automated response workflows.

Hardware

Runs on real machines you already own

M3SHD is designed for heterogeneous hardware. Desktop Macs handle compute-heavy tasks. Raspberry Pi 5 nodes expand the mesh at low cost, housed in custom 3D-printed N0D3 enclosures.

Desktop N0D3S

🖥

Mac Mini M2 Primary compute · iMessage bridge · 5 concurrent slots

🖥

Mac Mini (Intel) Research & file operations · 2 concurrent slots

🖥

iMac 27" (Intel) Overflow compute · 3 concurrent slots

🖨

Bambu Lab X1C Manufacturing N0D3 enclosures on-demand

Pi 5 Mesh Nodes — N0D3

🟢

N0D3-HUB · Pi 5 (2GB) Live — custom N0D3 enclosure printed and assembled

🔵

N0D3 ×3 · Pi 5 (1GB) Provisioning — expanding N0D3 fleet

📦

N0D3 Enclosure Custom 3D-printed case — validated fit, Bambu X1C print

N0D3S self-register on boot and advertise capabilities to the Commander. Adding a new Pi node to the mesh requires no Commander configuration — just flash, connect, and register.

Security

Audited, encrypted, access-controlled

M3SHD has gone through multiple structured security audits. Every finding was addressed. The security posture is documented, not assumed.

Fernet Encryption at Rest

Agent memory encrypted with MultiFernet, supporting key rotation without data loss. KEK recovery path validated. All sensitive fields encrypted before DB write.

RBAC with 17 Permissions

Four role presets with explicit permission sets. Zero-permission tokens are denied access by default. Per-agent tokens scoped to their declared capabilities only.

Structured Security Audits

Three formal red-team audits completed. Findings triaged by severity, addressed in code, and verified. Audit history documented alongside each component.

HMAC-Signed Task Results

Every task result carries an HMAC-SHA256 signature. Pipeline outputs form a Merkle chain — tampered results break verification before they reach the next stage.

Circuit Breaker Health Monitoring

Workers are automatically removed from rotation after repeated failures. Health state transitions are logged and visible in the dashboard. No silent degradation.

Parameterized Queries Only

All database access uses parameterized SQL. No string interpolation in queries. Input validated at the API layer before reaching any storage operation.