A thousand fake customers before launch

What it is and why it matters

Before a launch, you usually guess. Is the price right? Does the line at the top of the page make sense? Does the ad spark curiosity or annoy people? You find out when the first real customers arrive, and by then you've already spent time and money.

MiroFish is a multi-agent simulation engine, free and open source on GitHub, with more than 80,000 stars. An agent here is a character driven by an AI model: it has an age, a personality, a memory and its own opinions. You give it starting material, which the project calls a seed: your product page, your pricing, an ad, a news item. It builds a small world out of it, fills it with agents and lets them talk to each other on two simulated social networks, a Twitter-style feed and a Reddit-style community. At the end it writes a report, and you can ask questions to each one of them.

It's for people about to launch something on their own. It's not a crystal ball, it's a dress rehearsal: it shows you where your page might not land, and why, before a real customer finds out.

1. What you need

• Git, Node.js, Python and uv, a package manager for Python. The right versions are in the README's Prerequisites table: Python also has an upper limit, so the newest one might not work. Or just Docker.
• An API key for a language model that uses the OpenAI SDK format. The README recommends the qwen-plus model on Alibaba's Bailian platform, but any compatible service works.
• A Zep Cloud key, the service that holds the simulated world's memory as a graph, meaning a map of people, things and links. According to the README, the free monthly quota is enough for simple use. MiroFish only connects to Zep Cloud.
• The texts for it to read, as PDF, Markdown or TXT files.

One thing to know right away: the program runs on your computer, but what you upload goes out to the model's service and to Zep Cloud. Don't give it confidential documents or your customers' data.

2. Install and start it

1. Download the project with git clone https://github.com/666ghj/MiroFish and go into the folder.
2. Copy the example file with cp .env.example .env. The .env file holds the keys and stays only on your computer.
3. Open .env and fill in LLM_API_KEY, LLM_BASE_URL, LLM_MODEL_NAME and ZEP_API_KEY. At the bottom there are three LLM_BOOST lines, for an optional second, faster model: if you don't use it, delete them. The comment in the file says so, and it's in Chinese.
4. Install everything with npm run setup:all.
5. Start it with npm run dev. The interface is at http://localhost:3000, and the backend answers at http://localhost:5001.

With Docker, after step 3 all it takes is docker compose up -d: it reads the same .env and uses the same ports. The interface opens in Chinese: pick English from the language menu. There are only Chinese and English, and the language you pick there is also the language of the report and of the agents' answers.

Claude Code can do almost all the work. The only thing I do myself is the keys: I type them by hand into .env and never paste them into the chat.

Install MiroFish (https://github.com/666ghj/MiroFish) in a new folder, outside my projects.
Read the README and the .env.example file, and check that Git, Node.js, Python and uv are at the required versions. If something is missing, tell me how to install it before doing it.
Create .env from the example file, remove the three LLM_BOOST lines and leave the keys empty: I'll fill them in myself.
When I tell you I'm done, run npm run setup:all and then npm run dev, and tell me whether the frontend and backend start without errors.

3. Prepare your launch seed

The result depends on what you give it to read. To rehearse a launch I prepare a single Markdown file containing:

• The landing page text from top to bottom, exactly as it is.
• The pricing: the plans, what each one includes, the free trial if there is one.
• The ad you want to run: the copy and what you see in the image or video.
• Two lines on who you think your customers are. They help create believable agents.

Read my landing page (<path or address>), the pricing (<path>) and the ad copy (<text>).
Write a launch-seed.md file for MiroFish: the page text as it is, the pricing in a table, the ad and two lines about the customers I have in mind (<who they are>).
Don't improve anything and don't add promises the page doesn't make: it has to be the version I would publish tomorrow.

Then there's the second field, the request: what you want to know, in plain words. The more precise it is, the more the report answers your question and not another one. Mine, for a launch:

Simulate how <freelancers and small teams> react to the page and the ad in the first days after launch. I want to know: what isn't clear, which objections they raise about the price, who would share it and why, and which line of the page gets quoted most, for better or worse.

4. Run the simulation, with few rounds

You upload the file, write the request and press Start Engine. From there MiroFish goes through five stages, which you see one after the other:

1. Graph Build: it reads the document and builds the graph on Zep.
2. Env Setup: it creates the agents, each with an age, a country, a personality, a bio and memories taken from the seed. This is also where you decide how many rounds to run.
3. Run Simulation: the two social networks run together. Each round is a slice of simulated time in which the agents post, comment, like and follow each other.
4. Report Generation: a dedicated agent, the ReportAgent, reconstructs what happened and writes the report, section by section.
5. Deep Interaction: you chat with the ReportAgent or with any agent in the world, or send the same question to a group.

The money is in the rounds. MiroFish suggests a number on its own, but it uses a lot: the README says to try fewer than 40 rounds first, and the screen itself recommends switching to Custom the first time. In Env Setup turn on Custom and lower the slider, which starts at 10. Do a small test, check that everything works and the report makes sense, and only then go longer.

5. Read the report and question the fake customers

I read the report the way I read the comments under a post: I don't count votes, I look for the phrases that keep coming back. Three questions: what wasn't understood? Which objection comes up most often? Who defended the product, and with what words?

Then the most useful part, Deep Interaction. Pick an agent who criticized the price and ask why, and what would change their mind. With Send survey you select a group of agents and send them all the same question. My usual questions:

You've seen the page: in one sentence, what does this product do?
What made you doubt it the most?
At what price would you try it, and what would you expect to get?
What would you tell a friend who asks you whether it's worth it?

Careful: the simulation and the interviews only work while the environment is running. From the history you can reopen the graph, the environment and the report, but not the simulation or the interviews. Ask your questions before you close it.

The report also ends up in a file, full_report.md, inside backend/uploads/reports. There Claude Code can read it, next to your page:

Read the latest MiroFish report (the most recent full_report.md file in backend/uploads/reports) and my landing page.
List the objections that come up most often, each with the line of the page that triggers it.
For each one, suggest a change to the page. Keep what looks like a real problem apart from what might just be an idea of the simulation: I'll check that with real people.

6. The limits, stated plainly

• It's a dress rehearsal, not a forecast. The agents are language models playing a part: the report gives you hypotheses to check with real people, not sales figures.
• It costs money. The program is free, but every round means many calls to the model, which your provider charges by usage. More agents and more rounds, more spending. Zep Cloud costs money if you go beyond the free quota.
• Your texts leave your computer. There's a fork, MiroFish-Offline (github.com/nikmcfly/MiroFish-Offline), that replaces Zep Cloud with Neo4j and the cloud model with Ollama, so everything stays local. It's not from the original team, and its README asks for a strong machine: at least 16 GB of RAM, and a graphics card is recommended.
• The license is AGPL-3.0. Using it for yourself is free. But if you modify the code and let others use your version over a network, for example as an online service, you have to offer those users the source code of your modified version.

Common mistakes

• Running the first simulation with the rounds MiroFish suggests. Turn on Custom and start low.
• Writing a vague request, like “what do they think?”. Ask for specific things: what isn't clear, the price objections, who shares it.
• Taking the report as a forecast and redoing everything. What comes out of the simulation gets checked with a few real people.
• Closing the environment before asking the agents your questions.

Checklist

• The four model and Zep entries in .env, with no LLM_BOOST lines if I don't use them
• A seed file with the page, pricing and ad as I'll publish them
• A precise request, with the questions that matter for the launch
• First test in Custom, with few rounds
• Questions to at least one critic and one supporter before closing the environment
• The main objections noted down, to check with real people

Frequently asked questions