Five stages turn a source file into a synthetic society
MiroFish's 5-stage workflow accepts PDF, Markdown, and text material, extracts a graph, creates personas, configures two simulated social platforms, runs their activity, and sends the records to ReportAgent. You can read the report or question a simulated person. The sequence is visible in a Vue interface, which is easier to follow than agent logs. Chinese is the default interface language, with English UI files and an English README.
The 128-file checkout still contains several systems. OASIS supplies the multi-agent environment, an LLM creates the ontology and people, and Zep stores graph and memory data. That packaging is MiroFish's appeal: a user supplies material and a question instead of writing each simulation stage. Its official FAQ states the necessary limit. This combination does not establish calibrated opinion drift, causal validity, or prediction confidence.
Two cloud credentials sit inside the self-hosted application
A working run needs 2 cloud credentials: an OpenAI-compatible LLM endpoint and Zep Cloud. The static demo linked from the README cannot process new uploads. The FAQ describes it as a fixed presentation of the interface. Source deployment also calls for Node.js 18+, Python 3.11 or 3.12, and uv. Docker removes local packaging work, yet it still reads API credentials from .env.
Our 9.1 MB checkout makes a small first impression, but the runtime crosses a browser app, a Python backend, a model provider, and a hosted graph service. The phrase "OpenAI-compatible" does not ensure that every endpoint handles JSON mode, context limits, or request fields in the way MiroFish expects. Current main officially supports Zep Cloud rather than a local Zep URL, so this is not an offline simulation stack.
What happened when we ran it
Our sandbox installed 31 npm packages in 10 seconds and used 14 MB on disk. The build then failed with exit code 127 after 12 seconds. The root command changed into frontend, invoked its build, and reached vite build. The next line was sh: 1: vite: not found. That log shows the missing executable at build time. It does not show why the executable was unavailable.
There was no test script or target, so we skipped tests. The commit contained a tests directory, two CI workflow files, a Dockerfile, and a Compose file, but none of those turns an absent test target into a result. npm audit reported 0 known vulnerabilities among the 31 packages our run installed. These findings cover repository mechanics. We did not run a simulation or measure forecast quality, model cost, latency, or token use.
Repeated input can produce a different simulated crowd
Issue 751 reports abstention rates of 9.5% and 60.0% from two runs using the same input and interview prompt. The reporter traced part of the variation to temperatures used while creating the ontology, profiles, and simulation settings. Variation helps a writer explore several story paths. It breaks a controlled comparison when the group receiving each treatment changes before the experiment begins.
Issue 759 goes further. With the relevant cohort temperatures set to zero, two consecutive builds returned 27 and 26 entities, with 24 shared. Non-person items were also promoted into personas. Those are issue-reporter results, not measurements from our 3-CPU sandbox, but they concern the product's central promise. Preserve inputs and settings, run the scenario more than once, and report disagreement instead of selecting the most convincing result.
Refreshing Step 3 can delete the run you meant to inspect
Open issue 757 says the destructive path affects v0.1.2 and current main: mounting Step 3 starts the simulation with force: true, and the backend cleanup removes state, action logs, and the Twitter and Reddit databases. The FAQ says MiroFish lacks a general checkpoint and resume protocol. A tab refresh is a normal user action, so this is more serious than a hidden command-line edge case.
That risk lands after the 14 MB installation footprint, when costly work has begun. The README advises trying fewer than 40 rounds because model consumption can be high, while the FAQ says total cost varies with material, entities, agents, rounds, and report calls. Start with a small seed, finish the entire path once, and back up backend/uploads before spending on a longer run.
The default server is meant for a trusted network
The FAQ says current main has no complete user, tenant, authorization, or ownership layer. It also warns against exposing backend port 5001 directly to the internet. A personal experiment behind a private route is one thing. Turning MiroFish into a customer-facing service means adding authentication, tenant isolation, rate limits, secret handling, audit records, and path checks around code that was not shipped as a public SaaS boundary.
A clean npm audit does not answer those application questions. Our scan found 0 known package vulnerabilities and two CI workflow files, useful signals within a narrow scope. They say nothing about who can start another user's simulation or retrieve its files. The AGPL-3.0 license adds a separate deployment decision: anyone modifying the program for network users should review the license obligations with their own counsel.
The code moved after v0.1.2, while major limits remain open
GitHub showed 75,480 stars on October 1, 2026. The repository's last push was September 16, and issue 829 was opened September 29 with a report about a Zep graph operation. Search results contained 57 open issues and 93 open pull requests, rather than 150 bugs. That is an active project and an unusually large review queue. The latest tagged release is still v0.1.2 from March 7.
MiroFish earns a trial when the job is to generate hypotheses or expose reactions you had not considered. The 51,770 source lines package this workflow, but they cannot make a synthetic population representative or its report predictive. Treat each output as a prompt for investigation. If a decision needs repeatable evidence, use a model with explicit rules and validation, or check MiroFish's scenario against observed data before acting.