🍄 mycoSwarm

Distributed AI for everyone. Turn forgotten hardware into a thinking network.

mycoSwarm connects your machines — old laptops, mini PCs, Raspberry Pis, GPU workstations — into a single AI swarm. No cloud. No API keys. No data leaves your network.

curl -fsSL https://raw.githubusercontent.com/msb-msb/mycoSwarm/main/scripts/install.sh | bash
mycoswarm chat

That's it. Two commands. You're running local AI.

Dashboard

Live swarm monitoring — 5 nodes, 86.6 GB RAM, all from rescued hardware under $1,100.

What It Does

One machine? Chat with local models instantly — no daemon, no config.

Multiple machines? They find each other automatically via mDNS, share capabilities, and route tasks to the right hardware. A $50 mini PC can chat with a 27B model running on a GPU across the room.

The weakest machine in the swarm gets access to the strongest model.

Real Example: 5-Node Swarm

Total: ~$1,035. Zero monthly fees.

Features

Chat with memory — Persistent facts and session history across conversations. Your AI remembers what you tell it.

Research — Ask a question, the swarm plans multiple searches, distributes them across CPU workers in parallel, and synthesizes a cited answer on the GPU. Faster than any single machine.

Document library (RAG) — Drop files into ~/mycoswarm-docs/. The swarm indexes them and answers questions about your documents with citations.

Agentic tool routing — The model automatically decides when it needs web search or document lookup, shows you what it's doing, and uses the results. No manual tool selection.

Honest AI — When it doesn't know something, it says so. No hallucinated weather forecasts or fabricated facts.

Identity — Persistent self-model with first-run naming. Your AI remembers its own name across sessions.

Self-awareness (8 C's) — Real-time vital signs after every response: Calm, Clarity, Curiosity, Compassion, Courage, Creativity, Connectedness, Confidence. Derived from pipeline signals, not simulated.

Wu Wei Timing Gate — Contextual response calibration. Late night → shorter, warmer. Exploration mode → deeper, expansive. No LLM call, pure heuristics.

Procedural memory — The swarm learns from experience. Wisdom procedures surface automatically when similar problems recur.

Intent classification — Pre-inference routing decides tool, mode, and scope before the model runs.

Plugin system — Drop a folder into ~/.config/mycoswarm/plugins/ and your node advertises a new capability. No core code changes.

Install

Quick Start (Linux or macOS)

curl -fsSL https://raw.githubusercontent.com/msb-msb/mycoSwarm/main/scripts/install.sh | bash
mycoswarm chat

The installer detects your OS, installs Python and Ollama if needed, pulls a model sized for your RAM, and runs hardware detection.

Manual Install

pip install mycoswarm
mycoswarm chat

Requires Ollama running with at least one model pulled.

macOS (Apple Silicon)

brew install ollama
ollama serve &
ollama pull gemma3:27b  # or gemma3:4b for 8GB Macs
pip install mycoswarm
mycoswarm chat

Apple Silicon unified memory is detected automatically — an M1 with 16GB can run 14B+ models.

Raspberry Pi

Works on Pi 2 and newer. pymupdf (PDF support) is optional — if it fails to build on ARM, PDF reading is disabled but everything else works.

sudo apt install -y python3-venv git
git clone https://github.com/msb-msb/mycoSwarm.git
cd mycoSwarm
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
mycoswarm detect

Pi nodes can't run inference (no GPU, limited RAM) but contribute as web search workers, file processors, and coordinators.

Growing the Swarm

Single-node mode works out of the box. When you're ready for more:

Start the Daemon

mycoswarm daemon

Or install as a service (Linux):

sudo cp scripts/mycoswarm.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now mycoswarm

Add Another Machine

Install mycoSwarm on the second machine, start the daemon. That's it. mDNS handles discovery — no IP addresses to configure, no config files to edit. Within seconds:

mycoswarm swarm

Shows both nodes, their capabilities, and available models.

How Routing Works

The orchestrator scores each node for each task type:

• Inference → GPU nodes (highest VRAM wins)
• Web search / file processing → CPU workers (distributed round-robin)
• Embeddings → Nodes running Ollama with embedding models
• Code execution → CPU workers (sandboxed subprocess)

Tasks go to the best available node. If that node fails, the orchestrator retries on the next candidate. Executive (GPU) nodes are reserved for inference — they won't waste cycles on web searches when CPU workers are available.

CLI Commands

Chat Slash Commands

Architecture

src/mycoswarm/
├── hardware.py      # GPU/CPU/RAM/disk/Ollama detection (Linux, macOS, ARM)
├── capabilities.py  # Node classification — tiers, capabilities, model limits
├── node.py          # Persistent node identity (UUID survives restarts)
├── discovery.py     # mDNS auto-discovery, peer health tracking
├── api.py           # FastAPI service — health, status, peers, tasks, SSE streaming
├── daemon.py        # Main daemon — detection + discovery + API + worker + orchestrator
├── worker.py        # Task handlers — inference, search, embedding, files, code, translate
├── orchestrator.py  # Task routing — scoring, retry, load balancing, inflight tracking
├── plugins.py       # Plugin loader — scan ~/.config/mycoswarm/plugins/
├── solo.py          # Single-node mode — direct Ollama, agentic classification
├── library.py       # Document library — chunking, embeddings, ChromaDB, RAG
├── memory.py        # Persistent memory — facts, session summaries, prompt injection
├── identity.py      # Persistent self-model — name, origin, development stage
├── timing.py        # Wu Wei Timing Gate — PROCEED/GENTLE/DEEP calibration
├── vitals.py        # 8 C's vital signs — self-awareness from pipeline signals
└── cli.py           # All CLI commands and interactive chat

Node Tiers

Discovery

Nodes broadcast via mDNS (_mycoswarm._tcp.local.). No central server, no configuration. Plug in a machine, start the daemon, the swarm grows.

Task Flow

User asks question on Node A
  → Node A checks: can I handle this locally?
    → Yes: execute locally
    → No: orchestrator scores all peers
      → Dispatch to best peer
      → Stream response back to Node A

Plugins

Extend the swarm without touching core code. Drop a directory into ~/.config/mycoswarm/plugins/:

~/.config/mycoswarm/plugins/
└── my_summarizer/
    ├── plugin.yaml
    └── handler.py

plugin.yaml:

name: my_summarizer
task_type: summarize
description: Summarize text by extracting key points
capabilities: cpu_worker

handler.py:

async def handle(task):
    text = task.payload.get("text", "")
    # Your logic here
    return {"summary": summarized_text}

Restart the daemon. The node advertises the new capability. Other nodes can route summarize tasks to it.

Document Library

Drop files into ~/mycoswarm-docs/ and index them:

mycoswarm library ingest

Supports: PDF, Markdown, TXT, HTML, CSV, JSON.

Files are chunked, embedded (via Ollama), and stored in ChromaDB. Ask questions:

mycoswarm rag "what does the architecture section describe?"

Or use /rag in chat for inline document search.

The Manifesto

Named after mycelium — the underground network connecting a forest. It doesn't centralize. It finds what's available and connects it.

If a student in Lagos with two old laptops can't participate, the framework has failed.

No cloud dependencies. No API keys. No expensive hardware requirements. Every node counts.

What's Next

• Identity development — Monica grows through interaction, not just configuration
• Swarm identity sync — Consistent self-model across all nodes
• Agentic timing gate — SUPPRESS/DEFER/PROCEED for proactive actions
• Agentic planner — LLM generates multi-step plans and executes them across the swarm
• mTLS security — Encrypted, authenticated inter-node communication
• Config files — ~/.config/mycoswarm/config.toml for persistent settings
• Mesh networking — Connect swarms across the internet via VPN

Contributing

mycoSwarm is MIT licensed. Contributions welcome.

git clone https://github.com/msb-msb/mycoSwarm.git
cd mycoSwarm
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
python -m pytest tests/ -v  # 398 tests, all offline

v0.2.9 | 398 tests | 5 nodes — Built with experience, not hype. InsiderLLM