Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/developer51709/Niko/llms.txt

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

Self-hosting Niko means you’re responsible for keeping the bot healthy over time. This guide covers the routine tasks every operator should know: pulling updates, protecting your data, keeping the process alive, and diagnosing common problems when they arise.

​
Updating

Niko follows a straightforward Git-based update workflow. After pulling, always upgrade dependencies so new library requirements don’t cause import errors on the next startup.
1

Pull the latest changes

From the root of your Niko repository, run:
git pull origin main
2

Update dependencies

Install all Python packages pinned in requirements.txt:
pip install -r requirements.txt
3

Restart the bot process

Stop the currently running bot and start it again. If you are using a process manager such as PM2 or systemd (see Process Management below), issue the appropriate restart command for that tool. On Replit, stop and re-run the Discord Bot workflow.

​
Data Backup

All of Niko’s runtime state is stored in the data/ directory (JSON files and one SQLite database) plus memory.json for AI conversation history. Losing this directory means losing economy balances, XP progress, moderation records, and everything else — back it up regularly.
PathContents
data/economy_data/Per-user economy profiles — coin/bank balance, inventory, job, transaction log
data/levels.jsonPer-guild, per-user XP and level
data/warnings.jsonModeration warning records (User ID + reason + timestamp)
data/reminders.jsonScheduled reminder text and trigger timestamps
data/highlights.jsonUser keyword lists for DM notifications
data/birthdays.jsonUser birthday (MM-DD) entries
data/polls.jsonPoll questions, options, vote counts, and voter IDs
data/suggestions.jsonSuggestion text, author User ID, and vote counts
data/starboard.jsonOriginal message ID → starboard message ID mapping
data/tags.jsonPer-guild custom tag names, content, and author User IDs
data/database.dbGiveaway data — entries, end times, host and participant User IDs (SQLite)
memory.jsonAI conversation history, memory notes, and favorability scores per user
Automate backups with a cron job or systemd timer. A simple daily cron entry that compresses and copies the data/ folder and memory.json to a remote location (S3, a NAS, another server) is enough to protect against most data loss scenarios:
# Example: back up every day at 03:00
0 3 * * * tar -czf /backups/niko-$(date +\%F).tar.gz /path/to/niko/data /path/to/niko/memory.json

​
Process Management

Niko must stay running continuously to respond to Discord events. How you achieve that depends on your hosting environment.

​
Non-Replit (VPS / Dedicated Server)

Use PM2 or systemd to supervise the process and automatically restart it on crashes or reboots. PM2 (quick start): 
pm2 start "python src/bot.py" --name niko
pm2 save          # persist across reboots
pm2 startup       # generate the OS-level startup hook
Useful PM2 commands: 
pm2 status        # see running processes
pm2 logs niko     # tail live logs
pm2 restart niko  # restart the bot
pm2 stop niko     # stop the bot
systemd (production-grade): Create a service file at /etc/systemd/system/niko.service: 
[Unit]
Description=Niko Discord Bot
After=network.target

[Service]
Type=simple
User=niko
WorkingDirectory=/opt/niko
ExecStart=/usr/bin/python3 src/bot.py
Restart=on-failure
RestartSec=5
EnvironmentFile=/opt/niko/src/.env

[Install]
WantedBy=multi-user.target
Then enable and start it: 
sudo systemctl daemon-reload
sudo systemctl enable niko
sudo systemctl start niko

​
Replit

Use the Workflows tab to start, stop, and inspect the Discord Bot workflow. The Logs tab streams stdout/stderr in real time.

​
Monitoring

​
Console Logs

Niko uses a custom coloured terminal logger (src/utils/logging.py). Watch the console output for ERROR or WARNING lines during startup and normal operation. The log level labels indicate severity.

​
Logging Webhook

Set the LOGGING_WEBHOOK environment variable to a Discord webhook URL to have bot log output mirrored to a Discord channel. This is useful when you want alerts for errors without needing to SSH into the server. 
LOGGING_WEBHOOK=https://discord.com/api/webhooks/...

​
Debug Mode

Set DEBUG_MODE=True in your environment to enable verbose output. This is especially helpful when diagnosing AI API errors or tracing command failures: 
DEBUG_MODE=True
Remember to remove or set it back to False in production — verbose logging generates significant noise and can expose sensitive request/response data in logs.

​
Reloading Cogs Without Restart

Niko supports hot-reloading individual feature modules (cogs) from Discord itself. All three commands below are owner-only and available as prefix commands (default prefix: .).

​
.devreload <cog>

Reloads a single cog by its dotted module path (e.g. cogs.economy.main) without restarting the entire bot. Use this after patching a bug in a single cog file so users aren’t affected by a full outage.

​
.sync

Re-syncs all slash commands with Discord globally. Run this after adding or renaming slash commands. Global sync can take up to an hour to propagate to all Discord clients. You can also sync to the current guild only for faster testing: 
.sync guild

​
.syncemojis

Uploads and syncs application emojis from your local emoji configuration to Discord. Run this after adding new custom emojis that Niko uses in its responses.

​
Troubleshooting

Discord’s global rate limit is 50 requests per second per bot token. If Niko is hitting rate limits you will see 429 Too Many Requests errors in the console.Common causes include mass webhook creation (e.g. running a notifier or logging setup across many channels in quick succession). Add delays between bulk operations and avoid running multiple bots on the same token. If you are using the notifier cog with many subscriptions, consider staggering poll intervals.
If you see ModuleNotFoundError or ImportError at launch, your installed packages are out of date or missing. Run:
pip install --upgrade -r requirements.txt
Make sure you are running the command inside the same Python virtual environment (if any) that your bot uses.
Global slash command registration can take up to one hour to propagate to all Discord clients after a sync. If commands are missing:
  1. Run .sync (owner only) from a Discord channel where the bot is present, or restart the bot — it syncs globally on startup.
  2. For instant testing, run .sync guild to sync to the current server only.
  3. Make sure the bot was invited with the applications.commands OAuth2 scope. If not, re-invite it using a URL that includes that scope.
Niko’s music system uses wavelink to connect to a Lavalink node. If /play or other music commands fail or return errors:
  1. Confirm your Lavalink node is running and reachable from the machine hosting the bot.
  2. Check the wavelink connection in startup logs — you should see a successful node connection message.
  3. Verify the Lavalink host, port, and password in your environment variables match the running node’s configuration.
  4. See lavalink.dev for Lavalink setup and troubleshooting.
If Niko doesn’t reply when mentioned or messaged:
  1. Confirm AI_INTEGRATIONS_OPENAI_API_KEY (or the equivalent key for your OpenAI-compatible provider) is set in your environment.
  2. Enable DEBUG_MODE=True and watch the console for API error responses — these will show you whether the key is invalid, the endpoint is unreachable, or a quota has been exceeded.
  3. Check that the Message Content privileged intent is enabled in the Discord Developer Portal under your application’s Bot settings.

Build docs developers (and LLMs) love

Get started for freeTalk to us