Configuration
Musebot is configured through JSON-based configuration files (config.json or config.jsonc). This is the modern, standardized configuration format with excellent IDE support (autocomplete, validation, formatting).
Note on Configuration Loading:
Musebot loads the configuration file from its current working directory at startup. Changes to this file will not take effect while the bot is running. You must restart the bot for any changes to be applied.
Migration Guides
- Upgrading from a pre-v10 release (Ollama-only config)? See the v10 LLM Migration Guide.
- Previously using
.envfiles withMUSEBOT_*environment variables? See the Migration Guide.
Core Configuration
nodeEnvironment
- Description: The operating environment for the Node.js runtime.
- Required: No
- Type:
String - Default:
production - Values:
production,development
mode
- Description: The core operating mode of the bot. This determines which integrations are active. If set to
chat, an LLM host must be configured. If set tomedia, ComfyUI/SwarmUI must be configured. - Required: Yes
- Type:
String - Values:
chat,media
Discord Configuration
chatApis.discord.token
- Description: The authentication token for your bot, obtained from the Discord Developer Portal.
- Required: Yes
- Type:
String
chatApis.discord.channels
- Description: An array of allowed channel IDs. The bot will only respond in these channels. If left empty, all channels are allowed.
- Required: No
- Type:
String[]
chatApis.discord.channelsDisallowed
- Description: An array of disallowed channel IDs. The bot will never respond in these channels, even if they are in
chatApis.discord.channels. - Required: No
- Type:
String[]
requiresMention
- Description: If
true, the bot will only respond when it is mentioned in a message (e.g.,@Musebot help). - Required: No
- Type:
Boolean - Default:
true - Values:
true,false
responseRate
- Description: If
requiresMentionisfalse, this sets the percentage chance (0-100) the bot will respond to a public message. A value of50means it responds to roughly half of the messages. - Required: No
- Type:
Integer - Default:
100 - Values:
1-100
discord.privateMessageUsers
- Description: An array of Discord usernames (case-sensitive!) who are allowed to send the bot private messages. Note: This is the username, not the display name.
- Required: No
- Type:
String[]
errorMessage
- Description: A custom message to display when a task (like media generation) fails. If not set, a generic error message is displayed.
- Required: No
- Type:
String - Default:
An error occurred while generating a response. Please try again later.
Chat Mode (LLM) Settings
Required if mode=chat
Musebot speaks the OpenAI-compatible protocol, so any compatible platform works — Ollama, llama.cpp's llama-server, and hosted APIs. See LLM Providers for a provider capability matrix, and the v10 Migration Guide if you're upgrading from an earlier release.
llm.hosts
Description: An array of your LLM backend host(s). Each entry is an object with a
url(required) and optionaltokenandisLocalfields. You can specify multiple hosts for load balancing. Bare-string hosts (as used before v10) are rejected at startup."llm": { "hosts": [ { "url": "http://localhost:11434/v1" }, { "url": "https://api.examplerator.com/v1", "token": "sk-...", "isLocal": false } ] }Required: Yes
Type:
Object[]({ "url": String, "token"?: String, "isLocal"?: Boolean })
llm.hosts[].url
- Description: The base URL of the LLM backend. It must include the full OpenAI-compatible base route (usually
/v1), e.g.http://localhost:11434/v1for Ollama. Musebot appends only the endpoint paths (/chat/completions,/embeddings) to the URL exactly as given; platform probe endpoints (/api/ps,/models,/props, ...) are always joined to the server root. - Required: Yes
- Type:
String
llm.hosts[].token
- Description: An optional API token for the host. When set, it is sent as an
Authorization: Bearer <token>header on every request to that host; when unset, no header is sent. Tokens live only inconfig.jsonc— never commit them. See ADR 003. - Required: No
- Type:
String
llm.hosts[].isLocal
- Description: Overrides Musebot's automatic local-host detection. When
true, the host gets model lifecycle management (on supported platforms); whenfalse, the host is treated as remote and its models are never unloaded. Automatic detection:localhost/127.*/::1are local; other hostnames are DNS-resolved and considered local when they resolve to an RFC 1918 address (10/8,172.16/12,192.168/16), the Tailscale CGNAT range (100.64/10), link-local (169.254/16), IPv6 unique-local (fc00::/7), or IPv6 link-local (fe80::/10). Unresolvable hostnames are conservatively treated as local. - Required: No
- Type:
Boolean
llm.models
Description: The LLM(s) to use. A random one will be selected for each request. Entries may be plain model-name strings, or objects that declare which inputs and outputs each model supports:
"llm": { "models": [ "gemma4-12b-qat", { "name": "gemma4-12b-qat", "inputModalities": ["text", "image"], "outputModalities": ["text"] } ] }Modality values are case-insensitive and may be
text,image,video, oraudio; both arrays default to["text"]when omitted. A model declared withimageinput enables the Vision feature directly; otherwise Musebot detects vision from the host (Ollama via/api/show, other hosts via their/modelscatalog when available). Configured modalities always win over host detection. See Vision for details.Required: No
Type:
Array<string | { name: String, inputModalities?: Modality[], outputModalities?: Modality[] }>
llm.systemPrompt
- Description: A custom system prompt to give the LLM a specific persona or context. The bot also automatically uses the current Discord channel's topic as part of its system prompt, so it's aware of the conversation's context. Can be either a string or an array of strings. If an array is provided, the entries are joined with newlines to form a single prompt — useful for breaking up large system prompts into legible sections.
- Required: No
- Type:
StringorString[]
llm.streamsResponse
- Description: If
true, the bot will stream the LLM's response token-by-token, appearing as if it's typing in real-time. This provides a more natural user experience but can be less stable. Note: This is an experimental feature. - Required: No
- Type:
Boolean - Default:
false - Values:
true,false
llm.embeddingModel
- Description: The name of a model to use for generating text embeddings. When set, long-term memory (LTM) is enabled — Musebot will store conversation messages as vector embeddings and retrieve relevant context from past conversations to augment the LLM's prompt. See Long-Term Memory for details.
- Required: No
- Type:
String - Default: (unset — LTM disabled)
llm.embeddingInputLimit
- Description: The chunk size in characters for embedding inputs (Musebot embeds serialized conversation rows for long-term memory). Inputs longer than the limit are split into chunks, each chunk is embedded separately, and the resulting chunk vectors are pooled (averaged) into a single stored embedding — inputs are never truncated. Retrieval for oversized inputs matches their overall gist rather than individual chunk precision. There is no standard way to query an embedding server's maximum input size, so keep this within limits your embedding server accepts for a single input. Only applies when
llm.embeddingModelis set. - Required: No
- Type:
Integer - Default:
2000
llm.topK
- Description: The number of similar memories to retrieve from the vector store when augmenting the LLM prompt. Only applies when
llm.embeddingModelis set. Higher values provide more context at the cost of prompt length and latency. - Required: No
- Type:
Integer - Default:
5
llm.contextWindow
- Description: The maximum context window (in tokens) for the LLM, used to decide when conversation context compression triggers. When unset, Musebot probes the host for the model's context length — Ollama via
/api/show, llama.cpp router and most other OpenAI-compatible hosts via their/modelscatalog — and falls back to4096if the probe fails or returns nothing. A manually set value always wins over the probe. See Context Compression for details. - Required: No
- Type:
Integer - Default: (unset — probe the host, otherwise 4096)
llm.contextCompressionThreshold
- Description: The threshold, as a fraction of the context window, at which Musebot compresses the conversation context into a summary. For example,
0.75means compression triggers when the token count reaches 75% of the window. - Required: No
- Type:
Number - Default:
0.75
Media Mode (ComfyUI/SwarmUI) Settings
Required if mode=media
comfyUi.hosts
- Description: An array of URLs of your ComfyUI/SwarmUI backend(s). For SwarmUI, this is typically
http://localhost:7801/ComfyBackendDirect. Supports multiple URLs for redundancy or load balancing. - Required: Yes
- Type:
String[]
comfyUi.timeoutMinutes
- Description: The maximum duration in minutes that a single ComfyUI render task is allowed to run before it is aborted. When the timeout elapses, Musebot interrupts the ComfyUI workflow and disconnects the WebSocket, causing the task to fail and be retried (subject to
taskQueue.numAttempts). - Required: No
- Type:
Number - Default:
30
comfyUi.guidanceScaleInterval
- Description: The interval step used when adjusting the guidance scale via the +/− buttons in the media generation interface.
- Required: No
- Type:
Number - Default:
0.5
multiModal.randomPrompts
- Description: If both an LLM host and ComfyUI/SwarmUI are configured, this provides an array of prompt strings used by the "Randomize" button in the media generation interface. One will be chosen at random for the user.
- Required: No
- Type:
String[] - Default:
["Describe something or someone with extraordinary detail."]
Task Queue & Error Handling
taskQueue.numAttempts
- Description: The maximum number of times a failed task (e.g., a request to an LLM host or ComfyUI) will be retried before it is marked as a permanent failure. Can be set globally in
global.taskQueueor overridden per-bot. - Required: No
- Type:
Integer - Default:
10
taskQueue.retryDelayMs
- Description: The delay in milliseconds between task retries. Increasing this can be helpful if the AI backend is under heavy load. Can be set globally in
global.taskQueueor overridden per-bot. - Required: No
- Type:
Integer - Default:
1000
taskQueue.strategy
- Description: Determines if tasks are executed in
serial(one after the other) orparallel(at the same time). Useparallelonly if your hardware (e.g., multiple GPUs) and host configuration support it. For example, running an LLM host and ComfyUI on the same machine with one GPU will likely cause conflicts inparallelmode. Can be set globally inglobal.taskQueueor overridden per-bot. - Required: No
- Type:
String - Default:
serial - Values:
serial,parallel
taskQueue.forceSerialAcrossHosts
- Description: If
true, forces serial execution across all hosts even when the strategy isparallel. Can be set globally inglobal.taskQueueor overridden per-bot. - Required: No
- Type:
Boolean - Default:
false