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

> Deploy MiroFish in production using essential environment variables like LLM_API_KEY and ZEP_API_KEY. Discover optional but recommended settings for security and performance.

- Repository: [BaiFu/mirofish](https://github.com/666ghj/mirofish)
- Tags: configuration
- Published: 2026-02-23

---

**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`](https://github.com/666ghj/mirofish/blob/main/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`](https://github.com/666ghj/mirofish/blob/main/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.

```python

# 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.

```python

# 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`](https://github.com/666ghj/mirofish/blob/main/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.

```python

# 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:

```yaml

# 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`](https://github.com/666ghj/mirofish/blob/main/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`](https://github.com/666ghj/mirofish/blob/main/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`](https://github.com/666ghj/mirofish/blob/main/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`](https://github.com/666ghj/mirofish/blob/main/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`](https://github.com/666ghj/mirofish/blob/main/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.