# MiroFish simulates a population and calls it prediction, with no error bar

> An AGPL-3.0 multi-agent simulation engine where you upload seed material and receive both a report and an explorable simulated world. The two domains most readers would want, finance and politics, are listed as coming soon, the container image runs the development script, and nothing in the documentation measures accuracy.

**666ghj/MiroFish** — MiroFish is a swarm-intelligence engine that builds a parallel digital world from seed materials, letting thousands of interacting agents simulate future trajectories.

- Repository: https://github.com/666ghj/MiroFish
- Website: https://mirofish.ai
- Stars: 75,298 · Forks: 11,588
- Language: Python
- License: AGPL-3.0
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/666ghj-mirofish

## The Dockerfile ends in the dev script, and the image is tagged latest

Start with the deployment story, because it sets expectations for everything after it. The compose file pulls a single image, ghcr.io/666ghj/mirofish:latest, with a second regional mirror left commented out for people whose pulls are slow. There is no tag pinning, so two people running the compose file on different days get different code and the file itself cannot tell you which. The Dockerfile compounds this. It is built from a Python 3.11 base, installs Node from the system package manager, copies uv in from a pinned image, and then installs dependencies carefully with npm ci and a frozen uv sync. Its final command is the development script, which runs the front end and back end concurrently, not a production server. A build script that would produce a front-end bundle exists in the manifest, and the image never calls it. The consequence is that the container path is a development environment that happens to be packaged, and it should not be treated as a deployment target.

```bash
cp .env.example .env
docker compose up -d
```

## Finance and politics are the two examples listed as coming soon

Read the demonstration section closely, because it defines what the tool has actually been shown to do. Two worked examples ship: a public opinion simulation around Wuhan University, and a reconstruction of the lost ending of Dream of the Red Chamber. Both are the same shape of task, which is to take a body of text and let a population of agents interact with it, and in the university case the seed report was itself produced by a separate tool. Immediately after them comes a line stating that financial prediction, political news prediction and further examples are coming soon. Those are the two domains that would make this decision-relevant for most readers, and they are the two with no worked example at all. The consequence is that any evaluation has to be built on the university exercise and the novel, and the distance between what the framing promises and what has been demonstrated is exactly the width of the examples that do not exist yet.

## Two paid services are required before a simulation can start

The setup is short and it depends on two external services before anything runs. The first is an LLM endpoint speaking the OpenAI SDK format, so almost any provider qualifies, but the configuration example points at one specific hosted model, with a comment that consumption is high and that you should try simulations with fewer than forty rounds first. The second is a hosted memory graph product, where the configuration file notes that the free monthly quota is sufficient for simple use. There is also an optional boost tier with its own key, base URL and model name, and that same file carries an explicit instruction that if you are not using the boost settings, those entries should not appear in the env file at all. The consequence is that this is not a project you can run for free, and the bill scales with the number of agents multiplied by the number of rounds, which is what that forty-round advice is really about.

```bash
cp .env.example .env
```

## Python is pinned to a two-version window and Node to a floor

The prerequisites table is short, and the Python entry is unusually narrow. Node is 18 or newer for the front end, uv is expected as the Python package manager, and Python is given as greater than or equal to 3.11 and less than or equal to 3.12. That is a two-version window, which matters because 3.10 is excluded and so is 3.13. On a current operating system you may need a version manager to land inside the supported range before anything installs at all, and the Dockerfile confirms the choice by starting from a 3.11 base. The Node side is only a floor, making it the more forgiving of the two constraints. The consequence is asymmetric and worth planning around before you start: a too-new Python is a hard stop that fails at install time, while a too-old Node is merely a missing capability you discover later.

## Every release is 0.1.x, the newest from March, and the manifest says 0.1.0

Three releases exist and all of them are pre-1.0: v0.1.0 in December 2025, v0.1.1 in January 2026, and v0.1.2 in March 2026. The last push to the main branch was on 2026-09-16, so the newest tag sits roughly six months behind the tip of the branch. A second inconsistency sits on top of that one: the root package manifest still declares its version as 0.1.0, so the number written inside the repository is behind even the oldest tag. Set alongside a container image tagged latest, there are now three different answers to the question of what version you are running, and none of them is authoritative. The consequence is that this software is pre-1.0 by its own numbering and carries no stability promise, so anyone who needs reproducibility has to record a commit hash and build from source rather than pull an image and hope.

## The prediction claims arrive with no accuracy measurement attached

The framing is bold, and none of it is disputed here. The project describes itself as a prediction engine that constructs a high-fidelity parallel digital world containing thousands of agents with independent personalities, long-term memory and behavioural logic, and says you can inject variables from a god's-eye view to deduce future trajectories. What is worth noticing is what sits next to it, or rather what does not. Across the whole document there is no accuracy measurement, no benchmark of a simulated result against what subsequently happened, no error bar, and no stated confidence interval. The one place the document describes its own epistemic standing is the vision section, which frames the tool as a rehearsal laboratory where policies and public relations can be tested at zero risk, and as a creative sandbox for exploring scenarios. The consequence is that the value of the output lies in the argument it forces you to construct and the assumptions it forces you to write down, not in a number you can put in a decision.

## The engine is an upstream project, so the simulation core is not here

The acknowledgements section names where the simulation engine actually comes from, crediting an open agent social interaction simulations project and thanking the team behind it. That line carries more weight than a usual credit, because it means the component doing the real work, running the agents and letting them interact, is a third-party dependency rather than code in this tree. What this repository wraps around it is the five-stage pipeline: graph building from seed extraction through memory injection and graph construction, environment setup with entity relationships and persona generation, the parallel simulation itself, report generation through a report agent with a toolset, and an interactive layer for chatting with any agent in the world. So there are two separate questions when you evaluate this. Whether the pipeline around the engine is well built, which you can read here, and what the engine does, which you have to go and read over there. Nothing in this repository pins the dependency's version or its behaviour.

## Conclusion

Use MiroFish when you want to rehearse a decision by watching a population of agents react to a document, and treat the report as a structured argument you have to argue with rather than a forecast you can act on. Do not adopt it for the two domains it advertises, because financial and political prediction are both listed as coming soon and no worked example exists for either. Three things to check before you build anything on it. You need two paid services configured, an OpenAI-format LLM endpoint and a hosted memory graph key, and the cost scales with agents times rounds. The container image is tagged latest and its Dockerfile ends by starting the development server, so record a commit hash and build from source if you need reproducibility. And read the upstream engine yourself, because it is a separate project and this repository pins neither its version nor its behaviour.

## FAQ

### What is a MiroFish?

It is an AGPL-3.0 multi-agent simulation engine. You upload seed material such as a report or a story, describe what you want to explore in natural language, and it returns a prediction report alongside an interactive simulated world you can chat with. The engine underneath is credited to a separate open agent social interaction simulations project.

### How do I install MiroFish?

There are two routes. From source, copy the env example, fill in the API keys, run the one-click setup, then start both services with npm run dev, which gives a front end on port 3000 and a backend on port 5001. With Docker, copy the env file and run docker compose up -d, which pulls an image tagged latest.

### Is MiroFish open source?

Yes. The root package manifest declares AGPL-3.0 and a LICENSE file is present at the top level. The project received strategic support and incubation from Shanda Group, and its simulation engine is credited to an external open source project maintained by a different team.

### Is MiroFish legit?

The licence and provenance check out: AGPL-3.0, a named corporate incubator, and a credited upstream engine. What the documentation does not supply is any accuracy measurement, benchmark or error bar for the prediction output, so treat a report as a rehearsal of your own assumptions rather than a forecast.

## Sources

- [Official documentation](https://mirofish.ai)
- [Official README](https://github.com/666ghj/MiroFish#readme)
- [Project repository](https://github.com/666ghj/MiroFish)
- [Release notes](https://github.com/666ghj/MiroFish/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/666ghj-mirofish