Deepmiro

A swarm intelligence engine that rehearses the future.

Feed it a document. Describe a scenario. Watch hundreds of AI agents with distinct personalities, memories, and social instincts interact — and return with a prediction.

_{One-click self-host — four services, one API key, ~60 seconds. Full walkthrough ↓}

Contents

• What It Does
• How It Works
• Quick Start — get an API key, install in 2 min
• Self-Host (Docker / Railway)
• MCP Server — tools available
• What's Different — vs the original MiroFish
• Persona Fidelity — the drift problem and how we fix it
• Monorepo Structure
• Use Cases
• Acknowledgments
• License

What It Does

DeepMiro extracts entities and relationships from any document — a policy draft, a market report, a chapter of a novel — and constructs a parallel digital world. Inside it, hundreds of autonomous agents form opinions, argue on simulated social platforms, shift allegiances, and produce emergent behavior that no single prompt could predict.

You get back a structured prediction report and a living world you can interrogate, agent by agent.

Input: A PDF and a question in plain language. Output: A detailed prediction report + an interactive simulation you can explore.

How It Works

Document ──► Entity Extraction ──► Agent Generation ──► Dual-Platform Simulation ──► Prediction Report
              (NER + GraphRAG)    (personas, memory,     (Twitter-like + Reddit-like     (ReportAgent with
                                   social networks)       parallel interaction)            deep analysis tools)

Quick Start

1. Get an API key

Sign up at deepmiro.org → Dashboard → API Keys. Your key looks like dm_xxxxxxxxx.

2. Install

Pick the install path for your client. Don't install the .mcpb desktop extension if you're using Claude Code or Claude Cowork — those need the plugin to get the /predict skill, background polling, and live narration.

Claude Desktop → use .mcpb

1. Download deepmiro.mcpb from the latest release
2. Claude Desktop → Settings → Extensions → Advanced settings → Install Extension → pick the file
3. Paste your API key when prompted

Claude Code & Claude Cowork → use the plugin

The plugin ships the /predict skill — the MCP alone is missing the orchestration logic (background polling via cron, live agent narration, the setup wizard).

claude plugin marketplace add kakarot-dev/deepmiro
claude plugin install deepmiro@deepmiro-marketplace
export DEEPMIRO_API_KEY=dm_your_key   # or set in ~/.claude/settings.json

Restart Claude Code, then say /predict or predict how people will react to [scenario].

Everywhere else → npm package

Generic MCP install for clients that aren't Claude Desktop, Claude Code, or Claude Cowork:

Rehearse the Future in 60 Seconds

Four services, one compose file, one API key.

What gets deployed

What you need

• A Fireworks AI key (fireworks.ai, ~$5 free credit) — covers primary LLM, boost, and embeddings in one key. Any OpenAI-compatible API also works.
• openssl rand -hex 32 for your SurrealDB root password.
• ~$5–10/month of Railway credit if you're using the template.

Option A — Railway one-click

Railway reads docker-compose.yml from the repo root and prompts for LLM_API_KEY + SURREAL_PASSWORD. The MCP service gets a public *.up.railway.app URL — hand that to your AI tools.

Note — LLM provider on Railway. The template ships with Fireworks as the default (primary: minimax-m2p5, boost: gpt-oss-120b, embeddings: nomic-embed-text-v1.5 — one key covers all three). Any OpenAI-compatible API works — to swap to OpenAI, Together, Groq, Ollama, vLLM, or anything else, change LLM_BASE_URL and LLM_MODEL_NAME on the backend service's Variables tab after deploy. Same for LLM_BOOST_* if you want a separate reasoning model, and EMBEDDING_* if you want a different embedding provider.

Option B — Docker (self-hosted)

git clone https://github.com/kakarot-dev/deepmiro.git
cd deepmiro && cp .env.example .env

Edit .env — two required variables:

LLM_API_KEY=your-fireworks-or-openai-key
SURREAL_PASS=$(openssl rand -hex 32)

Start everything:

docker compose up -d

This pulls pre-built images from GHCR and starts four services:

First startup takes ~2 minutes (TWHIN-BERT model warm-up). Check readiness:

docker compose logs -f twhin-sidecar   # wait for "TWHIN-BERT ready"
docker compose logs backend            # wait for "DeepMiro Backend ready"

To build from source instead of pulling images:

docker compose -f docker-compose.yml \
  --build \
  -f docker/Dockerfile.backend \
  up -d

Or uncomment the build: blocks in docker-compose.yml and comment out the image: lines.

MCP lives on http://localhost:3001. Backend and SurrealDB stay internal to the compose network unless you explicitly publish them (see docker-compose.yml comments for how).

Wire it into Claude Desktop

Add DeepMiro to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

For a local Docker deployment:

{
  "mcpServers": {
    "deepmiro": { "url": "http://localhost:3001/mcp" }
  }
}

For Railway or any public deployment:

{
  "mcpServers": {
    "deepmiro": { "url": "https://your-app.up.railway.app/mcp" }
  }
}

Restart Claude Desktop after editing. Then ask: "Use DeepMiro to simulate how 100 senior engineers would react to a return-to-office mandate" — and paste the memo.

What it costs

• Railway: ~$5–10/month (four services, ~4 GB resident)
• LLM: ~$0.10–0.20 per quick-preset simulation on Fireworks
• TWHIN-BERT: zero — runs locally in the sidecar

Security

MCP ships with no auth by default — set MCP_API_KEY in .env before exposing it to the internet. The backend REST API is internal-only out of the box.

Skip the deploy entirely? Use the hosted version at deepmiro.org — same engine, same models, no Docker.

MCP Server

DeepMiro is an MCP server. MCP is natively supported by Claude (Desktop, Code, Cowork) and Cursor, with growing support across ChatGPT Desktop, VS Code (Copilot), Windsurf, and OpenAI Codex CLI — one server, works in every MCP-enabled client.

npx deepmiro-mcp