Caution
Breaking change in v1.2.0: JohnnyBot now installs with uv, not pip.
requirements.txt is gone. Auto-update will not carry you across this release —
a bot on v1.1.x that tries to auto-update will post an "Auto-update failed" alert
and keep running the old version. To upgrade, on the host:
curl -LsSf https://astral.sh/uv/install.sh | sh # or: brew install uv
cd johnnybot
git pull --ff-only
uv sync --frozen --no-dev
uv run --frozen --no-dev bot.py # update your service unit / start script to matchAfter that, auto-update works again — as long as uv is on the bot's PATH.
See CHANGELOG.md for details.
JohnnyBot does all of the stuff Discord bizarrely won't let you do! Designed to automate tons of server management and enforce some rules while you're at it. It provides features such as mass role management, message moderation, permissions cloning, event feed integration, and an automatic anti-raid suite to ensure a smooth server experience. Most moderation commands require the "Manage Messages" permission (no role to create or name — works on any server out of the box); server backup and restore commands require the stricter Administrator permission. PetBot commands can be leveraged by all users.
For complete documentation, installation guides, and command references, visit the JohnnyBot Wiki.
- Wiki Home - Project overview and features
- Setup Guide - Complete installation and configuration
- Commands Reference - All available commands with examples
- Safety Systems - Raid protection, anti-nuke, and spam filtering in depth
These run without being invoked, so they are worth knowing about before you deploy:
- DMs to the bot get you kicked. Anyone who sends the bot a direct message is removed from every server they share with it, and the kick is reported to the moderators channel. Two exemptions: users with the Manage Messages permission, and anyone the bot itself DMed in the last 24 hours — so replying to a
/message_dumparchive,/media_dumplink or/log_tailoutput is safe. - Protected channels are enforced. Messages posted by anyone without Manage Messages in any channel listed in
PROTECTED_CHANNELSare deleted. - Voice channel chaperone. When a voice channel contains exactly one adult and one child (by
ADULT_ROLE_NAMES/CHILD_ROLE_NAMES), everyone in it is server-muted and the moderators channel is alerted once. The mute lifts automatically when the channel is no longer one adult and one child, when a muted member moves to a safe channel, or when the feature is disabled — including across a bot restart, since outstanding mutes are persisted tochaperone_mutes.json. Only mutes the bot applied are lifted; a manual moderator mute is never undone. Toggle with/voice_chaperone. - Raid protection. A burst of joins (default 6 within 30s) pauses invites and DMs between members for an hour using Discord's own self-expiring incident actions, and alerts moderators. The pause lifts itself — no cleanup needed, even if the bot restarts. The alert includes an avatar-cluster breakdown ("12 of 14 share one image"), since bulk-created raid accounts reuse profile pictures. Toggle with
/raid protection. - Anti-nuke. Watches the audit log for a compromised moderator account or rogue integration: 3+ destructive actions (channel/role deletes, kicks, bans, webhook creation) in 60s, a member prune, or any grant of a dangerous permission. By default it strips the offending account's roles and reverts the permission change itself, then alerts. Reversible via
/assign_roleif it's a false alarm. Toggle with/nuke_protection. - Message spam protection. Deletes and times out for the same link posted in 2+ channels within 30s, or 3+ mentions in one message. Offenders whose account is under 2 days old are kicked instead. Link detection is behavioral rather than a domain blocklist, so it catches brand-new scam domains with nothing to maintain. Toggle with
/spam_protection.
Each of these can be turned off at runtime. Moderators are exempt from spam protection and from /raid kick_recent — but deliberately not from anti-nuke, since a compromised moderator account is exactly what it exists to catch.
- Version announcements. On the first start after the running commit changes, the moderators channel gets a short "updated
v1.0.0→v1.1.0" notice with the release notes. This is what confirms an update actually landed — the existing notices are sent before the restart, so a bot that failed to come back up looked identical to one that succeeded. It also covers manualgit pullupdates, which previously announced nothing. A rollback is labelled as such rather than shown as an upgrade. The body is the annotated tag's message, so release notes are whatever you write when tagging. Toggle withVERSION_ANNOUNCE_ENABLED. See the Safety Systems wiki page for thresholds, tuning, and the required bot permissions (Manage Server, Moderate Members, Kick Members, Manage Roles).
| Command | Description | Access |
|---|---|---|
/purge_last_messages |
Purge a specified number of messages from a channel | Mod |
/purge_string |
Purge all messages containing a specific string from a channel | Mod |
/purge_webhooks |
Purge all messages sent by webhooks or apps from a channel | Mod |
/kick |
Kick one or more members from the server | Mod |
/kick_role |
Kick all members with a specified role from the server | Mod |
/timeout |
Timeout a member for a specified duration | Mod |
/botsay |
Make the bot send a message to a specified channel | Mod |
/message_dump |
Dump a user's messages from a channel into a zipped archive DM'd to you (25 MB cap) | Mod |
/media_dump |
Zip a channel's images, video and audio for a date range and DM you a temporary download link (the built-in server shuts down after 15 min; TCP port 48731 must be reachable) | Mod |
| Command | Description | Access |
|---|---|---|
/raid status |
Show raid-protection settings, current lockdown state, and joins in the current window | Mod |
/raid protection |
Enable/disable automatic join-burst detection | Mod |
/raid lockdown |
Manually pause (or lift a pause on) invites and DMs, independent of auto-detection | Mod |
/raid recent_joins |
List members who joined recently, flagging new accounts and grouping them by identical avatar | Mod |
/raid kick_recent |
Kick recently-joined new accounts — dry run by default, so you preview before anything irreversible | Mod |
/nuke_protection |
Enable/disable audit-log monitoring for a compromised moderator account | Mod |
/spam_protection |
Enable/disable cross-channel link spam and mass-mention filtering | Mod |
These need the bot to hold Manage Server (pausing invites/DMs), Moderate Members (timeouts), and Kick Members. Without them the detection still fires and alerts, but the automatic response is reported as blocked rather than applied.
| Command | Description | Access |
|---|---|---|
/clone_category_permissions |
Clone permission overwrites from one category to another | Mod |
/clone_channel_permissions |
Clone permission overwrites from one channel to another | Mod |
/clone_role_permissions |
Clone permissions from one role to another (moderation permissions — Administrator, ban/kick, manage roles/guild/channels/messages, timeout — are excluded and must be granted manually) | Mod |
/clear_category_permissions |
Clear all permission overwrites from a category | Mod |
/clear_channel_permissions |
Clear all permission overwrites from a channel | Mod |
/clear_role_permissions |
Reset a role's permissions to default | Mod |
/sync_channel_perms |
Sync all channels in a category to match the category's permissions | Mod |
| Command | Description | Access |
|---|---|---|
/assign_role |
Mass-assign a role to multiple users at once | Mod |
/remove_role |
Mass-remove a role from multiple users at once | Mod |
/list_users_without_roles |
List all users with no server roles assigned | Mod |
| Command | Description | Access |
|---|---|---|
/set_reminder |
Set a recurring reminder message to a channel at a specified interval | Mod |
/list_reminders |
List all active reminders | All |
/delete_reminder |
Delete a reminder by title | Mod |
/delete_all_reminders |
Delete all active reminders | Mod |
| Command | Description | Access |
|---|---|---|
/add_event_feed |
Subscribe to an iCal or RSS feed (including Meetup.com); auto-detects feed type, runs an immediate check, creates Discord Scheduled Events with duplicate detection, and enables automatic event announcements to the chosen channel | Mod |
/list_event_feeds |
List all registered event feeds | All |
/remove_event_feed |
Remove a feed by name (announcements are disabled when the last feed is removed) | Mod |
/check_event_feeds |
Manually trigger a check of all feeds for new events | Mod |
Once a feed is added, everything else is automatic: feeds are re-checked every Monday at 9am, a "This Week" preview of the server's Discord Scheduled Events posts Monday at 10am, and day-of reminders post Tuesday through Sunday at 10am (Monday is skipped because the weekly preview already covers that day's events). Timezone is set by BOT_TIMEZONE in config.py, default US Central.
| Command | Description | Access |
|---|---|---|
/autoreply add |
Add an autoreply rule with a trigger string, reply text, and optional case sensitivity | Mod |
/autoreply list |
List all autoreply rules for this server | All |
/autoreply remove |
Remove an autoreply rule by ID | Mod |
/autoreply toggle |
Enable or disable an autoreply rule by ID | Mod |
| Command | Description | Access |
|---|---|---|
/server_backup |
Create a full structural backup of the server (roles, categories, channels, permission overwrites, emoji) and DM it to you as a JSON file | Admin |
/server_restore |
Restore server structure from a backup file. Shows a diff-style preview and requires an explicit confirm click before anything changes; automatically creates a safety snapshot of the current state first. Matches existing roles/categories/channels by name, so re-running is idempotent rather than duplicating everything. Never touches Administrator/managed/above-hierarchy roles or their overwrites, and never restores message history, member-specific overwrites, or audit logs | Admin |
/auto_backup |
Enable/disable automatic backups on an interval (default 24h). A new backup is only created — and posted to the moderators channel — when the server's structure actually changed since the last one | Admin |
| Command | Description | Access |
|---|---|---|
/voice_chaperone |
Enable/disable automatic voice channel safety monitoring (when only 1 adult + 1 child are in a channel, everyone present is server-muted and mods are alerted; the mute lifts automatically once the channel is no longer 1 adult + 1 child) | Mod |
/nuke_protection |
Enable/disable anti-nuke audit-log monitoring | Mod |
/spam_protection |
Enable/disable message spam protection | Mod |
/log_tail |
DM the last N lines of the bot log to yourself | Mod |
/dashboard |
Display all available commands grouped by category | All |
Mod above means the invoker needs the Manage Messages permission — not a specific role name, so there's nothing to configure to make command access work on a new server. Admin means the stricter Administrator permission, reserved for the backup/restore commands since they can rewrite the server's entire structure.
Update checking is configured in config.py (not via slash command): UPDATE_CHECKING_ENABLED turns on daily checks for new commits with moderator notifications, and AUTO_UPDATE_ENABLED additionally makes the bot pull CI-passing updates, sync its dependencies with uv and restart itself (see Auto-update requirements). Notifications display a git tag (e.g. v1.0.0) when the relevant commit is tagged, falling back to a short commit SHA otherwise — tags are cosmetic labels only, update detection itself is still commit-based so untagged commits are never missed.
| Command | Description | Access |
|---|---|---|
/bot_mood |
Check the bot's current mood | All |
/pet_bot |
Pet the bot | All |
/bot_pick_fav |
See who the bot prefers between two users today | All |
-
Clone and Install (needs uv):
git clone https://github.com/burbsec/johnnybot.git cd johnnybot uv sync --frozen --no-dev -
Configure: Copy
config_example.pytoconfig.pyand edit it with your server settings (config.pyis gitignored) -
Set Token: Add your Discord bot token as environment variable:
export DISCORD_BOT_TOKEN="your_bot_token_here"
-
Run:
uv run --frozen --no-dev bot.pyAlways start the bot this way, including from a service unit. A plain
uv runalso installs the test dependencies, and without--frozenit may rewriteuv.lockon the host.
Need help? Check the Setup Guide for detailed instructions.
For a long-running install, run the bot from systemd as a dedicated account, and install uv system-wide rather than in a home directory. That puts it on the service's default PATH, which auto-update needs, and out of reach of ProtectHome=:
curl -LsSf https://astral.sh/uv/install.sh | sudo env UV_INSTALL_DIR=/usr/local/bin UV_NO_MODIFY_PATH=1 shThe parts of the unit that matter for uv:
[Service]
User=johnnybot
WorkingDirectory=/opt/JohnnyBot
ExecStart=/usr/local/bin/uv run --frozen --no-dev bot.py
# uv's cache normally lives in ~/.cache, which ProtectHome= hides and
# ProtectSystem=strict makes read-only; systemd creates this one writable
CacheDirectory=johnnybot
Environment=UV_CACHE_DIR=/var/cache/johnnybot/uv
Environment=UV_LINK_MODE=copy
# Use the system Python; never download one at service start
Environment=UV_PYTHON_DOWNLOADS=never
Environment=UV_PYTHON_PREFERENCE=only-system
# Keep what auto-update pulls group-writable, and stop git warning about
# the ~/.config that ProtectHome= hides
UMask=0007
Environment=XDG_CONFIG_HOME=/nonexistentThe Setup Guide has a complete, sandboxed unit.
AUTO_UPDATE_ENABLED makes the bot run git pull --ff-only and uv sync as the service account, so that account must be able to update its own checkout:
- An HTTPS remote. The repository is public, so
git remote set-url origin https://github.com/BurbSec/JohnnyBot.gitneeds no credentials. An SSH remote needs a key the service account can read, which a sandboxed unit usually hides. - Write access to the checkout's directories and
.git. Git replaces files rather than editing them, so the files themselves can stay read-only to the bot — includingconfig.py. If you also pull by hand as another account, share a group: make the directories group-writable and setgid, make.gitgroup-writable, setgit config core.sharedRepository group, add yourself to the group, and give the unitUMask=0007. The Setup Guide has the exact commands. - A clean working tree.
git pull --ff-onlyrefuses to run over local edits to tracked files.
If any of these fail, the update stops before restarting and the moderators channel gets an "Auto-update failed" alert, so a misconfigured host fails loudly rather than breaking.
- Python 3.11+ — tested on 3.11, 3.12, 3.13 and 3.14 in CI. The dependencies themselves require 3.10+, but 3.10 reaches end-of-life in October 2026, so 3.11 is the supported floor.
- uv — dependencies are declared in
pyproject.tomland pinned inuv.lock. uv can also install a suitable Python for you. - Development:
uv syncinstalls the test dependencies too; run the suite withuv run pytest.
Contributions are welcome! If you encounter any bugs or have suggestions, feel free to open an issue or submit a pull request.
For detailed development information, see the Wiki.
This project is licensed under the GNU General Public License v3.0.
Attribution: Bot interaction functionality adapted from PetBot under MIT License.