Keep the seed narrow
Use one focused document or concise brief. A clean product launch note, public statement, policy proposal, market memo, or story summary is better than a giant mixed archive.
Complete tutorial
MiroFish tutorial: from first simulation to deployment and report review.
This guide turns the scattered MiroFish setup notes, workflow explanations, demo lessons, offline options, and CLI ideas into one learning path. Use it when you want more than a link list: a practical way to understand, run, evaluate, and iterate with MiroFish.
What MiroFish really is
MiroFish is best understood as a multi-agent scenario simulation engine. You provide reality seeds: a brief, policy draft, news event, market note, product plan, financial signal, transcript, or story world. MiroFish extracts entities and relationships, builds graph-grounded context, generates agent personas, runs interaction rounds, and then produces a structured report.
The chat surface is only the control layer. The deeper value is the sequence of seed data, graph construction, simulated perspectives, social interaction, evidence-backed reporting, and follow-up analysis.
The mental model
Seed material
GraphRAG context
Agent personas
Simulation rounds
Prediction report
Follow-up analysis
Do not treat a MiroFish result as a guaranteed future. Treat it as decision support: a way to compare possible paths, expose assumptions, discover weak narratives, and decide what to test next.
Lesson 1: prepare the first useful scenario
Name the actors
Tell MiroFish who matters: customers, critics, journalists, investors, regulators, competitors, developers, voters, fans, or undecided observers.
Set a horizon
A time frame such as 7 days, 14 days, 30 days, or 10 simulation rounds gives the report a sharper shape than an open-ended request.
A strong first prompt
Use a prompt that makes the social system explicit. This example works for launch, policy, public opinion, and market scenarios after you replace the actor list.
Please simulate the next 14 days based on this seed material.
Actors:
- early supporters
- skeptical critics
- industry observers
- journalists
- competitors
- undecided users
Report:
1. likely emotional trajectory
2. main objections and counter-narratives
3. messages most likely to spread
4. weak assumptions in the scenario
5. concrete actions that could improve the outcomeLesson 2: understand the five MiroFish stages
1. Graph building
The system extracts reality seeds, entities, facts, relationships, and memory context. Before simulation, check whether the important people, groups, organizations, events, and conflicts are present.
2. Environment setup
MiroFish creates agent personas with identity, background, behavior logic, perspective, and memory. This is where the scenario turns from static material into an interactive world.
3. Simulation
Agents interact on simulated social platforms. They can post, reply, agree, disagree, spread narratives, ignore topics, and shift sentiment over time.
4. Report generation
ReportAgent reviews the simulated environment, searches the graph, compares signals, and writes a structured report. Read it for evidence and assumptions, not only the headline conclusion.
5. Deep interaction
After the report, continue the analysis. Ask why a conclusion depends on a weak assumption, interview a simulated perspective, or rerun the scenario after changing one variable.
Lesson 3: deploy the official app
The official project is a decoupled full-stack app: a Vue/Vite frontend, a Flask backend, OpenAI-compatible LLM calls, Zep Cloud graph memory, and OASIS-based social simulation. Use this route when you want the canonical web workflow.
git clone https://github.com/666ghj/MiroFish.git
cd MiroFish
cp .env.example .env
npm run setup:all
npm run devThe frontend runs on http://localhost:3000. The backend API defaults to http://localhost:5001, and the Vite dev server proxies /api to the backend.
Official scripts and what they mean
| Command | Purpose | When to use it |
|---|---|---|
npm run setup |
Install root and frontend Node dependencies. | Use when frontend dependencies changed or after a fresh clone. |
npm run setup:backend |
Run uv sync inside the backend. |
Use when Python dependencies need to be installed or refreshed. |
npm run setup:all |
Install both frontend and backend dependencies. | Best default for first setup. |
npm run dev |
Start frontend and backend together. | Best default for local development. |
npm run backend |
Start only Flask through uv run python run.py. |
Use when debugging backend configuration or APIs. |
npm run frontend |
Start only the Vite frontend. | Use when the backend is already running elsewhere. |
Lesson 4: use Docker when you want the shortest path
The official Docker Compose file reads the same root .env, exposes ports 3000 and 5001, and persists uploads under the backend uploads directory.
cp .env.example .env
docker compose up -dUse Docker when you want a fast deployment-like environment. Use source mode when you plan to modify frontend or backend code.
Lesson 5: read reports like an analyst
Conclusion
What does the report think is likely: adoption, backlash, confusion, narrative split, slow burn, or unresolved uncertainty?
Evidence
Which simulated actions, graph facts, agent perspectives, or recurring arguments support the conclusion?
Path
How does the scenario move from initial event to reaction, amplification, disagreement, and outcome?
Assumptions
What must be true for the report to hold? Which actor behavior, timing, or information gap could break it?
Interventions
What could you change: message, price, audience, launch channel, timing, proof, product feature, or response plan?
Next run
Change one variable and rerun. Compare the delta rather than treating a single simulation as the whole answer.
Follow-up prompts after a report
Rank the report conclusions by confidence.
List the three weakest assumptions.
Explain the result from the critics' point of view.
What single variable would most change the outcome?
Turn this report into a management decision memo.
If a competitor responds aggressively on day 3, how does the scenario change?Lesson 6: choose the right deployment path
Official web app
Use the official stack for the canonical browser workflow: seed upload, graph build, environment setup, simulation, report, and interaction.
Self-hosted official stack
Run frontend and backend yourself, but still verify whether LLM and Zep memory calls leave your network.
Fully local direction
A fully local approach needs local model inference, local embeddings, local graph or memory, local storage, and controlled logs.
CLI automation
A CLI-first workflow is useful for batch simulations, saved artifacts, JSON reports, and repeatable scenario evaluation.
Hosted plan
Use a hosted plan when you want the workflow without maintaining the deployment, runtime, and business data path yourself.
Research workflow
For markets or prediction questions, use MiroFish to test narrative branches, not to replace fresh data or domain judgment.
Troubleshooting quick map
| Symptom | Likely cause | Fix |
|---|---|---|
LLM_API_KEY error |
The backend reads configuration from the project root .env. |
Copy .env.example to root .env and fill the LLM variables. |
ZEP_API_KEY error |
The official GraphRAG memory path expects Zep Cloud. | Add a Zep key or use a local/offline fork designed to replace that dependency. |
| Frontend loads but API fails | The Vite dev server expects the backend at port 5001. | Start npm run backend, or set matching backend host and port values. |
| Slow or expensive run | Large seed material, high round count, or expensive model settings. | Start with fewer rounds, smaller seed files, and a focused requirement. |
| Generic report | The seed and prompt do not name actors, conflicts, time horizon, and output sections. | Rewrite the scenario before scaling the run. |
Five-day learning plan
- Day 1: Understand the workflow, read this tutorial, and run a small scenario through the quick-start path.
- Day 2: Deploy the official app with source or Docker, confirm the frontend and backend ports, and run one low-round simulation.
- Day 3: Improve prompts. Compare product launch, public opinion, and market narrative scenarios.
- Day 4: Practice report review. Separate conclusion, evidence, path, assumptions, and intervention points.
- Day 5: Choose a longer-term route: hosted plan, official self-hosting, offline/local experimentation, or CLI automation.
Reference sources
This tutorial condenses the official MiroFish README, the existing MiroFish how-to-use guide, technical notes from DeepWiki, the MiroFish offline/self-hosting guide, and public video walkthroughs. Use the links below only as source material; the recommended next action stays inside the MiroFish product path.
Frequently asked questions
Should I start with source or Docker?
Use source mode if you want to modify code or inspect the stack. Use Docker when you want the shortest path to a running app.
Is a longer simulation always better?
No. Better seeds and sharper requirements usually improve quality before more rounds do.
Can I trust the prediction?
Use it as structured scenario rehearsal. MiroFish can reveal possible reactions and weak assumptions, but it does not replace fresh evidence or expert review.