Add to Discord
Tutorials

Step-by-step guides.

From adding the bot to self-hosting your own instance — everything you need, in the right order.

Beginner

Getting Started

Add Chopsticks to your server, grant the right permissions, and run your first commands. Five minutes from zero to working.

5 minRead
Beginner

Moderation Setup

Configure mod roles, a dedicated log channel, and test every action — ban, kick, mute, warn, and purge.

10 minRead
Beginner

Economy Setup

Set up the credits system, configure daily rewards, build a shop, and keep your community engaged with leaderboards.

15 minRead
Intermediate

Using the Agent Pool

Understand how the community Agent Pool works, configure it for your server, and deploy an agent to a voice channel.

20 minRead
Beginner

Customising with /theme

Change embed colors, rename the bot's persona, and disable modules — all from inside Discord, no code required.

8 minRead
Advanced

Self-hosting with Docker

Run your own Chopsticks instance. Full stack: PostgreSQL, Redis, Lavalink. From clone to online in under 15 minutes.

30 minRead

Getting Started

Beginner5 min

Add Chopsticks to your server, grant the right permissions, and run your first commands. Five minutes from zero to working.

1

1. Invite the bot

Visit the invite link and add Chopsticks to your server. Select a server where you have Manage Server permission.
2

2. Grant permissions

The invite pre-selects required permissions. Chopsticks needs at minimum: Send Messages, Embed Links, Use Application Commands, and Connect + Speak for music.
3

3. Run /setup

In any channel visible to the bot, run /setup. This initialises the database for your server — economy tables, mod log channel, welcome settings, etc.
4

4. Test a command

Try /ping to confirm the bot is responding. Then /help to see all available commands grouped by category.
5

Next steps

Head to the Moderation Setup or Economy Setup tutorials to configure those modules, or read Customising with /theme to brand the bot for your server.

Moderation Setup

Beginner10 min

Configure mod roles, a dedicated log channel, and test every action — ban, kick, mute, warn, and purge.

1

1. Set a mod log channel

Create a private channel (e.g. #mod-log) and run /setup modlog #mod-log. Every moderation action will be posted there with the moderator, reason, and case ID.
2

2. Assign mod roles

Run /setup modrole @YourModRole. Members with this role can use all moderation commands. You can add multiple roles.
3

3. Understand hierarchy

Chopsticks is hierarchy-safe — a moderator cannot take action against someone with a role higher than or equal to their own. This mirrors Discord's own hierarchy.
4

4. Test /warn

Run /warn @member Reason. This logs the warning, DMs the member, and creates a case record. Check /cases @member to view a user's history.
5

5. Configure auto-mod (optional)

Use /automod to set up spam filters, bad-word detection, or mention limits. Each rule can be scoped to specific channels or roles.

Economy Setup

Beginner15 min

Set up the credits system, configure daily rewards, build a shop, and keep your community engaged with leaderboards.

1

1. Enable economy

Run /setup economy enable. This creates the database tables for your server. Economy is on by default in the hosted instance.
2

2. Configure daily rewards

Run /setup daily amount:500 streak-bonus:100. Members can claim once per 24h. Streak bonuses reward consecutive daily claims.
3

3. Add shop items

Run /shop add name:"VIP Role" price:2000 role:@VIP. When a member buys this, the bot automatically assigns the role.
4

4. Set starting balance

New members start with 0 credits by default. To give a starting balance, run /setup economy start-balance:250.
5

5. Check the leaderboard

Run /leaderboard to see the top earners. Public and real-time. Great for competitions and engagement.

Using the Agent Pool

Intermediate20 min

Understand how the community Agent Pool works, configure it for your server, and deploy an agent to a voice channel.

1

How the pool works

The Agent Pool is a community-maintained set of bot tokens. When your server requests an agent, an available token from the pool is dispatched to your voice channel. You never manage tokens directly — you consume pool capacity via credits.
2

1. Configure via /setup agent-pool

Run /setup agent-pool to open the configuration wizard. Set which actions agents are allowed to perform, the credit cost per action, and the maximum session duration.
3

2. Earn or add credits

Server activity earns credits automatically. Credits are shared across the server, not per-user. Admins can also manually add credits with /credits add.
4

3. Request an agent

Join a voice channel, then run /agent join. An available agent from the pool will join within seconds. The bot confirms which agent was dispatched and the session credit cost.
5

4. Agent actions

Depending on your configuration, agents can play music, run AI conversations, host trivia games, or greet newcomers in voice. Use /agent leave to end the session and stop credit drain.
6

5. Contribute a token (optional)

To contribute a bot token to the community pool, see the Agent Pool contribution guide on GitHub.

Customising with /theme

Beginner8 min

Change embed colors, rename the bot's persona, and disable modules — all from inside Discord, no code required.

1

What /theme controls

The /theme command applies per-server customisations. Changes only affect your server. No forking, no code changes required.
2

1. Change embed color

Run /theme color #ff6b6b. All bot embeds in your server will use this accent color. Any valid hex value works.
3

2. Rename the bot's persona

Run /theme name "Wok Helper". This changes how the bot refers to itself in embeds within your server. The Discord username stays as Chopsticks.
4

3. Disable a module

Run /theme feature music:off to disable music commands in your server. Toggles: music, economy, games, ai. Re-enable with /theme feature music:on.
5

4. Check current theme

Run /theme view to see your active theme settings at a glance.
6

For deeper customisation

If you want to change the bot's name globally or avatar, that requires a self-hosted instance. See the Self-hosting tutorial.

Self-hosting with Docker

Advanced30 min

Run your own Chopsticks instance. Full stack: PostgreSQL, Redis, Lavalink. From clone to online in under 15 minutes.

1

Prerequisites

Docker Engine v24+ with Compose v2, a Discord application + bot token from the Developer Portal, and at least 1 GB of free RAM (2 GB recommended for the full stack).
2

1. Clone and configure

git clone https://github.com/WokSpec/Chopsticks.git
cd Chopsticks
cp .env.example .env
Open .env and fill in your DISCORD_TOKEN and CLIENT_ID.
3

2. Choose a profile and start

# Minimal (bot + PostgreSQL + Redis)
docker compose --profile free up -d

# Full stack (adds Lavalink + monitoring)
docker compose --profile production up -d
4

3. Verify it's running

docker compose ps
docker compose logs bot --follow
You should see the bot come online in your Discord server.
5

4. Rebrand (optional)

Edit src/config/branding.js to change the bot name, default colors, and enabled modules. Rebuild with docker compose build && docker compose up -d.
6

5. Stay updated

git pull && docker compose build && docker compose up -d
Watch GitHub releases for breaking changes before updating.
7

Need help?

Open a GitHub Discussion or an issue. Full guide on the Self-host page.

Still stuck?

Open a GitHub Discussion or file an issue. The community and maintainers actively respond.

GitHub Discussions Self-host guide