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 chatThat's it. Two commands. You're running local AI.
Live swarm monitoring — 5 nodes, 86.6 GB RAM, all from rescued hardware under $1,100.
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.
| Node | Hardware | Cost | Role |
|---|---|---|---|
| Miu | RTX 3090, 64GB RAM | ~$850 (used) | GPU inference — runs 27B models |
| naru | Lenovo M710Q, 8GB RAM | $50 | Web search, file processing |
| uncho | Lenovo M710Q, 8GB RAM | $50 | Web search, coordination |
| boa | Lenovo M710Q, 8GB RAM | $50 | Web search, code execution |
| raspberrypi | Raspberry Pi 2, 1GB RAM | $35 | Search, lightweight tasks |
Total: ~$1,035. Zero monthly fees.
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.
curl -fsSL https://raw.githubusercontent.com/msb-msb/mycoSwarm/main/scripts/install.sh | bash
mycoswarm chatThe installer detects your OS, installs Python and Ollama if needed, pulls a model sized for your RAM, and runs hardware detection.
pip install mycoswarm
mycoswarm chatRequires Ollama running with at least one model pulled.
brew install ollama
ollama serve &
ollama pull gemma3:27b # or gemma3:4b for 8GB Macs
pip install mycoswarm
mycoswarm chatApple Silicon unified memory is detected automatically — an M1 with 16GB can run 14B+ models.
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 detectPi nodes can't run inference (no GPU, limited RAM) but contribute as web search workers, file processors, and coordinators.
Single-node mode works out of the box. When you're ready for more:
mycoswarm daemonOr install as a service (Linux):
sudo cp scripts/mycoswarm.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now mycoswarmInstall 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 swarmShows both nodes, their capabilities, and available models.
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.
| Command | What It Does |
|---|---|
mycoswarm chat |
Interactive chat with memory, tools, and document search |
mycoswarm ask "prompt" |
Single question, streamed response |
mycoswarm research "topic" |
Parallel web search → synthesized answer with citations |
mycoswarm rag "question" |
Answer from your indexed documents |
mycoswarm search "query" |
Raw web search results |
mycoswarm library ingest [path] |
Index files for document search |
mycoswarm library list |
Show indexed documents |
mycoswarm detect |
Show hardware and capabilities |
mycoswarm swarm |
Swarm overview — all nodes and status |
mycoswarm models |
All models across the swarm |
mycoswarm plugins |
Installed plugins |
mycoswarm memory |
View and manage stored facts |
mycoswarm daemon |
Start the swarm daemon |
| Command | What It Does |
|---|---|
/remember <fact> |
Store a persistent fact |
/memories |
Show all stored facts |
/forget <n> |
Remove a fact by number |
/rag <question> |
Search documents and answer |
/library |
Show indexed documents |
/auto |
Toggle agentic tool routing on/off |
/identity |
View name, origin, substrate |
/name <n> |
Set or change AI name |
/vitals |
Detailed 8 C's breakdown with bar charts |
/timing |
Current timing gate state and reasons |
/stale |
Show facts approaching decay threshold |
/procedure |
View stored wisdom procedures |
/model |
Switch model |
/clear |
Reset conversation |
/quit |
Save session and exit |
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
| Tier | Example Hardware | Role |
|---|---|---|
| EXECUTIVE | RTX 3090 workstation | GPU inference, orchestration |
| SPECIALIST | RTX 3060 desktop | GPU inference (smaller models) |
| LIGHT | Lenovo M710Q, Raspberry Pi | Web search, file processing, coordination |
| WORKER | Any CPU-only machine | Distributed task execution |
Nodes broadcast via mDNS (_mycoswarm._tcp.local.). No central server, no configuration. Plug in a machine, start the daemon, the swarm grows.
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
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_workerhandler.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.
Drop files into ~/mycoswarm-docs/ and index them:
mycoswarm library ingestSupports: 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.
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.
- 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.tomlfor persistent settings - Mesh networking — Connect swarms across the internet via VPN
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 offlinev0.2.9 | 398 tests | 5 nodes — Built with experience, not hype. InsiderLLM