Create the Discord app
Every judgebot is its own Discord application, owned by whoever runs it. This page covers
the steps from creating the application to /judge answering in your server. Discord’s
walkthrough,
Building your first Discord Bot,
covers the same portal screens in general terms. The steps below say what to choose for
this bot.
The bot uses slash commands only. It needs no privileged gateway intents and no channel permissions. It receives only its own commands and button presses, and replies through the interaction, so it is never granted the ability to read messages.
Before you start
Section titled “Before you start”- The first run done up to the point where the web app answers: the database is up and the data is loaded. Nothing on this page spends money.
- The Manage Server permission in the Discord server you are adding the bot to. Adding an app to a server requires it (Installation Context).
- A Discord account with email verified, which the developer portal requires.
1. Create the application
Section titled “1. Create the application”Open the Developer Portal and choose New
Application. Members see the name beside /judge in the command picker and on the
bot’s profile, so name it for your server (“Rules Judge”, “Club Judge”).
The App Icon is the bot’s avatar. Any image works. The project’s icon is
a 512×512 PNG (assets/icon.png in the repository) if you want it.
Nothing else on the General Information page matters to the bot. The Application ID
shown there ends up in the install link in step 3.
2. Bot user and token
Section titled “2. Bot user and token”Under Bot:
-
Choose Reset Token and copy the result. Discord shows a token once. If you lose it, reset again. The token is a credential for the application, and every binary that reads it keeps it redacted. Then, in the config editor (
scripts/config.sh), Settings tab:DISCORD_TOKEN: Set…, paste the tokenJUDGE_OPERATOR_DISCORD: your own Discord username. The bot does not start without it, and/helpand/licenseshow it.
By hand, the same two lines go in
.env. -
Leave all three Privileged Gateway Intents (Presence, Server Members, Message Content) off. The bot connects with no intents (Gateway Intents explains what they are). Turning one on changes nothing in the bot. Past 100 servers it would trigger Discord’s verification process for nothing.
-
Public Bot can be off. It controls whether other people can use your install link, which a bot for your own servers does not need.
3. The install link
Section titled “3. The install link”Under OAuth2 → URL Generator:
- Tick the scopes
botandapplications.commands.botputs a bot user in the server.applications.commandslets it register slash commands there (OAuth2 scopes). - Under Bot Permissions, tick nothing. Replies, buttons and the “did you mean?” row
all go through the interaction, which needs no channel permission. The URL ends in
permissions=0. - Open the generated URL in your browser, pick the server, and Authorize. This is
Discord’s bot authorization flow.
The URL has the shape
https://discord.com/oauth2/authorize?client_id=<application id>&scope=bot%20applications.commands&permissions=0. You can reuse it for every server you administer.
The portal’s newer Installation page (installation contexts and a Discord-provided install link) does the same job. If you use it instead, choose:
- Guild Install as the only context. The bot has no user-install behaviour.
- The same two scopes.
- No permissions.
4. Command registration
Section titled “4. Command registration”The bot registers its own slash commands when it starts. It registers them either:
- in one server, where they appear instantly. Other servers the bot is in, and DMs with the bot, get no commands. Or:
- globally, in every server the bot is in, where they take up to an hour to appear.
/card,/rule,/help,/licenseand/forgetthen work in a DM with the bot too./judgeand/judge-privateare server-only either way.
See Registering a command. For a bot in one or two servers, register in the server:
- In Discord, User Settings → Advanced → Developer Mode on.
- Right-click the server icon → Copy Server ID (Discord’s help article Where can I find my User/Server/Message ID?).
- Put it in
.envasGUILD_ID.
Leave GUILD_ID unset to register globally.
Avoid switching back and forth. The bot registers the set it is configured for and does
not remove the other. Members would see two identical /judge entries from the same bot
until the stale set is cleared. The portal does not clear it. Overwriting the set with an
empty list does
(Bulk Overwrite Guild Application Commands).
You need the bot token, the Application ID from step 1 and, to clear a server’s set,
the server id GUILD_ID held before you blanked it:
DISCORD_TOKEN=... # as in .envAPPLICATION_ID=... # General Information → Application IDGUILD_ID=... # the server the stale set was registered in
# clear the server's set (after moving to global registration)curl -X PUT -H "Authorization: Bot $DISCORD_TOKEN" -H "Content-Type: application/json" -d '[]' \ "https://discord.com/api/v10/applications/$APPLICATION_ID/guilds/$GUILD_ID/commands"# clear the global set (after moving to GUILD_ID)curl -X PUT -H "Authorization: Bot $DISCORD_TOKEN" -H "Content-Type: application/json" -d '[]' \ "https://discord.com/api/v10/applications/$APPLICATION_ID/commands"Clear only the set the bot is no longer configured for. The bot registers its own set again at every start.
5. Start it
Section titled “5. Start it”scripts/deploy.sh # or: cargo run --release -p judgebot -- --discord --jobsThe compose service runs --discord unless JUDGE_ROLES in .env leaves it out. If you
set JUDGE_ROLES='--api --web --jobs' to try the web app first, clear it or add --discord.
The bot connects about 15 seconds after it starts. It first takes the gateway lease, a
lock in the database that keeps a second judgebot from answering beside it, and waits
out a grace period. A log line standing by: another instance holds the Discord gateway
means another judgebot --discord on the same database is connected. That is usually a
container left from a previous deploy; the line names it
(Deployment).
The log line registered /judge, /judge-private, /card, /rule, /help, /license and /forget in one guild (or … globally)
confirms registration. A warning registering the slash commands failed instead means
the bot is connected with whatever commands were registered before (none, on a first
start); the next start, such as the next scripts/deploy.sh, tries again. Running
/help in the server confirms it end to end. Another bot’s /judge in the same server
does not conflict with yours: Discord’s command picker shows each bot’s icon beside its
commands.
6. Card symbol emoji
Section titled “6. Card symbol emoji”init uploads the symbols if DISCORD_TOKEN was already set when it ran. Otherwise run this
once:
docker compose run --rm refresh emoji # or: cargo run --release -p judgebot -- ingest emojiIt uploads Scryfall’s mana and card symbols as application emoji. These belong to the
application, not to any server, and need no emoji permission
(Application-owned emoji).
Without them, answers show the literal {W}. The command is safe to rerun, reads
DISCORD_TOKEN and needs no database.
7. Interactions over HTTP
Section titled “7. Interactions over HTTP”This step is optional. By default the bot receives commands and button clicks over a
gateway connection, and Discord is quiet for a few seconds while a deploy hands it to
the new container. Receiving them over HTTP instead keeps them answered during a deploy, but
needs a public HTTPS address for the bot: https://<JUDGE_DOMAIN> with the bundled
public site, or your own proxy’s or the tunnel’s hostname
(Exposure; Deployment
has the steps).
- Set
DISCORD_INTERACTIONS=httpin.envand deploy (scripts/deploy.sh). Commands go unanswered until step 2. - In the Developer Portal, open General Information and set Interactions Endpoint
URL to
https://<your public host>/discord/interactions: with the bundled public site,https://<JUDGE_DOMAIN>/discord/interactions. Discord tests the address before it saves it.
The bot then opens no gateway connection, and shows in the member list without a status dot.
Discord’s requests come from its servers, not a browser, so they cannot pass a
challenge. Behind Cloudflare, keep /discord/interactions out of any Managed Challenge
rule or Access policy, and turn Bot Fight Mode off (it covers the whole zone and cannot
skip a path), or the test and every interaction fail.
One channel
Section titled “One channel”The bot answers wherever its commands can be used. That is a Discord setting, not the
bot’s. In Server Settings → Integrations, open your application and restrict /judge
(or every command) to the channels, roles or members you choose
(application command permissions).
A rules-questions channel keeps follow-ups together, because history is per channel.
The bot has two limits of its own. Neither applies to /card and /rule.
JUDGE_USER_LIMITquestions per member perJUDGE_USER_WINDOW_SECS. The default is six per ten minutes, and0turns it off.JUDGE_CONCURRENCYruns in flight at once.
A Partially correct or Incorrect rating asks the rater why, and the reason lands in
your feedback queue: the admin page’s Feedback tab, judge-cli queue, or the admin MCP
tools (Agents). An Incorrect rating’s confirmation
names you. When the repository JUDGE_SOURCE_URL names is on GitHub, it also links that
repository’s Wrong or unhelpful ruling issue form. A fork has Issues off until you
enable them under the repository’s Settings → General → Features.
The judge role
Section titled “The judge role”Members holding a role named JUDGE_ROLE (default Judge) rate as judges. Their rating
overrides the crowd’s smoothed average for that answer. Create the role under Server Settings →
Roles (Discord’s Role Management 101
covers it) and give it to the people whose rulings you trust. The name must match exactly.
The role needs no permissions of its own.
Several servers
Section titled “Several servers”One application can be in every server you administer. Reuse the install link from step 3
and register commands globally. The servers then share one process, with one spend cap
(JUDGE_MAX_USD), one concurrency limit and one judge role name
(D16 has the reasoning).
A community that wants its own budget runs its own instance: a second copy of the same
compose file, with a second application’s token.
Discord’s rules
Section titled “Discord’s rules”Your application is bound by the Discord Developer Policy and Terms of Service like any other. Two points matter for a judgebot:
- It must not collect more data than it needs. This one stores each question with its
channel and the asker’s id and username, ratings per user with the reasons they give,
and failed calls with the asker’s id.
/forgetdeletes a user’s ratings and reasons and removes them from their questions and failed calls. - Magic content is used under Wizards of the Coast’s
Fan Content Policy, which your instance’s
/helpalready states.
MTG Judgebot is unofficial Fan Content permitted under the Fan Content Policy. Not approved or endorsed by Wizards of the Coast. Portions of the materials used are property of Wizards of the Coast. ©Wizards of the Coast LLC.
The Comprehensive Rules come from Wizards of the Coast. Card data, rulings and card symbols come from Scryfall, which is not affiliated with this project. Rule links go to the Yawgatog mirror. License and attribution.