Who MiroFish is for#
Policy analysts modeling public response before deployment
A policy team uploads a draft proposal and recent news coverage as seed data, runs a simulation of agents representing different demographic segments, and receives a prediction report on likely public reactions. Dynamic variable injection lets them test how modifying policy language shifts sentiment across segments.
Skip if:
You need legally defensible impact assessments. Simulation outputs are probabilistic models, not certified forecasts. Regulatory or legal contexts require validated actuarial or econometric methods.
Researchers studying information diffusion in social networks
Academic researchers in sociology, political science, or computational social science can model how information spreads through a population with varied prior beliefs. The AGPL-3.0 license and self-hosting path keep institutional data on university infrastructure without routing it through a commercial platform.
Skip if:
Your institution requires a validated simulation framework with published peer-review validation records. MiroFish is a research-grade engine but does not yet carry formal scientific certification.
Financial analysts exploring market sentiment scenarios
Financial teams can seed MiroFish with macroeconomic signals, earnings releases, or geopolitical news to simulate how market participants might react. The GitHub topics list financial-forecasting explicitly, and a demo video covers this use case alongside public opinion analysis.
Skip if:
You need production-grade quantitative trading signals or a latency-optimized data feed. MiroFish is a scenario exploration tool, not a backtesting framework or real-time market data system.
Data scientists building swarm intelligence prediction systems
Developers exploring multi-agent architectures can use MiroFish as a foundation for domain-specific prediction systems. The Python backend is extensible, the LLM layer is provider-agnostic, and the underlying simulation engine is the open source OASIS framework from CAMEL-AI.
Skip if:
Your use case is simple time-series forecasting or regression prediction on tabular data. MiroFish is designed for complex social simulation; lighter statistical methods carry much lower infrastructure overhead for straightforward forecasting tasks.
The problem it solves#
Predicting how complex social systems evolve is a problem that statistical models handle poorly. A regression model can extrapolate a trend, but it cannot capture the emergent behavior that arises when thousands of individuals with different opinions, memories, and social connections interact. Public opinion shifts, financial market sentiment, and the trajectory of a policy controversy are all shaped by these non-linear dynamics.
The practical consequence is that decision-makers in government, finance, and public relations rely on tools that are either too simple (trend extrapolation) or too expensive (enterprise simulation platforms with significant license costs). There has been no affordable, self-hosted way to run agent-based social simulations at meaningful scale without building the infrastructure from scratch.
How it solves it#
Multi-agent simulation with independent AI agents
Spawns thousands of independent AI agents, each with individual personalities, behavioral logic, and long-term memory. Each agent responds to inputs from other agents and from injected variables, producing emergent collective behavior that single-model approaches cannot replicate. Agent count and simulation rounds are configurable per run.
Knowledge graph construction via GraphRAG
Automatically extracts a structured knowledge graph from your seed materials. Entity relationships are identified and used to build the social and informational substrate that agents navigate during simulation. Supported seed types include news articles, data analysis reports, policy documents, and narrative text.
Dynamic variable injection during simulation
Lets you intervene in a running simulation from a system-level view to test what-if scenarios. You can introduce breaking news, policy changes, or market shocks mid-simulation and observe how agent behavior shifts in response. The README calls this the God's-eye perspective.
ReportAgent with post-simulation deep interaction
After simulation completes, a dedicated ReportAgent generates a structured prediction report. You can also chat directly with any agent in the simulated world to explore specific perspectives or probe individual reasoning. The README describes this stage as deep interaction with the post-simulation environment.
OpenAI-compatible LLM layer
Works with any LLM API that speaks the OpenAI SDK format, including locally hosted models. You configure the base URL, API key, and model name in a .env file. The README recommends Alibaba's Qwen-plus model via the Bailian platform but does not require it.
Docker and source deployment paths
Supports both Docker deployment (docker compose up -d) and source code installation. The source path uses Node.js 18+ and Python 3.11-3.12 with one-command dependency installation via npm run setup:all. Frontend runs on port 3000, backend API on port 5001.
Strengths and trade-offs#
Strengths
- 73,000+ GitHub stars with sustained active development73,153 stars and 11,290 forks indicate genuine community adoption. The repo was created in November 2025 and had commits as recently as September 2026, showing sustained momentum despite being under a year old. 128 open issues is low relative to that activity level.
- Provider-agnostic LLM layer with no vendor lock-inMiroFish works with any LLM API that speaks the OpenAI SDK format, including self-hosted models via Ollama or similar. You configure the endpoint, key, and model name in the .env file. Teams with data-sovereignty requirements can route all inference through an on-premises model.
- Covers financial, social, political, and creative prediction domainsThe GitHub topics explicitly include financial-forecasting, public-opinion-analysis, and social-prediction. Demo videos cover a university campus event simulation and a novel ending prediction from 80 chapters of source text. The same engine applies to serious policy research and exploratory creative scenarios.
- Self-hosted cost model bounded by token consumptionRunning MiroFish on your own server limits ongoing costs to LLM API token consumption. There are no per-seat fees and no managed-service subscription. For internal research or analytics teams, this makes cost predictable and scales with usage rather than team size.
Trade-offs
- -High token consumption per simulation runThe README warns that simulations consume LLM tokens at a high rate and explicitly recommends starting with fewer than 40 simulation rounds. Larger simulations with many agents and rounds can become expensive depending on the LLM provider and pricing tier. Cost scales with simulation complexity, not with user count.
- -Requires external Zep Cloud for agent memoryAgent long-term memory depends on Zep Cloud, a third-party managed service. The README notes the free monthly quota is sufficient for simple usage, but production-grade simulations with many agents may exceed it. There is no documented path to replace Zep Cloud with a fully self-hosted memory backend.
- -Moderate self-hosting complexitySource deployment requires Node.js 18+, Python 3.11-3.12 (not 3.13+), the uv package manager, and configuration of at least two API keys. It is not a one-command install and assumes familiarity with both Python and Node environments. Docker simplifies startup but still requires a configured .env file.
- -AGPL-3.0 copyleft applies to hosted service deploymentsAGPL-3.0 allows running MiroFish for internal use, including commercial-internal use. If you modify MiroFish and offer it as a hosted service to external users, you must release those source modifications. Teams planning to build a managed prediction product on MiroFish should evaluate whether a commercial arrangement with the maintainers is needed.
MiroFish vs alternatives#
MiroFish vs AnyLogic
AnyLogic is the leading commercial agent-based simulation platform, used by universities, governments, and enterprises for logistics, supply chain, healthcare, and social modeling. MiroFish targets an overlapping but distinct use case: AI-driven social prediction using LLM-powered agents rather than rule-based behavioral models.
| Feature | MiroFish | AnyLogic |
|---|---|---|
| License | AGPL-3.0 | Proprietary paid license |
| Self-hosting | Yes | No (desktop app with optional cloud output) |
| Agent model | LLM-powered, OpenAI-compatible | Rule-based discrete-event simulation |
| Primary strength | Social, political, financial prediction from text seeds | Logistics, supply chain, healthcare, pedestrian simulation |
| Input type | Unstructured text (news, policy, reports) | Structured mathematical models and diagrams |
MiroFish is the better choice when your prediction problem involves unstructured text inputs, emergent social dynamics, and a need to keep data on-premises. The LLM-powered agent layer means agents reason from natural language seed data with no programming beyond configuration.
AnyLogic is still the better fit when your simulation requires precise, reproducible mathematical models with extensive validation history, or when you are building logistics and supply chain models where AnyLogic's domain-specific libraries (Road Traffic, Rail, Pedestrian, Fluid) are mature and tested. AnyLogic's graphical IDE also lowers the barrier for users who prefer not to edit configuration files.
MiroFish vs Enterprise ML Prediction Platforms
Platforms like DataRobot and H2O.ai automate traditional machine learning: they take tabular data, train models, and produce forecasts. They do not model agent behavior or social emergence. MiroFish takes a different approach better suited to complex social prediction, but it requires more compute and LLM API spend per run.
| Feature | MiroFish | DataRobot / H2O.ai |
|---|---|---|
| License | AGPL-3.0 | Proprietary enterprise SaaS |
| Self-hosting | Yes | Limited enterprise on-premises tier |
| Prediction method | Multi-agent social simulation | AutoML on tabular data |
| Best input type | Unstructured text, news, reports | Structured tabular datasets |
| Cost model | LLM API tokens plus server cost | Per-seat or usage-based enterprise pricing |
For teams with tabular historical data who need explainable forecasts with minimal setup, DataRobot or AutoML tools remain the practical choice. MiroFish is not a tabular forecasting replacement. Its value is in scenarios where emergent social behavior and natural-language seeds are the inputs and a precise tabular dataset does not exist.
Quick start#
Self-hosting with Docker reads from a configured .env file and maps ports 3000 and 5001.
```bash
cp .env.example .env
docker compose up -d
```What it's built on#
- Languages
- JavaScriptPython
- Frameworks
- FlaskVue
FAQ#
Is MiroFish free to use?
MiroFish is free to self-host under AGPL-3.0. You will need an LLM API key (any OpenAI-compatible provider works; Alibaba Qwen-plus is recommended) and a Zep Cloud account for agent memory. The Zep Cloud free monthly quota covers basic use. Your primary ongoing cost is LLM token consumption per simulation run, which scales with the number of agents and rounds.
What kinds of predictions can MiroFish make?
MiroFish models social, political, and financial outcomes by simulating agent behavior rather than extrapolating statistical trends. Documented examples include public opinion analysis for a university campus event, financial market sentiment from economic signals, and a creative scenario predicting the lost ending of a classic Chinese novel from 80 chapters of source text. Any domain where group dynamics and social interaction drive outcomes is a candidate.
Can I use my own LLM with MiroFish?
Yes. MiroFish works with any LLM API that speaks the OpenAI SDK format, including locally hosted models via Ollama or similar setups. You configure the base URL, API key, and model name in the .env file. The README recommends starting with a capable model like Qwen-plus because simulations consume tokens at a high rate per run.
How is MiroFish licensed?
AGPL-3.0. You can run it for internal or commercial-internal use and modify the code freely. If you deploy a modified version as a hosted service for external users, AGPL-3.0 requires you to release those source modifications. Teams planning to offer MiroFish as a managed prediction service to others should evaluate whether a commercial license from the maintainers is appropriate.
What are the prerequisites for self-hosting MiroFish?
Source deployment requires Node.js 18+, Python 3.11 or 3.12 (not 3.13+), and the uv Python package manager. You also need an LLM API key (any OpenAI-compatible endpoint) and a Zep Cloud API key for agent memory. Docker deployment reads from a configured .env file and maps port 3000 for the frontend and port 5001 for the backend API.
Similar open-source tools#
FckSignups
Open-source tools that work instantly, no signup required
DeskcommCRM
AI agents for WhatsApp sales, fully audited, no per-user pricing
fmt
Fast, type-safe C++ formatting that replaces printf and iostreams
treg
One token for 2,600+ agent tools across 47 providers
OpenCompany
Self-hosted AI agent canvas for every business function
Comp AI CRM
Open source agentic CRM with a durable research agent