Environment Variables

Freesona reads configuration from a .env file at startup. Copy .env.sample to .env and fill in the values you need. Variables you leave blank are ignored unless the feature that depends on them is used.

Required

These three variables must be set for the bot to start.

Variable	Description
`BOT_TOKEN`	Your Discord bot token from the Developer Portal
`CHANNEL_ID`	Discord channel ID where the bot sends startup messages
`AI_PROVIDER`	Active AI provider: `gemini`, `openai`, `ollama`, `nim`, `azure`, `groq`, or `openrouter`

HTTP_PORT has a default of 10000 and is not required.

AI Provider

Variable	Description
`AI_PROVIDER`	Active provider: `gemini`, `openai`, `ollama`, `nim`, `azure`, `groq`, or `openrouter`
`AI_PROVIDER_MODEL`	Override the default model for the chosen provider (leave blank to use the provider default)
`MODEL_NAME`	Default model name used when `AI_PROVIDER=gemini` (for example, `gemini-flash-lite-latest`)
`BOT_NAME`	Display name used in startup and status messages (default: `Freesona`)
`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.

Provider API Keys

Set only the key for the provider you chose in AI_PROVIDER. You do not need all of these.

Variable	Provider
`GOOGLE_API_KEY`	Gemini (`AI_PROVIDER=gemini`)
`OPENAI_API_KEY`	OpenAI (`AI_PROVIDER=openai`)
`OPENAI_BASE_URL`	OpenAI endpoint (default: `https://api.openai.com/v1/chat/completions`)
`OLLAMA_BASE_URL`	Ollama (`AI_PROVIDER=ollama`, default: `http://localhost:11434/api/chat`)
`NVIDIA_API_KEY`	NVIDIA NIM (`AI_PROVIDER=nim`)
`NVIDIA_NIM_BASE_URL`	NVIDIA NIM endpoint (default: `https://integrate.api.nvidia.com/v1/chat/completions`)
`NIM_API_KEY`	Alias for `NVIDIA_API_KEY` (NVIDIA NIM provider)
`NIM_BASE_URL`	Alias for `NVIDIA_NIM_BASE_URL` (NVIDIA NIM provider)
`AZURE_AI_KEY`	Azure AI Foundry (`AI_PROVIDER=azure`)
`AZURE_AI_BASE_URL`	Your Azure AI Foundry endpoint URL
`GROQ_API_KEY`	Groq (`AI_PROVIDER=groq`)
`GROQ_BASE_URL`	Groq endpoint (default: `https://api.groq.com/openai/v1/chat/completions`)
`OPENROUTER_API_KEY`	OpenRouter (`AI_PROVIDER=openrouter`)
`OPENROUTER_BASE_URL`	OpenRouter endpoint (default: `https://openrouter.ai/api/v1/chat/completions`)
`OPENROUTER_SITE_URL`	Your site URL sent in OpenRouter attribution headers
`OPENROUTER_SITE_NAME`	Your site name sent in OpenRouter attribution headers (default: `Freesona`)

NVIDIA_API_KEY is the preferred variable name for the NVIDIA NIM provider.

Optional Integrations

Set these only if you want to use the corresponding feature.

Variable	Description
`MVSEP_API_KEY`	MVSEP API key for the `~separate` / `/separate` audio separation command
`MVSEP_WEBHOOK_URL`	Public URL for MVSEP completion callbacks (for example, `https://your-host.example.com/webhooks/mvsep`); falls back to polling every 10 seconds if unset
`MVSEP_WEBHOOK_SEND_MAIL_ON_ERROR`	Send an email on MVSEP error (default: `false`)
`WOLFRAM_APPID_SHORT`	Wolfram Short Answer API key for `~math` (primary)
`WOLFRAM_APPID_LLM`	Wolfram LLM API key for `~math` (fallback when the Short Answer API returns no result)
`LOGOKIT_TOKEN`	LogoKit API key for fetching publisher logos in RSS feed embeds
`CHROMA_COLLECTION`	ChromaDB collection name (default: `freesona`)
`CHROMA_PERSIST_DIRECTORY`	Path to the ChromaDB vector store directory (default: `./.chroma`)
`BOT_NAME`	Display name used in startup and status messages (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 persists its state — persona, memory, warnings, character memory, anniversaries, config, and logs — to local files. The right path depends on where you are running the bot.

Variable	Local default	Cloud (Railway / Render)
`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`
`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`
`LOG_FILE_PATH`	`logs/freesona.log`	`/data/logs/freesona.log`

AI_PERSONA_JSON_FILE takes precedence over AI_PERSONA_FILE. If a persona.json is found it is loaded first. persona.txt is only used as a fallback for existing installs.

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)

On Railway and Render, you must mount a persistent volume at /data and use the /data/ paths shown above. Without a persistent volume, all data — including your persona, conversation memory, warnings, character memory, anniversaries, and runtime config — is wiped on every redeploy.

Get Started

Features

Guides

Reference

Changelog

Environment Variables

Required

AI Provider

Provider API Keys

Optional Integrations

File Paths

Logging

​Required

​AI Provider

​Provider API Keys

​Optional Integrations

​File Paths

​Logging

Required

AI Provider

Provider API Keys

Optional Integrations

File Paths

Logging