Environment Variables

BotBox supports two main ways to manage your Discord bot’s environment variables:

• .env file (default, simple)
• Doppler (advanced, for teams or secret management)

Using a .env File

When you choose .env during project setup, BotBox generates a .env file in your project root.

Example:

DISCORD_TOKEN=your-bot-token-here
DISCORD_GUILD=your-guild-id-here
ENVIRONMENTS=production,development
LOG_LEVEL=INFO
LOG_DIR=logs

Your bot will load these automatically at runtime.

The generated .gitignore already ignores .env, so keep every secret in this file rather than in your source.

Using Doppler

If you select Doppler during setup, BotBox generates a doppler.yaml for Doppler CLI integration.

• Make sure you have Doppler CLI installed.
• Set up your Doppler project and environment with the required secrets.

Example Doppler secrets:

• DISCORD_TOKEN
• DISCORD_GUILD
• ENVIRONMENTS

Run your bot with:

doppler run -- python3 src/main.py

Or just use the provided run.sh script.

The ENVIRONMENTS Variable

ENVIRONMENTS is a required, comma-separated list that defines the current scope of your bot (e.g., development, production).

• Purpose:
  Controls which cogs are loaded based on their env field in botbox.conf.
• Example values:

  • ENVIRONMENTS=development,production (for local testing)
  • ENVIRONMENTS=production (for deployment)

How it works:

• Cogs with an env matching any value in ENVIRONMENTS will be loaded.
• This allows you to have dev-only cogs, or hide unfinished features in production.

Accessing Variables in Code

Your bot’s Python code uses python-dotenv to load environment variables:

import os
from dotenv import load_dotenv

load_dotenv()
token = os.getenv("DISCORD_TOKEN")
guild = os.getenv("DISCORD_GUILD")
environments = os.getenv("ENVIRONMENTS", "production").split(",")

Logging Variables

src/utils/logger.py reads two optional variables at startup.

• LOG_LEVEL — Log level name passed to the root logger (DEBUG, INFO, WARNING, ERROR, CRITICAL). Defaults to INFO, and an unrecognized value falls back to INFO.
• LOG_DIR — Directory for bot.log. Defaults to logs, and the directory is created if it does not exist.

Logs are written to a rotating file handler (5 MB per file, 5 backups) and to stdout at the same time. discord.py itself is pinned to WARNING so its startup chatter stays out of your logs.

Required Variables

• DISCORD_TOKEN — Your bot’s token (required)
• DISCORD_GUILD — Your Discord server (guild) ID (required for guild-scoped commands)
• ENVIRONMENTS — Comma-separated list of environments (required)

Optional Variables

• LOG_LEVEL — Log level, defaults to INFO
• LOG_DIR — Log directory, defaults to logs

Next Steps

• Headless Mode
• Troubleshooting