Evidence Bot Installation & Setup
Install the ZCraft Studios Discord Evidence Bot. Configure Discord permissions, forum tags, environment variables, hosting and first-run checks.
Evidence Bot Installation & Setup
Requirements
- Node.js 22.13 or newer, and npm. SQLite migration uses Node's built-in SQLite reader, so no extra runtime dependency is needed.
- A Discord application with a bot token
- A Discord server with a Forum channel for case posts
- Permission to install and configure the bot in that server
- A host with a persistent, writable directory and internet access to Discord
- Optional: a MySQL/MariaDB database used by LiteBans or AdvancedBan, with a SELECT-only user for the bot
The bot is configured for one server and one evidence forum per running installation, with one bot instance per installation. The base package has no website, dashboard, or HTTP listener; those come from the optional addons.
Discord setup
Create the application
- Open the Discord Developer Portal and create or select an application.
- In Bot settings, get the bot token. Save it privately for
TOKEN. - Enable Message Content Intent.
Install the bot
Use an install link with the bot and applications.commands scopes, and grant the permissions below. Give members permission to use application commands.
Create channels and staff roles
Create a Forum channel for evidence cases. Optional channels: appeal intake, activity log, and review reminders. Enable Discord Developer Mode to copy IDs: the server ID is GUILD_ID and the forum's channel ID is FORUM_CHANNEL_ID.
Create forum tags
Create the seven status tags listed below in the evidence forum.
Appeal posts can contain email addresses, punishment details, and submitted evidence. Keep the appeal forum private and set visibility for your intended audience only.
Required bot permissions
| Permission | Purpose |
|---|---|
| View Channel | Access the forum and configured text channels. |
| Send Messages | Create forum posts and send logs or reminders. |
| Send Messages in Threads | Post follow-ups and appeal decisions. |
| Embed Links | Send structured case embeds. |
| Read Message History | Read starter messages and recover forum records. |
| Create Public Threads | Allow thread creation where applicable. |
| Manage Threads | Rename, tag, archive, and unarchive posts. |
| Attach Files | Deliver exports, timelines, and queue downloads. |
Check channel overrides as well as the bot's server role. Thread visibility follows the forum's permissions.
Forum tags
Create tags named Banned, Muted, Kicked, Pending, Suspicious, Appeal, and Resolved. These names are sufficient.
| Internal status | Display label | Tag name | Optional env override |
|---|---|---|---|
banned | Banned | Banned | TAG_ID_BANNED |
muted | Muted | Muted | TAG_ID_MUTED |
kicked | Kicked | Kicked | TAG_ID_KICKED |
pending | Pending Review | Pending | TAG_ID_PENDING |
suspicious | Suspicious | Suspicious | TAG_ID_SUSPICIOUS |
appeal | Appeal | Appeal | TAG_ID_APPEAL |
resolved | Resolved | Resolved | TAG_ID_RESOLVED |
The TAG_ID_* overrides still work if you use custom tag names. Status changes preserve unrelated tags up to Discord's five-tag limit. A forum that requires tags will reject new cases if the status tag is missing.
Install and run the bot
Run all commands from the extracted bot directory (where package.json is).
Install dependencies
node --version
npm ci
Use Node.js 22.13 or newer.
Create the environment file
cp .env.example .env
Copy-Item .env.example .env
Edit .env
At minimum, set the required values:
TOKEN=your_bot_token
GUILD_ID=your_server_id
FORUM_CHANNEL_ID=your_evidence_forum_id
STAFF_ROLE_IDS=your_staff_role_id,your_admin_role_id
.env.example lists every normal setting. Channel and role settings take IDs, not names or mentions. Boolean settings accept true or false.
Start the bot
npm start
Startup logs in, then registers the 17 core guild slash commands plus any installed addon commands automatically, before starting background services. CLIENT_ID is no longer needed: the application ID is detected from the logged-in bot.
Registration clears this application's global commands and its commands in every server it currently belongs to, then registers the current core and configured addon commands only in GUILD_ID — removing older commands and any global/guild duplicates. If you run independent bots for different servers, use a separate Discord application per installation. A registration failure stops startup; npm run deploy is still available for standalone registration and exits with a nonzero code on failure.
While starting, the console prints its current step (Discord connection, forum validation, command refresh, addons, background services), elapsed time, and a progress line every 15 seconds while a step is still running. A Discord command rate limit prints its estimated wait. Forum recovery and MySQL polling run in the background and don't hold up the bot becoming ready.
Configure environment variables
Restart the bot after changing any setting. Invalid required settings fail startup with a configuration error.
Required and recommended settings
| Variable | Required? | Description |
|---|---|---|
TOKEN | Yes | Discord bot token. Keep private. |
GUILD_ID | Yes | Discord server ID. Commands and intake are restricted to this server. |
FORUM_CHANNEL_ID | Yes | Evidence Forum channel ID in that server. |
STAFF_ROLE_IDS | Recommended | Comma-separated staff role IDs. Administrators always have access. When blank, only administrators can use staff commands. |
LiteBans and AdvancedBan connection settings are listed under Punishment imports.
If STAFF_ROLE_IDS is blank, staff commands are limited to administrators. Add your moderator role IDs so non-admin staff can use them.
Keep .env private and never publish a real bot token.
Keep the bot running
Press Ctrl+C to stop a foreground instance, and stop your process manager as well when migrating. Closing a foreground terminal ends the session unless your host manages the process. Use a host or service manager that supports long-running Node.js processes:
- Working directory: the folder containing
package.jsonand.env - Install command:
npm ci - Start command:
npm start - Persistent storage: keep the
data/directory and configuration across restarts and redeploys
There is no port to expose for the base bot. Run one instance per installation and never share one data store between multiple copies. A local instance lock prevents concurrent startup and protects migration writes, but it does not coordinate separate hosts.
Verify the installation
- Confirm the 17 core slash commands registered to the intended server.
- Run
/evidenceas a staff member with a short test report and an attachment. - Confirm the forum post shows the case ID, embed, and expected status tag.
- Assign the case, add a note with
/followup, then close and reopen it. - Find the case with
/searchcasesand download it with/caseexport. - If configured, submit a test appeal from an allowlisted webhook and confirm it is imported.
- If you enabled LiteBans or AdvancedBan, issue a test punishment and confirm a case appears once, including after a restart.
- Restart the bot and confirm
data/cases.jsonstill holds the case.