How to use MiroFish
There are two ways to use MiroFish. Online, through a hosted service such as MiroFish.co.uk: you paste or upload your material, describe who should react, and read a study in your browser, with nothing to install. Or self-hosted: you install the open-source engine from GitHub, add your own language-model and Zep keys, and run its five-step workflow yourself. This guide walks through both, and through the part that matters most either way: what you give it.
Written by MiroFish.co.uk, an independent hosted service built on the open-source MiroFish project. Upstream facts were checked against the MiroFish repository on 21 October 2026 (its documentation is unchanged since commit 39d8491).
Use MiroFish online, with nothing to install
The quickest way to see what MiroFish does is to run it on a hosted service. On MiroFish.co.uk a run is called a study, and your first Quick Study is free once you confirm your email address.
Create an account
Create an account and confirm your email address. The free Quick Study is added when the address is confirmed; no card is needed.
Say what you are deciding
Write the decision in a sentence or two: the price you are about to change, the launch, the campaign line, the statement. Templates cover the common cases.
Add the material
Paste it, or upload up to 10 files of up to 50 MB each in PDF, Markdown or plain text. For a Word document, export a PDF or paste the text.
Describe the audience
Say who should react, in your own words, and choose a lens such as Customers, Journalists, Employees or Critics. Leave the description empty and the audience is drawn from the people your material names.
Choose the depth and run it
A Quick Study runs five discussion rounds on a smaller audience and returns a three-section report. A Standard Study runs ten rounds on a larger audience and returns four to seven sections. Most studies take 10 to 25 minutes, and you can close the page while one runs.
Read the study
Start with the decision-readiness verdict, then the findings and the quotations they rest on. Each quotation is verbatim from the discussion and shows the round it came from.
To see what comes back before you run one, read a complete example study.
Use MiroFish self-hosted: the upstream workflow
MiroFish itself is open source, published on GitHub by 666ghj under the AGPL-3.0 licence. Running it yourself gives you the whole upstream workflow, including the knowledge graph and chatting with individual agents. In outline, following the README:
Install the prerequisites
Node.js 18 or later, Python 3.11 or 3.12 and uv; or Docker.
Add your keys
Copy .env.example to .env. Fill in LLM_API_KEY, LLM_BASE_URL and LLM_MODEL_NAME for a language-model API in the OpenAI SDK format, and ZEP_API_KEY for Zep Cloud, which holds the graph memory.
Install and start
Run npm run setup:all, then npm run dev, and open http://localhost:3000. With Docker, run docker compose up -d instead.
Give it seed material and a question
Upload the material, such as a report or a story, and describe in plain language what you want to explore.
Let it build and simulate
MiroFish builds a knowledge graph from the material, generates agents with personas and memory, and runs them on two simulated social platforms. The README warns that consumption is high and suggests trying fewer than 40 rounds first.
Read the report and question the agents
A report agent writes up what happened. You can then chat with any agent and with the report agent.
The full requirements, the Docker route and the fully local fork are set out in Self-hosted vs hosted MiroFish.
What to give MiroFish: the part that shapes the result
Whichever route you take, the material and the audience description shape the result more than any setting. A simulated audience can only react to what it is given, in ways shaped by how you describe it.
- Give it the real thing. The actual pricing page, announcement or ad copy, not a summary of it. A summary removes the wording people would react to.
- State the decision. "Should we move from £199 one-off to £29 a month?" gives the discussion something to argue about; "our pricing" does not.
- Describe people, not segments. "Sole traders who do their own books and worry about monthly cash flow" produces sharper reactions than "small businesses".
- Include the people who could object. Critics, journalists, competitors' customers or employees often find the problem first.
- Keep one decision per run. Two options side by side is fine; five unrelated questions blur the findings.
How to read what comes back
A MiroFish run is a rehearsal, not a forecast. Read it for the objections, the confusion and the differences between groups, and treat any score as a summary of the simulated discussion, not a measurement of real people.
- Start with the verdict and the reasons given for it.
- Check each finding against the quotations beneath it. If the evidence does not convince you, discount the finding.
- Look at what changed between rounds: an objection that grows over the discussion matters more than one that fades.
- Write down the questions worth asking real customers, and ask them.
The methodology page explains how a study is built and where the method stops.
Common mistakes
- Treating the output as a forecast. It shows what could plausibly happen under the assumptions you set.
- Testing a summary instead of the material people will actually see.
- Describing the audience so narrowly that everyone agrees, or so broadly that nobody has a reason to care.
- Self-hosted: starting with a long run. The README warns that consumption is high; check a short run first. On a hosted service the run length is set by the study type.
Questions people ask
Can I use MiroFish without installing it?
Yes, through a hosted service. MiroFish.co.uk is an independent hosted service built on the open-source MiroFish project. You run studies in your browser.
How do I use MiroFish for free?
The software is free under the AGPL-3.0, but self-hosting means paying your language-model provider, and Zep Cloud beyond its free monthly quota. On MiroFish.co.uk the first Quick Study is free once you confirm your email address.
How long does a MiroFish run take?
On MiroFish.co.uk most studies take 10 to 25 minutes. Self-hosted, it depends on the model, the number of agents and rounds, and your setup; the README suggests starting with fewer than 40 rounds.
Do I need to know how to code?
Not to use a hosted service. To self-host you need to be comfortable installing Node.js and Python tools, editing an .env file and running commands in a terminal.
Is MiroFish.co.uk the official MiroFish project?
No. It is an independent hosted service built on the open-source MiroFish project. The upstream project is on GitHub; the source of this service is at mirofish.co.uk/source.