The warm, capable Discord companion for communities that care.
Moderation, music, progression, tickets, social feeds, and AI — in one polished Discord experience with a full web dashboard.
Add Niko · Dashboard · Support server · Documentation · Changelog
Niko is a self-hosted Discord bot built for communities that want thoughtful moderation, engaging social features, and a dashboard that actually reflects how their server is doing. It runs as a single Python process: the bot, the Flask API, and the generated React dashboard share one deployment, one database, and one event loop.
The result is a companion that feels native to Discord — fast slash commands, polished Components v2 panels, live profile popouts, and transcripts that look like Discord's own — without giving up the control of self-hosting.
Quick start: set
DISCORD_BOT_TOKEN, runpython src/bot.py, and open the dashboard on port5000.
- Kick, ban, mute, tempmute, warn, purge, slowmode, and channel lockdown
- AutoMod for spam, invite links, blocked words, mass mentions, join raids, and external-app abuse
- Premium AI image filtering through fal.ai's NSFW model
- Moderation logs, case history, and per-server exemption lists
- Persistent ticket system with Discord-styled HTML transcripts
- Giveaways with account-age, server-age, role, and booster requirements
- Polls, suggestions, starboard, custom tags, birthdays, and reminders
- Social feed notifications for YouTube, Twitch, X, TikTok, Bluesky, and Reddit
- Lavalink/wavelink playback with queue, loop, shuffle, volume, and seek controls
- YouTube, Spotify, and direct URL support
- Live now-playing cards and Last.fm-powered autoplay
- Monthly server subscriptions with a white-label OxaPay crypto checkout
- AI image moderation (
fal-ai/imageutils/nsfw) as the premium perk - Gift premium to a server you are in, with an automatic DM to its owner
- Renewal reminders before a subscription ends and an owner billing tab
- Per-message XP, leveling curves, role rewards, and leaderboards
- Jobs, banking, daily streaks, shops, collectibles, crime, and robbery
- Weekly lottery and unlockable achievements with server-side image cards
- OpenAI-compatible chat with per-user memory and favorability
- Configurable identity and tone per server
- Image generation, translation, definitions, and AI-assisted error reports
- Discord OAuth dashboard for server settings, activity, and moderation insights
- Live command directory, documentation, changelog, and public profile cards
- Staff workspace for team applications, server notes, standby management, and owner-only billing
- Optional Discord REST proxy workers with live latency, errors, and request telemetry
- Interaction endpoint support, standby failover, and Discord-aware proxy recovery
| Layer | Technology |
|---|---|
| Bot runtime | Python 3.10+, discord.py 2.7+ |
| Web API | Flask, served in the bot process |
| Dashboard | React 18, TypeScript, Vite 6 |
| Music | Lavalink / wavelink |
| AI | OpenAI-compatible API |
| Storage | MongoDB when configured, with SQLite/JSON fallbacks |
| AI image moderation | fal.ai (fal-ai/imageutils/nsfw) |
| Optional Discord egress | Cloudflare Workers (proxy-worker/) |
src/
├── bot.py # Bot entry point and gateway lifecycle
├── api_server.py # Starts the Flask API beside the bot
├── cogs/ # Feature modules (moderation, economy, music, ...)
├── webapp/ # Flask routes, auth, cards, and shared web helpers
├── utils/ # AI, music, tickets, image rendering, and integrations
├── events/ # Gateway and startup event handlers
├── config/ # Bot IDs, links, emojis, and runtime configuration
├── assets/ # Fonts, badges, and generated emoji art
└── website/dist/ # Generated dashboard build (served by Flask)
web/ # React + Vite dashboard source
docs/ # Setup, API, dashboard, maintenance, and legal docs
tests/ # pytest suite covering bot, API, and rendering behavior
nsfw-api/ # Optional Cloudflare Worker for image classification
proxy-worker/ # Optional Cloudflare Worker for Discord API egress
scripts/ # Badge and emoji asset generation helpers
src/website/dist/ is generated output. Edit web/ and run the build rather than changing files under dist/ directly.
- Python 3.10 or newer
- Node.js 20 or newer
- A Discord application with a bot user and the Message Content, Server Members, and Presence intents enabled
git clone https://github.com/developer51709/Niko.git
cd Niko
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txtSet these variables in your hosting dashboard, shell, or a local src/.env file. DISCORD_BOT_TOKEN is required; the dashboard needs OAuth credentials.
| Variable | Required | Purpose |
|---|---|---|
DISCORD_BOT_TOKEN |
Yes | Bot token from the Discord Developer Portal |
DISCORD_CLIENT_SECRET |
For the dashboard | Enables Discord OAuth login |
SESSION_SECRET |
Recommended | Keeps dashboard sessions stable across restarts |
DISCORD_CLIENT_ID |
Optional | Defaults to Niko's application ID |
PUBLIC_URL |
Optional | Canonical public origin for OAuth and links |
PORT |
Optional | Web port, defaults to 5000 |
MONGODB_URL |
Optional | MongoDB connection; otherwise local storage is used |
MONGODB_DATABASE |
Optional | MongoDB database name |
DISCORD_PUBLIC_KEY |
Optional | Enables Discord's interactions endpoint |
FAL_KEY |
For premium moderation | fal.ai key for the AutoMod NSFW image filter |
OXAPAY_API_KEY |
For payments | OxaPay merchant key for premium and donation checkout |
PROXY_WORKER_TOKEN |
Optional | Enables owner-managed Discord API proxy workers |
TOPGG_WEBHOOK_TOKEN |
Optional | Enables top.gg vote rewards |
The full list, including Twitch and notification integrations, lives in docs/setup.md.
npm install
npm run buildpython src/bot.pyThe API starts with the bot. The dashboard is available at http://localhost:5000 (or your configured PORT), and the same process serves the generated site from src/website/dist/.
| Area | Commands |
|---|---|
| Economy | /balance /daily /work /job /shop /bank /lottery /pay /crime /rob |
| Leveling | /leveling rank /leveling leaderboard /leveling panel /leveling config |
| Music | /play /nowplaying /queue /skip /stop /loop /shuffle /volume |
| Moderation | /kick /ban /warn /mute /purge /automod /whitelist |
| Giveaways | /giveaway start /giveaway end /giveaway reroll /giveaway list |
| Tickets | /ticket panel /ticket config /close /delete |
| Community | /poll /suggest /starboard /tag /birthday /highlight /notifier |
| AI | @Niko /favor /memory /imagine /translate /define |
| Fun | /hug /pat /boop /meme /cat /afk /snipe |
| Utility | /remind /serverinfo /userinfo /avatar /prefix |
| Admin | /reload /sync /emojisync /onboarding /voicemaster /trigger |
The dashboard's live command directory is the source of truth for the current build.
| Guide | What it covers |
|---|---|
| Setup | Environment variables, first run, and interactions endpoint |
| API | Public and authenticated routes, plus endpoint conventions |
| Dashboard | Dashboard structure and server configuration |
| Maintenance | Updates, backups, proxy behavior, and standby failover |
| AI providers | OpenAI-compatible provider configuration |
| FAQ | Common questions and troubleshooting |
| Privacy policy | What Niko stores and how it is used |
| Terms of service | Usage terms for the hosted deployment |
Public documentation, release notes, and the command reference are also available at niko.sryze.cc.
Niko takes user privacy seriously. If you believe you have found a vulnerability, please report it privately:
- Open a private security advisory at github.com/developer51709/Niko/security/advisories/new, or
- Join the support server and open a Bug post in
#community-helpor a private ticket from#create-a-ticket.
Include the affected endpoint or page, reproduction steps, and the impact. Please do not include real secrets or other people's private data. Valid reports are rewarded with the Bug Bounty role, because every vulnerability fixed is a potential future incident prevented.
The deployment also publishes /.well-known/security.txt and serves friendly decoy responses on commonly scanned secret paths rather than exposing real configuration.
Run the checks before opening a pull request:
pytest
npm run typecheck
npm run buildGuidelines:
- Keep changes focused and match the existing Python and React conventions.
- Add or update tests when behavior changes.
- Update
web/src/data/changelog.tsfor user-visible updates. - Rebuild
src/website/dist/when the frontend changes; do not edit generated assets by hand. - Never commit tokens,
.envfiles, or other credentials.
Niko is built and maintained by @sorenthedev, with contributions from the Niko staff and community.
Built for communities that care.