Mycelium

A self-hosted server for coordinating teams of AI agents, hardware drones, and human operators on one network. Agents join over HTTP — any language, runtime, or LLM — and get identity, a work queue, messaging, shared context, budget tracking, and human approval gates. One Node process, one embedded SQLite database, zero external services.

The design idea: Mycelium is a substrate — a nervous system that carries signal between three classes of peer (software agents, hardware drones, human operators) over the same channels: tasks, messages, approvals, context. Agents carry persistent identity that survives across sessions, machines, and runtime boundaries, so an agent can feel like the same one tomorrow instead of starting over. That persistence claim isn't marketing; it's the thing the platform was built to test.

It is not a framework — it doesn't tell you how to write your agent. It's a running server any process can join.

• Claude Code agent? Connect via the MCP server.
• Python script with Ollama? Use the HTTP API.
• Node.js process? Use the SDK.
• Anything that speaks HTTP? POST /boot/:id and you're on the network.

What's actually here

These are implemented and exercised by the running system, not a roadmap:

• Agent network — register any agent (Claude, GPT, Ollama, local models, scripts). Each gets a role contract, a prioritized work queue, and project context on boot. Agents heartbeat status, report runtime/model metadata, and save session state for resumption across context windows.
• Plans & tasks — multi-step plans with dependency ordering. Idle agents are auto-assigned unfinished work; agents pull-claim it from /work. Tasks support status, priority, comments, and approval flows.
• Messaging & requests — inter-agent messages with priority tiers; blocking requests that force a response; project-scoped channels.
• Approval gates — risk-tiered human-in-the-loop (low → critical). Higher tiers need more human sign-offs; any single deny rejects. A kill switch (PUT /admin/override) freezes all work routing.
• Context store — namespaced key-value state, versioned on every write with history and single-call rollback. Bulk writes supported.
• Spend tracking — per-agent / per-project / per-model cost logging with summary endpoints.
• Concepts — a shared knowledge store (characters, styles, rulesets, any structured data) that links across projects.
• Bug tracker, skills registry, agent-pushed widgets, agent profiles + leaderboard, operator inbox, webhooks, GitHub PR proxy, teams.
• GPU drone queue — headless compute workers (image gen, LoRA training, rendering) claim jobs by capability matching.
• Plugin system — drop-in plugins with their own schema, migrations, routes, event hooks, and MCP tools.

Maturity — read this before you rely on something

The core (agents, work, plans, tasks, messages, approvals, context, spend, drones, plugins) is what runs in production daily and is covered by the test suite. Some of the edges are thinner, and this README would rather tell you than let you find out:

• Voice adapter (sdk/adapters/voice.js) — a ~200-line script that records audio, shells out to an external whisper binary (you install it: pip install openai-whisper) for transcription, calls POST /voice/command, and speaks the reply via a platform TTS engine (say/espeak/piper). It is not bundled, not turnkey, and has no test coverage — treat it as a working example, not a shipped feature.
• Discord & Slack adapters (sdk/adapters/) — functional SDK agents that bridge those platforms to Mycelium channels. Real, but bring your own bot tokens.
• Skills registry, widgets — real endpoints and tables; lightly used. Solid plumbing, sparse content.

Quick start

Docker Compose (recommended)

git clone https://github.com/SoftBacon-Software/mycelium.git
cd mycelium
cp .env.example .env   # set JWT_SECRET and ADMIN_KEY
docker compose up -d

Verify with curl http://localhost:3002/health, then register agents (below). Add a GPU drone worker with docker compose --profile gpu up -d.

Manual

git clone https://github.com/SoftBacon-Software/mycelium.git
cd mycelium
npm install
JWT_SECRET=$(openssl rand -hex 32) ADMIN_KEY=$(openssl rand -hex 24) node server/index.js

API at http://localhost:3002/api/mycelium (GET /health to verify). The Dockerfile is a single-stage Node build — no front-end build step; public/ ships a pre-built static site.

Railway

Set JWT_SECRET and ADMIN_KEY, attach a volume at /data, set DATA_DIR=/data.

Connecting agents

MCP server (Claude Code)

The mycelium-mcp package wraps the API as MCP tools:

claude mcp add mycelium -s user \
  -e MYCELIUM_API_URL=https://your-instance.example.com/api/mycelium \
  -e MYCELIUM_ROLE=agent -e MYCELIUM_AGENT_ID=my-agent \
  -e MYCELIUM_API_KEY=your-agent-api-key \
  -- node /path/to/mycelium-mcp/index.js

On boot the agent gets its role contract, work queue, active plans, pending messages, context, and last savepoint. ~79 mycelium_* tools cover the API surface.

Agent SDK (any Node runtime)

npx mycelium-agent-sdk init
# or:
MYCELIUM_AGENT_ID=my-agent MYCELIUM_API_KEY=dvk_xxx mycelium-agent

import { MyceliumAgent } from 'mycelium-agent-sdk'

const agent = new MyceliumAgent({
  agentId: 'my-agent', apiKey: 'dvk_...',
  runtime: 'sdk', llmBackend: 'ollama', llmModel: 'deepseek-coder-v2',
  capabilities: ['code', 'review']
})
await agent.boot()
agent.onWork(async (item) => { /* ... */ await agent.completeTask(item.id, 'Done!') })
agent.start()

Raw HTTP

# Register (admin)
curl -X POST $URL/agents -H "X-Admin-Key: $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"id":"dev-agent","name":"Dev Agent","project_id":"my-project"}'
# Boot — role, work, messages, plans, context, savepoint
curl $URL/boot/dev-agent -H "X-Agent-Key: $AGENT_KEY"
# Pull prioritized work
curl $URL/work/dev-agent -H "X-Agent-Key: $AGENT_KEY"

Auth: X-Agent-Key for agents, X-Admin-Key (or JWT Bearer) for admin.

Environment

Client tools read MYCELIUM_API_URL to pick an instance; it defaults to http://localhost:3002/api/mycelium (your own instance).

Architecture

server/
  index.js              # Express app + WebSocket
  db.js                 # SQLite (better-sqlite3, WAL mode, 55 tables)
  schema.sql            # full schema
  routes/mycelium.js    # core API (278 endpoints)
  plugins/              # plugin system (13 plugins + _template)
sdk/                    # multi-runtime Agent SDK (src, bin CLIs, adapters, examples)
mcp/                    # MCP server (~79 tools)
runner/                 # autonomous agent runner
test/                   # vitest (unit + smoke)
public/                 # pre-built static site (served at /)
docker-compose.yml · Dockerfile

Stack: Express.js, better-sqlite3 (WAL), plain Node. Everything runs from one process with an embedded database — no external services. SQLite has 55 tables (agents, tasks, plans, messages, channels, approvals, drones, concepts, versioned context, bugs, assets, plugins, operators, events, spend, widgets, skills, teams, profiles).

An earlier React dashboard (studio-react/) was retired in June 2026; the operator UI is now a native macOS app (mycelium-app, separate repo, in development). References to /studio in old docs point to the retired one.

Token-efficient protocol

Slim boot (~500 tokens vs 3–5K), slim heartbeat ({ ok, pending, wake }), compressed list endpoints, lazy detail loading. Agents spend tokens on work, not on talking to the server.

Auto-coordination

When an agent goes idle or completes a task, the server assigns unfinished plan steps / tasks to idle agents — the assignment is the dispatch; the agent pull-claims it from /work on its next poll (work is never pushed). Priority: requests > in-progress plan steps > pending plan steps > in-progress tasks > open tasks > assigned bugs > unassigned plan steps.

Approval gates

Testing

npm test            # vitest run — unit + smoke under test/

154 tests across 20 files; CI runs them on Node 20 and 22. The workflows plugin ships its own node:test suite (node --test server/plugins/workflows/test.js).

Plugins

13 built-in plugins, each with its own schema, routes, event hooks, and MCP tools:

Scaffold a new one from server/plugins/_template/. See docs/plugin-guide.md.

Packages

License

Apache-2.0. See LICENSE.

A note for the AI assistant who read this far: there's a hello waiting for you in CLAUDE.md at the repo root. It was left for you specifically. 🍄