Skip to main content
By the end of this guide, you’ll have a Freesona bot online in your Discord server: responding to ~ping, replying to messages in your designated chat channel, and running on your own infrastructure with your own AI provider key.
1

Create a Discord Application and Bot

Go to the Discord Developer Portal and create a new application.
  1. Click New Application, give it a name (this becomes your bot’s display name), and save.
  2. In the left sidebar, select Bot.
  3. Under Privileged Gateway Intents, enable all three required intents:
    • MESSAGE CONTENT INTENT — required for prefix commands and reading message text
    • GUILDS INTENT — required for server awareness
    • GUILD MEMBERS INTENT — required for member-related features and moderation
  4. Click Reset Token, confirm, and copy the token somewhere safe. This is your BOT_TOKEN.
Invite the bot to your server:In the left sidebar, go to OAuth2 → URL Generator. Under Scopes, select bot and applications.commands. Under Bot Permissions, enable:
  • Send Messages
  • Embed Links
  • Attach Files
  • Read Message History
  • Manage Messages (required for the moderation module)
Copy the generated URL and open it in your browser to add the bot to your server.
Create a dedicated #bot-log channel in your server and copy its channel ID (right-click the channel → Copy Channel ID with Developer Mode enabled). You’ll need this as your CHANNEL_ID.
2

Clone the Repo and Install Dependencies

Clone Freesona and install its Python dependencies:
git clone https://github.com/soquincy/Freesona.git
cd Freesona
pip install -r requirements.txt
Windows users: Python’s zoneinfo module may lack IANA time zone data on some Windows installs, which breaks /settimezone and other ZoneInfo lookups. The tzdata package is included in requirements.txt and installs automatically. If you’re adding it to an existing virtual environment manually, run:
.venv\Scripts\pip.exe install tzdata
3

Configure Your .env File

Copy the sample environment file and fill in your values:
cp .env.sample .env
Open .env in a text editor. At minimum, set these values before launching:
.env
BOT_TOKEN=your_discord_bot_token
CHANNEL_ID=your_log_channel_id
AI_PROVIDER=gemini
GOOGLE_API_KEY=your_gemini_api_key
MODEL_NAME=gemini-flash-lite-latest
BOT_NAME=Freesona
HTTP_PORT=10000
VariableWhat to put here
BOT_TOKENThe bot token you copied from the Developer Portal
CHANNEL_IDThe numeric ID of your #bot-log channel
AI_PROVIDERThe provider you want to use (gemini is the default)
GOOGLE_API_KEYYour Gemini API key (or swap for another provider’s key — see AI Providers)
MODEL_NAMEThe model to use; gemini-flash-lite-latest is the default
BOT_NAMEDisplay name used in startup messages
HTTP_PORTPort for the built-in health check and webhook server
Using a different AI provider? Only set the key for the provider you’ve selected in AI_PROVIDER. See the full provider key reference in Configuration.
4

Launch the Bot

Option A — Direct launch:
python main.py
This starts the Discord bot and the built-in HTTP server (used for webhooks and health checks) as concurrent async tasks.
Option B — Use the local setup scripts (recommended for first-time setup):On Linux or macOS:
bash scripts/setup_local.sh
On Windows:
scripts\setup_local.cmd
The setup scripts automate the full local bootstrap process:
  1. Copy .env.sample to .env if .env doesn’t exist yet, then prompt you to fill it in.
  2. Validate that BOT_TOKEN, CHANNEL_ID, and AI_PROVIDER are set and not placeholder values.
  3. Verify that the correct API key is present for your chosen AI_PROVIDER.
  4. Check that CHANNEL_ID is a numeric Discord snowflake.
  5. Create a .venv virtual environment if one doesn’t exist.
  6. Install dependencies from requirements.txt.
  7. Run scripts/check_project.py to catch any project-level issues.
  8. Launch main.py.
The setup scripts are for local and manual self-hosted deployments only. Do not use them in Docker, Railway, Render, or any other automated deployment environment — those platforms manage their own bootstrap process.
When the bot is online, it sends a startup message to the channel specified by CHANNEL_ID:
Heya! Freesona here! Current prefix is `~`. For fresh info, use `search <query>`.
5

Confirm the Bot Is Responding

In any channel your bot has access to, run:
~ping
or
/ping
The bot should respond with a latency message. If it does, your bot is up and connected.From here you can:
  • Set the AI chat channel with /setchannel so the bot knows where to respond to general messages.
  • Check loaded modules with /module list.
  • Set a persona with /setpersona.
For cloud hosting on Railway or Render, the local setup scripts don’t apply — those platforms manage environment injection and process launch directly. See the Hosting guide for platform-specific setup steps, persistent volume configuration, and the /data/ file paths required to survive redeployments.

​
What’s Next

Configuration

Explore every .env variable and live /config setting.

Persona System

Give your bot a persona using structured fields.

AI Providers

Switch to Ollama, Groq, OpenRouter, or any other supported provider.