> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fs.soquincy.qzz.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Freesona Environment Variables: Setup and Configuration
> Every environment variable Freesona reads from .env — required credentials, AI provider keys, optional integrations, and file paths.
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](https://discord.com/developers/applications) |
| `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 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`); 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.
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, and runtime config — is wiped on every redeploy.