How to Install MiroFish on macOS, Windows & Linux

What You Need Before Starting

MiroFish requires Node.js 18+, Python 3.11 (not 3.13 or 3.14 — PyTorch doesn't have wheels yet), git, and uv (a fast Python package manager). You'll also need an OpenAI API key and a free Zep Cloud account for agent memory. Important: Anthropic's API is not OpenAI-compatible. MiroFish uses the OpenAI SDK format, so you cannot use an Anthropic API key directly. Use OpenAI, or route through OpenRouter if you want Claude models.

Install on macOS

Open Terminal and install the prerequisites with Homebrew. Run brew install python@3.11 and brew install node. Install uv with curl -LsSf https://astral.sh/uv/install.sh | sh — then close and reopen your terminal so uv is in your PATH. Clone the repo with git clone https://github.com/666ghj/MiroFish.git and cd MiroFish. Copy the example environment file with cp .env.example .env, edit it with your OpenAI key and Zep key, then run npm run setup:all to install everything.

Install on Windows (WSL2)

MiroFish doesn't run natively on Windows — you need WSL2. Open PowerShell as Administrator and run wsl --install. After restarting, open Ubuntu and follow the Linux instructions below. Everything runs inside the Ubuntu terminal from this point.

Install on Linux

Install Node.js with the NodeSource installer, Python 3.11, and uv. Clone the MiroFish repo, configure your .env file, and run npm run setup:all. If uv sync fails with a PyTorch error, you're on the wrong Python version — force it with cd backend && uv sync --python 3.11.

The .env Gotcha That Breaks Everything

This is the number one reason people get stuck. MiroFish's frontend reads .env from the project root, but the backend reads it from backend/.env. If you only have the root copy, you'll get 500 errors every time you try to run a simulation. The fix: cp .env backend/.env. Run this every time you change your .env file.

Run Your First Simulation

Start MiroFish with npm run dev. Open http://localhost:3000 in your browser. Create a new simulation, paste a seed document (a news article or policy brief works well), and describe what you want to predict. The simulation takes 1-3 minutes depending on your LLM. If agents start interacting and a report generates, you're fully operational.