> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/RightNow-AI/openfang/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Overview

> Complete guide to configuring OpenFang Agent OS

OpenFang is configured via a single TOML file located at `~/.openfang/config.toml`. This file controls all aspects of the system including models, channels, security, memory, and networking.

## Quick Start

Create your configuration file:

```bash theme={null}
cp ~/.openfang/config.toml.example ~/.openfang/config.toml
```

Or initialize with the setup wizard:

```bash theme={null}
openfang init
```

## Configuration File Location

* **Default path**: `~/.openfang/config.toml`
* **Custom path**: Set via `OPENFANG_CONFIG` environment variable
* **Example file**: Included in installation at `~/.openfang/config.toml.example`

## Core Configuration Sections

<CardGroup cols={2}>
  <Card title="Models" icon="brain" href="/configuration/models">
    Configure LLM providers, model routing, and fallback chains
  </Card>

  <Card title="Providers" icon="plug" href="/configuration/providers">
    Setup API keys and endpoints for 27 LLM providers
  </Card>

  <Card title="Channels" icon="message" href="/configuration/channels">
    Connect to 40+ messaging platforms and configure behavior
  </Card>

  <Card title="Security" icon="shield" href="/configuration/security">
    Enable authentication, rate limiting, and security features
  </Card>
</CardGroup>

## Minimal Configuration

The absolute minimum configuration requires only a default model:

```toml theme={null}
[default_model]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
api_key_env = "ANTHROPIC_API_KEY"
```

Set the API key as an environment variable:

```bash theme={null}
export ANTHROPIC_API_KEY="sk-ant-..."
openfang start
```

## Full Configuration Example

<CodeGroup>
  ```toml Complete Config theme={null}
  # API server settings
  api_key = ""                               # Set to enable Bearer auth (recommended)
  api_listen = "127.0.0.1:50051"             # HTTP API bind address (use 0.0.0.0 for public)

  [default_model]
  provider = "anthropic"                    # "anthropic", "gemini", "openai", "groq", "ollama", etc.
  model = "claude-sonnet-4-20250514"        # Model identifier
  api_key_env = "ANTHROPIC_API_KEY"         # Environment variable holding API key
  # base_url = "https://api.anthropic.com"  # Optional: override API endpoint

  [memory]
  decay_rate = 0.05                         # Memory confidence decay rate
  # sqlite_path = "~/.openfang/data/openfang.db"   # Optional: custom DB path

  [network]
  listen_addr = "127.0.0.1:4200"           # OFP listen address
  # shared_secret = ""                      # Required for P2P authentication

  # Session compaction (LLM-based context management)
  [compaction]
  threshold = 80                          # Compact when messages exceed this count
  keep_recent = 20                        # Keep this many recent messages after compaction
  max_summary_tokens = 1024               # Max tokens for LLM summary

  # Usage tracking display
  usage_footer = "Full"                   # "Off", "Tokens", "Cost", or "Full"

  # Channel adapters (configure tokens via environment variables)
  [telegram]
  bot_token_env = "TELEGRAM_BOT_TOKEN"
  allowed_users = []                      # Empty = allow all

  [discord]
  bot_token_env = "DISCORD_BOT_TOKEN"
  guild_ids = []                          # Empty = all guilds

  [slack]
  bot_token_env = "SLACK_BOT_TOKEN"
  app_token_env = "SLACK_APP_TOKEN"

  # MCP server connections
  [[mcp_servers]]
  name = "filesystem"
  command = "npx"
  args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
  ```

  ```toml Minimal Production theme={null}
  api_key = "your-secure-api-key-here"
  api_listen = "0.0.0.0:4200"

  [default_model]
  provider = "anthropic"
  model = "claude-sonnet-4-20250514"
  api_key_env = "ANTHROPIC_API_KEY"

  [network]
  listen_addr = "0.0.0.0:4200"
  shared_secret = "your-p2p-shared-secret"
  ```

  ```toml Multi-Provider theme={null}
  [default_model]
  provider = "anthropic"
  model = "claude-sonnet-4-20250514"
  api_key_env = "ANTHROPIC_API_KEY"

  # Fallback providers - tried in order if primary fails
  [[fallback_providers]]
  provider = "openai"
  model = "gpt-4o"
  api_key_env = "OPENAI_API_KEY"

  [[fallback_providers]]
  provider = "ollama"
  model = "llama3.2:latest"
  ```
</CodeGroup>

## Environment Variables

OpenFang uses environment variables for sensitive credentials:

### API Keys

```bash theme={null}
# LLM Providers
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GEMINI_API_KEY="..."
export GROQ_API_KEY="gsk_..."

# Channel Adapters
export TELEGRAM_BOT_TOKEN="..."
export DISCORD_BOT_TOKEN="..."
export SLACK_BOT_TOKEN="xoxb-..."
export SLACK_APP_TOKEN="xapp-..."

# Web Services
export BRAVE_API_KEY="..."
export TAVILY_API_KEY="..."
```

<Note>
  Never hardcode API keys in `config.toml`. Always use environment variables referenced via `api_key_env` fields.
</Note>

## Hot Reload

OpenFang can automatically reload configuration changes without restarting:

```toml theme={null}
[reload]
mode = "hybrid"          # "off", "restart", "hot", or "hybrid"
debounce_ms = 500       # Wait time before applying changes
```

### Reload Modes

* **`off`**: No automatic reloading (default for production)
* **`restart`**: Full daemon restart on config change
* **`hot`**: Hot-reload safe sections only (channels, skills, heartbeat)
* **`hybrid`**: Hot-reload where possible, flag restart-required otherwise

<Warning>
  Some settings like `api_listen` and security settings require a full restart and cannot be hot-reloaded.
</Warning>

## Validation

Validate your configuration before starting:

```bash theme={null}
openfang config validate
```

View merged configuration (includes defaults):

```bash theme={null}
openfang config show
```

## Configuration Hierarchy

Configuration is loaded with the following precedence (highest to lowest):

1. **Environment variables** (for API keys)
2. **Command-line flags** (e.g., `--api-listen`)
3. **`config.toml`** (user configuration)
4. **Built-in defaults** (in code)

## Next Steps

<CardGroup cols={2}>
  <Card title="Configure Models" icon="brain" href="/configuration/models">
    Set up LLM providers and model routing
  </Card>

  <Card title="Setup Providers" icon="plug" href="/configuration/providers">
    Configure all 27 supported LLM providers
  </Card>

  <Card title="Enable Channels" icon="message" href="/configuration/channels">
    Connect messaging platforms
  </Card>

  <Card title="Secure Your Instance" icon="shield" href="/configuration/security">
    Enable authentication and security features
  </Card>
</CardGroup>