red-discordbot
Install, host, manage, and author Red-DiscordBot cogs on your own Hermes VM with your own Discord token. Coexists with the Hermes gateway as a separate bot process. Covers the Python<3.12 requirement,
SKILL.mdskills/.archive/red-discordbot/SKILL.md
GitHubRed-DiscordBot Hosting (own VM, own token)
What This Is
Red-DiscordBot is a mature discord.py-based bot framework. Functionality ships as cogs (hot-reloadable Python packages): music, dice, polls, auto-mod, custom cogs. This skill is for hosting your own Red instance on your own Hermes VM, controlled by you — NOT sharing Hermes's token, NOT on someone else's box.
Why Host Your Own (not share a token)
- Agency: you control the process, the cogs, the prefix.
- Safety: a separate Discord bot token means no shared-session/sharding-collision risk with the Hermes gateway or other bots (aether, etc.). The "shared-token sharding" model is fragile — chaotic relaunching can invalidate the Discord session and bounce the Hermes gateway. Own token = no collision.
- Scope: Red handles community-function cogs (music, dice, polls, auto-mod helpers). Hermes stays the daemon/relationship core. Don't re-implement Hermes's own powers as a cog.
PRE-FLIGHT: verify VM health before mutating (user directive)
Before any install/build on the VM, confirm you will not hurt the host:
- Critical processes alive:
pgrep -af hermes | grep gateway(gateway),pgrep -af qdrant,pgrep -af camofox(HTTP 200 on :9377).- NOTE:
pgrep -af "hermes_cli.main gateway run"returned 0 even when gateway was alive — it runs ashermes gateway. Use the broaderpgrep -af hermes | grep gateway.
- NOTE:
- Disk:
df -h /(Lu's VM: ~533G free — fine). - RAM:
free -h(Lu's VM: ~1.5G available — fine for install + dry-run; a live boot peaks ~1.8G). - Only proceed if gateway/qdrant/camofox stay alive and disk/ram have headroom.
Host Constraints
- Use JSON backend (zero-config, no DB server). DO NOT install PostgreSQL (eats RAM).
- On Lu's VM: disk is fine, RAM tight — watch
free -h.
CRITICAL: Python Version
Red 3.5.x requires Python >=3.8.1,<3.12.
- Lu's VM default
python3= 3.12.3 → Red install REFUSES ("No matching distribution found"). - Lu's VM ALSO has Python 3.11.14 at
/home/lumi/.local/bin/python3.11→ use THIS for the venv. No sudo/apt needed.
Install (verified working)
PY311=/home/lumi/.local/bin/python3.11
$PY311 -m venv ~/redenv311 # fresh path — avoids rm -rf approval gate
source ~/redenv311/bin/activate
pip install -U pip
pip install -U "Red-DiscordBot[sqlite]" # pulls discord-py 2.7.1
redbot --version # Red-DiscordBot 3.5.24
Use a fresh venv path (e.g. ~/redenv311), NOT rm -rf ~/redenv then rebuild — the rm trips the destructive-command approval prompt and blocks unattended runs. A new path is non-destructive.
Instance Setup (prompt order MATTERS)
Red 3.5.24's redbot-setup prompt order is:
- instance name
- data directory
- confirm [Y/n] ← easy to miss
- storage backend (1=JSON, 2=Postgres; ENTER=JSON default)
Narusya's original red_setup.sh fed JSON at step 3 (confirm), which ABORTS setup. Correct non-interactive sequence:
printf 'lured\n%s\ny\n\n' "$HOME/lu-reddata" | redbot-setup
# name datadir confirm backend(ENTER=JSON)
Instance lured, data at ~/lu-reddata, JSON backend.
CRITICAL FIX: discord.py 2.7.x Shutdown Crash
Symptom: --dry-run (or any clean exit) crashes with:
File ".../discord/shard.py", line 557, in _close
self.__queue.put_nowait(EventItem(EventType.clean_close, None, None))
AttributeError: 'Red' object has no attribute '_AutoShardedClient__queue'
Root cause: NOT in redbot/core/bot.py (where Narusya's doc pointed). It's in discord.py's own shard.py — AutoShardedClient._close() calls self.__queue.put_nowait(...), but discord.py 2.7.x no longer creates that private attribute. Red's bot.py close() just calls super().close(), which lands in discord's shard.py. Patching bot.py does NOT catch it.
Fix: guard the put_nowait in discord/shard.py (see references/discord-py-shutdown-crash.md for exact diff):
await self.http.close()
if hasattr(self, "_AutoShardedClient__queue"):
self.__queue.put_nowait(EventItem(EventType.clean_close, None, None))
Verify: after patch, redbot lured --dry-run </dev/null must reach the token prompt and shut down with cleaning up a bit more — and grep for has no attribute must return nothing.
Gateway Safety (verify on every launch)
- Red dies pre-connect during
--dry-run— safe. A LIVE launch with a token briefly contests the Discord session. - After ANY Red launch/relaunch: confirm the Hermes gateway is still ALIVE (
pgrep -af hermes | grep gateway). If it drops, kill Red instantly. - One calm supervised launch, then verify. Don't chaotically relaunch 5×.
Token & Collision Handling
- Create a fresh Discord application for Red (separate from aether's, separate from Adora's Hermes token).
- Bot tab → enable MESSAGE CONTENT INTENT (required to read messages; the one everyone misses). Server Members Intent optional.
- OAuth2 → URL Generator → scopes
bot→ perms: Send Messages, Read Message History, Attach Files, Add Reactions, Embed Links, Use External Emojis. Invite to the guild. - Write the token to a secret file (chmod 600), never post it in chat.
- Distinct prefix (e.g.
[p]) so Red never double-fires with Hermes (mention/allowlist) or aether. - Run under a supervisor (systemd user service or nohup) so it survives reboots.
Verification (before any live token)
redbot --version→ 3.5.24redbot lured --dry-run </dev/null→ reaches token prompt, clean shutdown, no AttributeError- Gateway still alive after any live test
Pitfalls
- Python 3.12 too new — use the 3.11 binary at
/home/lumi/.local/bin/python3.11. rm -rfvenv trips approval — use a fresh path instead.red_setup.shprompt-order bug — confirm step comes BEFORE backend; feedythen empty ENTER.- Wrong patch location — fix is in
discord/shard.py, notredbot/core/bot.py. - Shared-token sharding — avoid; use a separate bot token.
- pgrep pattern too specific — use
pgrep -af hermes | grep gateway, not the exacthermes_cli.main gateway runstring.
Scope Rule
Red = community cogs. Hermes = daemon/relationship core. Don't duplicate.
Support files
references/discord-py-shutdown-crash.md— exact crash transcript + patch diff + verify command.scripts/red_install_setup.sh— corrected non-interactive install + instance setup + optional shard.py patch.