.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 |
HTTP_PORT | Port for the built-in FastAPI health/webhook server (default: 10000) |
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 (e.g. 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 (e.g. 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 inAI_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); also accepted as NIM_API_KEY |
NVIDIA_NIM_BASE_URL | NVIDIA NIM endpoint (default: https://integrate.api.nvidia.com/v1/chat/completions) |
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) |
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 (e.g. 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) |
GOOGLE_SEARCH_API_KEY | Legacy Google Custom Search key — fallback for /search when Gemini grounding is unavailable |
SEARCH_ENGINE_ID | Legacy Google Custom Search engine ID — required alongside GOOGLE_SEARCH_API_KEY |
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) |
File Paths
Freesona persists its state — persona, memory, warnings, and config — to local files. The right path depends on where you’re 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 |
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.