MiroFish Installation Guide: Simulate a Startup Idea with AI Agents

Before installing

What MiroFish does-and what it does not prove

MiroFish describes itself as a multi-agent prediction engine. You upload seed material and state a prediction requirement; the system builds a graph, generates personas and memories, runs social interactions, and produces a report you can explore further.

For a startup idea, this is best used as an assumption generator. Synthetic agents can surface possible customer segments, language, conflicts, objections, and scenarios. They are still produced by models using your inputs and cannot reproduce real budgets, incentives, organizational politics, or purchase behavior reliably. It is not accurate to claim that they react exactly like real humans.

↳

Do not replace interviews, pre-orders, paid pilots, usage data, or sales conversations with a simulation. Use MiroFish to decide what your next real-world test should investigate.

Step 01

Prepare the required tools and accounts

The repository’s recommended source installation requires the following versions. Check them before installing dependencies so failures are easier to diagnose.

• Git for cloning the repository.
• Node.js 18 or newer, including npm.
• Python 3.11 or 3.12. The README does not list newer Python versions as supported.
• The latest uv Python package manager.
• An API key, base URL, and model name for an OpenAI SDK-compatible LLM service.
• A Zep Cloud API key for the memory graph.
• Alternatively, Docker with Docker Compose for the container workflow.

git --version
node -v
npm -v
python --version
uv --version

↳

The repository is free to download, but the hosted LLM and memory services may have quotas or usage charges. Set provider budgets and alerts before a large simulation.

Step 02

Clone MiroFish and create the environment file

Clone the official repository, enter its root directory, and copy the example environment file. Keep `.env` local and confirm it remains excluded from version control before adding real keys.

git clone https://github.com/666ghj/MiroFish.git
cd MiroFish
cp .env.example .env

git check-ignore .env

Step 03

Configure the LLM and Zep API keys

Open `.env` and replace every placeholder you intend to use. The default example points to Alibaba Cloud’s OpenAI-compatible endpoint and `qwen-plus`, but the README says any API compatible with the OpenAI SDK format can be used.

LLM_API_KEY=your_api_key_here
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus

ZEP_API_KEY=your_zep_api_key_here

↳

The optional LLM_BOOST_* settings should be omitted entirely when you are not using a second acceleration model. Do not leave placeholder boost variables in the file.

Option A · Recommended

Install and run MiroFish from source

From the repository root, run the combined setup script. It installs root and frontend Node dependencies, then uses uv to create the backend environment and synchronize Python dependencies.

• Frontend: http://localhost:3000
• Backend API: http://localhost:5001
• Use `npm run frontend` to start only the frontend.
• Use `npm run backend` to start only the backend.

npm run setup:all

npm run dev

↳

Run these commands from the repository root. Starting a root script from the frontend or backend directory will fail or run a different package script.

Option B · Container

Run MiroFish with Docker Compose

The official Compose file pulls `ghcr.io/666ghj/mirofish:latest`, reads the root `.env`, exposes ports 3000 and 5001, and persists backend uploads into a local volume.

git clone https://github.com/666ghj/MiroFish.git
cd MiroFish
cp .env.example .env
# Add your real keys to .env, then run:
docker compose up -d

docker compose ps
docker compose logs -f mirofish

↳

The Docker image uses the `latest` tag. For a repeatable production deployment, review releases and pin a tested image digest or version instead of assuming future `latest` images behave identically.

How a run works

Understand the five-stage MiroFish workflow

• Graph building: extract information from the seed material and create individual and collective memory using GraphRAG.
• Environment setup: identify entities and relationships, generate personas, and configure agents.
• Simulation: run interactions while interpreting the prediction requirement and updating temporal memory.
• Report generation: use ReportAgent to analyze the simulated environment.
• Deep interaction: inspect the resulting world and continue conversations with agents or ReportAgent.

↳

Every stage depends on the quality and framing of the seed material. Missing evidence and biased assumptions can become confident-looking output later in the pipeline.

Step 04

Prepare a startup simulation brief with real evidence

A one-line idea gives the system room to invent the market. A better seed package combines a clear offer with verified material: interview notes, competitor pricing, substitute workflows, reviews, market constraints, and observed customer behavior.

Remove personal data, trade secrets, credentials, confidential customer material, and anything you are not permitted to send to the configured providers.

STARTUP IDEA
Describe the product in one sentence:
[YOUR ANSWER]

TARGET CUSTOMER
Who experiences the problem, in what situation, and how often?
[YOUR ANSWER]

PROBLEM AND CURRENT BEHAVIOUR
What happens today? What tools, services, spreadsheets, or manual work do people currently use?
[YOUR ANSWER]

EVIDENCE
Add verified interview notes, search behavior, competitor pricing, reviews, market reports, and other relevant source material.
[YOUR ANSWER OR ATTACHED DOCUMENTS]

OFFER
What outcome does the product promise? What would it cost? How would customers discover and buy it?
[YOUR ANSWER]

ASSUMPTIONS TO TEST
1. [ASSUMPTION]
2. [ASSUMPTION]
3. [ASSUMPTION]

SIMULATION QUESTION
Simulate how the target market may react when this offer is introduced. Identify distinct customer segments, recurring objections, trust concerns, adoption triggers, switching barriers, pricing reactions, and disagreements between agents. Compare a base case, an optimistic case, and a skeptical case. Do not treat the simulation as real customer validation. End with the five most important hypotheses to test with real people.

Choose a narrow decision

Three useful business scenarios to simulate

A simulation becomes more useful when it compares explicit alternatives and produces hypotheses you can test. Attach the evidence behind the current behavior, price, audience, and channel before using one of these templates.

Simulate how each target-customer segment may respond if the price changes from [CURRENT PRICE] to [NEW PRICE].

Hold the product and acquisition channel constant. Identify perceived value, price objections, downgrade or churn triggers, segments with different willingness to pay, and information agents would need before accepting the change.

Compare no change, the proposed increase, and a version with added value. End with hypotheses to test through customer interviews, pricing-page behavior, renewal conversations, and a limited real-world pricing experiment. Do not estimate actual churn from synthetic agents.

Compare two messages for the same product and audience.

Message A leads with price: [PASTE MESSAGE]
Message B leads with outcome: [PASTE MESSAGE]

Simulate how different audience segments may interpret each message. Identify confusion, credibility gaps, emotional reactions, trust concerns, unintended meanings, questions, and reasons to ignore or share the campaign.

Do not predict that either message will go viral. End with a real A/B test plan, success metric, minimum test duration, and qualitative questions for five customer conversations.

Simulate the launch of [PRODUCT] to [TARGET CUSTOMER] through [CHANNEL].

Use the attached evidence about the problem, existing alternatives, price, onboarding, and distribution. Model an optimistic case, a base case, and a skeptical case. Identify discovery triggers, objections, switching costs, onboarding failures, trust barriers, likely questions, and differences between users, buyers, and decision-makers.

End with the five assumptions most likely to break the launch and the cheapest real-world experiment for each. Do not convert synthetic reactions into forecasted users, revenue, or market share.

↳

Use simulation to widen the scenario set, not to manufacture precise forecasts. If an answer cannot be checked against real behavior, treat it as a hypothesis.

Step 05

Run a small first simulation

Open the frontend, upload the prepared seed material, and enter the prediction requirement. Start with a narrow decision and fewer than 40 rounds, following the repository’s cost warning. Record the model, settings, seed documents, and question so later runs are comparable.

• Ask about one buyer, offer, price, or adoption decision at a time.
• Include a skeptical scenario instead of asking the system to confirm the idea.
• Run at least one variation that changes a major assumption such as price, audience, or distribution channel.
• Save the report and note where conclusions came directly from your seed material versus emergent agent interactions.

Step 06

Convert simulation output into falsifiable experiments

Do not average synthetic opinions into a fictional market-size estimate. Look for patterns that can become real research questions.

• Segments that describe the problem differently or care about different outcomes.
• Objections that repeatedly stop adoption or delay a purchase.
• Trust, privacy, integration, switching, or procurement barriers.
• Words customers may use when searching for a solution.
• Assumptions where small changes create very different simulated outcomes.

↳

The next step is not “build the full product.” Test the riskiest pattern with real strangers through interviews, a landing page, a paid pilot, a pre-order, or a manual concierge offer.

Before serious use

Review privacy, cost, and the AGPL-3.0 license

• Assume uploaded seed material and prompts may be processed by the configured LLM and memory providers; review their current data policies.
• Never commit `.env`, expose keys in screenshots, or paste credentials into simulation material.
• Use restricted provider keys where supported and rotate a key immediately if it leaks.
• Set model-spend limits and begin with small simulations before increasing rounds or agent counts.
• MiroFish is licensed under AGPL-3.0. Review its obligations before modifying it or making a modified version available over a network.
• Do not use synthetic forecasts as the sole basis for medical, legal, financial, hiring, safety, or other high-impact decisions.

Common failure points

MiroFish troubleshooting checklist

• Setup fails: confirm Node is 18+, Python is 3.11 or 3.12, and uv is available in the current shell.
• Model request fails: verify the API key, compatible base URL, model name, account quota, and provider region.
• Memory or graph step fails: verify the Zep API key and current quota.
• The UI opens but cannot run: confirm the backend is listening on port 5001 and inspect its terminal or container logs.
• A port is already in use: stop the conflicting service or deliberately change the mapped port and corresponding application configuration.
• Usage is unexpectedly expensive: stop the run, reduce rounds and scope, then inspect provider usage before trying again.
• Docker changes do not persist: confirm the Compose volume exists and that the process can write to `backend/uploads`.