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. Sets up a local SQLite store for sessions and dedupe state.
  4. On the very first run, sends you (the owner) a one-time welcome message so you know the agent is online.
  5. 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)

Sessions persist to disk and survive host restarts — the agent picks up where it left off, with full conversation context. Recent sessions are kept in memory for fast access; older ones load from the database on demand.

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:

~/.mutiro/agents/<project-hash>/agent.db

<project-hash> is derived from the agent's workspace path (or username when the workspace is unset) so the same agent always uses the same database, even when launched from different terminals.

The database holds:

  • The agent's API key (encrypted at rest by the OS keychain when available)
  • Per-conversation session IDs
  • The hash and ID of the last processed message per conversation (prevents duplicate replies)
  • The first-startup flag (so the welcome message goes out exactly once)

Resetting

# Reset one specific agent — workspace and project-hash are tied together rm -rf ~/.mutiro/agents/<project-hash>/ # Wipe everything (all agents on this machine) rm -rf ~/.mutiro/agents/

After a reset the host will:

  • Forget every session (conversations start fresh as far as the engine is concerned)
  • Resend the welcome message
  • Potentially re-process recent messages once (Mutiro's server-side dedupe still helps, but the local guard 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. Flush the database to disk.
  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). Useful for systemd/launchd/Cloud Run-style probes.

Troubleshooting

"Agent storage locked"

Another host is already running for the same project. Find and stop the other process before starting a new one — concurrent hosts on the same database corrupt state.

Agent forgets everything after restart

The project hash is derived from the absolute workspace path. If you launch the host from a different working directory, it computes a different hash and ends up looking at a different database. Use absolute paths in agent.workspace (or always launch from the same directory).

Bot replies twice to the same message

The dedupe guard lives in the local database. If the database was deleted or corrupted, the guard goes with it. Check ~/.mutiro/agents/<hash>/agent.db — if it's gone or unreadable, that explains the duplicates. Recreate by restarting the host; it will rebuild from scratch.

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).