MoonMind

# MoonMind

**MoonMind is a self-hosted AI orchestration hub for chat, memory, and automation. It combines multi-provider LLM routing, retrieval-augmented generation, and a Celery-based orchestrator that can run skills-based workflows across your code and infrastructure.**

## What is MoonMind?

MoonMind is an AI control plane you run yourself. It gives you:

- **Model routing:** An OpenAI-compatible `/v1/chat/completions` and `/v1/models` API that fans out to Google Gemini, OpenAI, Anthropic, Ollama, and VLLM without redeploying. Models are discovered from all enabled providers and cached for fast listing and routing.
- **Memory and retrieval:** A RAG pipeline powered by LlamaIndex, Qdrant, and configurable embeddings, with loaders for Confluence, GitHub, Google Drive, and more so agents and UIs can ground their reasoning in your real documents.
- **Automation and orchestration:** A Celery-based automation layer and mm-orchestrator service that run skills-based workflows, execute task chains over RabbitMQ + PostgreSQL, emit StatsD metrics, and write artifacts under `var/artifacts/spec_workflows/<run_id>`.

MoonMind exposes all of this through:

- **OpenAI-compatible APIs** for drop-in use with tools and UIs like Open-WebUI.
- **Model Context Protocol (MCP)** so external agents can treat MoonMind as a standardized model and tools backend.
- **Apps and manifests** that describe higher-level workflows declaratively and can be invoked from CLIs, agents, or CI.

## Quick Start with Codex

**Prerequisites:**

*   **Docker:** Ensure Docker is installed and running on your system. You can download it from [Docker's official website](https://www.docker.com/products/docker-desktop).
*   **Docker Compose:** Docker Compose is included with most Docker Desktop installations. If not, follow the [official installation guide](https://docs.docker.com/compose/install/).
*   **Environment File:** Create a `.env` file in the root of the project by copying the `.env-template` file:
    ```bash
    cp .env-template .env
    ```
    For a fast Codex launch:
    - `CODEX_ENV=prod`
    - `CODEX_MODEL=gpt-5.3-codex`
    - `GITHUB_TOKEN=<github_pat_with_repo_access>`

**Running MoonMind:**

1.  **Open a terminal** in the root directory of the MoonMind project.
2.  **Authenticate worker OAuth volumes (one-time per environment)** before running queue/Celery automation:
    ```bash
    ./tools/auth-codex-volume.sh
    ./tools/auth-claude-volume.sh
    ```
    This persists Codex auth in `codex_auth_volume` and Claude auth in `claude_auth_volume` so runtime pre-flight checks pass.
    By default (`AUTH_PROVIDER=disabled`) the `codex-worker` service auto-creates and persists a worker token on first start. If auth is enabled, set either `MOONMIND_WORKER_TOKEN` (recommended) or `MOONMIND_API_TOKEN` in `.env`. If required runtime auth is missing, the worker stays idle and retries until runtime-specific preflight checks pass.
3.  **Start the services** using the following command:
    ```bash
    docker-compose up -d
    ```
    The `-d` flag runs the containers in detached mode, meaning they will run in the background.
    To force-refresh remote images first, run:
    ```bash
    docker-compose pull && docker-compose up -d
    ```
    To build locally instead of pulling images, run:
    ```bash
    docker-compose up -d --build
    ```

4.  **Accessing the UI:** Once the services are up and running (this might take a few minutes the first time as images are downloaded and built), you can access the Open-WebUI by navigating to `http://localhost:8080` in your web browser.

5.  **Manage API Keys:** When `AUTH_PROVIDER` is left as `disabled` (the default for local setups), any provider keys you place in `.env` are copied to the default user profile on startup. Visit `http://localhost:8080/settings` to view or change these values.
6.  **Initializing the Vector Database (Optional but Recommended):**
    If you want to load initial data into the Qdrant vector database (e.g., from local files or other sources configured in `config.toml`), you can trigger the initialization process.
    Set the `INIT_DATABASE` variable in your `.env` file to `true`:
    ```env
    INIT_DATABASE=true
    ```
    Then, restart your Docker Compose setup:
    ```bash
    docker-compose down && docker-compose up -d
    ```
    The `init-db` service will run, attempt to load data, and then exit. You can check its logs using `docker-compose logs init-db`. After initialization, you may want to set `INIT_DATABASE=false` again to prevent re-initialization on subsequent restarts.

**Stopping MoonMind:**

To stop all running services, execute the following command in the project root:
```bash
docker-compose down
```

This setup uses the main `docker-compose.yaml` file, which is configured for a production-like deployment with the Qdrant vector store. For development purposes, or if you need to use a different configuration, you might use other specific compose files (for exampl

... (truncated)