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.

This guide walks you through setting up a self-hosted SudoBot instance from source. You will clone the repository, build the project with BlazeBuild, configure your environment and config files, run database migrations, and start the bot. The process takes about 10–20 minutes depending on your system speed.

Prerequisites

Before you begin, have the following ready:
  • Discord API application — Go to the Discord Developer Portal to create an application and obtain your bot token, client ID, and client secret.
  • PostgreSQL database — A local PostgreSQL server or a hosted service such as Supabase. SudoBot will connect to it via a connection URL.
  • Node.js v21+ or Bun v1.1.12+ — Either runtime works. If neither is installed, BlazeBuild will install one automatically during the build.
  • Git — Optional, but recommended for cloning the repository.
The following optional credentials unlock additional commands: a TheCatAPI token (for cat), a TheDogAPI token (for dog), a Pixabay token (for pixabay), and a Discord webhook URL for error reports.
These instructions assume a Linux or macOS system. Windows users should follow the Windows compatibility section below.

Installation steps

1

Clone the repository

Clone the SudoBot GitHub repository to your local machine:
git clone https://github.com/onesoft-sudo/sudobot
cd sudobot
If you prefer SVN:
svn checkout https://svn.onesoftnet.eu.org/svn/sudobot sudobot
cd sudobot
If you don’t have Git or SVN installed, download the latest release archive from the GitHub releases page and extract it.
2

Build the project

SudoBot uses BlazeBuild, an included build tool that automatically installs any missing SDKs or tools before compiling.
Run the BlazeBuild wrapper to compile the TypeScript source into the build/ directory:
./blazew build
The build requires at least 8 GB of RAM and 2 CPU cores for reasonable build times. If the process fails with heap allocation errors, download a prebuilt release instead from the GitHub releases page.
Prebuilt releases are tested on Node.js v23 and v22 but also work with v21 and v20. Only Linux and macOS native binaries are distributed, but this does not prevent you from running the bot on Windows.
3

Configure environment variables

Create a .env file in the project root. This file holds your secret credentials and must never be committed to version control.
# Your bot's token from the Discord Developer Portal.
TOKEN=your-bot-token

# Client ID of your bot from the Discord Developer Portal.
CLIENT_ID=your-bot-client-id

# Client Secret of your bot from the Discord Developer Portal.
CLIENT_SECRET=your-bot-client-secret

# The ID of the guild used for development mode command registration
# and emoji lookup. The bot also sends error reports here.
HOME_GUILD_ID=your-home-guild-id

# PostgreSQL connection URL.
# Format: postgresql://username:password@hostname:port/database
DB_URL=postgresql://username:password@hostname:5432/sudobot

# JWT secret for the bot's internal token generation.
# Generate one on Linux/macOS: openssl rand -base64 32
JWT_SECRET=your-jwt-secret

# Directory where the bot stores persistent data such as config files and logs.
SUDO_PREFIX=/path/to/sudobot/storage

# Uncomment to enable debug mode and development features.
# NODE_ENV=development
For a full list of supported environment variables, see the EnvironmentVariableSchema source file.
4

Configure the bot

SudoBot reads its settings from two JSON files:
  • config.json — guild-level settings (prefix, roles, feature toggles)
  • system.json — global system-level settings (admin IDs, global flags)
Both files are included in the config/ directory of the repository as starting points. Edit them to match your server, then copy the entire config/ directory to your SUDO_PREFIX directory:
cp -r config /path/to/sudobot/storage/config
Keeping your config files inside SUDO_PREFIX (outside the repository directory) prevents them from being overwritten when you pull updates with Git.
To see all available options, refer to the schema files:
5

Run database migrations

With your DB_URL set in .env, run the following command to create the required tables in your PostgreSQL database:
./blazew migrate
6

Start the bot

Launch SudoBot with BlazeBuild:
./blazew run
Your bot should come online in your Discord server. If you encounter any issues, join the Discord server and ask for help.

Registering application commands

SudoBot uses Discord’s Application Commands API for slash commands and context menus. After the bot starts for the first time, register the commands:
# Registers commands in HOME_GUILD_ID when debug mode is on
./blazew run -- -u

Setting up emojis

SudoBot uses custom emojis for formatting certain messages. The bot searches for these in the guild specified by HOME_GUILD_ID. Without them, some bot messages may appear broken or unformatted. Download the emoji pack from the OSN download server and upload the images to your home guild. Some additional emojis are available on emoji.gg.

Windows compatibility

BlazeBuild on Windows is still experimental. Use the following commands instead:
1

Install dependencies

bun install
2

Build the project (Node.js only)

Skip this step if you are using Bun.
npm run build
After building, copy src/main/resources into build/out/main/resources.
3

Run database migrations

Create a migration script manually. For Bun, create migrate.ts:
import "dotenv/config";

const { drizzle } = await import(String("drizzle-orm/node-postgres"));
const { migrate } = await import(String("drizzle-orm/node-postgres/migrator"));
const { Pool } = await import(String("pg"));

const pool = new Pool({ connectionString: process.env.DB_URL });
const db = drizzle(pool);
await migrate(db, { migrationsFolder: "drizzle" });
await pool.end();
Then run it:
bun migrate.ts
For Node.js, create migrate.js:
require("dotenv/config");

async function main() {
    const { drizzle } = await import(String("drizzle-orm/node-postgres"));
    const { migrate } = await import(String("drizzle-orm/node-postgres/migrator"));
    const { Pool } = await import(String("pg"));

    const pool = new Pool({ connectionString: process.env.DB_URL });
    const db = drizzle(pool);
    await migrate(db, { migrationsFolder: "drizzle" });
    await pool.end();
}

main();
Then run it:
node migrate.js
4

Start the bot

bun dev
To pass options that you would normally pass to ./blazew run, append them directly when using Bun (bun dev -u), or after -- when using npm (npm run start -- -u).

Getting help

If you get stuck at any point:

Build docs developers (and LLMs) love