Sharding & Multi-Process Scaling
When a Discord bot joins more than 2,500 guilds, Discord enforces Gateway Sharding. Each shard maintains its own independent WebSocket connection and handles a fraction of the bot’s total servers.
How Shard Allocation Works
Section titled “How Shard Allocation Works”Discord distributes guilds across shards using a deterministic snowflake formula:
$$\text{Shard ID} = (\text{Guild ID} \gg 22) \pmod{\text{Total Shards}}$$
Lunibee handles this calculation automatically via manager.getShardIdForGuild(guildId).
import { ShardManager, GatewayIntentBits } from "lunibee";
const manager = new ShardManager({ token: process.env.DISCORD_TOKEN!, intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages], shardCount: "auto", // Automatically requests Discord's recommended shard count});
await manager.connect();import { ShardManager, GatewayIntentBits } from "lunibee";
const manager = new ShardManager({ token: process.env.DISCORD_TOKEN, intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages], shardCount: "auto", // Automatically requests Discord's recommended shard count});
await manager.connect();Cross-Shard Messaging with ShardBus
Section titled “Cross-Shard Messaging with ShardBus”ShardBus passes messages between shards. Inside one process it uses a named BroadcastChannel; in a cluster forked by ClusterManager it uses IPC automatically (0.3.1), because a BroadcastChannel does not cross fork()ed processes.
ClusterManager (parent) ├─ cluster 0 ── shards 0, 1 ──┐ worker.send(frame) ├─ cluster 1 ── shards 2, 3 ──┼─▶ parent relays the frame to every other cluster └─ cluster 2 ── shards 4 ──┘ and, when a cluster exits, tells the others which shards are goneYour code does not change: new ShardBus(shardId, "my-bot") picks the transport. Pass { transport } (a ShardBusTransport: post, onMessage, close) to override it. A request to a shard whose cluster dies rejects at once instead of waiting for its timeout, maxPending (10,000 by default) bounds the requests waiting for replies, and an error thrown by a handler reaches onError listeners, or becomes a process warning (LUNIBEE_SHARD_BUS_ERROR) when there are none.
import { ShardBus } from "lunibee";
const bus = new ShardBus(shardId, "my-bot");
// Fire-and-forgetbus.on("reload", (message) => reloadConfig(message.data));bus.broadcast("reload", { section: "commands" });
// Errors thrown or rejected by handlersbus.onError((error, message) => console.error(message.type, error));Queries across shards
Section titled “Queries across shards”respond() answers requests. request() asks one shard; broadcastRequest() asks every
other shard and collects replies until expected arrive or the timeout passes. Shards
query each other without sending code to be evaluated.
bus.respond("guildCount", () => client.guilds.cache.size);
const one = await bus.request<number>(1, "guildCount", null); // throws on timeoutconst all = await bus.broadcastRequest<number>("guildCount", null, { expected: totalShards - 1, timeoutMs: 5_000,});const total = all.reduce((sum, r) => sum + (r.result ?? 0), 0);Events, buckets and the start limit (0.3.1)
Section titled “Events, buckets and the start limit (0.3.1)”ShardManager re-emits what its shards do, each with the shard id first: shardReady, shardDisconnect (with { code, action }), shardResume, shardError and shardUnstable; ready (no arguments) fires once every shard it owns is ready, and again after a shard recovers.
manager.on("shardReady", (id) => console.log(`shard ${id} ready`));manager.on("shardDisconnect", (id, { code }) => console.warn(`shard ${id} closed: ${code}`));Discord rate-limits IDENTIFY per shard_id % max_concurrency. Lunibee groups the shards that need a connection by that key and starts the next shard of every bucket together, then waits spawnDelay (5 s) before the next round. It refuses to start, with a clear error, when /gateway/bot reports fewer remaining session starts than shards to connect. getShardIdForGuild() keeps using the shard count of the current set while a reshard has no shards, and fetchGatewayBot(token) is the one helper both managers use to read /gateway/bot.
Startup Pacing and Health
Section titled “Startup Pacing and Health”With shardCount: "auto", the manager reads /gateway/bot and starts shards
in rounds of Discord’s max_concurrency (override with maxConcurrency),
waiting spawnDelay between rounds. It refuses to start more shards than the
remaining session-start budget and tells you when it resets.
const manager = new ShardManager({ token, intents, shardCount: "auto" });await manager.connect();manager.health(); // [{ id, state, ping, status }, ...]Rounds are spaced from the moment each shard sends IDENTIFY/RESUME, not from
socket open (handshakeTimeout, default 15 s, bounds that wait). A
maxConcurrency override is capped at Discord’s value. Shards that are
already connected do not count against the session start limit, and a
too-small budget never tears down running shards.
Restarting crashed clusters
Section titled “Restarting crashed clusters”ClusterManager re-forks a cluster that exits. By default every crash is restarted after restartDelay (5 s). For a crash loop, add a supervisor policy:
new ClusterManager({ token, script: "./bot.js", supervisor: { restartDelay: 1000, backoff: 2, maxDelay: 60_000, jitter: 0.2, maxRestarts: 5, window: 60_000 }, onGiveUp: (cluster) => console.error(`cluster ${cluster.id} keeps crashing`),});Each crash inside window multiplies the delay by backoff (doubles it here; up to maxDelay, plus jitter); more than maxRestarts crashes inside window stops restarting that cluster and calls onGiveUp. A cluster that stays up for a full window starts over. ShardSupervisor is exported for custom managers.
ShardManager and ClusterManager together (0.3.1)
Section titled “ShardManager and ClusterManager together (0.3.1)”Two managers, two jobs. ClusterManager orchestrates processes; ShardManager runs shards. The ClusterManager decides which cluster owns which shard, forks one worker per cluster, keeps the workers alive and hands out IDENTIFY slots. Inside each worker a ShardManager opens the Gateways for the shards that cluster owns. A shard is never owned by two clusters, and no manager starts a shard the other one owns. Shards are split in contiguous blocks (clusterCount: 3 over 10 shards: [0-3] [4-6] [7-9]; shardsPerCluster: 4: [0-3] [4-7] [8-9]), the plan event reports the split, and startup: "sequential" starts one shard at a time across all clusters. A Client in a worker runs one of the cluster’s shards: gateway: { shardId, shardCount }.
ClusterManager (parent process) ├─ owns: shard → cluster map, restarts, IDENTIFY slots, request routing, health ├─ cluster 0 ── ShardManager { shards 0, 1 } env: SHARD_LIST=0,1 └─ cluster 1 ── ShardManager { shards 2, 3 } env: SHARD_LIST=2,3Parent
Section titled “Parent”import { ClusterManager } from "lunibee";
const clusters = new ClusterManager({ token: process.env.DISCORD_TOKEN!, script: "./worker.ts", shardCount: "auto", // or a number shardsPerCluster: 2, // or clusterCount waitForReady: true, // spawn() resolves when every cluster is ready startTimeout: 120_000, // kill and restart a cluster that never reports ready supervisor: { restartDelay: 1000, backoff: 2, jitter: 0.2, maxRestarts: 5 }, reassignOnGiveUp: true, // move a failed cluster's shards to a healthy one});
clusters.on("clusterReady", (cluster) => console.log(`cluster ${cluster.id} ready`));clusters.on("clusterRestart", (cluster, { delay, attempt }) => console.warn(`cluster ${cluster.id} restarts in ${delay}ms (#${attempt})`));clusters.on("error", (error) => console.error(error));
await clusters.spawn();import { ClusterManager } from "lunibee";
const clusters = new ClusterManager({ token: process.env.DISCORD_TOKEN, script: "./worker.js", shardCount: "auto", shardsPerCluster: 2, waitForReady: true, startTimeout: 120_000, supervisor: { restartDelay: 1000, backoff: 2, jitter: 0.2, maxRestarts: 5 }, reassignOnGiveUp: true,});
clusters.on("clusterReady", (cluster) => console.log(`cluster ${cluster.id} ready`));clusters.on("error", (error) => console.error(error));
await clusters.spawn();Worker
Section titled “Worker”import { ShardManager, ShardBus, GatewayIntentBits } from "lunibee";
// Inside a cluster the ShardManager reads the worker contract from the// environment: it owns only this cluster's shards, asks the parent for every// IDENTIFY, and tells the parent when all its shards are ready.const shards = new ShardManager({ token: process.env.DISCORD_TOKEN!, intents: [GatewayIntentBits.Guilds],});
for (const id of shards.shardIds) new ShardBus(id, "my-bot").respond("guildCount", () => 42);
await shards.connect();import { ShardManager, ShardBus, GatewayIntentBits } from "lunibee";
const shards = new ShardManager({ token: process.env.DISCORD_TOKEN, intents: [GatewayIntentBits.Guilds],});
for (const id of shards.shardIds) new ShardBus(id, "my-bot").respond("guildCount", () => 42);
await shards.connect();How many shards, how many per cluster
Section titled “How many shards, how many per cluster”Two numbers decide the layout, and you can set either:
- Guilds per shard. Discord assigns a guild to a shard by its ID, so you cannot place guilds one by one; you choose the shard count. With
shardCount: "auto",guildsPerShard: 1000givesceil(guilds / 1000)shards (at least one), using the guild count Discord reports for your application, orguildCountif you pass it. WithoutguildsPerShard,"auto"uses Discord’s own recommendation. It must be 1 to 2500 (Discord’s limit per shard; anything else throws aRangeError), and the count is re-checked byautoScaleInterval. Guild IDs spread evenly, so a shard holds about that many guilds, not exactly. - Shards per cluster.
shardsPerCluster: 4startsceil(shards / 4)clusters; or setclusterCountinstead (not both).
new ClusterManager({ token, script: "./worker.ts", shardCount: "auto", guildsPerShard: 1000, shardsPerCluster: 4 });// 12,000 guilds → 12 shards → 3 clusters of 4 shardsThe worker contract
Section titled “The worker contract”ClusterManager sets these variables in every worker. readClusterContext() parses them; isClusterWorker() tells a worker it is one.
| Variable | Meaning |
|---|---|
LUNIBEE_CLUSTER_WORKER=1 |
This process is a worker. A ClusterManager refuses to spawn() here, so a worker can never fork the fleet again. |
CLUSTER_ID, CLUSTER_COUNT |
This cluster, and how many clusters the deployment started. |
SHARD_COUNT |
Total shards in the deployment (Discord’s num_shards). |
SHARD_LIST |
Comma-separated shard IDs this cluster owns. |
LUNIBEE_SHARD_BUS=ipc |
ShardBus uses IPC instead of a BroadcastChannel. |
LUNIBEE_IDENTIFY |
coordinated when the parent hands out IDENTIFY slots, otherwise local. |
A ShardManager in a worker rejects an autoScaleInterval, shardCount: "auto", a shardCount that differs from SHARD_COUNT, and shardIds it does not own. Outside a worker, shardIds lets one ShardManager run a slice of a larger deployment.
IDENTIFY across the whole deployment
Section titled “IDENTIFY across the whole deployment”Discord allows one IDENTIFY per shard_id % max_concurrency key every five seconds, for the whole bot. The parent holds that rule for every cluster: a worker asks for a slot before it connects a shard and gives it back once the IDENTIFY went out, so two clusters can never IDENTIFY on the same key within the interval, and fork order does not matter. With shardCount: "auto" the parent also reads the session-start budget; when it is exhausted, requests wait for the reset (an identifyWait event says so) instead of failing and crash-looping. maxConcurrency lowers Discord’s value, identify: { interval, holdTimeout } tunes the pacing, and identify: { coordinate: false } returns to per-cluster pacing. spawnInterval (default 500 ms) only spreads the CPU cost of forking.
With a fixed shardCount the parent does not call Discord: pass maxConcurrency, or fetchLimits: true to read it and the budget from /gateway/bot. A reconnect after an invalid session is the Gateway’s own affair and does not use a slot.
Readiness and lifecycle
Section titled “Readiness and lifecycle”A cluster is starting until its ShardManager reports every shard ready, then ready; a crash makes it restarting (or failed once supervisor.maxRestarts is exceeded). ready(timeoutMs?) resolves when every shard is served by a ready cluster (a failed cluster whose shards were reassigned no longer counts) and rejects if a failure leaves shards with no owner, waitForReady makes spawn() do that, and startTimeout turns a cluster that never reports ready into a crash. Workers that do not use ShardManager can call ClusterWorker.current()?.ready() themselves. spawn() and shutdownAll() are idempotent and safe to call concurrently; shutdown cancels restarts and pending requests, sends SIGTERM and escalates to SIGKILL after shutdownTimeout. A deliberate shutdown, including killAll(), is never restarted.
Requests, broadcasts and routing
Section titled “Requests, broadcasts and routing”// One shard: routed to the cluster that owns it.const stats = await clusters.request<{ guilds: number }>(3, "stats", null, { timeoutMs: 3000 });
// Every shard of every live cluster. It never rejects for a slow or dead shard.const { replies, missing } = await clusters.broadcast<number>("guildCount", null, { timeoutMs: 5000 });const total = replies.reduce((sum, r) => sum + (r.result ?? 0), 0);// replies: [{ shardId, result } | { shardId, error }]; missing: shards that did not answer
// One worker process (not a shard): answered by ClusterWorker.onRequest().await clusters.requestCluster(1, "flushCaches", null);Shard handlers are the same bus.respond() handlers as between shards. Messages between workers go only to the cluster that owns the target shard (a broadcast goes to every other cluster); a message to a shard whose cluster is down fails fast. Every request has a timeout, an optional AbortSignal, and a bound on how many can wait (maxPendingRequests). Answers are accepted once, and only from the cluster that owns the shard; late, duplicate and unknown answers are dropped, and a cluster that dies settles its open requests at once.
Health
Section titled “Health”clusters.health(); // last known state, nothing is sentawait clusters.refreshHealth({ metrics: true }); // asks every worker; metrics are opt-in// { state, totalShards, readyClusters, missingShards,// clusters: [{ id, state, pid, shardIds, uptimeMs, restarts, readyAt, lastReadyAt,// shards: [{ id, state, status, ping, readyAt, disconnectedAt }],// metrics?: { rssBytes, heapUsedBytes, cpuUserMicros, cpuSystemMicros } }] }A shard’s lifecycle status (idle, connecting, ready, disconnected, unstable, destroyed) is separate from its Gateway state. Cluster health follows the process: a transient Gateway problem in one shard, a reconnect storm included, never restarts a healthy cluster; the Gateway’s own reconnect and zombie detection handle it. Only an exited process (or a missed startTimeout) is restarted.
When a cluster keeps crashing
Section titled “When a cluster keeps crashing”By default a cluster that exceeds supervisor.maxRestarts stays down (clusterGiveUp, onGiveUp). With reassignOnGiveUp: true the parent asks the ready cluster that owns the fewest shards to start them; ownership moves only after that worker confirms, and the failed process is already dead, so no shard has two owners. If no cluster is ready or the worker refuses, an error event says so, the shards stay down, and pending ready() calls reject.
Multiple hosts
Section titled “Multiple hosts”One coordinator (a ClusterManager) and one host agent (ClusterHost) per extra machine. The coordinator keeps everything above: the shard-to-cluster map, IDENTIFY slots, routing, health and recovery. A host only starts the worker script for the clusters placed on it and relays their IPC frames over a WebSocket, so a cluster on another machine behaves like a local one, and IDENTIFY pacing holds for the whole bot.
import { ClusterManager } from "lunibee";
const clusters = new ClusterManager({ token: process.env.DISCORD_TOKEN!, script: "./worker.ts", // only used for clusters on this machine (remote.local) shardCount: "auto", clusterCount: 6, waitForReady: true, remote: { port: 7070, hostname: "0.0.0.0", // the default, 127.0.0.1, is this machine only tls: { cert: process.env.TLS_CERT!, key: process.env.TLS_KEY! }, // required beyond loopback secret: process.env.CLUSTER_SECRET!, // 16+ characters, shared with every host hosts: ["eu-1", "eu-2", "us-1"], // clusters are placed on these, in this order lease: 15_000, },});await clusters.spawn(); // waits for the hosts to join, then places clusters on them
// host.ts, on each machineimport { ClusterHost } from "lunibee";
const host = new ClusterHost({ url: "wss://coordinator.example.com:7070", secret: process.env.CLUSTER_SECRET!, id: "eu-1", script: "./worker.ts", // the host decides what runs; the coordinator cannot});await host.connect(); // rejects if the secret or ID is refused; reconnects by itself laterimport { ClusterManager } from "lunibee";
const clusters = new ClusterManager({ token: process.env.DISCORD_TOKEN, script: "./worker.js", shardCount: "auto", clusterCount: 6, waitForReady: true, remote: { port: 7070, hostname: "0.0.0.0", tls: { cert: process.env.TLS_CERT, key: process.env.TLS_KEY }, secret: process.env.CLUSTER_SECRET, hosts: ["eu-1", "eu-2", "us-1"], lease: 15_000, },});await clusters.spawn();
// host.js, on each machineimport { ClusterHost } from "lunibee";
const host = new ClusterHost({ url: "wss://coordinator.example.com:7070", secret: process.env.CLUSTER_SECRET, id: "eu-1", script: "./worker.js",});await host.connect();Placement. Cluster n goes to host n % hosts.length, in the order of remote.hosts (or, without it, the hosts that had joined at spawn(), sorted by ID; minHosts says how many to wait for). remote.local: true adds the coordinator’s own machine as the first place. A cluster stays on its host for the life of the spawn: when it crashes it restarts there. While the host is away, each restart attempt fails at once and counts toward supervisor.maxRestarts, so a long outage can take the cluster to failed; set maxRestarts and window with that in mind. With reassignOnGiveUp, its shards move to a ready cluster on any host after supervisor.maxRestarts.
Security.
- A host proves it knows
remote.secretby answering a random challenge with an HMAC (the secret never travels), and the coordinator checks it in constant time. A failed proof, unknown IDs (whenhostsis set), duplicates, protocol mismatches, malformed or binary frames, a missing hello and too many unauthenticated connections are closed with codes4401,4410,4409,4426,4400,4408and4429(RemoteClose). - A coordinator can only set the worker contract variables (
SHARD_LIST,SHARD_COUNT,CLUSTER_ID,CLUSTER_COUNT,LUNIBEE_SHARD_BUS,LUNIBEE_CLUSTER_WORKER,LUNIBEE_IDENTIFY) in a remote worker and can only sendSIGTERM,SIGKILLorSIGINT; the script is the host’s own, and the bot token is read from the host’s environment, never sent. - Encryption is required off this machine. The coordinator listens on
127.0.0.1unless you say otherwise, and refuses to listen on any other address withoutremote.tls(wss://). Behind a TLS proxy, bind127.0.0.1and let the proxy forward; on a network you fully trust,remote.allowInsecure: trueaccepts plainws://. AClusterHostlikewise refusesws://to another machine unlessallowInsecure: true. The HMAC proves who a host is; it does not encrypt or sign frames, so without TLS shard messages and worker output travel in the clear. - Size limits. Frames on the host link are capped at 8 MiB, and
maxMessageBytes(default 8 MiB) caps what the coordinator relays from any worker, local or remote, and whatrequest(),broadcast()andrequestCluster()accept. An oversized worker message is dropped with anerrorevent; a request waiting for it times out as usual, and an oversized answer to a request settles it with an error at once.
Failure and fencing. A shard must never run in two places. A host kills all its workers the moment its connection closes, and also after one lease without hearing from the coordinator. The coordinator pings every third of a lease and treats a host as lost only after two leases of silence, so the host has already fenced itself; only then are its clusters restarted (hostLeave event). When a host reconnects with the same ID (it retries with backoff), its clusters start again on it (hostJoin). hosts() lists every host with its clusters, and health().clusters[].host says where each cluster runs.
Limits
Section titled “Limits”- The coordinator is a single process and a single point of failure for the deployment: if it stops, hosts fence their workers. Run it under a supervisor.
remoteneeds Bun on the coordinator (it listens withBun.serve); aClusterHostneeds a globalWebSocketandchild_process.fork(Bun or Node 22).- Hosts do not take over for a lost coordinator, and a lost host’s clusters are not moved to other hosts unless
reassignOnGiveUpis on. - Messages between shards of the same worker process do not go through the parent: the parent relays only between clusters.
- Gateways you create yourself (a plain
Clientwithgateway: { shardId }) are not paced by the parent; useShardManagerorClusterWorker.current()?.identifyGate.