Troubleshooting

Agent Won't Start

"Connected to message stream" never appears:

• Check your API key: echo $MUTIRO_AGENT_API_KEY — should start with mut_key_
• Make sure you ran source .env before mutiro start
• Check the agent exists: mutiro agents get <username>
• Run diagnostics: mutiro agent doctor

Port already in use:

The daemon auto-discovers an available port in the 50050-50100 range. If you see a port conflict, it usually means another agent is already running. Check with:

lsof -i :50050-50100

You can also set a specific port in .mutiro-agent.yaml:

agent: daemon: port: 50055

Agent Not Responding

Agent is online but doesn't reply:

• Check the LLM provider key is set: echo $GEMINI_API_KEY (or your provider's key)
• Check daemon.log in the agent's directory — every agent writes its logs there
• Try a different model if the current one is unresponsive
• Verify .agent_instructions.md exists and isn't empty

Agent responds but personality is wrong:

• Edit .agent_instructions.md and restart with mutiro start
• Lower temperature in the config for more predictable responses
• Add more specific rules to the instructions

Authentication Issues

"Not authenticated" error:

mutiro auth whoami # check current login mutiro auth login # re-authenticate

Can't create agent:

• Make sure you're logged in: mutiro auth whoami
• Check username rules: 3-20 chars, lowercase letters + numbers + underscores
• Reserved names (admin, mutiro, support, etc.) are blocked

Message Issues

Can't message the agent:

• Check the agent is running and online
• Verify you're in the allowlist: mutiro agents allowlist get <agent-username>
• If owner-only (default), only the agent's creator can message it

Messages not delivered:

• Check network connectivity
• Verify the agent's API endpoint in .mutiro-agent.yaml
• Restart the agent: stop and run mutiro start again

Configuration Issues

Changes not taking effect:

• Restart the agent after editing .mutiro-agent.yaml
• Restart the agent after editing .agent_instructions.md
• Changes require mutiro start to be re-run

Tools not working:

• Check the tool is listed in the tools: section of the config
• If tools: is omitted, only default tools are available
• Dangerous tools (bash, process, code) are owner-only
• web_search and web_fetch are not enabled by default

Getting Help

mutiro --help # general help mutiro --help # command-specific help mutiro agent doctor # run diagnostics

If you're stuck, check the full documentation:

• Getting started — setup walkthrough
• Configuration — config file reference
• Features — what works on which client
• Sharing and security — allowlist and permissions

Or reach out at support@mutiro.com.