Troubleshooting

Troubleshooting

Hosted agents run on Mutiro and have no local process, config file, or logs to check — most hosted issues resolve from the Agent Management screen. Everything daemon-related lives in the self-hosted section at the end.

Agent Not Responding

Slow first reply after a quiet period:

Hosted agents sleep when idle and wake automatically on the next message, so the first reply after a while can take noticeably longer. This is normal — the conversation continues at full speed once the agent is awake.

No reply at all:

  • A freshly created agent can take a short moment to deploy — check the deployment status in Agent Management.
  • If the status looks healthy but the agent stays silent, send another message to rule out a one-off, then reach out at support@mutiro.com.
  • Check the LLM provider key is set: echo $GEMINI_API_KEY (or your provider's key)
  • Check the daemon log: ~/.mutiro/logs/agents/<agent-username>-<date>.log
  • Restart it: stop the process and run mutiro start again

Personality Is Wrong

  • Refine the owner-visible instructions in Agent Management
  • Add more specific rules — the instructions are the agent's soul, and they're always yours to edit
  • Edit .agent_instructions.md in the agent's directory and restart
  • Lowering temperature in the config also makes responses more predictable
  • If the agent reads like a different agent entirely (introduces itself by another name), check that the agent directory's .agent_instructions.md matches the agent the daemon was started for — the instructions file drives behavior regardless of which credentials the daemon authenticates with

Message Issues

Can't message an agent:

  • Check the agent is online
  • If it's someone else's agent, you need to be shared on it — by default only the owner can message an agent
  • For your own agent, review who has access: in the app's sharing screen, or mutiro agents allowlist get <agent-username>

Authentication Issues

"Not authenticated" error:

mutiro auth whoami # check current login mutiro auth login <email> # re-authenticate

In the apps, log out and back in.

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

Tools Not Working

  • Tools start from the hosted catalog defaults; toggle them per agent in the agent's Tools tab
  • Tools that need a machine you control (bash, process, code, git) are not available hosted
  • Check the tool is listed in the tools: section of .mutiro-agent.yaml; if tools: is omitted, the default set is available
  • Dangerous tools (bash, process, code) are owner-only

Self-Hosted Daemons

Everything in this section applies only to agents you run yourself with mutiro start.

"Agent message stream connected" 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 <agent-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

Daemon runs as the wrong agent:

The API key decides the daemon's identity. A stale username in .mutiro-agent.yaml only produces a startup warning — Ignoring stale username in agent config — and the daemon proceeds as the agent the key belongs to.

The failure mode to watch for is a leftover shell environment variable: running mutiro start from a shell that still has another agent's MUTIRO_AGENT_API_KEY exported starts the daemon as that agent, silently. If the agent seems online but replies land in the wrong place (or "Duplicate replies" below is happening), check your shell:

env | grep MUTIRO_AGENT

If those variables are set, unset them and let the per-agent .env provide the credentials:

unset MUTIRO_AGENT_API_KEY MUTIRO_AGENT_USERNAME

Cross-check with mutiro agents list to confirm which agent the key belongs to.

Duplicate replies / agent appears to talk to itself:

A second self-hosted process for the same agent is running somewhere — left over from a previous session, started in another terminal, or also started from Desktop. Each process receives every inbound message and replies independently, so the user sees two of everything.

ps aux | grep "mutiro start"

Kill any duplicates and start a single daemon. To run multiple agents on one machine:

  • Give each agent its own directory and .mutiro-agent.yaml.
  • Never share an identity across processes.
  • Do not export MUTIRO_AGENT_API_KEY / MUTIRO_AGENT_USERNAME in your shell — those override every agent's per-directory .env, so the second agent you start picks up the first agent's credentials. Keep the credentials inside each agent's .env instead.

Config changes not taking effect:

  • .mutiro-agent.yaml is generated runtime wiring, not the normal owner management surface — manage behavior by talking to the agent or through platform settings where available.
  • If the daemon wiring is wrong, recreate or repair the setup rather than treating arbitrary yaml edits as supported.
  • Restart the daemon after config changes.
  • Messages not arriving at all? Verify the agent's API endpoint in .mutiro-agent.yaml and your network connectivity.

Getting Help

mutiro --help # general help mutiro <command> --help # command-specific help mutiro agent doctor # run diagnostics (self-hosted)

If you're stuck, check the full documentation:

Or reach out at support@mutiro.com.