Sharding a discord.py bot across processes and servers
How to run a large discord.py bot as several clustered processes on more than one server: shard ranges, a supervisor with health checks and backoff, and shared state in PostgreSQL.
Most discord.js guides end with the built-in ShardingManager. In Python the story is thinner: AutoShardedBot runs every shard inside one process, and that is where many bots stay until the process runs out of memory or one slow handler stalls every guild. This is how Krypton, the Discord security bot I build, runs as several clustered processes spread across more than one server, and what I would tell anyone doing the same.
Why one AutoShardedBot stops being enough
A shard is one gateway connection that carries the events for a slice of your guilds. Discord tells you how many you need through GET /gateway/bot. AutoShardedBot opens all of them in one event loop, which is fine until a few things start to hurt:
- One Python process means one core for every event in every guild.
- A blocking call or a slow database query delays protection everywhere, not just in one server.
- A restart for a deploy or a crash disconnects every guild at once.
- You cannot move part of the load to another machine.
The fix is to run several processes, each owning a contiguous range of shards. I call each process a cluster. discord.py supports this directly: pass shard_ids and shard_count to AutoShardedBot and it only connects the shards you give it.
Splitting shards into clusters
The shard ranges must be deterministic, so any process on any machine can compute its own range from the same inputs with no coordinator. Ask Discord for the recommended count once, then divide:
import math
def split_shards(total_shards: int, clusters: int) -> list[tuple[int, int, int]]:
per_cluster = math.ceil(total_shards / clusters)
ranges, start = [], 0
for cluster_id in range(clusters):
end = min(start + per_cluster - 1, total_shards - 1)
if start > end:
break
ranges.append((cluster_id, start, end))
start = end + 1
return rangesWith 10 shards and 4 clusters this gives ranges of 3, 3, 3 and 1. Keep an override for the total so you can pin the shard count during a migration instead of having it change under you when Discord raises its recommendation.
Launching a cluster
Each cluster is the normal bot, told which shards it owns:
import discord
from discord.ext import commands
def make_bot(shard_start: int, shard_end: int, total: int) -> commands.AutoShardedBot:
return commands.AutoShardedBot(
command_prefix="!",
intents=discord.Intents.default(),
shard_ids=list(range(shard_start, shard_end + 1)),
shard_count=total,
)Krypton's launcher takes a cluster id from its environment, computes the range with the function above, and starts. Each cluster also serves a tiny HTTP health endpoint on its own port, which matters for the next part.
A supervisor that knows when to restart
A process manager like PM2 or systemd restarts a process that exits. That is not enough for a Discord bot, because the common failure is a process that stays alive but stops working: the gateway never reconnects, or the client closed and nothing noticed. So each cluster runs under a supervisor that asks it how it is doing.
The health endpoint returns a few fields: the process id, whether the client is ready, whether it is closed, and how long it has had no gateway connection. The supervisor polls it every 15 seconds and restarts the cluster when any of these is true:
- the process exited;
- the client reports that it is closed;
- it is still not ready long after starting;
- it has had no gateway connection for too long;
- several health checks in a row got no answer at all, after a startup grace period.
Two details saved me real debugging time. First, the health response includes the process id, and the supervisor ignores answers from a different pid: after a crash, a stale process can still be holding the port. Second, restarts back off exponentially, and the crash streak only resets after a run has stayed up for ten minutes:
def next_backoff(self) -> float:
if self.started_at and time.monotonic() - self.started_at >= STABLE_RUNTIME:
self.crash_streak = 0
self.crash_streak += 1
return min(BACKOFF_BASE * 2 ** (self.crash_streak - 1), BACKOFF_MAX)Without that, a cluster that crashes on startup hammers Discord's identify endpoint in a loop. With it, a bad deploy degrades to one restart every few minutes, which is loud in the logs and harmless to the gateway.
State that has to be shared
Once guilds live in different processes, anything that was a Python dict becomes a bug. Krypton keeps shared state in PostgreSQL and per-machine caches in Redis:
- A shard registry and cluster heartbeats in PostgreSQL, so a cluster can find which process owns a guild and reach it over HTTP.
- Claims instead of locks for actions that must happen once. Anti-nuke punishments are claimed with a unique row before acting, so two processes that see the same event cannot both punish. I tested it with five concurrent claims against a real database: exactly one wins.
- Row locks for redemptions, using
SELECT … FOR UPDATEand a conditional update, when exactly one person may win. - Lockouts and rate limits in the database, not in memory, so they survive restarts and apply no matter which cluster handles the request.
The rule of thumb: each guild is handled by exactly one process, so per-guild caches can live in memory, but anything that crosses guilds or must survive a restart goes to the database.
Checklist
- Compute shard ranges deterministically from the total and the cluster count.
- Pin the total shard count while you migrate.
- Stagger cluster starts.
- Give each cluster a health endpoint that reports readiness, closure and disconnection time.
- Supervise with health checks, not just exit codes, and ignore answers from another pid.
- Back off restarts exponentially and reset only after a stable run.
- Move every cross-guild or must-happen-once decision into the database.
None of this is exotic, but the pieces only work together. If you are building something similar, the Krypton case study has the rest of the architecture, and I am happy to talk it through.
