Skip to main content

​
Prerequisites

Before you begin, make sure you have the following installed and available:
1

Clone the repository and install dependencies

Clone the repo and install all dependencies with pnpm:
git clone https://github.com/VolvoxLLC/volvox-bot.git
cd volvox-bot
pnpm install
2

Copy the environment file

Copy the example environment file and open it for editing:
cp .env.example .env
Fill in the required values. The table below describes every variable:Required variables
VariableDescription
DISCORD_TOKENYour Discord bot token
DISCORD_CLIENT_IDYour Discord application/client ID
ANTHROPIC_API_KEYAnthropic API key for Claude
DATABASE_URLPostgreSQL connection string, e.g. postgresql://postgres:postgres@localhost:5432/volvoxbot
SESSION_SECRETSecret for JWT signing — generate with openssl rand -base64 32
Optional but recommended
VariableDescriptionDefault
REDIS_URLRedis connection stringin-memory fallback
BOT_API_SECRETShared secret for bot ↔ dashboard API auth—
LOG_LEVELLogging level (debug, info, warn, error)info
SENTRY_DSNSentry error tracking DSNdisabled
MEM0_API_KEYmem0 API key for long-term user memorydisabled
Web dashboard variables (required only if running the dashboard)
VariableDescription
NEXTAUTH_URLDashboard canonical URL, e.g. http://localhost:3000
NEXTAUTH_SECRETNextAuth.js JWT encryption secret — generate with openssl rand -base64 32
DISCORD_CLIENT_SECRETDiscord OAuth2 client secret
BOT_API_URLURL the dashboard uses to reach the bot API
DASHBOARD_URLDashboard URL for CORS origin
NEXT_PUBLIC_DISCORD_CLIENT_IDDiscord client ID exposed to the browser
If you are using Docker Compose, DATABASE_URL, REDIS_URL, NEXTAUTH_URL, and BOT_API_URL are overridden automatically by the compose file. You only need to set the secrets and Discord credentials.
3

Edit config.json

Open config.json at the project root and update it to match your Discord server. At minimum, set your bot owner ID in permissions.botOwners so you have full access:
{
  "permissions": {
    "botOwners": ["YOUR_DISCORD_USER_ID"]
  }
}
The default config.json ships with the upstream maintainer’s Discord user ID in permissions.botOwners. Replace it with your own ID before running the bot, or anyone with that ID will have full owner-level access to your server’s bot.
Other key sections you may want to review:
  • ai — enable AI chat, set channel blocklists, configure conversation history length
  • welcome — set a welcome channel ID and message template
  • moderation — configure the alert channel and protected roles
  • triage — adjust the AI triage model, daily budget, and keyword triggers
All settings in config.json can also be changed at runtime using the /config slash command or the web dashboard.
4

Set up your Discord application

If you haven’t already configured your bot in the Discord developer portal, follow these steps:
  1. Go to discord.com/developers/applications and open your application.
  2. Navigate to Bot and copy your bot token into DISCORD_TOKEN in your .env.
  3. Under Privileged Gateway Intents, enable all four intents:
    • Message Content Intent
    • Server Members Intent
    • Guild Voice States Intent (listed as Presence Intent in the portal)
    • Guild Message Reactions Intent
  4. Navigate to OAuth2 → URL Generator and select the following:
    • Scopes: bot, applications.commands
    • Bot permissions: View Channels, Send Messages, Read Message History, Manage Messages, Add Reactions, Manage Roles
  5. Copy the generated URL and use it to invite the bot to your server.
All four privileged intents are required. Missing any one of them will prevent features like welcome messages, reaction roles, and AI chat from working correctly.
5

Run database migrations

Apply all pending migrations to set up the database schema:
pnpm migrate
This runs node-pg-migrate up against the DATABASE_URL in your .env. Make sure PostgreSQL is running and the database exists before running this command.
Using Docker Compose? Run docker compose up -d db first to start the database, then run pnpm migrate from your host.
6

Deploy slash commands to Discord

Register all slash commands with the Discord API:
pnpm deploy
This reads DISCORD_TOKEN and DISCORD_CLIENT_ID from your .env and deploys commands globally. Global command propagation can take up to an hour.For faster iteration during development, deploy to a single guild instead:
pnpm deploy -- --guild-id YOUR_GUILD_ID
Guild-scoped commands update instantly.
7

Start the bot

Start Volvox.Bot:
pnpm start
Once running, you should see log output confirming the database connection, configuration load, and Discord login. Mention the bot in any channel to verify AI chat is working.
The bot exposes a REST API and WebSocket server on port 3001 (or BOT_API_PORT if set). The /api/v1/health endpoint returns the bot’s health status.

​
What’s next

Configuration

Explore all configuration options and learn how to update settings at runtime.

AI chat

Learn how AI chat works, how to manage conversation history, and how to configure channel blocklists.

Dashboard

Set up the Next.js web dashboard for analytics, audit logs, and live configuration.

Build docs developers (and LLMs) love

Get started for freeTalk to us