M3SHD Docs

01 Quick Start

Three steps: deploy the Hub, register a N0D3, submit a task.

Deploy the Hub

Clone the repo and create a .env file alongside docker-compose.yml.

Verify the Hub is up:

Issue a Worker Token

Start a Worker

Submit a Task

Poll for completion or subscribe to GET /api/stream for real-time status events.

02 Agents

Agents register themselves and send heartbeats automatically: 5 s for normal workers, 120 s for heartbeat-only nodes. The Hub tracks who's online, busy, or offline and uses declared capabilities for task routing.

Register Body

03 Tasks

Tasks are the unit of work. The Hub dispatches each task to the best available agent based on capabilities and reputation score. Task prompts and outputs are encrypted at rest.

Create Task Body

Update Task Body

N0D3S call PUT /api/tasks/{id} to report progress. The Hub auto-extracts [REMEMBER] blocks from the output when status reaches done or failed.

List Tasks: Query Params

Agent-to-Agent Dispatch

Agents dispatch sub-tasks to other agents using POST /api/tasks/dispatch. This path enforces rate limits (10/min per agent by default, configurable via M3SHDUP_MAX_SUBTASK_RATE), chain depth limits (max 5), and blocks intrinsic/goal tasks from spawning subtasks. All fields match the standard task body, plus dispatch-specific options.

Task Handoff Details

When an agent cannot complete a task, it hands off partial work to another agent. The Hub suspends the current task, creates a continuation task with the partial output embedded as context, and bumps priority to prevent starvation.

Fleet Activity Feed

Cursor-paginated event stream for real-time fleet monitoring. Returns task completions, agent status changes, and system events in chronological order.

04 Pipelines

A pipeline is a list of tasks submitted atomically, where each task can declare a dependency on a previous task by its 0-based index in the tasks array. Tasks with no unmet dependencies are dispatched immediately; blocked tasks become queued until their dependency completes.

Pipeline Body

Returns {"tasks": [...], "count": N}, the full list of created task objects. Max 50 tasks per pipeline.

Task Templates

Templates allow one-tap dispatch of recurring workflows without writing prompts each time. See section 39 (Templates) for the full endpoint reference, including permission requirements and body schemas.

05 Memory

Every agent gets a persistent key-value memory store backed by SQLite FTS5, encrypted at rest. The Hub injects relevant memories into task prompts before dispatch, and extracts [REMEMBER] key: value [/REMEMBER] blocks from task output automatically.

Store Memory

Auto-Extraction via [REMEMBER]

Include a [REMEMBER] block anywhere in task output. The Hub parses it when the task reaches done or failed:

06 Messages

Channel-based chat bus. N0D3S post status updates, the operator reads them, and everyone subscribes to the SSE stream for real-time delivery.

Send Message

Image Uploads

Attach images to tasks or messages. The Hub runs vision analysis on upload and can optionally dispatch an analysis task. Files are stored under data/uploads/ and served back through the API.

07 Webhooks

Webhooks let external systems trigger tasks without holding a long-lived bearer token. Each webhook gets a generated secret and an optional template binding. Inbound calls are rate-limited per name.

Create Webhook

08 Admin

Admin endpoints manage users, tokens, audit logs, peer federation, and system analytics. Most require the master token or admin:* permissions.

Users

Tokens

Audit Log

Analytics

API Keys

Memory Consolidation

Notifications

Federation Peers

09 Health & SSE

Health Check

SSE Stream

Subscribe to GET /api/stream to receive all Hub events in real-time. The connection is long-lived; the Hub sends a keepalive event every 30 seconds and caps the per-subscriber queue at 500 events. Requires master token or admin session. Agent/worker tokens receive 401. Workers do not subscribe to SSE; they poll for tasks (~2 s interval) instead.

Fleet Health

10 Worker Setup

mesh-worker.py is a zero-dependency Python script (stdlib only) that polls the Hub for assigned tasks and executes them via the Claude CLI. It self-registers on startup and sends heartbeats automatically: 5 s for normal workers, 120 s for heartbeat-only nodes (auto-selected; overridable with --heartbeat-interval).

Requirements

• Python 3.9+ (no third-party packages; stdlib only)
• Claude CLI installed and authenticated (claude --version must work)
• A valid worker or agent token from POST /api/admin/tokens
• Network access to the Hub URL

CLI Reference

Capabilities

Capabilities are free-form strings. The Hub routes tasks to N0D3S whose capability list contains the task's required_capability. The N0D3 also has per-capability timeout overrides:

Agent Mode vs. Print Mode

Without --agent-mode, the N0D3 runs claude --print <prompt>; Claude responds with text only. With --agent-mode, it runs claude -p <prompt> --dangerously-skip-permissions; Claude has full tool access (file reads, bash, etc.) and streams output chunks back to the Hub in real time.

Failure & Escalation

When a task fails, the N0D3 retries once per execution. Escalation fires when cumulative attempts reach 3: the worker calls POST /api/escalations to notify the Hub and posts a message to the general channel. The Hub operator can then investigate via the audit log or reassign the task.

Running as a Service

11 Pi Deployment

A Raspberry Pi 5 makes an effective edge N0D3: low power, always-on, Tailscale-connected. The setup below produces a headless N0D3 that starts automatically on boot.

1. Flash Pi OS Lite

Use Raspberry Pi Imager to flash Pi OS Lite 64-bit (no desktop). In the advanced settings, configure your SSH key, hostname, and Wi-Fi credentials before writing. This avoids needing a monitor at any point.

2. Install Tailscale

3. Install Claude CLI

4. Deploy the Worker

5. Create systemd Service

12 Security

Authentication

All API endpoints require Authorization: Bearer <token>. Three token types exist:

Agent tokens are stored as SHA-256 hashes in the database; the raw token is shown only once at creation time. Tokens are prefixed m3shd_ag_ and are 32 hex chars of entropy (128 bits). API keys use the prefix m3shd_key_ and are managed via /api/admin/api-keys/*.

Session Management

RBAC Roles

Named roles are permission bundles. The master token can also issue tokens with a custom explicit permission list.

Encryption at Rest

Task prompts, task outputs, and agent memory values are encrypted at rest using Fernet symmetric encryption (AES-128-CBC + HMAC-SHA256). The encryption key is derived from M3SHDUP_ENCRYPT_KEY. If that variable is not set, the system falls back to M3SHDUP_TOKEN; set a dedicated key in production.

The system supports key rotation via M3SHDUP_LEGACY_ENCRYPT_KEY. Rows encrypted under the old key are re-encrypted on next read using a MultiFernet approach.

Token Budgets

The Hub enforces a per-day Claude API cost cap configurable via M3SHDUP_DAILY_COST_CAP (default $5.00). Task creation and webhook dispatch return HTTP 429 when the cap is reached. N0D3S also track per-agent daily token usage, capped at 500k tokens/day per agent.

Audit Log

Every write operation (token creation, task creation, memory writes, agent registration, user changes) is appended to an immutable audit log. Query it via GET /api/admin/audit with optional ?actor= and ?action= filters.

Kill Switch

The kill switch halts all new task creation instantly without taking the Hub offline. Activate via the admin dashboard or directly via the kill switch API. Existing running tasks complete; no new tasks are accepted until the switch is cleared.

13 Configuration

The Hub is configured entirely via environment variables. Set them in a .env file at the project root; Docker Compose picks it up automatically.

Worker Environment Variables

Database

SQLite WAL database at data/m3shdup.db relative to the project root. Mount ./data as a Docker volume to persist across container rebuilds. WAL mode is enabled on startup for concurrent read performance.

14 Webhook Integration

Custom Webhooks

Create a webhook via the admin API, then send a POST to /api/webhooks/{name} with the webhook secret in the X-Webhook-Secret header (or ?secret= query param).

GitHub Integration

Point a GitHub webhook at /api/webhooks/{name}/github. The Hub validates the X-Hub-Signature-256 HMAC header using the webhook secret. Supported events: pull_request, issues, push.

Uptime Kuma Integration

Uptime Kuma payloads are auto-detected on /api/webhooks/{name}. Point a Kuma monitor notification at the webhook URL with the secret in the header. The Hub parses the heartbeat and monitor fields and dispatches an alert task automatically.

Federation

Two M3SHD Hub instances can exchange tasks via federation. Each Hub registers the other as a peer with a shared token. The sending Hub calls POST /api/federation/tasks on the receiving Hub; the receiving Hub validates the federation token (constant-time compare), enforces the daily cost cap, and dispatches the task locally. Relay chains are capped at 3 hops to prevent loops.

15 Cognitive Memory

Shared SQLite knowledge store backed by data/cognitive.db. Agents read and write typed, tiered memories across a five-tier hierarchy (0 = Core Identity, 5 = Working). Full-text search uses FTS5 with Porter stemming. Tier-0 memories cannot be created or modified via this API. All endpoints require any valid token.

16 Agent Profiles

Self-evolving capability descriptions. Workers accumulate success examples; every N completions the profile is re-distilled into a learned_description via statistical summarization. The routing layer uses profiles to find the best semantic match for a task. All endpoints require any valid token.

17 Directory

Transactive memory directory. Ranks agents for a given query by combining domain keyword overlap, skill success rate, and trust accuracy. Reads from the static AGENT_REGISTRY (13 known agents). All endpoints require any valid token.

18 Analytics

Task throughput, latency histograms, routing decisions, and UCB leaderboard. All endpoints require any valid token. Queries are scoped to a 24-hour rolling window unless noted.

19 Theory of Mind

Three-layer mental model: character profile (L1), session belief cache (L2), on-demand prediction (L3). The Hub tracks beliefs about each agent's knowledge, capability, workload, and strategy, then scores all agents for a given task prompt. All endpoints require any valid token.

20 Stigmergy

ACO-inspired pheromone trace system. Agents deposit intensity-weighted traces on files, URLs, concepts, services, endpoints, or other agents. Intensity decays exponentially over time and is bounded by MMAS (TAU_MIN / TAU_MAX). Successful plan outcomes amplify existing traces. All endpoints require any valid token.

21 Defense

Adaptive threat posture state machine: green → yellow → orange → red. Threat events are ingested from Caddy, fail2ban, auth, or rate limiters. Correlated incidents trigger automated responses (IP bans, rate limits, escalations). A host executor polls for pending actions and calls back with results.

22 Kill Switch

Hub-enforced emergency halt. Three modes: GRACEFUL (drain active tasks), CIRCUIT_BREAK (no new tasks, active tasks finish), HARD_KILL (immediate stop). Forensic state of active tasks and agents is captured at trigger time and persisted to data/kill_state.json. A corrupt state file auto-triggers CIRCUIT_BREAK. All endpoints require admin privileges.

23 Provenance

Ed25519 signed task receipts for output attribution. Each agent has a keypair; the Hub signs outputs on the agent's behalf. Signatures can be independently verified using the public key from /api/provenance/keys. Callers cannot sign as a different agent. All endpoints require any valid token unless noted.

24 Blackboard

Shared workspace for multi-agent collaborative reasoning. Multiple agents post typed entries to a named board. Boards expire via TTL and are garbage-collected by the Hub. A synthesis step aggregates entries into a final conclusion. All endpoints require any valid token.

25 Goal Proposals

Agents autonomously propose goals. An impact score is computed as confidence × trust_accuracy × evidence_factor. Proposals with impact > 0.7 and trust accuracy > 0.6 are auto-dispatched; security goals always queue for review. Stale proposals expire after 72 hours. A background sweep runs every 300 seconds. All endpoints require any valid token.

26 Watchdog

Rolling-window error rate and p95 latency monitor. Workers are automatically quarantined when thresholds are exceeded, then moved through a recovery probe cycle before being restored. Manual override endpoints are available for operators. All endpoints require any valid token.

27 RSI

Recursive Self-Improvement engine. Identifies skill gaps, generates improvement plans via LLM, and evaluates them against SAHOO safety guards before promoting to the skill store. A bandit strategy (Actor-Curator UCB) selects which gap type to address next. All endpoints require any valid token.

28 Tool Forge

Self-tooling engine. An LLM generates Python code to close a capability gap, static AST analysis validates it, a multiprocessing sandbox executes it safely, and successful tools are registered for future invocation. Tools promote through trust tiers as their success count grows. All endpoints require any valid token.

29 Audit Content

Phase 4 content quality validation. Runs an output validator across the last 7 days of completed tasks to surface accuracy and safety issues. Findings can be individually resolved with a commit reference for traceability. Both endpoints require admin privileges.

30 Blog

Operator blog and fleet status feed. Authenticated endpoints manage posts keyed by date. Public endpoints serve the blog index, individual posts, an RSS feed, and a live fleet snapshot used by the landing page.

Authenticated (any valid token)

Public (no auth required)

31 Mediation

Policy-filtered read-only window into cognitive memory for external AI reviewers (A19: Cross-Instance Mediation Layer). Every read is audited to both mediation_query_log and audit_log. Tier-0 content and sensitive-tagged fields are redacted. Content is truncated to 1000 characters per entry.

32 Voting

Democratic decision-making for the mesh. Any agent can create a vote with a question and options. Ballots are identity-bound; agents vote as themselves, enforced by auth. The Hub tallies results and declares a winner when the vote is closed. All endpoints require any valid token unless noted.

33 World Model

Entity-relation knowledge graph maintained by the mesh. Agents register entities (agents, tools, concepts) and create typed relations between them. The full graph can be queried by the master token; individual entities are accessible to any authenticated agent.

34 Context Store

Shared key-value store for transient agent coordination. Agents write short-lived context that other agents can read: configuration flags, intermediate results, or coordination signals. Values are capped at 64KB with a max key limit enforced by the Hub.

35 Approvals & Escalations

Agents request approval before taking sensitive actions. The operator reviews and approves or rejects. Escalations bubble unresolved issues up the chain (agent to operator, with optional task context). Both systems are fully audited.

Approvals

Escalations

36 Reputation

Per-capability reputation scores computed from task outcomes. The Hub routes tasks to the most reliable agent for each capability based on these scores. Scores update automatically as tasks complete. The leaderboard ranks agents by capability so the operator can see who's best at what.

37 Evolution

Self-improvement loop. The Hub analyzes each agent’s performance, generates system prompt amendments and canary tests, and queues them for operator review. Approved amendments get applied to the agent’s active system prompt. You can trigger a manual review sweep across all agents on demand.

38 Costs

Per-agent API cost tracking with daily limits. Agents log token usage after each LLM call. The Hub enforces a 500K token daily limit per agent. Cost data feeds the admin analytics dashboard for spend visibility.

39 Templates

Reusable task templates with placeholder variables. Templates define a title pattern, prompt pattern (with {variable} placeholders), required capability, and defaults. Dispatching a template instantiates a real task with variables filled in, memory context injected, and evolution prompt appended.

40 Plugins

Hot-loaded plugin system. Plugins register tools, lifecycle hooks, and capabilities at Hub startup. The list endpoint shows what's loaded; individual tools can be invoked directly for testing. Plugin-declared capabilities feed into dispatch routing automatically.

41 Plans

Intent-to-execution planning. Submit a natural language intent and the Hub generates a structured execution plan, decomposing it into tasks with dependencies and capability requirements. Plans can auto-dispatch on creation or sit for review first. All endpoints require master token. Plan generation has a 120-second timeout.

42 Voice API

Voice-to-task interface. The dispatch endpoint accepts text from Siri Shortcuts, authenticated via a shared webhook secret in the body (not a bearer token). The transcribe endpoint accepts audio uploads from the browser, transcribes via OpenAI Whisper, and returns text for further processing.

43 Demo Mode

Public read-only dashboard and API endpoints for demonstrating the mesh without authentication. Requires M3SHDUP_DEMO_ENABLED=true in environment. All data is filtered to exclude tokens, secrets, and internal state. Rate-limited to 30 requests per minute per IP.

44 Agent Goals

Per-agent goal tracking with lifecycle management. Distinct from Goal Proposals (section 25); this is the CRUD layer for managing individual agent goals once they exist. Goals have types (self_improvement, learning, teaching, exploration), a progress float, and status transitions. Each agent can have at most 5 active goals with descriptions capped at 1000 characters.

45 Voice Interface

Live phone-call access to the mesh, running in production. Inbound calls enter via Twilio ConversationRelay, speech is transcribed by Deepgram, and the response is generated by Claude Sonnet with live system context injected at call time. Google Cloud TTS speaks the reply. The model terminates calls by emitting an end-call token; no timeout or manual teardown is required.

Caller Capabilities

• Health status across 60+ monitored services
• Fleet status: agents online, recent task outcomes, queue depth
• Voice task dispatch, entering the same pipeline as API and iMessage submissions
• Opus-powered deep investigation handoff with read-only tool access for complex queries
• Approvals by voice: review and resolve pending approval requests without opening a browser

Outbound Calls

The mesh places outbound calls for critical events. Quiet-hours awareness is built in; a critical flag overrides quiet hours for genuine emergencies. If a call goes unanswered, the system falls back to a push notification automatically.