Configuration

MindRoom is configured through one config.yaml file, optionally split across included files, plus environment variables. This page covers where the file lives, a minimal working configuration, which page owns each top-level section, splitting the file, built-in prompt overrides, and the environment variable reference.

Configuration File

If MINDROOM_CONFIG_PATH is set, MindRoom uses that path, even when no file exists there. Otherwise, it uses ./config.yaml in the current working directory if present, then ~/.mindroom/config.yaml.

Data storage (mindroom_data/) is placed next to the config file by default.

Validate a file with:

mindroom config validate --path /path/to/config.yaml

Edits to config.yaml apply by hot reload without restarting MindRoom, except event journal changes, which need a restart. Edits to an agent's or team's own settings, such as instructions, model, tools, or a team's mode, apply from its next reply without restarting it. Changing display_name or accept_invites, an agent's private settings, whether an agent has the desktop tool, or which MCP tools it has restarts that agent or team. An edit that restarts no agent, team, or router and changes no access, room, or authorization setting, such as a model definition, knowledge base, or agent instruction change, applies within seconds even while agents are replying. Other edits, including ones that restart an agent or team, an agent's or team's access or rooms, administrators, authorization, room_defaults, rooms, or router.access, first wait for active responses to finish, for at most 600 seconds. To confirm that a reload finished, use mindroom config check-applied.

Minimal Configuration

All top-level sections are optional; configure at least one agent for conversational replies. This configuration runs one agent in a lobby room, with ANTHROPIC_API_KEY set in the environment or in the .env next to config.yaml:

models:
  default:
    provider: anthropic
    id: claude-sonnet-5-5

agents:
  assistant:
    display_name: Assistant
    role: A helpful AI assistant
    model: default
    rooms: [lobby]

timezone: America/Los_Angeles

Keep models.default configured, because room topic generation and automatic thread summaries fall back to it even when agents, teams, and the router select other models.

Top-Level Sections

Optional tools that agents load on demand are configured as described in Dynamic Tools, and skills in Skills.

Splitting the Configuration Into Multiple Files

Large configs can be split across multiple files with Home-Assistant-style include tags.

A realistic split keeps each agent in its own file, shared lists in _-prefixed snippets, and long prompts in Markdown:

# config.yaml
agents: !include_dir_merge_named agents/
models: !include models.yaml

# agents/researcher.yaml
researcher:
  display_name: Researcher
  role: Deep research and analysis
  model: default
  tools:
    - !expand _shared/web_tools.yaml
    - calculator
  instructions:
    - !include_text ../prompts/researcher.md

# agents/_shared/web_tools.yaml
- duckduckgo
- website
- browser

Here tools resolves to [duckduckgo, website, browser, calculator].

• Relative paths resolve against the directory of the file containing the tag.
• Absolute paths are rejected, and every include must stay inside the top-level config file's directory after symlinks and .. are resolved.
• Explicit include paths may not contain hidden components starting with ., so !include_text .env fails.
• Directory includes recurse into subdirectories, take only .yaml/.yml files in lexicographic order of their relative path, and skip files and directories whose name starts with . or _.
• YAML anchors cannot cross an include boundary, so share values through _-prefixed snippet files.
• !expand is only valid as a list item, may appear several times in one list, and splices one level while keeping order and duplicates. The expanded file must be a YAML list; [] adds nothing, while an empty file, null, a scalar, or a mapping is an error. An ordinary - !include tools.yaml inserts the included value as one item, and tools: !include tools.yaml replaces the whole list.
• An empty included file resolves to null under !include and contributes nothing to directory includes.
• Include cycles, missing files, duplicate keys across !include_dir_merge_named files, and duplicate filename stems under !include_dir_named are errors that name the file and line of the failing tag.

Editing any file in the include tree triggers the same hot reload as editing config.yaml, and a multi-file update such as git pull applies as one reload. Adding a file to an included directory or deleting an included file does not trigger a reload by itself; save config.yaml again (for example with touch config.yaml) or restart MindRoom to apply it. After a failed reload, fixing any file the failed attempt read triggers a retry.

When migrating an existing monolith, diff the fully merged config before and after the split:

mindroom config resolve > before.yaml
# split config.yaml into include files
mindroom config resolve > after.yaml
diff before.yaml after.yaml

When the configuration uses include tags, structured saves from the dashboard and the self-config tools are rejected, so edit the source files instead; the raw config editor still edits the top-level file's text (see Dashboard). MINDROOM_CONFIG_TEMPLATE copies only the single template file, so a template that uses includes needs its included files shipped next to the config path.

Built-In Prompt Overrides

Use the optional root prompts block to replace MindRoom's built-in prompts, keyed by the prompt's uppercase name:

prompts:
  HIDDEN_TOOL_CALLS_PROMPT: |
    Tool calls are hidden from users.
    Answer directly without narrating internal tool use.
  ROUTER_AGENT_SELECTION_PROMPT_TEMPLATE: |
    Decide which agent or team should respond to this message.

    Available agents and teams:

    {agents_info}

    User message: {message}

    Return only the agent or team name.

An unknown key fails config validation with an error that lists every allowed prompt name. Template prompts accept only their own {field_name} placeholders, and an unsupported placeholder fails validation with an error that lists the allowed ones. Placeholders are exact {field_name} replacements, not Jinja or Python str.format, so {message.text}, {message!r}, and {message:.2f} are rejected. Escape literal braces as {{ and }} in overrides that use placeholders. Changed overrides apply through hot reload. Changing a prompt that agents build in when they start, such as HIDDEN_TOOL_CALLS_PROMPT or AGENT_IDENTITY_CONTEXT_TEMPLATE, restarts every agent, team, and the router; other prompt changes apply without restarts.

Environment Variables

Set variables in the process environment or in the .env file next to config.yaml; the process environment wins. MINDROOM_CONFIG_PATH, LOG_LEVEL, MINDROOM_LOGGER_LEVELS, MINDROOM_LOG_FORMAT, NO_COLOR, and MINDROOM_TIMING are read only from the process environment, so the .env file does not set them. Container env_file/--env-file injection sets process variables and therefore works.

Core

Matrix

Hosted pairing variables written by mindroom connect are described in Hosted Matrix, and desktop setup variables in Desktop.

Model Providers

Provider API keys such as ANTHROPIC_API_KEY and OPENAI_API_KEY, their _FILE variants, and Vertex AI and Bedrock settings are listed in Models — Environment Variables, and codex login and CODEX_HOME in Codex Models with ChatGPT Login. Provider keys from the environment or .env are also copied into the shared credentials store, as described in Automatic Credential Import.

Dashboard and API

Workers and Background Scripts

See Background Scripts for when each script gateway variable is required, and Sandbox Proxy for the other MINDROOM_SANDBOX_* and Kubernetes worker variables. Credential seed variables are described in Credential Seeds.