MiroFish: The Free, Open Source Multi-Agent AI Simulation Engine That Predicts How the Public Will React (2026 Setup Guide)
MiroFish is a free, open source multi-agent AI prediction engine that spawns hundreds of autonomous LLM agents on a simulated social network to forecast public reaction to news, product launches, and policy drafts before you publish.
Predicting how people will react to a product launch, a crisis statement, or a new policy is expensive and slow. Focus groups take weeks to organize and cost thousands of dollars, and traditional forecasting models treat the world like a tidy math equation. The real world does not work that way: opinions shift, coalitions form, and one viral post can flip the entire conversation. MiroFish is built to simulate exactly that messiness before you commit anything to the public.
MiroFish is a free, open source AI prediction engine that works like a digital sandbox for scenario simulation. You feed it a "reality seed" such as a news report or a draft memo, tell it what you want to predict, and it spawns hundreds of autonomous AI agents onto a simulated social network to argue, post, and influence each other. The result is a prediction that emerges from collective behavior rather than a single hardcoded model.
In this guide, you'll learn what MiroFish is, who it's for, and how to deploy the full stack locally with your own LLM API key.
What is MiroFish?
MiroFish is an open source multi-agent simulation engine that treats forecasting as a social process instead of a static calculation. The easiest way to picture it is "SimCity meets AI forecasting": rather than fitting a curve to historical data, it builds a living world of AI personalities and lets you watch how a scenario plays out inside it.
The workflow starts with a reality seed, which can be a news article, a policy draft, or a financial earnings call. Using GraphRAG (Graph-based Retrieval-Augmented Generation), MiroFish extracts the key entities from that document and assembles a knowledge graph. It then spawns hundreds of autonomous AI agents, each given a distinct personality, bias, and memory, and drops them into a simulated dual-platform environment modeled on Twitter and Reddit. That environment is powered by the OASIS engine, an open source social simulation framework.
Over multiple rounds, the agents post, react, debate, and persuade one another. Because each agent keeps a persistent memory, stances evolve as the simulation runs: agents can build trust, hold grudges, and change their minds based on what they read. When the rounds finish, an AI ReportAgent analyzes the emergent behavior of the whole swarm and produces a prediction report with confidence signals and the turning points that shifted the crowd.
Who is it for?
- PR and marketing strategists: People who want to upload a crisis response or product launch memo and stress-test how the public might react before anything goes live.
- Financial analysts: Analysts injecting market signals to watch how simulated retail and institutional investors respond to each other's moves.
- Policymakers and executives: Leaders testing downstream impact by uploading a draft policy to see how different stakeholder groups form alliances or push back.
- AI automation researchers: Developers studying multi-agent orchestration, persistent memory, and how emergent behavior arises inside LLM swarms.
What makes MiroFish different from traditional forecasting tools?
- Emergent prediction: The output is not hardcoded. The forecast arises naturally from the collective intelligence and social contagion of hundreds of agents interacting, arguing, and persuading one another.
- God's-eye deep interaction: When the simulation ends you get more than a static PDF. You can open a chat window and interview any individual agent to ask why it changed its opinion or posted a specific comment.
- Persistent agent memory: Agents are not amnesiacs. They keep long-term memory across simulation rounds, so they can build trust, hold grudges, and evolve their positions over time using the knowledge graph.
- Dual-platform social environment: The OASIS engine models both Twitter-style and Reddit-style dynamics, so you can watch how the same seed spreads differently across two very different social structures.
- Offline community forks: The official repo uses cloud LLM APIs, but the community maintains forks like MiroFish-Offline that swap the backend for Neo4j and local Ollama models, giving you fully private, on-device simulation.
- Free and open source: MiroFish is released under the AGPL-3.0 license, so you can read, self-host, and modify the entire stack with no subscription.
What you need before you start
MiroFish orchestrates a large number of LLM calls across a full-stack environment. Make sure you have the following ready:
- Node.js 18 or newer: Required to run the Vue-based frontend UI.
- Python 3.11 or 3.12: Required for the backend simulation engine.
- The uv package manager: The fast, modern Python package installer that the setup script relies on.
- An LLM API key: MiroFish supports any OpenAI-compatible API. Because running hundreds of agents is token-heavy, the developers strongly recommend cost-efficient models like Alibaba's Qwen-Plus or Anthropic's Claude Haiku rather than a premium flagship model.
- A token budget in mind: Even with cheap models, large simulations add up. Plan to start small so you understand the cost curve before scaling the agent count.
Step-by-step installation
Deploying the official MiroFish stack locally means running both the frontend and backend together. The unified setup script handles most of the work.
Step 1: Clone and configure
Open your terminal, clone the repository, and create your environment file from the provided example:
git clone https://github.com/666ghj/MiroFish.git
cd MiroFish
cp .env.example .env
Open the .env file in a text editor and add your chosen LLM API key and base URL:
LLM_API_KEY=your_key_here
LLM_BASE_URL=https://api.openai.com/v1
You can point LLM_BASE_URL at any OpenAI-compatible endpoint, including Qwen, a local server, or another provider.
Step 2: Install all dependencies
MiroFish ships a unified setup script that installs both the frontend JavaScript packages and the backend Python virtual environment (via uv) automatically:
npm run setup:all
If this step fails on the Python side, it almost always means uv is not installed yet. See the errors table below for the fix.
Step 3: Start the simulation engine
Once everything is installed, start the local development servers:
npm run dev
This boots the Python backend and the Vue frontend together. Open the localhost URL printed in your terminal, upload your first document, define your prediction requirement, and watch the agents spawn into the simulated world.
Note: For your very first run, keep the simulation small, such as 10 agents over 5 rounds. This lets you understand the system and the token cost before scaling up to hundreds of agents.
Common errors and how to fix them
| Error | What it means | How to fix it |
|---|---|---|
| Massive API bills / token limits exceeded | Simulating 100 agents talking for 40 rounds generates a staggering amount of LLM prompt tokens. | Do not use a premium flagship model for your first run. Start small (10 agents, 5 rounds) and use cheap, fast models like Qwen 2.5, Claude Haiku, or Llama 3 as the agent brains. |
| uv: command not found | The npm run setup:all script is trying to install Python dependencies but uv is not installed on your system. |
Install uv globally first. On macOS or Linux run curl -LsSf https://astral.sh/uv/install.sh | sh. On Windows run powershell -c "irm https://astral.sh/uv/install.ps1 | iex", then rerun the setup. |
| Graph generation fails or the UI defaults to Chinese | The upstream MiroFish was built heavily for the Chinese market and may default to regional API prompts or UI text. | For a native English experience, clone the nikmcfly/MiroFish-Offline fork instead, which translates the UI to English and swaps cloud services for local Neo4j graphs. |
| Frontend loads but agents never spawn | The Vue frontend started but the Python backend either crashed or cannot reach your LLM endpoint. | Check the backend terminal output. A wrong LLM_BASE_URL, an invalid key, or a blocked outbound request is the usual cause. Confirm the endpoint responds with a simple curl test. |
MiroFish vs traditional focus groups and polling
| Feature | MiroFish (open source swarm) | Human focus groups and polling |
|---|---|---|
| Cost and speed | Near instant, costs only API tokens (roughly $10 to $20 per run) | Weeks of planning and thousands of dollars per study |
| Dynamic scenario testing | Inject variables mid-simulation and watch the crowd react | Static, requires commissioning a completely new poll |
| Data privacy | Fully private, especially with the offline forks | Requires sharing sensitive drafts with a third-party vendor |
| Scale | Hundreds of agents in a single run, easily rerun | Limited by recruiting and scheduling real participants |
| Real-world accuracy | Strong for directional sentiment, not exact statistics | Better for strict demographic sampling and hard numbers |
| Best for | Fast, private, directional stress-testing of a message | Regulated research needing statistically valid samples |
Bottom line: MiroFish points at the next frontier of applied AI, where the most valuable insight comes from watching AIs talk to each other rather than prompting a single chatbot. A traditional focus group costs thousands of dollars and weeks of lead time to tell you how a message might land. MiroFish runs the same directional test in minutes for the price of a few dollars in API tokens, and it stays fully private if you use the offline Neo4j and Ollama fork. If you are a strategist, marketer, or developer who wants to pressure-test an idea against a simulated crowd, this is the best free, open source way to do it today.
3 alternatives worth checking out
- OASIS by CAMEL-AI (github.com/camel-ai/oasis): The multi-agent social simulation engine that actually powers MiroFish's Twitter and Reddit interactions. If you are a developer who wants to build a simulation from scratch without the MiroFish UI, go straight to the source. OASIS scales to roughly one million agents and supports a wide range of social actions.
- AutoGen by Microsoft (github.com/microsoft/autogen): The industry-standard framework for multi-agent conversational AI. Where MiroFish is tuned specifically for social media simulation and forecasting, AutoGen is a general framework where you code agents to act as programmers, reviewers, and planners that collaborate on complex coding or reasoning workflows.
- CrewAI (github.com/crewAIInc/crewAI): A popular, lightweight framework for orchestrating role-playing autonomous agents into a "crew" that tackles a shared goal. It is less about mass social simulation and more about small, coordinated teams of agents, which makes it a good starting point if you want structured multi-agent workflows without heavy infrastructure.
Found this guide useful? Check out more AI tools and open source projects on Sudo Scout.
Related posts
Prime Agent: The Self-Improving AI Coding Agent With Persistent IPython and Built-In Subagents (2026 Guide)
Prime Agent is a free, open source self-improving RLM agent for coding and long-running autonomous tasks. Persistent IPython, built-in subagents, continual harness refinement, daemon-backed sessions. 15.8K stars.
NVIDIA Switchyard: Route LLM Traffic Across Models and Providers Without Changing Your API (2026 Guide)
NVIDIA Switchyard is a free, open source Rust proxy that routes LLM requests across providers. Translates between OpenAI and Anthropic APIs, supports Claude Code and Codex, A/B benchmarking, cost optimization. Apache 2.0.
Needle 2: The 14MB AI Model That Runs on Phones, Wearables, and Smart Home Devices (2026 Guide)
Needle 2 is a free, open source 45M-parameter foundation model for tool calling on tiny devices. 14MB binary, 28MB RAM, runs fully offline. LoRA fine-tuning, confidence gating, structured extraction. 5.4K stars.