Deploy and Host MiroFish on Railway

MiroFish is an open-source AI prediction engine powered by multi-agent simulation. By combining OpenAI-compatible large language models with long-term agent memory, it creates an interactive digital world where autonomous AI agents simulate future scenarios, analyze complex events, and generate detailed prediction reports from real-world seed materials.

About Hosting MiroFish

Railway makes deploying MiroFish simple by running the official Docker image while managing infrastructure, networking, HTTPS, and deployments automatically. MiroFish consists of a frontend and backend that work together to process uploaded documents, generate agent simulations, and present interactive prediction results through a web interface. The application requires API credentials for an OpenAI-compatible LLM provider and Zep Cloud for long-term memory. A Railway Volume mounted at /app/backend/uploads is required to persist uploaded files and datasets across deployments. Railway also simplifies environment variable management, logging, and scaling, allowing you to focus on running AI simulations instead of maintaining infrastructure.

Common Use Cases

Simulate public opinion, financial markets, and policy outcomes using AI agents.
Build interactive digital worlds for research, storytelling, and scenario planning.
Generate prediction reports from uploaded documents, reports, news articles, or datasets.

Dependencies for MiroFish Hosting

Dependency	Required	Purpose
OpenAI-compatible LLM API	Yes	Powers agent reasoning and simulations.
Zep Cloud API	Yes	Provides long-term memory and knowledge graph capabilities.
Railway Volume	Yes	Stores uploaded documents and simulation input files.

Deployment Dependencies

Resource	Link
GitHub Repository	https://github.com/666ghj/MiroFish
Docker Image	https://github.com/666ghj/MiroFish/pkgs/container/mirofish
Zep Cloud	https://app.getzep.com
DashScope (Recommended)	https://bailian.console.aliyun.com

Implementation Details

Docker

This template deploys the official Docker image:

ghcr.io/666ghj/mirofish:v0.1.2

Railway pulls the prebuilt image directly, so no build configuration is required.

Public Networking

Setting	Value
Proxy Type	HTTP Proxy
Target Port	3000

Environment Variables

Configure the following Railway Variables before deployment.

Variable	Required	Description
`LLM_API_KEY`	Yes	API key for your OpenAI-compatible LLM provider.
`ZEP_API_KEY`	Yes	API key for Zep Cloud.
`LLM_BASE_URL`	Yes	Base URL of your LLM provider.
`LLM_MODEL_NAME`	Yes	Primary LLM model.
`LLM_BOOST_API_KEY`	No	Optional secondary LLM API key.
`LLM_BOOST_BASE_URL`	No	Optional secondary LLM endpoint.
`LLM_BOOST_MODEL_NAME`	No	Optional secondary LLM model.
`OASIS_DEFAULT_MAX_ROUNDS`	No	Maximum simulation rounds. Default: 10.
`FLASK_DEBUG`	No	Enable or disable Flask debug mode.
`PORT`	Yes	Internal application port.

Raw Editor example:

LLM_API_KEY=your_llm_api_key_here

ZEP_API_KEY=your_zep_api_key_here

LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus

LLM_BOOST_API_KEY=
LLM_BOOST_BASE_URL=
LLM_BOOST_MODEL_NAME=

OASIS_DEFAULT_MAX_ROUNDS=10

FLASK_DEBUG=false

PORT=3000

Getting API Keys

OpenAI-Compatible LLM

MiroFish works with any provider exposing an OpenAI-compatible API.

Configure:

LLM_API_KEY
LLM_BASE_URL
LLM_MODEL_NAME

The recommended provider is Alibaba DashScope using the qwen-plus model.

Zep Cloud

Create a free Zep Cloud account:

https://app.getzep.com

Generate an API Key and configure:

ZEP_API_KEY=your_zep_api_key

Persistent Storage

A Railway Volume is required.

Open your Railway service.
Go to Settings → Volumes.
Click Add Volume.
Mount the volume at:

/app/backend/uploads

The mounted volume stores uploaded documents, datasets, reports, and other seed materials used by simulations, ensuring they persist across redeployments and service restarts.

Database

No database is required.

MiroFish uses Zep Cloud for agent memory and knowledge graph storage.

Build & Start

This template uses the official Docker image.

Configure the following Start Command in Railway:

sh -c 'sed -i "s/server: {/server: { allowedHosts: true,/" /app/frontend/vite.config.js && sed -i "/baseURL:/s#baseURL:.*#baseURL: \"\",#" /app/frontend/src/api/index.js && npm run dev'

Accessing the Application

After deployment:

Open your Railway service.
Navigate to Settings → Networking.
Click Generate Domain.
Open the generated Railway URL.

The MiroFish dashboard will load in your browser.

Using MiroFish

After opening the application:

Upload one or more seed documents, datasets, reports, or news articles.
Describe your prediction objective using natural language.
Configure simulation settings if needed.
Start the simulation.
Wait while MiroFish builds its digital world and performs multi-agent reasoning.
Review the generated prediction report.
Continue interacting with the generated agents and simulation environment for deeper analysis.

Why Deploy MiroFish on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying MiroFish on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.