Skip to content
Hoh JDLatest guide
All guides
AI simulation15 min setup

MiroFish setup: test how people react before you announce

Jump to a section

MiroFish lets you rehearse the future. Give it a document (a news story, a launch post, a policy draft) and a question. It creates AI agents with their own personalities and memories, lets them post and argue on simulated social media, then writes you a report. You can even chat with any agent about why it reacted the way it did.

It's free and open source, built by the MiroFish team (GitHub: 666ghj): https://github.com/666ghj/MiroFish

Want to see it first? Try the demo, nothing to install: https://666ghj.github.io/mirofish-demo/

Setup takes about 15 minutes.

What you need

  • An AI model key: OpenAI is easiest. Alibaba's Qwen is what the MiroFish team recommends. Pay as you go.
  • A Zep Cloud key: gives the agents memory. The free monthly quota is enough to start.
  • Docker Desktop: runs MiroFish for you. Free: https://www.docker.com/products/docker-desktop/
  • Claude Code, if you want it to do the setup for you (recommended)

Mind the cost: every simulation makes a lot of AI calls. Start with a short document and the default 10 rounds, and stay under 40 rounds until you know what a run costs you.

1. Get your two keys

  1. OpenAI: go to https://platform.openai.com/api-keys, click Create new secret key, and copy it. Add a little credit under Billing.
  2. Zep: sign up at https://app.getzep.com/, create a project, open API Keys, and create one.

Keep both somewhere private. Anyone with your key can spend your credit.

2. Let Claude Code set it up

Open Docker Desktop and wait until it says it's running. Then open Terminal (Mac) or PowerShell (Windows), type claude, and paste this:

Set up MiroFish for me from https://github.com/666ghj/MiroFish. Clone it into my home folder. Create the .env file from .env.example with only these four lines: LLM_API_KEY, LLM_BASE_URL=https://api.openai.com/v1, LLM_MODEL_NAME=gpt-4o-mini and ZEP_API_KEY. Delete the LLM_BOOST lines completely. Leave the two keys as placeholders, open .env for me so I can paste them in myself, and wait until I say done. Then start it with docker compose up -d and tell me when http://localhost:3000 is ready.

When .env opens, paste your two keys after the = signs (no spaces, no quotes), save, and tell Claude done. You paste the keys yourself so they never go into the chat.

When Claude says it's ready, open http://localhost:3000.

Or do it by hand

  1. Download the ZIP from https://github.com/666ghj/MiroFish (green Code button, then Download ZIP) and unzip it.
  2. Open a terminal in that folder. On Mac, right-click the folder and choose New Terminal at Folder.
  3. Create a file called .env in the folder with exactly this, using your real keys:
LLM_API_KEY=sk-your-openai-key
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL_NAME=gpt-4o-mini
ZEP_API_KEY=your-zep-key
  1. With Docker Desktop running, start it:
docker compose up -d
  1. Open http://localhost:3000. The first start takes a few minutes while it downloads.

To stop MiroFish later, run docker compose down in the same folder. To start it again, run docker compose up -d.

3. Run your first simulation

The app walks you through it:

  1. Upload a file and ask a question. A PDF, Markdown or text file works. A one-page article is perfect for a first run. For example:

A city announces higher fuel taxes to fund public transport. How will people react online in the first week? Who supports it, who pushes back, and why?

  1. Graph build: MiroFish maps the people and groups in your document and how they connect.
  2. Agent setup: each one becomes an AI agent with a profile and memories, like a journalist, a student or a parent.
  3. Simulation: the agents post, comment and reply to each other, round by round.
  4. Report and chat: you get a prediction report. Then ask any agent "Why did you push back on this?"

Ideas to try

  • Product launch: how will customers and competitors react to your announcement?
  • Brand crisis: does the conversation calm down faster if the company apologises or stays quiet?
  • Policy draft: which groups support it, which oppose it, and why?

If it doesn't work

  • Error mentioning LLM_API_KEY 未配置 or ZEP_API_KEY 未配置 ("key not set"): the file must be named exactly .env (not .env.txt) and sit in the main MiroFish folder.
  • The graph builds but the simulation fails: delete any LLM_BOOST_... lines from .env, then restart.
  • ZEP_API_URL 不受支持 ("not supported"): delete the ZEP_API_URL line. MiroFish only works with Zep Cloud.
  • 401 or "invalid API key": re-paste the key with no spaces or quotes, save, and restart.
  • localhost:3000 won't load: check Docker Desktop is open and MiroFish is running, and that nothing else is using port 3000 or 5001.
  • Your bill is climbing: use shorter documents, fewer rounds, or a cheaper model like gpt-4o-mini.

Stuck on something else? Paste the error into Claude Code and ask it to fix it.

Two things to remember:

  • It's a rehearsal, not a crystal ball. Real people can behave differently. Use it to spot reactions you hadn't thought of, not as a guaranteed forecast.
  • Never share your .env file. It holds your keys.

MiroFish is an open-source project by the MiroFish team (github.com/666ghj/MiroFish), released under the AGPL-3.0 license. Its simulation engine is built on OASIS by the CAMEL-AI team, and agent memory runs on Zep. All credit to them. This guide isn't affiliated with the project.