astrae

Guides

Sharding and clusters

Every guild lives on one shard. A small bot can hold every shard in one process. More shards is not automatically a cluster. Split when one process is the wrong failure domain.

astrae cluster mybot --clusters 8 --shards 64

CLI, deployment.

Names

Name Purpose
Gateway process Owns Discord sockets.
Worker process Consumes shard-affine event streams through Redis.
ClusterSupervisor Spawn, restart, and reshard local children.
ClusterContext Shard range and cluster identity for one child.
Redis Required for every gateway and worker in a split deploy.
Partition Ordering preserved per stream partition. At-least-once after a crash.

Process-local Redis

Name Purpose
RedisPool.shared(url) One pool per URL in this Python process.
Cluster children Separate processes. Separate pools. Size connections for the fleet.

Supervisor

Name Purpose
Contiguous shard ranges Assigned to children. Remainder goes to earlier processes.
Restart Unexpected exit. Exit 78 (InvalidToken) is not restarted.
Telemetry Local. Not cross-host service discovery.
Metrics ports Base port plus cluster ID. Keep them on loopback.
Token / Redis Injected via environment or supervisor env.