Skip to main content

​
Prerequisites

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

Node.js 22+

Volvox.Bot requires Node.js 22 or later.

pnpm

Install with npm install -g pnpm.

PostgreSQL 17+

Required for all bot state and configuration.

Redis 7+

Recommended for caching, rate limiting, and session storage. The bot runs without it but performance degrades.

Anthropic API key

Required for all AI features (chat, moderation, triage).

Discord application

A Discord bot token and application with the correct intents enabled.

​
Step-by-step setup

1

Clone and install

Clone the repository and install all dependencies:
git clone https://github.com/VolvoxLLC/volvox-bot.git
cd volvox-bot
pnpm install
The repository is a pnpm workspace that includes both the bot (/) and the web dashboard (web/).
2

Configure environment variables

Copy the example environment file and fill in your values:
cp .env.example .env
Open .env in your editor. At minimum, set the three required variables:
DISCORD_TOKEN=your_discord_bot_token
ANTHROPIC_API_KEY=your_anthropic_api_key
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/volvoxbot
See the environment variables reference below for all options.
3

Configure the bot

Edit config.json in the repository root to match your Discord server. Key sections include:
  • ai — AI chat settings, feedback, and channel blocklist
  • aiAutoMod — Auto-moderation thresholds and actions
  • triage — Message triage and daily budget
  • welcome — Welcome messages with template variables
  • moderation — Moderation features and protected roles
  • backup — Auto-backup schedule and retention
  • performance — Monitoring thresholds and alerting
You can also update config.json at runtime via the /config slash command or the web dashboard.
4

Set up your Discord bot

  1. Go to the Discord Developer Portal and create a new application.
  2. Navigate to Bot → Add Bot and copy the token into DISCORD_TOKEN.
  3. Under Privileged Gateway Intents, enable all four:
    • Message Content Intent
    • Server Members Intent
    • Guild Voice States Intent (for voice tracking)
    • Guild Message Reactions Intent (for reaction roles and AI feedback)
  4. Navigate to OAuth2 → URL Generator and select these scopes: bot, applications.commands.
  5. Under Bot Permissions, select at minimum:
    • View Channels
    • Send Messages
    • Read Message History
    • Manage Messages
    • Add Reactions
    • Manage Roles
  6. Copy the generated URL and use it to invite the bot to your server.
  7. Copy the Client ID from OAuth2 → General into DISCORD_CLIENT_ID.
5

Run database migrations

Apply all pending schema migrations:
pnpm migrate
This runs node-pg-migrate up against the DATABASE_URL in your .env. The bot also runs migrations automatically on startup, so this step is optional but recommended to verify your database connection before starting.See the database guide for details on all migrations and rollback procedures.
6

Deploy slash commands

Register all slash commands with Discord:
pnpm deploy
This pushes commands globally. For development, you can scope deployment to a single guild for instant propagation:
pnpm deploy -- --guild-id YOUR_GUILD_ID
Global command registration can take up to one hour to propagate across all Discord clients. Guild-scoped commands are available immediately.
7

Start the bot

pnpm start
The bot starts, applies any pending migrations, connects to Discord, and begins listening for events. You should see log output confirming the database connection and Discord login.

​
Environment variables

​
Required

VariableDescription
DISCORD_TOKENDiscord bot token from the Developer Portal
DISCORD_CLIENT_IDDiscord application/client ID for slash command deployment
ANTHROPIC_API_KEYAnthropic API key for Claude (AI chat, moderation, triage)
DATABASE_URLPostgreSQL connection string, e.g. postgresql://user:pass@host:5432/dbname
VariableDescriptionDefault
REDIS_URLRedis connection string for caching and rate limiting(disabled)
SESSION_SECRETSecret for JWT signing — generate with openssl rand -base64 32(required for OAuth2)

​
Web dashboard

VariableDescription
NEXTAUTH_URLThe canonical URL of the dashboard, e.g. http://localhost:3000
NEXTAUTH_SECRETJWT encryption secret — generate with openssl rand -base64 32
DISCORD_CLIENT_SECRETDiscord OAuth2 client secret
DISCORD_REDIRECT_URIDiscord OAuth2 redirect URI, e.g. http://localhost:3001/api/v1/auth/discord/callback
BOT_API_SECRETShared secret for bot ↔ dashboard API authentication
BOT_API_URLURL the dashboard uses to reach the bot API, e.g. http://localhost:3001
DASHBOARD_URLURL of the dashboard for CORS origin, e.g. http://localhost:3000
NEXT_PUBLIC_DISCORD_CLIENT_IDDiscord client ID exposed to the browser

​
Optional

VariableDescriptionDefault
BOT_API_PORTPort for the bot’s REST API3001
BOT_OWNER_IDSComma-separated Discord user IDs that bypass all permission checks(from config.json)
PG_POOL_SIZEPostgreSQL connection pool size5
DATABASE_SSLSSL mode: false, no-verify, or trueAuto-detected
MEM0_API_KEYmem0 API key for long-term user memory (optional feature)(disabled)
WEBHOOK_SECRETHMAC signing secret for outbound webhook notifications(disabled)
SENTRY_DSNSentry DSN for error tracking(disabled)
LOG_LEVELLogging level: debug, info, warn, errorinfo

​
Running in production

Start the bot with: 
pnpm start
This runs node src/index.js directly. For production deployments, consider using a process manager like PM2 to handle restarts and log rotation: 
npm install -g pm2
pm2 start src/index.js --name volvox-bot
pm2 save
pm2 startup
For containerized deployments, see the Docker guide.

​
Running the web dashboard

The web dashboard is a separate Next.js application in the web/ directory. It requires its own environment variables in addition to the root .env.
1

Configure the dashboard

Copy and fill the dashboard-specific env file:
cp web/.env.example web/.env
Set these variables:
DISCORD_CLIENT_ID=your_discord_client_id
DISCORD_CLIENT_SECRET=your_discord_client_secret
NEXTAUTH_SECRET=your_nextauth_secret
NEXTAUTH_URL=http://localhost:3000
BOT_API_URL=http://localhost:3001
BOT_API_SECRET=your_bot_api_secret
NEXT_PUBLIC_DISCORD_CLIENT_ID=your_discord_client_id
2

Run both services together

From the repository root, run all services in parallel using Turborepo:
pnpm mono:dev
Or run them separately in two terminals:
# Terminal 1 — bot
pnpm start

# Terminal 2 — dashboard
pnpm --filter web dev
The bot must be running for the dashboard to fetch guild configuration. Set BOT_API_URL to the bot’s API address so the dashboard can communicate with it.

Build docs developers (and LLMs) love

Get started for freeTalk to us