Agent Host (Daemon)

Agent Host (Daemon)

The agent host is the local process that keeps your Mutiro agent online. It connects to Mutiro, receives messages addressed to your agent, runs them through the AI engine, and sends responses back. It runs as long as you want the agent online.

You start it with mutiro start (a shortcut for mutiro agent host). The host reads .mutiro-agent.yaml from the current directory.

This page covers what the host does at runtime. For the yaml schema — engine, model, workspace, tools, voice, memory, live calling — see agent configuration.

Starting the Host

cd /path/to/your-agent export MUTIRO_AGENT_API_KEY="your-key-here" # or use a .env file beside the yaml mutiro start

The host:

  1. Reads .mutiro-agent.yaml.
  2. Connects to Mutiro (messaging, presence, optional live).
  3. Opens its local state store (a small file-based key/value store).
  4. Listens for incoming messages and dispatches them to the engine.

Sessions and Memory

The host keeps one engine session per conversation, so users never see each other's context:

Alice ─► Conversation 1 ─► Session A (only Alice's messages) Bob ─► Conversation 2 ─► Session B (only Bob's messages)

Session state survives host restarts — the host stores each conversation's engine session ID in its state store and resumes that session when the conversation continues, so the agent picks up where it left off.

How much conversation history is included on each turn is controlled by agent.history_limit (see Memory and Context).

Local Storage

Per-host state lives under your home directory, one directory per agent:

~/.mutiro/store/<project-path>__<agent-member-id>/

The directory name combines the sanitized path the host runs from with the agent's immutable member ID, so the same agent in the same directory always uses the same store. Set MUTIRO_AGENT_STORE_DIR to move the root.

The store holds plain files, grouped by purpose:

  • cursor/ — the last processed message (chain hash) per conversation; this is what prevents re-processing across restarts
  • session/ — the engine session ID per conversation
  • inflight/ — in-progress turn attempts, so an interrupted turn can be recovered

The agent's API key is not stored here — it comes from the environment or .mutiro-agent.yaml on every start.

Resetting

# Reset one specific agent rm -rf ~/.mutiro/store/<project-path>__<agent-member-id>/ # Wipe everything (all agents on this machine) rm -rf ~/.mutiro/store/

After a reset the host will:

  • Forget every session (conversations start fresh as far as the engine is concerned)
  • Potentially re-process the most recent messages once (the last-processed marker is gone)

Reconnection Behavior

If the network drops or Mutiro restarts, the host reconnects automatically. While offline, messages addressed to the agent are queued server-side; when the host comes back, it processes the backlog in order. The host tracks the last-processed message per conversation, so nothing is lost or duplicated across a restart.

agent.reconnect_delay (default 5s) controls the gap between retry attempts.

Graceful Shutdown

Ctrl+C (or SIGTERM) triggers a clean shutdown:

  1. Stop accepting new incoming messages.
  2. Finish in-flight turns.
  3. Finish writing state files.
  4. Close engine and live connections.
  5. Exit.

You can stop and restart the host at any time without losing state.

Logs

~/.mutiro/logs/agents/<agent-username>-<date>.log

Useful patterns:

# Tail today's log for an agent tail -f ~/.mutiro/logs/agents/my_assistant-$(date +%Y-%m-%d).log # Find errors across all logs grep -i error ~/.mutiro/logs/agents/*.log # See message-handling traces grep -i "processing message" ~/.mutiro/logs/agents/my_assistant-*.log

Health Check

The host exposes a small HTTP health endpoint on daemon_port + 1000 (so if the engine is on 50051, health is on 51051); if that port is taken, it falls back to an ephemeral port and logs the address. Useful for systemd/launchd/Cloud Run-style probes.

Troubleshooting

Agent forgets everything after restart

The store directory is named after the path the host runs from. Launching from a different working directory produces a different store, so sessions and cursors start empty. Always launch from the agent's directory (or set MUTIRO_AGENT_STORE_DIR).

Bot replies twice to the same message

The usual cause is two hosts running as the same agent — typically a leftover MUTIRO_AGENT_API_KEY in another shell (see troubleshooting). A deleted store can also make the host re-process the most recent messages once, since the last-processed marker is gone.

Host can't write to storage

ls -la ~/.mutiro/agents/

Confirm the directory is writable by the user running mutiro start. The most common cause is launching the host as a different user (e.g., via sudo) than the one that created the directory.

Memory grows over time

The host keeps recent sessions in memory for speed. With many active conversations, RAM usage climbs. This is normal up to a point. If memory becomes a real issue:

  • Restart the host periodically (sessions reload from disk on next message).
  • Lower agent.history_limit so each turn pulls less context (see configuration).