CLI Reference

The root command:

mushroom-agent <command> [options]

Available commands:

Command	Description
init	Initialize local config, prompts, and sidecar files
accesskey	Manage agent server accesskeys
start	Start the local agent server, attach the current local device runtime, and open the browser UI
serve	Start the agent service and API transports
node	Attach device runtime and run hardware diagnostics
admin	Manage skills and tools

mushroom-agent init

Initialize the local environment under ~/.mushroom_agent/. The command starts an interactive wizard that writes text-mode or voice-mode model configuration into config.yaml.

mushroom-agent init
mushroom-agent init --root /custom/path
mushroom-agent init --force
mushroom-agent init --mode agent
mushroom-agent init --mode node --server-url ws://host:7860 --access-key <accesskey>

This creates the default generated files:

config.yaml
hardware.yaml
remote.yaml
logs/
skills/
prompts/
  SOUL.md
  AGENTS.md
  IDENTITY.md
  APPROACH_GREETING.md

The generated config.yaml starter only writes workspace.path as the local path anchor. Logs, the default skills/ directory, memory storage, and read / exec / write working directories are derived from that path at runtime. prompts/SOUL.md, prompts/AGENTS.md, and prompts/IDENTITY.md provide starter files for persona, rules, and identity. prompts/APPROACH_GREETING.md tunes camera-approach greeting style and is read only for that event. hardware.yaml configures local device inputs and outputs for start and node attach; remote.yaml configures remote node attachment for node attach.

Options:

Option	Description
--root	Custom root directory (default: ~/.mushroom_agent)
--force	Overwrite existing generated config files
--mode agent|node	agent writes the agent host config; node writes only remote attach config

mushroom-agent accesskey

Manage agent server accesskeys. Accesskey plaintext is printed only when an accesskey is created; config.yaml stores server.accesskeys with accesskey hashes and previews. Accesskeys do not expire automatically; use disable or delete to revoke one.

mushroom-agent accesskey create --name "Kitchen Pi" --node-id pi-kitchen
mushroom-agent accesskey list
mushroom-agent accesskey disable akid_xxx
mushroom-agent accesskey enable akid_xxx
mushroom-agent accesskey delete akid_xxx

accesskey list also reads accesskey_usage.yaml next to config.yaml and shows the most recent node that used each accesskey.

mushroom-agent start

Start the configured local agent server and attach the configured local device runtime from hardware.yaml. The browser UI is always enabled, the URL is printed, and the browser opens when the server is ready.

export MUSHROOM_SKIP_LANGFUSE_AUTH=1
mushroom-agent start
mushroom-agent start --host 127.0.0.1 --port 7860

Options:

Option	Description
--config	Path to config file
--host	UI server host (default: read from server.host)
--port	UI server port (default: read from server.port)

The local UI includes the Local I/O view for configured audio, text, video, User/Agent voice text, latest video preview frame, command summaries, and hardware output events.

mushroom-agent serve

Start the agent service from config.yaml. This is the service/API entrypoint for HTTP chat, WebSocket chat, realtime voice, and function communication.

export MUSHROOM_SKIP_LANGFUSE_AUTH=1
mushroom-agent serve

Options:

Option	Description
--config	Path to config file
--communications	Comma-separated transports: http, websocket, func
--port	HTTP port (default: 7860)

Browser UI

Use --ui for local browser testing. It mounts /i/chat, prints the URL, and opens the browser by default.

mushroom-agent serve --ui

Option	Description
--ui	Mount the local browser test page at /i/chat

mushroom-agent node

Attach the configured device runtime to a remote service or run local hardware diagnostics. Single-machine startup is handled by mushroom-agent start.

node attach

Attach this device runtime to a remote agent service configured in remote.yaml.

# 1. On the agent host
mushroom-agent serve

# 2. On each device
mushroom-agent node attach

Options:

Option	Description
--config	Path to the local config file whose sibling remote.yaml should be used

node record-audio

Capture local audio for noise suppression A/B diagnostics.

mushroom-agent node record-audio --seconds 10

Options:

Option	Description
--seconds	Recording duration in seconds
--config	Path to config file

mushroom-agent skills

Manage installed skills.

mushroom-agent skills list
mushroom-agent skills available
mushroom-agent skills install <name>
mushroom-agent skills install --source <repo-or-dir> --all

mushroom-agent admin

Advanced commands.

mushroom-agent admin tools list

Local vs Remote

serve --ui

Starts the service/API path and mounts /i/chat.

start

Agent and configured device runtime together in one process with the local UI.

serve + node attach

Start the agent on a host, then attach one or more configured devices to it.