Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/onesoft-sudo/sudobot/llms.txt

Use this file to discover all available pages before exploring further.

SudoBot reads its runtime configuration from environment variables, which you typically store in a .env file at the project root. Required variables must be present or the bot will refuse to start. Optional variables unlock additional features or override default behavior. Never commit your .env file to version control — it contains secrets.
Variables marked as sensitive control authentication and access. Treat them like passwords: use strong random values, rotate them if exposed, and store them in a secrets manager for production deployments.

​
Example .env file

# ─── Required ─────────────────────────────────────────────────────────────────

TOKEN=your-bot-token
CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret
HOME_GUILD_ID=your-home-guild-id
DB_URL=postgresql://username:password@hostname:5432/sudobot
JWT_SECRET=your-jwt-secret

# ─── Optional ─────────────────────────────────────────────────────────────────

PORT=4000
SUDO_PREFIX=/path/to/sudobot/storage
NODE_ENV=production

​
Required variables

These variables must be set before starting the bot.
​
TOKEN
string
required
Your Discord bot token from the Discord Developer Portal. This authenticates the bot with the Discord API.Sensitive — do not commit or share this value.
​
CLIENT_ID
string
required
The application (client) ID of your Discord bot, found in the Discord Developer Portal. Used for OAuth2 flows and slash command registration.
​
CLIENT_SECRET
string
required
The OAuth2 client secret for your Discord application. Required for OAuth2-based authentication.Sensitive — do not commit or share this value.
​
HOME_GUILD_ID
string
required
The Discord guild (server) ID used as your home guild. The bot registers development slash commands here, searches for custom emojis here, and sends error reports to this guild.
​
DB_URL
string
required
PostgreSQL connection URL in the format postgresql://username:password@hostname:port/database. SudoBot uses this to connect to its database for storing settings, infractions, and other persistent data.Sensitive — this contains your database credentials.
​
JWT_SECRET
string
required
Secret key used to sign and verify JWT tokens for the bot’s internal API authentication. Generate a strong random value — for example, on Linux/macOS:
openssl rand -base64 32
Sensitive — treat this like a password.

​
Server and runtime variables

​
PORT
string
default:"4000"
The TCP port the bot’s built-in API server listens on. Must be a valid integer. Defaults to 4000.
​
SUDO_PREFIX
string
The root directory where SudoBot stores its persistent data, including config/config.json, config/system.json, logs, and extension files. If not set, the bot falls back to a default location relative to the project root. Set this to a directory outside the repository to prevent your configuration from being overwritten by Git updates.
​
NODE_ENV
string
default:"production"
Sets the application environment. Accepted values: development, production, dev, prod, test. Setting this to development or dev enables additional debug logging and development-specific behaviors.
​
SUDO_ENV
string
An alternative way to set the SudoBot environment. Accepted values: dev, prod. Takes precedence in some code paths over NODE_ENV.
​
DEBUG
string
Set to 1 to enable debug mode, or 0 to disable it. When enabled, the bot produces more verbose log output.
​
SUPPRESS_LOGS
string
Set to any non-empty value to suppress standard log output. Useful for production environments that manage logs through a separate logging system.
​
EXTENSIONS_DIRECTORY
string
Custom path to the directory where SudoBot looks for installed extensions. Overrides the default location under SUDO_PREFIX.
​
SOCKET_FILE
string
Path to the Unix socket file used for inter-process communication between the bot and the log server. Defaults to a path under SUDO_PREFIX.
​
DISCORD_INTENTS
string
A space- or comma-separated list of Discord gateway intents to enable. When not set, SudoBot uses a default set of intents.
​
HTTP_USER_AGENT
string
Custom User-Agent header sent with outgoing HTTP requests made by the bot. Set to the string null to omit the User-Agent header entirely.
​
PRIVATE_BOT_MODE
string
Set to true to enable private bot mode, which restricts the bot to only operate in guilds it has been explicitly configured for.
​
NO_GENERATE_CONFIG_SCHEMA
string
Set to any non-empty value to skip auto-generating JSON schema files for config.json and system.json at startup.

​
Web and OAuth2 variables

​
BASE_SERVER_URL
string
The base URL of the bot’s API server, used when generating absolute URLs in API responses. For example: https://api.example.com.
​
FRONTEND_URL
string
The URL of the SudoBot web frontend. Used for generating links sent to users during verification flows.
​
FRONTEND_GUILD_MEMBER_VERIFICATION_URL
string
URL template for the guild member verification page on the frontend. SudoBot substitutes guild and token parameters into this URL and sends it to users who need to verify.
​
DISCORD_OAUTH2_REDIRECT_URI
string
The redirect URI registered in the Discord Developer Portal for the standard OAuth2 flow. Must exactly match the URI configured in the portal.
​
DISCORD_OAUTH2_RP_REDIRECT_URI
string
The redirect URI for the relying-party OAuth2 flow (used by the verification system).
​
FRONTEND_KEY
string
A shared secret between the bot API and the web frontend, used to authenticate certain internal API requests.Sensitive — do not commit or share this value.
​
MODIFICATIONS_PUBLIC_URL
string
The publicly accessible URL where modification logs or audit exports are served.
​
HIDE_MODIFICATIONS_URL_NOTICE
string
Set to 1 to suppress the notice that displays the MODIFICATIONS_PUBLIC_URL in bot output.

​
Authentication integration variables

​
GITHUB_CLIENT_ID
string
GitHub OAuth2 application client ID. Required if you enable GitHub-based login in the SudoBot web frontend.
​
GITHUB_CLIENT_SECRET
string
GitHub OAuth2 application client secret.Sensitive — do not commit or share this value.
​
GOOGLE_CLIENT_ID
string
Google OAuth2 application client ID. Required if you enable Google-based login in the SudoBot web frontend.
​
GOOGLE_CLIENT_SECRET
string
Google OAuth2 application client secret.Sensitive — do not commit or share this value.
​
RECAPTCHA_SECRET_KEY
string
Google reCAPTCHA v2 or v3 secret key. Used to validate CAPTCHA responses during member verification.Sensitive — do not commit or share this value.
​
CF_TURNSTILE_SECRET
string
Cloudflare Turnstile secret key. An alternative to reCAPTCHA for bot-detection during member verification.Sensitive — do not commit or share this value.
​
TWO_FACTOR_AUTH_URL
string
URL for a two-factor authentication service integrated with the bot’s login system.

​
Third-party API keys

​
CAT_API_TOKEN
string
API token from TheCatAPI. Enables the cat command to fetch cat images.
​
DOG_API_TOKEN
string
API token from TheDogAPI. Enables the dog command to fetch dog images.
​
PIXABAY_TOKEN
string
API key from Pixabay. Enables the pixabay image search command.
​
API_NINJAS_JOKE_API_KEY
string
API key from API Ninjas. Enables the joke command.
​
PERSPECTIVE_API_TOKEN
string
API key for Google’s Perspective API. Used by AI-based auto-moderation to score message toxicity.Sensitive — do not commit or share this value.
​
PROXYCHECKIO_API_KEY
string
API key for ProxyCheck.io. Used during member verification to detect VPN and proxy connections.
​
PAXMOD_API_KEY
string
API key for Paxmod, a third-party moderation data service used by SudoBot.
​
SYSTEM_API_URL
string
Base URL for the system-level external API that SudoBot may call for extended functionality.

​
AI and content moderation variables

​
NSFWJS_MODEL_URL
string
URL to a custom NSFW.js TensorFlow model. When set, SudoBot uses this model for image content classification instead of the bundled default.
​
NSFWJS_MODEL_IMAGE_SIZE
string
The input image size (in pixels, as an integer string) expected by the NSFWJS model. Required when using a custom model that differs from the default image dimensions.

​
Webhook and notification variables

​
ERROR_WEBHOOK_URL
string
A Discord webhook URL where the bot sends uncaught error reports. Useful for monitoring production deployments.
​
DM_LOGS_WEBHOOK_URL
string
A Discord webhook URL where the bot forwards direct message logs.
​
BACKUP_CHANNEL_ID
string
Discord channel ID where the bot uploads periodic data backups.
​
BACKUP_STORAGE
string
Storage backend identifier or path for backup data. Controls where the bot writes backup files.
​
DATA_DELETION_REQUESTS_CHANNEL_ID
string
Discord channel ID where the bot posts data deletion request notifications.

​
System shell variables

​
SYSTEM_SHELL_KEY
string
Authentication key for the system shell API endpoint. Required to use the remote shell execution feature.Sensitive — do not commit or share this value.
​
SYSTEM_SHELL_EXEC_STREAM_PORT
string
TCP port for the shell execution stream server. Must be a valid integer.

​
Emoji variables

​
EMOJI_RESOLVE_STRATEGY
string
default:"both"
Controls how the bot resolves custom emoji. Accepted values:
  • both — searches the home guild first, then falls back to application emojis
  • home_guild — uses only the home guild’s emojis
  • application — uses only application-level emojis
This can also be set via emoji_resolve_strategy in system.json.
The EMOJI_RESOLVE_STRATEGY environment variable overrides the emoji_resolve_strategy field in system.json when both are set.

Build docs developers (and LLMs) love

Get started for freeTalk to us