Configuration

Freesona has two configuration layers. The .env file handles startup configuration — credentials, provider selection, file paths, and optional integration keys. This file is read once when the bot launches and requires a restart to change. The runtime config layer handles tunable behavior values — polling intervals, timeouts, generation pacing — via /config commands that take effect immediately without a restart.

Environment Variables

Copy .env.sample to .env and fill in your values before launching the bot:

cp .env.sample .env

Required

These three variables must be set. The bot refuses to start if any of them is missing or still holds a placeholder value.

Variable	Required	Default	Description
`BOT_TOKEN`	Yes	—	Your Discord bot token from the Developer Portal
`CHANNEL_ID`	Yes	—	Numeric channel ID (Discord snowflake) where the bot posts its startup message
`AI_PROVIDER`	Yes	—	Active AI provider: `gemini`, `openai`, `ollama`, `nim`, `azure`, `groq`, or `openrouter`

AI Provider Keys

You only need to set the key for the provider you selected in AI_PROVIDER. Leave the others blank.

Provider	`AI_PROVIDER` value	Variable(s) to set	Notes
Google Gemini	`gemini`	`GOOGLE_API_KEY`	Default provider
OpenAI	`openai`	`OPENAI_API_KEY`	Also set `OPENAI_BASE_URL` (default: `https://api.openai.com/v1/chat/completions`)
Ollama	`ollama`	`OLLAMA_BASE_URL`	Defaults to `http://localhost:11434/api/chat` if not set
NVIDIA NIM	`nim`	`NVIDIA_API_KEY`	Also set `NVIDIA_NIM_BASE_URL` (default: `https://integrate.api.nvidia.com/v1/chat/completions`). `NIM_API_KEY` and `NIM_BASE_URL` are also accepted as aliases.
Azure AI Foundry	`azure`	`AZURE_AI_KEY` + `AZURE_AI_BASE_URL`	`AZURE_AI_BASE_URL` is your Azure AI Foundry endpoint
Groq	`groq`	`GROQ_API_KEY`	Base URL defaults to `https://api.groq.com/openai/v1/chat/completions`
OpenRouter	`openrouter`	`OPENROUTER_API_KEY`	Optionally set `OPENROUTER_BASE_URL` (default: `https://openrouter.ai/api/v1/chat/completions`), `OPENROUTER_SITE_URL`, and `OPENROUTER_SITE_NAME`

You can also set MODEL_NAME to override the default model for your chosen provider, or use AI_PROVIDER_MODEL to set a per-provider model override that persists across provider switches.

Optional Integrations

These variables unlock specific features. The bot starts and runs normally without them — the corresponding commands will simply be unavailable or fall back to a different method.

Variable	Required	Default	Description
`MVSEP_API_KEY`	No	—	Required for audio stem separation via the `~separate` command (MVSEP module)
`MVSEP_WEBHOOK_URL`	No	—	Public URL for MVSEP task completion callbacks
`MVSEP_WEBHOOK_SEND_MAIL_ON_ERROR`	Set to `true` to have MVSEP send an email on task error (default: `false`)
`WOLFRAM_APPID_SHORT`	Wolfram Short Answer API key used by the `~math` command for direct computation
`WOLFRAM_APPID_LLM`	Wolfram LLM API key used as a fallback if the short answer API does not return a result
`LOGOKIT_TOKEN`	LogoKit API token for fetching publication logos in RSS feed embeds
`CHROMA_COLLECTION`	ChromaDB collection name for the knowledge base (default: `freesona`)
`CHROMA_PERSIST_DIRECTORY`	Local path for ChromaDB vector storage (default: `./.chroma`)
`BOT_NAME`	Display name used in startup messages and certain response contexts (default: `Freesona`)
`HTTP_PORT`	Port for the built-in health check and webhook server (default: `10000`)
`EMBEDDING_MODEL`	Sentence transformer model for ChromaDB embeddings (default: `all-MiniLM-L6-v2`)
`KB_ENABLED`	Enable knowledge base (ChromaDB) integration (default: `true`)
`KB_TOP_K`	Number of top chunks to retrieve from knowledge base (default: `5`)
`MODEL_TEMPERATURE`	Sampling temperature for AI generation 0.0–2.0 (default: `0.7`)
`AI_PERSONA`	Inline persona text used as the bot’s system instruction (for example, `You are a helpful assistant.`). Overridden by `AI_PERSONA_JSON_FILE` or `AI_PERSONA_FILE` if those are set.
`PROMPT_TOKEN_BUDGET`	Token budget for prompt construction (default: `8000`)
`NIM_API_KEY`	Alias for `NVIDIA_API_KEY` (NVIDIA NIM provider)
`NIM_BASE_URL`	Alias for `NVIDIA_NIM_BASE_URL` (NVIDIA NIM provider)
`OPENROUTER_BASE_URL`	OpenRouter endpoint (default: `https://openrouter.ai/api/v1/chat/completions`)

File Paths

Freesona stores several mutable files: a runtime config file, a user memory database, a warnings database, a character memory database, an anniversaries database, a canon database, and persona files. The correct paths depend on where you are hosting the bot.

Variable	Local default	Cloud (Railway / Render)
`CONFIG_FILE_PATH`	`config.json`	`/data/config.json`
`MEMORY_FILE_PATH`	`memory.db`	`/data/memory.db`
`WARNINGS_FILE_PATH`	`warnings.db`	`/data/warnings.db`
`CHARACTER_MEMORY_FILE_PATH`	`character_memory.db`	`/data/character_memory.db`
`ANNIVERSARIES_FILE_PATH`	`anniversaries.db`	`/data/anniversaries.db`
`CANON_FILE_PATH`	`canon.db`	`/data/canon.db`
`AI_PERSONA_FILE`	`persona.txt`	`/data/persona.txt`
`AI_PERSONA_JSON_FILE`	`persona.json`	`/data/persona.json`
`AI_PERSONAS_FILE`	`personas.json`	`/data/personas.json`
`LOG_FILE_PATH`	`logs/freesona.log`	`/data/logs/freesona.log`

On cloud hosts without a persistent volume, file changes do not survive a redeployment. The container resets to the image state. Mount a persistent volume at /data and switch to the /data/ paths in your .env to keep your config, memory, warnings, and persona across deploys.

Logging

Freesona uses a structured logging system. These variables control logging behavior:

Variable	Default	Description
`LOG_ENABLED`	`false`	Enable or disable logging entirely
`LOG_CHANNEL_ID`	—	Discord channel ID to send log messages to (optional)
`LOG_LEVEL`	`INFO`	Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`
`LOG_FILE_PATH`	`logs/freesona.log`	Path to the log file
`LOG_FILE_MAX_MONTHS`	`3`	Maximum months to retain log files
`LOG_INCLUDE_DISCORD`	`true`	Include Discord library logs
`LOG_SECTION_GENERAL`	`true`	Log general bot events (startup, shutdown, cogs)
`LOG_SECTION_CONFIG`	`false`	Log configuration changes
`LOG_SECTION_AI`	`true`	Log AI provider calls, generation, prompts
`LOG_SECTION_MEMORY`	`false`	Log memory operations (conversation, facts, character, KB)
`LOG_SECTION_MEDIA`	`false`	Log media operations (MVSEP, yt-dlp, search)
`LOG_SECTION_MODERATION`	`false`	Log moderation actions (kick, ban, warn)
`LOG_SECTION_SECURITY`	`true`	Log security checks (injection detection, URL validation)
`LOG_SECTION_WEBHOOK`	`false`	Log webhook events (FastAPI/MVSEP)

Runtime Config

The /config command group lets the bot owner inspect and adjust tunable behavior values while the bot is running. Changes take effect immediately. No restart is needed. These commands require you to be the bot owner (the account that owns the Discord application in the Developer Portal).

Commands

/config list
/config show [key]
/config set <key> <value>
/config reset <key>

/config list — Prints all configurable keys with their descriptions and current defaults.
/config show [key] — Shows the current value and default for one key, or all keys if you omit the argument.
/config set <key> <value> — Updates a key to a new value immediately. The bot converts the value to the correct type (int, float, bool, or string) based on the key’s default type.
/config reset <key> — Removes the override and restores the key to its compiled-in default.

Configurable Keys

These are the configurable keys and the defaults the bot ships with.

Key	Type	Default	Description
`prefix`	string	`~`	Command prefix for text commands
`conversation_response_mode`	string	`all`	How the bot responds in conversations: `all`, `mention`, `reply`
`provider`	string	`gemini`	AI provider to use: `gemini`, `openai`, `ollama`, `nim`, `azure`, `groq`, `openrouter`
`provider_model`	string	“	Model name for the selected provider (empty = use env default)
`chroma_collection`	string	`freesona`	ChromaDB collection name
`chroma_persist_directory`	string	`./.chroma`	ChromaDB persistence directory
`debounce_seconds`	float	`1.2`	Debounce time for message processing in seconds
`autonomy_cooldown_seconds`	int	`120`	Cooldown between autonomous actions in seconds
`autonomy_user_cooldown`	int	`60`	Per-user cooldown for autonomous actions in seconds
`mvsep_poll_interval`	int	`10`	Seconds between MVSEP API polling checks
`mvsep_poll_timeout`	int	`600`	Max seconds to wait for MVSEP task completion
`ytdlp_subprocess_timeout`	int	`300`	Max seconds for yt-dlp subprocess to complete
`ytdlp_compress_target_mb`	float	`9.5`	Target size in MB for video compression
`generation_split_min_length`	int	`280`	Minimum message length before splitting into segments
`generation_split_delay_base`	float	`1.2`	Base delay in seconds between message segments
`generation_split_delay_per_char`	float	`0.012`	Additional delay per character in segment
`generation_split_delay_max`	float	`3.5`	Maximum delay between segments in seconds
`generation_rate_limit`	float	`5`	Minimum seconds between AI generation calls
`model_temperature`	float	`0.7`	Sampling temperature for AI generation
`log_enabled`	bool	`false`	Enable optional logging
`log_channel_id`	int	`0`	Discord channel ID for log messages (0 = disabled)
`log_level`	string	`INFO`	Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`
`log_file_path`	string	`logs/freesona.log`	Log file path with monthly rotation
`log_file_max_months`	int	`3`	Log file rotation period in months
`log_include_discord`	bool	`true`	Also send logs to Discord channel
`log_section_general`	bool	`true`	Log general bot events (startup, shutdown, cogs)
`log_section_config`	bool	`false`	Log configuration changes
`log_section_ai`	bool	`true`	Log AI provider calls, generation, prompts
`log_section_memory`	bool	`false`	Log memory operations (conversation, facts, character, KB)
`log_section_media`	bool	`false`	Log media operations (MVSEP, yt-dlp, search)
`log_section_moderation`	bool	`false`	Log moderation actions (kick, ban, warn)
`log_section_security`	bool	`true`	Log security checks (injection detection, URL validation)
`log_section_webhook`	bool	`false`	Log webhook events (FastAPI/MVSEP)

Example Usage

/config show mvsep_poll_interval
/config set generation_rate_limit 2.0
/config reset ytdlp_compress_target_mb

Use /dumpconfig to see the full contents of your current config.json in one shot. Useful for verifying the state of all settings at once.

config.json

config.json is the bot’s runtime state file. Freesona reads it on startup and writes to it whenever you use commands that change persistent settings. You do not need to edit this file manually. The Discord commands are the intended interface. A fresh config.json starts from config.sample.json and contains only:

config.json

{
  "prefix": "~",
  "chat_channel_id": null
}

As you use the bot, it accumulates additional fields:

Field	Set by	Description
`prefix`	`~prefix <new_prefix>`	The active prefix for all prefix commands (max 5 characters)
`chat_channel_id`	`/setchannel`	Channel where the bot responds to general (non-mention) messages
`conversation_response_mode`	`/chatmode`	How the bot decides to respond: `all`, `mentions`, or `smart`
`autonomy_*` settings	`/autonomy`	Whether autonomy mode is on, and its frequency setting
`enabled_modules`	`/module enable` / `/module disable`	Per-module on/off state persisted across restarts
`provider` / `provider_model`	`/provider set` / `/model set`	Active AI provider and model overrides
`timezone`	`/settimezone`	IANA timezone string for time-sensitive features
`rss_feeds`	`/rss add` / `/rss remove`	Configured RSS/Atom feed subscriptions

You do not edit config.json directly. Use the Discord commands — ~prefix, /setchannel, /autonomy, /module, /provider, /model, /settimezone, and /rss — to change these values. The bot writes the file automatically.

Get Started

Features

Guides

Reference

Changelog

Environment Variables

Required

AI Provider Keys

Optional Integrations

File Paths

Logging

Runtime Config

Commands

Configurable Keys

Example Usage

config.json

​Environment Variables

​Required

​AI Provider Keys

​Optional Integrations

​File Paths

​Logging

​Runtime Config

​Commands

​Configurable Keys

​Example Usage

​config.json

Environment Variables

Required

AI Provider Keys

Optional Integrations

File Paths

Logging

Runtime Config

Commands

Configurable Keys

Example Usage

config.json