Quickstart

By the end of this guide, you will have a Freesona bot online in your Discord server. It will respond to ~ping, reply to messages in your designated chat channel, and run on your own infrastructure with your own AI provider key. The bot keeps its conversation state, user memory, character memory, persona knowledge, and retrieval context in separate systems so the runtime stays modular and provider-agnostic.

Create a Discord application and bot

Go to the Discord Developer Portal and create a new application.

Click New Application, give it a name (this becomes your bot’s display name), and save.
In the left sidebar, select Bot.
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
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 will need this as your CHANNEL_ID.

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 are adding it to an existing virtual environment manually, run:

.venv\Scripts\pip.exe install tzdata

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

Variable	What to put here
`BOT_TOKEN`	The bot token you copied from the Developer Portal
`CHANNEL_ID`	The numeric ID of your `#bot-log` channel
`AI_PROVIDER`	The provider you want to use (`gemini` is the default)
`GOOGLE_API_KEY`	Your Gemini API key (or swap for another provider’s key — see AI Providers)
`MODEL_NAME`	The model to use; `gemini-flash-lite-latest` is the default
`BOT_NAME`	Display name used in startup messages

Using a different AI provider? Only set the key for the provider you selected in AI_PROVIDER. See the full provider key reference in Configuration.

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:

Copy .env.sample to .env if .env does not exist yet, then prompt you to fill it in.
Validate that BOT_TOKEN, CHANNEL_ID, and AI_PROVIDER are set and not placeholder values.
Verify that the correct API key is present for your chosen AI_PROVIDER.
Check that CHANNEL_ID is a numeric Discord snowflake.
Create a .venv virtual environment if one does not exist.
Install dependencies from requirements.txt.
Run scripts/check_project.py to catch any project-level issues.
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>`.

If the bot fails to start or you encounter errors in the console, see the Troubleshooting guide.

Confirm the bot is responding

In any channel your bot has access to, run:

~ping

/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 do not 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.

Get Started

Features

Guides

Reference

Changelog

What’s Next

Configuration

Persona System

AI Providers

​What’s Next

Configuration

Persona System

AI Providers

What’s Next