Configuration Reference

MushroomAgent's local runtime is configured from ~/.mushroom_agent/config.yaml. mushroom-agent init also writes ~/.mushroom_agent/node.yaml, prompt files, skills/log directories, and a local secrets sidecar referenced by config.yaml.

Configuration is loaded in order:

MUSHROOM_ROOT/config/config.yaml from the project root
~/.mushroom_agent/config.yaml as the local override

Local settings override fields with the same name. The generated starter keeps local paths implicit: logs, prompt discovery, memory storage, skills, and tool working directories are derived from the local root at runtime.

Generated Files

File or directory	Purpose
`config.yaml`	Main agent, model, tools, channel, voice, eval, and skill config
`node.yaml`	Node identity, remote attachment settings, and builtin device capabilities
local secrets sidecar	API keys and access keys referenced by `config.yaml`; do not commit it
`prompts/IDENTITY.md`	Canonical identity and role
`prompts/SOUL.md`	Persona and interaction style
`prompts/AGENTS.md`	Operating rules, project constraints, and boundaries
`prompts/APPROACH_GREETING.md`	Greeting style for camera approach events
`skills/`	Local user skills
`logs/`	Runtime logs

`node.yaml`

node.yaml contains node identity, remote connection settings, and builtin audio/video/speech/text capability configuration.

node:
  node_id: "auto-generated"
  node_name: "MyNode"
  remote:
    url: "ws://127.0.0.1:7860"
    access_key: "mushroom-local-accesskey"
    proxy: ""
    headers: {}
  builtin:
    audio_input:
      enabled: false
    video_input:
      enabled: false
    speech_output:
      enabled: false
    text_input:
      enabled: false

mushroom-agent start uses node.yaml to attach the current machine as the local node runtime. mushroom-agent node attach uses the same file when a device connects to a remote mushroom-agent serve host.

Section	Purpose
`builtin.audio_input`	Microphone input, codec, device selection, local VAD, echo cancellation, noise suppression, debug recording
`builtin.video_input`	Camera input, device list, frame size, JPEG quality, vision settings, proximity observer, side-face gate
`builtin.speech_output`	Speaker or stream output, codec, RTSP/WebSocket output options
`builtin.text_input`	Console text input

Camera sizing, JPEG quality, proximity detection, and side-face gate settings live under node.yaml builtin video configuration, not under config.yaml.

`agent`

agent:
  id: "local-agent"
  name: "LocalAgent"
  max_iterations: 90

Field	Description
`id`	Stable agent identifier
`name`	Display name
`max_iterations`	Maximum think/action loop iterations
`ephemeral_system_prompt`	Per-turn temporary instructions, mainly for delegated sub-agents
`skip_context_files`	Skip workspace context files such as `AGENTS.md`, `SOUL.md`, and `IDENTITY.md`
`quiet_mode`	Suppress non-essential output for sub-agents or quiet runs

`llm`

llm:
  api_type: "openai"
  api_key: "${MUSHROOM_LLM_API_KEY}"
  base_url: "https://api.openai.com/v1"
  model: "gpt-5.5"
  reasoning: "medium"
  temperature: 0.2
  max_output_tokens: 4096
  timeout: 600

Current init wizard text providers are openai, deepseek, and qwen. Voice mode can use OpenAI or Qwen as the main model provider, with OpenAI realtime models handled by realtime_llm.

Field	Description
`api_type`	Provider type, for example `openai`, `deepseek`, or `qwen`
`api_key`	API key or secrets-sidecar placeholder
`base_url`	Provider endpoint
`model`	Model name
`reasoning`	Reasoning effort, such as `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`
`temperature`	Sampling temperature
`max_output_tokens`	Maximum output tokens
`timeout`	Request timeout in seconds

See LLM Providers for model/provider details.

`embedding`

embedding:
  api_type: "openai"
  api_key: ""
  base_url: "https://qwen3-embed.kiwilightyear.com/v1"
  model: "Qwen3-Embedding-0.6B"
  embed_batch_size: 100
  dimensions: 1024

Embeddings are used by memory and retrieval features. Keep the configured vector dimension aligned with the selected embedding model.

`server`

server:
  host: "0.0.0.0"
  port: 7860
  accesskeys: []

server.accesskeys stores hashed accesskey records and previews. Plaintext accesskeys are printed only when created by mushroom-agent init or mushroom-agent accesskey create.

`mcp`

mcp:
  enabled: false
  servers: {}

MCP is disabled by default. Enable it only after adding server definitions under mcp.servers.

`tools`

Builtin tools are loaded from tools.* configuration. The actual visible tools can be inspected with:

mushroom-agent tools list

Section	Default	Purpose
`skill_manage`	enabled	Create or update skills in writable skill roots
`skill_view`	enabled	Inspect skills from readable roots
`read`	enabled	Read text and image files
`exec`	enabled	Run shell commands
`web_fetch`	enabled	Fetch URLs and HTTP response content
`web_search`	enabled	Search the web
`image_generation`	enabled	Generate images through the configured provider
`video_generation`	disabled	Generate videos through VolcEngine Ark or Google provider settings
`video_analyze`	disabled	Analyze video through provider settings
`audio_analyze`	disabled	Analyze audio through provider settings
`attach_artifact`	enabled	Attach generated artifacts
`process`	enabled	Manage longer-running background processes
`memory_search`	enabled	Search agent memory
`memory_add_file`	enabled	Add local text/Markdown files to memory
`manage_schedule`	enabled	Schedule management
`skip_voice_reply`	disabled	Voice-mode helper to skip spoken reply
`emit_ui_command`	disabled	Emit UI commands in voice/UI runtimes
`update_identity_profile`	enabled in starter	Update identity profile data
`delegate_task`	disabled	Spawn constrained child agents

The current default builtin registry does not register standalone write or api_request tools. Use exec/process for local automation, web_fetch/web_search for web access, and service APIs for external integrations.

`channels`

channels:
  feishu:
    enabled: false
    app_id: ""
    app_secret: ""
    verification_token: ""
    encrypt_key: ""
  discord:
    enabled: false
    bot_token: ""
  openim:
    enabled: false
  magiccampus:
    enabled: false
  livekit:
    enabled: false

Platform channels adapt external chat or media platforms into MushroomAgent messages. Direct communication transports (http, websocket, func) are selected with mushroom-agent serve --communications rather than this section.

Voice Sections

Section	Purpose
`stt`	Speech-to-text provider and behavior
`rtc`	Realtime voice mode switch, recording, identity, VAD, interruptions
`tts`	Text-to-speech provider and voice output settings
`realtime_llm`	Realtime LLM model and API key for realtime voice

rtc:
  enabled: false
  identity_enabled: false
  voice_mode: "realtime"
  vad_mode: "vad"
  allow_interruptions: true

realtime_llm:
  model: "gpt-realtime-2"
  api_key: "YOUR_REALTIME_API_KEY"

When rtc.enabled=false, normal mushroom-agent serve --ui and text WebSocket chat do not require TTS or realtime LLM credentials.

`skills`

skills:
  enabled: true
  roots: []
  include_defaults: true
  include_bundled: true
  explicit_only: false

Field	Description
`enabled`	Enable skill discovery and injection
`roots`	Additional skill root directories
`include_defaults`	Include the default local skills root
`include_bundled`	Include bundled official skills
`explicit_only`	Only load skills explicitly requested by the user/task

`self_improvement`

self_improvement:
  enabled: false
  skill:
    enabled: true
    post_turn_nudge: true
  skill_curator:
    enabled: true

Self-improvement features are disabled by default. Enable them only when you want the agent to suggest, review, or curate skills over time.

`dev.eval`

dev:
  eval:
    enabled: true
    max_concurrency: 1
    keep_runs: 20
    default_enable_judge: false
    case_timeout: 120

This controls the Eval Panel at /i/dev/eval. See Eval Panel for usage and token-cost guidance.

Updating Config Safely

Prefer mushroom-agent init for first-time generation.
Use mushroom-agent init --force only when you intentionally want to overwrite generated files.
Do not commit local secrets sidecars.
For remote devices, create accesskeys with mushroom-agent accesskey create and store the plaintext immediately.
Treat mushroom-cli/mushroom_cli/configs/local-config.template.yaml, local-node.template.yaml, and local-builtin.template.yaml in the framework repository as the source of truth for generated defaults.

Generated Files​

node.yaml​

agent​

llm​

embedding​

server​

mcp​

tools​

channels​

Voice Sections​

skills​

self_improvement​

dev.eval​

Updating Config Safely​