Configuration

Mumimo reads its settings from a TOML config file, environment variables, and CLI arguments. On the very first run a default config.toml is copied from the bundled template into the data directory.

Precedence

Settings are resolved in the following order — highest wins:

CLI arguments (e.g. --ip, --port)
Environment variables (e.g. MUMBLE_IP)
Config file (config.toml)
Built-in defaults

Config File Location

The config file defaults to data/config.toml relative to the working directory. You can override this with --config <path> or the MUMIMO_CONFIG_FILE environment variable.

`[connection]` — Connection Settings

Key	Type	Default	Env Var	Description
`user_id`	string	`"Mumimo"`	`MUMIMO_USER_ID`	Bot’s Mumble username
`user_cert`	string	`""`	`MUMIMO_USER_CERT`	Path to user certificate
`auto_reconnect`	bool	`false`	`MUMIMO_AUTO_RECONNECT`	Reconnect automatically on disconnect
`default_channel`	string	`"Root"`	`MUMIMO_DEFAULT_CHANNEL`	Channel to join on connect
`default_admin`	string	`""`	`MUMIMO_DEFAULT_ADMIN`	Default admin username
`self_register`	bool	`false`	`MUMIMO_SELF_REGISTER`	Self-register with the Mumble server
`default_comment`	string	`"Hello! I am Mumimo!"`	`MUMIMO_DEFAULT_COMMENT`	Bot’s user comment shown in client
`server_ip`	string	`""`	`MUMBLE_IP`	Server IP address (usually via `--ip`)
`server_port`	string	`"64738"`	`MUMBLE_PORT`	Server port
`server_password`	string	`""`	`MUMBLE_PASSWORD`	Server password

`[main]` — Core Settings

Key	Type	Default	Env Var	Description
`enable_database_integrity_check`	bool	`true`	`MUMIMO_DB_INTEGRITY`	Run DB integrity check on boot
`enable_database_backup`	bool	`false`	`MUMIMO_DB_BACKUP`	Auto-backup database on boot
`command_tick_rate`	float	`0.1`	`MUMIMO_CMD_TICK_RATE`	Seconds between command-poll cycles
`multi_command_limit`	int	`200`	`MUMIMO_MULTI_CMD_LIMIT`	Max commands in a single pipe chain
`command_token`	string	`"!"`	`MUMIMO_CMD_TOKEN`	Command prefix character
`command_queue_limit`	int	`600`	`MUMIMO_CMD_QUEUE_LIMIT`	Max items in the command queue
`command_history_limit`	int	`25`	`MUMIMO_CMD_HIST_LIMIT`	Max history entries per user
`default_timezone`	string	`""`	`MUMIMO_DEFAULT_TZ`	Log timezone (empty = system default)

`[media]` — Audio Settings

Key	Type	Default	Env Var	Description
`ffmpeg_path`	string	`"ffmpeg"`	`MUMIMO_FFMPEG_PATH`	Path to the ffmpeg binary
`use_stereo_audio`	bool	`true`	`MUMIMO_USE_STEREO`	Output stereo audio
`audio_lib_quiet`	bool	`true`	`MUMIMO_AUDIO_LIB_QUIET`	Suppress audio-library log output
`default_volume`	float	`0.1`	`MUMIMO_DEFAULT_VOLUME`	Default playback volume (0.0–1.0)
`use_audio_duck`	bool	`false`	`MUMIMO_USE_AUDIO_DUCK`	Enable volume ducking on startup
`ducking_volume`	float	`0.02`	`MUMIMO_DUCKING_VOLUME`	Volume level while ducked
`ducking_threshold`	float	`2500.0`	`MUMIMO_DUCKING_THRESHOLD`	RMS threshold to trigger ducking
`ducking_start_delay`	float	`1.0`	`MUMIMO_DUCKING_START_DELAY`	Seconds before ducking engages
`ducking_end_delay`	float	`1.0`	`MUMIMO_DUCKING_END_DELAY`	Seconds before volume restores
`max_queue_length`	int	`50`	`MUMIMO_MAX_QUEUE_LENGTH`	Maximum tracks in the audio queue
`youtube_dl_proxy_url`	string	`""`	`MUMIMO_YTDL_PROXY`	Proxy URL for yt-dlp
`youtube_dl_cookie_file`	string	`""`	`MUMIMO_YTDL_COOKIE`	Cookie file for yt-dlp
`youtube_dl_js_runtimes`	list[str]	`["node"]`	`MUMIMO_YTDL_JS_RUNTIMES`	JS runtimes for yt-dlp extractors
`youtube_dl_remote_components`	list[str]	`["ejs:github"]`	`MUMIMO_YTDL_REMOTE_COMPONENTS`	Remote components for yt-dlp

`[pgui]` — GUI & Theme Settings

Key	Type	Default	Env Var	Description
`canvas_bg_color`	string	`"black"`	`MUMIMO_CANVAS_BG`	Canvas background colour
`canvas_img_bg_color`	string	`"black"`	`MUMIMO_CANVAS_IMG_BG`	Image background colour
`canvas_alignment`	string	`"center"`	`MUMIMO_CANVAS_ALIGN`	Text alignment on canvas
`canvas_border`	int	`0`	`MUMIMO_CANVAS_BORDER`	Border width in pixels
`canvas_text_color`	string	`"Snow"`	`MUMIMO_CANVAS_TEXT_COLOR`	Default text colour
`default_font`	string	`"Georgia"`	`MUMIMO_DEFAULT_FONT`	Default font family
`header_text_color`	string	`"red"`	`MUMIMO_HEADER_TEXT_COLOR`	Header text colour
`index_text_color`	string	`"cyan"`	`MUMIMO_INDEX_TEXT_COLOR`	Index text colour
`subheader_text_color`	string	`"yellow"`	`MUMIMO_SUBHEADER_TEXT_COLOR`	Subheader text colour
`theme`	string	`"default"`	`MUMIMO_THEME`	Active theme name

`[plugin]` — Plugin Settings

Key	Type	Default	Env Var	Description
`disabled_plugins`	list[str]	`[]`	`MUMIMO_DISABLED_PLUGINS`	Plugins that should never be loaded
`safe_mode_plugins`	list[str]	`["core_commands", "bot_commands"]`	`MUMIMO_SAFE_MODE_PLUGINS`	Plugins loaded when `--safe` is used
`allowed_root_channels`	list[str]	`["Root"]`	`MUMIMO_ALLOWED_CHANNELS`	Channels the bot is allowed to join

`[logging]` — Logging Settings

Key	Type	Default	Env Var	Description
`enable_logging`	bool	`false`	`MUMIMO_ENABLE_LOGGING`	Enable writing logs to disk
`max_logs`	int	`20`	`MUMIMO_MAX_LOGS`	Maximum number of log files to keep
`max_log_size`	int	`1500000`	`MUMIMO_MAX_LOG_SIZE`	Maximum log file size in bytes
`hide_message_logging`	bool	`true`	`MUMIMO_HIDE_LOG_MESSAGES`	Suppress message content in logs
`log_stack_trace`	bool	`false`	`MUMIMO_LOG_STACK_TRACE`	Include full stack traces in logs

`[roles.<name>]` — Custom Roles

Define custom roles by adding a sub-table under [roles]. Each role needs a description field.

[roles.dj]
description = "Users allowed to manage the audio queue"

[roles.vip]
description = "VIP users with elevated access"

Four built-in roles always exist and do not need to be defined:

Role	Purpose
`blacklisted`	Completely blocked from running any commands
`admin`	Full access — bypasses all role gates
`moderator`	Elevated access for moderation commands
`user`	Default role for all unassigned users

`[command_overrides]` — Per-Command Role Overrides

Override the roles required for any command without editing plugin manifests. Keys follow the "plugin.command" format and values are lists of role names.

[command_overrides]
"audio_commands.play" = ["dj", "admin"]
"core_commands.quit" = ["admin"]

Plugin-Specific Sections

Any config section that does not match a known framework key is captured into config.custom and made available to plugins through the PluginContext.

`[ai_assistant]` — AI Assistant Plugin

The AI assistant plugin reads its settings from [ai_assistant]. The most commonly-tuned keys are listed below:

Key	Type	Default	Description
`api_key`	str	`""`	OpenRouter API key (or use `api_key_env_var`)
`api_key_env_var`	str	`"OPENROUTER_API_KEY"`	Env var name holding the key (takes precedence over `api_key`)
`chat_model`	str	`"openai/gpt-4o-mini"`	OpenRouter chat model id
`voice_model`	str	`"google/gemini-3.1-flash-tts-preview"`	TTS model id
`voice_name`	str	`"Kore"`	Gemini voice name (30 voices available)
`transcribe_model`	str	`"openai/whisper-1"`	STT model for `!speak`
`enable_voice_output`	bool	`false`	Enable TTS voice output on startup
`function_calling`	bool	`true`	Allow model to call client-side tools
`karma_system`	bool	`true`	Enable karma rating system
`emotion_system`	bool	`true`	Enable emotion/mood tracking
`web_search`	bool	`false`	Enable OpenRouter server-side web search
`reasoning_effort`	str	`""`	Reasoning effort (`"low"`/`"medium"`/`"high"`, empty = disabled)
`context_compression`	bool	`false`	OpenRouter middle-out context compression
`history_max_turns`	int	`8`	Max conversation turns sent to the model
`reply_char_limit`	int	`2000`	Max chars of AI reply rendered in GUI (full reply still spoken via TTS)
`max_user_notes`	int	`50`	Max notes per user in the memory store
`max_global_notes`	int	`50`	Max global notes in the memory store

Consult each plugin’s documentation for its available configuration keys.

Configuration

Precedence

Config File Location

[connection] — Connection Settings

[main] — Core Settings

[media] — Audio Settings

[pgui] — GUI & Theme Settings

[plugin] — Plugin Settings

[logging] — Logging Settings

[roles.<name>] — Custom Roles

[command_overrides] — Per-Command Role Overrides