kythia.config.js Reference

A complete, super-detailed reference for every setting in kythia.config.js — what it does, how to get it, and what to set it to.

The kythia.config.js file is the master control file for your entire bot. It controls its identity, features, behavior, and integrations. It is loaded at startup and injected throughout the bot via the dependency container.

To get started: Copy example.kythia.config.js → rename it to kythia.config.js.

Type: string | Default: 'local'

Describes the environment the bot is running in. This is informational only — it shows in log output but does not change bot behavior.

env: 'local', // Use 'production' for your live VPS bot

Auto-managed. Do not change.

Automatically reads the version from package.json. This is shown in the /about command and log output.

version: require('./package.json').version,

Your Kythia license key, read from .env. Do not hardcode the key value here.

licenseKey: process.env.LICENSE_KEY,

Set LICENSE_KEY=your_key_here in your .env file.

The bot refuses to start if either value is false. This is intentional — you must consciously accept both before running.

legal: {
  acceptTOS: true,       // ⚠️ MUST be true — Accept Terms of Service
  dataCollection: true,  // ⚠️ MUST be true — Accept anonymous telemetry
},

Defines who has superuser (owner) access to the bot. Owners can use owner-only commands, bypass all cooldowns (if ownerSkipCooldown is enabled), and interact with the AI using bypass filters.

owner: {
  ids: '1158654757183959091',   // Your Discord User ID
  names: 'kenndeclouv',        // Your display name
},

How to get your Discord User ID:

Optional. Enables automatic error tracking via Sentry. Unhandled exceptions will be reported to your Sentry dashboard. If SENTRY_DSN is empty, this has no effect.

sentry: {
  dsn: process.env.SENTRY_DSN,
},

How to get your Sentry DSN:

This section controls your bot's core Discord identity and behavior.

bot: {
  name: 'Kythia',
  token: process.env.DISCORD_BOT_TOKEN,
  clientId: process.env.DISCORD_BOT_CLIENT_ID,
  clientSecret: process.env.DISCORD_BOT_CLIENT_SECRET,
  totalShards: 'auto',
  mainGuildId: '',
  devGuildId: '',
  color: '#FFFFFF',
  prefixes: ['!', 'k!'],
  status: 'online',
  activityType: 'Playing',
  activity: 'join support https://dsc.gg/kythia',
  globalCommandCooldown: 5,
  language: 'en',
  locale: 'en-US',
  timezone: 'Asia/Jakarta',
},

Type: string

The bot's internal name, shown in log headers, embeds, and the /about command.

Type: string (from .env)

Your Discord bot token. This is the most sensitive value — never share it or commit it to Git.

How to get your bot token:

Type: string (from .env)

Your Discord application's Client ID (also called Application ID). Used to register slash commands and generate invite links.

How to get it:

Type: string (from .env)

Your Discord application's Client Secret. Only required if you are using the Dashboard (OAuth2 login).

How to get it:

Type: 'auto' | number | Default: 'auto'

Controls how many shards the bot runs. Discord requires sharding for bots in 2,500+ servers.

Type: string

The ID of your main/support Discord server. Used internally for guild-specific features and logging.

How to get it: Right-click your server name in Discord → Copy Server ID (requires Developer Mode enabled).

Type: string

The ID of your development/testing Discord server. Slash commands deployed to a specific guild appear instantly, unlike global commands which can take up to 1 hour to propagate.

Type: string (hex color) | Default: '#FFFFFF'

The embed accent color used across all bot messages and the ContainerBuilder interface.

color: '#F6B1CE', // Pink — change to your branding color

Type: string[] | Default: ['!', 'k!']

List of text command prefixes. Users can type !ping or k!ping to trigger prefix commands.

prefixes: ['!', 'k!'], // Add or remove prefixes as needed

Type: 'online' | 'idle' | 'dnd' | 'invisible' | Default: 'online'

The bot's presence status shown in Discord.

Type: string | Default: 'Playing'

The type of activity shown in the bot's status.

Type: string

The text shown in the bot's Discord status next to the activity type.

activity: 'join support https://dsc.gg/kythia',

Type: number (seconds) | Default: 5

The minimum number of seconds a user must wait between any two command uses. This is a global anti-spam cooldown applied to all commands.

Type: string | Default: 'en'

The default language for bot responses. Currently supported: 'en' (English), 'id' (Indonesian).

Type: string | Default: 'en-US'

Used for formatting numbers, dates, and currencies. Must be a valid BCP 47 locale tag.

Examples: 'en-US', 'id-ID', 'ja-JP'

Type: string | Default: 'Asia/Jakarta'

The IANA timezone string used for all time-based features (schedulers, daily resets, cron jobs). Should match your VPS/server's timezone for consistency.

Find your timezone: Wikipedia TZ Database List

Examples: 'Asia/Jakarta', 'America/New_York', 'Europe/London', 'UTC'

db: {
  driver: process.env.DB_DRIVER,
  host: process.env.DB_HOST,
  port: process.env.DB_PORT,
  name: process.env.DB_NAME,
  user: process.env.DB_USER,
  pass: process.env.DB_PASSWORD,
  storagePath: process.env.DB_STORAGE_PATH,
  socketPath: process.env.DB_SOCKET_PATH,
  dialectOptions: process.env.DB_DIALECT_OPTIONS,
  timezone: '+07:00',
  useRedis: true,
  redis: process.env.REDIS_URLS,
  redisCacheVersion: 'v1.0',
},

The database engine to use. Set DB_DRIVER in your .env.

Standard database connection credentials. All read from .env.

SQLite only. Path to the .sqlite file on disk.

DB_STORAGE_PATH=./kythia.sqlite

MySQL / MariaDB / Cloud SQL only. Path to the Unix socket used instead of TCP connections. Common with Google Cloud SQL.

DB_SOCKET_PATH=/var/run/mysqld/mysqld.sock

MSSQL only. Extra driver options passed as a JSON string.

Type: string (UTC offset) | Default: '+07:00'

The timezone offset for the database connection. This controls how the database driver interprets DATETIME values. Use '+00:00' for UTC.

Type: boolean | Default: true

Enables Redis as the caching layer. Strongly recommended. Some features (global chat, high-frequency lookups) may not work correctly without Redis.

Type: string (from .env) — comma-separated Redis URLs.

REDIS_URLS=redis://localhost:6379
# Multiple nodes:
REDIS_URLS=redis://localhost:6379,redis://localhost:6380

How to set up Redis:

sudo apt install redis-server
sudo systemctl enable --now redis

docker run -d --name redis -p 6379:6379 redis:latest

Type: string | Default: 'v1.0'

A version tag appended to all Redis cache keys. Changing this value (e.g., from 'v1.0' to 'v1.1') invalidates all existing cached data on restart without touching the database.

All bot features are packaged as addons. Every addon has an active toggle. Disabled addons are never loaded — their commands, events, and memory footprint are completely removed.

addons: {
  all: {
    active: true, // Set to false to disable ALL addons at once (useful for debugging)
  },
}

adventure: { active: true },

Enables the full text-based RPG system: character creation, dungeon battles, monster encounters, inventory management, and the in-game shop.

Commands enabled: /adventure battle, /adventure inventory, /adventure profile, /adventure recall, /adventure shop, /adventure start, /adventure use

Enables AI-powered chat using Google's Gemini models.

ai: {
  active: true,
  model: 'gemini-2.5-flash',
  geminiApiKeys: process.env.GEMINI_API_KEYS,
  getMessageHistoryLength: 4,
  perMinuteAiLimit: 10,
  safeCommands: ['ping', 'avatar'],
  additionalCommandKeywords: ['setting', 'musik', 'latency'],
  personaPrompt: `You are Kythia, a friendly Discord assistant. Your creator is kenndeclouv.`,
  defaultPersonality: 'friendly',
  ownerInteractionPrompt: `kenndeclouv is your developer.`,
  dailyGreeter: false,
  dailyGreeterSchedule: '0 7 * * *',
  dailyGreeterPrompt: `Make a warm greeting for the members.`,
  ownerBypassFilter: true,
},

The Gemini model to use. See full model list.

Comma-separated list of Gemini API keys. Multiple keys are used in round-robin rotation to spread requests and avoid per-key rate limits.

How to get Gemini API Keys:

How many recent messages (before the user's message) to include as context for the AI. Higher values = better context, higher token usage.

Max AI requests per minute across all users. Tune this based on your Gemini plan's rate limits.

The system prompt that defines Kythia's personality. Customize this to fit your bot's character. Keep it concise.

personaPrompt: `You are Kythia, a friendly and helpful Discord bot. You are cheerful and love helping users. Your creator is kenndeclouv.`,

Default personality mode for new users. Users can change their own with /ai personality.

Set to true to have the AI automatically send a morning greeting to configured channels.

Cron expression for when the greeting is sent. Uses crontab format.

dailyGreeterSchedule: '0 7 * * *', // Every day at 7:00 AM (server timezone)

When true, the bot owner can use the AI without content safety filtering.

checklist: { active: true },

Provides admin commands to create and manage interactive server setup checklists.

core: {
  active: true,                                        // ❗ Do NOT disable
  exchangerateApi: process.env.EXCHANGERATE_API,        // For /currency command
},

Contains all essential utility commands: /ping, /stats, /help, /settings, /language, /about.

How to get ExchangeRate API key:

economy: {
  active: true,
  dailyCooldown: 86400,    // 1 day    — /eco daily
  begCooldown: 3600,       // 1 hour   — /eco beg
  lootboxCooldown: 14400,  // 4 hours  — /eco lootbox
  workCooldown: 28800,     // 8 hours  — /eco work
  robCooldown: 7200,       // 2 hours  — /eco rob
  hackCooldown: 3600,      // 1 hour   — /eco hack
},

All cooldown values are in seconds. Here's a quick reference:

api: {
  active: true,
  url: process.env.API_URL,
  port: process.env.API_PORT || 3000,
  secret: process.env.API_SECRET,
},

Enables the bot's built-in API server and web dashboard integration.

fun: {
  active: true,
  wordle: {
    words: ['apple', 'grape', 'lemon', 'mango', 'peach', 'berry', 'melon', 'guava'],
  },
},

The word pool for /fun wordle. All words must be exactly 5 letters. Users won't know which words are in the list.

giveaway: {
  active: true,
  checkInterval: 20, // Seconds between giveaway end checks
},

How often (in seconds) the bot checks whether any active giveaways have ended. Lower = more responsive, but slightly more CPU usage. 20 is a good balance.

globalchat: {
  enabled: false,
  apiUrl: process.env.GLOBAL_CHAT_API_URL,
  apiKey: process.env.GLOBAL_CHAT_API_KEY,
  healthCheckSchedule: '*/30 * * * *',
  healthCheckDelay: 1000,
},

globalvoice: {
  active: false,
  apiUrl: process.env.GLOBAL_VOICE_API_URL,
  apiKey: process.env.GLOBAL_VOICE_API_KEY,
},

invite: { active: true },

Tracks which Discord invite link was used when a new member joins. Enables /invite commands to view invite leaderboards and stats.

image: {
  active: false,
  storageUrl: process.env.KYTHIA_IMAGE_STORAGE_URL,
  apiKey: process.env.KYTHIA_IMAGE_STROAGE_API_KEY,
},

leveling: {
  active: true,
  backgroundUrl: 'https://placehold.co/800x250.png',
},

The background image for the /rank card. Replace the placeholder with your own hosted image.

• Recommended size: 800 × 250 px
• Format: PNG or JPG
• Host on: Cloudflare Images, ImageKit, Imgur (permanent link), or your own CDN

music: {
  active: true,
  defaultPlatform: 'ytsearch',
  useAI: true,
  playlistLimit: 3,
  autocompleteLimit: 5,
  suggestionLimit: 7,
  lavalink: {
    hosts: process.env.LAVALINK_HOSTS || 'localhost',
    ports: process.env.LAVALINK_PORTS || '2333',
    passwords: process.env.LAVALINK_PASSWORDS || 'youshallnotpass',
    secures: process.env.LAVALINK_SECURES || 'false',
  },
  spotify: {
    clientId: process.env.SPOTIFY_CLIENT_ID,
    clientSecret: process.env.SPOTIFY_CLIENT_SECRET,
  },
  artworkUrlStyle: 'banner',
},

The source used when a user searches by text (not a URL).

Max number of custom playlists a user can save.

Number of results shown in /music play autocomplete dropdown.

Number of related songs shown on the Now Playing embed.

How the song artwork is displayed.

Lavalink is a separate audio server that handles all music streaming. You must run at least one Lavalink node.

Required Lavalink plugins:

• lavasrc-plugin — Spotify, Apple Music, Deezer support
• youtube-plugin — YouTube streaming
• lavasearch-plugin — Search autocomplete
• sponsorblock-plugin — Skip sponsored segments

For multiple Lavalink nodes, use comma-separated values:

LAVALINK_HOSTS=node1.example.com,node2.example.com
LAVALINK_PORTS=2333,2334
LAVALINK_PASSWORDS=pass1,pass2
LAVALINK_SECURES=false,true

How to get Spotify API credentials:

SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret

pet: {
  active: true,
  useCooldown: 28800,   // 8 hours — how often users can interact with their pet
  gachaCooldown: 3600,  // 1 hour  — how often users can pull the pet gacha
},

Allows users to claim their own subdomains (e.g., username.kyth.me) via bot commands.

pro: {
  active: false,
  cloudflare: {
    token: process.env.CLOUDFLARE_API_TOKEN,
    zoneId: process.env.CLOUDFLARE_ZONE_ID,
    domain: process.env.CLOUDFLARE_DOMAIN,
  },
  maxSubdomains: 5,
},

How to set up Cloudflare:

CLOUDFLARE_API_TOKEN=your_token
CLOUDFLARE_ZONE_ID=your_zone_id
CLOUDFLARE_DOMAIN=kyth.me

server: { active: true },

Enables /server autobuild, /server backup, /server restore, and other server structure tools.

streak: { active: true },

Tracks users' daily activity streaks. Users who interact every day maintain their streak.

suggestion: { active: true },

Enables the /suggest command, letting users submit suggestions to a configured channel with upvote/downvote reactions.

ticket: { active: true },

Enables the full ticket system: panel creation, private ticket channels, transcript export, and staff assignment.

quest: {
  active: false,
  scheduler: '*/30 * * * *',
  apiUrls: 'http://.../quests,http://...',
},

This is a separate api key at the root config level (outside of addons). It configures Discord webhooks and Top.gg vote tracking.

api: {
  webhookGuildInviteLeave: process.env.WEBHOOK_GUILD_INVITE_LEAVE,
  webhookErrorLogs: process.env.WEBHOOK_ERROR_LOGS,
  topgg: {
    authToken: process.env.TOPGG_AUTH_TOKEN,
    apiKey: process.env.TOPGG_API_KEY,
  },
  webhookVoteLogs: process.env.WEBHOOK_VOTE_LOGS,
},

How to create a Discord Webhook:

logConsoleFilter: 'all',   // 'all' or e.g. 'warn,error,info,debug'
logFormat: 'HH:mm:ss',    // Timestamp format — see: https://date-fns.org/v4.1.0/docs/format

supportServer: 'https://dsc.gg/kythia',
inviteLink: `https://discord.com/oauth2/authorize?client_id=${process.env.DISCORD_BOT_CLIENT_ID}&scope=bot%20applications.commands&permissions=8`,
ownerWeb: 'https://kenndeclouv.me',
kythiaWeb: 'https://kythia.me',
statusPage: 'https://status.kythia.my.id',

All banners default to placeholder images. Replace with your own hosted URLs.

• Recommended size: 800 × 300 px
• Host on: Cloudflare Images, ImageKit, or any public CDN

webhookErrorLogs: false,         // true = send errors to the error logs webhook
webhookGuildInviteLeave: true,   // true = notify when bot joins/leaves a server

ownerSkipCooldown: true, // Bot owner bypasses all command cooldowns (economy, pet, etc.)

These values control Kythia's built-in AutoMod detection engine.

All button emojis used by the bot's interactive components. You can use:

• Default Unicode emoji: '▶️'
• Custom server emoji: '<:name:id>'

How to get a custom emoji ID: Type \:emojiname: in any Discord message and send it. The raw format <:name:id> will appear.

emojis: {
  music: {
    playPause: '⏯️',
    play: '▶️',
    pause: '⏸️',
    skip: '⏭️',
    stop: '⏹️',
    loop: '🔁',
    autoplay: '🎶',
    lyrics: '📝',
    queue: '📜',
    shuffle: '🔀',
    filter: '🎚️',
    favorite: '❤️',
    back: '⏮️',
  },

  tempvoice: {
    rename: '⌨️',
    limit: '👥',
    privacy: '🛡️',
    waiting: '⏲️',
    stage: '🎙️',
    trust: '🤝',
    untrust: '✂️',
    invite: '📞',
    kick: '👢',
    region: '🌐',
    block: '🚫',
    unblock: '🟢',
    claim: '👑',
    transfer: '🔁',
    delete: '🗑️',
  },
},