Set up Soren in minutes
Everything you need to go from zero to a fully working events system in your Discord server.
Add Soren to your Discord server
Click the invite link below. You'll be asked to select a server and approve the required permissions. Soren needs: Send Messages, Embed Links, Read Message History, and Mention Everyone (for pinging notify roles during reminders).
➕ Add Soren to DiscordEnable Server Members Intent
If you're self-hosting Soren, go to the Discord Developer Portal, open your bot's settings, go to Bot → Privileged Gateway Intents, and enable Server Members Intent. This lets Soren resolve member names for RSVP lists.
Run /setup in your server
In any text channel, type /setup and pick the role whose members should be able to
create, edit, and delete events. This is your Event Creator role —
it can be any existing role, or create a new one first.
Server administrators always have full access regardless of role assignment.
Customize your embed color (optional)
Run /embedcolor to choose the accent color for all event embeds on your server.
Free servers get 3 colors (Blue, Red, Green). Premium servers unlock 8 colors including Gold, Purple, Cyan, and Orange.
Create your first event with /newevent
Run /newevent #channel where #channel is where you want the event post to appear. You'll walk through 4 steps:
- Event type — Single, Daily, Weekly, Bi-Weekly, Bi-Monthly, Monthly, or Custom
- Timezone — Pick from a dropdown of common timezones
- Reminder timing — 15 min, 30 min, 1 hr, 2 hrs, or a custom offset
- Event details — Title, description, start/end time, notify role
July 4 8pm, next Friday 9pm, tomorrow 8pm,
or the strict format 2026-07-04 20:00.
Google Calendar Integration
Soren has two separate Google Calendar features. Neither is required — the core event system works completely without Google.
📤 Primary Sync (/gcal)
Connect one Google Calendar per server. Events created with /newevent are automatically pushed into it.
New events added directly in Google Calendar sync back to Discord every 15 minutes.
📥 G-Cal Integrations (/gcalint)
Connect multiple Google Calendars. Each one posts a weekly digest summary into its own Discord channel. Great for syncing a shared team or community calendar. Free tier: up to 5 integrations.
Create a Google Cloud project
Go to Google Cloud Console
and create a new project (or use an existing one). Name it anything — e.g. Soren.
Enable the Google Calendar API
In your project, go to APIs & Services → Library. Search for Google Calendar API and click Enable.
Create OAuth credentials
Go to APIs & Services → Credentials → Create Credentials → OAuth client ID.
Choose Web application as the type.
Under Authorized redirect URIs, add: http://localhost
Download the JSON file, rename it google_credentials.json, and place it in the Soren bot's root folder.
google_credentials.json to version control. It's already in Soren's .gitignore.
Connect in Discord
Run /gcalint add (or /gcal connect for primary sync) and follow the prompts.
After authorizing with Google, your browser will show "This site can't be reached" — that's normal!
Copy the code= value from the browser URL bar and paste it into /gcalint verify <code>.
A calendar picker will appear — select which calendar to connect.
Running Soren yourself
Soren is fully open source. Clone it, run it on your own machine or VPS.
Requirements
- Python 3.10 or newer
- A Discord bot application (create one here)
- Server Members Intent enabled on the bot
- Optional: Google Cloud project for Calendar features
Quick start
# Clone the repository
git clone https://github.com/retrac-ca/soren.git
cd soren
# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate # macOS / Linux
venv\Scripts\activate # Windows PowerShell
# Install dependencies
pip install -r requirements.txt
# Configure your environment
cp .env.example .env
# Edit .env: add your DISCORD_TOKEN and BOT_OWNER_ID
# Run the bot
python bot.pyRunning as a service (Linux / VPS)
To keep Soren running after you close your terminal, create a systemd service:
# /etc/systemd/system/soren.service
[Unit]
Description=Soren Discord Bot
After=network.target
[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/path/to/soren
ExecStart=/path/to/soren/venv/bin/python bot.py
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.targetsudo systemctl enable soren
sudo systemctl start soren
sudo systemctl status soren # check it's running