> ## 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.
# Introduction to Freesona: BYOK Self-Hosted Discord Bot
> Freesona is a free, open-source Discord bot you self-host. Bring your own AI keys, customize the persona, and run it on your infrastructure.
Freesona is a **BYOK (Bring Your Own Key)** Discord bot you fork, configure, and run on your own hardware or cloud account. Drop in your own API key and you get a fully functional bot that behaves exactly the way you configure it. No paying for credits, no rate limits set by someone else, and no lock-in to a single AI vendor's personality. No credits. No voting. No "upgrade to unlock." Everything runs on your infrastructure, under your control.
## What Freesona Can Do
Freesona ships as a ready-to-run Python application built on [discord.py](https://discordpy.readthedocs.io/). It organizes its capabilities into loadable modules you can enable or disable without touching a line of code:
* **AI persona system** — `/setpersona` opens a structured, button-based editor for persona fields. Changes apply immediately with no restart required. Save and load named presets with `/personasave` and `/personaload`.
* **Multi-provider AI** — a shared provider abstraction lets you swap providers without changing any command logic. Switch live with `/provider set` and `/model set`.
* **Long-term user memory** — Freesona extracts facts about each user from conversation, scores them by importance, and persists them across restarts. Memory stays isolated per user per server, so conversations never bleed between guilds.
* **Autonomy mode** — the bot can respond on its own using a confidence-scored intent evaluator, not random chance. Per-channel cooldowns prevent it from dominating a conversation.
* **Knowledge base** — when ChromaDB is enabled, Freesona retrieves relevant document chunks semantically and injects them into generation context. Manage entries with `/kbadd`, `/kblist`, `/kbdelete`, and `/kbsearch`.
* **Media tools** — download audio and video with yt-dlp, separate audio stems via MVSEP, and process images, PDFs, audio, and code files through the active provider's multimodal pipeline.
* **Moderation suite** — a full warning system with hex IDs, auto-threshold actions, and DM notifications. Module-level on/off controls let you enable only what your server needs.
Clone the repo, fill in your `.env`, and have the bot running in under five minutes.
Every `.env` variable and every runtime `/config` key, explained.
Build a convincing AI persona with structured fields and instant live updates.
Gemini, OpenAI, Ollama, NVIDIA NIM, Azure AI Foundry, Groq, and OpenRouter.
Complete listing of every prefix and slash command the bot ships with.
Warning system, auto-threshold actions, and per-guild moderation controls.
## How Freesona Differs from Hosted Bots
Platforms like MEE6 or hosted persona bots give you a product someone else built on infrastructure you don't control with a ceiling you'll eventually hit. Freesona inverts that model:
| | Freesona | Hosted bots |
| ----------------- | --------------------------------------------------------------------------- | ----------------------------------- |
| **Cost** | Only your AI provider costs | Subscription or per-message credits |
| **AI provider** | Your choice, swappable at runtime | Locked to vendor |
| **Data** | Stays on your host, but is also sent to whichever AI provider you configure | Processed on third-party servers |
| **Features** | All modules enabled by default | Gated behind upgrades |
| **Customization** | Full source access via fork | Config options only |
## Supported AI Providers
Freesona's generation pipeline routes through a common provider abstraction. Set `AI_PROVIDER` in your `.env` to activate one:
| Provider | `AI_PROVIDER` value | Notes |
| ---------------- | ------------------- | ------------------------------------------------------------------- |
| Google Gemini | `gemini` | Default provider; set `GOOGLE_API_KEY` |
| NVIDIA NIM | `nim` | Set `NVIDIA_API_KEY` and `NVIDIA_NIM_BASE_URL` |
| Ollama | `ollama` | Local inference; defaults to `http://localhost:11434/api/chat` |
| OpenAI | `openai` | Also set `OPENAI_BASE_URL` |
| Azure AI Foundry | `azure` | Set `AZURE_AI_KEY` and your Foundry endpoint in `AZURE_AI_BASE_URL` |
| Groq | `groq` | Set `GROQ_API_KEY` |
| OpenRouter | `openrouter` | Set `OPENROUTER_API_KEY` |
You can switch the active provider at runtime without restarting: `/provider set `.
## Command System
Freesona uses a hybrid command system — every command is available as both a **prefix command** (default prefix `~`) and a **slash command**. For example, `~ping` and `/ping` do exactly the same thing. You can change the prefix at any time with `~prefix ` (requires Administrator).
Core commands like `/ping`, `/status`, and `/help` are always loaded. Everything else — AI generation, media tools, moderation, knowledge base — lives in optional modules you control with `/module enable` and `/module disable`.
## Ready to Set Up Your Bot?
Clone Freesona, configure your Discord bot token and AI provider key, and have your self-hosted bot running in under five minutes.