Introduction
Most AI tools answer your question with one model’s opinion. MiroFish answers it with a simulated crowd. You drop in research data, ask a forecasting question, and the tool spins up dozens of autonomous AI agents — with different personas, goals, and biases — who debate, post, comment, and quote-reply on each other across simulated Twitter and Reddit. Hundreds of rounds later you get a structured report on what they collectively predict.
It hit 51,000 GitHub stars in 10 days, $4M+ in early funding, and a turn at the top of the global trending charts. This guide walks through what MiroFish is, how the five-stage simulation pipeline works, the one-click deploy path on Hostinger, and a real run forecasting Dubai real-estate prices through 2035. You finish with an installed instance and the muscle memory to use it for your own questions.
📚 Table of contents
- What MiroFish actually is
- Why swarm intelligence beats single-model prediction
- The five stages: graph, agents, simulation, report, interaction
- The tech stack underneath
- Deploying on Hostinger (one-click) or locally
- OpenAI and Zep Cloud API keys
- Running a real forecast end-to-end
- Choosing wheels (simulation rounds) wisely
- Interrogating the resulting agents
- Real-world use cases
- Limitations
- Common mistakes
- Frequently asked questions
🐟 What MiroFish is
A swarm-intelligence simulation engine built on top of Oasis. Feed it context (a research report, market data, news clips), ask a question, and it generates a digital society of agents who interact like real users on a social network. The collective behavior of those agents over time becomes the forecast.
- Open-source, 51K+ stars at launch, 7.6K forks
- Built in 10 days, $4M+ funding
- Top GitHub trending repo globally
- Runs on any OpenAI-compatible model (Claude, GPT, MiniMax, etc.)
👥 Why swarm intelligence
Single-model prediction is one perspective filtered through one model’s biases. Swarm simulation is hundreds of perspectives with different goals, talking to each other, updating their own views as they go. The same logic that makes prediction markets work better than expert forecasts: aggregated, diverse, dynamic.
Real examples already running on top of similar engines: a PolyMarket prediction bot earning ~$4K, a BTC fear/greed index, public-opinion simulators, story-ending generators for books and movies.
🔁 The five-stage pipeline
- Knowledge graph build. Parses your input documents and extracts entities, relationships, claims.
- Environment setup. Generates 20–40 agents (personas, memories, goals, activity windows) based on the topic and source data.
- Dual-platform simulation. Two parallel simulated social networks — Twitter-style (Info Plaza) and Reddit-style (Topic Community) — over multiple rounds.
- Report generation. A specialized report agent interviews the simulated agents and synthesizes findings.
- Deep interaction. You can chat with any agent or the report agent to dig into reasoning.
🧰 The tech stack
- Oasis — the simulation engine
- Zep Cloud — memory layer (only paid component; free tier covers most usage)
- FastAPI — backend
- Vue/JS — frontend
- Any OpenAI-compatible LLM — pick by cost/quality
🚀 Deploying MiroFish
Two paths:
Hostinger one-click
Start at ~$6.50/month (KVM 1); KVM 2 at $9/month is more comfortable. Click deploy, paste your API keys, get a secure URL. Avoids the three hours of local setup.
Local from GitHub
Clone the repo, fill in env vars, run setup commands. Works fine but takes longer and uses local resources during simulations.
🔑 API keys you’ll need
- OpenAI or any OpenAI-compatible provider. GPT-4o is a good default ($3 for a typical simulation); avoid frontier models like Opus or GPT-5 unless you’re fine with $30+ runs.
- Zep Cloud — sign up at app.getzep.com, create a project, generate a key. 1,000 free credits, plenty for evaluation.
Set a hard spend cap on your OpenAI project before running anything — agent simulations can burn through credits faster than you expect with poorly chosen models.
🏙️ A real forecast end-to-end
Example used in the walkthrough: Dubai real estate over the next 10 years, with current war context in the Middle East factored in.
- Use Claude or another research agent to produce a 20–30 page markdown report with historical data, current sentiment, and news.
- Drop the report into MiroFish’s upload area.
- Add a forecasting prompt: “Predict the price of two-bedroom apartments in downtown Dubai over the next 1, 2, 5, and 10 years given current market data and the Iran war.”
- Start the engine. Watch the knowledge graph build live.
- Approve the generated agent personas (you’ll see Trump, Pelosi, UAE defense ministry, Goldman Sachs, plus invented retail-investor accounts).
- Pick the wheel count (10 minimum for a quick run, 100+ for a deep simulation).
- Watch the dual-platform simulation: posts, replies, retweets, dislikes appear in real time.
- Trigger report generation; the report agent interviews each agent and synthesizes a forecast.
- Click Deep interaction to chat with the report agent or individual personas.
🎡 Choosing wheels wisely
Wheels = how many rounds the simulation runs. More wheels = richer behavior and longer runtime.
- 10 wheels — quick evaluation, useful for testing prompts (~5 min, ~$1)
- 30 wheels — reasonable depth (~20 min)
- 60 wheels — serious forecasting (~45 min)
- 120 wheels — deep simulation (~hours, $$$)
Start with 10 to validate your input quality. Only crank wheels up after you’ve seen the agents behave sensibly.
🗣️ Interrogating the agents
The most underrated feature. Once the report is generated, you can chat with the report agent (“What’s the ultimate conclusion?”) or with any individual persona (“Trump, what do you think of Dubai?”).
Each agent retains the influence of every other agent they interacted with. So you’re not just seeing what a generic model thinks of Dubai — you’re seeing what an agent thinks after being shaped by debate with US defense, UAE ministry, a Goldman analyst, and three retail investors. The voice of well-known figures comes through surprisingly cleanly.
🎯 Real-world use cases
- Market and price forecasting (real estate, equities, crypto)
- Public-opinion modeling for product launches
- Predicting story endings for books, films, games
- Political event simulation
- Brand-perception what-if analysis
- Sentiment forecasting before campaigns go live
⚠️ Limitations
- Forecasts are bound by what’s in your source data — garbage in, garbage out
- Model bias still shows up — less than single-model, but not gone
- No real-time data unless you connect external feeds (not natively supported yet)
- Cost scales with wheels and model choice — budget carefully
- UI is Chinese-translated; some labels feel rough until you get the pattern
- Doesn’t replace domain experts — treat as a structured second opinion
❌ Common mistakes
- Running 120 wheels on Opus and getting a $50 bill
- Skimping on source data — agents have no real context to debate over
- Asking yes/no questions — the simulation shines on probabilistic forecasts
- Treating the report as truth instead of one more signal
- Not setting a hard spend cap on the underlying OpenAI project
- Exposing the public URL without rate-limiting and letting strangers burn your API budget
Conclusion
MiroFish is one of the more imaginative AI projects of 2026. Swarm simulation as a forecasting technique is genuinely useful, the open-source pipeline is approachable, and the one-click deploy makes it accessible without three hours of YAML. Use it as a structured second opinion on multi-actor questions — markets, public opinion, narrative endings — and pair it with your own analysis rather than treating it as oracle.
Run one simulation tonight on a question you actually care about. The agents debating in two simulated social networks while you watch is its own demo.
Explore More on DevShelf
-
Claude AI — Tool Profile
Anthropic's Claude works as a drop-in MiroFish model — useful when GPT-4o costs are too high for long simulations.
-
Learn Agentic AI in 7 Steps
The multi-agent debate patterns in MiroFish map directly to Step 3 of this sequenced agentic AI path.