Self-hosted vs hosted MiroFish: what running it yourself actually takes

What MiroFish is

MiroFish is an open-source multi-agent simulation engine, published by 666ghj on GitHub under the AGPL-3.0 licence. You give it seed material, such as a report, a policy draft or a story, and describe what you want to explore. It builds a knowledge graph, generates agents with their own personas and memory, runs them on a simulated social platform powered by OASIS from CAMEL-AI, and writes a report. Its README lists five steps: graph building, environment setup, simulation, report generation and deep interaction, where you can chat with any agent and with the report agent.

What self-hosted actually means

Self-hosting means running the MiroFish code on your own computer or server. It does not, by itself, mean running offline: the upstream version calls a language model through an API in OpenAI SDK format and uses Zep Cloud for graph memory, so your material goes to the providers you configure. A fully local setup is possible with MiroFish-Offline, a community fork that swaps both services for local ones and documents much higher hardware needs.

What you need, as documented upstream

Node.js 18 or later. Python 3.11 or 3.12 (the backend requires >=3.11 and <3.13). uv, the Python package manager. Three settings for the language model: LLM_API_KEY, LLM_BASE_URL and LLM_MODEL_NAME, for any API in OpenAI SDK format; the README recommends the qwen-plus model through Alibaba's Bailian platform. ZEP_API_KEY for Zep Cloud graph memory; the README says the free monthly quota is enough for simple usage. Optionally LLM_BOOST_API_KEY, LLM_BOOST_BASE_URL and LLM_BOOST_MODEL_NAME for a second, faster model; if you do not use it, leave those keys out of .env. The frontend listens on port 3000 and the backend API on port 5001. The README warns that consumption is high and suggests trying simulations with fewer than 40 rounds first. It does not state CPU, memory or disk requirements.

Installing from source

This is the route upstream recommends. Copy .env.example to .env and fill in the keys, run npm run setup:all to install the Node dependencies (root and frontend) and the Python dependencies with uv, then run npm run dev to start both services and open http://localhost:3000. You can also install in two steps (npm run setup, then npm run setup:backend) and start the services separately (npm run backend, npm run frontend).

Installing with Docker Compose

Copy .env.example to .env, then run docker compose up -d. The compose file pulls ghcr.io/666ghj/mirofish:latest, reads .env, maps ports 3000 and 5001, and keeps uploads in ./backend/uploads on the host. The image's Dockerfile starts both services with npm run dev, which it describes as development mode.

The fully local fork: MiroFish-Offline

MiroFish-Offline is a separate community project. It replaces Zep Cloud with Neo4j Community Edition 5.15 and the hosted model API with Ollama (qwen2.5 and nomic-embed-text), so nothing leaves your hardware. Its README documents Docker and Docker Compose, or Python 3.11+, Node.js 18+, Neo4j 5.15+ and Ollama; a minimum of 16 GB RAM, 10 GB VRAM for the 14b model, 20 GB disk and 4 CPU cores; and a recommended 32 GB RAM, 24 GB VRAM for the 32b model, 50 GB disk and 8 or more cores. It says CPU-only mode works but is significantly slower. The repository was last updated in March 2026.

One-click templates

Hostinger offers a one-click Docker template for MiroFish on its VPS plans. Zeabur's deploy template asks for LLM_API_KEY, LLM_BASE_URL, LLM_MODEL_NAME and ZEP_API_KEY, with the LLM_BOOST values optional, and repeats the advice to start with fewer than 40 rounds. Our note: a template sets up the server; the model and memory accounts are still yours to create and pay for.

Running it over time (our commentary)

This is not upstream documentation, but it is what running MiroFish yourself involves in practice: pulling new versions and re-running setup when dependencies change; keeping .env and its keys private and watching usage at your model provider and at Zep; backing up backend/uploads if you keep your results; and, if you run it on a server, controlling who can reach it.

Hosted MiroFish: what changes

MiroFish.co.uk is an independent hosted service built on the open-source MiroFish project. It runs a modified version of the engine for one job: stress-testing a decision with a synthetic audience. There is nothing to install and there are no model or Zep keys to manage; the service runs the language model and the graph memory (its Data and AI page names Anthropic and Zep Cloud). It packages the engine as a study rather than exposing each upstream step: you give it the material and describe the audience, a Quick Study runs five discussion rounds and a Standard Study ten, and the report gives a decision-readiness verdict, key findings, segment reactions, risks, what to change and verbatim quotations checked against the discussion. You do not choose the model or tune the engine yourself. Pricing is per study or by monthly plan, and the first Quick Study is free. The complete source of the running service is published at mirofish.co.uk/source.

Who should self-host

Self-host if you want to work with the upstream workflow directly, including the graph and the agent chat; if you want to choose and control the model provider and the memory service; if you are comfortable with Node.js, Python, environment variables and a server; or if your material has to stay on your own infrastructure and you have the hardware the fully local fork documents.

Who should use a hosted service

Use a hosted service if you want to start without installing the stack or opening model and Zep accounts, if your question is a decision to stress-test (a pricing change, a launch, a campaign or a statement), and if you want a structured report you can share rather than a system to operate. Neither route is right for everyone.

Can I run MiroFish locally?

Yes. The upstream code runs on your own machine with Node.js 18+, Python 3.11 or 3.12 and uv, but it still calls a hosted language model and Zep Cloud. For a fully local setup, the community fork MiroFish-Offline uses Neo4j and Ollama instead, with much higher hardware needs.

What do I need to install MiroFish?

Node.js 18 or later, Python 3.11 or 3.12 and uv, or Docker; plus an API key for a language model in OpenAI SDK format and a Zep Cloud API key.

Does MiroFish need an API key?

The upstream version needs LLM_API_KEY, with LLM_BASE_URL and LLM_MODEL_NAME, for the language model, and ZEP_API_KEY for graph memory. MiroFish-Offline replaces both with local services.

Does MiroFish need Zep?

The upstream version uses Zep Cloud for graph memory, and its README says the free monthly quota is enough for simple usage. MiroFish-Offline uses Neo4j instead.

Can I use MiroFish without installing it?

Yes, through a hosted service. MiroFish.co.uk is one: an independent hosted service built on the open-source MiroFish project.

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.

Sources

• MiroFish README (upstream repository, commit 39d8491)
• MiroFish .env.example (upstream)
• MiroFish docker-compose.yml (upstream)
• MiroFish Dockerfile (upstream)
• MiroFish package.json (upstream)
• MiroFish backend/pyproject.toml (upstream)
• MiroFish-Offline README (community fork, commit 313fe64)
• Hostinger: MiroFish VPS Docker template
• Zeabur: MiroFish deploy template
• Zep: pricing