Self-hosting guide

Run your own
Chopsticks.

Full Docker stack — PostgreSQL, Redis, and Lavalink included. One command and you're running. MIT licensed. Own it completely.

View on GitHub →Quickstart

Prerequisites

Requirement	Version	Notes
Node.js	20 or 22 LTS	Required even with Docker for deploy scripts
Docker + Compose	v2+	docker compose (not docker-compose)
PostgreSQL	15+ (or use Docker)	Included in all Docker Compose profiles
Redis	7+ (or use Docker)	Included in all Docker Compose profiles
Lavalink	Latest	Music playback only — skip if disabling music
Discord bot token	—	Create at discord.com/developers

Quickstart (Docker)

Clone the repository

git clone https://github.com/WokSpec/Chopsticks.git
cd Chopsticks

Configure your environment

Copy the example env file and fill in the required values. At minimum you need DISCORD_TOKEN, CLIENT_ID, and BOT_OWNER_IDS.

cp .env.example .env
# Open .env in your editor and fill in:
#   DISCORD_TOKEN=your_bot_token_here
#   CLIENT_ID=your_application_id
#   BOT_OWNER_IDS=your_discord_user_id

Start the stack

Use the free-tier profile for a minimal deployment, or the production profile for a hardened setup.

# Minimal free-tier stack
docker compose -f docker-compose.free.yml up -d

# Production-hardened stack
docker compose -f docker-compose.production.yml up -d

The bot will auto-register slash commands on first start. Check logs with docker compose logs -f bot.

Rebranding your instance

Everything needed to give Chopsticks your own brand identity lives in src/config/branding.js. No other files need to change for a full rebrand.

// src/config/branding.js
export const Branding = {
  name:          "YourBot",
  tagline:       "Your bot's tagline",
  supportServer: "https://discord.gg/yourserver",
  inviteUrl:     "https://discord.com/api/oauth2/authorize?...",
  website:       "https://yourbot.example.com",
  github:        "https://github.com/yourname/yourbot",
  footerText:    "{botname} • yourbot.example.com",

  colors: {
    primary: 0xFF5733,   // hex → decimal: parseInt('FF5733', 16)
    success: 0x57F287,
    error:   0xED4245,
    music:   0x1DB954,
  },
};

Alternatively, set everything via .env — no code edits required:

BOT_NAME=YourBot
BOT_TAGLINE=Your bot's tagline
COLOR_PRIMARY=16734003    # decimal equivalent of hex color
FEATURE_ECONOMY=false     # disable modules you don't need

Per-server customization

Server admins can customize appearance and features per-guild using /theme — no fork or restart needed.

Command	Effect
/theme color primary #FF5733	Change the primary embed color for this server
/theme color success #00FF00	Change success embed color
/theme name MyBot	Rename the bot persona in this server
/theme footer "Powered by MyBot"	Set a custom embed footer
/theme feature economy disable	Disable the economy module in this server
/theme preview	Preview current server theme
/theme reset	Reset all customizations to bot defaults

Feature flags

Toggle entire modules on or off. Useful if you want a music-only bot, a moderation-only bot, etc.

# .env — disable modules globally
FEATURE_ECONOMY=false
FEATURE_MUSIC=false
FEATURE_AI=false
FEATURE_LEVELING=false

Docker Compose profiles

File	Use case
docker-compose.free.yml	Minimal free-tier stack — bot + DB + Redis
docker-compose.production.yml	Hardened production with secrets management
docker-compose.lavalink.yml	Adds Lavalink for music support
docker-compose.monitoring.yml	Adds Prometheus + Grafana monitoring
docker-compose.voice.yml	Voice-focused stack with agent pool support
docker-compose.laptop.yml	Lightweight dev stack for local development

Need more detail?

The full SELF_HOSTING.md in the repo covers every config option, environment variable, and deployment scenario.

Full guide on GitHub Read the docs

Need help getting set up?

Open a discussion on GitHub and the community will help. For issues with the bot itself, file a bug report. For questions about specific deployments, Discussions is the right place.

GitHub Discussions Open an issue