Environment Variables for Deploying MiroFish in Production: Required and Optional Configuration

To deploy MiroFish in production, you must define LLM_API_KEY and ZEP_API_KEY in your environment; all other variables are optional but strongly recommended for security and performance tuning.

MiroFish is an open-source simulation framework that orchestrates LLM agents and persistent memory graphs. When deploying to production, the application loads configuration from backend/app/config.py, which enforces strict validation of critical secrets before the Flask server starts. Understanding which environment variables are mandatory versus optional ensures your deployment succeeds without runtime errors.

Required Environment Variables

MiroFish will abort startup if these two variables are missing. The Config.validate() method in backend/app/config.py (lines 70-73) explicitly checks for their presence and raises an error if either is undefined.

LLM_API_KEY

The LLM_API_KEY authenticates requests to your Large Language Model provider (e.g., OpenAI, Alibaba DashScope). This key is consumed by the simulation agents and report generation tools.

# backend/app/config.py (line 31)

LLM_API_KEY = os.environ.get('LLM_API_KEY')

Without this variable, the application cannot initialize the LLM client, causing immediate startup failure.

ZEP_API_KEY

The ZEP_API_KEY connects to the Zep memory-graph service, which persists simulation state and agent memory across sessions. MiroFish relies on Zep for long-term context retention.

# backend/app/config.py (line 32)

ZEP_API_KEY = os.environ.get('ZEP_API_KEY')

If missing, the Config.validate() method returns a configuration error, preventing the Flask application from launching.

Optional but Recommended Variables

While MiroFish provides defaults for these settings, overriding them in production is strongly advised for security, performance, and customization.

Security and Debug Settings

Variable	Default	Production Recommendation
SECRET_KEY	mirofish-secret-key	Generate a cryptographically secure random string to secure Flask sessions and CSRF tokens.
FLASK_DEBUG	True	Set to False to disable debug mode and prevent stack trace exposure.

LLM Provider Configuration

You can redirect MiroFish to alternative LLM endpoints by setting these variables:

• LLM_BASE_URL: Defaults to https://api.openai.com/v1. Override to use providers like Alibaba DashScope (https://dashscope.aliyuncs.com/compatible-mode/v1).
• LLM_MODEL_NAME: Defaults to gpt-4o-mini. Change to match your provider's model (e.g., qwen-plus).

These values are loaded in backend/app/config.py using os.environ.get() with default fallbacks.

Simulation Tuning Parameters

Control agent behavior and resource usage with these optional variables:

• OASIS_DEFAULT_MAX_ROUNDS: Maximum simulation rounds (default: 10).
• REPORT_AGENT_MAX_TOOL_CALLS: Tool call limit per report (default: 5).
• REPORT_AGENT_MAX_REFLECTION_ROUNDS: Reflection loop limit (default: 2).
• REPORT_AGENT_TEMPERATURE: LLM temperature for reporting (default: 0.5).

Accelerated LLM Configuration (Optional)

For high-throughput deployments, MiroFish supports an optional "boost" LLM configuration:

• LLM_BOOST_API_KEY
• LLM_BOOST_BASE_URL
• LLM_BOOST_MODEL_NAME

These are only required if you enable the boost feature, as shown in the .env.example file (lines 14-16).

Configuration Loading and Validation

MiroFish uses python-dotenv to load environment variables from a .env file located at the project root, falling back to system environment variables if the file is absent.

# backend/app/config.py (excerpt)

from dotenv import load_dotenv
import os

project_root_env = os.path.join(os.path.dirname(__file__), '../../.env')
if os.path.exists(project_root_env):
    load_dotenv(project_root_env, override=True)
else:
    load_dotenv(override=True)

class Config:
    LLM_API_KEY = os.environ.get('LLM_API_KEY')
    ZEP_API_KEY = os.environ.get('ZEP_API_KEY')
    # ... additional settings ...

    
    @classmethod
    def validate(cls):
        errors = []
        if not cls.LLM_API_KEY:
            errors.append("LLM_API_KEY is required")
        if not cls.ZEP_API_KEY:
            errors.append("ZEP_API_KEY is required")
        return errors

Before the Flask application initializes, the startup sequence calls Config.validate() and aborts if errors are returned, ensuring no deployment proceeds without the necessary API credentials.

Docker Deployment Example

When deploying via Docker Compose, inject environment variables using a host-side .env file or orchestration secrets:

# docker-compose.yml (excerpt)

services:
  mirofish:
    image: ghcr.io/666ghj/mirofish:latest
    environment:
      - LLM_API_KEY=${LLM_API_KEY}
      - ZEP_API_KEY=${ZEP_API_KEY}
      - SECRET_KEY=${SECRET_KEY}
      - FLASK_DEBUG=False
      - LLM_BASE_URL=${LLM_BASE_URL:-https://api.openai.com/v1}
      - LLM_MODEL_NAME=${LLM_MODEL_NAME:-gpt-4o-mini}
    ports:
      - "8000:8000"
    restart: unless-stopped

Store sensitive values in a .env file excluded from version control, or use Docker secrets/Kubernetes secrets for production-grade security.

Summary

• Mandatory variables: LLM_API_KEY and ZEP_API_KEY are enforced by Config.validate() in backend/app/config.py and must be defined for the application to start.
• Security essentials: Override SECRET_KEY with a cryptographically secure value and set FLASK_DEBUG=False in production.
• Provider flexibility: Use LLM_BASE_URL and LLM_MODEL_NAME to switch between OpenAI, Alibaba DashScope, or other compatible endpoints.
• Configuration source: Variables are loaded from a .env file at the project root or from the host environment via python-dotenv in backend/app/config.py.

Frequently Asked Questions

What happens if I don't set LLM_API_KEY or ZEP_API_KEY in production?

The application will abort immediately during startup. The Config.validate() method in backend/app/config.py (lines 70-73) checks for these variables and returns an error list if either is missing, preventing the Flask server from launching.

Can I use environment variables instead of a .env file?

Yes. While MiroFish attempts to load a .env file from the project root in backend/app/config.py, it falls back to system environment variables if the file is absent. In containerized deployments, you can inject variables directly via Docker or Kubernetes without mounting a .env file.

How do I configure MiroFish to use a different LLM provider?

Set the LLM_BASE_URL and LLM_MODEL_NAME environment variables. For example, to use Alibaba DashScope instead of OpenAI, set LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 and LLM_MODEL_NAME=qwen-plus. These values are read in backend/app/config.py using os.environ.get() with sensible defaults for OpenAI.

Is FLASK_DEBUG required for production deployments?

No, FLASK_DEBUG should be explicitly set to False in production. The default value is True, which exposes detailed stack traces and enables auto-reloading—both security risks and performance liabilities in production environments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}