Configuration reference
All configuration is environment variables, kept in .env. The
config editor (scripts/config.sh) is the way to set them: it lists
every variable below with its documentation and checks each change with the binaries’ own
loaders. Editing .env by hand works too, starting from the annotated .env.example.
- Every binary reads
.envfrom its working directory. Exporting it into your shell (set -a; source .env; set +a) is optional. - The containers get theirs through compose’s
env_file. - A
judge.tomlchooses providers and models. It names environment variables for its secrets and never holds one. - The config editor never shows a secret, and can replace one with a value you type.
In the tables, judgebot is the long-running process whatever its roles, and a role flag
(--discord) means a variable only that role reads.
| Variable | Default | Meaning |
|---|---|---|
JUDGE_ROLES |
compose: --discord --api --web --jobs |
What judgebot runs: --discord (the bot), --api (POST /api/judge), --web (the web app), --mcp (the MCP transport), --admin (the admin interface), --jobs (the scheduled refresh), at least one, separated by spaces and quoted. The compose service passes it as its command; judgebot itself reads it when its command line names no role. '--api --web --jobs' runs without Discord. |
Database and models
Section titled “Database and models”| Variable | Default | Read by | Meaning |
|---|---|---|---|
DATABASE_URL |
(required) | all | Postgres connection string. Compose overrides it to db:5432 inside the network. The example points at localhost:5432. |
DB_PORT |
5432 |
compose only | The loopback port compose publishes Postgres on. Change it together with the port in DATABASE_URL when 5432 is taken. |
ANTHROPIC_API_KEY |
judgebot, eval, agent | The zero-config model setup: Anthropic direct, claude-opus-5-5 for both stages. Unused when a judge.toml names other providers. |
|
ANTHROPIC_BASE_URL |
Anthropic’s | same | Zero-config only. A gateway speaking /v1/messages. |
VOYAGE_API_KEY |
judgebot, eval, agent | Zero-config embeddings (voyage-3.5, 1024). Blank turns the vector search off. |
|
VOYAGE_MODEL, VOYAGE_DIMENSIONS |
voyage-3.5, 1024 |
same | Zero-config embedding model and width. |
JUDGE_CONFIG |
all | Path to a judge.toml. Blank: ./judge.toml if present (for cargo run), else the zero-config setup. Compose mounts only the file this names, so under Docker a ./judge.toml is ignored until this names it. |
|
<provider>_KEY … |
all | Whatever api_key_env names in judge.toml, one per provider a stage uses. A table no stage names is parsed but its key is never read. |
|
AWS_*, GOOGLE_APPLICATION_CREDENTIALS |
judgebot | Credentials for the claude-platform-on-aws, bedrock and vertex endpoints, read through each platform’s own credential chain. Checked once at startup. |
|
JUDGE_MAX_USD |
5 |
judgebot, judgebot ingest, eval, agent |
Spend cap in USD, across every provider, embeddings included. Each call reserves its worst-case cost before it is sent. A question is refused once the money left is less than that, so values under about $0.36 refuse synthesis outright. JUDGE_BUDGET_PERIOD says what the cap covers. |
JUDGE_BUDGET_PERIOD |
process |
judgebot | What JUDGE_MAX_USD caps. process: each process, all its roles together, for its lifetime, in memory. A restart counts from zero. day or month: the current UTC day or month, shared by every process through the spend_days table and kept across restarts. The processes sync every 10 seconds, so together they can overshoot by what they spend in that time. judgebot ingest follows it too, so a re-embed counts toward the period. judge-cli and judge-eval always cap per process. |
JUDGE_LOCALE |
en |
every interface | The language replies are in when the asker’s own is not one the bot speaks: Discord tries the user’s language, the web app and the admin pages the browser’s (a server’s own language setting is not used: Discord sets it to US English unless an admin changes it, so it would hide this one), judge-cli, judgebot and judge-config the terminal’s (LC_ALL, LC_MESSAGES, LANG), and judge-config‘s page the browser’s (judge-config falls back to the value in the .env it edits). The alert webhook’s messages are always in this language; the backup service reads it from .env through Compose. Only English (en) ships today. The rules material, the answers, JSON output and diagnostics (logs, the command lines’ errors, health checks) stay English; the API’s and the bot’s own error replies are translated. A value that names no supported language stops every binary that loads the configuration. |
JUDGE_CALL_RETENTION_DAYS |
unset (keep every call) | the refresh | Delete answered calls older than this many days, with their ratings: 1 to 3650, or unset / 0 to keep them all. 90 is a sensible choice. Each refresh’s prune step deletes them, as does judgebot ingest prune; with JUDGE_REFRESH_HOURS=0, cron one of those. A deleted call is no longer an example for later answers or a thread’s history. Each run’s usage record (judge_runs) is kept. A value out of range stops every binary that loads the configuration. |
FEEDBACK_IP_DAYS |
90 |
judgebot, the refresh | How many days a rating given on the web keeps the address and user agent it came from, for dealing with abuse: 1 to 3650. After that both are cleared, and the rating and its reason are kept. Every rating written clears the older ones, and so does each refresh’s sweep step. There is no “keep forever”. Discord ratings store neither. A value out of range stops every binary that loads the configuration. |
JUDGE_REFRESH_HOURS |
24 |
--jobs |
Hours between data refreshes (Scryfall cards and rulings, a new Comprehensive Rules release, embeddings, emoji), which the --jobs role runs. 1 to 720, or 0 for off (keep a cron’d scripts/refresh-data.sh instead). Every process and a cron run take turns through a lock in the database, so a refresh runs once however many processes there are. A failed refresh is retried after an hour, then less often while it keeps failing. A container asked to stop (a deploy) stops its refresh, recorded as neither a success nor a failure, and the new container runs it again at its first check. It waits for the first load (init) on an empty database. A scheduled run never embeds more than 800 rows; above that it skips the step and alerts. A value out of range stops every binary that loads the configuration (judge-cli, judge-mcp, judge-eval and judgebot ingest too), as JUDGE_BUDGET_PERIOD does. Set 0 in a development .env, or cargo run with --jobs refreshes your local database for real. |
JUDGE_SPEND_WARN_AT |
(none) | judgebot, judgebot ingest |
Warn before the cap is reached, at these percentages of JUDGE_MAX_USD: comma-separated whole numbers from 1 to 99, such as 50,80. Each threshold is logged and posted to JUDGE_ALERT_WEBHOOK once per period. A check that finds several passed reports the highest. In a day or month period one process sends each warning however many share the cap (claimed in the spend_warnings table). A cap raised mid-period, or an ingest run under a raised one, warns at its own percentages. Spend counts calls in flight at their worst case (about $0.36 each), so with several questions in flight a threshold can fire early. Questions are refused about $0.36 short of the cap, so a threshold that close may never be reached. Blank: no warnings. A malformed value stops every binary that loads the configuration, as JUDGE_BUDGET_PERIOD does. |
JUDGE_ALERT_WEBHOOK |
judgebot, scripts, backup | An https webhook (Discord, Slack or compatible). It is called the first time the cap refuses a question in a period (once per process), and when spending reaches a JUDGE_SPEND_WARN_AT threshold. A refused embedding does not call it: the question is still answered, without vector search, and a refresh whose embed step stops at the cap reports as a failed refresh. It is also called when a scheduled refresh fails (once per streak of failures, saying when it timed out), succeeds again, first skips embedding at the 800-row ceiling or crashes, when scripts/refresh-data.sh or scripts/backup-db.sh fails, when DISCORD_INTERACTIONS disagrees with the application’s Interactions Endpoint URL at startup, and when an interaction over HTTP is refused for its timestamp (once per streak: a host clock five minutes wrong refuses them all). The backup service reads its own copy from .env.deploy and posts the first failure of a streak, a failure at another step, and the recovery. The URL is a credential. Without it, a tripped cap, a spend warning or a failed refresh is only a line in the log. |
|
JUDGE_USER_LIMIT, JUDGE_USER_WINDOW_SECS |
6, 600 |
--discord |
/judge questions per Discord member per window. 0 turns the limit off. A “busy” reply does not count. Held in memory. /card and /rule are not limited. |
JUDGE_CONCURRENCY |
2 |
judgebot | Judge runs in flight at once, per interface. Further ones get a “busy” reply. The MCP transport shares the API’s slots. Discord has slots of its own, so one process with --discord and --api runs up to twice this many. |
JUDGE_AUTO_MIGRATE |
true |
judgebot | Apply pending schema migrations at startup. Set false to manage the schema yourself with judgebot ingest migrate or sqlx-cli. |
JUDGE_SOURCE_URL |
the upstream repository | all | Where your instance’s source code is. Every remote interface shows it with the commit the binary was built from and the AGPL-3.0-or-later notice: the web footer and GET /api/about, Discord /help and /license, the MCP instructions and about tool, judge-cli about. Set it to your fork if you run a modified version. It must be an http(s) URL, or startup fails. |
JUDGE_OPERATOR_DISCORD |
(required by --discord) |
all | The Discord username of whoever runs the instance, shown by /help and /license, and by the other interfaces when set. A username, not a display name or a name#1234 tag. A leading @ is dropped. Every binary refuses to start on a malformed value. |
JUDGE_OPERATOR_EMAIL |
(required by --api, --web, --mcp) |
all | A support address, shown by GET /api/about, the web app’s footer, and the MCP instructions and about tool. Discord shows it too when set. The web app, the API and the MCP transport (--web, --api, --mcp) do not start without it. Only letters, digits and ._+- before the @. judge-cli and judge-mcp on stdio need neither contact, and show them when set. |
Discord
Section titled “Discord”| Variable | Default | Meaning |
|---|---|---|
DISCORD_TOKEN |
(required by --discord) |
The bot token. Also read by judgebot ingest emoji, which uploads symbols to the same application. |
GUILD_ID |
Register commands in this one server only (instant). Other servers the bot is in, and DMs with it, get none. Unset: globally, in every server and in DMs for all but /judge and /judge-private (up to an hour). Switching leaves the other set registered until you clear it. |
|
JUDGE_ROLE |
Judge |
Members holding a role with this exact name rate as judges: their rating overrides the crowd’s. |
DISCORD_INTERACTIONS |
gateway |
How Discord delivers commands and button clicks. gateway: over the connection one judgebot holds. http: POSTed to /discord/interactions on API_ADDR, which must be reachable at a public HTTPS address saved as the application’s Interactions Endpoint URL; no gateway connection is opened, and interactions keep being answered while a deploy switches containers. Interactions over HTTP. |
HTTP API and web app
Section titled “HTTP API and web app”| Variable | Default | Meaning |
|---|---|---|
API_ADDR |
0.0.0.0:8787 |
Listen address of the network roles (--api, --web, --mcp) and of Discord’s interactions endpoint with DISCORD_INTERACTIONS=http, which also serves GET /api/health and GET /api/about whichever of them is on (with --discord alone over HTTP, /api/health only). Keep 0.0.0.0 in Docker so the proxy, edge and cloudflared services can reach it. The container publishes no port; the proxy service publishes 127.0.0.1:8787, loopback only, and edge (the public profile) ports 80 and 443. |
WEB_DIST |
web/dist |
The built web app, read only under --web. The image sets /srv/web. A --web launch with no index.html there is refused at startup. |
API_RATE_LIMIT, API_RATE_WINDOW_SECS |
4, 300 |
Questions per IP per window, checked before the concurrency semaphore and the spend cap. |
API_CLIENT_IP |
peer |
What the per-address limit counts. peer: the socket address, which behind any proxy is the proxy’s. proxy: X-Judgebot-Client-IP, which the public profile’s edge sets to the visitor’s address and your own reverse proxy on the host can set through 127.0.0.1:8787; the tunnel’s and the admin site remove it, and nothing on the compose network may be pointed at the proxy’s :8788. cloudflare: CF-Connecting-IP, with the tunnel profile. Never X-Forwarded-For. The limit counts an IPv4 address by itself and an IPv6 address by its /64. Any other value stops the network roles. See Security and Client address. |
JUDGE_FEED |
on | false removes the public feed and dashboard: the /feed, /calls/<id>, /users/<name> and /dashboard pages and GET /api/feed / GET /api/calls/{id} / GET /api/stats. On, every --web listener serves it, listing every answered call not asked private, earlier ones included, with the Discord asker’s username. /help says so unless it is off, whatever roles run (a Discord process cannot tell whether another serves the web app), so a deployment with no --web sets it false. A value that is not a boolean stops every binary that loads the configuration. |
JUDGE_FEED_DAYS |
unset (no limit) | Hide calls older than this many days from the feed, its pages and the dashboard’s counts: 1 to 3650, or unset / 0 for none. 90 is a sensible choice. Nothing is deleted, and older calls still serve as examples; JUDGE_CALL_RETENTION_DAYS deletes. A value out of range stops every binary that loads the configuration. |
JUDGE_PUBLIC_FEEDBACK |
false |
Show, under each answer on the feed and call pages, the reasons raters gave with a Partially correct or Incorrect rating: the kind of problem and their words, never who gave them (no name, user id or address). Raters are told so in the form and the confirmation, on Discord and the web. Unset or false: the reasons are the operator’s alone (the admin pages, judge-cli queue). The counts are public either way. Turning it on publishes free text from anonymous web raters: 30 ratings per address per ten minutes, and a fresh session id per request makes each a new rater. Only user, role and channel mentions are reduced (to @… and #…) and @everyone / @here broken; nothing else is filtered. Dismissing a feedback-queue item takes its reason off the public pages. A value that is not a boolean stops every binary that loads the configuration. |
JUDGE_PUBLIC_COST |
false |
Show, on the public dashboard, what the public questions cost: their runs’ model charges in all and per question (GET /api/stats’s cost). Unset or false: spend is the operator’s alone (the admin dashboard, judge-cli stats). Private questions are never counted either way. A value that is not a boolean stops every binary that loads the configuration. |
JUDGE_PUBLIC_MODELS |
false |
Show, on the public dashboard, which models read and answered the public questions, and let it narrow to one model (GET /api/stats’s models and model). Unset or false: a model filter there is refused. A value that is not a boolean stops every binary that loads the configuration. |
MCP_TOKEN |
The bearer token for /mcp (24+ printable ASCII bytes). The endpoint also needs --mcp. --mcp without a token fails at startup. A token without --mcp serves nothing and logs a warning. |
|
MCP_ALLOWED_HOSTS |
loopback only | Comma-separated Host values the MCP transport accepts: the public hostname (JUDGE_DOMAIN, or the tunnel’s), plus localhost if you curl on the host. |
MCP_JUDGE_LIMIT, MCP_JUDGE_WINDOW_SECS |
20, 3600 |
judge runs per window through /mcp. This limits the damage a leaked token can do. |
MCP_ADMIN_TOKEN |
A second /mcp token that also reaches the admin tools (admin_calls, admin_call, admin_failures, admin_usage, and the feedback queue’s queue_list, queue_show, queue_resolve, queue_dismiss), which read every stored call with its asker and close queue items. Unset: /mcp has no admin tools, and MCP_TOKEN never does. 24+ printable ASCII bytes, different from MCP_TOKEN and ADMIN_TOKEN, or no process that reads it starts. For agents that cannot run a command; one that can runs stdio judge-mcp over SSH instead (Agents). |
Admin interface
Section titled “Admin interface”The operator’s pages: every stored call, private ones included, the feedback queue, the
failed calls, and the dashboard with usage and spend
(Web app). Read only under --admin.
| Variable | Default | Meaning |
|---|---|---|
ADMIN_ADDR |
127.0.0.1:8789 |
Where --admin listens, outside compose. The compose service sets 0.0.0.0:8789 inside the container whatever .env says, and the proxy service publishes it on the host’s loopback only. Neither the public site nor the tunnel points at it; from another machine, forward the port over SSH, or on a trusted network publish it on the LAN address with a compose override (Deployment). It may not share API_ADDR’s port. |
ADMIN_PORT |
8789 |
The host port compose publishes the admin interface on (127.0.0.1 only). The proxy publishes it whether --admin runs or not, so set a free port when something else has 8789, or the proxy cannot start. judge-cli admin-url in the container prints it. |
ADMIN_TOKEN |
(required by --admin) |
The admin pages’ bearer token: 24+ printable ASCII bytes (openssl rand -base64 32), different from MCP_TOKEN and MCP_ADMIN_TOKEN. judge-cli admin-url prints the page’s address with it in the #token= fragment. |
Ingest and deployment
Section titled “Ingest and deployment”| Variable | Default | Meaning |
|---|---|---|
INGEST_CACHE_DIR |
.cache (image: /var/cache/judgebot) |
Where Scryfall bulk files and the CR text are cached. |
RUST_LOG |
info in compose |
Tracing filter. The containers use info,sqlx=warn. |
JUDGE_IMAGE, JUDGE_IMAGE_TAG |
upstream package, latest |
Which image judgebot, refresh and backup run (amd64 and arm64). A fork sets its own package. A release version (1, 1.2, 1.2.0) or a sha-<short> tag pins or rolls back. |
COMPOSE_PROFILES |
The optional services scripts/deploy.sh also starts, comma-separated. public: edge, the HTTPS site at JUDGE_DOMAIN on ports 80 and 443 (with API_CLIENT_IP=proxy). tunnel: cloudflared, a Cloudflare Tunnel (with API_CLIENT_IP=cloudflare). backup: the weekly database backup. Empty: 127.0.0.1:8787 on the host only. Exposure. |
|
JUDGE_DOMAIN |
The public host name edge serves and gets a Let’s Encrypt certificate for, e.g. judge.example.com: two or more dot-separated labels of letters, digits and inner hyphens, the last not all digits (not localhost or an IP address), with no scheme, port, path or trailing dot. A DNS record must point it at the host, with ports 80 and 443 forwarded. Read only by edge, which refuses to start under public without it; the config editor checks it. |
|
TUNNEL_TOKEN, BACKUP_S3_* |
In .env.deploy, read only by cloudflared, the backup service and the backup script, never by the internet-facing containers. |
Backup
Section titled “Backup”These live in .env.deploy, beside TUNNEL_TOKEN. The backup service and scripts/backup-db.sh read the same ones, with the same defaults, and blank means the default. The deployment runbook has the setup and the restore drill.
| Variable | Default | Meaning |
|---|---|---|
BACKUP_S3_ENDPOINT, BACKUP_S3_BUCKET |
The S3 API’s URL (https://, or http:// on a private network, with a warning) and the bucket. Required. Cloudflare R2: https://<account-id>.r2.cloudflarestorage.com; AWS: https://s3.<region>.amazonaws.com; Backblaze B2: https://s3.<region>.backblazeb2.com. |
|
BACKUP_S3_ACCESS_KEY_ID, BACKUP_S3_SECRET_ACCESS_KEY |
A key scoped to reading and writing that bucket. Required. | |
BACKUP_S3_REGION |
auto |
The region requests are signed for. auto suits Cloudflare R2; AWS and Backblaze B2 need the bucket’s own (eu-west-1, us-west-004). |
BACKUP_S3_ADDRESSING |
path |
path (<endpoint>/<bucket>/…) or virtual-hosted (<bucket>.<endpoint host>/…, what AWS recommends; needs a host name and, over https, a bucket without dots). |
R2_ENDPOINT, R2_BUCKET, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY |
Retired in 2.0.0: a set one stops the backup, naming the BACKUP_S3_* line that replaces it. |
|
BACKUP_PREFIX |
db |
The key prefix the backups live under. |
BACKUP_KEEP_DAYS |
60 |
Backups older than this are pruned after a successful upload. The service never prunes the two newest. |
BACKUP_MIN_BYTES |
20000000 |
A smaller dump is refused, never uploaded. |
BACKUP_KEEP_LOCAL |
A directory to copy each dump into. For the service, a path inside its container (mount one there). | |
BACKUP_EVERY_DAYS |
7 |
The service takes a backup whenever the newest in the bucket is this many days old (1 to 365). The script’s schedule is cron. |
DATABASE_URL |
set by compose | The service reaches db:5432 over the compose network; compose sets it, as for judgebot. |
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.