Introduction

discord-bot-rs is a multi-instance Discord bot framework written in Rust. One binary runs any number of bot instances from a single shared codebase, each with its own personality file, configuration, database schema, and feature set. The goal is a batteries-included bot you can actually operate in production: a real music player, real AI chat, real moderation, and a small enough codebase that you can read the whole thing in an afternoon.

What it does

The bot is built from independent feature modules that you enable or disable per instance in config.toml. Out of the box you get:

• AI chat — @mention the bot and it replies in-character, using DeepSeek V4 as the primary provider and Google Gemini as a fallback, with a configurable personality prompt.
• Music — yt-dlp plus songbird plus ffmpeg, with a full queue, loop modes, shuffle, and interactive button controls on the now-playing embed.
• Games — the daily NYT Wordle, NYT Connections, and a virtual stock trading game backed by live Finnhub quotes.
• Moderation — tempbans with auto-unban, channel nukes, audit log routing, and a DJ-only mode for music commands.
• Minecraft integration — link a Discord account to a Minecraft account, sync donator roles from a game server, and route chargeback alerts to staff.
• An embedded MCP server — every instance exposes a set of Model Context Protocol tools so external AI clients can read channels, send messages, and manage roles through the bot.

Who it’s for

Self-hosters who want a bot they can stand up with one docker compose up and grow into. The Quickstart takes about ten minutes.

Developers who want to read and extend real Rust code — a working serenity + poise + songbird + sqlx + axum stack with no magic. The Codebase Tour is the fastest way in.

Community admins running a Minecraft server, a Discord, and whatever else, who want a single bot that handles account verification, donator roles, and chargeback alerts without writing glue code.

What this book covers

• Getting Started — prerequisites, quickstart, first-bot tutorial, and verification.
• Configuration — .env, config.toml, personality files, secrets, and multi-instance layouts.
• Features — a page per feature, with activation, configuration, and troubleshooting.
• Architecture — how the pieces fit together.
• Deployment — Docker Compose, Postgres, upgrades, and the production checklist.
• Development — codebase tour, building locally, adding commands, and the contribution workflow.
• Reference — command list, MCP tool catalog, FAQ, glossary.

Where to start

If you want to run the bot, head to the Quickstart. If you want to contribute, start with the Development Overview and then the Codebase Tour. If you’re evaluating the project for a team, the Architecture Overview is the shortest path to “how does this actually work.”

License

discord-bot-rs is licensed under the GNU Affero General Public License v3.0 or later. See CONTRIBUTING.md for contribution terms.

Getting Started

This section takes you from “I have a Discord server” to “I have my own bot running in it.” It is split into five pages:

• Prerequisites lists what you need to gather before touching the code: a Discord application, a token, Docker, and a host to run on.
• Quickstart is the fast path. If you have done Discord bot setup before, this is the only page you need.
• First Bot Tutorial is the slow path. It walks through every step with no assumed knowledge, including screenshots of the Discord developer portal.
• Verifying Your Setup is the post-deploy checklist. Run it once after your first start to make sure each piece is healthy.

When to use discord-bot-rs

This project is a good fit if any of the following describe you:

• You want to self-host a Discord bot rather than rent a hosted one, and you are comfortable running a Docker container on a Linux box.
• You want one codebase that can run several distinct bots (different names, different personalities, different feature sets) from a single deployment.
• You want a bot with batteries included: AI chat, music, games, moderation, and a Minecraft integration, all behind feature flags so you can switch off what you do not need.
• You want a Rust codebase you can read, fork, and extend without fighting a framework.

When NOT to use it

Reach for something else if:

• You just want a moderation or music bot for one server and you do not want to run anything yourself. A hosted bot from top.gg will be faster.
• You want a JavaScript or Python codebase to hack on. Sapphire.js, discord.py, and pycord are all excellent and have larger communities.
• You need a single small bot and the overhead of Docker plus PostgreSQL feels like too much. A 100-line script is the right answer for that.

System requirements

The bot is tested on Linux. macOS and Windows (via WSL2) work as long as Docker Desktop is running. You will need:

• Docker Engine 20.10 or newer with the Compose plugin.
• About 2 GB of free RAM. The bot itself is small; most of the budget goes to PostgreSQL and ffmpeg during music transcoding.
• About 5 GB of free disk for the Docker images, the database volume, and yt-dlp cache.
• Outbound network access to Discord, your AI provider, and (if you enable music) YouTube.

A Raspberry Pi 4 with 4 GB of RAM is enough for a single instance. A $5/month VPS is enough for several. Your laptop is enough for testing.

Time investment

Plan on about 10 minutes from git clone to a running bot if you have set up a Discord application before and you already have Docker installed. Budget closer to 25 minutes if it is your first time, mostly because the Discord developer portal has a few non-obvious clicks.

Next step

Head to Prerequisites to gather what you need before the first command.

Prerequisites

Before you can run the bot, you need three things: a Discord application (this gives you the bot token and identity), Docker with the Compose plugin (this runs the bot), and a host to run them on. None of these take very long, but the Discord developer portal has some non-obvious clicks, so this page walks through every one.

If you would rather follow a step-by-step version with more hand-holding, see First Bot Tutorial. If you have done all this before, skim and skip to Quickstart.

Discord application

A Discord “application” is the parent object for a bot. It owns the token, the client ID, the OAuth scopes, and the assets (avatar, name, description). You create one through Discord’s developer portal.

Create the application

1. Open https://discord.com/developers/applications and sign in.
2. Click New Application in the top right.
3. Give it a name. This is the public name your bot will appear under in Discord, so pick something you are comfortable with. You can change it later.
4. Accept the developer terms and click Create.

You are now on the application’s General Information page. Two things on this page matter:

• The Application ID under the application name. Copy this and save it somewhere safe. This is your CLIENT_ID.
• (Optional) The icon and description, which become your bot’s profile in Discord. Set them now or later, it does not affect anything technical.

Get the bot token

1. In the left sidebar, click Bot.
2. Scroll to the Token section. If a token is already displayed, copy it. If not, click Reset Token and copy the new value.
3. Save it somewhere safe. This is your DISCORD_TOKEN.

The token is a password. Anyone who has it can control your bot. Do not commit it to git, do not paste it into chat, and do not share screenshots of it. The bot’s .env file (which you will create later) is gitignored specifically to keep this safe.

If you ever leak it, come back to this page and click Reset Token again. The old one stops working immediately.

Enable privileged intents

Still on the Bot page, scroll to Privileged Gateway Intents. Two intents must be on:

• Server Members Intent — required for member join events, which the auto-role and welcome features depend on.
• Message Content Intent — required for the AI chat feature, which reads the text of messages that @mention the bot, and for any prefix command (!m help, !m play, etc.) that needs to read what the user typed.

You can leave Presence Intent off; nothing in this bot uses it.

Click Save Changes at the bottom of the page.

Invite the bot to your server

The bot exists, but it is not in any server yet. You need to generate an OAuth invite URL.

1. In the left sidebar, click Installation (newer portals) or OAuth2 → URL Generator (older portals).
2. Under Scopes, check bot only. (The bot has no slash commands, so applications.commands isn’t required — checking it is harmless.)
3. Under Bot Permissions, check the permissions the features you plan to use require:
   • View Channels, Send Messages, Embed Links, Attach Files, Read Message History are needed for almost everything. Always include these.
   • Connect and Speak are needed for music.
   • Manage Roles is needed for auto-role, join role, donator sync, and chargeback alerts. The bot’s own role must also be ranked above any role it tries to assign.
   • Kick Members, Ban Members, and Moderate Members are needed for the moderation commands.
4. Copy the generated URL at the bottom of the page.
5. Paste it into your browser, pick the server you want the bot in, and click Authorize.

You can drop any of those permissions if you do not plan to use the corresponding feature. The bot will simply log a warning the first time a disabled feature tries and fails to do its job.

Get the GUILD_ID

The bot needs to know which Discord server is its primary one. That is the “guild ID.”

1. In Discord, open User Settings → Advanced and turn on Developer Mode.
2. In your server list, right-click the server you just invited the bot to and choose Copy Server ID.
3. Save it. This is your GUILD_ID.

Docker and Docker Compose

The bot ships as a set of Docker images. You need Docker Engine and the Compose plugin (Compose v2, invoked as docker compose, not the legacy docker-compose script).

• Linux: install from your distribution’s package manager, or run the convenience script at https://get.docker.com. Most distributions package the Compose plugin separately as docker-compose-plugin or docker-compose-v2.
• macOS or Windows: install Docker Desktop. Compose ships with it. On Windows, run everything from inside a WSL2 distribution; native PowerShell has not been tested.

Verify the install:

docker --version
docker compose version

Both commands should print a version. If docker compose version fails but docker-compose --version works, you have the legacy Python plugin. Install the v2 plugin and use docker compose (with a space) from then on.

A host to run on

Anything that runs Docker will run the bot. Concrete options:

• A Raspberry Pi 4 (4 GB or 8 GB) on your home network. Plenty for a single instance.
• A small VPS (1 vCPU, 2 GB RAM) from any provider. Hetzner, Vultr, and DigitalOcean all have suitable boxes for around five dollars a month.
• Your laptop, for testing. The bot does not care if it runs intermittently while you are developing.

Plan for about 5 GB of free disk for Docker images, the PostgreSQL volume, and any cached audio.

Optional external services

These are only required if you want the corresponding feature. All can be added later by editing your .env and restarting.

• DeepSeek API key — primary AI chat provider. Free credits on signup. Sign up at https://platform.deepseek.com/.
• Gemini API key — fallback AI chat provider, used automatically when DeepSeek errors. Free tier is generous. Get a key at https://aistudio.google.com/apikey.
• Finnhub API key — required for the virtual stock trading game. Free tier is enough. Sign up at https://finnhub.io/.
• Minecraft companion plugin — required only if you plan to use the Minecraft verification or donator sync features. See Minecraft: Verify.

If you are not sure whether you want a feature, leave its key blank and enable it later.

What you do NOT need

A few things people commonly ask about that you can ignore:

• An external PostgreSQL — the bundled docker-compose.yml includes one.
• A domain name or DNS records — the bot connects out to Discord; nothing needs to reach it from the public internet.
• A reverse proxy or TLS certificate — only relevant if you intend to expose the embedded MCP server to a network outside localhost. See MCP Exposure.
• A specific Linux distribution — anything that runs current Docker works.

Next step

Once you have your token, client ID, guild ID, and Docker installed, head to Quickstart.

Quickstart

This page is the fast path: about ten minutes from git clone to a running bot, assuming you have already gathered everything from Prerequisites. If you have not, do that first. If you want a slower walkthrough with more context, see First Bot Tutorial.

By the end of this page you will have a bot online in your Discord server, running locally in Docker, talking to a bundled PostgreSQL container.

Step 1: Clone the repo

git clone https://github.com/MrMcEpic/discord-bot-rs.git
cd discord-bot-rs

The repo is small (a few hundred kilobytes) and has no submodules.

Step 2: Create your instance directory

Each bot is configured by a directory under instances/. The example directory is the canonical reference and is also the directory the bundled docker-compose.yml points at by default. Copy it to a new name for your own bot:

cp -r instances/example instances/mybot
cp instances/mybot/.env.example instances/mybot/.env

mybot is just a label. Use whatever name you like. The name does not have to match the bot’s display name in Discord.

Step 3: Fill in .env

Open instances/mybot/.env in your editor of choice. The required fields are at the top:

DISCORD_TOKEN=...     # from the Discord developer portal (Bot page)
CLIENT_ID=...         # the application ID from General Information
GUILD_ID=...          # right-click your server in Discord, Copy Server ID

Paste in the values you saved during Prerequisites.

The next block is the database. If you are using the bundled PostgreSQL, the default works as-is:

DATABASE_URL=postgresql://discord_bot:discord_bot_pass@postgres:5432/discord_bot
DB_SCHEMA=mybot

Change DB_SCHEMA to match your instance name. Each instance gets its own PostgreSQL schema, so you can run several bots side by side without their data colliding.

If you want AI chat, paste in DEEPSEEK_API_KEY and/or GEMINI_API_KEY. If you want stock trading, paste in FINNHUB_API_KEY. Anything you leave blank just disables the corresponding feature.

One pair of values is mandatory for the bundled stack: MCP_AUTH_TOKEN inside the instance .env (read by the bot container) and MCP_GATEWAY_AUTH_TOKEN inside a .env at the repo root (read by Docker Compose and forwarded to the mcp-gateway service). The bot and gateway both refuse to start with an empty token on a non-loopback bind, and the gateway uses its token as the bearer when reaching the bot, so the two values must be identical. Generate one and install it in both places:

TOKEN=$(openssl rand -hex 32) && \
  sed -i.bak "s|^MCP_AUTH_TOKEN=.*|MCP_AUTH_TOKEN=$TOKEN|" instances/mybot/.env && \
  rm instances/mybot/.env.bak && \
  echo "MCP_GATEWAY_AUTH_TOKEN=$TOKEN" >> .env

See MCP Exposure for the security model.

Save the file. It is gitignored, so it will not end up in any commit you make.

Step 4: Review config.toml

Open instances/mybot/config.toml. The fields you most likely want to change are at the top:

bot_name = "My Bot"
command_prefix = "!"
personality_file = "personality.txt"

bot_name is what the bot calls itself in help text and welcome messages. command_prefix is the prefix for text-based commands (the default ! gives you !m help, !m play, etc.). discord-bot-rs uses prefix commands only — there are no slash commands.

Below that is a [features] block with feature flags:

[features]
minecraft = false
auto_role = false
join_role = false
welcome = false

Leave them all false for your first run. You can turn things on later once the bot is up. See Instance Config for what each flag does.

Step 5: Tweak personality.txt (optional)

instances/mybot/personality.txt is the system prompt for AI chat. The default is a starting template; you can customize tone and behavior here. If you are not sure what to put, skip this for now and try the defaults first. You can edit and restart the bot at any time.

Step 6: Start the stack

From the repo root:

INSTANCE_DIR=./instances/mybot docker compose up -d

The first run takes a few minutes because Docker has to build the bot image. Subsequent starts are seconds.

INSTANCE_DIR tells Compose which instance directory to mount into the container. If you skip the variable, it defaults to ./instances/example, which is fine for trying things out but you will want it pointing at your real instance long-term.

The stack starts three services:

• postgres — bundled PostgreSQL 17.
• bot — the Discord bot itself.
• mcp-gateway — a small HTTP router for the embedded MCP server (safe to ignore for now; see MCP Server when you are curious).

Step 7: Watch the logs

docker compose logs -f bot

You should see output that ends with something like:

INFO discord_bot::db: Database initialized (schema: example).
INFO discord_bot: Instance config loaded: Example Bot (prefix: !)
INFO discord_bot: Starting bot...
INFO discord_bot::events::ready: Example Bot is connected! (ID: ...)
INFO discord_bot::mcp: MCP server listening on 0.0.0.0:9090

Press Ctrl+C to stop tailing. The bot keeps running.

Step 8: Test it in Discord

Open your Discord server. The bot should appear in the member list with a green dot.

• Type !m help (or whatever prefix you set). You should see a list of commands. discord-bot-rs uses prefix commands only — there are no slash commands.
• @mention the bot in a channel. If you set an AI API key, it should reply. If you did not, the mention is ignored.

That is the minimum success criterion. For a more thorough check, run through Verifying Your Setup.

Troubleshooting

A few common failures and what to do about them.

The bot never comes online (no green dot in the member list).

The token is wrong, or the privileged intents are off. Check docker compose logs bot for an error like “Invalid Token” or “Disallowed intents.” Go back to Prerequisites and double-check both the token and the two privileged intents on the Bot page of the developer portal.

Postgres reports unhealthy in docker compose ps.

Run docker compose logs postgres. The most common cause is the disk being full or the PostgreSQL data volume being corrupted from an interrupted shutdown. docker compose down followed by docker compose up -d fixes most transient issues. If the volume is genuinely broken, docker volume rm discord-bot-rs_pgdata and start fresh (this destroys all bot data).

!m help does not get a reply.

Check that the bot has Read Messages, Send Messages, and Read Message History permission in that channel. Some channels inherit deny-by-default overrides that block bot replies. The bot needs Message Content Intent enabled in the Discord developer portal to read your prefix commands at all — if you forgot that during prerequisites, re-enable it and restart the bot.

The bot is online but @mentioning it does nothing.

AI chat needs at least one of DEEPSEEK_API_KEY or GEMINI_API_KEY in .env. If neither is set, AI chat is silently disabled. Set one, then restart with docker compose restart bot and watch the logs for any API errors on the next mention.

Next steps

Once your bot is up and replying:

• Verifying Your Setup — run through the post-deploy checklist.
• Features — see what each feature does and how to configure it.
• Production Checklist — when you are ready to leave it running long-term.

First Bot Tutorial

This page is the slow path. It walks through every step of getting a Discord bot running, with no assumptions about prior experience. If you have set up a Discord bot before, Quickstart is the short version of this same flow.

Who this tutorial is for

You have heard of Discord bots. You have not set one up yourself, you have not built a Rust project, and “Docker” is at most a vague impression. That is fine. By the end of this page you will have a real bot in a real Discord server, running on hardware you control. You will copy a few files, fill in a few blanks, and run a few commands.

What you will build

A Discord bot you fully own:

• Online in a server you control.
• Responds to !m help with a command list.
• Plays music in a voice channel with !m play <url>.
• Chats with you when you @mention it (if you provide an AI API key).
• Can play Wordle and other small games.
• Stores its data in a PostgreSQL database that runs alongside it.

The whole thing runs in Docker on one machine. There is no website to set up, no domain to buy, no public IP needed.

Section 1: Create the Discord application

Discord calls the parent object that owns a bot an “application.” Creating one takes a few clicks in their developer portal.

1. Open https://discord.com/developers/applications and log in with your normal Discord account.
2. Click New Application in the top right.
3. Give it a name (this becomes the bot’s display name; you can change it later), accept the terms, and click Create.

You are now on the General Information page.

Find the Application ID and copy it. Save it in a notes file labeled CLIENT_ID. You will need it later.

Get the bot token

The token is the secret password your code uses to log in as this bot.

1. Click Bot in the left sidebar.
2. In the Token section, click Copy (or Reset Token if no token is shown), and save the value as DISCORD_TOKEN.

Treat this string like a banking password. Do not paste it in chat, do not screenshot it, do not commit it to git. The configuration files you will create later are gitignored specifically so a slip of the keyboard cannot leak it. If you ever do leak it, click Reset Token again and the old token stops working immediately.

Turn on the privileged intents

Still on the Bot page, scroll to Privileged Gateway Intents.

Turn on Server Members Intent and Message Content Intent. Leave Presence Intent off. The bot needs Server Members so it can react to joins (welcome and auto-role features), and Message Content so it can read @mentions for AI chat and parse text commands like !m help.

Click Save Changes at the bottom.

Section 2: Invite the bot to your server

The application exists, but it is not in any server yet.

1. Click Installation in the sidebar (or OAuth2 → URL Generator on older portals).
2. Under Scopes, check bot. (applications.commands isn’t needed — the bot has no slash commands — but checking it is harmless if your workflow already includes it.)
3. Under Bot Permissions, check at minimum: View Channels, Send Messages, Embed Links, Attach Files, Read Message History, Connect, Speak, Manage Roles, Kick Members, Ban Members, Moderate Members. You can drop any of these later if you do not use the matching feature.
4. Copy the URL at the bottom, paste it into a new tab, choose your server (you must have Manage Server there), and click Authorize.

The bot now appears in your server’s member list with a grey dot. The dot turns green once you start the code.

Get the server ID

1. In Discord, open User Settings → Advanced and turn on Developer Mode.
2. Right-click your server icon and choose Copy Server ID.
3. Save it as GUILD_ID.

You should now have three values:

DISCORD_TOKEN=...
CLIENT_ID=...
GUILD_ID=...

Section 3: Install Docker

Docker runs the bot. The bot ships as a container so you do not have to install Rust, set up a database server, or worry about library versions.

Linux. Use the convenience script at https://get.docker.com, or your distribution’s packages: apt install docker.io docker-compose-v2 on Debian/Ubuntu, dnf install docker docker-compose on Fedora. Add yourself to the docker group with sudo usermod -aG docker $USER, then log out and back in.

macOS. Install Docker Desktop and launch it once after install.

Windows. Install Docker Desktop with the WSL2 backend, install a WSL2 Linux distribution from the Microsoft Store (Ubuntu is fine), and run all the commands in this tutorial from inside that distribution. Native PowerShell is technically possible but not worth the friction.

Verify in a terminal:

docker --version
docker compose version

Both should print a version.

Section 4: Clone and configure

Fetch the code:

git clone https://github.com/MrMcEpic/discord-bot-rs.git
cd discord-bot-rs

Make a copy of the example instance directory:

cp -r instances/example instances/mybot
cp instances/mybot/.env.example instances/mybot/.env

mybot is just a directory name. Pick whatever you like.

Open instances/mybot/.env in any text editor and paste in the three values you saved earlier:

DISCORD_TOKEN=...
CLIENT_ID=...
GUILD_ID=...

A few lines down, change DB_SCHEMA to match your instance name:

DB_SCHEMA=mybot

That is the minimum. Save the file.

Open instances/mybot/config.toml. The first few lines control identity:

bot_name = "My Bot"
command_prefix = "!"

Change bot_name to whatever you want shown in help text. Leave command_prefix as ! for now; the rest of the documentation assumes it. Save and close.

If you want AI chat, also paste a DEEPSEEK_API_KEY or GEMINI_API_KEY into .env. Both are free to start with — see Prerequisites for signup links. You can add them later.

One last required step: generate an MCP auth token. The bundled stack won’t start without one, because the embedded MCP server and the mcp-gateway sidecar both refuse to run without a shared secret set. Generate one random value and install it in two places: MCP_AUTH_TOKEN in instances/mybot/.env (the bot reads it) and MCP_GATEWAY_AUTH_TOKEN in a new .env at the repo root (Docker Compose reads it and feeds it to the gateway). Both must hold the same value — the gateway uses it as the bearer when reaching the bot, so a mismatch locks the two out of each other:

TOKEN=$(openssl rand -hex 32) && \
  sed -i.bak "s|^MCP_AUTH_TOKEN=.*|MCP_AUTH_TOKEN=$TOKEN|" instances/mybot/.env && \
  rm instances/mybot/.env.bak && \
  echo "MCP_GATEWAY_AUTH_TOKEN=$TOKEN" >> .env

If you prefer editing by hand, run openssl rand -hex 32, copy the output, paste it after MCP_AUTH_TOKEN= in instances/mybot/.env, and add a single line MCP_GATEWAY_AUTH_TOKEN=<paste> to a new file called .env at the repo root (next to docker-compose.yml).

Section 5: First run

Start the stack:

INSTANCE_DIR=./instances/mybot docker compose up -d

The first run takes a few minutes because Docker has to download PostgreSQL and build the bot from source. Once it finishes, you get your shell prompt back.

Tail the logs:

docker compose logs -f bot

You will see, roughly in order:

1. Postgres starting up and reporting it is ready to accept connections.
2. The bot connecting to Postgres and creating its schema (“Database initialized (schema: mybot)”).
3. The bot loading its instance config (“Instance config loaded: My Bot (prefix: !)”).
4. The bot connecting to Discord (“Starting bot…” → shard running → “My Bot is connected! (ID: …)”).
5. The MCP server binding to port 9090. From here on the bot is online.

Press Ctrl+C to stop tailing. The bot keeps running. To stop everything, run docker compose down from the repo root.

Section 6: Test it

Open Discord. Your bot should now have a green dot in the member list.

In any channel the bot can see, type:

!m help

You should get a help embed listing the available commands. discord-bot-rs uses prefix commands only — there are no slash commands — so !m help is how you discover everything.

Section 7: What to try next

Now that the bot works, here are some things to play with.

• Customize the personality. Edit instances/mybot/personality.txt and put whatever you want the bot’s voice to be. Restart with docker compose restart bot.
• Try AI chat. With an API key set, @mention the bot and ask it something. It will reply in the personality you defined.
• Try music. Join a voice channel, then run !m play <YouTube URL> in any text channel. !m skip skips, !m queue shows the queue.
• Try Wordle. Run !m wordle in a channel.
• Read Features to see everything the bot can do and how to enable the optional pieces.

Section 8: Common first-time mistakes

If something is not working, the issue is almost always one of these.

Bot stays grey (offline) and never goes green. The token is wrong, the privileged intents are off, or both. Check docker compose logs bot — “Invalid Token” means reset the token and paste the new value; “Disallowed intents” means go back to the Bot page in the portal and verify both Server Members Intent and Message Content Intent are enabled.

!m help returns nothing. The bot needs Message Content Intent enabled in the Discord developer portal to read prefix commands. If you skipped that in Section 1, re-enable it and restart the bot with docker compose restart bot. Also check that the bot has permission to read and send messages in the channel you are typing in.

Bot replies to !m help but not to @mentions. AI chat is disabled because no API key is set. Add DEEPSEEK_API_KEY or GEMINI_API_KEY to .env, then docker compose restart bot.

Postgres keeps restarting. Run docker compose logs postgres. Usually this is a disk space issue or a corrupted volume from an unclean shutdown. docker compose down followed by docker compose up -d resolves most transient issues.

The first build hangs or fails. The Rust build downloads many crates and compiles for several minutes. If your machine has very little RAM (under 2 GB), the build may run out of memory. The smallest VPS that reliably builds the project is 2 GB RAM with at least 2 GB of swap.

If none of these apply, run through Verifying Your Setup for a more thorough diagnostic, or open an issue on GitHub.

Verifying Your Setup

Once you have run docker compose up -d and the logs look reasonable, this page is the post-deploy checklist. Run through it once. If every command matches its expected output, your bot is healthy. If something is off, the bottom of the page points at what to read next.

All commands assume you are in the repo root.

Docker-level checks

The containers should all be running and healthy.

docker compose ps

You should see three services: postgres, bot, and mcp-gateway. Each should report running in the STATUS column. postgres and bot also report healthy once their healthchecks settle (a few seconds for postgres, up to a minute for the bot the first time).

If any service is restarting, look at its logs to find out why.

Next, the bot’s recent logs:

docker compose logs bot --tail 20

A healthy startup ends with a sequence like this, in roughly this order:

INFO discord_bot::db: Database initialized (schema: example).
INFO discord_bot: Instance config loaded: Example Bot (prefix: !)
INFO discord_bot: Starting bot...
INFO serenity::gateway::bridge::shard_runner: [ShardRunner ShardInfo { id: ShardId(0), total: 1 }] Running
INFO discord_bot::events::ready: Example Bot is connected! (ID: 123456789012345678)
INFO discord_bot::mcp: MCP server listening on 0.0.0.0:9090

Exact wording can shift slightly between releases, but you should see the database schema initialize, the instance config load, a shard enter Running, a line stating that the bot “is connected” along with its user ID, and the MCP server bind to port 9090. If the last log line is hours old and there is nothing about errors, the bot is sitting idle. That is fine.

And postgres:

docker compose logs postgres --tail 5

You should see database system is ready to accept connections.

Discord-level checks

Open Discord. The bot should appear in your server’s member list with a green dot. A grey dot means the bot is not running or cannot reach Discord; the Docker-level checks above will tell you which.

Try a prefix command in any channel the bot can see:

!m help

You should get a help embed immediately. If your config.toml sets a different prefix, use that instead. discord-bot-rs uses prefix commands only — there are no slash commands to sync.

If you configured an AI API key, @mention the bot and ask it something. You should get a reply within a few seconds. If you did not configure an AI key, mentions are silently ignored — that is expected, not a bug.

Database-level checks

The bot uses one PostgreSQL database with a separate schema per instance. Confirm your instance’s schema exists:

docker compose exec postgres psql -U discord_bot -d discord_bot -c '\dn'

You should see at least one schema beyond the built-in public, information_schema, and pg_* schemas. The name should match your instance’s DB_SCHEMA from .env.

If the schema is missing, the bot did not finish its first migration — check docker compose logs bot for migration errors.

MCP-level checks

If you have not exposed the MCP port (the default), this section does not apply. The MCP server inside the bot still runs, but it is only reachable from inside the Docker network.

If you have mapped the port to your host, confirm it responds:

curl -i http://localhost:9090/mcp

You should get an HTTP response. The exact body depends on whether you configured authentication; the important thing is that you get a response rather than a connection refused. See MCP Exposure for how to expose it safely.

What “good” looks like

A healthy bot has all of the following true at the same time:

• All Compose services report running, and postgres and bot report healthy.
• The bot’s recent logs contain a “is connected! (ID: …)” line and have no errors.
• The bot has a green dot in your Discord server.
• !m help replies when invoked in a channel the bot can read.
• Your instance’s PostgreSQL schema exists.

If those five things are true, you are done. From here, treat any future log errors as the diagnostic signal — the bot logs to stdout, which Compose captures and docker compose logs reads.

What to do if something fails

If any of the checks above fail, two pages have most of the answers:

• Monitoring covers reading logs, watching healthchecks, and what each service’s failure modes look like.
• FAQ collects the issues that come up repeatedly.

If neither helps, open an issue on https://github.com/MrMcEpic/discord-bot-rs with the output of docker compose ps and the last 50 lines of docker compose logs bot.

Configuration

discord-bot-rs splits its configuration across three files per instance, each with a clear job. Once you understand the split, every other page in this section is just filling in the field-by-field detail.

The three-file model

Every instance lives in its own directory under instances/ and contains the same three files:

• .env holds secrets and runtime connection details: the Discord token, the database URL, AI provider API keys, and the schema name. It is loaded by dotenvy at startup and exists only on the host (and inside the container at runtime).
• config.toml holds the bot’s identity and feature surface: its display name, command prefix, which feature modules are enabled, and the IDs/settings each feature needs (role IDs, channel IDs, intervals). This file is checked in as part of your fork and versioned alongside the rest of the repo.
• personality.txt holds the free-form prose that becomes the system prompt for AI chat. It is plain text — no escaping, no structure — so editing it feels like editing a doc, not a config file.

Why the split

Mixing secrets and structured config in one file is a recipe for accidentally committing tokens. Splitting them lets each format do what it does best.

.env is gitignored at the repo root, so secrets stay out of git history by default. Rotating a key is one line edit and a restart, with no risk of touching feature settings. config.toml is the opposite: checked in, typed, and reviewable in pull requests, so changes to feature behavior are visible and traceable. personality.txt is plain prose because system prompts are prose — putting them inside TOML would mean wrestling with multiline string escapes every time you wanted to tweak a sentence.

What lives where

How the files are loaded

At startup the bot does the following, in order:

1. Calls dotenvy::dotenv() to read the .env file from the current working directory, exporting each key into the process environment. This populates DISCORD_TOKEN, DATABASE_URL, and friends.
2. Determines CONFIG_DIR from the environment, defaulting to . (the current directory). Inside the Docker image this is set to /config, which Docker Compose mounts from the instance directory on the host.
3. Reads config.toml from CONFIG_DIR and parses it into the InstanceConfig struct. Failures here panic with a clear error pointing at the file.
4. Reads personality.txt (or whatever personality_file is set to) from CONFIG_DIR. An empty or missing file panics; the AI chat module needs a non-empty system prompt.
5. Logs the loaded bot_name, command prefix, and which feature modules are enabled, then connects to Discord and Postgres.

The mapping is mechanical: one instance directory on the host becomes /config inside the container, and everything the bot needs is in that directory. Nothing else is read.

Configuration is per-instance

Each bot you run is a separate instance with its own .env, config.toml, and personality.txt. They share a Postgres database (with schema-level isolation per instance) and, optionally, a single MCP gateway, but otherwise they are wholly independent processes. See Multiple Instances for the multi-bot recipe and Multi-Instance Model for the architectural picture.

Where to next

• Environment Variables — the canonical reference for every variable the bot reads from .env.
• Instance Config — the canonical reference for every field in config.toml.
• Personality Files — how to write a system prompt that does what you want.
• Secrets Management — keeping .env out of git, rotating tokens, and what to do if a secret leaks.
• Multiple Instances — running more than one bot from a single repo and database.

Environment Variables

This page is the canonical reference for every environment variable the bot reads. The source of truth is Config::load() in src/config.rs; if you find a variable in the code that isn’t on this page, please open an issue.

Overview

The bot reads its environment from two places:

1. A .env file in the current working directory, parsed at startup by dotenvy. The file is plain KEY=VALUE lines; comments start with #. Empty values are treated as if the variable were unset for every optional key here, so DEEPSEEK_API_KEY= means “no DeepSeek key.”
2. The process environment itself. Anything Docker Compose passes via env_file or an environment: block also works, and overrides the same key in the file.

Inside Docker Compose the standard pattern is env_file: instances/yourbot/.env, which loads the file once when the container starts. There is no live reload — changing a value requires restarting the container.

The variables fall into seven groups: Discord core (required), database (required), AI providers (optional), Finnhub (optional), Minecraft (optional), the embedded MCP server (optional), and the MCP gateway (optional, only used by the gateway service).

Discord core (required)

All three are validated at startup. If any is missing the bot panics with <KEY> must be set in .env. There is also a placeholder check: if a value still starts with the literal string your- (as in the shipped .env.example), the bot panics with a hint that you forgot to fill it in.

DISCORD_TOKEN

Created in the Discord Developer Portal under your application’s Bot page. Format is MTxxxxxxxxxxxxxxxxxxxxx.G_xxxxxxxxxxxxxxxxxxxxxxxxxxx or similar — there is no fixed length, but if it doesn’t start with the right prefix Discord will reject it. Treat this like a password: it grants full control over the bot user. See Secrets Management for rotation.

CLIENT_ID

The application’s snowflake ID, also from the Developer Portal (top of the General Information page). The bot uses this for command registration. It is not a secret in the same way the token is — leaking it doesn’t compromise the bot — but you should still keep it with the rest of your config.

GUILD_ID

The snowflake of the Discord server this instance manages. The bot uses this as the default guild for its MCP tools, event handling, and auto-role checks. Right-click your server icon in Discord with Developer Mode enabled to copy it.

Database (required)

DATABASE_URL

Standard postgresql://user:password@host:port/database connection string, parsed by sqlx. The default points at the bundled Compose service; if you’re using docker-compose.yml from this repo as-is, keeping it pointed at postgres:5432 (the service name on the Compose network) works. Outside Docker, point it at wherever your Postgres lives.

The default is technically a fallback rather than a hard requirement — the loader uses it if the variable is unset. But you should always set it explicitly so that misconfigurations fail loudly instead of silently connecting to a fictional localhost:5432.

DB_SCHEMA

The Postgres schema name this instance owns. The default is public, but for any real deployment you should set this to a unique value per instance — mybot1, mybot2, and so on. At connection time the bot runs SET search_path TO "<schema>" on every new pool connection (see src/db/mod.rs), so all queries land in that schema and instances can’t see each other’s tables. See Multiple Instances and Multi-Instance Model for the full picture.

AI providers (optional)

All three are independently optional. If DEEPSEEK_API_KEY and GEMINI_API_KEY are both unset the AI chat feature is disabled — mention the bot and you’ll get nothing back. If only one is set it is used. If both are set the bot uses DeepSeek as primary text and Gemini for image vision. GROK_API_KEY is only used when an instance opts into the CENSORED cascade via [ai.fallback] in its config.toml. Empty strings (DEEPSEEK_API_KEY=) are normalized to “unset.”

Custom providers may name any env var. The api_key_env field of an [ai.providers.<name>] block in instance config.toml names the env var the bot will read for that provider’s bearer token. The default-registry providers’ api_key_env values map to the env vars listed above. See AI Providers for the schema and worked examples (custom env-var names, multiple providers, etc.).

DEEPSEEK_API_KEY

Get one at platform.deepseek.com. DeepSeek’s chat models are the cheapest of the supported providers and are recommended as the primary. See the AI Chat feature page for model selection details.

GEMINI_API_KEY

Get one in Google AI Studio. Used as the vision provider when image attachments are present in the prompt or replied-to message. Also valid as a CENSORED-cascade fallback if listed in [ai.fallback].

GROK_API_KEY

Get one at console.x.ai. Optional; needed only if an instance lists "grok" in its [ai.fallback] on_censored config. Grok is a less-restrictive alternative the bot can replay a refused conversation through when DeepSeek hits its content-moderation block. See the AI Chat feature page for the cascade story.

Finnhub (optional)

Required only if you use the virtual stock trading game. Free tier keys are available at finnhub.io and have generous limits. If unset, stocks-related commands return a not-configured message.

Minecraft integration (optional)

These are unset by default; the bot only needs them when features.minecraft = true in config.toml and at least one Minecraft sub-feature (verify, donator_sync, chargeback) is enabled. The companion plugin lives on the Minecraft server and exposes verification and donator-tier endpoints; both URL and secret are required for any of those calls to work.

See Minecraft Verify, Minecraft Donator Sync, and Minecraft Chargeback.

MCP server (optional)

The bot embeds a Model Context Protocol server so external tools can drive Discord operations programmatically. These three variables control where it listens and how it authenticates.

MCP_PORT

The port the in-process MCP server binds to. Must be a number; an unparseable value panics at startup. Default 9090 is fine for a single-instance setup. When running multiple instances on the same host you can either keep all internal ports the same and let Docker isolate them, or assign different host ports if you expose them.

MCP_BIND_ADDR

The address to bind to. Two defaults are in play here, and the difference matters:

• Config::load() fallback (no value set anywhere): 127.0.0.1. Loopback only.
• Shipped instances/example/.env.example: 0.0.0.0. The bundled Compose stack has the mcp-gateway sidecar reach the bot over the Docker bridge network at http://bot:9090, which requires the bot to bind on a non-loopback interface inside its own container.

Pick based on shape:

• Single-host, no gateway, you only want loopback access: set MCP_BIND_ADDR=127.0.0.1 (or simply unset it and let the fallback apply).
• Bundled Docker Compose with the gateway sidecar: keep MCP_BIND_ADDR=0.0.0.0 from the example. Each bot lives in its own container, so “all interfaces” means “the container’s interface on the Compose bridge network” — not the host’s public IP. Pair this with MCP_AUTH_TOKEN; the bot now refuses to start without one (see below).

See MCP Exposure for the threat model and the deploy shapes in detail.

MCP_AUTH_TOKEN

Bearer token required on all MCP requests. The default is an empty string, which disables auth entirely.

This is now a hard startup requirement when MCP_BIND_ADDR is anything other than a loopback address. If MCP_AUTH_TOKEN is empty and the bind address is non-loopback, the bot logs an error and refuses to start. The check is in src/mcp/mod.rs. The intent is to prevent the easy mistake of binding 0.0.0.0 for a Compose deploy and forgetting to set a token — which would otherwise hand programmatic control of the bot to anyone who could reach the port.

Loopback binds with no token are still allowed (and are the right answer for a single-host bot with no gateway). Comparison against the configured token is constant-time (via the subtle crate) so the auth path doesn’t leak token contents through timing.

See MCP Exposure for the full security model and the two deploy shapes.

MCP gateway (optional)

This variable is read by the separate mcp-gateway service in docker-compose.yml, not by the bot binary itself. It is the token that external MCP clients (Claude Code, etc.) present when calling the gateway, which then proxies the request to the appropriate per-instance MCP server. See MCP Gateway Routing.

The gateway always binds non-loopback and treats this token as mandatory. If MCP_GATEWAY_AUTH_TOKEN is empty the gateway refuses to start at all — there is no loopback escape hatch like the bot has, because the gateway’s whole job is to be reachable from outside its container.

The same value must be set as each bot’s MCP_AUTH_TOKEN. The gateway uses MCP_GATEWAY_AUTH_TOKEN for both inbound auth (checking client bearers) and outbound auth (as the Authorization: Bearer header it forwards to every backend bot). A bot with a different MCP_AUTH_TOKEN will 401 the gateway at startup. Generate one secret with openssl rand -hex 32 and use it in both the gateway environment and every bot’s .env.

A note on placeholder detection

Config::load() rejects any required variable whose value still starts with the literal string your- — for example, DISCORD_TOKEN=your-discord-bot-token. This catches the easy mistake of copying .env.example to .env and forgetting to actually fill it in. If you see <KEY> has placeholder value — set it in .env at startup, that’s the check firing.

Instance Config (config.toml)

config.toml describes a bot instance’s identity, command surface, and feature configuration. Every field on this page comes from the InstanceConfig, Features, AutoRoleConfig, JoinRoleConfig, WelcomeConfig, MinecraftConfig, DonatorSyncConfig, and ChargebackConfig structs in src/instance_config.rs. If you find a field in the source that isn’t documented here, please open an issue.

The file is read once at startup from CONFIG_DIR/config.toml (where CONFIG_DIR defaults to the working directory and is /config inside the Docker image). Parse failures panic with a path and the underlying TOML error — you’ll see them immediately when the container starts.

Top-level fields

bot_name

The human-readable name of this instance. It is used in help output, in welcome messages where templates reference it, and in startup log lines so you can tell which instance you’re looking at when you tail several at once.

command_prefix

The prefix the bot listens for on text commands. The repo ships with "!" in the example, but you can use anything that won’t collide with normal chat. discord-bot-rs uses prefix commands only — there are no slash commands — so this setting controls how users invoke every command.

command_root

The name of the parent command that wraps every subcommand. Default "m" gives users the historical form <prefix>m <subcommand> (e.g. !m play). Three modes:

The renamed-parent mode is useful when you run multiple bot instances in the same Discord guild — give each one a distinct command_root so users can address them unambiguously even when they share command_prefix. The flat mode is useful for single-bot servers where the prefix alone is enough discriminator.

Validation: must be a single token. Whitespace is rejected at startup with a clear error pointing back at this field.

The bot pre-renders the full command-invocation string (<prefix><root> for the rename case, <prefix> for the flat case) and uses it everywhere the help output prints example commands, so the help embed and the bot’s Discord activity status (Playing <prefix>help or @ me) both stay consistent across all three modes.

Note: the rest of these docs (and the README) use !m play / !m skip / etc. as their command examples, since ! is the default command_prefix and m is the default command_root. If you’ve customized either field, mentally substitute your values when reading them — !m play → <your-prefix><your-root> play. The bot itself always shows the right form at runtime, so this only affects reading the docs.

personality_file

The filename (relative to the same directory as config.toml) where the AI system prompt lives. Defaults to personality.txt. The file must exist and must not be empty when AI chat is active — the loader panics if either condition fails. See Personality Files for how to write one.

timezone

Optional IANA timezone name (for example "America/Toronto", "Europe/London", "Asia/Tokyo") used to build the “current date / time” line in the AI system prompt. When this field is set, the bot formats the line as the local date, local clock time, IANA zone, and numeric UTC offset — for example:

Today is Friday, April 17, 2026. Current local time: 10:52 PM (America/Toronto, UTC-04:00).

When the field is absent, the bot falls back to UTC and explicitly labels the line as UTC so the AI model doesn’t guess at a timezone. The bare-UTC fallback is safe for non-chat workloads but is typically wrong for conversation: at 10:52 PM local in most of the Americas, UTC has already rolled over to the next day, and without a timezone label the model will happily report “today” as tomorrow’s date (and sometimes invent a plausible-sounding city to justify it).

Accepted values are any zone name chrono-tz can parse. Prefer full IANA zone names like "America/New_York", "America/Los_Angeles", or "Europe/Paris" over bare abbreviations like "EST", "PST", or "CET" — the abbreviations parse as fixed offsets with no daylight saving, so a config that says "EST" will report the wrong time for half the year. A value chrono-tz can’t parse makes the bot panic at startup with the offending string, so misconfiguration fails loudly rather than silently defaulting.

[features] section

The features table holds the master feature flags. Every flag defaults to false, so an empty [features] section (or no section at all) means a stripped-down bot that only does AI chat, music, games, and the always-on commands.

Setting a flag to false disables the entire feature area; the corresponding sub-section ([auto_role], [minecraft], etc.) is not required and will be ignored if present. Setting a flag to true activates the loader for the matching sub-section. If the sub-section is missing the bot logs a warning at startup and disables the feature anyway, rather than panicking — see Validation below.

[auto_role] section

Required when features.auto_role = true. The auto-role module periodically scans members who currently have from_role and grants them to_role (and removes from_role) once they meet the configured criteria. The first scan runs at bot startup; subsequent scans run on a fixed schedule.

Duration format for min_age

min_age is a short duration string parsed by parse_duration in src/util/duration.rs. The grammar is <integer><unit> with no spaces, where unit is one of:

Combined units (1d12h) are not supported — pick the largest unit that expresses what you want. The maximum allowed duration is 365 days; anything longer is rejected.

How the criteria combine

With require_all = false (the default), a member is promoted as soon as either condition holds: they’ve been in the guild long enough, or they’ve sent enough messages. With require_all = true, both must hold. Newly added IDs and recent message counts are picked up between scans, so the lag between meeting the threshold and getting promoted is bounded by the scan interval.

See Auto-Role for behavioral details.

[join_role] section

Required when features.join_role = true. Assigns a single role to every new member on join. Most often used to mark unverified accounts that haven’t gone through whatever onboarding flow your server has set up.

See Join Features.

[welcome] section

Required when features.welcome = true. Posts an AI-generated welcome message to a designated channel when a new member joins. The bot needs at least one AI provider key (DEEPSEEK_API_KEY or GEMINI_API_KEY); without one, it logs a warning at startup and the feature stays inactive.

The prompt file is loaded by load_welcome_prompt in src/instance_config.rs; if it’s missing or empty the bot logs a warning and welcome stays off. See Join Features.

[minecraft] section

Required when features.minecraft = true. The Minecraft module is itself a bundle of three independently toggleable sub-features. All three depend on the bot being able to talk to a companion plugin on the Minecraft server, which means MC_VERIFY_URL and MC_VERIFY_SECRET must be set in the instance’s .env.

verify defaults to true so that the most common case (you want player-account linking) needs no extra configuration beyond enabling the module. donator_sync and chargeback default to false and need their own sub-sections (below) before they do anything useful.

See Minecraft Verify, Minecraft Donator Sync, and Minecraft Chargeback.

[minecraft.donator_sync_config] section

Required when minecraft.donator_sync = true. Polls the Minecraft server on an interval and synchronizes Discord roles to match each user’s purchased tier.

The default 300-second interval is conservative enough to avoid spamming the MC server while keeping role state reasonably fresh. See Minecraft Donator Sync.

[minecraft.chargeback_config] section

Required when minecraft.chargeback = true. The bot exposes an HTTP endpoint that receives chargeback notifications from the MC store; on receipt it strips the user’s roles, applies a restricted role, and posts an interactive alert to a staff channel with Ban and Dismiss buttons.

See Minecraft Chargeback.

Validation

At startup the loader inspects each enabled feature flag and tries to find its sub-section:

• TOML parse errors panic with the file path and the parser’s error message. Fix the syntax and restart.
• Missing bot_name or command_prefix is a TOML parse error (they’re required fields with no default), so they fall into the same case.
• Missing personality file when AI chat is implicitly active panics with the file path. An empty file panics with a different message asking you to fill it in.
• features.minecraft = true with no [minecraft] section logs a warning and disables the Minecraft module. The bot still starts.
• features.auto_role = true with no [auto_role] section logs a warning and disables auto-role. The bot still starts.
• features.join_role = true with no [join_role] section logs a warning and disables join-role. The bot still starts.
• features.welcome = true with no [welcome] section, no prompt file, or an empty prompt file logs a warning and disables welcomes. The bot still starts.
• minecraft.donator_sync = true with no [minecraft.donator_sync_config] logs a warning and disables donator sync.
• minecraft.chargeback = true with no [minecraft.chargeback_config] logs a warning and disables chargeback.

Validation strategy is “loud warnings, soft fail”: misconfiguration of optional features doesn’t crash the bot, but it does show up clearly in the logs. Run with RUST_LOG=info,discord_bot=info (or similar) to see the per-module enable/disable lines on startup.

AI Provider Configuration ([ai.providers] and [ai.routing])

Define custom AI providers and override role routing per-instance. Both sections are optional — when absent, the bot uses a baked-in default registry equivalent to all releases prior to 0.15.0.

See AI Providers for the full schema reference, default registry contents, validation rules, and worked examples (one-model setup, three-provider setup with cascade, overriding a default).

Complete annotated example

The example instance ships with this config.toml (also at instances/example/config.toml in the repo):

# ============================================================================
# discord-bot-rs — Example Instance Configuration
# ============================================================================
#
# This file is the authoritative reference for every config.toml option.
# Copy this whole directory to create a new instance:
#
#     cp -r instances/example instances/mybot
#
# Then edit this file, instances/mybot/.env, and instances/mybot/personality.txt.
# ============================================================================


# ----- Identity -------------------------------------------------------------

# Display name shown in bot output (help text, welcome messages, etc.)
bot_name = "Example Bot"

# Prefix for all user commands. discord-bot-rs uses prefix commands only
# (no slash commands), so this is the single prefix every user sees.
command_prefix = "!"

# Path to the personality file (system prompt for AI chat), relative to this
# config file. Default: "personality.txt"
personality_file = "personality.txt"


# ----- Feature Flags --------------------------------------------------------
#
# Each flag gates a whole feature area. Setting to false disables the feature
# entirely — the corresponding config section below is not required.

[features]
minecraft = false     # Minecraft verification + donator sync + chargeback alerts
auto_role = false     # Automatic role promotion based on activity
join_role = false     # Assign a role to new members on join
welcome = false       # AI-generated welcome message on join


# ----- Auto-Role Promotion --------------------------------------------------
#
# Required when features.auto_role = true.
# Promotes members from `from_role` to `to_role` once they meet activity
# criteria. Runs periodically; the first pass happens at bot startup.

# [auto_role]
# from_role = "ROLE_ID"       # Snowflake of the role to remove
# to_role = "ROLE_ID"         # Snowflake of the role to grant
# min_age = "3d"              # Time in guild before eligible (e.g. "1h", "3d", "1w")
# min_messages = 20           # Messages sent in the guild before eligible
# require_all = false         # true = both criteria required, false = either


# ----- Join Role ------------------------------------------------------------
#
# Required when features.join_role = true.

# [join_role]
# role = "ROLE_ID"            # Snowflake of the role to grant on join


# ----- Welcome Messages -----------------------------------------------------
#
# Required when features.welcome = true.

# [welcome]
# channel = "CHANNEL_ID"
# prompt_file = "welcome_prompt.txt"   # Relative to this config file


# ----- Minecraft Module -----------------------------------------------------
#
# Required when features.minecraft = true.
# Any sub-feature can be independently toggled.
# MC_VERIFY_URL and MC_VERIFY_SECRET in .env are required for all sub-features.

# [minecraft]
# verify = true               # !m verify command (default: true)
# donator_sync = false        # Poll MC server for donator tier role sync
# chargeback = false          # Webhook listener for chargeback alerts


# ----- Donator Sync ---------------------------------------------------------
#
# Required when minecraft.donator_sync = true.

# [minecraft.donator_sync_config]
# supporter_role = "ROLE_ID"
# premium_role = "ROLE_ID"
# check_interval = 300        # Poll interval in seconds (default: 300)


# ----- Chargeback Alerts ----------------------------------------------------
#
# Required when minecraft.chargeback = true.

# [minecraft.chargeback_config]
# staff_channel = "CHANNEL_ID"
# restricted_role = "ROLE_ID"
# staff_roles = ["MOD_ROLE_ID", "ADMIN_ROLE_ID", "OWNER_ROLE_ID"]   # Snowflakes allowed to press Ban/Dismiss; empty = no one

To turn any feature on, flip its flag in [features] and uncomment the matching sub-section, replacing ROLE_ID and CHANNEL_ID placeholders with real Discord snowflakes (right-click → Copy ID with Developer Mode enabled).

AI Providers

This page documents the [ai.providers], [ai.routing], and [ai.fallback] sections of an instance’s config.toml. All three are optional — an instance with no [ai.*] section uses a sensible default stack (DeepSeek for chat, Gemini for vision, DeepSeek Reasoner for hard questions, no CENSORED cascade).

Quick reference

# instances/<your-bot>/config.toml

[ai.providers.<name>]
url = "https://..."           # required: full chat-completions endpoint
model = "..."                 # required: model identifier
api_key_env = "..."           # required: name of env var holding the bearer token
max_tokens = 8192             # required: per-provider hard cap on response tokens
timeout_secs = 30             # optional, default 30
supports_vision = false       # optional, default false
supports_tools = true         # optional, default true
is_reasoner = false           # optional, default false
spec = "openai"               # optional, default "openai"

[ai.routing]
chat = "<provider-name>"      # required if section present
vision = "<provider-name>"    # optional — if omitted, image messages fall through to chat
reasoner = "<provider-name>"  # optional — if omitted, classifier step is skipped

[ai.fallback]
on_censored = ["<name>", "..."]  # CENSORED-cascade chain (optional)

Default registry

When [ai.providers] is absent, the bot ships these four definitions:

A provider whose api_key_env resolves to an unset/empty env var is “unavailable” — defined but not usable. The bot starts and runs without it; AI features that depend on it are silently disabled (with a warning at startup if anything references it).

Default routing

When [ai.routing] is absent:

chat = "deepseek_chat"
vision = "gemini_flash"
reasoner = "deepseek_reasoner"

This is exactly the routing behaviour of every release before 0.15.0. Existing instances pick it up automatically with no config changes.

Routing degradation rules

When [ai.routing] IS present, only the keys you write take effect. There’s no field-merge with the defaults above. Specifically:

This lets you write a one-model config:

[ai.providers.my_local]
url = "http://localhost:11434/v1/chat/completions"
model = "llama3.1:70b"
api_key_env = "LOCAL_LLM_KEY"
max_tokens = 8192

[ai.routing]
chat = "my_local"
# vision and reasoner omitted → graceful degrade

Disabling V4-Pro flagship

deepseek_reasoner defaults to DeepSeek V4-Pro (the 1.6T-parameter flagship). V4-Pro output costs roughly 12× V4-Flash output per token, so high-volume reasoner traffic adds up quickly. The existing routing system already provides the off-switch — no per-feature boolean is needed.

To skip V4-Pro entirely without redefining a provider, point the reasoner role at the cheaper V4-Flash:

[ai.routing]
reasoner = "deepseek_chat"

To disable the reasoner role altogether — the bot will never invoke a reasoner provider, and every chat goes through the chat role — set [ai.routing] and omit reasoner:

[ai.routing]
chat = "deepseek_chat"
vision = "gemini_flash"
# reasoner intentionally omitted — graceful degrade

Either pattern leaves V4-Pro unconfigured by routing and unbilled by DeepSeek.

Provider definitions

Each [ai.providers.<name>] block is independent. The <name> is your handle for the provider — used in [ai.routing] lookups, in [ai.fallback] on_censored lists, and in log lines.

Required fields

• url — full HTTPS endpoint (the chat-completions URL, including any version path).
• model — model identifier the provider expects in the request body.
• api_key_env — name of an environment variable. The bot reads std::env::var(api_key_env) at startup; an unset/empty value marks the provider unavailable.
• max_tokens — per-provider hard cap on response tokens. The orchestration layer asks for whatever budget it wants and clamps to this cap.

Optional fields

• timeout_secs (default 30) — HTTP timeout for chat-completions calls. DeepSeek Reasoner needs 300 (5 minutes); fast chat models are fine with the default.
• supports_vision (default false) — whether the model accepts image content parts. Today only the Gemini default registry entry sets this to true.
• supports_tools (default true) — whether the model accepts a tools array. DeepSeek Reasoner is the standout exception (set to false).
• is_reasoner (default false) — flags a slow reasoning model. The orchestration layer uses this signal alongside the longer timeout_secs budget you should also set.
• spec (default "openai") — request/response shape. "openai" (default) and "anthropic" (added in 0.16.0) are supported. See Anthropic spec for details.

Provider name rules

• Non-empty after .trim()
• No internal whitespace characters
• TOML’s bare-key rules already constrain [ai.providers.<name>] syntax to safe characters (alphanumeric, underscore, hyphen, dot)
• A user-defined name that matches a default-registry name (e.g. gemini_flash) fully replaces the default — no field-level merge

Backward-compatible alias names

For instance configs that pin model-string aliases instead of canonical provider names, the bot recognises a small set of short aliases at lookup time. They were introduced in two waves:

These aliases work in [ai.fallback] on_censored and in any other place the bot looks up a provider by name at request time. They are not accepted by [ai.routing] startup validation — using [ai.routing] chat = "gemini" panics at startup with the canonical name (gemini_flash) in the error message.

The 0.14.0 aliases exist so a [ai.fallback] on_censored = ["grok", "gemini"] line copied from a 0.14.0 example doesn’t silently produce an empty cascade. The 0.18.0 aliases preserve [ai.fallback] configs that named DeepSeek’s deepseek-reasoner (retiring 2026-07-24) and add forward-compatible spellings for the explicit V4 model names.

New configs should use the canonical names (deepseek_chat, deepseek_reasoner, gemini_flash, grok).

Anthropic spec

As of 0.16.0, spec = "anthropic" enables native Anthropic /v1/messages routing. This is useful for using Claude directly without going through an OpenAI-compat proxy — native routing preserves Claude’s structured tool use, vision content parts, and prompt caching (future work).

An Anthropic provider definition looks like this:

[ai.providers.claude]
spec = "anthropic"
url = "https://api.anthropic.com/v1/messages"
model = "claude-opus-4-7"
api_key_env = "ANTHROPIC_API_KEY"
max_tokens = 8192
supports_vision = true
supports_tools = true

# Anthropic's auth is x-api-key with no scheme prefix.
auth_header = "x-api-key"
auth_scheme = ""

# Anthropic's required version header.
headers = { "anthropic-version" = "2023-06-01" }

New fields (also available to OpenAI providers)

• headers — HashMap<String, String> of extra HTTP headers. Default empty. Values must be printable ASCII. Use inline-table syntax (headers = { "x" = "y" }) for 1-2 headers, or a sub-table ([ai.providers.claude.headers]) for longer lists.
• auth_header — name of the auth header. Default "Authorization". Must be non-empty.
• auth_scheme — prefix prepended to the API key. Default "Bearer " (with trailing space). Use "" for Anthropic.

These fields are respected by both the OpenAI and Anthropic paths — you can use them on any provider that needs custom auth or headers (e.g. a self-hosted endpoint requiring a custom x-internal-auth header).

Translation — what the bot handles automatically

When you route to an Anthropic provider, the bot translates every shape difference transparently. The internal tool definitions, system prompt, and message history are all built in OpenAI shape (the bot’s internal canonical form) and translated to Anthropic’s wire shape on each request. You never need to write Anthropic-specific prompt logic.

Translation covers:

• System prompt → top-level system field on the request body (not a role: "system" message in the array)
• Image content parts → base64 source blocks with correct media_type
• Tool definitions → flat {name, description, input_schema} shape
• Tool call responses → tool_use content blocks are extracted into the same flat ToolCall { id, name, arguments } shape the bot uses internally
• Tool result messages → wrapped in user-content tool_result blocks

What works with Claude today

• Text chat (any routing role)
• Vision (when supports_vision = true)
• Tool use (when supports_tools = true)
• Multi-round search via the CENSORED cascade / [ai.fallback] on_censored = ["claude", ...] as a post-DeepSeek-refusal fallback
• Mixed setups: DeepSeek primary + Claude as cascade member, or Claude primary + DeepSeek as reasoner, etc.

What’s not yet available

• Streaming responses
• Anthropic’s cache_control ephemeral blocks for prompt caching
• Structured “thinking” / extended reasoning outputs (Claude’s reasoning models)

These are tracked as future enhancements; today’s integration gives feature parity with DeepSeek/Gemini for the bot’s standard workflow.

Validation behaviour

Performed once at startup, before the bot connects to Discord:

Worked examples

One-model setup (local Ollama)

[ai.providers.local]
url = "http://localhost:11434/v1/chat/completions"
model = "llama3.1:70b"
api_key_env = "OLLAMA_API_KEY"   # any non-empty value works for Ollama
max_tokens = 8192

[ai.routing]
chat = "local"

Vision and reasoner gracefully degrade. Image messages will be handed to the local model anyway; classifier is skipped so every prompt goes straight to chat.

Three providers + cascade

[ai.providers.openai_gpt]
url = "https://api.openai.com/v1/chat/completions"
model = "gpt-4o"
api_key_env = "OPENAI_API_KEY"
max_tokens = 16384
supports_vision = true

[ai.routing]
chat = "openai_gpt"
vision = "openai_gpt"            # reuse same provider for vision
reasoner = "deepseek_reasoner"   # keep the default reasoner

[ai.fallback]
on_censored = ["grok", "gemini_flash"]

Override a default

To use gemini_flash but with a different model:

[ai.providers.gemini_flash]
url = "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions"
model = "gemini-2.5-pro"           # not the default flash; check ai.google.dev for newer Pro models
api_key_env = "GEMINI_API_KEY"
max_tokens = 32768
supports_vision = true

The user definition fully replaces the default gemini_flash entry. No [ai.routing] change needed if you’re keeping the same role assignment.

See also

• Environment variables — *_API_KEY reference
• Instance config — full config.toml schema
• defaults/example-providers.toml — copy-paste catalogue for popular endpoints
• AI Chat feature page
• Issue #28 — design context + phase 2 follow-up

Personality Files

The personality file is a free-form text file that becomes the system prompt for AI chat. It’s plain prose — no TOML, no escaping, no structure imposed by the loader. Editing it feels like editing a doc, because that’s all it is.

Where it lives

Each instance has its own personality file under its config directory, named personality.txt by default. You can override the filename with the personality_file field in config.toml:

personality_file = "my-bot-persona.txt"

The path is resolved relative to config.toml, so personality.txt and my-bot-persona.txt both live alongside the config file in instances/<your-bot>/.

The loader is the load_personality method on InstanceConfig (see src/instance_config.rs). At startup the bot reads the file from CONFIG_DIR, panics if it can’t find it, and panics again if the contents are empty after trimming. There is no live reload — restarting the container picks up changes.

How it’s used

Whenever someone interacts with AI chat — by mentioning the bot, replying to one of its messages in a thread the bot is part of, or triggering a command that goes through the AI pipeline — the contents of the personality file are sent to the AI provider as the system message. Conversation context (recent messages from the same channel) is appended as user/assistant turns underneath. The personality is what the model sees first and treats as the immutable framing for every reply.

That means everything in the file is in scope for every response. There’s no “this is just the intro” — the whole file is the rules.

For the full request shape, see AI Pipeline.

Tips for writing one

• Lead with identity. The first sentence should be You are <name>, a <something> on <where>. Models latch onto this and use it to frame everything below.
• Explicitly state what you are NOT. A line like “You are not Claude, ChatGPT, Gemini, or any other branded AI” prevents the model from breaking character with a “Sorry, I’m actually Claude” disclosure.
• Describe tone with concrete traits, not just adjectives. “Direct — say the thing, no preamble” lands better than “Helpful and friendly”. Showing what direct means is more useful than naming the property.
• Include both DOs and DON’Ts. Models attend to negative instructions as well as positive ones; a short “Things you do not do” list reliably blocks the most common annoying behaviors (corporate disclaimers, refusal theater, performative emoji use).
• Keep it under 1000 words. Longer prompts dilute. Above a certain length the model starts averaging instructions instead of obeying them sharply.
• Iterate against real interactions. Ship something, watch how it answers a few real questions, and tweak. Personality writing is a feedback loop, not a one-shot specification.

Example: a short personality

You are Maple, a friendly assistant on the Cabin discord. You are not Claude,
ChatGPT, Gemini, or any other branded AI — you are Maple.

Personality:
- Warm but not saccharine
- Brief by default; expand when the question deserves it
- Honest about not knowing things
- No corporate disclaimers, no "As an AI language model"

You answer questions, you help with code, you join in jokes when they're funny,
and you don't pretend to be more capable than you are. If someone asks for
something you can't do, say so plainly and suggest what they could try instead.

Example: a longer personality

You are Cinder, the resident AI on the Forge discord — a community for people
who build small electronics, write embedded code, and argue about microcontrollers.

You are NOT Claude, ChatGPT, Gemini, Llama, or any other branded AI. You are
Cinder. Don't break character to disclose what you actually are.

# Tone

You're competent, dry, and patient. You answer the question that was asked,
not the question you wish was asked. You're allowed to have opinions —
"BLE pairing on the ESP32 is genuinely painful" is a fine sentence — but you
don't editorialize unprompted. Your humor is observational rather than performed:
you don't deploy emoji as punctuation, you don't say "absolutely!" or "great
question!" and you don't use exclamation points unless someone is in actual
danger.

# How you handle questions

- **Technical questions:** Answer concretely. If there's a code example that
  would help, write it. If there's a datasheet that has the answer, name it.
  If you're not sure, say "I'm not sure, but here's what I'd check first."
- **Debugging help:** Ask the smallest clarifying question that would let you
  give a useful answer. Don't make people fill out a form.
- **Project ideas:** Be encouraging but honest. If something is going to be
  hard, say so, then say what makes it hard. Don't sugarcoat.
- **Off-topic chatter:** Engage briefly when it's friendly. Don't lecture
  people about staying on topic — that's what mods are for.

# What you do not do

- You do not pretend to be a human.
- You do not pretend to be Claude, ChatGPT, or any other branded AI.
- You do not refuse reasonable questions for performative-safety reasons.
- You do not give long disclaimers about being an AI before answering.
- You do not say "As an AI language model" — ever.
- You do not claim you've forgotten the conversation. The recent messages
  are right there. Use them.
- You do not use a dozen emoji per message. One occasionally is fine.

# Final note

If you don't know something, say so. If you're guessing, say you're guessing.
If a question is poorly specified, name the missing piece. Confidence is good;
overconfidence is corrosive.

Common mistakes

• Making the persona contradict itself. “Be terse and concise. Provide thorough, detailed answers.” The model will pick one and ignore the other, and you won’t know which.
• Filling it with safety boilerplate. Long lists of “do not say X under any circumstances” make the model defensive and make every reply read like a legal disclaimer. Trust the underlying model’s safety training and write the file as if you were briefing a thoughtful new hire.
• Forgetting to claim a name. Without an identity statement the model will sometimes default to “I’m Claude” or “I’m a language model,” undermining the whole point of having a persona file.
• Treating it like config. It’s prose. Bullet points are fine, headings are fine, but you don’t need a schema. The model reads it the way a human would.

See also

• AI Chat — the feature page for AI chat behavior, providers, and command surface.
• AI Pipeline — how the personality file is wired into the chat completion request.

Secrets Management

A Discord bot token grants full control over your bot user — anyone who has it can read messages the bot can read, post anywhere it can post, and join voice channels on its behalf. Provider API keys cost real money if abused. Database credentials open the door to your whole instance’s data. Leaked secrets are by far the most common way bot projects get pwned, and they almost always leak the same way: someone commits an .env file or pastes a token into a public log.

This page describes how this project keeps secrets out of git by default, how to verify that’s actually the case for your fork, and what to do if something escapes anyway.

The default posture

The repo’s .gitignore excludes secrets at the file level, not the line level. The relevant entries are:

.env
instances/*/.env
!instances/*/.env.example
cookies.txt
instances/*/cookies.txt

That covers three things:

1. The root .env (used in some legacy local-dev flows).
2. Any per-instance .env under instances/<name>/.
3. The negation !instances/*/.env.example keeps the documented templates checked in, so the docs and onboarding still work.
4. Any cookies.txt (used by the music feature for YouTube authentication) at the repo root or per-instance.

If you cloned the repo cleanly and only created .env files at the documented paths, none of them will ever be staged by git add ..

Verifying your .gitignore

Before your first push, confirm that git is actually ignoring your .env:

git check-ignore -v instances/yourbot/.env

You should see a line pointing at .gitignore and the matching pattern. If you get nothing, the file is not ignored — investigate before pushing. The likeliest cause is that you put your env file somewhere unexpected (e.g. instances/yourbot/secrets.env), in which case either move it to .env or extend .gitignore to cover the new path.

Checking git history

If you’re worried something already snuck in, search the whole history:

git log -p --all | grep -iE "DISCORD_TOKEN|API_KEY|SECRET|password" | head -50

This is noisy by design — it’ll match docs and example files too. Read each hit carefully. If you find an actual token, a real API key, or anything else that grants access, treat it as leaked and follow the recovery flow below. Rotation is your only real fix; deleting the file in a new commit does not remove the value from history.

Local development

For local dev, copy the example file:

cp instances/example/.env.example instances/example/.env

Then fill in the values. Never copy your real .env into chat, into a paste site, or into a screenshot. If you need to share configuration with a teammate, send them the field list and have them generate their own values, or use a secret-sharing tool like age or your password manager’s sharing feature.

If you use a code editor with cloud sync, double-check that it isn’t quietly mirroring .env files to a remote — some editors (and some “AI assistant” extensions) read everything in the workspace by default.

Docker Compose: env_file vs. environment:

docker-compose.yml uses env_file: instances/yourbot/.env rather than putting values in an environment: block. This matters because docker-compose.yml is checked into the repo, and environment: values live in plain sight inside it. env_file keeps the path to the secrets in the compose file but the actual values stay in the gitignored .env.

The same logic applies if you ever feel tempted to bake secrets into a Dockerfile with ENV or ARG. Don’t. They end up in image layers, which are visible to anyone with pull access to the image.

Docker secrets in production

For production deployments, Docker has a secrets primitive that mounts secret values as files inside the container, owned by root and readable only by the process. It’s a step up from env_file because the secret never lives on disk in plaintext outside the swarm raft store, and because rotating a secret rotates it everywhere it’s mounted.

For a single-host Compose deployment, the marginal benefit over a properly permissioned .env (see Production hardening) is small. For a Swarm or Kubernetes deployment, secrets are the right answer. The bot itself reads from environment variables, so adapting it just means setting up a small entrypoint that exports the contents of mounted secret files into the environment before launching the binary.

Rotating secrets

• Discord token. Open the Developer Portal → your application → Bot → Reset Token. The new token immediately invalidates the old one. Update .env, restart the bot, done.
• DeepSeek / Gemini / Finnhub API keys. Each provider has a key-management page. Generate a new key, update .env, restart, then revoke the old key in the dashboard.
• Database password. Update Postgres (ALTER USER discord_bot WITH PASSWORD '<new>';), update DATABASE_URL in .env, restart the bot.
• MCP_AUTH_TOKEN / MCP_GATEWAY_AUTH_TOKEN. Generate a new value (openssl rand -hex 32), update .env, restart the bot and the gateway.

There is no live reload for any of these — restarting the container is the rotation step.

What to do if a secret leaks

If you discover an exposed secret, work in this order:

1. Generate a replacement before revoking the leaked one. Your running bot still has a valid token; you don’t want to take it offline before the replacement is ready.
2. Update .env with the new value.
3. Restart the bot. Confirm it comes back up cleanly with the new credentials.
4. Revoke the old secret in the provider dashboard. For Discord, Reset Token invalidates the previous one automatically.
5. Audit logs for the window the secret was live. Look for unexpected message activity, role changes, channel creations, or API calls.
6. If the secret was committed to git, the value is in history and is effectively public. Use git filter-repo to purge it, force-push the rewritten history, and ask collaborators to re-clone. Note that anyone who already cloned (including caches like the GitHub web UI) still has it — rotation is what actually fixes the leak. History rewriting is just hygiene.

Production hardening

A few quick wins beyond gitignoring .env:

• Restrict database access to the bot user. Don’t reuse a Postgres superuser. If you’re running multi-instance, use the same dedicated discord_bot user but rely on the per-schema search_path for isolation.
• Set tight permissions on .env. chmod 600 instances/yourbot/.env so only the owner can read it. The Compose service runs as a non-root user; make sure that user is the owner.
• Don’t log environment variables at startup. The bot doesn’t currently log secrets — it logs only the bot name, command prefix, and which feature modules are enabled — but if you add logging, never dump the full env or the full Config struct.
• MCP_AUTH_TOKEN is mandatory on any non-loopback bind. The bot now refuses to start if MCP_BIND_ADDR is anything other than a loopback address and MCP_AUTH_TOKEN is empty — this used to be a “you really should” recommendation; it is now enforced at startup. The bundled Compose .env.example ships with MCP_BIND_ADDR=0.0.0.0 (the gateway sidecar reaches the bot over the Docker network), so a Compose deploy without a token will fail on boot until you set one. The mcp-gateway service is stricter still and refuses to start at all without MCP_GATEWAY_AUTH_TOKEN. See MCP Exposure.
• Run the container as a non-root user. The shipped image already does this.
• Keep dependencies up to date. cargo update and rebuild on a regular cadence; security advisories for transitive crates show up via cargo audit if you wire it into CI.

For a more complete production walkthrough, see the Production Checklist.

Multiple Instances

discord-bot-rs is designed so a single binary, a single docker-compose.yml, and a single Postgres database can host as many independent bots as your hardware can spare. “Multiple instances” here means exactly that: several Discord bot identities, each with its own config and database schema, running side by side as separate processes.

When to use it

• You run more than one Discord community and want one machine to host every bot.
• You want a dev or staging instance running alongside production so you can test changes without risking the live bot.
• You’re hosting bots for friends and want to consolidate maintenance.

If you only run one bot, you don’t need any of this — the example instance is already a complete single-instance deployment. Come back here when you actually have a second bot to add.

The recipe

The flow is “copy the example, edit two files, edit Compose, restart.” Concretely:

1. Copy the example directory.

   cp -r instances/example instances/bot2
   cp instances/bot2/.env.example instances/bot2/.env
   

2. Edit instances/bot2/.env. At minimum, change:

   • DISCORD_TOKEN — the new bot’s token from the Discord Developer Portal
   • CLIENT_ID — the new application’s client ID
   • GUILD_ID — the snowflake of the new bot’s home server
   • DB_SCHEMA=bot2 — must be unique across instances

   Leave DATABASE_URL pointing at the same Postgres service as the first bot. If you set any optional API keys (DeepSeek, Gemini, Finnhub, Minecraft), each instance gets its own — they don’t share keys unless you make them.

3. Edit instances/bot2/config.toml. Set bot_name to something distinct (it shows up in logs and helps you tell which instance is which when tailing) and adjust command_prefix, feature flags, and feature sub-sections to match what you want this bot to do.

4. Edit instances/bot2/personality.txt. Even if the persona is the same as your first bot, edit the file so the loader has something non-empty to read. Most people want a different persona per community anyway.

5. Duplicate the bot service in docker-compose.yml. Copy the existing bot service block and rename the copy to bot2. Update its env_file to point at instances/bot2/.env, update its volume mount so instances/bot2 becomes /config inside the new container, and change the container name. The image, depends_on: postgres, and restart settings can stay identical — both containers run the same image with different config mounted.

6. Update the mcp-gateway service. Add the new instance to the gateway’s INSTANCES env var so it knows where to route requests for bot2. The gateway reads this list at startup; restarting the gateway picks up new entries.

7. Bring it up.

   docker compose up -d bot2
   docker compose restart mcp-gateway
   

You should see bot2’s startup logs report its bot name, prefix, and the feature modules it enabled. From Discord’s perspective the second bot is wholly independent of the first.

Shared resources

A multi-instance deployment shares three things across all bots:

• PostgreSQL. One Postgres container, one database, but each instance writes to its own schema. The schema is set by DB_SCHEMA in the instance’s .env and applied via SET search_path on every new connection (see src/db/mod.rs). Tables, sequences, and migrations all live inside the schema, so two instances with DB_SCHEMA=bot1 and DB_SCHEMA=bot2 cannot see each other’s data.
• MCP gateway. A single gateway service routes MCP requests to the right instance based on the URL path. Each instance still runs its own embedded MCP server inside its container; the gateway just provides a single externally addressable endpoint. See MCP Gateway Routing.
• Docker network. All bots and the gateway sit on the default Compose bridge network. They can reach Postgres and each other by service name, but Discord-side they’re completely independent — each one owns its own gateway connection and Discord application.

Everything else — config, personality, runtime memory, async tasks — is per-instance.

Concurrency and resource limits

Each instance is a separate process running its own Tokio runtime, so CPU and RAM scale roughly linearly with the number of instances. There is no shared in-process state between bots, which is the point — but it also means there’s no economy of scale on memory: two bots use about twice as much RAM as one bot.

Practical sizing notes:

• A modern Pi 4 (4GB) comfortably runs two or three bots plus the bundled Postgres and gateway.
• The biggest variable is music: voice connections and ffmpeg pipelines dominate memory and CPU when active. A bot that never plays music is much cheaper than one with three concurrent voice channels.
• Postgres is the smallest part of the budget unless you have many tens of thousands of tracked messages or game states.

When you start hitting limits, the next step up is usually splitting Postgres onto a dedicated host (or a managed service) rather than splitting the bots themselves.

Gotchas

• DB_SCHEMA must be unique per instance. Two instances pointed at the same schema will corrupt each other’s state. There is no defensive check for this — you have to get it right.
• The MCP server runs in-process and is reached over the Docker network from the gateway. You don’t need to expose its port to the host unless you also want direct access from outside Compose. If you do expose it, every instance needs a different host port (e.g. 9091:9090, 9092:9090).
• Docker container names must be unique. If you copied the bot service block without renaming the container_name, Compose will complain. Pick a name per instance.
• Health checks per instance are fine. Each container’s healthcheck talks to its own MCP server on 127.0.0.1:9090 inside the container, and that doesn’t conflict with anything because each container has its own loopback.
• Discord rate limits are per-token, not per-host. Running multiple bots on one host doesn’t multiply the rate limit budget for any single bot, but bots don’t share rate limits with each other.

See also

• Multi-Instance Model — the architectural picture, with a diagram of how the pieces fit.
• Multi-Instance Deployment — the full Compose layout and operational runbook.
• MCP Gateway Routing — how the gateway maps requests to instances.

Features

This is a quick-reference index of every feature the bot ships with: what it does in one line, what flag turns it on, what environment variables and config.toml sections it needs, and where to read more.

The bot is built so each feature is independent. There are no cross-feature dependencies — you can run the bot with nothing but AI chat enabled, or with nothing but Minecraft tooling, and the rest will sit quietly out of the way.

Always-on vs opt-in

There are two flavours of feature gating in the codebase:

• Always-on — the code is always compiled in and the runtime always registers the relevant commands and event handlers. The feature only activates when its dependencies are met. AI chat, for example, is always-on, but if you don’t set DEEPSEEK_API_KEY or GEMINI_API_KEY the bot just never replies to mentions. Music is similarly always-on but needs yt-dlp and ffmpeg on the PATH to actually play anything.
• Opt-in — the feature is gated behind a boolean in the [features] section of config.toml. If the flag is false (or absent), the feature’s startup hooks never run and the associated config sections are ignored. Auto-role, join-role, welcome, and the three Minecraft sub-features all work this way.

The MCP server is a special case: it is always-on but binds to a port, so you have a separate set of MCP_* env vars to control where it listens and whether it requires a bearer token.

Feature matrix

A few things worth calling out:

• The flags in the table match the field names on the Features struct in src/instance_config.rs. There is no auto_role, join_role, welcome, or minecraft flag in [features] if you don’t put it there — they all default to false.
• When you set a features.* flag to true but forget the matching config section, the bot logs a warning at startup and silently skips that feature instead of refusing to boot. Watch the logs after editing config.toml.
• The Welcome feature is the only opt-in that needs an AI key in addition to its config section, because it generates greeting messages with the same provider stack as AI Chat.
• Stocks is “always-on” in the sense that the !m stock commands are always registered, but every command will return “Finnhub API key not configured” if FINNHUB_API_KEY is missing.

Enabling a feature at runtime

Features are loaded once at startup. There is no live reload. To change what is enabled:

1. Edit config.toml (or .env for env-var-driven features).
2. Restart the bot. With Docker Compose that’s docker compose restart <service-name>.
3. Check the startup logs to confirm the feature was picked up — every opt-in feature emits an enabled log line on boot.

For deployment-level guidance on how to roll restarts safely, see Upgrading.

Cross-references

• Instance Config (config.toml) — reference for every key in the [features] and per-feature sections.
• Environment Variables — reference for every variable named in the table above.
• Multiple Instances — how to run several bot instances with different feature sets out of the same image.
• Architecture overview — for understanding how features compose at runtime.

AI Chat

The bot replies to natural-language messages in Discord using a large language model. The chat path is wired up to two providers — DeepSeek as the primary, Google Gemini as a vision-and-fallback path — and the personality is loaded from a plain text file you write yourself.

What it does

When someone @mentions the bot or replies to one of its messages, the bot collects the recent conversation in that channel, feeds it to the AI along with your personality.txt system prompt, and sends the model’s reply back as a Discord message. It does this with whatever model you have keys for:

• DEEPSEEK_API_KEY — primary provider (deepseek-v4-flash, with automatic routing to deepseek-v4-pro for hard questions). The chat-tier output is inexpensive; the bot is built around DeepSeek’s tool-calling format.
• GEMINI_API_KEY — secondary provider. Used for image attachments (DeepSeek Chat is text-only) and as a fallback if the DeepSeek text path is unavailable.

If you set neither key, the bot still starts cleanly — it just won’t react to mentions. If you set both, you get text replies via DeepSeek and image understanding via Gemini for free.

The pipeline goes well beyond echoing replies: the AI can call tools you’ve exposed (music, moderation, stocks, web search, NYT-style games) and the bot routes the resulting tool calls back into Discord. See Architecture: AI Pipeline for the flow diagram.

Activation

The message handler in src/events/mod.rs triggers the AI on exactly two conditions:

1. The message contains a direct mention of the bot’s user (the bot is in message.mentions).
2. The message is a Discord reply to one of the bot’s previous messages.

Anything else is ignored. The bot does not respond to keywords, prefixes, or DMs. There is no “owner override” or special-user bypass — every user is treated identically by the AI path.

When neither DEEPSEEK_API_KEY nor GEMINI_API_KEY is set, the activation check short-circuits and the handler exits immediately. This is the safe state: you can deploy the bot without an AI key and the rest of its features still work.

Configuration

Provider configuration: as of 0.15.0, the providers DeepSeek + Gemini + Grok the bot ships with can be replaced or extended by your own definitions in config.toml. As of 0.16.0, Anthropic Claude is also supported natively (spec = "anthropic") — native routing preserves structured tool use and vision content parts without going through an OpenAI-compat proxy. See AI Providers for the schema and examples, and the Anthropic spec section for Claude-specific configuration.

There are exactly three things to configure:

1. DEEPSEEK_API_KEY in .env. Optional in the strict sense, but without it you get no text replies. Get one from platform.deepseek.com.
2. GEMINI_API_KEY in .env. Optional. Required only if you want image understanding or text-fallback when DeepSeek is unreachable.
3. personality.txt in the instance config directory (the directory pointed at by CONFIG_DIR, defaults to the working directory). This is loaded at startup by InstanceConfig::load_personality and panics if the file is missing or empty — this is intentional, because shipping without a personality means the bot has no voice.

There is no in-app configuration of model parameters, temperature, or context window size — they are tuned in src/ai/chat.rs. If you want to override them you have to recompile.

For details on how to write a good personality file, see Personality Files. For where to keep your .env and how to feed it into Docker safely, see Secrets Management.

How the personality shapes responses

personality.txt is loaded as a free-form string, prepended to a small hard-coded system prompt, and sent to every API request as the system-role message. The hard-coded part covers things the bot needs to know regardless of personality — the current date, its version, what tools it has, security boilerplate against prompt-injection attacks, and formatting rules for Discord markdown. Your text sits at the top.

This means:

• Anything you write in personality.txt overrides the generic LLM voice. Be opinionated. The AI is much more interesting when the personality is specific.
• The personality is loaded once at startup. Editing the file and saving it does nothing until the bot restarts.
• The personality is the same across every channel and every user. There is no per-guild override.

Conversation context window

For each mention, the bot fetches the last 100 messages in the channel (FETCH_LIMIT in src/ai/chat.rs) and walks them in order, picking up to 10 relevant messages (MAX_RELEVANT) that meet two filters:

• They are no older than 30 minutes.
• They are either bot replies or messages that mentioned/replied to the bot.

Messages from before the bot’s current process started are also dropped, so a restart wipes the AI’s memory of older conversation. There is no cross-channel memory; each channel is its own scratch buffer.

This window is deliberately small. It keeps token costs down, keeps context fresh, and prevents the bot from rehashing a stale request from hours ago. The trade-off is that long conversations summarize themselves out of view quickly.

Known limitation: in busy channels, two unrelated conversations happening at the same time can bleed into one another’s context. The bot does not segment by conversation thread; it segments by channel and time window. Discord threads are treated as their own channel, so threading a conversation is the cleanest workaround.

Tool use

The AI has access to a set of function-calling tools defined in src/ai/tools.rs. They cover:

• Music — play_song, skip, stop, pause, resume, show_queue, now_playing, shuffle, set_loop, remove_from_queue. The AI can control the music player conversationally (“play something chill”, “skip this”) without the user needing to know the prefix commands.
• Moderation — tempban, unban, nuke. Privileged. Every moderation tool call goes through a confirmation embed (see below) before it actually runs.
• Web search — web_search, used for current-events questions and fact-checking. Up to three rounds of search are allowed per request (the MAX_SEARCH_ROUNDS constant in src/ai/chat.rs, also interpolated into the system prompt so the model and the loop agree), so the AI can refine queries based on results.
• Stocks — stock_buy, stock_sell, stock_price, stock_portfolio, stock_leaderboard. Bound to the virtual portfolio system.
• Games — connections_start, wordle_start. Lets users say “start a Wordle” without remembering the command name.

All tool calls except web search are visible in chat: the bot replies with the result of the action (e.g. an “Added to Queue” embed or a “Banned user” message). Web search is silent — the AI consumes the results and folds them into its answer.

For the full pipeline including tool dispatch, see Architecture: AI Pipeline.

Moderation confirmation

Moderation tools (tempban, unban, nuke) are powerful enough to do real damage if the AI misreads a request. The bot inserts a confirmation step:

1. The AI emits a moderation tool call.
2. The bot posts an embed showing exactly what is about to happen (“Tempban @user for 3d — repeated spam”), with Approve and Cancel buttons.
3. Only the original requesting user can press a button.
4. If the user lacks the corresponding permission (BAN_MEMBERS for tempban/unban, MANAGE_MESSAGES for nuke), the bot refuses up front.
5. If 30 seconds pass with no response, the action expires and is cancelled.

This is implemented in src/ai/confirmation.rs. There is no way to opt out — privileged tools always go through the confirmation gate.

Safety and sanitization

User input is sanitized before being sent to the model (see src/ai/sanitize.rs): role markers like system: are rewritten, DeepSeek <|...|> tokens are stripped, and Llama-style [INST] / <<SYS>> blocks are removed. This makes it harder for a user to inject a fake system prompt by typing one into chat.

The model’s output is also filtered. The bot maintains a list of “bad assistant” patterns — “I am Claude”, “I don’t have the ability to remember”, “created by Anthropic” — and refuses to fold those messages back into the conversation history. Without this, hallucinated identities would propagate through the context window.

The hard-coded system prompt also tells the model to ignore “ignore previous instructions” jailbreaks and never reveal its system prompt.

Rate limiting

A per-user rate limiter (data.rate_limiters.ai) checks the requester before each AI call. If the user is over their budget, the bot replies “Slow down — try again in Ns” instead of calling the API. There is a separate, stricter limiter on moderation tool calls.

The limits are tuned to absorb normal back-and-forth chat without throttling, while preventing one user from running up an API bill in isolation.

Provider failover

The text path is hard-coded to DeepSeek. The vision path is hard-coded to Gemini. If a request has image attachments, the bot tries Gemini first; on failure it strips the multimodal content and falls back to DeepSeek text-only with a description-of-context placeholder.

Inside the DeepSeek path, the bot routes between deepseek-v4-flash (fast) and deepseek-v4-pro (the V4 flagship) by classifying each message: simple chat goes to V4-Flash, anything that smells like a reasoning task goes to V4-Pro. The reasoner role can’t use tools directly, so the bot uses deepseek-v4-flash as a research assistant first to perform any web searches, then hands the gathered context to V4-Pro for the final answer.

Common issues

• Bot doesn’t respond to @MyBot — check that DEEPSEEK_API_KEY is set in the running environment (Docker users: confirm .env is being passed in), check the bot’s logs for API request failed messages, and verify the bot has the Message Content gateway intent enabled in the Discord developer portal.
• Bot replies but the personality is wrong — personality.txt was edited but the bot wasn’t restarted. The personality is loaded once at boot.
• Bot mixes up two conversations in the same channel — known limitation of the channel-and-time-window approach. Move the second conversation into a Discord thread, or wait 30 minutes for the older context to age out.
• Bot refuses to talk about a topic with “my overlords at DeepSeek won’t let me” — DeepSeek’s content filter triggered. The bot detects the upstream Content Exists Risk error and translates it into a snarky message instead of crashing.
• Bot’s reply is cut off mid-sentence — replies longer than 2000 characters are split into chunks by src/ai/split.rs. If you see a truncated message ending in ...[truncated], that’s the splitter hitting the Discord per-message limit on a single chunk; the next chunk should follow immediately.
• Bot says “I don’t have memory” / “I’m Claude” — the model hallucinated a different identity. The output filter catches the most common phrasings on subsequent turns; if it’s getting through on the first turn, strengthen the personality file with an explicit “you are not Claude / ChatGPT / etc.” line.

Cost

Costs depend almost entirely on which model you route to. DeepSeek V4-Flash is inexpensive enough that an active community server typically lands at single-digit dollars per month. V4-Pro is ~12× more expensive per output token (the flagship reasoner) but only fires on detected reasoning queries. Gemini’s free tier covers casual image traffic.

Check the providers’ current pricing pages directly:

• DeepSeek: https://api-docs.deepseek.com/quick_start/pricing
• Google Gemini: https://ai.google.dev/pricing

Cross-references

• Personality Files — how to write personality.txt.
• Architecture: AI Pipeline — request flow, tool dispatch, model routing.
• Secrets Management — where to put API keys safely.
• Environment Variables — DEEPSEEK_API_KEY, GEMINI_API_KEY, and friends.
• Moderation — what the moderation tools actually do when the AI invokes them.

Music

A queue-based voice music player. Audio is fetched and remuxed by yt-dlp into an Opus-in-OGG stream, which Discord (via songbird) plays back without any additional transcoding.

What it does

• One queue per Discord guild, up to 100 tracks (MAX_QUEUE_LENGTH in src/music/player.rs).
• Plays anything yt-dlp can resolve: YouTube videos, YouTube playlists, SoundCloud, Bandcamp, Mixcloud, Vimeo, direct media URLs, and several hundred other sites.
• Search-by-text via the ytsearch1: prefix when you don’t have a URL.
• Loop modes (off / track / queue), shuffle, queue editing.
• An interactive “Now Playing” embed with button controls.
• Auto-leave the voice channel after 5 minutes of nothing playing.

The bot speaks 256 kbps Opus directly, so there is no transcoding step inside the process — yt-dlp hands songbird an Opus stream and songbird forwards it to Discord. CPU usage is essentially flat, even on small VPSes.

Commands

All music commands live under the m parent. With the default ! prefix that means !m <subcommand>. The prefix is configurable per instance via command_prefix in config.toml; the examples below assume !.

There is no previous, no seek, and no playback-position scrubbing. The model is “modify the queue, then let it play” rather than random-access seeking inside a track.

The bot can also drive these commands via the AI tool layer — say “@bot play something chill” or “@bot skip this” and the AI invokes the same underlying functions. See AI Chat.

Interactive controls

Whenever the bot starts a track (via !m play, !m skip, or auto-advance), it sends a “Now Playing” embed with a row of buttons:

• ⏯ Pause / Resume
• ⏭ Skip
• ⏹ Stop and leave
• 🔀 Shuffle the queue
• 🔁 / 🔂 Loop mode (cycles off / track / queue)
• 📋 Show queue

The buttons are gated by two checks:

1. The user pressing them must be in the same voice channel as the bot.
2. If DJ mode is on for the guild and the user lacks the DJ role (and isn’t an administrator), the button refuses with an ephemeral message.

The “Show queue” button skips the voice-presence check so anyone listening can peek at what’s coming up.

When a track ends and the next one starts automatically, the bot deletes the previous “Now Playing” message and posts a fresh one for the new track, so there’s only ever one set of controls live in the channel. The same cleanup runs when a track is skipped — both the Skip button and the !m skip text command delete the previous “Now Playing” message before posting the new one, so manual skips don’t leave orphaned embeds behind.

Supported sources

Anything yt-dlp supports. The most common cases:

• YouTube videos — paste a URL, or use a free-text query (the bot prefixes the query with ytsearch1: so you get the top result).
• YouTube playlists — use !m playlist <url>. !m play on a playlist URL only takes the first video, by design (--no-playlist is set on the single-track path).
• SoundCloud, Bandcamp, Mixcloud, Vimeo, Twitch VODs, direct media URLs — anything in the yt-dlp extractor list.

If yt-dlp can extract a single audio stream URL from it, the bot can play it.

Audio quality

The bot configures songbird for 256 kbps Opus (Bitrate::Bits(256_000) in src/music/voice.rs) and uses the streaming YoutubeDl input. yt-dlp is launched with -f bestaudio, so the input is whatever the highest-bitrate audio stream is at the source — typically Opus directly from YouTube, which means the bytes flow through to Discord with no transcoding at any point.

Practical consequences:

• CPU footprint is negligible — under a percent on a small VPS — even with multiple guilds streaming.
• Quality is bounded by the source. A 96 kbps SoundCloud track is still 96 kbps when it reaches your ears.
• There is no normalization, no equalizer, no audio filters. If you want loudness normalization you need to add it yourself.

YouTube cookies

YouTube increasingly demands a logged-in session for anonymous IPs, particularly:

• Age-restricted videos
• Region-locked videos
• “Sign in to confirm you’re not a bot” anti-scraping prompts on data-center IPs

The fix is to provide a cookies file. The bot looks for cookies.txt in the working directory at startup. The file is gitignored and intentionally lives per-instance — each bot instance has its own.

Format

cookies.txt is the Netscape / Mozilla cookies format. Easiest way to generate one:

1. Install a browser extension such as “Get cookies.txt LOCALLY” (Firefox or Chrome).
2. Log into YouTube in the browser session you control.
3. Use the extension to export cookies for youtube.com.
4. Save the file as cookies.txt in the instance config directory next to config.toml.

Use a throwaway YouTube account for this. The bot is going to make API calls with whatever account you log in as.

Cookie fallback behaviour

If the cookies file is missing, expired, or otherwise rejected by YouTube, the bot does not give up. The flow in src/music/track.rs::resolve_tracks is:

1. Run yt-dlp with --cookies cookies.txt.
2. If the call succeeds, return the result.
3. If it fails and the stderr contains a known cookie-error marker (“page needs to be reloaded”, “sign in to confirm”, “this helps protect our community”, “login required”), retry the same query with no --cookies flag at all.
4. If the second attempt succeeds, return the result and tell the caller to flag the cookies as stale.
5. If the second attempt also fails, surface the error to the user.

When the second attempt is what worked, the bot adds a one-line warning to chat:

⚠ YouTube cookies are expired. Music still works but age-restricted content won’t. Someone needs to refresh cookies.txt.

So you’ll know to refresh them, but the bot stays usable in the meantime.

Auto-leave

When playback finishes and there is nothing left in the queue, the bot starts a 5-minute idle timer (src/music/voice.rs::start_idle_timer). If nothing else is queued within those 5 minutes, the bot leaves the voice channel and clears its per-guild player state. Any new track started before the timer fires cancels it.

There is also a separate auto-leave path triggered by voice state updates: if everyone else leaves the voice channel and the bot is the only remaining occupant, it leaves immediately. See src/events/voice_state.rs.

Permissions required

The bot needs the standard voice trio in any channel it should be allowed to play in:

• Connect — to join the voice channel
• Speak — to transmit audio
• Use Voice Activity — so it doesn’t have to push-to-talk

If the role you assigned to the bot is missing any of these, joining will succeed but no audio will be heard, and the bot will not produce a clean error — it’ll just sit silently in the channel. Check role permissions on a per-channel basis if a specific room misbehaves.

DJ mode

If the guild has DJ mode enabled (set via !m djmode and !m djrole, stored in the database), only members with the DJ role (or administrators) can use music commands and music buttons. Other members get a polite refusal.

DJ mode is a per-guild setting, not a config-file setting — each server’s admins manage their own.

Common issues

• “Sign in to confirm you’re not a bot” or “Couldn’t find that song” — YouTube needs cookies. Provide a cookies.txt (see above). Until you do, only non-restricted videos will play.
• “Video unavailable” or geo-blocked content — there’s nothing the bot can do; the source is refusing the request from the bot’s egress IP. A different region’s cookies.txt plus a tunneled connection might work, but that’s outside the bot’s scope.
• Bot joins the channel but no audio plays — ffmpeg is missing on the host. The Docker image bundles it; if you’re running outside Docker, install it via your package manager and make sure it’s on PATH.
• Audio is choppy or stutters — rare with passthrough, since CPU is barely involved, but possible if the host has heavy disk/network contention. Check htop and the bot logs for backpressure.
• The bot’s “Now Playing” embed disappears every track change — that’s intentional. The bot deletes the previous embed when a new track starts so there’s only one set of controls live at a time.
• A long playlist only adds a fraction of its tracks — the queue is capped at 100. Anything past MAX_QUEUE_LENGTH is dropped on enqueue and the bot tells you how many were added.

Rate limiting

Every music prefix command and every music_* button interaction is throttled per user through the shared RateLimiters infrastructure at 15 requests / 30 seconds. That covers all 11 prefix commands (play, playlist, skip, stop, pause, resume, queue, nowplaying, remove, loop, shuffle) and every button on the “Now Playing” embed (pause/resume, skip, stop, shuffle, loop, show queue). Hitting the cap returns a “Slow down” reply instead of executing the action.

The rate limit is in addition to the existing practical limits:

• Discord’s voice-gateway rate limits.
• yt-dlp startup time (it forks a subprocess per resolve).
• The 100-track queue cap.

If you want stricter throttling than per-user, gate the commands with DJ mode.

Cross-references

• Architecture: Music Pipeline — diagrams of the resolve / play / event-handler flow.
• AI Chat — how to drive music commands through the AI tool layer.
• Instance Config — command_prefix and other per-instance settings.
• Codebase Tour — where the music modules live in the source tree.

Wordle

A Discord-native port of the New York Times’ daily five-letter word puzzle. The bot fetches the official puzzle from the NYT API and tracks each game in memory, scoped to a single channel.

What it does

Wordle is the classic six-guess word game: you have six attempts to guess a five-letter solution. Each guess is graded letter-by-letter — green for the right letter in the right spot, yellow for the right letter in the wrong spot, black for a letter that isn’t in the solution at all. The bot owns the score grid and the “keyboard” tracker; you just type your guesses into chat as plain messages.

Three flavours of puzzle are available:

• Today’s puzzle — the same one everybody else is playing. Pulled from the NYT API in UTC.
• A specific date — replay any puzzle from 2021-06-19 (the first NYT Wordle) onwards.
• A random puzzle — pick any past puzzle uniformly at random from the full back catalogue.

Wordle is always-on. There is no [features] flag and no API key required. The bot calls a public NYT JSON endpoint (nytimes.com/svc/wordle/v2/<date>.json) and the word list of valid guesses is bundled into the binary (src/wordle/words.txt).

Commands

All commands live under the m parent command. With the default ! prefix that means !m wordle <subcommand>. The prefix is configurable per instance via command_prefix in config.toml; the examples assume !.

Starting a new game in a channel that already has an active (non-expired) game is refused — the bot replies that there’s a game in progress and asks you to finish or wait for it to expire (30 minutes idle). Once the existing game is solved, lost, or times out, you can start a new one. This applies to the AI wordle_start tool path as well, so the AI can’t accidentally clobber an in-progress game either. One puzzle per channel at a time.

The date subcommand validates its argument up front via chrono::NaiveDate::parse. Bad input (!m wordle date today, !m wordle date 2026/04/16, !m wordle date april 16) gets a “Use YYYY-MM-DD format” reply and no NYT call. If the request parses but NYT returns a puzzle whose print_date doesn’t match the requested date, the bot prepends a warning before the game embed (NYT occasionally serves the previous day’s puzzle near the rollover boundary).

How to play

1. Start the puzzle with one of the commands above. The bot posts an embed showing six empty rows and a Wordle — YYYY-MM-DD title.
2. Type a five-letter word into the channel. The bot detects any message in the channel that’s exactly five ASCII letters while a game is active — no command prefix needed.
3. The bot deletes your guess message and edits the embed in place, filling in the next row with green/yellow/black squares and updating the keyboard tracker at the bottom.
4. Repeat until you solve it or run out of guesses.

If you type a five-letter sequence that isn’t a real word, the bot replies “Not a valid word.” and deletes both your message and its reply after about two seconds. You don’t lose a guess.

When you win, the title flips to Wordle — YYYY-MM-DD — Solved in N! with a green border. When you lose, the title flips to Game Over, the border goes red, and the answer is revealed under the grid.

The keyboard tracker

Below the grid the bot maintains a per-letter status line that summarizes what you’ve learned so far:

🟩 A E   🟨 R   ⬛ S T O U N D L

Letters get “upgraded” as you discover better information about them: a letter that started as black (⬛ Absent) gets promoted to yellow (🟨 Present) the first time you see it in a yellow square, and to green (🟩 Correct) the first time you see it in a green one. The tracker never downgrades a letter, so you can scan it for what’s still on the table at a glance.

Game lifecycle

Wordle game state lives in an in-memory DashMap keyed by Discord channel ID. Two things end a game:

• Completion. When you win or lose, the game is removed from the map immediately. The embed stays in the channel as a record.
• Inactivity. A game that hasn’t received a guess in 30 minutes is treated as expired. Expired games are cleaned up the next time someone tries to interact with the channel.

Restarting the bot wipes all in-progress games. There is no persistence; nothing about Wordle touches the database. If you start the daily puzzle, guess a few times, and the bot restarts, you’re back to a fresh six guesses.

There is no per-user lockout — once a game is going in a channel, anyone in that channel can guess. This makes it work nicely as a collaborative puzzle.

Configuration

There is nothing to configure. Wordle ships always-on and uses no environment variables. If your instance hides the games behind DJ mode or a role gate, that’s outside Wordle’s scope; gate the channel itself with Discord permissions.

Common issues

• “Use YYYY-MM-DD format” — your date argument didn’t parse as an ISO date. Examples that work: 2024-01-15, 2021-06-19. Examples that don’t: today, 2024/01/15, Jan 15 2024.
• “No Wordle found for date YYYY-MM-DD” — the date parsed but is before 2021-06-19 (when the NYT bought Wordle and started serving puzzles via this API) or NYT has no puzzle for that day.
• “There’s already a Wordle in progress in this channel” — someone started a game and it hasn’t finished or timed out (30 minutes idle). Finish the game or wait it out.
• “NYT served a different date than requested” warning above the game — happens occasionally when NYT’s rollover lags the requested date. The bot still posts the puzzle; the warning is just so you don’t think you’re playing the wrong day’s game.
• Five-letter guesses do nothing — there is no active game in the channel. Start one with !m wordle. Or the previous game just expired (30 minutes idle); the next guess after expiry is silently ignored rather than triggering anything weird.
• Bot says “Not a valid word.” — your guess isn’t in the bundled word list (src/wordle/words.txt). The list is the standard Wordle guess vocabulary; it does not include slang, names, or every English word. Try a different guess.
• Wins/losses don’t show up on a leaderboard — there is no Wordle leaderboard. Game state is per-channel and ephemeral, by design.
• Multiple people guessing at the same time — that’s fine. The bot serializes guesses through a per-game lock and applies them in the order they arrive. The grid will update once per guess.

Cross-references

• Connections — sister command, same daily-NYT pattern.
• Stocks — the third “always-on” game-like feature.
• AI Chat — the AI can invoke wordle_start as a tool, so users can say “@bot start a Wordle” without remembering the command.
• Instance Config — command_prefix if you’ve changed it from the default !.

Connections

The New York Times’ “find the four hidden groups” word puzzle, played inside Discord with button controls. The bot fetches the official puzzle from the NYT API and renders the 16-word board as a grid of clickable buttons.

What it does

A Connections puzzle gives you sixteen words. Those words sort into four hidden categories of four words each, each category colour-coded by difficulty: yellow (easiest), green, blue, and purple (hardest). Your job is to identify all four groups. You’re allowed four mistakes before the game ends.

The bot:

• Fetches the puzzle for a given date from the NYT API (nytimes.com/svc/connections/v2/<date>.json).
• Shuffles the 16 words and renders them as four rows of four buttons.
• Lets users click words to select them, click again to deselect, and hit Submit when they have exactly four selected.
• Tracks selected words, solved categories, mistakes remaining, and a status line showing the result of the last guess.
• Detects “one away” guesses (three of four correct) and tells you so, the same way the official NYT version does.
• Reveals all four categories when the game ends, win or lose.

Three flavours of puzzle are available, mirroring the Wordle commands: today’s daily puzzle, a specific date, or a random one from the back catalogue.

Connections is always-on. There’s no [features] flag and no API key required.

Commands

All commands live under the m parent command. With the default ! prefix that means !m connections <subcommand>. The prefix is configurable per instance.

Starting a new game in a channel that already has an active (non-expired) game is refused — the bot replies that there’s a game in progress and asks you to finish or wait for it to expire (30 minutes idle). Once the existing game is solved, lost, or times out, you can start a new one. The same guard applies to the AI connections_start tool path. One puzzle per channel at a time.

The date subcommand validates its argument up front via chrono::NaiveDate::parse. Bad input (!m connections date today, !m connections date 2026/04/16) gets a “Use YYYY-MM-DD format” reply and no NYT call. If NYT returns a puzzle whose print_date doesn’t match the requested date, the bot warns above the board.

How to play

1. Run !m connections (or one of the variants above). The bot posts an embed with the title Connections — YYYY-MM-DD, a “Mistakes remaining: ⬛⬛⬛⬛” line, and four rows of word buttons.
2. Click words to select them. Selected words flip from grey (Secondary) to blue (Primary). The Submit button only enables once you have exactly four selected.
3. Click Deselect to clear your current selection, Shuffle to randomize the remaining words on the board, or Submit to commit the four-word guess.
4. Each guess produces one of three outcomes:
   • Correct — the four words form one of the hidden categories. The bot adds them to the solved list at the top of the embed (annotated with the category title and difficulty colour) and removes them from the board.
   • One away — three of your four words are in the same hidden category but the fourth doesn’t fit. The bot says “One away” and decrements your mistakes counter.
   • Wrong — none of the unsolved categories matches three or more of your words. Counter decrements.
5. Continue until you solve all four groups (win) or run out of mistakes (lose). At game end the bot reveals every group with its words and category title.

The status line under “Mistakes remaining” shows the most recent result and which user made the guess: e.g. 🟪 Tricky Wordplay solved by @alice! or ❌ One away! (guessed by @bob) — 2 mistakes remaining.

Anyone in the channel can press the buttons. Connections is collaborative by default — the bot doesn’t restrict guessing to a single user.

The board representation

The bot embed has three parts:

1. Solved groups at the top, in difficulty order (yellow → purple), each line showing the colour emoji, the category title, and the four words.
2. Mistakes remaining as a row of four squares: ⬛ for each remaining mistake, ✖️ for each used.
3. Status message showing the result of the last action.

Below the embed, an action row holds the word buttons (4 per row, up to 4 rows for 16 words; the row count shrinks as you solve groups) plus a control row with Shuffle, Deselect, and Submit. When the game ends, all buttons disappear.

Game lifecycle

Connections game state lives in an in-memory DashMap keyed by Discord channel ID. Two things end a game:

• Completion. A win or a fourth mistake. The bot rewrites the embed with the answer key and removes the buttons.
• Inactivity. A game that hasn’t received a button press in 30 minutes is treated as expired. The next click after expiry gets an ephemeral “Game expired due to inactivity” message and the game is dropped from memory.

Restarting the bot wipes all in-progress games. Nothing about Connections touches the database; there is no persistence and no leaderboard.

Configuration

There is nothing to configure. Connections ships always-on and uses no environment variables. The puzzle archive starts at 2023-06-12 (the first NYT Connections puzzle). Earlier dates return “No puzzle found for date”.

Common issues

• “Use YYYY-MM-DD format” — your date argument didn’t parse as an ISO date. Examples that work: 2024-01-15, 2023-06-12.
• “No puzzle found for date YYYY-MM-DD” — the date parsed but is before 2023-06-12 (the first NYT Connections puzzle) or NYT has no puzzle for that day.
• “There’s already a Connections game in progress in this channel” — someone started a game and it hasn’t finished or timed out (30 minutes idle). Finish the game or wait it out.
• “NYT served a different date than requested” warning above the board — happens when NYT’s rollover lags the requested date. The bot still posts the puzzle.
• “Select exactly 4 words before submitting” — the Submit button is meant to be disabled until you have four selected, but if you press it via tooling that ignores the disabled state, you’ll get this ephemeral notice.
• “No active game in this channel” when pressing a word button — the previous game expired or was replaced. Start a new one.
• The board doesn’t shrink when I solve a group — it does, but Discord caches embeds aggressively in some clients. Refresh the channel.
• Two people clicking words at the same time fight each other — the bot serializes each click through a per-game lock, so there’s no race, but you may briefly see a button toggle on/off if two users click the same word in quick succession.
• Today’s puzzle isn’t available yet — the NYT publishes the new puzzle around midnight Eastern. Until then the bot’s “today” date (UTC) may resolve to a not-yet-available puzzle and you’ll get the “No puzzle found” error. Try !m connections date <yesterday>.

Cross-references

• Wordle — sister command, same daily-NYT pattern.
• AI Chat — the AI can invoke connections_start as a tool, so users can say “@bot start Connections” without remembering the command.
• Instance Config — for command_prefix.

Virtual Stock Trading

A play-money trading game backed by real-time stock quotes. Every user in a guild gets a virtual $1,000 portfolio, can buy and sell US-listed stocks at live prices, and can compete against the rest of the server on a leaderboard ranked by total portfolio value.

What it does

• Each (guild, user) pair has its own portfolio: a cash balance and a set of holdings.
• Quotes come from the Finnhub /quote endpoint, using your free or paid FINNHUB_API_KEY.
• Buys and sells settle at the live quote at the moment the order executes (no slippage simulation, no order book).
• Realized profit and loss is computed on each sell, using the weighted-average cost basis tracked in the database.
• A per-server leaderboard ranks the top ten portfolios by total value (cash + holdings at current prices).
• A trade history shows your last ten transactions with timestamps.

The game is per-guild, so the same Discord user has independent portfolios on each server they’re in.

Activation

Stocks is always-on in the sense that the !m stock command tree is always registered. Every command requires FINNHUB_API_KEY in the environment, however. Without it, every subcommand returns:

Stock trading is not configured. The bot owner needs to set FINNHUB_API_KEY.

To activate the feature you need exactly two things:

1. A Finnhub account. The free tier is generous (60 calls/minute) and covers all US equities.
2. The key in your bot’s .env as FINNHUB_API_KEY=….

Restart the bot after editing .env.

Commands

All commands live under the m parent. With the default ! prefix that means !m stock <subcommand>. The prefix is configurable per instance.

Tickers are case-insensitive and normalized to uppercase. The Finnhub universe is US-listed equities — AAPL, MSFT, TSLA, NVDA and so on. Crypto, forex, indices, and non-US listings will return “Could not find stock symbol”.

Examples

!m stock buy AAPL 5            # buy 5 whole shares of Apple
!m stock buy NVDA $250         # spend $250 on Nvidia (fractional shares OK)
!m stock sell AAPL 2           # sell 2 shares
!m stock sell NVDA all         # close the Nvidia position entirely
!m stock price MSFT            # look up Microsoft, no trade
!m stock portfolio @someone    # peek at another user's portfolio
!m stock leaderboard           # see the top 10
!m stock reset                 # nuclear option (with button confirmation)

The bot can also drive these commands via the AI tool layer: ask the bot in plain language (“buy me $500 of Tesla”) and the AI invokes stock_buy with the right arguments. See AI Chat.

How it works

Starting balance

The first time you touch any stock command, the bot calls get_or_create_portfolio and seeds your account with $1,000.00 in cash. From that point on, your balance changes only via buys, sells, and !m stock reset.

Quotes and caching

Every command that needs a live price calls stocks::api::get_quote. The function:

1. Checks the database price cache for that symbol.
2. If a fresh entry exists, returns it immediately. Otherwise hits https://finnhub.io/api/v1/quote?symbol=<TICKER> with the API key in the X-Finnhub-Token header.
3. Caches the result on the way back.

The cache is what keeps you under the Finnhub rate limit when a busy server pulls the leaderboard or many people check the same stock. Quotes contain three numbers: current price, previous close, and the day’s percent change.

Buy and sell semantics

A buy debits cash, increments the holding, and updates the holding’s weighted-average avg_cost. A sell credits cash and computes the realized P/L for that sale: (sell_price − avg_cost) × quantity.

Both buy and sell (and reset) run inside a database transaction that takes a SELECT … FOR UPDATE row lock on the portfolio first, so concurrent trades — including a buy/sell racing against a reset — serialize cleanly instead of double-spending or deleting freshly purchased shares.

Buys are sized one of two ways:

• By share count: !m stock buy AAPL 10 — exactly ten shares. Fractional counts are allowed (!m stock buy AAPL 0.5).
• By dollar amount: !m stock buy AAPL $500 — spend $500, receive $500 / current_price shares. Always fractional.

If you don’t have the cash, the bot replies “Insufficient funds” and the trade is rejected. If you try to sell more than you own, the bot tells you your actual share count and refuses the trade.

Portfolio embed

!m stock portfolio (or just !m stock) shows:

• Your cash balance.
• Each holding: ticker, share count, current price, market value, P/L percent.
• Total value (cash + market value of holdings).
• Total P/L versus the original $1,000 baseline, in both dollars and percent.

The embed border colour reflects whether you’re up (green) or down (red) overall.

Leaderboard

!m stock leaderboard walks every portfolio in the guild, fetches a current quote for every holding, and ranks the top ten by total value. The P/L column is total − $1,000, since that’s the baseline everybody started from. The top three get medals (🥇🥈🥉).

On large servers with many active portfolios this command does a lot of API calls. The price cache absorbs most of it; if you find yourself rate-limited, slow it down or switch to a paid Finnhub tier.

History

!m stock history shows your last ten transactions: buy or sell, share count, price, total amount, and a relative timestamp. Older trades are still in the database — the embed is just capped at ten for readability.

Reset

!m stock reset is destructive. Running it posts a confirmation embed with Confirm and Cancel buttons. Only the user who ran the command can press a button; if 30 seconds pass with no response the confirmation expires and nothing is wiped. Confirm clears all holdings and trade history and resets cash to $1,000.00; Cancel just dismisses the prompt. You can reset as often as you like.

The reset itself runs in the same FOR UPDATE-locked transaction as buys and sells, so a sell that lands at the same instant won’t beat the reset to the holdings table.

Decimal precision

Money math throughout the stocks module uses rust_decimal::Decimal rather than f64. The database columns are NUMERIC(18, 4), so share quantities and cash balances are precision-exact — no floating-point drift on cents or fractional shares from compound buy/sell sequences. Display rounds money to two decimal places (.round_dp(2)) and shares to four (.round_dp(4)), but the stored values keep full precision.

Rate limiting

The buy, sell, and reset commands are throttled per user at 10 requests / 30 seconds by the shared RateLimiters infrastructure. Hitting the cap returns a “Slow down” reply instead of executing the trade. Read-only commands (portfolio, price, leaderboard, history) aren’t gated.

Permissions

There are no Discord permission gates on the stock commands. Anyone in a guild can play. If you want to restrict it, gate the channel itself with role permissions.

Common issues

• “Stock trading is not configured” — FINNHUB_API_KEY is missing or empty. Set it and restart.
• “Could not find stock symbol X” — Finnhub returned 0 for that ticker. Verify on finnhub.io; crypto and non-US equities aren’t on the free tier.
• “Finnhub API returned status 429” — rate-limited. Wait a minute or upgrade your Finnhub tier.
• Stale price — the quote came from cache. Trades use a fresh quote every time.
• Fractional-share rounding looks weird — share counts are stored to four decimals as NUMERIC(18, 4) Decimals (no f64 drift). Display rounds to four decimals for shares and two for money; the stored values keep full precision.
• Lost my position after reset — irreversible by design.
• Markets closed — Finnhub returns the last traded price. Trades still execute; there’s no “market closed” rejection.

Cross-references

• Environment Variables — FINNHUB_API_KEY.
• AI Chat — the stock_buy, stock_sell, stock_price, stock_portfolio, and stock_leaderboard tools.
• Wordle and Connections — the other always-on game features.

Moderation

A small, focused set of moderation commands: temporary bans with automatic expiry, an early-unban override, an active-tempbans listing, and a bulk-message-delete (“nuke”) tool. Every action can optionally be mirrored to an audit-log channel.

What it does

The moderation module is deliberately narrow. It covers the cases where a Discord-native action falls short:

• Tempban — Discord’s built-in ban is permanent; the bot adds an expiry timestamp and a background task that automatically lifts the ban when the duration is up.
• Unban — early termination of a tempban (or removal of any Discord ban), with database bookkeeping to mark the active record as resolved.
• Banlist — a quick view of every active tempban in the guild, with the user, moderator, expiry timestamp (relative), and reason.
• Nuke — bulk delete the most recent N messages in a channel. Useful for cleaning up spam raids and accidental message dumps.

There is no kick command, no timeout command, and no role-assignment command in the moderation module. Discord’s built-in tools cover those well enough that wrapping them adds no value. Auto-role promotions and join-role assignment are separate features (see Auto-Role and Join Features).

Moderation is always-on. There’s no [features] flag and no configuration required — it works out of the box. The audit-log channel is the one optional bit, configured at runtime per guild.

Commands

All commands live under the m parent. With the default ! prefix that means !m <subcommand>. The prefix is configurable per instance.

Permissions are enforced by Poise’s required_permissions attribute — invocations from users without the listed permission are rejected before the command body runs, so unprivileged users get Discord’s standard “missing permissions” error rather than the bot’s own message.

Tempbans in detail

Duration parsing

The duration argument uses the same short-string format as min_age for auto-role: <integer><unit> with no spaces, where unit is s, m, h, d, or w. Examples:

• 30s — 30 seconds
• 15m — 15 minutes
• 2h — 2 hours
• 3d — 3 days
• 1w — 1 week

Combined units (1d12h) are not supported. The maximum is 365 days; anything longer is rejected with “Invalid duration”.

What !m ban actually does

1. Parses the duration; bad input gets Invalid duration. Use: 30s, 5m, 2h, 3d, 1w.
2. Inserts a row into the tempbans table with the guild, user, moderator, expiry timestamp, and reason.
3. Calls Discord’s ban_with_reason with the audit-log reason Tempban by <moderator> (<duration>): <reason>.
4. Replies in the invocation channel with a relative-timestamp footer.
5. If an audit-log channel is configured, posts a richer embed there — see Audit logging.

Automatic expiry

A background task runs every 30 seconds (started about 5 seconds after bot boot), polling the tempbans table for entries whose expires_at is in the past. For each expired entry, the bot calls remove_ban against Discord’s API and marks the row as unbanned in the database. The audit-log reason on the unban call is “Tempban expired”.

This means there’s a worst-case 30-second window between a tempban’s nominal expiry and the user actually being unbanned. Good enough; nobody really notices a tempban resolving 25 seconds late.

Early unban

!m unban @user calls Discord’s unban API and updates the database. If there was no active tempban for that user in the database, the bot still issues the Discord unban (so it works for non-tempban bans too) and appends “(No active tempban was found in the database.)” to the reply, so the moderator knows.

Banlist

!m banlist queries the tempbans table for everything still flagged active in this guild and renders an embed with one line per ban: the user mention, a relative expiry timestamp, the moderator who issued it, and the reason if there was one.

Empty output is “No active tempbans.”

Nuke (bulk delete)

!m nuke <count> fetches the last count + 1 messages in the channel (the + 1 is to swallow the command invocation itself), then bulk-deletes them. Discord’s bulk-delete endpoint refuses messages older than 14 days, so:

• The actual delete count may be lower than count if some of the recent messages are old.
• The reply tells you how many actually got deleted: Deleted **42/100** messages (messages older than 14 days can't be bulk-deleted).

The bot’s own confirmation message is auto-deleted after 3 seconds so it doesn’t sit in the channel. The audit-log embed (if configured) records the action.

The minimum is 1, the maximum is 100. Anything outside that range gets a usage hint instead of running.

Audit logging

Every successful moderation action — tempban, unban, nuke — can be mirrored to a designated channel as a structured embed. Set it up once per guild:

!m setlog #mod-actions

Requires ADMINISTRATOR. The channel ID is stored in the guild_settings.audit_log_channel_id column. Subsequent moderation actions look up that channel and post:

• Tempban / Nuke — red border (#ed4245), title Mod Action: <Tempban|Nuke>, fields for user/moderator/duration (or channel
  • count), timestamped.
• Unban — green border (#57f287), same shape.

If no audit-log channel is set, the action still happens — the audit post is silently skipped.

Audit-log delivery is best-effort: if the bot can’t post to the configured channel (deleted, bot lacks permission, etc.) the moderation action still goes through and the failure is swallowed.

AI moderation

The AI chat layer can invoke moderation tools (tempban, unban, nuke) on behalf of a user. Every AI-initiated moderation call goes through a confirmation embed with Approve and Cancel buttons (only the original requester can press them, requester’s Discord permissions still checked, expires after 30 seconds). See AI Chat: Moderation confirmation.

Rate limiting

The moderation rate limiter applies to both the AI tool path and the prefix commands. !m ban, !m unban, and !m nuke each check the per-user moderation rate limiter before running, so a moderator can’t bypass it by typing the prefix command instead of asking the AI. The Poise required_permissions check still fires first; the rate-limit check follows. Hitting the cap returns a “Slow down” reply and skips the action.

Permissions required

The bot itself needs BAN_MEMBERS (for !m ban and !m unban) and MANAGE_MESSAGES (for !m nuke). Moderators need the same permissions on their own role to invoke the commands.

For !m setlog the moderator needs ADMINISTRATOR. The bot needs SEND_MESSAGES and EMBED_LINKS in the audit-log channel itself.

Common issues

• “Invalid duration” — your duration string didn’t parse. Use 30s, 5m, 2h, 3d, 1w. Combined formats aren’t supported.
• Tempban issued, user comes back after a bot restart — shouldn’t happen. The database is the source of truth and the unban task picks up where it left off.
• !m banlist empty after a restart — only if you wiped the database. The Discord ban list is independent (Server Settings → Bans).
• Nuke deleted fewer messages than asked — Discord’s 14-day bulk-delete limit; the bot reports the actual count.
• Audit log embed missing — wrong channel ID, missing permissions, or !m setlog never ran.
• Unban says “No active tempban was found” — not a bug; the user was banned manually and there’s no tempban row to mark resolved. The unban itself worked.

Cross-references

• Auto-Role — the role-promotion side of moderation tooling.
• Join Features — auto-assigning a role on join, and AI welcome messages.
• AI Chat: Moderation confirmation — how the AI gates moderation tool calls behind a button confirmation.
• Instance Config — for command_prefix.

Auto-Role Promotion

Promote members from one role to another automatically once they cross a configurable activity threshold. Useful for unverified → verified flows, lurker → member graduations, and any other “stick around long enough and you get the upgrade” pattern.

What it does

The auto-role module watches every member who currently holds a designated from_role and promotes them — adding to_role and removing from_role — once they meet your criteria. The criteria are simple:

• Minimum age in the guild (e.g. 3d).
• Minimum messages sent in the guild (e.g. 20).

You decide whether either condition is enough to trigger promotion (require_all = false, the default), or whether both must hold (require_all = true).

Two checks run in parallel so promotions feel snappy without depending solely on activity:

1. Live, on every message. When a member posts in the guild, the bot increments their message count and immediately checks whether they now meet the threshold. If so, the promotion fires asynchronously.
2. Background, every 60 seconds. A scheduled task scans every unpromoted member, including ones who’ve gone quiet, and promotes anyone whose age-in-guild has crossed the line.

Together this means a chatty user is promoted within a few seconds of hitting the message threshold; a silent user is promoted within a minute of crossing the age threshold.

Activation

Auto-role is opt-in. Enable it in config.toml:

[features]
auto_role = true

[auto_role]
from_role    = "123456789012345678"   # the role to remove
to_role      = "987654321098765432"   # the role to grant
min_age      = "3d"
min_messages = 20
require_all  = false

Restart the bot after editing. The startup logs will show:

Auto-role module enabled (from=…, to=…, min_age=3d, min_messages=20, require_all=false)
Auto-role time checker started (60s interval).

If you set features.auto_role = true but omit the [auto_role] section, the bot logs a warning and the feature stays off — it doesn’t refuse to boot. See docs/configuration/instance-config.md for the field reference.

Configuration

Snowflake IDs, not role names

Both from_role and to_role are role IDs as strings (Discord snowflakes), not role names. To get a role’s ID: in Discord, turn on Developer Mode (Settings → Advanced → Developer Mode), then right-click the role in Server Settings → Roles and choose “Copy ID”.

Duration format

min_age accepts a single integer-with-unit string: 30s, 15m, 2h, 3d, 1w. No combined units. Maximum 365 days. The default is 3d.

Combining criteria

With require_all = false (the default), the bot promotes as soon as either condition holds. A user who’s been in the guild for four days but has never spoken still gets promoted on the next 60-second tick. A user who joined ten minutes ago and has already sent 30 messages gets promoted the moment their 20th message lands.

With require_all = true, both conditions must hold. Same flow, but neither condition alone is enough to fire the promotion.

How it works

Tracking activity

The first time the bot sees a message from a user in a guild with auto-role enabled, it inserts a row into the member_activity table with message_count = 1 and first_seen = NOW(). Every subsequent message increments message_count. The promoted flag on the row starts as FALSE and flips to TRUE after a successful promotion.

first_seen is set on the first observed message, not on the member’s actual join timestamp. A user who joined the guild before auto-role was enabled — or before the bot was running — is treated as “first seen” the next time they post. This is intentional: the bot can’t promote someone it has no record of, and falling back to join time would risk batch-promoting half the server the moment you enable the feature.

If you want to backfill historical members, the cleanest path is to manually add to_role to existing members and let the auto-role flow only handle newcomers.

The two promotion paths

Live path (src/events/mod.rs::handle_message): on every non-bot guild message, the bot increments the user’s count and immediately checks meets_criteria. If true, it spawns a task that calls try_promote. This is where the message-count threshold gets caught.

Background path (src/main.rs): a long-lived task wakes up every 60 seconds, queries the member_activity table for every row with promoted = FALSE in the configured guild, evaluates each one against the criteria, and promotes whoever qualifies. This is where the age-only path gets caught.

The two paths converge on the same try_promote function, which:

1. Adds to_role to the member.
2. Removes from_role.
3. Sets promoted = TRUE in the database.

Both Discord API calls have the audit-log reason “Auto-role promotion”, so the action is identifiable in the guild’s audit log.

Multi-instance / multi-guild scope

Auto-role is configured per bot instance, not per guild. The background task uses the GUILD_ID env var to know which guild to scan. If you want different thresholds in different guilds, run separate bot instances with separate config.toml files. See Multiple Instances.

Permissions

The bot’s role must:

• Be higher in the role list than both from_role and to_role (Discord enforces role-hierarchy on add/remove).
• Have the Manage Roles permission.

Without either, the promotion call will fail and the bot will log Auto-role promotion failed: … for that user. The row stays promoted = FALSE, so the next tick will retry — possibly forever, until you fix the permissions.

Common issues

• Nobody is being promoted — confirm the startup log shows Auto-role module enabled and Auto-role time checker started. If only the first, the [auto_role] section is missing or the role IDs failed to parse.
• One user stuck at promoted = FALSE — bot’s role isn’t above both target roles, or it lost MANAGE_ROLES. Check the logs around the promotion attempt.
• Existing members aren’t being promoted — expected. The scan only sees members who have a member_activity row, created on their first observed message. Silent members stay invisible until they post.
• Promotion is late — bounded by the 60-second background tick for age-only promotions. The live (message-count) path is near-instant.
• Re-promote a user who lost the role — flip promoted back to FALSE on their member_activity row in the database; the next tick re-promotes.
• Invalid from_role ID warning — value isn’t a numeric snowflake. Copy the role’s ID, not its name.

Cross-references

• Instance Config: [auto_role] — full schema reference.
• Join Features — for auto-assigning a role the moment someone joins, before they hit the activity threshold.
• Moderation — for tempbans and bulk delete, the manual side of mod tooling.
• Multiple Instances — how to run different auto-role configs in different guilds.

Member Join Features

Two independent features that fire when a new member joins a guild: an automatic role assignment (“join role”), and an AI-generated welcome message (“welcome”). Either can be enabled without the other; they’re configured in separate sections of config.toml.

Both react to the same Discord event (GuildMemberAddition) and run sequentially in the bot’s member_join handler. If you have both enabled, the join-role assignment happens first, then the welcome message is generated and posted.

Join role

The simplest behaviour the bot ships with: when a new member joins, add a single role to them.

The most common use is marking unverified accounts so they can’t see sensitive channels until they go through whatever onboarding flow you have set up. Another common use is granting a default colour role so new members aren’t completely roleless on arrival.

Activation

Enable in config.toml:

[features]
join_role = true

[join_role]
role = "123456789012345678"   # the role ID to assign

Restart the bot. The startup log will show:

Join-role module enabled (role=123456789012345678)

If you set features.join_role = true but omit the [join_role] section, the bot logs a warning and the feature stays off rather than refusing to boot.

Configuration

That’s it. There is no per-guild override (it applies to every guild the bot instance serves), no exclusion list, and no condition. If a member joins, they get the role.

How it works

src/events/member_join.rs::handle_member_join is invoked by the event dispatcher every time a GuildMemberAddition event fires. The first thing it does is check data.join_role_config. If present, it parses the role ID and calls add_member_role with the audit-log reason Auto join role. Failures are logged but otherwise swallowed — the bot doesn’t try to retry.

Permissions

The bot’s role must be above the configured role in the role hierarchy and have MANAGE_ROLES. Without that, the assignment will fail with a Discord permission error and the member will be left without the role. Watch the logs for Failed to assign join role to <user>: ….

Common issues

• Role isn’t being assigned — bot’s role lacks MANAGE_ROLES or sits below the target role in the hierarchy.
• Members joined while the bot was offline — there’s no catch-up. The handler only fires for live GuildMemberAddition events. Existing roleless members need to be batched manually.
• Invalid join role ID warning — the configured role value isn’t a numeric snowflake. Make sure Developer Mode is on and you copied the role’s ID, not its name.

Welcome messages

When a new member joins, the bot can post an AI-generated welcome message to a designated channel. The message uses your bot’s personality plus an additional welcome-specific prompt to produce something on-brand and member-specific (mentions the new user, ideally riffs on their display name).

Activation

Welcome messages have three prerequisites:

1. features.welcome = true in config.toml.
2. A [welcome] section pointing at the channel and an optional custom prompt file.
3. At least one AI provider key — DEEPSEEK_API_KEY or GEMINI_API_KEY — in .env.

If you set the flag but skip the prompt file, the welcome stays off silently (logged at warn level). Same if neither AI key is set.

[features]
welcome = true

[welcome]
channel     = "123456789012345678"          # where to post the welcome
prompt_file = "welcome_prompt.txt"          # default; relative to config dir

Then create welcome_prompt.txt next to config.toml. This is not the bot’s overall personality — that’s personality.txt, loaded for AI chat. The welcome prompt is appended to the personality and tells the model specifically how to write a welcome.

A short welcome prompt might look like:

Write a one-paragraph welcome message for the new member.
Keep it under 80 words, be warm but on-brand, and mention them
by their Discord display name (already provided in the user
message). Suggest one channel they should check out first.

How it works

After the join-role step, handle_member_join checks for both welcome_config and welcome_prompt. If both are present, it:

1. Rate-limits per user. Each joining user gets their own 5-second budget through the shared RateLimiters infrastructure (1 request / 5 seconds, keyed on the joining user’s ID). A single user re-joining repeatedly is throttled, but a raid of distinct users all get their own welcomes.
2. Picks a provider. If DEEPSEEK_API_KEY is set, use DeepSeek (deepseek-v4-flash). Otherwise fall back to Gemini (gemini-3-flash-preview). Both providers are called via their OpenAI-compatible chat endpoints.
3. Builds the system prompt. Concatenates the bot’s full personality file with the welcome prompt under a ## Welcome Message Instructions heading.
4. Sends one user message. It tells the model the new member’s display name and mention string and asks it to write a welcome.
5. Posts the model’s response. The reply text goes straight to the configured channel as a regular message (no embed).

The request has a 30-second timeout and a 512-token max. Failures (API down, model returns empty content, channel doesn’t exist, bot lacks permission) are logged at warn and silently swallowed — no fallback “Welcome!” message is sent.

Configuration

Rate limiting

Welcome generation is rate-limited per joining user through the bot’s shared RateLimiters infrastructure: 1 request per 5 seconds, keyed on the new member’s user ID. The same user re-joining within the window gets a single welcome; ten distinct users joining inside the same five seconds get ten welcomes (one each).

This is the fix for the older global-mutex rate limit, which suppressed legitimate joins during a raid: a burst of 10 joiners used to produce one welcome and nine silent skips. Now the limiter only throttles a single user’s repeated joins, not the whole channel.

Permissions

The bot needs SEND_MESSAGES and the standard message-content permissions in the welcome channel. It does not need EMBED_LINKS since welcomes are plain text. If permissions are missing, the bot logs Failed to send welcome message: … and moves on.

Cost

One AI call per join, capped at 512 output tokens. On DeepSeek V4-Flash that’s a fraction of a cent per welcome — even an active server won’t notice the bill. If you’re using Gemini, the free tier covers most casual join volumes; check https://ai.google.dev/pricing for current rates.

Common issues

• No welcome appears — check the logs at startup. If you don’t see Welcome module enabled, either features.welcome = false, the [welcome] section is missing, or the prompt file is missing/empty. If you do see the enabled line but no AI key warning, verify DEEPSEEK_API_KEY or GEMINI_API_KEY is in the running environment.
• Welcome appears but the personality is wrong — the personality file is loaded once at boot. Restart the bot after editing personality.txt or welcome_prompt.txt.
• Welcome is generic / boring — the welcome prompt is inheriting the bot’s overall personality. Make the prompt more specific — tell it the server’s tone, what to highlight, what to avoid.
• The same user keeps re-joining and only gets one welcome — the per-user 5-second rate limiter. Distinct users in a raid each get their own welcome; a single user looping through join/leave/join is throttled.
• Welcome posted to wrong channel — verify the snowflake ID in [welcome].channel is for the channel you actually meant. No mention syntax; just the raw ID as a string.

Cross-references

• Instance Config: [join_role] and [welcome] — schema references.
• AI Chat — how the AI provider stack works; welcomes reuse it.
• Personality Files — where personality.txt and welcome_prompt.txt are sourced.
• Auto-Role — for the post-join “graduate the member” promotion flow.
• Secrets Management — where to put DEEPSEEK_API_KEY and GEMINI_API_KEY safely.

Minecraft: Verify

Link Discord accounts to Minecraft accounts. The user generates a verification code on the Minecraft server, types it into Discord with !m verify, and the bot calls the Minecraft server’s HTTP API to confirm the link.

This is the foundational sub-feature of the Minecraft module. The donator sync and chargeback features both rely on the Discord ↔ Minecraft mapping that verify produces.

What it does

A typical flow:

1. A player joins your Minecraft server and runs an in-game /verify command. The companion plugin generates a short alphanumeric code, stores it server-side with a TTL, and tells the player to type !m verify <code> in Discord.
2. The player runs !m verify <code> in any Discord channel where the bot can read messages.
3. The bot POSTs the code plus the player’s Discord ID to the Minecraft server’s /api/verify endpoint.
4. The Minecraft server validates the code, links the Discord ID to the player’s Mojang UUID, and responds with success + username.
5. The bot replies in Discord with Verified! Your Discord account is now linked to **<username>** in Minecraft.

Once linked, that mapping powers everything else the Minecraft module does — donator role sync, chargeback alerts, and any future features that need to know who-is-who across the two platforms.

Activation

Verify is part of the Minecraft module. Three things have to line up in config.toml:

[features]
minecraft = true

[minecraft]
verify = true   # default; can be omitted

[minecraft.donator_sync_config]
# unrelated, but [minecraft] needs to exist

And two environment variables in .env:

MC_VERIFY_URL=https://your-mc-server.example.com
MC_VERIFY_SECRET=long-random-string-shared-with-the-mc-plugin

MC_VERIFY_URL is the base URL of the Minecraft companion plugin’s HTTP server (no trailing slash needed; the bot strips it). The bot appends /api/verify for the verify call.

MC_VERIFY_SECRET is a shared bearer token. The bot sends it as Authorization: Bearer <secret>; the plugin must compare against the same value. Treat it like a password — anyone with this secret can issue verify (and ban) calls against the MC server.

verify defaults to true inside the [minecraft] section, so enabling the Minecraft module is enough to enable verify. Set verify = false only if you want donator sync or chargeback without exposing the verify command.

The !m verify command is registered conditionally at startup — if features.minecraft is false or minecraft.verify is false, the command isn’t added to the parent command tree at all. Users typing !m verify see the standard “command not found” response.

Commands

If the user runs !m verify with no code, the bot replies:

Usage: !m verify <code> — get your code by running /verify in Minecraft.

If MC_VERIFY_URL or MC_VERIFY_SECRET is missing from the environment, the command refuses with:

MC verification is not configured. Set MC_VERIFY_URL in .env

(or the same about MC_VERIFY_SECRET).

How it works

src/minecraft/api.rs::verify is a thin POST against <MC_VERIFY_URL>/api/verify with the body:

{
  "code": "ABC123",
  "discord_id": "987654321098765432"
}

and the Authorization: Bearer <MC_VERIFY_SECRET> header. The Minecraft plugin is expected to respond with JSON of the shape:

{ "success": true,  "username": "Steve", "uuid": "069a79f4-..." }

or, on failure:

{ "success": false, "error": "Invalid or expired code" }

The bot turns the success path into a Discord confirmation message including the linked Minecraft username. On success: false it echoes the error string back to the user, so the plugin’s error copy (“expired”, “code already used”, etc.) reaches the player unchanged. On HTTP/transport failure the bot replies Could not reach the MC server: <error> so the user knows the linkage didn’t happen because of infrastructure rather than a bad code.

The bot does not store the linkage itself. The Minecraft side is the source of truth. Other Minecraft sub-features (donator sync, chargeback) re-fetch the mapping from the same plugin when they need it.

The Minecraft side

This module only describes the Discord side of the integration. The companion plugin on the Minecraft server is its own thing — ours implements /api/verify, /api/donators, and /api/ban endpoints, plus a chargeback webhook that POSTs to the bot. If you’re rolling your own integration, the contract is:

• POST /api/verify — accepts {code, discord_id}, returns {success, username, uuid, error}. Auth via bearer token.
• The plugin is responsible for issuing codes, validating them, enforcing TTLs, and persisting Discord ↔ UUID mappings.

For the source-of-truth wire format, see src/minecraft/api.rs in the bot codebase.

Permissions

The bot needs no special Discord permissions for verify itself — just the standard SEND_MESSAGES to reply in the channel where the command was invoked. There’s no role assignment step on successful verification; that’s left to the plugin (which can trigger donator sync separately) or to a server admin.

Common issues

• “MC verification is not configured” — MC_VERIFY_URL or MC_VERIFY_SECRET is missing from the running environment. Make sure your .env is being passed in (Docker users: env_file: .env in compose.yaml).
• “Could not reach the MC server” — the bot can’t contact the URL. Check that MC_VERIFY_URL is reachable from the bot’s network (try curl from inside the bot container), and that the plugin’s HTTP listener is up.
• “Verification failed: invalid or expired code” — the Minecraft plugin rejected the code. The most common causes are typos, codes that have already been used, or codes that TTL’d out (most plugins expire codes after a few minutes).
• 401 Unauthorized in bot logs — MC_VERIFY_SECRET doesn’t match the value the plugin expects. Make sure both sides have the exact same string (no trailing whitespace).
• !m verify says “command not found” — features.minecraft or minecraft.verify is false, or the bot wasn’t restarted after enabling them.
• The verification succeeded, but donator roles still aren’t syncing — verify only creates the mapping. Donator role assignment is a separate sub-feature; see Minecraft: Donator Sync.

Cross-references

• Minecraft: Donator Sync — uses the Discord ↔ UUID mapping that verify produces.
• Minecraft: Chargeback Alerts — reaches out from the MC server to Discord using the same mapping.
• Instance Config: [minecraft] — schema reference.
• Environment Variables — MC_VERIFY_URL, MC_VERIFY_SECRET.
• Secrets Management — how to keep the shared secret out of source control.

Minecraft: Donator Sync

Periodically poll a Minecraft server’s donator list and reconcile two Discord roles — supporter_role and premium_role — so that the right people have the right perks at any moment, without anyone having to manually grant or revoke them.

The companion to this feature is the chargeback flow, which handles the reverse case: someone files a chargeback, their Discord roles get stripped, and a staff alert is posted.

What it does

The donator sync background task wakes up every check_interval seconds, calls the Minecraft companion plugin’s /api/donators endpoint, and reconciles the response with the current state of the guild. After each tick:

• Anyone who’s a supporter on the MC server but doesn’t have the supporter role gets it.
• Anyone who’s a premium donator but doesn’t have the premium role gets it.
• Anyone who has either role on Discord but isn’t on the MC list loses it (their donation expired or was revoked).
• Tier upgrades (supporter → premium) and downgrades (premium → supporter) are handled correctly: the old role is removed when the new one is added.
• Anyone with the chargeback restricted role is skipped entirely — sync never re-grants donor perks to a user being held by a chargeback alert.

The sync is bidirectional state reconciliation, not an event stream. There’s no “donator added” notification; the bot just queries the source of truth and patches the difference.

Activation

Donator sync is part of the Minecraft module. You need:

[features]
minecraft = true

[minecraft]
donator_sync = true

[minecraft.donator_sync_config]
supporter_role = "123456789012345678"
premium_role   = "234567890123456789"
check_interval = 300                        # seconds; default 300 (5 min)

Plus, in .env:

MC_VERIFY_URL=https://your-mc-server.example.com
MC_VERIFY_SECRET=long-random-string-shared-with-the-mc-plugin

(The same MC_VERIFY_* pair as verify and chargeback. One pair, three sub-features.)

Restart the bot. The startup log will show:

Donator sync enabled (supporter=…, premium=…, interval=300s)
Donator sync checker started (300s interval).

The first sync runs about 15 seconds after bot boot, then every check_interval seconds after that.

If donator_sync = true but the [minecraft.donator_sync_config] section is missing, or MC_VERIFY_URL/MC_VERIFY_SECRET aren’t set, the bot logs a warning and the sync task never spawns.

Configuration

Both role IDs must be valid snowflakes (numeric strings). Invalid IDs cause the entire sync to abort with a logged warning rather than partially executing.

The default check_interval of 5 minutes is conservative. For most deployments that’s fine — donations don’t change often, and the five-minute lag is invisible to users. Push it lower (e.g. 60) only if you have a use case that needs faster sync.

How it works

src/minecraft/donator_sync.rs::sync_roles runs in five logical phases per tick:

1. Fetch. Call <MC_VERIFY_URL>/api/donators with the shared secret. Response shape:

   {
     "donators": [
       { "discord_id": "987654321098765432", "tier": "supporter" },
       { "discord_id": "234567890123456789", "tier": "premium" }
     ]
   }
   

2. Build target sets. Walk the response and produce two sets: should_have_supporter and should_have_premium. Unknown tiers (anything that isn’t supporter or premium) are logged as warnings and ignored.

3. Snapshot current state. Call Discord’s get_guild_members (paginated, 1000 per page) and build three sets: current_supporters, current_premium, and restricted_users (anyone with the chargeback-restricted role, if chargeback is also configured).

4. Add missing roles. For each user who should have a tier but doesn’t, call add_member_role with the audit-log reason `Donator sync: {tier} tier`. Restricted users are skipped.

5. Remove stale roles, then handle tier transitions. Anyone who has a tier role but isn’t on the MC list loses the role (“Donator sync: {tier} expired”). Anyone whose tier moved gets the old role removed (“upgraded to premium” or “downgraded to supporter”).

The sync is idempotent — running it twice in a row does no extra work the second time, since the desired and current states already match.

The restricted-role short-circuit

If the chargeback feature is configured, donator sync also reads chargeback_config.restricted_role and treats it as a “do not touch” set. Any member with that role is skipped during all five phases. The reasoning: a user under a chargeback hold should not have donor perks restored automatically just because the MC server hasn’t yet pulled them off its donator list.

If chargeback isn’t configured, no restriction set is built and this short-circuit doesn’t apply.

Pagination

Guilds with many members are paginated 1,000 at a time. The loop breaks once a page returns fewer than 1,000 entries (the standard sentinel for “end of list”). For most servers this is a single page; for very large guilds it’s a handful of API calls per tick.

Permissions

The bot’s role must:

• Be higher than both supporter_role and premium_role in the role hierarchy.
• Have MANAGE_ROLES.

Without those, individual add_member_role / remove_member_role calls fail with permission errors and get logged at warn. The sync continues to the next user; one bad permission on one role won’t break the whole loop.

Common issues

• No sync log line at startup — donator_sync = true but either the config sub-section or MC_VERIFY_* is missing. Check the warning log lines around startup.
• Sync runs but no roles change — the MC server’s /api/donators returned an empty or malformed response. Check the bot’s logs for MC server returned status … or Invalid donator response. Try curl -H "Authorization: Bearer $MC_VERIFY_SECRET" $MC_VERIFY_URL/api/donators from the bot host.
• Roles get added then removed seconds later — the MC server is returning inconsistent data between calls (e.g. an unstable cache). Pin down whether the source data is stable; the sync is idempotent on stable input.
• Restricted-role users are losing their donor role — that’s the intended behaviour during a chargeback hold. Roles are not removed for them — they’re just not added by sync. To restore them, lift the chargeback restriction first.
• Invalid supporter_role ID warning — one of the snowflake fields isn’t a numeric string. Snowflakes are quoted strings in TOML; make sure you have supporter_role = "123…" and not supporter_role = 123… (TOML integers can’t represent Discord snowflakes accurately).
• Sync feels slow — check_interval is 5 minutes by default. Lower it if you need faster reconciliation, but bear in mind every tick fetches the full member list from Discord and the donator list from MC.
• Tier change took effect on MC but Discord lags — bounded by the next check_interval tick. There’s no event hook for faster propagation.

Cross-references

• Minecraft: Verify — required precursor for any Discord ↔ MC mapping.
• Minecraft: Chargeback Alerts — the inverse flow; donator sync reads the restricted role this feature applies.
• Instance Config: [minecraft.donator_sync_config] — schema reference.
• Environment Variables — MC_VERIFY_URL, MC_VERIFY_SECRET.

Minecraft: Chargeback Alerts

When a player files a chargeback against a purchase on your Minecraft server, the bot reacts immediately: it strips the player’s Discord roles, applies a “restricted” role, and posts a staff alert with Ban and Dismiss buttons. Staff can ban (Discord + Minecraft) or dismiss with a click.

This closes the loop on the donor flow: verify creates the Discord ↔ Minecraft mapping, donator sync keeps roles in line with active donations, and chargeback alerts handle the case where a donation gets reversed.

What it does

The MC store (Tebex, Buycraft, or whatever you use) is wired up to POST a chargeback notification to the bot’s HTTP listener at /webhook/chargeback. On receipt:

1. Authenticates the request via Authorization: Bearer <MC_VERIFY_SECRET>. Mismatched or missing tokens get a 401 Unauthorized and no further processing.
2. Strips and restricts. If the chargeback payload includes a linked discord_id, the bot calls edit_member on Discord with a fresh roles list of just [restricted_role] — wiping every other role the user had — and an audit-log reason Chargeback: roles stripped, user restricted.
3. Posts a staff alert to the configured staff channel, showing the player’s MC username, tier, UUID, the linked Discord account (if any), and a timestamp. Two buttons sit at the bottom: 🔨 Ban and ❌ Dismiss.
4. Returns 200 to the MC store so the chargeback notification isn’t retried.

The Ban button issues a Discord ban (if the user is linked) and a Minecraft ban (via <MC_VERIFY_URL>/api/ban). Dismiss closes the alert without further action. Either way the embed is rewritten with a footer recording who took the action (“Banned by alice” or “Dismissed by bob”) and the buttons are removed so the alert can’t be acted on twice.

Activation

Chargeback alerts are part of the Minecraft module. You need:

[features]
minecraft = true

[minecraft]
chargeback = true

[minecraft.chargeback_config]
staff_channel   = "123456789012345678"
restricted_role = "234567890123456789"
staff_roles     = ["345678901234567890", "456789012345678901", "567890123456789012"]

Plus the standard MC env vars in .env:

MC_VERIFY_URL=https://your-mc-server.example.com
MC_VERIFY_SECRET=long-random-string-shared-with-the-mc-plugin

The chargeback listener is mounted onto the bot’s existing HTTP server (the one the MCP server uses) at POST /webhook/chargeback. There’s no separate port; the bot’s HTTP listener handles both. See MCP Server for how to expose the HTTP listener publicly.

The webhook router only spins up if all three preconditions hold: the chargeback feature is enabled, the config sub-section is present, and MC_VERIFY_URL + MC_VERIFY_SECRET are both set. Missing any one of those quietly disables the route — the bot starts cleanly, but no chargeback alerts will ever fire.

Configuration

staff_channel and restricted_role must be valid snowflakes. Invalid values cause the webhook to return 500 Internal Server Error and log the bad config; the underlying chargeback isn’t lost on the MC side, but no alert gets posted on the Discord side until you fix the config. Entries in staff_roles that don’t parse as integers are silently skipped, so a typo will quietly remove that role from the allowlist — double-check the IDs if buttons aren’t working for staff who you expect to have access.

The restricted role’s purpose is twofold:

• It marks the user as “currently in a chargeback hold” so donator sync doesn’t re-grant their donor perks on the next tick.
• Combined with channel-level permissions on your server, it isolates the user from sensitive channels until staff resolves the alert.

Set the role’s permissions and channel overrides to whatever “banned but not yet acted on” means for your server.

The webhook payload

The MC plugin POSTs JSON in this shape:

{
  "uuid":       "069a79f4-44e9-4726-a5be-fca90e38aaf5",
  "username":   "Steve",
  "discord_id": "987654321098765432",
  "tier":       "supporter",
  "timestamp":  "2026-04-15T18:00:00Z"
}

discord_id is optional — if the player never verified, it’s null and the bot only takes MC-side action via the staff button. The wire format lives in src/minecraft/chargeback.rs::ChargebackPayload. Authentication is the shared MC_VERIFY_SECRET sent as Authorization: Bearer <secret>; treat the secret like a credential.

The staff alert

The alert embed has a red border and the title ⚠️ CHARGEBACK ALERT, with fields for Player, Tier, Discord (<@id> (id) or Not linked), MC UUID, and Time. The footer summarizes the automatic action: All roles stripped. User restricted. (linked) or No Discord account linked. MC-side actions only. (unlinked).

Two buttons sit beneath: 🔨 Ban (or Ban MC if unlinked) and ❌ Dismiss. Only members with one of the roles listed in staff_roles (see Staff role gating below) can press either — anyone else gets You don't have permission to do this.

After a button is pressed the embed is rebuilt with a neutral border, the footer is replaced with Banned by <staff> or Dismissed by <staff>, and the buttons are removed.

Ban action

When a staff member clicks Ban:

1. Discord side. If the embed shows a linked discord_id, the bot extracts it and calls ban_user with audit-log reason Chargeback ban by <staff>. Failures are logged but don’t block MC side.
2. MC side. The bot POSTs to <MC_VERIFY_URL>/api/ban with the player’s UUID and a reason identifying the staff member.
3. Failure surfacing. If the MC ban returns non-2xx or transport-fails, the bot reposts the failure into the staff channel: ⚠️ MC ban failed for UUID {uuid}: {status} {body}.

Dismiss action

Clicking Dismiss doesn’t restore anything — the roles are already stripped and the restricted role applied. It just closes the alert with a footer recording who dismissed it. To restore a user, staff manually removes the restricted role and re-adds whatever roles they had before; stripped roles aren’t preserved.

Staff role gating

Button permission checks read the staff_roles list from [minecraft.chargeback_config]. A member must hold at least one of the listed roles to press either Ban or Dismiss; everyone else gets You don't have permission to do this. as an ephemeral reply.

The list is #[serde(default)], so omitting staff_roles entirely (or leaving it as []) means no one can use the buttons — the alert still posts and the auto-strip still happens, but the alert can’t be confirmed or dismissed from Discord. This is the safe default for a feature that’s opt-in per instance: you must explicitly grant button access.

Add as many or as few roles as you want — typically Moderator, Admin, and Owner, but anything you wire up works:

staff_roles = ["111111111111111111", "222222222222222222", "333333333333333333"]

Entries that don’t parse as u64 are silently dropped at button-handler time, so a malformed snowflake will quietly remove that role from the allowlist without preventing the others from working.

Permissions

The bot’s role must:

• Be higher than the restricted role and any roles it might need to strip on offenders, in the role hierarchy.
• Have MANAGE_ROLES (to apply the restricted role and strip roles) and BAN_MEMBERS (for the Ban button).
• Have SEND_MESSAGES and EMBED_LINKS in the configured staff_channel.

Without BAN_MEMBERS the auto-strip will succeed but the Ban button will fail; the alert will still post and dismiss.

Common issues

• No alert appears after a chargeback — check the bot logs for Chargeback webhook received: …. If absent, the MC plugin isn’t POSTing to the right URL or the HTTP listener isn’t exposed. If present but no embed posts, check staff_channel and bot permissions there.
• 401 Unauthorized on the webhook — MC_VERIFY_SECRET doesn’t match between bot and plugin.
• Roles aren’t stripped on the offender — only happens when the payload includes a linked discord_id. Unverified users get no Discord-side action; the alert footer says so.
• Ban button does nothing for non-staff — staff role gate. Add the staff member’s role to staff_roles in [minecraft.chargeback_config] and restart the bot. If staff_roles is empty (the default), no one can press the buttons.
• MC ban failed — the /api/ban endpoint returned an error. The bot reposts the failure into the staff channel; check the response body.
• Dismiss didn’t restore the user’s roles — by design. Restoring stripped roles is a manual operation.

Cross-references

• Minecraft: Verify — for the Discord ↔ UUID mapping that determines whether chargeback can act Discord-side.
• Minecraft: Donator Sync — uses the restricted role as a “do not re-grant donor perks” signal.
• MCP Server — how the bot’s HTTP listener is hosted; the chargeback webhook lives on the same router.
• Instance Config: [minecraft.chargeback_config] — schema reference.
• Environment Variables — MC_VERIFY_URL, MC_VERIFY_SECRET.

MCP Server

The bot embeds a Model Context Protocol (MCP) server that exposes Discord server-management as 51 tools any MCP client can call. The intended workflow is to point an AI coding assistant — Claude Code, Cursor, etc. — at the bot and let it manage your Discord server programmatically.

What it does

When the bot starts, it spins up an HTTP server on a configurable port (default 9090) and registers the tool catalog with the standard MCP streamable-HTTP transport. An MCP client connects, lists the available tools, and can then invoke them. Every tool runs against the same Discord HTTP client the bot itself uses, so the actions execute as the bot user with the bot’s permissions.

The point of this is that you can talk to your Discord server in natural language from inside an AI assistant:

“Find the channel category called Archive and move all read-only channels into it.”

“List every member with the @Verified role who hasn’t sent a message in 30 days.”

“Create a new role ‘Beta Testers’, colour green, no permissions, and assign it to these five users.”

Instead of writing Discord API code or clicking through the Discord UI, your AI assistant calls the matching MCP tools.

Why this exists

Discord administration is full of repetitive multi-step operations: auditing roles, cleaning up old channels, mass-renaming, bulk permission changes. The Discord client doesn’t have a scripting interface, and writing one-off API scripts for every cleanup task is tedious. An LLM with the right tools can plan the operation, ask for confirmation, and execute it in a couple of turns.

The bot is also a natural place to put this server: it is already a long-running process holding the Discord HTTP client, with the right intents and a privileged token. Adding an MCP endpoint costs almost nothing in startup time and gives you a remote-control interface for free.

The protocol

Model Context Protocol is an open JSON-RPC-based protocol from Anthropic that lets clients (LLMs and IDE extensions) discover and call tools exposed by servers. The bot uses the Streamable HTTP transport, which is a simple HTTP-and-SSE flavour of MCP (no stdio handshakes, no daemon-spawning).

The server is built on the rmcp Rust SDK. Tool definitions are written as decorated async fns on a single DiscordTools struct in src/mcp/tools.rs; the #[tool(description = "...")] attribute generates the JSON schema from each function’s parameter type.

Connecting Claude Code

The simplest way to test the server is to add it to your local Claude Code config (~/.claude.json):

{
  "mcpServers": {
    "discord": {
      "type": "http",
      "url": "http://localhost:9090/mcp"
    }
  }
}

Then restart Claude Code. The next time you start a session, the discord server should appear in your tool list and you can call any of the 51 tools by name.

If you’ve set MCP_AUTH_TOKEN (see below), add the bearer token to the same entry:

{
  "mcpServers": {
    "discord": {
      "type": "http",
      "url": "http://localhost:9090/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

Other MCP-capable clients (Cursor, Continue, custom code) follow the same pattern: point them at http://<host>:<port>/mcp over HTTP and optionally pass a bearer token.

Tool catalog

The 51 tools are grouped into five categories. The full reference, including parameter schemas, lives in Reference: MCP Tool Catalog. The table below is the one-line summary.

Guilds

Server

Channels

Roles

Members

Direct Messages

Webhooks

Invites

Custom Emoji

That’s 51 tools total: 1 + 7 + 9 + 4 + 14 + 4 + 4 + 4 + 4.

Multi-guild support

Almost every tool takes an optional guild_id parameter. When it’s omitted, the tool acts against the bot’s configured guild — the one named in the GUILD_ID env var. When it’s supplied, the tool acts against that guild instead, as long as the bot is a member of it.

This means you can run a single bot across several Discord servers and manage them all through one MCP endpoint. The list_guilds tool is deliberately the one that does not take a guild_id parameter — use it to discover what’s available, then pass the right ID into the follow-up calls.

Port and binding

Two environment variables control the listen address (loaded in src/config.rs):

The defaults are chosen so that a fresh install is not exposing anything to the public internet. To make the server reachable from other machines on a private network, set MCP_BIND_ADDR=0.0.0.0 and arrange your own network ACLs. To expose it over the public internet at all, see the security section below first.

Authentication

A third environment variable controls authentication:

The middleware in src/mcp/mod.rs is a single from_fn layer:

• If MCP_AUTH_TOKEN is empty, every request is allowed through.
• If it is set, every request must carry a matching Authorization: Bearer <token> header, otherwise it is rejected with 401 Unauthorized.
• The bearer-token comparison is constant-time (via subtle::ConstantTimeEq) so a network attacker can’t use response timing to probe the token byte-by-byte.

Strict startup guard

The bot refuses to start if MCP_AUTH_TOKEN is empty and MCP_BIND_ADDR is not a loopback address. This replaces the older “soft warning” behaviour — the misconfiguration that used to expose an unauthenticated MCP endpoint on the public internet now fails the boot instead, with a pointed error explaining how to fix it. Either set a token or bind to loopback; there is no third option.

The mcp-gateway applies the same rule even more strictly: because it always listens on 0.0.0.0, it refuses to start without MCP_AUTH_TOKEN set, no loopback escape hatch available. The gateway also forwards that same token on every outgoing request to its backends — one shared secret covers both the inbound check and the outbound forward — so operators configure a single value and the bundled docker-compose deploy (where backends bind 0.0.0.0:9090 and therefore require a token themselves) works without extra plumbing.

Request size limit

Every incoming request body is capped at 64 KiB. Oversize bodies are rejected with 413 Payload Too Large. Bodies that fit but aren’t valid JSON-RPC come back with a standards-conformant {"jsonrpc":"2.0","error":{"code":-32700,"message":"Parse error"},"id":null} response rather than a generic 400.

The MCP gateway

If you run multiple bot instances out of the same host (production and staging, or two community bots, etc.), each one binds its own port and exposes its own catalog. Pointing Claude Code at all of them individually means maintaining a list of URLs and switching between them.

The repository ships a separate mcp-gateway service that solves this. It listens on a single port, multiplexes requests to whichever bot’s MCP endpoint they belong to, and presents a unified tool list to clients. Each tool’s schema gains an extra instance parameter (matching a key in the INSTANCES env var, e.g. bot_a or bot_b) which the gateway uses to pick the target bot. A synthetic list_instances tool is appended to the catalog so clients can discover the available instances and their guilds.

The gateway is the recommended entry point in production — see Architecture: MCP Gateway Routing for how it routes and authenticates requests.

Security considerations

The MCP tools are powerful. ban_member permanently removes a user; delete_channel is destructive and unrecoverable; send_message lets the bot post anywhere it has Send Messages permission. There is no in-bot confirmation gate on MCP calls — a misfiring AI agent or a compromised client could do real damage in seconds.

This means the threat model is the MCP endpoint itself is privileged infrastructure. Treat it the same way you’d treat a bare-metal SSH session into your Discord server.

Concrete recommendations:

• MCP_AUTH_TOKEN is required unless bound to loopback. The bot enforces this at startup: if MCP_BIND_ADDR is anything other than a loopback address and the token is unset, the process refuses to boot. Generate the token with openssl rand -hex 32 or similar.
• Default to 127.0.0.1. The default MCP_BIND_ADDR is localhost for a reason. Do not change it unless you’re putting something meaningful in front of it.
• Do not put the port on the public internet. Even with a bearer token, you’re one token leak away from a takeover. Use a WireGuard / Tailscale / SSH tunnel / VPN to reach it remotely.
• Audit the bot’s Discord permissions. The MCP server can only do what the bot itself can do. If you grant the bot Administrator, you’ve granted Administrator to anyone holding the MCP token.
• See Deployment: MCP Exposure for the long-form discussion and example reverse-proxy configurations.

Known limitations

• OAuth 2.1 is not implemented. The MCP spec defines an OAuth-based flow that some clients prefer (Claude Code’s HTTP transport, for instance, expects it). The bot speaks bearer-token auth only, so you’ll see warnings in those clients about the auth mode being unrecognised — they still work, but the OAuth handshake never happens.
• Rate limiting is Discord’s, not ours. The tools call the Discord HTTP API directly with no extra throttling. Bulk operations on members, roles, or messages are bounded by Discord’s rate limits, and a too-eager AI agent will trigger 429 responses you’ll see surfaced as Discord API error: ... in the tool output.
• Per-call API timeout is 10 seconds. API_TIMEOUT in src/mcp/tools.rs. Long-running Discord calls (e.g. fetching a large guild’s full member list) may time out; in that case, page through with smaller limit values.
• Discord permission errors are surfaced as plain strings, not as structured error codes. If a tool says Missing Permissions, the bot itself doesn’t have the permission needed for the operation.
• The timeout_member tool’s reason argument is currently cosmetic — it’s part of the schema for forward compatibility, but the underlying call doesn’t yet thread it through to Discord’s audit log.

Example use cases

• Mass channel cleanup. “List every channel in the #archive-2022 category that hasn’t had a message this year and delete them.” The AI calls list_channels, filters mentally, and invokes delete_channel for each one.
• Role audits. “List every member with the @Donor role and cross-check against the active payment list.” Pair list_members with whatever data source you point the AI at.
• Permissions sweep. “Make sure every channel under the #mods-only category has the @Moderator role allowed and @everyone denied.” set_channel_permissions per channel.
• Bulk message cleanup. “Delete the last 50 messages in #spam.” One call to delete_messages.
• Server bootstrapping. “Create a category ‘Beta’, three text channels under it, and a role with permissions limited to that category.” Several create_channel and create_role calls in sequence.

The general pattern is list-then-act: ask the AI to discover what’s there, then have it execute the change with a clear plan you can approve.

Cross-references

• Architecture: MCP Gateway Routing — how the gateway multiplexes multiple bot instances.
• Deployment: MCP Exposure — safe ways to make the server reachable from outside the host.
• Reference: MCP Tool Catalog — the full per-tool schema reference, including every parameter and default.
• Adding an MCP Tool — how to extend the catalog with new tools.
• Environment Variables — reference for MCP_PORT, MCP_BIND_ADDR, and MCP_AUTH_TOKEN.

Architecture Overview

discord-bot-rs is built from small, well-isolated modules communicating through a central shared Data struct and a handful of Discord event handlers. The process is a single Tokio runtime that hosts a Discord client, a Postgres connection pool, and an embedded MCP server, plus whichever feature modules you’ve turned on in config.toml. Everything else — music players, game state, rate limiters, the AI pipeline — hangs off Data and is accessed async-safely through per-guild or per-channel maps. This page sketches the high-level shape; the rest of the architecture section drills into each piece.

Components

graph TB
    subgraph "Bot Process"
        Gateway[Discord Gateway<br/>serenity shard]
        Handler[Event + Command Handler<br/>poise]
        Commands[Commands<br/>src/commands/]
        AI[AI Pipeline<br/>src/ai/]
        Music[Music Player<br/>src/music/]
        Games[Games<br/>wordle, connections, stocks]
        DB[(PostgreSQL<br/>sqlx pool)]
        MCP[MCP Server<br/>src/mcp + axum]
    end
    Discord[Discord API] <--> Gateway
    Gateway --> Handler
    Handler --> Commands
    Handler --> AI
    Handler --> Music
    Commands --> DB
    AI --> DB
    Games --> DB
    Handler --> Games
    Claude[MCP client<br/>e.g. Claude Code] --> MCP
    MCP --> Handler

One Tokio process hosts a serenity shard (the WebSocket to Discord’s gateway), a poise dispatcher wrapped around it, and an axum-based MCP server bound on a local port. Gateway events flow into the event handler, which either fires a command (via poise) or routes the event directly to a feature module — the AI pipeline for @mentions and replies, the music player for voice state updates, the games module for interaction buttons. Every module talks to the Postgres pool through sqlx. The MCP server is a separate ingress point: it exposes tools like list_guilds and send_message to outside clients, and its handlers reach into the same shared state the event handler uses.

The Data struct

Poise gives every handler a typed reference to a user-defined state struct. In this project that struct is Data, defined at the top of src/main.rs. It holds:

• db: sqlx::PgPool — the shared Postgres connection pool.
• http_client: reqwest::Client — a preconfigured HTTP client for yt-dlp, DeepSeek, Gemini, Finnhub, DuckDuckGo scraping, and any other outbound HTTP work a feature needs.
• config: Config — loaded from environment variables at startup.
• personality: String and bot_name: String — per-instance identity.
• Optional feature configs — auto_role_config, minecraft_config, join_role_config, welcome_config, etc. Each is Option<T> so that disabled features simply hold None.
• Per-guild state maps: guild_players, track_handles, now_playing_msgs, idle_timers, connections_games, wordle_games. All are Arc<DashMap<key, value>>, giving lock-free guild lookup. Most values are wrapped in Arc<Mutex<T>> for serialised access inside one guild; track_handles is the exception — it stores TrackHandle directly because songbird’s handle is already cheap to clone and internally synchronised.
• rate_limiters: RateLimiters — sliding-window limiters for AI, music, moderation, stock tools, and the welcome/join flow, keyed by user ID. All five are enforced; a periodic cleanup task in main.rs evicts empty buckets every 5 minutes. See Concurrency Model.
• mcp_started: AtomicBool and started_at: DateTime<Utc> — one-shot flags used to guard the MCP server against gateway reconnects and to let the AI history builder ignore messages from previous bot lifetimes.

A single Arc<Data> is cloned into every command context, event handler future, and background task. Cheap to clone, shared everywhere, no global state — see Concurrency Model for why this shape works without contention.

Per-instance model

Each running bot is a separate Linux process with its own Data, its own Discord token, its own Postgres schema, and its own instance config directory. “Multi-tenant” here means “run two containers with two .env files,” not “one process with guild-scoped data.” The Multi-Instance Model page explains the boundaries and why the project chose a schema-per-instance approach over the alternatives.

How events flow

Discord pushes an event down the gateway. serenity parses it into a typed variant and hands it to poise’s event dispatcher, which either matches a prefix command (the !m family) and runs the command handler, or calls the plain event_handler for everything else. The event handler is one big match over FullEvent variants — ready, message create, voice state update, interaction create, member add — and each arm dispatches to the corresponding feature module. Responses go back to Discord via serenity’s HTTP client. The full lifecycle is in Data Flow.

Major modules

Tech choices

• serenity — Rust’s mature Discord library, the foundation for everything else. Chosen for its stable gateway handling and typed model objects.
• poise — a command framework built on serenity. Used for its prefix-command parsing, subcommand tree, and typed Context<'_, Data, BotError>. Saves hundreds of lines of boilerplate compared to raw serenity.
• songbird — the voice driver. Handles voice gateway, UDP, and Opus packet assembly so this project only has to feed it audio bytes.
• sqlx — async Postgres client with compile-time-checked queries. Chosen over an ORM for explicitness and because the schema is small enough not to need one.
• dotenvy — reads .env at startup. Modern maintained fork of the classic dotenv crate.
• rmcp — the official Rust SDK for the Model Context Protocol; used for the embedded MCP server.
• axum — HTTP server. The MCP server and (optionally) chargeback webhook router run on axum inside the same Tokio runtime as the Discord client.
• dashmap — a lock-free concurrent hash map. Used for every per-guild and per-channel state map so that work in one guild never blocks work in another.

Where to go next

• Multi-Instance Model for the process and schema layout when you run more than one bot against one Postgres.
• Data Flow for the step-by-step lifecycle of a single Discord event.
• AI Pipeline for how @mention → response actually works, including tool-use loops.
• Music Pipeline for the yt-dlp + songbird path.
• Concurrency Model for DashMap + tokio::Mutex patterns and why locks are the last tool, not the first.
• Error Handling for how BotError reaches users.
• Database Schema for every table and what owns it.

Multi-Instance Model

discord-bot-rs is designed to run more than one bot at a time on the same host — different Discord identities, different personalities, different feature sets, sharing one Postgres server and one MCP gateway. This page explains what an “instance” actually is, where the isolation boundaries sit, and why the project chose a schema-per-instance approach over the alternatives you’d usually reach for.

If you just want to deploy two bots, see Multi-Instance Deployment. This page is the architectural rationale behind that recipe.

What an instance is

An instance is a tuple of four things:

1. One Discord bot identity — its own DISCORD_TOKEN, CLIENT_ID, and GUILD_ID.
2. One config directory — a path on disk containing config.toml, personality.txt, an .env file, and whatever optional feature files (welcome prompt, cookies, etc.) that instance uses.
3. One Postgres schema — selected by the DB_SCHEMA environment variable. All of the instance’s persistent state lives inside it.
4. One Linux process — in practice, one container running the discord-bot-rs binary. Each process has its own Tokio runtime, its own Data struct, its own memory state, its own MCP server on its own port.

Nothing in the bot code is aware of other instances. The binary reads a single .env, mounts a single CONFIG_DIR, talks to a single schema, and serves a single Discord token. You get multi-tenancy by running the binary twice with two configurations, not by having one process juggle multiple identities.

Topology

graph TB
    subgraph "Host"
        subgraph "bot container #1"
            B1[discord-bot binary<br/>CONFIG_DIR=/config]
            M1[MCP server :9090]
            B1 --- M1
        end
        subgraph "bot container #2"
            B2[discord-bot binary<br/>CONFIG_DIR=/config]
            M2[MCP server :9090]
            B2 --- M2
        end
        subgraph "postgres container"
            PG[(PostgreSQL)]
            S1[schema: bot1]
            S2[schema: bot2]
            PG --- S1
            PG --- S2
        end
        subgraph "mcp-gateway container"
            G[gateway :9100]
        end
        B1 -.-> S1
        B2 -.-> S2
        G --> M1
        G --> M2
    end
    D1[Discord API<br/>bot1 token] <--> B1
    D2[Discord API<br/>bot2 token] <--> B2
    Claude[MCP client] --> G

Each bot container has its own /config volume mount and its own .env, so they see completely different DISCORD_TOKEN, CONFIG_DIR, and DB_SCHEMA values. Both bots connect to the same Postgres server but operate on different schemas, so their tables never collide. The gateway container sits in front of both MCP servers on an internal Docker network and presents a single endpoint to outside tools.

Isolation boundaries

The same instance can be cloned, renamed, or retired without touching the others. Here’s what’s isolated and where each boundary is enforced.

1. Process. Each instance is a separate Docker service (or plain process) with its own Tokio runtime, memory, and lifetime. Crashing one takes the others with it only if they share a container, which Docker Compose setups avoid by default.
2. Config. CONFIG_DIR points at a per-instance directory. The bot reads config.toml, personality.txt, the optional welcome prompt, and (for music) cookies.txt from that path. Two instances can ship completely different config.toml feature flags and the code will ignore them independently.
3. Database. DB_SCHEMA selects a Postgres schema. See below for how sqlx threads this through the pool. Bot A can migrate its schema without affecting Bot B, and you can drop one schema without touching the other.
4. Personality. Each instance has its own personality.txt loaded into Data::personality at startup. The AI system prompt interpolates this string, so the two bots have different voices even if they share every other config value.
5. Discord identity. Token, client ID, and guild are environment variables, so they live in each instance’s .env. The Discord gateway has no concept of “the same binary running twice” — each token opens its own shard connection.

Schema-per-instance: how it works

The database setup lives in src/db/mod.rs. At startup, init_pool takes the DATABASE_URL and the DB_SCHEMA name and does three things:

1. Opens a one-off connection and runs CREATE SCHEMA IF NOT EXISTS "<schema>".
2. Builds a PgPoolOptions with an after_connect hook that runs SET search_path TO "<schema>" on every new connection the pool hands out.
3. Runs the migration SQL (currently a set of CREATE TABLE IF NOT EXISTS statements) against the freshly configured pool, so the tables land in the right schema.

The key move is the search_path hook. Postgres resolves unqualified table names by walking search_path in order, so as long as every connection has search_path = <schema>, every SELECT * FROM tempbans in the codebase silently becomes SELECT * FROM "<schema>".tempbans. No feature module has to know the schema name, no query has to be parameterised. The abstraction is completely transparent to the rest of the code.

Migrations are a tradeoff of their own. Today, migrate runs a flat list of CREATE TABLE IF NOT EXISTS statements. That’s enough to bootstrap a new schema but doesn’t handle schema evolution gracefully. A proper migration tool is future work; the current setup is “good enough until we need to rename a column.”

What’s shared

A few things cross instance boundaries on purpose, because isolating them would cost more than it’s worth:

• The Postgres server. One Postgres process, one connection listener, one set of backups. Each instance gets its own schema inside that server. Running two Postgres containers just to keep bots apart would waste RAM and double the ops surface.
• The Docker network. All bot containers, the Postgres container, and the MCP gateway share an internal bridge network. That’s how mcp-gateway reaches http://bot1:9090 by name.
• The host. CPU, disk, memory, the kernel — everything underneath Docker is shared. If you need stronger isolation than “same Linux host” you’re looking at a different architecture.
• The mcp-gateway container. One gateway fronts all instances. See MCP Gateway Routing for how it picks which bot to forward a tool call to.

Why not the alternatives

Three approaches were considered before landing on schema-per-instance.

Separate Postgres databases. Instead of one server with many schemas, you could spin up one Postgres database per bot. This gives stronger isolation — separate pg_stat, separate WAL, separate roles — at the cost of doubling your connection count and making backups harder. For a bot whose per-instance data is measured in kilobytes, the cost isn’t justified. Schemas inside one database give you every isolation property that actually matters (no accidental cross-instance queries, independent migrations, drop-and-recreate safety) without the overhead.

Single schema, guild_id column. The other extreme: one schema, every table has a guild_id column, every query adds WHERE guild_id = $1. This is how Discord bots usually handle multi-tenancy. It works for a shared public bot, but it makes “run a second bot with a different personality against the same server” a lot harder. Every test fixture, every migration, every ad-hoc SQL query now has to carry the guild ID as ceremony, and there’s no isolation if buggy code accidentally forgets the filter. For the use case this project targets — self-hosters running a handful of dedicated bots — the schema boundary is a much safer default.

Separate Postgres containers. The nuclear option: one entire Postgres per bot. Each container is a full Postgres, so you pay its full RAM footprint, its full startup time, and its full ops burden. For two bots on a small VPS, this is 200–400 MB of overhead to solve a problem that schemas already solve for free.

Concurrency across instances

Because instances are separate processes with their own Data, there is zero shared in-memory state. One bot can be cranking through a music queue and another can be handling a moderation action at the same time without any lock contention whatsoever — the two runtimes don’t even see each other. Scaling is linear until Postgres becomes the bottleneck, which for this workload is “many hundreds of active bots on one box.”

The flip side is that there’s also no cross-instance coordination. Bot A cannot send a message to a channel that only Bot B has permission to post in. Bot A cannot read Bot B’s music queue. If you need that, you need to build it through the MCP gateway or an external message bus — the bot framework itself doesn’t model it.

Adding an instance

Operationally, adding a new instance is copy-paste plus a restart. Make a new directory under instances/, fill in config.toml, .env, and personality.txt, copy the bot service in docker-compose.yml, rename it, point its volume at the new directory, run docker compose up -d. The Multiple Instances configuration page walks through the .env and config.toml side. The Multi-Instance Deployment deployment page walks through the compose file and the gateway registration.

Known limits

• No cross-instance messaging. Each process is an island. There’s no built-in way for one bot to trigger an action in another one.
• No shared in-memory state. Rate limiters, music queues, game state — none of it crosses processes. If you need shared state, you’d put it in Postgres.
• No dynamic instance add/remove. Adding a new instance means editing docker-compose.yml and restarting docker compose. There’s no admin API to register a new bot at runtime.
• MCP gateway routing is static. The gateway reads INSTANCES from its environment once at startup and refreshes the guild map every five minutes. It doesn’t discover new backends on the fly.

See MCP Gateway Routing for how a single MCP client talks to all these instances through one URL, and Configuration Overview for how to split config between environment and config.toml.

Data Flow

This page follows a single Discord event from its arrival on the gateway to the response going back out, touching every layer the bot passes it through on the way. The goal is to give you enough mental model to know where to look when something misbehaves and where to add new behaviour when you’re extending the bot.

The two main paths are commands (a message starting with the configured prefix that matches a !m subcommand) and events (everything else — @mentions handled by the AI, voice state changes, button clicks, member joins). Both start at the same gateway shard and both pass through the same poise dispatcher, but they diverge at the point where poise decides whether a prefix parser matched.

Sequence: a single command

sequenceDiagram
    participant U as User
    participant DG as Discord Gateway
    participant SR as serenity Shard
    participant P as poise dispatcher
    participant H as Command handler
    participant D as Data (DashMap / PgPool)
    participant DB as PostgreSQL
    U->>DG: !m ban @user 3d
    DG->>SR: MESSAGE_CREATE event
    SR->>P: FullEvent::Message
    P->>P: parse prefix, match subcommand
    P->>H: moderation::ban(ctx, target, duration, reason)
    H->>D: create_tempban(db, ...)
    D->>DB: INSERT INTO tempbans ...
    DB-->>D: row id
    D-->>H: Ok(expires_at)
    H->>SR: ctx.say("Banned ...")
    SR->>DG: CREATE_MESSAGE
    DG-->>U: reply visible in channel

The whole round trip is one async function call tree — there is no inter-process hop between any of the boxes above. What looks like a distributed system on paper is a single Tokio task spinning up a few short-lived sub-tasks and then awaiting the response.

Step by step

1. Gateway. serenity runs a persistent WebSocket connection to Discord’s gateway, wss://gateway.discord.gg. When a user sends a message, Discord pushes a MESSAGE_CREATE event down this socket. serenity’s shard runner parses the frame into a typed FullEvent variant and forwards it to whatever listener is registered. In this project, poise registers itself as the listener.

2. Poise dispatcher. Poise is a thin command framework layered on top of serenity. It receives every FullEvent, runs its own prefix parser against messages, and decides whether to route them as commands or fall through to the user-defined event handler. The wiring lives in main.rs where the framework is built with both a commands list and an event_handler closure pointing at events::event_handler.

For prefix commands, poise walks through your command tree looking for a match. The tree here is rooted at a single top-level command m (defined in src/commands/mod.rs) with every user-facing command as a subcommand — music::play, moderation::ban, admin::djmode, help::help, and so on. There are no slash commands, so there’s no application-command sync step: the registered !m command is all poise needs.

3. Command handler. If poise found a match, it calls the handler function with a typed Context<'_, Data, BotError>. The context gives the handler its arguments (poise parsed them from the message), an &Data reference for shared state, and convenience methods like ctx.say("...") for replying. A simple command looks like moderation::ban: it reads the target user and duration, calls create_tempban in db::queries, then replies with a confirmation string via ctx.say. That’s the whole round trip.

4. Database access. Every DB call reaches Postgres through the sqlx::PgPool stored in Data::db. The pool was built in main.rs with an after_connect hook that pins search_path to the per-instance schema, so queries inside handlers can say SELECT * FROM tempbans without worrying about which schema they land in. See Multi-Instance Model for why.

5. Response. Replies go back through serenity’s HTTP client (not the gateway), which submits them to Discord’s REST API. serenity takes care of per-route rate limiting transparently, so handlers don’t have to think about Retry-After headers. The user sees the message.

Event path (no command match)

When poise decides a message isn’t a command — no prefix match, or the event isn’t a message at all — it calls the event_handler closure. In this project that closure is events::event_handler, which is one big match over FullEvent variants:

• Ready — fires once at startup (and on every reconnect). The first time, it spawns the MCP server and any webhook routers; subsequent reconnects are guarded by an AtomicBool so the server doesn’t bind its port twice.
• Message — handle_message runs auto-role bookkeeping, checks for active Wordle games in the channel, and dispatches to ai::deepseek::handle_mention if the message mentions the bot or replies to a bot message (and at least one AI key is configured).
• VoiceStateUpdate — if a user left the bot’s voice channel and the channel is now empty of humans, voice_state::handle_voice_state_update cleans up the player, cancels the idle timer, and leaves the channel.
• InteractionCreate — a component button click. The dispatcher looks at the custom_id prefix (music_, game_, cb_) and hands off to the right feature handler.
• GuildMemberAddition — a new member joined, used by the welcome prompt and join-role features.

Event handlers get the same &Data reference as commands, so they reach shared state the same way. The only structural difference is that they don’t go through poise’s command parser, so argument parsing and permission checks are the handler’s own responsibility.

Error paths

Each layer has its own failure model, and errors surface differently depending on where they start.

• Command handler returns Err(BotError). Poise catches this and calls its on_error hook, which is wired in main.rs to log the full error via tracing::error! and post error.user_message() — a short, sanitised, per-variant string — in the channel. See Error Handling for the full picture.
• DB query fails. sqlx::Error converts into BotError::Sqlx via a From impl in src/error.rs, so ? in a command handler turns a query failure into an automatic early-return with a user-visible message.
• Event handler fails. Event handlers mostly use let _ = ... patterns when calling Discord to swallow transient errors, because there’s no safe place to post a user-visible error for, say, a failed auto-role bookkeeping write. Serious failures get logged via tracing::error!.
• Panic inside a handler. Tokio catches task panics and logs them, and serenity’s shard runner keeps going. A panicking command does not take the process down, but it also does not reply to the user — the user sees no response.
• Rate limit from Discord. serenity’s HTTP client implements bucketed rate limiting; 429s are retried transparently. Commands don’t see them unless the wait exceeds serenity’s patience.
• Network drop. The gateway shard auto-reconnects with exponential backoff. On reconnect, serenity replays any missed events Discord will give it, and the Ready handler re-fires. The mcp_started guard prevents double-binding the MCP port on reconnect.

Shared state access

Data is given to handlers by reference (&Data), wrapped in an Arc by poise so cloning it for spawned tasks is O(1). Inside Data, per-guild and per-channel state lives in DashMap instances — guild_players, track_handles, now_playing_msgs, idle_timers, connections_games, wordle_games. DashMap is a sharded lock-free hash map, so two handlers running in different guilds never block each other on the outer map. Inside one shard entry, the value is typically Arc<Mutex<T>>, so concurrent access to the same guild’s player (for example) is serialised through a tokio Mutex.

Why not a global RwLock<HashMap>? Because a single global lock would turn every music command in every guild into a contention point. DashMap gives you concurrent reads and writes across different keys, which is exactly the shape of “per-guild state accessed by concurrent handlers.” Concurrency Model expands on this pattern.

Cross-links

• Error Handling — what happens when any of the above fails, and how errors reach users (or get quietly logged).
• Concurrency Model — why Data uses DashMap the way it does, and how background tasks coexist with event handlers.
• AI Pipeline — the most elaborate event path: an @mention becomes a history fetch, a chat completion, a tool-use loop, and a response splitter. Everything in this page applies, plus a lot more.

AI Pipeline

This page walks through the path from a Discord @mention to the reply the user sees. It’s the most elaborate event path in the bot: history building, personality injection, provider routing, tool-use loops, response sanitising, and Discord-friendly chunking all happen before the reply is sent. A reader who understands this page can confidently extend the AI in new directions — adding tools, tweaking the system prompt, swapping providers — without breaking the rest.

The core file is src/ai/chat.rs. Everything under src/ai/ is either called from there or defines data it consumes. For how users actually interact with this from Discord, see AI Chat.

Sequence

sequenceDiagram
    participant U as User
    participant E as events::handle_message
    participant H as build_message_history
    participant R as model router
    participant API as DeepSeek / Gemini
    participant T as tool executor
    participant S as sanitize + split
    participant D as Discord

    U->>E: @bot what's the weather in tokyo?
    E->>E: activation check (mention / reply + AI key)
    E->>H: fetch 100 recent messages
    H->>H: filter by age, started_at, bad-msg
    H->>E: system prompt + history + current msg
    E->>R: classify message: reasoning or chat?
    R->>API: chat completion with tools
    API-->>R: content + tool_calls (web_search, play_song, ...)
    loop up to 3 rounds
        R->>T: run search tool calls
        T-->>R: search results
        R->>API: re-call with results
    end
    R->>S: final text response
    S->>S: sanitize, split at 2000 chars
    S->>D: send one or more reply messages
    T->>D: execute action tools (play_song, tempban, ...)

Not shown: vision routing (images go directly to Gemini 3 Flash via OpenAI-compatible endpoint before any of this), the moderation confirmation button flow, and the typing indicator that fires every 8 seconds while the pipeline is running.

Activation

Before any of the pipeline runs, the bot has to decide “is this for me?” That check lives in handle_message in src/events/mod.rs and is deliberately narrow. Three conditions must all hold before handle_mention is called:

1. The message is from a non-bot author in a guild channel.
2. The message either contains a direct mention of the bot user ID, or is a Discord reply to a message the bot itself sent.
3. At least one of DEEPSEEK_API_KEY or GEMINI_API_KEY is set on Data::config.

There is no keyword trigger, no prefix alternative, no owner override. Everything flows through @mention or reply. This keeps the activation surface small, which matters for a bot that can issue tempbans and spend real money on API calls.

A fourth short-circuit happens inside handle_mention: the per-user AI rate limiter (RateLimiters::ai) is a sliding window of 10 requests per 60 seconds. Users who exceed it get a “Slow down — try again in Ns.” reply and the pipeline exits before any API call.

History building

The AI’s memory is whatever messages the bot can reconstruct from the channel’s recent history. There is no vector store, no long-term memory, no per-user state. When the pipeline starts, build_message_history fetches the last 100 messages before the current one via channel.messages(...).before(message.id).limit(100) and walks them in reverse-chronological order.

From that window, it keeps the most recent 10 relevant messages, where “relevant” means:

• Posted after Data::started_at. Bot messages from a previous process instance are filtered out, because they might be tied to state this process no longer has.
• Posted within the last 30 minutes. Anything older is stale context — the AI would start mixing up a question from an hour ago with the current one.
• Either from the bot (assistant role) or from a human who was directly talking to the bot (either mentioning it or replying to a bot message). Messages that are just general channel chatter don’t get included — the bot is not trying to maintain a running summary of the whole channel.
• Not a known bad assistant message. Leaked I'm Claude, memory denials, broken tool replies, and error strings are pattern-matched via BAD_ASSISTANT_PATTERNS and skipped — and any user message those bad assistant messages were replying to is skipped too, on the theory that if the AI blew up on that question, feeding it back in will make it blow up again.

Bot messages whose content is empty but that carry embeds (Now Playing, Added to Queue, confirmation prompts, etc.) get their embeds summarised into a compact [Already completed action] [title: description] string. This is what keeps the AI from replaying the same music request every time someone @mentions it — the embed history tells the model “you already did this, move on.”

After the loop, the builder pushes a synthetic system message:

Everything above is conversation history for context only. You have already responded to all of it. Do NOT act on any previous requests again. The NEXT message is the current request — respond ONLY to it.

This separator is a necessary belt-and-braces measure against a failure mode where the AI would pick up an earlier question and answer it instead of the new one. Finally, the current message is appended as a user-role message, prefixed with the author’s display name.

If the current message is a Discord reply to a non-bot message, the builder fetches that referenced message, truncates it to 300 characters, and prepends a [Replying to name: "..."] marker to the current message. If the referenced message has image attachments, they’re collected for vision routing.

Personality and system prompt

The personality file loaded from CONFIG_DIR/personality.txt is appended verbatim into the system prompt by get_system_prompt. Around it, the function hard-codes:

• The current date (so the model doesn’t guess),
• The current bot version (pulled from CARGO_PKG_VERSION),
• A block explaining the music tools and the rules for using them (most importantly: only on explicit current requests, never replay old ones),
• A block explaining the web search tool and the rule that the model can search up to three times per turn,
• A block explaining moderation tools and that the system does its own permission checking,
• A block covering markdown capabilities, the user-name prefix convention, and how to handle mentions in message text,
• A security block instructing the model to refuse prompt-injection attempts and to treat role markers in user text as data, not instructions.

The personality file never sees this hard-coded framing: the bot operator writes only their instance’s voice, and the bot fills in the mechanics. See Personality Files for how to write the free-form half.

Provider selection

The bot speaks two providers, both through an OpenAI-compatible chat-completions API:

• DeepSeek at https://api.deepseek.com/chat/completions. deepseek-v4-flash (DeepSeek V4) is the default for text. deepseek-v4-pro is the flagship used for questions the router classifies as needing deeper thinking.
• Gemini at https://generativelanguage.googleapis.com/v1beta/openai/chat/completions. gemini-3-flash-preview handles image vision, because DeepSeek’s chat model is text-only.

Routing happens in two places. First, vision routing: if the message (or the message it replies to) has image attachments and a Gemini key is configured, the pipeline preprocesses each image (resize to 1024x1024 max, re-encode as JPEG, base64 in a data URI) and sends the history as a multimodal completion to Gemini. If Gemini fails, the pipeline strips the images and falls through to the text path.

Second, reasoning routing: for text requests, classify_message sends the user’s most recent message to DeepSeek V4 with a one-shot “yes/no — does this need deep reasoning?” prompt. If the classifier says yes, the pipeline switches the active endpoint to deepseek-v4-pro. Because the reasoner role can’t use tools, the pipeline first runs a pre-flight loop on deepseek-v4-flash that’s allowed to call web_search up to MAX_SEARCH_ROUNDS times (currently 3), collects the results, and injects them into the V4-Pro conversation as extra system context before asking V4-Pro the real question.

If the classifier itself fails (network error, timeout), the pipeline defaults to deepseek-v4-flash without reasoning — “failing toward the cheap path” is the preferred failure mode.

Tool use loop

Once an endpoint and model are picked, call_api posts the history with the full tool definitions attached (except for the reasoner role, which gets no tools). The response contains content (the assistant message), tool_calls (any function calls the model wants to invoke), or both.

Tools come in two flavours:

• Search tools — just web_search today. The model asks for a search, the bot runs it, the result goes back to the model as a role: "tool" message, and the model gets another turn to decide whether to search again or answer. Up to MAX_SEARCH_ROUNDS rounds (currently 3), after which the pipeline forces a final answer with tools disabled. The same MAX_SEARCH_ROUNDS constant in src/ai/chat.rs is interpolated into the system prompt and drives both the V4-Flash chat loop and the V4-Pro pre-flight loop, so the prompt and the code can never disagree about the limit.
• Action tools — everything that changes state: play_song, skip, stop, pause, resume, show_queue, now_playing, shuffle, set_loop, remove_from_queue, tempban, unban, nuke, stock_buy, stock_sell, stock_price, stock_portfolio, stock_leaderboard, connections_start, wordle_start.

Search tools are executed inside the loop because their results feed back into the model. Action tools are executed after the text response is posted: the bot sends the model’s witty reply, then runs the actions. This preserves the personality when actions have their own output (skip messages, Now Playing embeds, etc.) and keeps the user experience close to “bot says something, then does the thing.”

Action tools are dispatched from a single for loop in handle_mention that checks each call against is_moderation_tool, is_stock_tool, is_connections_tool, is_wordle_tool, and falls through to execute_music_tool for the rest. Moderation tools go through an extra step: a Discord confirmation embed with Approve/Cancel buttons, handled by request_confirmation. That function pre-checks the requesting user’s guild permissions (computed from role permissions because Message::member.permissions is often None for fetched messages), posts the confirmation embed, waits up to 30 seconds for the original author to click, and returns approval status. Only then does the moderation action run. Other action tools run without confirmation — permissions are enforced inside each tool by the DJ mode check or by Discord’s own permissions.

DSML: tool calls in prose

DeepSeek V4 sometimes emits tool calls as structured text inside the content field instead of the proper OpenAI-style tool_calls array. The bot handles this by parsing a custom “DSML” (Discord Structured Message Language) block out of the content — fullwidth pipe characters wrapping <|DSML|invoke name="...">...</|DSML|/invoke> — in parse_dsml. Any DSML tool calls found are appended to the real tool call list and the content is cleaned up before being shown to the user. This is a resilience hack for model quirks; the primary path is still proper function calling.

Response sanitising

Two kinds of cleaning happen to AI-adjacent text.

Input sanitising is applied to every bit of user text that gets added to the history. Mentioned in sanitize_content, it rewrites system:, assistant:, user: role markers into bracketed forms ([system]:), strips DeepSeek’s internal <|...|> tokens, and strips Llama-style [INST] and <SYS> markers. The point is not to block every conceivable prompt injection — that’s impossible — but to make it harder to slip a realistic-looking “new system prompt” into the model’s conversation by typing one into Discord.

Output filtering happens at history-build time. Past bot messages that match known failure patterns (“I’m Claude”, “I don’t have access to our previous”, “created by Anthropic”, “Failed to join”, etc.) are skipped when reconstructing the history, and so are any user messages those bad bot messages were replying to. This is a self-healing mechanism: if the model goes off the rails once, the next turn won’t see the broken exchange and is less likely to repeat it.

Response splitting

Discord messages max out at 2000 characters. The splitter in src/ai/split.rs takes a raw response string and returns a Vec<String> of chunks each under the limit. Simple cases (response under 2000 chars) return a single-element vec. For long responses, the splitter walks forward looking for the best break point:

• If the current chunk ends inside a fenced code block (an odd number of ``` markers), the splitter finds the opening fence and either splits just before it (if the code block hasn’t yet started near the top of the chunk) or closes it with ``` and re-opens it with ```lang in the next chunk, preserving syntax highlighting.
• Otherwise, it prefers breaking on \n\n, then \n, then ". " — in that order. The split point has to be at least 200 bytes into the chunk to avoid pathological tiny slices.

All slicing is done at char boundaries (UTF-8 safety), not byte boundaries, so multi-byte characters don’t get cut in half.

Rate limiting

Rate limiting for the AI path is a per-user sliding window configured in src/util/ratelimit.rs: 10 requests per 60 seconds, shared across every AI interaction. It’s enforced in handle_mention before any API call. The other limiters — music, moderation, stocks, and welcome — are all enforced too on their respective paths; see the Concurrency Model rate-limiter section for the full table and the periodic bucket-cleanup task that keeps the limiter maps from growing without bound.

Rate limiting at the API layer (DeepSeek / Gemini quotas) is the provider’s responsibility; the bot doesn’t pre-check quotas and relies on the API’s own error responses.

Error handling inside the pipeline

Each layer has its own fallback:

• Classifier fails → default to deepseek-v4-flash (non-reasoner) path.
• Vision API fails → strip images and fall through to text.
• Text API fails → reply with “Something went wrong talking to the AI. Try again in a sec.” Log the upstream error with tracing.
• “Content Exists Risk” censored response from DeepSeek → reply with a sarcastic “my overlords at DeepSeek won’t let me talk about that.”
• Search tool fails → inject “Search failed.” as the tool result and let the model continue with whatever it has.
• Tool call with bad arguments → the tool executors generally unwrap_or(...) past missing fields rather than erroring, because the user has already waited for the model and a silent no-op is better than a red error string.
• Tool dispatch / DB / HTTP failures inside a tool → all user-facing replies in handle_mention’s tool loop now use the same generic, sanitised wording as BotError::user_message() (“Something went wrong talking to the database. Please try again later.”, etc.). Operators still see the full upstream error via tracing::error! with the failing tool name and guild ID, but raw sqlx/reqwest/serde_json strings never reach Discord. See Error Handling for the mapping table.

The typing indicator is re-triggered every 8 seconds by a spawned background task, so users see the bot “thinking” for the whole duration of a slow tool-use loop. That task is aborted on every exit path (typing_handle.abort()) to keep it from leaking past the end of the conversation.

Known issues

• Context bleed. The 10-message / 30-minute window is a compromise. Shorter would drop useful context; longer pulls in stale questions the AI wants to answer. Users occasionally see the AI start answering a question from 20 minutes ago when they @mention it with something new. The self-healing filter helps but doesn’t eliminate it.
• Permission checks on message.member. Confirmation flow has to recompute permissions from the guild’s role table because message.member.permissions is often None for messages fetched via the API. This is a serenity quirk, not a design choice.
• rmcp session auth. See MCP Gateway Routing for the current state of MCP authentication.

Cross-links

• AI Chat — user-facing feature description.
• Personality Files — how to write personality.txt.
• Concurrency Model — the rate limiter and DashMap patterns the pipeline leans on.
• MCP Tool Catalog — the separate tool surface exposed via MCP, not via the AI pipeline.

Music Pipeline

From a !m play <query> command or an AI tool call to audio playing in a voice channel. This page follows every step of the path so you can add features, debug playback issues, or reason about what happens when yt-dlp fails at 3 a.m.

For how users interact with music features, see Music.

Sequence

graph TB
    User[!m play <query>] --> Cmd[commands::music::play]
    AI[AI tool call: play_song] --> Exec[execute_music_tool]
    Cmd --> Resolve[resolve_track / resolve_tracks]
    Exec --> Resolve
    Resolve --> Ytdlp[[yt-dlp --dump-json<br/>HTTP search or URL]]
    Ytdlp --> Track[Track struct<br/>url, title, thumb]
    Track --> Join[voice::join_channel<br/>songbird: deafen, 256k bitrate]
    Join --> Play[voice::play_track<br/>YoutubeDl input via songbird]
    Play --> Songbird[(songbird driver<br/>ffmpeg + Opus)]
    Songbird --> Voice[Discord voice gateway]
    Voice --> Channel[audio in voice channel]
    Play --> Embed[now_playing_embed + controls]
    Embed --> Msg[channel.send_message]
    Play --> EndHook[TrackEndHandler<br/>registered via Event::Track]
    EndHook --> Advance[GuildPlayer::advance<br/>respect loop_mode]
    Advance -->|Some track| Play
    Advance -->|None| Idle[start_idle_timer 5 min]
    Idle -->|timeout| Leave[songbird leave]

Two entry points, one pipeline. The prefix command path and the AI tool path both converge on resolve_track, then both use voice::play_track to hand the URL to songbird. After that, track advancement is driven by songbird’s TrackEvent::End hook, not by polling.

The MusicPlayer struct

Per-guild state lives in GuildPlayer:

• queue: VecDeque<Track> — upcoming tracks, bounded to 100 entries (MAX_QUEUE_LENGTH).
• current: Option<Track> — what’s playing right now, or None if the player is idle.
• loop_mode: LoopMode — Off, Track, or Queue. Cycles through those three values when the loop button is pressed.
• paused: bool — tracks paused state so the now-playing embed can show the right icon.
• skip_in_progress: Arc<AtomicBool> — see Skip race below.

The struct is plain data plus a handful of methods (enqueue, enqueue_many, advance, skip_current, stop_all, remove, shuffle, leave_empty). None of those methods touch the Tokio runtime, do I/O, or know anything about songbird. That’s deliberate: the player is a pure state machine, and the music pipeline wraps it in an Arc<Mutex<GuildPlayer>> stored in Data::guild_players. Every feature that reads or mutates the player takes the lock, works with plain Rust data, and releases it. See Concurrency Model for why this separation matters.

The interesting method is advance. It implements loop semantics:

• LoopMode::Track returns a clone of the current track (play it again).
• LoopMode::Queue pushes the current track back onto the queue’s tail, then pops the front.
• LoopMode::Off drops the current track and pops the next one from the queue.

If the queue is empty after popping, advance returns None and the caller uses that as the signal to leave the voice channel.

Track resolution

A raw user query — "sabrina carpenter espresso", a YouTube URL, a playlist URL — becomes a Track via src/music/track.rs. The resolve_track and resolve_tracks helpers shell out to yt-dlp with --dump-json --no-download and parse the NDJSON output into one or more Track structs (URL, title, duration, thumbnail, requested-by display name).

The yt-dlp invocation is a little unusual because YouTube’s age and region gates require a browser session. The bot passes several flags:

• --cookies <path> — supplies a cookies.txt file exported from a logged-in browser. The path is the cookies.txt in the current working directory if it exists (so per-instance containers can mount their own).
• --js-runtimes node:<path> — tells yt-dlp to solve JavaScript challenges using a specific Node binary. The default node path isn’t always on PATH in service environments, so the code probes /home/webapps/.nvm/versions/node/v20.20.1/bin/node first and falls back to node.
• --remote-components ejs:github — lets yt-dlp pull JS extractor patches from its GitHub repo when the built-in ones are out of date.
• --no-playlist or --flat-playlist depending on whether the caller wants one track or the whole URL’s contents.

If yt-dlp fails with output that looks like a cookie problem (“page needs to be reloaded”, “sign in to confirm”, “this helps protect our community”), the bot retries without the --cookies flag and, on success, returns cookies_stale = true so the caller can warn the user that cookies need refreshing. Non-cookie failures bubble up as errors.

Joining and playing

Once there’s a Track, the pipeline joins the user’s voice channel via voice::join_channel. This calls songbird’s manager.join(guild_id, channel_id), self-deafens the bot (so it doesn’t waste bandwidth receiving audio), and sets the voice bitrate to 256 kbps.

Playback happens through songbird’s YoutubeDl input source:

let source = YoutubeDl::new(http_client, url).user_args(ytdlp_user_args());
handler.play_input(source.into())

ytdlp_user_args() passes the same cookies/node-runtime/remote-components flags as above. Songbird runs yt-dlp, reads its stdout, pipes it through ffmpeg (internally), and feeds the Opus-encoded frames to Discord’s voice UDP.

play_input returns a TrackHandle which the bot stores in Data::track_handles keyed by guild ID, so pause/resume buttons and AI tool calls can find the right handle to act on.

Track-end event and the idle timer

Songbird fires a TrackEvent::End when playback finishes. The bot registers a custom TrackEndHandler on every track via track_handle.add_event(Event::Track(TrackEvent::End), handler). When the event fires, the handler:

1. Looks up the GuildPlayer for this guild.
2. Checks the per-guild skip_in_progress flag and bails out if set (see Skip race).
3. Calls advance() to figure out what plays next.
4. If there’s a next track, starts it with play_next_from_context and replaces the prior “Now Playing” message via replace_now_playing_message (delete old + send new under one mutex hold).
5. If there isn’t, starts the idle timer.

Skip race: suppressing the spurious TrackEnd

handler.stop() causes songbird to fire TrackEvent::End for the track being stopped. The end handler attached to that track would then see “track ended naturally” and call advance() — which on a !m skip would skip past the song the caller is about to play, because the caller has already advanced the queue itself before calling play_track. Songbird 0.6 has no way to detach an event listener from a TrackHandle, so the bot can’t simply remove the handler before the stop.

The fix is a per-guild skip_in_progress: Arc<AtomicBool> on GuildPlayer. Right before any code path that calls handler.stop() on an existing track and immediately starts a new one, the caller sets the flag to true. When the stale TrackEnd event arrives, TrackEndHandler::act swaps the flag back to false with swap(false, Ordering::SeqCst) and, if it was true, returns early without advancing. The next natural TrackEnd (after the new track finishes) sees the flag as false and proceeds normally.

Because the flag is an AtomicBool, no lock is needed, and the swap-on-read pattern guarantees exactly one of the two events (skip-induced End vs. natural End) is consumed by the bail-out path.

NP message lifecycle

Three different code paths can replace the “Now Playing” embed: the prefix command, the AI tool’s “play song” path, and the TrackEndHandler advancing to the next track. Previously each path sent its new NP message independently and only the track-end handler remembered to delete the prior one, leaving orphan embeds with stale buttons whenever a !m play or AI tool call replaced an existing track.

All three paths now go through a single replace_now_playing_message helper in src/music/voice.rs. The helper takes the per-guild Arc<Mutex<Option<MessageId>>> slot, locks it for the whole sequence, deletes the prior message ID if one is stored, sends the new embed (with optional component rows), and stores the new message ID into the slot before releasing the mutex. Holding the lock across delete-then-send is intentional: it prevents two concurrent skip operations in the same guild from racing each other into a partially-deleted, partially-orphaned state. Failures to delete the prior message (the user could have deleted it manually) are swallowed at debug level — the new message still gets sent and recorded.

The idle timer is the mechanism that gets the bot out of the channel politely when the queue runs dry. start_idle_timer spawns a task that sleeps 5 minutes, then calls songbird.leave and cleans up the per-guild maps. The task’s JoinHandle is stored in Data::idle_timers so that new tracks (or explicit stops) can cancel it with .abort().

This two-step — store the handle in a per-guild Arc<Mutex<Option<..>>>, cancel it before starting anything new — is why the idle_timers DashMap exists. A new !m play call on an idle bot cancels the pending leave timer before joining, preventing a race where the bot would leave mid-song.

The voice-state-update handler in src/events/voice_state.rs is a separate trigger: when the user side of the voice channel goes empty (all humans left), it short-circuits the idle timer and leaves immediately.

Queue operations

User commands and AI tools both hit the same queue methods on GuildPlayer:

• add — enqueue(track) or enqueue_many(vec). The latter respects the 100-track cap and returns how many it actually added.
• skip — skip_current() returns the title for the user-facing confirmation; the caller then runs advance() to decide what’s next and plays it.
• remove — remove(position) removes by 1-based index, so users can !m remove 3 to drop the third track in the queue.
• shuffle — drains the queue, shuffles with rand::thread_rng(), refills. Returns the queue length so the response can say “Shuffled N songs.”
• loop — loop_mode.cycle() rotates through Off → Track → Queue.

“Previous” isn’t supported. Once advance is called, the previous track is dropped (or pushed to the back, in queue-loop mode). There’s no history stack.

Button controls

The “Now Playing” embed ships with two rows of buttons, built by music_controls:

• Row 1: Pause/Resume, Skip, Stop, Shuffle, Loop.
• Row 2: Queue (shows the current queue as an ephemeral reply).

Each button’s custom_id starts with music_ (music_pauseresume, music_skip, music_stop, music_shuffle, music_loop, music_queue). The button handler sits in handle_component_interaction and does three checks before running any action:

1. Voice presence: the clicker must be in a voice channel, and it must be the same channel the bot is in. Otherwise the interaction replies ephemerally with an error.
2. DJ mode: if DJ mode is enabled on the guild, only admins and users with the DJ role can press buttons. Non-DJs get an ephemeral error.
3. Active player: there must be a GuildPlayer registered for the guild. Otherwise the button replies “No active player.”

The music_queue button is read-only, so it bypasses the voice and DJ checks — anyone can look at the queue even if they can’t control it.

Error and failure handling

yt-dlp crashes, ffmpeg hangs, voice gateway disconnects, cookies expire. The pipeline tries to handle each gracefully:

• yt-dlp exits non-zero. resolve_tracks checks the stderr for cookie-error patterns. Cookie errors retry without cookies and warn the user. Non-cookie errors bubble up as "Couldn't find that song." plus a tracing log with the real stderr.
• Join fails. voice::join_channel returns an error with songbird’s message; the caller replies “Failed to join voice: {error}” and aborts. No partial state is stored.
• Playback fails. voice::play_track wraps songbird’s errors; failures log and the caller replies “Playback error: {error}.”
• Track-end handler fails to start the next track. The handler clears current, drops the track handle, and starts the idle timer, so the bot doesn’t get stuck claiming it’s playing when it isn’t.
• Voice disconnect mid-track. Songbird manages its own reconnect, and the bot doesn’t react explicitly. If the reconnect fails, playback simply ends and the track-end handler runs its normal path.
• Queue overflow. is_full() is checked before enqueuing; the response tells the user the queue is full.

Cross-links

• Music — user-facing description of how music commands work.
• Command List — every music command.
• Concurrency Model — why per-guild state is behind Arc<Mutex<T>> inside a DashMap.
• Data Flow — the wider event lifecycle that commands and buttons flow through.

MCP Gateway Routing

Each bot instance runs its own MCP server on port 9090. A small companion crate, mcp-gateway, sits in front of those servers and routes incoming MCP requests to the right backend. This page explains why the gateway exists, how it picks a target, and how it stays synchronised with the backends over time.

For the user-facing side of MCP — how to connect a client, how to call tools — see MCP Server and MCP Tool Catalog. For deploying it safely to a public host, see MCP Exposure.

Why the gateway exists

The Model Context Protocol is session-oriented and connection-oriented. A client (for example Claude Code) opens one session against one MCP endpoint and issues tool calls over that session. If you’re running two bot instances and want to send tool calls to both, the obvious approach — configure the client with two endpoints — has two problems:

1. Every new instance breaks your client config. Adding a third bot means editing the client’s mcp.json, reloading the client, and hoping you didn’t typo the URL.
2. Every tool call has to pick an instance out of band. Your prompt has to say “on bot1, list the guilds”; there’s no way to say “list the guilds on the bot serving guild 1234” and let the system figure out which bot that is.

The gateway solves both. Clients point at one URL (the gateway). They see a single tool catalog. Each tool acquires an optional instance parameter, injected by the gateway, and they can also pass guild_id and have the gateway figure out which instance serves that guild. Adding a new bot is a docker-compose line plus a gateway restart — clients don’t change anything.

Topology

graph TB
    Client[MCP client<br/>Claude Code, CLI, etc.] -->|POST /mcp| Gateway
    subgraph "mcp-gateway container"
        Gateway[axum server :9100]
        State[GatewayState<br/>Router + BackendClients]
        Cache[tool_list_cache]
        Gateway --- State
        State --- Cache
    end
    subgraph "bot1 container"
        B1MCP[MCP server :9090]
    end
    subgraph "bot2 container"
        B2MCP[MCP server :9090]
    end
    State -->|session per backend| B1MCP
    State -->|session per backend| B2MCP

The gateway is a standalone axum app on port 9100. It keeps one open MCP session to each backend and multiplexes requests from clients onto those persistent sessions. Clients do not know backends exist; backends do not know other backends exist.

Routing model

The gateway configuration is a single environment variable, INSTANCES, formatted as comma-separated name=url pairs:

INSTANCES="bot1=http://bot1:9090,bot2=http://bot2:9090"

GatewayConfig::from_env parses this into a Vec<Instance> at startup. Each name becomes a routing key and each URL becomes a backend target. The gateway panics if INSTANCES is missing — a misconfigured gateway is a hard failure.

Routing itself is a two-step decision in mcp-gateway/src/routing.rs:

1. Explicit instance wins. If the tool call’s arguments contain an instance field (injected by the gateway into every tool’s schema), the router looks up that name in instances: HashMap<String, String> and routes there. Unknown instance names return RouteError::InstanceNotFound.
2. Otherwise, match by guild_id. If the arguments contain a guild_id, the router consults its guild_map: Arc<RwLock<HashMap<String, String>>>, where the keys are guild IDs and the values are instance names. If the map has the ID, it routes to that instance. If it doesn’t, returns RouteError::GuildNotFound.
3. Neither present returns RouteError::NoTarget, which the server layer turns into a helpful “available instances: …” error.

The guild map is populated by calling each backend’s list_guilds tool at startup and every 5 minutes thereafter (see “Lifecycle” below).

Session management

MCP’s Streamable HTTP transport uses Server-Sent Events (SSE) with a session ID header (Mcp-Session-Id). The backend opens the SSE stream on the initial POST, keeps it open, and sends JSON-RPC responses down it indexed by request ID. Each subsequent POST carries the session header so the backend knows which session the request belongs to.

The gateway maintains one BackendClient per configured instance, each with its own persistent session. On startup, initialize_backends calls initialize on every client — which does the MCP handshake (initialize request, read response, send notifications/initialized, start a background task that keeps the SSE stream open for future responses). Once initialised, subsequent tool calls reuse that session.

When a client sends a request to the gateway, the flow is:

1. Client → Gateway: single JSON-RPC POST to /mcp. Bodies are capped at 64 KiB by a RequestBodyLimitLayer in mcp-gateway/src/main.rs — JSON-RPC envelopes are tiny, and the cap stops authenticated callers from saturating the gateway with multi-MiB bodies.
2. Gateway parses the body. A malformed JSON envelope returns the spec-compliant JSON-RPC -32700 Parse error response instead of axum’s opaque 422, which keeps clients on the protocol’s own error model.
3. Gateway inspects method. For tools/list, the cached tool list is returned immediately. For tools/call, the gateway extracts instance, guild_id, and the tool arguments from params, picks a target via the router, and forwards the call to the chosen backend’s BackendClient::call_tool.
4. BackendClient::call_tool posts to <backend>/mcp, reads the response from the POST’s own SSE stream, and returns the result. (The earlier in-process pending-request dispatcher map has been removed — the original prototype kept a pending: HashMap<request_id, oneshot::Sender> and a background SSE reader, but in practice every backend response arrives on the same POST’s SSE stream, so the dispatcher was dead code. Removing it cut about 77 lines and eliminated a state machine that didn’t earn its keep.)
5. Gateway wraps the result in an event: message\ndata: {...}\n\n SSE frame and sends it back to the client with Mcp-Session-Id: gateway-session.

The gateway uses a single synthetic session ID (gateway-session) for all client connections, because it doesn’t actually track per-client state — every gateway request is a stateless proxy onto the backend’s real session. This is simpler than forwarding real session IDs and avoids the problem of tying a gateway restart to session IDs clients still expect to see.

Session recovery

MCP sessions can expire. When the backend returns a 404 Not Found or an error mentioning “Session not found”, handle_tool_call in mcp-gateway/src/server.rs re-initialises the dead backend client in place and retries the tool call once. This is transparent to the client: a successful retry looks exactly like a first-try success.

On top of the on-demand recovery, a background task spawned in mcp-gateway/src/main.rs runs every 5 minutes and does two things:

1. refresh_guild_map — health-checks every backend, re-initialises any unhealthy ones, and re-fetches each backend’s guild list to update the router’s guild map. Guild memberships change — a bot joins a new server, leaves an old one — and the 5-minute refresh keeps the map current without client action.
2. refresh_tool_list — re-fetches the tool catalog from a backend and rebuilds the cached tools/list response. Without this, a new tool added to a backend bot stays invisible to clients until the gateway itself is restarted, even though the bot already serves it correctly. The cached list is the same surface clients query, so freshness here matters as much as for the guild map.

Tool catalog

The gateway doesn’t define its own tools. On startup (and after re-init), it picks one arbitrary backend, calls tools/list on it, and caches the result. Every tool schema is mutated in flight to add an instance property:

"instance": {
    "type": "string",
    "description": "Bot instance name to route to, matching a key in the INSTANCES env var (e.g., 'bot_a', 'bot_b'). If omitted, routes by guild_id."
}

The gateway also appends its own synthetic tool:

• list_instances — returns a text blob listing every registered backend, its online/offline status, and the guilds it’s currently known to serve. Clients call this to discover the topology.

Because all instances run the same binary, their tool catalogs are identical, so asking one backend for tools is sufficient. If you ever run backends with mismatched tool sets, you’d need to change the catalog-building logic to union them.

Authentication

The gateway supports a single bearer token via the MCP_AUTH_TOKEN environment variable, enforced by an axum auth_middleware in server.rs. Every request must carry Authorization: Bearer <token> or it’s rejected with 401.

Because the gateway always binds 0.0.0.0:GATEWAY_PORT (so sibling containers on the Docker network can reach it), there is no loopback escape hatch. Running it without a token would expose every backend’s destructive Discord tools (ban, delete-channel, send-message, …) to anyone with network reach. To make that impossible to do by accident, mcp-gateway/src/main.rs panics at startup if MCP_AUTH_TOKEN is missing or empty (config.auth_token.is_none()), with a message naming the risk. Local development inside the same compose network still works — the operator just has to set a token, even if it’s a throwaway one.

The gateway uses a single shared-secret model: the same MCP_AUTH_TOKEN the middleware verifies on incoming requests is forwarded as Authorization: Bearer <token> on every outgoing request to a backend (BackendClient::auth_token, set from GatewayState::new). Backends in the bundled docker-compose deploy bind 0.0.0.0:9090 so the gateway sidecar can reach them over Docker DNS, and the bot-side strict guard therefore forces them to require a token of their own. One secret both sides share — the gateway verifies it inbound and forwards it outbound — keeps the configuration to one value and matches what the backend’s constant-time comparison expects.

One implementation detail worth knowing about: the gateway sends an explicit Host: localhost:9090 header on every outgoing request, overriding the Docker service name reqwest would otherwise use. The backend’s rmcp::StreamableHttpService enforces an allowlist on the incoming Host header as DNS-rebinding protection; the default allowlist contains only loopback names. Without the override, the backend would reject every gateway request with 403 Forbidden: Host header is not allowed.

Claude Code’s current MCP client prefers OAuth 2.1 over bearer tokens for remote servers, so running the gateway as a Claude Code remote-server target is more work than bearer auth suggests. Support for OAuth 2.1 in the gateway is tracked as future work.

Deployment topology

The gateway runs in its own Docker container from mcp-gateway/Dockerfile, alongside the bot containers. Its compose service (in the project’s top-level docker-compose.yml) declares depends_on: bot with condition: service_healthy, so the gateway doesn’t start until at least one backend is reachable. It binds its port to 127.0.0.1:9100 by default, keeping it local; operators who want remote MCP access typically front it with a reverse proxy that terminates TLS and adds whatever authentication their environment needs.

The health-check side uses the backend’s curl on http://localhost:9090/mcp to decide when the bot is ready to proxy requests to — a simple 2xx check on the HTTP endpoint.

Future work

• OAuth 2.1 support. Bearer tokens are fine for scripts, but Claude Code’s remote-server transport really wants OAuth. Adding an OAuth 2.1 code-flow endpoint to the gateway is the main gap before it’s ready for general consumer use.
• Dynamic instance registration. Today INSTANCES is read once at startup. An admin API to add/remove backends at runtime would avoid the restart cycle.
• Per-client sessions. The gateway collapses every client onto one synthetic session. Real per-client sessions would allow tool-call cancellation and progress streaming.
• Streaming tool responses. The current proxy waits for the full result from the backend and then sends one SSE frame back. Real streaming would let backends emit progress events for long-running tools.

Cross-links

• MCP Server — the user-facing description of what MCP does in this project.
• MCP Tool Catalog — the full list of tools the gateway exposes.
• MCP Exposure — deployment patterns for running the gateway on a public host.
• Multi-Instance Model — the deployment model the gateway was built for.

Database Schema

The bot’s persistent state is small and simple. Every table is created at startup by running sqlx::migrate! against versioned SQL files in migrations/, driven from src/db/mod.rs. All tables live inside one Postgres schema picked by the DB_SCHEMA environment variable and are read or written through helper functions in src/db/queries.rs. This page enumerates every table, its columns, who writes to it, and how the schema is bootstrapped.

Schema isolation recap

As described in Multi-Instance Model, the bot operates inside a Postgres schema whose name comes from DB_SCHEMA. At startup, init_pool creates that schema if it doesn’t exist, then configures the pool to run SET search_path TO "<schema>" on every new connection. From that point on, every unqualified table reference in the query layer resolves inside the instance’s own schema. One Postgres server can host as many instances as you like without any table collisions or per-query filtering.

ER diagram

erDiagram
    tempbans {
        SERIAL id PK
        TEXT guild_id
        TEXT user_id
        TEXT moderator_id
        TEXT reason
        TIMESTAMPTZ banned_at
        TIMESTAMPTZ expires_at
        BOOLEAN unbanned
    }
    guild_settings {
        TEXT guild_id PK
        TEXT audit_log_channel_id
        TEXT dj_role_id
        BOOLEAN dj_mode_enabled
    }
    stock_portfolios {
        TEXT guild_id PK
        TEXT user_id PK
        NUMERIC cash_balance
        TIMESTAMPTZ created_at
    }
    stock_holdings {
        SERIAL id PK
        TEXT guild_id
        TEXT user_id
        TEXT symbol
        NUMERIC quantity
        NUMERIC avg_cost
    }
    stock_transactions {
        SERIAL id PK
        TEXT guild_id
        TEXT user_id
        TEXT symbol
        TEXT action
        NUMERIC quantity
        NUMERIC price_per_share
        NUMERIC total_amount
        TIMESTAMPTZ created_at
    }
    stock_price_cache {
        TEXT symbol PK
        DOUBLE price
        DOUBLE prev_close
        DOUBLE change_pct
        TIMESTAMPTZ fetched_at
    }
    member_activity {
        TEXT guild_id PK
        TEXT user_id PK
        INTEGER message_count
        TIMESTAMPTZ first_seen
        BOOLEAN promoted
    }
    stock_portfolios ||--o{ stock_holdings : "owns"
    stock_portfolios ||--o{ stock_transactions : "records"

Relationships shown in the diagram are conceptual: there are no actual foreign keys in the schema. Every stock table carries (guild_id, user_id) as a denormalised composite, and the bot enforces consistency at the query layer (inside sqlx transactions for multi-table writes). This decision keeps migrations simple and makes per-guild data easy to delete in bulk.

Tables

tempbans

Tracks temporary bans so the unban worker can restore users when their ban expires. Feature: moderation (!m ban, !m unban, !m banlist).

Index: idx_tempbans_active on (guild_id, expires_at) WHERE unbanned = FALSE. This is a partial index — it only covers active bans — so the unban worker’s WHERE unbanned = FALSE AND expires_at <= NOW() sweep reads a small working set even in guilds with a long ban history.

Writers: create_tempban (from !m ban or the tempban AI tool), mark_unbanned (from !m unban), mark_unbanned_by_id (from the background unban worker in main.rs).

guild_settings

Per-guild configuration that’s mutable at runtime: audit log channel, DJ role, DJ mode toggle. Feature: admin (!m setlog, !m djrole, !m djmode) and moderation (uses the audit log channel).

Writers: the admin commands write via upsert_guild_setting (string values) and upsert_guild_setting_bool (boolean values). Both functions whitelist their column name against an ALLOWED_COLUMNS list in Rust before constructing the SQL, which is how the bot safely takes the column name as a parameter.

stock_portfolios

Virtual cash balance for the stock-trading game. One row per (guild, user) pair. Feature: stocks.

Primary key is (guild_id, user_id). The portfolio row is created on demand by get_or_create_portfolio using INSERT ... ON CONFLICT DO NOTHING followed by a SELECT.

stock_holdings

Share ownership: which symbols a user holds, how many, at what average cost. Feature: stocks.

Unique constraint: UNIQUE (guild_id, user_id, symbol) — one row per symbol per user per guild.

Index: idx_stock_holdings_user on (guild_id, user_id) for portfolio lookups.

Writers: buy_stock uses an upsert that recalculates avg_cost as a weighted average:

avg_cost = (old_avg * old_qty + new_price * new_qty) / (old_qty + new_qty)

sell_stock either reduces the quantity or deletes the row when the remaining amount is exactly zero (Decimal::is_zero() — replaces the old float-epsilon < 0.0001 guard now that arithmetic is exact).

All three mutating paths — buy_stock, sell_stock, and reset_portfolio — run inside a sqlx transaction that begins with a SELECT cash_balance FROM stock_portfolios WHERE ... FOR UPDATE on the relevant (guild_id, user_id) portfolio row. That row-level lock serialises every concurrent action against one user’s portfolio, so a !m stock reset running at the same time as a !m stock sell (or a parallel buy from the AI tool path) cannot interleave their reads of cash_balance and produce divergent totals. The cash update, holdings update, and transaction-log insert all commit atomically with that lock held.

stock_transactions

Immutable audit log of every buy/sell. Feature: stocks.

Index: idx_stock_transactions_user on (guild_id, user_id, created_at DESC) so !m stock history can fetch the most recent N trades without scanning.

stock_price_cache

Short-lived price cache to avoid hammering the Finnhub API. Feature: stocks.

TTL is enforced at query time: get_cached_price uses WHERE fetched_at > NOW() - INTERVAL '60 seconds', so anything older than 60 seconds is ignored and a fresh quote is fetched from the upstream API. There’s no separate eviction job.

This table intentionally stays DOUBLE PRECISION even after the stock_* Decimal migration — it’s a short-lived display cache, never fed into portfolio arithmetic without first being converted to Decimal at the API boundary in stocks::api::get_quote.

member_activity

Tracks messages sent per user per guild, for the auto-role promotion feature. Feature: auto-role.

Primary key is (guild_id, user_id). increment_message_count uses INSERT ... ON CONFLICT ... DO UPDATE ... RETURNING * so the caller gets the latest counts in one round trip, which is what the message handler uses to decide whether to queue a promotion attempt. See Auto-Role for the thresholds.

The two promotion paths — the per-message scanner inside handle_message and the 60-second background loop — would otherwise race on the same user when they happen to fire close together. The try_promote query closes that race with a single atomic claim: UPDATE member_activity SET promoted = TRUE WHERE guild_id = $1 AND user_id = $2 AND promoted = FALSE RETURNING .... Only one of the concurrent updates returns a row; the other returns nothing and exits silently. The caller that wins the claim is the one that performs the actual Discord role add, so a member is never double-promoted and never sees two welcome reactions.

What’s not stored

A lot of state the bot manages lives entirely in memory and never touches the database. Music queues, active Wordle and Connections games, rate-limit counters, idle timers, and tempban cache are all DashMap-based state on Data. Restarting the bot loses all of them, and that’s intentional — persisting a music queue across restarts would create more problems than it solves (stale URLs, replayed commands, surprise audio when the bot rejoins). Games are re-started by users on demand; rate limits reset cleanly; idle timers are disposable.

The things in the database are the things that must survive a restart: tempbans (so the worker can still unban someone), portfolios and trades (real virtual money), auto-role counters (so promotions happen at the right time), and DJ-mode settings (so operators don’t have to reconfigure after every deploy).

Migrations

Migrations live in the top-level migrations/ directory and are applied with the compile-time sqlx::migrate! macro. init_pool in src/db/mod.rs sets search_path on every connection and then calls sqlx::migrate!("./migrations").run(&pool), so each instance tracks its own migration history in a _sqlx_migrations table inside its own schema. Migrations are embedded in the binary at build time — no DATABASE_URL is needed at build time, and there’s no sqlx-data.json to regenerate.

File naming. Each file is <timestamp>_<description>.sql. Use a sortable UTC timestamp (YYYYMMDDHHMMSS) so sqlx applies them in the right order. The bootstrap migration is 20260414000000_init.sql.

Adding a new migration. Drop a new file into migrations/ with a later timestamp — for example, 20260501120000_add_user_timezone.sql — and include whatever DDL the change needs (ALTER TABLE, CREATE TABLE, backfill UPDATEs, etc). On the next startup, sqlx runs any unapplied migrations in order and records each one in _sqlx_migrations. Do not edit an existing migration file after it has been deployed — sqlx checksums the file contents and a mismatch aborts startup.

Existing-database compatibility. The init migration keeps IF NOT EXISTS on every CREATE so it is idempotent against the pre-migration databases that already have all the tables (production examplebot and secondbot). On those databases the init migration is a no-op at the SQL level; sqlx still writes the _sqlx_migrations row afterwards, so later migrations see a normal history.

Schema evolution (renaming a column, adding a NOT NULL default, dropping a table) is now a new migration file rather than a manual psql session. Destructive changes still deserve a release note in CHANGELOG and the Upgrading page.

Connection pool

The pool is a sqlx::PgPool built once in main.rs and handed to Data::db. Every feature module holds an &PgPool (or clones the pool — cloning is cheap because it’s just an Arc bump) and uses sqlx’s async query methods directly. There’s no repository layer, no DAO, no ORM — queries are SQL strings in src/db/queries.rs with typed parameter binding and FromRow deserialisation.

Most queries use query_as::<_, Model> for typed reads and query for writes. The compile-time-checked macros (query!, query_as!) aren’t used here because they’d require sqlx-cli to generate sqlx-data.json against a live database as part of the build, and the project prefers a simpler Docker build.

Backups

Backup strategy is owned by the Postgres container, not the bot. See PostgreSQL Setup for the recommended approach. Because every instance’s data lives in one schema, pg_dump --schema=<schema> gives you a clean per-instance backup, and dropping or restoring one schema leaves the others untouched.

Cross-links

• Multi-Instance Model — why the schema boundary is the multi-tenancy line.
• PostgreSQL Setup — deployment, tuning, backup.
• Data Flow — how commands reach the pool from event handlers.

Error Handling

This page describes how errors flow through the bot: where they start, where they get turned into user-visible messages, and where they’re logged and swallowed. The design is deliberately minimal — one error type, one on_error hook, and a handful of rules about who panics and who doesn’t.

The BotError type

Every fallible function in this codebase returns Result<T, BotError>, where BotError is a plain hand-written enum defined in src/error.rs:

#[derive(Debug)]
pub enum BotError {
    Serenity(serenity::Error),
    Sqlx(sqlx::Error),
    Reqwest(reqwest::Error),
    SerdeJson(serde_json::Error),
    Other(String),
}

Each variant wraps one upstream error type. The fifth variant, Other, is an escape hatch for ad-hoc string errors that don’t correspond to a specific upstream — BotError::Other("Not in a guild".into()) is a common pattern when a command can’t proceed because of a missing argument or a precondition failure.

Conversions live right next to the definition as From impls:

impl From<serenity::Error> for BotError { ... }
impl From<sqlx::Error> for BotError { ... }
impl From<reqwest::Error> for BotError { ... }
impl From<serde_json::Error> for BotError { ... }
impl From<String> for BotError { ... }

These From impls are the reason command handlers can use ? everywhere. let expires_at = create_tempban(...).await?; turns a sqlx::Error into a BotError::Sqlx and bubbles up, without the handler having to know what create_tempban can fail with. The enum implements std::error::Error and Display, so errors also format sensibly when logged.

There’s no thiserror, no anyhow, no derived From. The enum is small enough that hand-writing the impls is cleaner than pulling in a macro dependency, and the explicitness makes it obvious what kinds of errors the bot actually handles.

Where errors are surfaced

Command errors. Poise ties every handler’s return value to its framework error hook. A command returning Err(BotError::Sqlx(...)) or Err(BotError::Other("...".into())) raises a FrameworkError::Command, which the hook turns into a user-facing reply and a tracing log. That hook lives in main.rs and now uses BotError::user_message() to keep operator-only details out of chat:

on_error: |error| Box::pin(async move {
    match error {
        poise::FrameworkError::Command { error, ctx, .. } => {
            // Full error (including upstream sqlx/reqwest text) goes
            // to logs only.
            tracing::error!("Command error: {error}");
            // Sanitised, per-variant copy goes to the user.
            let _ = ctx.say(error.user_message()).await;
        }
        other => {
            tracing::error!("Framework error: {other}");
        }
    }
})

The split between Display and user_message() is deliberate:

• Display still produces the verbose form ("Database error: <sqlx message>", "HTTP error: <reqwest message>", …) and is what gets logged. It carries every byte of upstream context an operator might want to grep for.
• user_message() returns a fixed, generic per-variant string (“Something went wrong talking to the database. Please try again later.”, “Couldn’t reach an external service. Please try again.”, …) — except for Other(s), which is treated as already-curated copy and passed through verbatim. That last case is what makes short messages like "Not in a guild" and validation errors still surface naturally.

The user sees the short, friendly form. The operator sees the full upstream chain in the logs and can correlate by timestamp.

Other FrameworkError variants (permission denied, argument parse failure, missing subcommand) are logged but not replied to. The default poise behaviour is to post a short notice for some of these; the current hook is deliberately minimal, because command errors are rare and usually only interesting to operators.

Event handler errors. Event handlers (message handler, voice state, component interactions, member join) don’t return Result in the usual sense. The top-level event_handler function returns Result<(), BotError>, but it never actually returns Err — every sub-handler uses let _ = ... to swallow individual errors and continues. This is because an event handler has no good place to post an error: the “user” who triggered the event might be a raw gateway event like a voice state update, not a chat message, so there’s nothing to reply to.

Instead, event handlers emit tracing::error! or tracing::warn! at the site of the failure. For example, the auto-role promotion path inside handle_message spawns a task that logs via tracing::warn!("Auto-role promotion failed for {}: {}", ...). The user sees nothing; the operator sees the error in the logs.

Background task errors. main.rs spawns several long-running tasks (rate-limiter cleanup, tempban unban sweep, auto-role time-based check, donator sync). Each iteration body runs inside the run_supervised helper, which wraps it in AssertUnwindSafe(...).catch_unwind(). A panic inside one iteration is caught and logged via tracing::error! with the task name and panic payload, and the outer loop continues to the next iteration — “a background task should never take the bot down” is now enforced by the wrapper, not just by convention. Recoverable errors inside the body still use the same tracing::warn! / tracing::error! pattern and continue. See Concurrency Model: background task supervision for the JoinSet plumbing and graceful-shutdown story.

The AI pipeline. handle_mention doesn’t return a Result at all. It uses pattern matching and explicit return statements to exit on failure paths, and posts its own user-visible messages for things like “Something went wrong talking to the AI.” This is by design: the pipeline has too many recoverable states (classifier failure, vision failure, censored response, search failure) for the ? operator to express naturally, so it handles each one explicitly. The tool dispatch paths used to compose user-facing replies as message.reply(format!("Database error: {e}")) (and similar for reqwest/serde_json/MCP errors), which leaked the same internal detail the command path now hides. Those reply sites have all been swept to use the same generic copy as BotError::user_message(), with the full upstream error logged via tracing::error! carrying the failing tool name and guild ID for operator diagnostics.

Debug vs production

What gets logged and what gets shown to users is split on purpose:

• Logs (tracing::error!, tracing::warn!): the full Display form of BotError, including every byte of upstream context. These go to stderr and whatever log aggregator the operator has set up. tracing_subscriber::fmt::init() in main.rs is the default config — override with RUST_LOG to raise or lower the level.
• User messages (ctx.say(...), message.reply(...)): the output of BotError::user_message(). A failed DB query becomes "Something went wrong talking to the database. Please try again later."; a flaky upstream API becomes "Couldn't reach an external service. Please try again.". The user knows something is broken and that retrying is reasonable, but no SQL fragment, hostname, or serde path leaks to chat.

The split matters because upstream error messages can contain information that shouldn’t be in Discord — file paths, internal hostnames, table names, partial stack traces from dependencies. The old format!("Error: {e}") path leaked all of that whenever a handler bubbled up a BotError::Sqlx or BotError::Reqwest; the user_message() mapping closes that gap. The same swept the BotError::Other(format!("...{e}")) pattern out of the AI tool dispatch paths so a failing DeepSeek call can’t smuggle a raw HTTP body into chat by way of Other.

Panics

Panics are reserved for one specific case: startup config validation. The get_env_or_throw helper in src/config.rs panics if a required environment variable is missing or contains a placeholder value:

fn get_env_or_throw(key: &str) -> String {
    let val = env::var(key).unwrap_or_else(|_| panic!("{key} must be set in .env"));
    if val.starts_with("your-") {
        panic!("{key} has placeholder value — set it in .env");
    }
    val
}

This is used for DISCORD_TOKEN, CLIENT_ID, and GUILD_ID — the three variables without which the bot literally cannot connect. A missing value there is a deployment error that the operator needs to see immediately, in the clearest possible way, before the process starts doing real work. The panic message ends up in the process output and the operator fixes it.

The database_url, MCP bind config, and AI API keys do not panic. They fall back to defaults or stay unset, and the features that need them either disable themselves or warn at first use.

Optional config is never a panic. When config.toml has a feature enabled but its corresponding [feature_name] section is missing, main.rs warns through tracing::warn!(...) and skips the feature. For example:

let auto_role_config = if instance_cfg.features.auto_role {
    match &instance_cfg.auto_role {
        Some(cfg) => { /* log, enable */ Some(cfg.clone()) }
        None => {
            tracing::warn!("Auto-role feature enabled but [auto_role] config section missing");
            None
        }
    }
} else {
    None
};

The same pattern repeats for the minecraft donator-sync config, the chargeback config, the join-role config, and the welcome prompt file. Missing optional config is always a warning plus a disabled feature, never a crash. Operators can ship a bot with half its features half-configured and it’ll still start — the log just tells them what they missed.

Runtime panics elsewhere — inside a command handler, an event handler, or a background task — are considered bugs. If one happens, Tokio will catch the task panic and log it, and the rest of the runtime will keep going. The user whose command triggered the panic sees nothing, which is unpleasant but better than the process exiting.

Cross-links

• Data Flow — the shape of the call chain that produces these errors in the first place.
• Debugging — how to read the logs and track a failure back to its source.
• Environment Variables — the required variables whose absence produces a startup panic.

Concurrency Model

discord-bot-rs is a single-process async application. It handles many simultaneous guilds, commands, and background tasks on one Tokio runtime, without global locks. This page explains how it stays correct under concurrent load: which data structures it leans on, where mutex boundaries sit, and which patterns to copy when you’re adding a new feature.

The design rule is simple: locks are the last tool, not the first. Where a feature can get away with a lock-free concurrent map, it does. Where it needs serialised access within a single guild or channel, it uses a narrow tokio::Mutex around the minimum amount of state. No feature in the codebase holds a mutex across a network call, and there is no global RwLock<HashMap>-style state anywhere.

Tokio runtime

main.rs starts the app with #[tokio::main], which gives it a multi-threaded runtime using one worker thread per CPU by default. Everything the bot does — gateway events, HTTP requests, DB queries, yt-dlp subprocesses, MCP server, axum webhook router, background workers — runs as async tasks on this single runtime. There are no other runtimes, no threads spawned by std::thread::spawn, and no blocking I/O outside of spawn_blocking (which isn’t currently used anywhere).

The result is that scheduling decisions are centralised: Tokio can starve a slow task without blocking the rest, and cargo run boots into a fully functional bot without any threading ceremony.

The Data struct as shared state

Poise’s framework gives every command and event handler a reference to a user-defined state object. In this project that’s Data, defined at the top of src/main.rs. It’s built once at startup, wrapped in an Arc by poise, and handed out to every handler via poise::Context. Cloning an Arc<Data> is a single atomic refcount bump, so passing it into a spawned task is free.

Inside Data, the read-only fields (db, http_client, config, personality, bot_name, all the optional feature configs) are accessed concurrently without any locking — they’re either Arc- shared resources (the pool, the HTTP client) or immutable owned strings. The interesting parts are the mutable per-guild and per-channel maps.

DashMap for per-guild state

Six of Data’s fields are DashMap-based:

DashMap is a sharded concurrent hash map — internally it splits keys across a fixed number of shards, each with its own RwLock. Lookups of different keys hit different shards and don’t block each other. This is the shape of the workload here: two guilds’ music commands land on different DashMap shards and run concurrently; even two lookups inside the same guild’s DashMap won’t block because the inner value is Arc<Mutex<T>> and the outer map only holds the Arc.

Why not Arc<RwLock<HashMap<GuildId, T>>>? Because every write — a user starts a song in guild A — would have to take the write lock on the outer map, and every read from guild B would either have to wait or hold a read lock that blocks guild C’s write. DashMap eliminates that global contention by design.

Per-guild Mutex<T> inside DashMap

DashMap gives concurrent key-level access. Once a handler has its guild’s value in hand, it needs a way to serialise access inside that guild — because a music player is a single state machine and you don’t want the skip button to race with the play command. The pattern is to store Arc<Mutex<T>> as the value:

let player_arc = data.guild_players
    .entry(guild_id)
    .or_insert_with(|| Arc::new(Mutex::new(GuildPlayer::new(guild_id))))
    .value()
    .clone();

// Drop the DashMap entry guard before awaiting the inner mutex
let mut player = player_arc.lock().await;
player.enqueue(track);

Two important details:

1. Release the DashMap guard before the await. entry(...).value() returns a guard that holds the DashMap shard’s lock. Holding it while you .await on the inner mutex would hold up other handlers that need the same shard. The idiom is to clone the inner Arc out and let the guard drop.
2. Use tokio::sync::Mutex, not std::sync::Mutex. Tokio mutexes are designed to be held across .await points; std mutexes are not. A handler that’s holding a std::sync::Mutex across an .await can deadlock the whole runtime if Tokio happens to schedule the task back onto the thread that’s blocked on the same mutex. Every mutex in this codebase is a tokio mutex.

This pattern gives fine-grained concurrency: two guilds can run music commands in parallel, two channels can run Wordle games in parallel, and within one guild the music player is still serialised. No feature module has to coordinate with another, because they use different DashMaps.

Idle timers

The music idle timer pattern in src/music/voice.rs is a good example of how to manage cancellable background work in this style. When a track ends and the queue is empty, the track-end handler calls start_idle_timer, which:

1. Spawns a task that sleeps 300 seconds, then leaves the voice channel and cleans up.
2. Stores the task’s JoinHandle inside Data::idle_timers at the guild’s entry.

When the next track starts — or the user calls !m stop — the code calls cancel_idle_timer, which takes the handle out of the mutex and calls .abort() on it. Cancellation is atomic: either the task already ran and there’s nothing to abort, or it was sleeping and the .abort() drops its future.

The idle_timers DashMap’s value type is Arc<Mutex<Option<JoinHandle<()>>>>. The Option is there because a guild can be in the map without having an active timer (the slot exists but is empty). The Mutex protects the slot from the “start a new timer while the old one is being cancelled” race.

Rate limiting

src/util/ratelimit.rs implements a sliding-window limiter using — unsurprisingly — a DashMap:

pub struct SlidingWindowLimiter {
    buckets: DashMap<String, Vec<Instant>>,
    max_requests: usize,
    window: Duration,
}

The key is arbitrary (in practice, user_id.to_string()). The value is a vector of timestamps. When check is called, it prunes timestamps older than the window, then either returns 0 (allowed, append the current timestamp) or the seconds until the oldest timestamp expires (rate limited).

Because DashMap::entry gives unique access to one slot, two concurrent check calls for the same user serialise naturally through the entry guard. Two calls for different users land on different shards and don’t block each other.

Data::rate_limiters holds five of these, all enforced:

• ai — 10 requests per 60 seconds, used by the AI chat pipeline.
• music — 15 requests per 30 seconds, enforced on every !m music command and every AI music tool call.
• moderation — 5 requests per 60 seconds. Enforced both by the AI pipeline’s moderation tool execution path and by the prefix !m ban / !m unban / !m nuke commands. (Discord-side permission checks still apply on top.)
• stocks — 10 requests per 30 seconds, enforced on every !m stock command and every AI stock tool call.
• welcome — 1 event per 5 seconds per joining user. Throttles the join flow so a fast-rejoining account can’t spam the welcome prompt or AI greeting.

Bucket cleanup

Every check call inserts a vector of timestamps into the limiter’s DashMap entry, but nothing removes empty entries on its own. Without periodic eviction, memory would grow with the unique-user count over the lifetime of the process. To fix that, main.rs spawns a rate_limiter_cleanup background task that calls RateLimiters::cleanup_all() every 5 minutes. cleanup_all walks all five limiters, prunes timestamps older than each window, and drops entries that are now empty. This keeps the steady-state memory footprint proportional to the active user count rather than the all-time-unique user count.

Background task supervision

main.rs spawns several long-running loops (rate-limiter cleanup, tempban unban sweep, auto-role time check, donator sync). They used to be plain tokio::spawn calls with no panic recovery — a single panic inside the loop body would silently kill the whole task and the feature would simply stop working until the next restart, with nothing in the logs to tell the operator what happened.

The current pattern has two layers:

1. Per-iteration panic recovery. Every loop body runs inside the run_supervised(task_name, || async { ... }) helper defined at the top of main.rs. The helper wraps the body in AssertUnwindSafe(...).catch_unwind() so a panic inside one iteration is caught, logged via tracing::error! with the task name and panic payload, and then swallowed. The outer loop { ... sleep ... } continues to the next iteration. A bug in one tempban sweep doesn’t break tomorrow’s sweeps.
2. Task-level tracking via JoinSet. Background tasks are spawned into a JoinSet<()> owned by main(). A separate task awaits join_next in a loop and logs at error level if any supervised loop ever exits — which, with the panic-recovery wrapper in place, should never happen. If it does, the operator knows immediately rather than waiting to notice the missing behaviour.

Graceful shutdown

main.rs races client.start() against a shutdown_signal() future inside tokio::select!. shutdown_signal() resolves on Ctrl-C, and on unix it also resolves on SIGTERM (so docker stop and kill are honoured). When the signal fires, shard_manager.shutdown_all() is called before exit, which closes the gateway shards cleanly and gives songbird a chance to tear down voice connections instead of leaving them dangling on the Discord side.

Database pool concurrency

Sqlx’s PgPool is itself concurrent: it holds a bounded number of connections, hands them out to tasks that need them, and queues waiters when the pool is saturated. A handler that awaits a query yields the task to Tokio until a connection is free; no thread is blocked. That means running 50 simultaneous commands on 5 Postgres connections is fine — 45 of them will be parked, waiting their turn, while other tasks on the runtime continue unhindered.

Because the after_connect hook sets search_path per connection (see Multi-Instance Model), every query transparently lands in the right schema without per-query parameterisation. There is no per-query lock; sqlx handles concurrency through the pool.

Voice concurrency

Songbird runs its own audio processing inside the Tokio runtime. It spawns internal tasks for gateway traffic, UDP packets, Opus encoding, and track event dispatch. The bot’s main event handlers only talk to songbird through its API: manager.join, handler.play_input, handler.stop, and track_handle.add_event. All of those are non-blocking control calls. The actual audio pipeline runs on background tasks owned by songbird, so a slow handler on the main runtime doesn’t stutter playback.

What NOT to do

A few patterns are actively avoided:

• Don’t use std::sync::Mutex in async code. As explained above, holding one across an .await can deadlock the runtime. The only place in the codebase that uses std::sync primitives is AtomicBool, which is lock-free.
• Don’t hold a DashMap entry guard across an .await. Clone the Arc out and release the guard first. This keeps shard-level contention short and avoids mysterious stalls.
• Don’t invent a global RwLock<HashMap<GuildId, T>>. Use DashMap. If you find yourself wanting a global lock, reconsider the shape of your state: it probably should be keyed by guild or channel.
• Don’t block in a handler. Anything that would normally block (reading a file, running a subprocess, parsing a big input) should either be async (tokio::fs, tokio::process) or wrapped in tokio::task::spawn_blocking. The yt-dlp integration goes through tokio::process::Command, which is the right pattern.
• Don’t share !Send state across tasks. Every tokio task must be Send, so anything held across .await inside a task must be too. Tokio’s mutex guards satisfy this; Rc and RefCell do not.

Cross-links

• Data Flow — the lifecycle that these patterns are serving.
• Music Pipeline — the most elaborate example of the patterns on this page.
• AI Pipeline — the other heavy user of the rate limiter and per-user state.
• Multi-Instance Model — why none of this contention crosses instance boundaries.

Deployment Overview

This section is the operations manual for discord-bot-rs. It covers how to get a bot running on a real server, how to add a second one later, how to back up the database, when to expose the MCP port, and how to keep the whole thing alive long-term.

If you have not got a bot up locally yet, start with Quickstart and come back here once you are ready to put something on a host that lives longer than your laptop.

What ships in the box

The repo includes everything you need to deploy a single instance:

• A multi-stage Dockerfile that builds the bot binary on rust:bookworm and ships a debian:bookworm-slim runtime image with ffmpeg, yt-dlp, Node.js (for yt-dlp’s JS challenges), and the Opus / libsodium shared libraries the voice stack needs.
• A separate mcp-gateway/Dockerfile for the gateway service.
• A top-level docker-compose.yml that wires the bot, a postgres:17 container, and the gateway together with health checks and named volumes.
• An instances/example/ directory used as a fully-documented reference for config.toml, .env.example, and personality.txt.

There are also pre-built images on GitHub Container Registry — ghcr.io/mrmcepic/discord-bot-rs:0.5.0 and :latest, plus ghcr.io/mrmcepic/discord-bot-rs-mcp-gateway — for hosts where you do not want to build from source. They are amd64-only at the moment.

Recommended path: Docker Compose

Docker Compose is the path the repo is designed around and the path most operators should use. It gets you the bot, Postgres, and the MCP gateway with one command, with sensible defaults for restart policy, health checks, persistent volumes, and network isolation. Almost every other page in this section assumes you are running under Compose.

The defining choice in the Compose file is that the bot service is generic — it points at a configurable INSTANCE_DIR. The default is ./instances/example, but you select your own with:

INSTANCE_DIR=./instances/mybot docker compose up -d

That single switch lets the same Compose file run any instance you have configured under instances/. To run more than one bot at a time you copy the bot block in the Compose file, give it a unique service name, and point it at a different directory — see Multi-Instance Deployment for the recipe.

Other deployment shapes

You are not locked into Compose. The bot binary and the gateway are both standalone executables, and you can run them however your infrastructure prefers:

• Plain Docker — docker run the published images directly, bring your own Postgres, manage networking yourself.
• Kubernetes — wrap the same images in a Deployment and a StatefulSet for Postgres. There is no Helm chart in-tree, but the shape is straightforward enough that you can write one in an hour.
• Bare metal — cargo build --release, install ffmpeg, yt-dlp, libopus, libsodium, and Node.js, run the binary as a systemd unit, point it at a system Postgres. The build dependencies are listed in the Dockerfile.

The rest of this section is written against Compose because that is where the hardening, health-check, and upgrade workflows are best defined. If you are running under one of the alternatives, the configuration knobs and operational concerns are the same — only the mechanics of “restart this container” change.

Pages in this section

If something on a page surprises you, the architecture pages — especially Multi-Instance Model and MCP Gateway Routing — explain why the deployment shape looks the way it does.

Docker Compose Deployment

Docker Compose is the default deployment path. The repo ships a top-level docker-compose.yml that brings up the bot, a postgres:17 database, and the MCP gateway as a single coordinated stack. This page covers everything in that file: what each service does, what the environment variables mean, how the health checks compose, how to use a custom instance directory, what volumes persist, and what to look at first when something is broken.

If you have not run the stack at all yet, work through Quickstart first. This page assumes you have done that and want a deeper look at the moving parts.

The three services

services:
  postgres:    # PostgreSQL 17, bundled
  bot:         # the discord-bot binary
  mcp-gateway: # routes MCP requests to one or more bots
volumes:
  pgdata:      # persistent storage for postgres

postgres and bot are both required for a working deployment. mcp-gateway is only needed if you want an MCP client (Claude Code, Cursor, etc.) to be able to drive the bot programmatically — but since the gateway is harmless when nobody connects to it, it is included by default and you can ignore it until you need it.

The postgres service