Aetheris: Discord Infrastructure as Declarative Code
Autonomous engine for Discord servers: Git-versioned YAML manifests, idempotent diff before apply, and a Python bot as the single write path.
The server, declared in a manifest
Aetheris treats Discord server configuration as code. Roles, categories, channels, permission overwrites, AutoMod rules and embeds are described in a YAML manifest (schema_version: 1) that lives in a Git repository, where it gets reviewed, versioned and reverted like any other code. The dashboard (planobinario/aetheris-web, Astro 5 served from Cloudflare Pages) edits, validates and previews. The bot (planobinario/aetheris, Python with discord.py and Pydantic) executes. Nothing gets hand-edited in production.
A single write path
The rule holding the system together is simple: only the bot mutates Discord. The web validates the manifest to fail fast on anything outside the contract, enqueues a job (apply or structure_sync) on the aetheris-lock worker, built on Durable Objects with a 25-job cap and 10-minute expiry, and streams progress back live. If the bot is not consuming the queue, the session fails with a 503 apply_requires_worker instead of pretending it applied. The old TypeScript write engine was deleted in full: roughly 1,700 fewer lines to maintain.
Diff before touching anything
Every apply starts by comparing the live server state against the manifest and showing the delta: which roles, channels and permissions change, and in which order. Dependencies resolve through a directed acyclic graph (categories, roles, channels, overwrites and AutoMod) so nothing references identifiers that do not exist yet. The dispatcher honors Discord rate-limit buckets by reading X-RateLimit headers in real time, with per-route queues instead of bursts that end in a 429.
Permissions and AutoMod with real numbers
All 53 permission flags validate as bitmasks with hierarchy precedence, so a channel-level overwrite cannot slip past a misconfigured moderator role. Anti-raid rules compile down to deterministic finite automata so phishing, token-grabber and invite-filter protection fits the Discord budget: 260 characters and 10 rules per guild.
Sessions, audit trail and production
Access goes through Discord OAuth2. Tokens travel sealed under AES-256-GCM, and middleware checks Origin and Sec-Fetch-Site on every request. The dashboard API allows 30 requests per minute per IP and rejects bodies over 260 KB before parsing. Every run leaves its audit trail. The reverse path exists too: the workspace generates the manifest from the live server, with emojis, stickers, sounds and branding each carrying their SHA-256.
The bot runs as a dedicated systemd service and the web serves from the edge. Shipping code and deploying are two separate, deliberate steps, never an accidental push.