> ## Documentation Index
> Fetch the complete documentation index at: https://docs.multimind.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Guide

This guide covers all configuration options available in the MultiMind SDK.

## Environment Variables

### API Keys

```bash theme={null}
# Required for OpenAI models
OPENAI_API_KEY=your_openai_api_key

# Required for Anthropic models (CLAUDE_API_KEY is also accepted)
ANTHROPIC_API_KEY=your_anthropic_api_key

# Required for Mistral AI (hosted) models
MISTRAL_API_KEY=your_mistral_api_key

# Required for Groq models
GROQ_API_KEY=your_groq_api_key

# Required for Gemini models (GOOGLE_API_KEY is also accepted)
GEMINI_API_KEY=your_gemini_api_key

# Required for DeepSeek models
DEEPSEEK_API_KEY=your_deepseek_api_key

# Optional Hugging Face token for gated models. HuggingFaceModel always runs
# locally via transformers; this is only read by multimind.Config and the gateway
HUGGINGFACE_API_KEY=your_huggingface_api_key
```

### Default Settings

```bash theme={null}
# Default model provider for the gateway (default: openai)
DEFAULT_MODEL=openai

# Logging level for the gateway
LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL

# Log level for optional-dependency warnings at import time (default: WARNING)
MULTIMIND_LOG_LEVEL=WARNING

# Path to a YAML config file loaded by multimind.Config
MULTIMIND_CONFIG=config.yaml

# Ollama server URL for OllamaModel / multimind.Config / the serve proxy (default: http://localhost:11434)
OLLAMA_HOST=http://localhost:11434

# Ollama settings read by the gateway API (multimind.core.config)
OLLAMA_API_BASE=http://localhost:11434
OLLAMA_MODEL_NAME=mistral
```

### Compliance Proxy (`multimind serve`)

Every `multimind serve` flag can also be set through an environment variable
(CLI flags win):

```bash theme={null}
MULTIMIND_PROXY_UPSTREAM=openai        # openai, groq, mistral, gemini, deepseek, ollama
MULTIMIND_UPSTREAM_BASE_URL=           # custom OpenAI-compatible upstream URL
MULTIMIND_UPSTREAM_API_KEY=            # explicit upstream key (else provider env var is used)
MULTIMIND_PROXY_STRATEGY=mask          # mask, hash, remove
MULTIMIND_PROXY_BLOCK_ON=ssn,credit_card
MULTIMIND_PROXY_AUDIT_LOG=audit.jsonl
MULTIMIND_PROXY_COSTS_LOG=costs.jsonl
MULTIMIND_PROXY_BUDGET=10.0
MULTIMIND_PROXY_COST_PER_TOKEN=
MULTIMIND_PROXY_SCAN_OUTPUT=true
MULTIMIND_PROXY_HOST=127.0.0.1
MULTIMIND_PROXY_PORT=8400
```

The guardrails file passed with `--config` defaults to `MULTIMIND_DASHBOARD_GUARDRAILS` (see below). See the [Guard Proxy guide](/guard-proxy) for details.

### Governance Dashboard (`multimind dashboard`)

Every `multimind dashboard` flag can also be set through an environment variable
(CLI flags win):

```bash theme={null}
MULTIMIND_DASHBOARD_AUDIT_LOG=audit.jsonl
MULTIMIND_DASHBOARD_COSTS_LOG=costs.jsonl
MULTIMIND_DASHBOARD_PROJECT=.
MULTIMIND_DASHBOARD_GUARDRAILS=guardrails.json
MULTIMIND_DASHBOARD_HOST=127.0.0.1
MULTIMIND_DASHBOARD_PORT=8501
MULTIMIND_DASHBOARD_API_KEY=          # when set, PUT /api/guardrails requires this X-API-Key header
MULTIMIND_API_BASE=                   # API base URL the dashboard page calls (e.g. http://localhost:8000)
MULTIMIND_API_KEY=                    # X-API-Key the dashboard page sends to that API
```

`multimind backend` reads `MULTIMIND_BACKEND_HOST` and `MULTIMIND_BACKEND_PORT` (default `127.0.0.1:8080`).

### API Servers and Misc

```bash theme={null}
# Comma-separated API keys; enables X-API-Key auth on the REST APIs when set
API_KEYS=key1,key2

# Enables JWT bearer auth on the RAG gateway when set
JWT_SECRET=your_jwt_secret
JWT_USERS_JSON='{"user": "password_hash"}'

# CORS is off unless this is set (comma-separated origins). Read by the
# backend, the gateway, the RAG API, and the guard proxy (multimind serve).
# The legacy name MULTIMIND_ALLOWED_ORIGINS is also accepted.
MULTIMIND_CORS_ORIGINS=https://app.example.com

# Audit log path for the MCP server
MULTIMIND_AUDIT_LOG=audit_log.jsonl

# Opt-in warnings for missing optional backends / legacy compliance imports
MULTIMIND_SHOW_BACKEND_WARNINGS=false
MULTIMIND_SHOW_LEGACY_WARNINGS=false
```

## Model Configuration

Generation parameters such as `temperature` and `max_tokens` are passed per
call (e.g. to `generate()`), not to the model constructor.

### OpenAI Models

```python theme={null}
from multimind import OpenAIModel

model = OpenAIModel(
    model_name="gpt-4o-mini",
    api_key=None,  # falls back to OPENAI_API_KEY
    base_url=None,  # custom OpenAI-compatible endpoint
    cost_per_token=None,  # override for cost tracking
)
```

### Claude Models

```python theme={null}
from multimind import ClaudeModel

model = ClaudeModel(
    model_name="claude-3-opus-20240229",
    api_key=None,  # falls back to ANTHROPIC_API_KEY or CLAUDE_API_KEY
)
```

### Mistral Models

`MistralModel` runs Mistral models locally through Ollama; `MistralAIModel`
uses the hosted Mistral AI (La Plateforme) API via `MISTRAL_API_KEY`.

```python theme={null}
from multimind import MistralModel
from multimind.models.mistral import MistralAIModel

local_model = MistralModel(
    model="mistral",
    base_url="http://localhost:11434",  # Ollama server
)

hosted_model = MistralAIModel(
    model_name="mistral-small-latest",
    api_key=None,  # falls back to MISTRAL_API_KEY
)
```

## Agent Configuration

### Memory Settings

```python theme={null}
from multimind import AgentMemory

memory = AgentMemory(
    max_history=100,  # Maximum number of interactions to store
)
```

### Tool Configuration

```python theme={null}
from multimind import CalculatorTool

tools = [
    CalculatorTool(),
]
```

## Task Runner Configuration

```python theme={null}
from multimind import OpenAIModel, TaskRunner

runner = TaskRunner(
    model=OpenAIModel(model_name="gpt-4o-mini"),
    tasks=None,  # optional list of task dicts
    max_retries=3,  # Number of retry attempts per task
)
```

## MCP Configuration

### Workflow Definition

An MCP spec must contain `version`, `models` (a list of `{name, type, config}`
entries; types: `openai`, `claude`, `mistral`, `huggingface`, `ollama`) and a
`workflow` with `steps` (`{id, type, config}`; types: `model`, `transform`,
`condition`) and `connections` (`{from, to}` between existing step ids). A
`model` step's config needs `model` (a registered model name) and
`prompt_template`; the full schema is in `multimind/mcp/schema.json`:

```python theme={null}
workflow = {
    "version": "1.0.0",
    "models": [
        {
            "name": "gpt",
            "type": "openai",
            "config": {"model": "gpt-4o-mini", "temperature": 0.7}
        }
    ],
    "workflow": {
        "steps": [
            {
                "id": "analysis",
                "type": "model",
                "config": {"model": "gpt", "prompt_template": "Analyze: {input}"}
            },
            {
                "id": "review",
                "type": "model",
                "config": {"model": "gpt", "prompt_template": "Review: {analysis}"}
            }
        ],
        "connections": [
            {"from": "analysis", "to": "review"}
        ]
    }
}
```

## Logging Configuration

### Usage Tracking

```python theme={null}
from multimind import UsageTracker

tracker = UsageTracker(
    db_path=None,  # SQLite database path (default location if None)
)
```

### Trace Logging

```python theme={null}
import logging

from multimind import TraceLogger

logger = TraceLogger(
    log_dir=None,  # Directory for trace logs (default location if None)
    log_level=logging.INFO,
)
```

## CLI Configuration

### Command Line Options

```bash theme={null}
# Show environment and configuration info
multimind config info

# View or set global CLI configuration
multimind config manage
multimind config manage --set default_model openai
multimind config manage --get default_model
```

Global CLI configuration is stored as JSON in `~/.multimind_cli_config`.

### Configuration File (config.yaml)

The SDK-level `multimind.Config` loads a YAML file from the path given by the
`MULTIMIND_CONFIG` environment variable (or an explicit `config_path`).
Environment variables override file values for API keys and the Ollama host:

```yaml theme={null}
# Provider settings (api_key is overridden by the matching env var)
openai:
  api_key: your_openai_api_key
anthropic:
  api_key: your_anthropic_api_key
mistral:
  api_key: your_mistral_api_key
huggingface:
  api_key: your_huggingface_api_key
ollama:
  host: http://localhost:11434

# Per-model parameters, read via Config.get_model_params(model_type, model_name)
models:
  openai:
    gpt-4o-mini:
      temperature: 0.7
      max_tokens: 2000
```

## Best Practices

1. **Environment Variables**
   * Use environment variables for sensitive data
   * Keep configuration in version control
   * Use different configs for different environments

2. **Model Selection**
   * Choose models based on task requirements
   * Consider cost and performance trade-offs
   * Monitor model usage and costs

3. **Resource Management**
   * Set appropriate timeouts
   * Implement retry strategies
   * Monitor memory usage

4. **Security**
   * Never commit API keys
   * Use secure storage for sensitive data
   * Implement proper access controls

5. **Monitoring**
   * Enable usage tracking
   * Set up logging
   * Monitor performance metrics

## Troubleshooting

### Common Issues

1. **Configuration Not Loaded**
   * Check file permissions
   * Verify environment variables
   * Check config file syntax

2. **Model Access**
   * Verify API keys
   * Check model availability
   * Confirm account status

3. **Resource Limits**
   * Check rate limits
   * Monitor token usage
   * Verify timeout settings

### Getting Help

* Check the [feature status](/feature-status) and [installation guide](/installation)
* Open an issue on [GitHub](https://github.com/multimindlab/multimind-sdk/issues)
* Contact support at [contact@multimind.dev](mailto:contact@multimind.dev)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.