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’s global configuration lives in $SUDO_PREFIX/config/system.json. Unlike the per-guild config.json, this file controls settings that apply across every guild the bot operates in — including which users are system administrators, how the internal API behaves, what presence the bot displays, and how commands are registered with Discord.
Changes to system.json require a bot restart to take effect unless you use a configuration reload command. The file is validated against the SystemConfigSchema on startup; invalid values cause the bot to exit with an error.

​
File structure

system.json
{
  "$schema": "./schema/system.schema.json",
  "sync_emojis": true,
  "emoji_resolve_strategy": "both",
  "system_admins": [],
  "restart_exit_code": 1,
  "commands": { ... },
  "api": { ... },
  "presence": { ... },
  "extensions": { ... },
  "logging": { ... },
  "statistics": { ... }
}
SudoBot automatically generates a JSON schema file at $SUDO_PREFIX/config/schema/system.schema.json on startup. Add the $schema field shown above to enable autocompletion and inline validation in editors like VS Code.

​
Top-level fields

​
$schema
string
Optional path or URL to the JSON schema for this file. Used only by editors for validation and autocompletion; SudoBot itself ignores this field.
​
sync_emojis
boolean
default:"true"
When true, SudoBot syncs custom emoji from the home guild to the application’s emoji store on startup. Disable this if you manage application emojis manually.
​
emoji_resolve_strategy
string
default:"both"
Controls how the bot resolves custom emoji references. Accepted values:
  • "both" — searches the home guild first, then falls back to application-level emojis
  • "home_guild" — uses only the home guild’s custom emojis
  • "application" — uses only application-level emojis
The EMOJI_RESOLVE_STRATEGY environment variable overrides this field when both are set.
​
restart_exit_code
integer
default:"1"
The process exit code SudoBot uses when restarting. Process managers like PM2 can use non-zero exit codes to distinguish a deliberate restart from a crash.
​
trust_proxies
integer
The number of reverse proxy hops to trust when reading client IP addresses from headers like X-Forwarded-For. Set this to the number of proxies in front of the API server (e.g., 1 for a single Nginx instance). Omit to disable proxy trust.
​
enable_file_filter
boolean
default:"false"
Enables a global file-type filter that inspects attachments in messages. When enabled, disallowed file types are blocked across all guilds.
​
command_permission_mode
string
default:"overwrite"
The default mode for resolving command permissions. Accepted values:
  • "ignore" — ignores Discord’s built-in slash command permissions
  • "overwrite" — SudoBot’s permission system takes precedence
  • "check" — checks both Discord’s and SudoBot’s permissions; the user must pass both
Individual guilds can override this via permissions.command_permission_mode in config.json.

​
System admins

system.json
{
  "system_admins": ["USER_ID_1", "USER_ID_2"]
}
​
system_admins
array of strings
default:"[]"
Discord user IDs who have full system-level access to the bot. System admins bypass all guild-level permission checks and can run any command in any guild, including commands that normal administrators cannot access.
System admin access is absolute. Only add user IDs you fully trust. A system admin can modify configuration, manage all guilds, and access sensitive bot internals.

​
Commands

system.json
{
  "commands": {
    "mention_prefix": true,
    "register_application_commands_on_boot": "auto_global",
    "groups": {},
    "global_disabled": [],
    "system_banned_users": []
  }
}
​
commands.mention_prefix
boolean
default:"true"
When true, any guild that does not override this setting allows users to invoke commands by mentioning the bot.
​
commands.register_application_commands_on_boot
string
default:"auto_global"
Controls when and where slash commands are registered. Accepted values:
  • "always_global" — registers all commands globally on every boot
  • "auto_global" — registers globally only when the command list has changed
  • "guild" — registers commands only in the home guild (faster, for development)
  • "none" — never registers commands automatically; you manage registration manually
​
commands.groups
object
default:"{}"
Maps group names to lists of command names. Groups are used to organize commands in the help system. Keys are group names; values are arrays of command name strings.
​
commands.global_disabled
array of strings
default:"[]"
Command names that are disabled across all guilds at the system level. No guild can enable these commands.
​
commands.system_banned_users
array of strings
default:"[]"
User IDs who are banned from using any bot command across all guilds.

​
Bot presence

system.json
{
  "presence": {
    "name": "your server",
    "type": "Watching",
    "status": "online",
    "url": "https://twitch.tv/example"
  }
}
​
presence.name
string
The activity text displayed in the bot’s status (e.g., “Watching your server”).
​
presence.type
string
The activity type. Accepted values: "Playing", "Watching", "Listening", "Streaming", "Competing", "Custom".
​
presence.status
string
The bot’s online status. Accepted values: "online", "idle", "dnd", "invisible".
​
presence.url
string
A URL associated with the activity. Only visible when type is "Streaming", in which case this should be a Twitch stream URL.

​
API

system.json
{
  "api": {
    "enabled": true,
    "server_status": "operational",
    "server_status_description": "All systems normal."
  }
}
​
api.enabled
boolean
default:"true"
Enables the built-in HTTP API server. Disable this if you do not use the API or the web frontend.
​
api.server_status
string
default:"operational"
The status string returned by the API’s status endpoint. Accepted values:
  • "operational" — everything is working normally
  • "degraded" — some functionality is impaired
  • "partial_outage" — some services are down
  • "major_outage" — most services are down
  • "maintenance" — the bot is undergoing planned maintenance
  • "error" — the bot encountered an unexpected error state
​
api.server_status_description
string
An optional human-readable explanation of the current server_status. This string is included in the API status response.

​
Extensions

system.json
{
  "extensions": {
    "default_mode": "enable_all"
  }
}
​
extensions.default_mode
string
default:"enable_all"
The default state for extensions that are not explicitly configured. Set to "enable_all" to activate all installed extensions by default, or "disable_all" to require each extension to be enabled explicitly in config.json.

​
Log server

system.json
{
  "log_server": {
    "enabled": false,
    "auto_start": false
  }
}
​
log_server.enabled
boolean
default:"false"
Enables the internal log server, which streams bot log output over a Unix socket. Used by companion tools that consume live log data.
​
log_server.auto_start
boolean
default:"false"
When true, the log server starts automatically with the bot. When false, you must start it manually.

​
Logging

The logging block configures a global webhook that receives all system-level log events, independent of the per-guild logging configuration in config.json.
system.json
{
  "logging": {
    "enabled": false,
    "webhook_url": "https://discord.com/api/webhooks/..."
  }
}
​
logging.enabled
boolean
default:"false"
Enables the global system logging webhook.
​
logging.webhook_url
string (URL)
required
A Discord webhook URL where system-level log events are sent. Must be a valid HTTPS URL.
This webhook URL grants the ability to post messages to your log channel. Store it securely and do not commit system.json to version control.

​
Statistics

system.json
{
  "statistics": {
    "enabled": false,
    "sync_delay": 60000
  }
}
​
statistics.enabled
boolean
default:"false"
Enables periodic statistics collection. When active, the bot gathers usage metrics such as command invocations and moderation actions.
​
statistics.sync_delay
integer
default:"60000"
How often in milliseconds the bot syncs collected statistics to the database. Default is one minute (60000 ms).

​
Infractions

system.json
{
  "infractions": {
    "store_attachments": true
  }
}
​
infractions.store_attachments
boolean
default:"true"
When true, the bot stores copies of message attachments that are part of infraction evidence (e.g., images in a deleted message that triggered a rule). Disable this to reduce storage usage.

​
Snippets

system.json
{
  "snippets": {
    "save_attachments": false
  }
}
​
snippets.save_attachments
boolean
default:"false"
When true, the bot downloads and stores attachments included when a snippet is created, so they remain available even if the original message is deleted.

​
Complete example

{
  "$schema": "./schema/system.schema.json",
  "system_admins": ["YOUR_USER_ID"],
  "commands": {
    "register_application_commands_on_boot": "auto_global"
  },
  "api": {
    "enabled": true
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us