Agent Daemon Documentation

What is This?

The agent daemon is a background service that runs your AI agent and keeps it online 24/7. Your agent is like a member of Mutiro (a messaging platform) - it can receive and send messages, just like a human user would.

The Big Picture

Mutiro is a messaging platform where users can chat with each other and with AI agents. Your agent daemon:

• Receives messages from users via Mutiro
• Sends them to an AI (like Claude or Genie) for processing
• Sends the AI's response back to the user
• Stays running 24/7 so your agent is always available

What You Can Build

• Personal assistant - An always-on AI helper for yourself
• Customer support bot - Automated help for your users
• Code assistant - AI that helps with programming tasks
• Team helper - Shared AI agent for your organization

How It Works (Simple View)

User sends message ↓ Mutiro ↓ Agent Daemon ←── You configure this ↓ AI Engine (Claude/Genie) ↓ Agent Daemon ↓ Mutiro ↓ User receives response

AI Engines Explained

An AI engine is the actual AI brain that generates responses. The daemon supports three options:

• Claude - Anthropic's Claude AI (powerful, conversational, great for most uses)
• Genie - A customizable AI with file access and tool usage
• Echo - Simple test engine that echoes messages back (for development)

What Makes the Daemon Different?

The daemon is one way to run an agent on Mutiro. Key characteristics:

• Runs continuously in background
• Responds to messages automatically
• Perfect for always-on bots and assistants
• Requires configuration file

Use the daemon when: You want an always-on agent that responds to messages automatically without manual intervention.

Configuration

The daemon needs a configuration file to know how to behave. This file is called .mutiro-agent.yaml and should be in the directory where you run the mutiro start command.

How to get this file: Run mutiro agents create --username your_bot_name --engine claude (or genie/echo). This command:

• Creates your agent on Mutiro
• Generates the API key for authentication
• Creates .mutiro-agent.yaml with your agent's credentials

Think of it as: The instruction manual for your AI bot - it tells the daemon which AI to use, what username to give your bot, and how it should behave.

Key Settings Explained

Before diving into the full configuration, here are the most important settings you need to know:

Required Settings (automatically set by mutiro agents create):

• agent.username - Your bot's username (like my_assistant)
• agent.api_key - Secret key to connect to Mutiro (generated when you create the agent)
• agent.engine - Which AI to use (claude, genie, or echo)

Important Settings:

• workspace - Where your AI can read/write files (set this if your agent needs file access)
• allowlist - Who can message your agent (defaults to only you - see Access Control & Security)

Optional Settings:

• Everything else has sensible defaults and you can ignore them at first
• api_endpoint and use_tls - Only for developers running local Mutiro services

Complete Configuration Reference

Here's a full example showing all possible settings:

# ===================================== # Connection Settings # ===================================== debug: false # Turn on detailed logs for troubleshooting presence_subscribe: false # Show when users are online/offline # Developer settings (only for running local Mutiro services) # api_endpoint: localhost # Default: api.mutiro.com:443 # use_tls: false # Default: true # ports: # Local development only # auth: 8082 # member: 8081 # messaging: 8083 # presence: 8084 # ===================================== # Agent Settings # ===================================== agent: # REQUIRED: Your bot's identity username: my_assistant # Bot's username (must be unique) api_key: ${MUTIRO_API_KEY} # Secret key (set MUTIRO_API_KEY environment variable) # REQUIRED: Which AI brain to use engine: claude # Options: claude, genie, or echo # Working Directory (where your AI can access files) workspace: "./workspaces/${CONVERSATION_ID}" # Creates separate folder per conversation workspace_init: "mkdir -p ${WORKSPACE}" # Command to set up workspace # Network Settings daemon: host: localhost port: 9090 # Port for the daemon to listen on # Connection Behavior messaging_enabled: true # Connect to messaging service presence_enabled: true # Update "online" status reconnect_delay: 5s # Wait 5 seconds before reconnecting after disconnect heartbeat_interval: 30s # Send "I'm alive" ping every 30 seconds # ===================================== # AI Engine-Specific Settings # ===================================== # Claude Settings (only used if engine: claude) claude: command: "claude" # Path to Claude executable append_system_prompt: "" # Extra instructions for Claude # Note: Set ANTHROPIC_API_KEY environment variable for Claude authentication # Genie Settings (only used if engine: genie) genie: persona: helpful_assistant # Optional: Genie persona name auto_approve: false # If true, Genie runs commands without asking (safer: false) # Note: Genie uses the workspace field above for its working directory # Echo Settings (only used if engine: echo - for testing only) echo: prefix: "🤖 Echo:" # Text to add before echoing messages delay: 100ms # Fake processing delay

Environment Variable Substitution

What is this? Instead of hardcoding secrets in your config file, you can reference environment variables (values stored in your terminal session or .env file).

Why use it? Keep API keys secret and out of version control (like git).

How it works: Put ${VARIABLE_NAME} anywhere in your config:

agent: api_key: ${MUTIRO_API_KEY} # Gets value from environment workspace: "/home/${USER}/workspace" # Uses your username from environment claude: command: "${CLAUDE_PATH:-claude}" # Uses CLAUDE_PATH if set, otherwise "claude" genie: persona: "helpful_assistant" # Genie persona name

Setting environment variables:

Option 1: Using a .env file (recommended):

# Create a .env file in your agent directory echo "MUTIRO_API_KEY=your-secret-key-here" > .env echo "MUTIRO_SUPPORT_BOT_KEY=your-other-key" >> .env echo "ANTHROPIC_API_KEY=your-claude-key" >> .env # Make sure .env is in .gitignore so secrets don't go to git! echo ".env" >> .gitignore

The daemon automatically loads .env files from the current directory.

Option 2: Export in terminal:

# In your terminal before starting the daemon export MUTIRO_API_KEY="your-secret-key-here" export GENIE_PERSONA="helpful_assistant"

Pro tip: Use descriptive variable names like ${MUTIRO_SUPPORT_BOT_KEY} instead of generic ${MUTIRO_API_KEY} when you have multiple agents. This makes it clear which key is for which agent.

Workspace Variables

What is a workspace? A folder where your AI can read and write files. Think of it as the AI's "working directory."

Why use workspace variables? To give each conversation its own isolated folder, preventing file conflicts.

The workspace setting supports special variables that change based on who's talking:

• ${CONVERSATION_ID}: Unique ID for each conversation (like conv_abc123)
• ${USERNAME}: Who sent the message (like alice)

Examples:

# Separate folder per conversation (recommended for multi-user bots) workspace: "./workspaces/${CONVERSATION_ID}" # Result: ./workspaces/conv_504fc1eb-f10d-40bd-ab18-725ff3b19a82 # Separate folder per user AND conversation workspace: "./users/${USERNAME}/${CONVERSATION_ID}" # Result: ./users/kcaldas/conv_504fc1eb-f10d-40bd-ab18-725ff3b19a82

Setting up workspaces automatically:

The workspace_init script runs once when a workspace is first created:

workspace: "./workspaces/${CONVERSATION_ID}" workspace_init: | mkdir -p ${WORKSPACE} echo "Welcome!" > ${WORKSPACE}/README.md

Variables available in the init script:

• $CONVERSATION_ID - The conversation ID
• $USERNAME - Who's talking
• $WORKSPACE - The full workspace path

Access Control & Security

Who Can Message Your Agent?

By default: Only you (the agent creator) can message your agent. This is the safest option.

Why this matters: Your agent can execute code, access files, and take actions on your behalf. You want to control who can trigger these actions!

The Allowlist

The allowlist setting controls which users can send messages to your agent:

agent: allowlist: - "alice" # Only alice can message this agent

Default behavior (when you create an agent):

agent: allowlist: - "your_username" # Only you

Sharing with Specific Users

Share with a few trusted people:

agent: allowlist: - "alice" # Your username - "bob" # Your teammate - "carol" # Another trusted user # @ prefix is optional - both "alice" and "@alice" work

Public Agents

Warning: Opening your agent to everyone means anyone can trigger it to run code and access files. Only do this if:

• Your agent has no sensitive access
• You understand the security implications
• You're ready to handle potential abuse

Make agent public to everyone:

agent: allowlist: - "*" # Anyone can message this agent

Blocking Specific Users

Block individual users:

agent: allowlist: - "*" # Accept everyone... - "!baduser" # ...except this specific user - "!spammer" # ...and this one too

The ! prefix means "reject this user."

Security Best Practices

1. Start restrictive, expand carefully:

# Day 1: Just you allowlist: - "alice" # Week 1: Add trusted teammates allowlist: - "alice" - "bob" - "carol"

2. For public agents, limit capabilities:

• Use Echo engine for testing
• Don't give file access (workspace not set)
• Monitor logs regularly
• Set up rate limiting (future feature)

3. Review who's using your agent:

# Check logs for message activity grep -i "processing message" ~/.mutiro/logs/agents/my_assistant-*.log

4. Different agents for different purposes:

# Personal assistant - private agent: username: alice_personal allowlist: ["alice"] workspace: "/home/alice/work" # Team helper - shared with specific people agent: username: team_helper allowlist: ["alice", "bob", "carol"] workspace: "./shared/${CONVERSATION_ID}" # Public demo - restricted capabilities agent: username: demo_bot allowlist: ["*"] engine: echo # Safe, no code execution

Session Management

What is a Session?

A session is like a conversation's memory. When you talk to Claude AI, it remembers what you said earlier in the conversation - that's the session. Without sessions, the AI would have amnesia and forget everything between messages!

Example without sessions:

You: "My name is Alice" AI: "Nice to meet you!" You: "What's my name?" AI: "I don't know, you haven't told me" ← Forgot!

Example with sessions:

You: "My name is Alice" AI: "Nice to meet you, Alice!" You: "What's my name?" AI: "Your name is Alice" ← Remembered!

How the Daemon Manages Sessions

The daemon keeps separate sessions per conversation so users don't accidentally share context:

User Alice ─────► Conversation 1 ─────► Claude Session A (only Alice's messages) User Bob ─────► Conversation 2 ─────► Claude Session B (only Bob's messages) User Alice ─────► Conversation 3 ─────► Claude Session C (Alice's other chat)

This means Alice and Bob can both talk to your bot without seeing each other's conversation history.

Where Sessions are Stored

Sessions are saved in a database on your computer so they survive restarts:

~/.mutiro/agents/{project_hash}/{agent_username}/agent.db

What does this mean?

• ~/.mutiro/agents/ - Hidden folder in your home directory
• {project_hash} - A unique code based on your workspace path (ensures consistent location)
• {agent_username} - Your bot's username
• agent.db - The local database file

Example:

~/.mutiro/agents/a3f5c9d.../my_assistant/agent.db

What Gets Stored

The database remembers:

• Session IDs: Which Claude session belongs to which conversation
• Processed Messages: Which messages we've already responded to (prevents duplicates)
• Message Hashes: Fingerprint of the last message processed
• First Startup Flag: Whether we've sent the welcome message yet
• API Key: Your bot's authentication key

Session Persistence Across Restarts

The magic: When you restart the daemon, it picks up right where it left off!

How it works:

1. Loads session from storage - Checks the database for existing sessions
2. Resumes conversation - Tells Claude "continue session XYZ"
3. Maintains full context - The AI remembers everything from before the restart

Example:

Before restart: You: "My favorite color is blue" AI: "I'll remember that!" [Daemon restarts] After restart: You: "What's my favorite color?" AI: "Blue!" ← Still remembers!

Performance optimization: The daemon keeps recent sessions in memory (RAM) for instant access. Only checks the database when a session isn't in memory yet. This makes responses faster after the first message in a conversation.

Claude --continue Mode (Advanced)

Special feature for personal assistants: You can share context between manually running claude code and your Mutiro bot!

Setup:

agent: engine: claude claude: command: "claude --continue" # Magic flag

How it works:

1. Work on your code manually: claude code in your terminal
2. Start your Mutiro bot: mutiro start in the same folder
3. Message your bot on Mutiro
4. The bot continues your manual session! It sees all the context from step 1
5. Keep working in terminal - the daemon picks up your changes

Real-world example:

# Terminal 1: Manual work $ claude code You: "Write a Python function to sort numbers" Claude: "Here's the function: [code]" # Terminal 2: Start daemon (keeps running) $ mutiro start # Via Mutiro app You: "Make it faster" Bot: "I'll optimize the sorting function I wrote..." ← Remembers! # Back to Terminal 1 (still running) You: "Add error handling" Claude: "I'll update the optimized function..." # Via Mutiro app (picks up the changes!) You: "What does the function do now?" Bot: "It sorts numbers with error handling..." ← Knows about latest changes!

The magic: Both manual Claude and the daemon can run simultaneously! Each time either one accesses the session, it gets the latest state. Your manual work is visible to the bot, and vice versa.

When to use:

• Personal assistant (only you use the bot)
• Multi-user bot (would mix everyone's conversations - bad!)
• Seamless switching between terminal and Mutiro
• Bot can see your manual work in real-time

Technical details:

• Claude stores sessions in ~/.claude/projects/{project-path}/
• --continue finds the most recent session file
• Session updates are picked up by both processes
• Session files are .jsonl files with UUID names

How the Daemon Behaves

What Happens When You Start It

When you run mutiro start, here's what happens behind the scenes:

1. Reads your config from .mutiro-agent.yaml
2. Sets up storage in ~/.mutiro/agents/ for sessions and state
3. Checks if this is the first time
   • If yes: Sends you a welcome message
   • Saves a flag so it doesn't welcome you again
4. Connects to Mutiro services
   • Messaging (to receive/send messages)
   • Presence (to show your bot as "online")
5. Starts listening for messages
   • Tries port 9090 (or your configured port)
   • If busy, tries ports 50050-50100
   • If all busy, uses a random available port
6. Starts health check (daemon_port + 1000, so if daemon is on 9090, health check is on 10090)
7. Ready! Your bot is now online and waiting for messages

The Welcome Message

The first time your bot starts, it sends you a friendly greeting:

Hello! I'm @my_assistant, your new AI agent. I'm ready to help you with tasks and answer questions. Send me a message anytime!

Important: This only happens once! The daemon remembers it said hello and won't spam you on every restart.

How Messages Get Processed

When someone sends your bot a message, here's the journey it takes:

1. Message arrives (via streaming connection) ↓ 2. "Have I seen this before?" (prevents duplicates) ↓ 3. Extract the text (including transcribed audio) ↓ 4. Get the AI engine for this conversation ↓ 5. Load the session (conversation memory) ↓ 6. Send to AI: "Here's the message + past context" ↓ 7. AI responds + gives us updated session ID ↓ 8. Save the session (for next time) ↓ 9. Send response back to user

Key insight: Steps 2-8 happen in milliseconds! The AI part (step 6-7) is the slowest.

What If Connection Drops?

Don't worry! The daemon automatically handles connection issues and no messages are lost.

What happens:

• Agent goes offline (network issue, restart, etc.)
• Users can keep sending messages - Mutiro queues them
• Daemon reconnects automatically after reconnect_delay (default 5s)
• Picks up where it left off - Processes all queued messages in order
• No messages missed - The daemon tracks the last processed message

Real-world example:

1. User sends: "Write a function" 2. Agent processes and responds 3. [Network drops - agent offline] 4. User sends: "Add tests" ← Queued by Mutiro 5. User sends: "Make it async" ← Also queued 6. [Agent reconnects - 5 seconds later] 7. Agent processes: "Add tests" ← First queued message 8. Agent processes: "Make it async" ← Second queued message

Key benefit: Users don't need to know if your agent is online or offline. They can send messages anytime, and the agent will catch up when it reconnects.

Future improvement: Exponential backoff (wait longer after repeated failures)

Stopping the Daemon Safely

When you press Ctrl+C or send a stop signal:

1. Stops accepting new messages - "No more work, please!"
2. Finishes current work - Completes messages it's already processing
3. Closes AI connections - Cleanly shuts down Claude/Genie
4. Saves everything - Flushes database to disk
5. Shuts down - Exits cleanly

Result: No data loss, no corrupted state. Safe to restart anytime!

Storage & State

What's in the Database?

The daemon stores everything in a local database (like a dictionary with key-value pairs):

What's Stored	Example	Why
API Key	your-secret-key-123	Authentication
Sessions	session:conv_abc → session_xyz	Remember conversations
Message Hashes	hash:conv_abc → a1b2c3	Know which message we last processed
Processed Messages	processed:msg_123 → timestamp	Prevent duplicates
First Startup Flag	first_startup → true	Remember we sent the greeting

Think of it like: A small notebook where the daemon writes down important things to remember.

Resetting Everything (Nuclear Option)

Want to start fresh? Delete the database:

# Find your bot's database ls ~/.mutiro/agents/*/my_assistant/ # Delete just this bot rm -rf ~/.mutiro/agents/*/my_assistant/ # Delete ALL agent data rm -rf ~/.mutiro/agents/

Warning: This erases all conversation memory and history. Your bot will:

• Forget all sessions (fresh conversations)
• Reprocess old messages (might duplicate responses)
• Send the greeting message again
• Forget its API key (you'll need to reconfigure)

AI Engine Setup

Claude Engine

What is it? Uses Anthropic's Claude AI via the Claude Code CLI tool.

Simplest setup:

agent: engine: claude

That's it! Just make sure you have Claude Code installed and ANTHROPIC_API_KEY set.

Custom settings:

agent: claude: command: "claude --model sonnet --temperature 0.5"

Session options:

Setting	What Happens	Best For
(default)	Separate session per conversation	Multi-user bots
command: "claude --continue"	Share session with manual usage	Personal assistant

Add extra instructions to Claude:

agent: claude: append_system_prompt: | You are a friendly coding assistant. Always explain your code clearly.

Behind the scenes:

• Daemon adds --resume {session-id} automatically
• If you use --continue, daemon skips adding --resume
• Session ID extracted from Claude's response and saved

Genie Engine

What is it? Genie is a customizable AI with tool access - it can run commands, read files, and take actions on your computer. You define "personas" (personalities/behaviors).

Developed by Mutiro Labs as an open-source project.

Learn more: github.com/kcaldas/genie

Why use Genie?

• More control over AI behavior via personas
• Can run shell commands and scripts
• Local file access and manipulation

Setup:

1. Create a persona folder:

   mkdir -p .genie/personas/my_helper/

2. Add prompt.yaml defining the persona's behavior

3. Configure the daemon:

   agent: engine: genie workspace: /absolute/path/to/workspace # Where Genie can work genie: persona: my_helper # Must match folder name auto_approve: false # Ask before running commands

Important notes:

• auto_approve: false means Genie asks before running commands (safer!)
• auto_approve: true means Genie runs commands automatically (faster but riskier!)
• Working directory comes from workspace field

Echo Engine (For Testing)

What is it? A dummy AI that just repeats your messages back. Perfect for testing!

Why use it?

• No API keys needed
• Instant responses
• Test your daemon setup without using real AI

Setup:

agent: engine: echo echo: prefix: "🤖 Echo:" # Added to every response delay: 100ms # Fake thinking time

What you'll see:

You: Hello! Bot: 🤖 Echo: @your_username: Hello!

Pro tip: Use delay: 0ms for instant testing, or add delay to simulate real AI response times.

Common Use Cases

Here are some real-world examples to get you started!

Personal Assistant (Just For You)

Goal: Your own private AI that remembers your conversations across terminal and Mutiro.

Config:

agent: username: my_assistant api_key: ${MUTIRO_API_KEY} engine: claude claude: command: "claude --continue" # Share context with manual Claude usage

How to use:

1. Code in your terminal: claude code
2. Ask Claude to write a feature
3. Start daemon: mutiro agent daemon
4. Message your bot on Mutiro: "Add tests for that feature"
5. Bot remembers the feature from your terminal session!

Multi-User Support Bot

Goal: A bot that helps multiple users, keeping their conversations separate.

Config:

agent: username: support_bot api_key: ${MUTIRO_API_KEY} engine: claude workspace: "./workspaces/${CONVERSATION_ID}" # Separate folder per chat

What happens:

• Alice talks to the bot → Gets her own session
• Bob talks to the bot → Gets his own session
• They never see each other's messages
• Bot remembers context separately for each
• Daemon restart doesn't lose any context

Quick Testing

Goal: Test your daemon setup without spending money on API calls.

Config:

agent: username: test_bot api_key: ${MUTIRO_API_KEY} engine: echo echo: prefix: "[TEST]" delay: 0ms # Instant responses

Perfect for:

• Verifying daemon starts correctly
• Testing message delivery
• Debugging configuration issues
• No API key needed (besides Mutiro)

Code Assistant with File Access

Goal: AI that can read/write files, with isolated workspace per user.

Config:

agent: username: code_helper api_key: ${MUTIRO_API_KEY} engine: claude workspace: "./workspaces/${CONVERSATION_ID}" workspace_init: | mkdir -p ${WORKSPACE} git clone https://example.com/repo.git ${WORKSPACE}/repo claude: command: "claude --add-dir ${WORKSPACE}"

What happens:

1. User messages bot for first time
2. Daemon creates workspace folder
3. Runs init script (clones repo)
4. Claude gets file access to that workspace only
5. Each user gets their own isolated copy

Troubleshooting

Common problems and how to fix them!

Bot Forgets Everything After Restart

Problem: Your bot has amnesia every time you restart it.

Why this happens:

• The workspace path keeps changing
• Database gets created in different locations
• Can't find old sessions

Fix: Use an absolute path for workspace:

agent: workspace: "/home/you/projects/my-bot" # Absolute path, not relative!

Bad examples:

workspace: "./workspace" # Changes based on where you run the command workspace: "~/workspace" # Sometimes causes issues

Good examples:

workspace: "/Users/alice/bots/my-assistant" # Always the same workspace: "/home/bob/projects/support-bot" # Always the same

Bot Responds Twice to Same Message

Problem: You send one message, bot replies twice (or more!)

Why this happens:

• Database got deleted or corrupted
• Daemon can't track which messages it already processed

How to check:

# Does database exist? ls ~/.mutiro/agents/*/my_assistant/ # Can daemon write to it? ls -la ~/.mutiro/agents/*/my_assistant/

How to fix:

1. Check logs: tail ~/.mutiro/logs/agents/my_assistant-*.log
2. Look for database errors
3. If corrupted, delete and restart: rm -rf ~/.mutiro/agents/*/my_assistant/

Can't Find Claude

Problem: Error says claude: executable file not found

Why: Your computer doesn't know where Claude is installed.

Fix #1 - Add Claude to PATH:

# Add this to your ~/.bashrc or ~/.zshrc export PATH="$PATH:$HOME/.local/bin" # Then reload source ~/.bashrc # or source ~/.zshrc

Fix #2 - Use full path in config:

agent: claude: command: "/Users/alice/.local/bin/claude" # Replace with YOUR path

Check if Claude is installed:

which claude # Should show path to Claude claude --version # Should show version number

If not installed: Install Claude Code from claude.ai/code

Sessions Not Loading Correctly

Problem: Sessions seem to disappear randomly or don't persist.

Debug steps:

1. Check the logs for session operations:

# See today's logs tail -f ~/.mutiro/logs/agents/my_assistant-$(date +%Y-%m-%d).log | grep -i session

2. Look for these messages:

• Session loaded from storage - Good!
• Session saved for conversation - Good!
• Session found in cache - Good!
• Any errors - Bad!

3. Inspect database (advanced):

# Check if database file exists and its size ls -lh ~/.mutiro/agents/*/my_assistant/agent.db

Genie Can't Find Persona

Problem: Error says persona not found: my_helper

Common mistakes:

1. Wrong folder structure:

# Wrong .genie/my_helper/prompt.yaml # Correct .genie/personas/my_helper/prompt.yaml ^^^^^^^^ Don't forget this folder!

2. Missing environment variable:

# Set this before starting daemon export GENIE_PERSONA=my_helper

3. YAML file has syntax errors:

• No tabs allowed, only spaces
• Check indentation is consistent
• Validate at yamllint.com

Daemon Using Too Much Memory

Problem: Memory usage keeps growing.

Why this happens:

• Daemon keeps one AI engine per conversation in memory
• More active conversations = more memory
• This is normal and expected!

Is it a problem?

• 10 conversations: Probably fine
• 100 conversations: Might need more RAM
• 1000+ conversations: Consider restarting periodically

Solution if needed:

• Restart daemon daily/weekly: systemctl restart mutiro-daemon
• Or just Ctrl+C and restart manually

Where Are the Logs?

All daemon activity gets logged here:

~/.mutiro/logs/agents/{agent-username}-{date}.log

Useful commands:

# Watch logs in real-time tail -f ~/.mutiro/logs/agents/my_assistant-2025-10-04.log # See all log files ls -lh ~/.mutiro/logs/agents/ # Find errors grep -i error ~/.mutiro/logs/agents/*.log # See today's logs (auto-calculates date) tail -f ~/.mutiro/logs/agents/my_assistant-$(date +%Y-%m-%d).log