Self-hosted Agent Configuration
This page is the file reference for self-hosted agents. Mutiro-hosted agents do not expose .mutiro-agent.yaml; their runtime config is platform-managed, and creation is intentionally simple:
For hosted agents, manage owner-facing settings such as profile, instructions, sharing, voice, and language through Mutiro surfaces. Tool enablement and per-tool settings use hosted catalog defaults and are not configurable per agent yet.
For self-hosted agents, behavior is shaped by owner-visible instructions and runtime configuration:
.agent_instructions.md— personality, tone, rules (the agent's soul).mutiro-agent.yaml— self-hosted technical config: model, workspace, tools, voice, memory, live calling
A few things still live on the Mutiro platform instead of the yaml — your agent's display name, bio, avatar, and allowlist (who can message it). Manage those via mutiro agents update-profile / mutiro agents allowlist or the Agent Management screen in the Desktop app. See sharing and security.
mutiro agents create --self-hosted generates .mutiro-agent.yaml automatically. Treat it as runtime wiring. Most owners should manage behavior through instructions and platform settings; change the yaml only when you intentionally need self-hosted runtime wiring.
Quick Reference
Self-hosted runtime fields, with defaults. Sections below explain each in depth.
agent.*:
| Field | Type | Default | Purpose |
|---|---|---|---|
username |
string | — | Agent's Mutiro handle (set by mutiro agents create) |
api_key |
string | — | Agent API key (use ${MUTIRO_AGENT_API_KEY}) |
hosting_mode |
string | self_hosted |
Self-hosted runtime marker |
engine |
string | genie |
Brain engine |
workspace |
string | agent directory | Owner's working directory |
user_workspace |
string | ./users/${USERNAME} |
Per-user working directory for non-owner users |
workspace_init |
string | — | Shell command run when a workspace directory does not exist |
allowed_dirs |
[]string | — | Additional directories all users can read/write |
tts_voice |
string | — | Text-to-speech voice for <voice> responses |
language |
string | client locale or en-US |
BCP-47 transcription language preference |
timezone |
string | — | IANA timezone for the scheduler |
history_limit |
int | 30 |
Number of conversation messages included in engine context |
ambient_recall_enabled |
bool | true |
Inject relevant memory snippets before each turn |
working_memory_decay_after |
duration | 72h |
Stop surfacing stale working-memory items (0s disables) |
live_calling_enabled |
bool | false |
Enable real-time voice calls |
agent.live.* (only when live_calling_enabled: true):
| Field | Type | Default | Purpose |
|---|---|---|---|
gemini_api_key |
string | env GEMINI_API_KEY / GOOGLE_API_KEY |
Gemini key for the live model |
model |
string | — | Live audio model name |
agent.genie.* (when engine: "genie"):
| Field | Type | Default | Purpose |
|---|---|---|---|
llm_provider |
string | genai |
genai | anthropic | openai | ollama | lmstudio |
model_name |
string | gemini-3-flash-preview |
Model identifier |
temperature |
float | 0.7 |
Sampling temperature (0 = deterministic, 1 = creative) |
max_tokens |
int | 8000 |
Maximum response length (output cap) |
context_budget |
int | auto from model | Maximum tokens of conversation history kept in each prompt (input cap) |
auto_approve |
bool | true |
Auto-approve Genie tool actions |
tools |
list | registry defaults | Self-hosted explicit tool list (see Tools) |
tool_config |
map | — | Self-hosted provider-specific settings keyed by tool family |
Identity and Engine
username— the agent's Mutiro handle. Set when you ranmutiro agents create. Don't change it manually.api_key— leave it as${MUTIRO_AGENT_API_KEY}. Put the actual key in a.envfile beside the yaml or export it in your shell. The CLI prints the key once when you create the agent.hosting_mode— generated marker for the runtime tier. Mutiro uses it to branch guidance and client behavior. Don't change it manually.engine—genieis the default and the engine wired to LLM providers. If you want to drive the agent from a custom brain you wrote yourself, see swap the brain.
Display name, bio, avatar, allowlist
These do not live in the yaml — they are server-owned and managed via the CLI or Desktop app:
Legacy yamls with display_name, bio, avatar_url, or allowlist keys still parse, but those values are silently ignored on load and stripped on the next save.
LLM Provider and Model
gemini-3-flash-preview is the default — fast, capable, free-tier friendly. Swap llm_provider and model_name together if you want a different provider and set the corresponding API key in your environment (e.g. GEMINI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY).
Input vs output limits
Two independent caps shape each turn:
max_tokenscaps the agent's reply — how long a single response can run.context_budgetcaps the prompt — how much past conversation (and any tool-read files) the agent sees on each turn.
By default the prompt cap is sized automatically from the model's context window, so most agents never need to set context_budget. Override it (in tokens) when you want a tighter or looser cap than the default — for example, lowering it to keep cost predictable on long-running chats, or raising it on a large-window model if the agent feels too forgetful. Setting context_budget always wins over the automatic sizing.
Workspace
The agent's file access is shaped by three fields:
workspace— the owner's working directory. Defaults to the directory where.mutiro-agent.yamllives. The owner always operates here.user_workspace— the working directory for non-owner users. New agents ship withuser_workspace: "./users/${USERNAME}", giving each non-owner user an isolated subfolder they cannot see out of. Variables:${USERNAME}(sender's username),${CONVERSATION_ID}.allowed_dirs— additional directories every user (owner and non-owners) can read and write, on top of their workspace. Use this to share materials or project data without collapsing per-user isolation.
workspace_init is an optional shell command run whenever the resolved workspace directory does not yet exist. Available environment variables: CONVERSATION_ID, USERNAME, WORKSPACE. Examples:
Sharing materials across users
When a teacher wants to distribute files to students — or any owner wants a shared folder alongside private per-user space — keep user_workspace as-is and add the shared folder to allowed_dirs:
The owner saves files to ./materiais from the agent root. Students reach the same path through the expanded sandbox. Each student's own work stays in their private users/<their-name>/ folder, unreadable by other students.
Per-conversation workspaces
If you want each conversation to get its own isolated workspace, use ${CONVERSATION_ID}:
This works for the owner. Combine with user_workspace to also isolate per-user.
Tools
tools: defines what the self-hosted runtime can expose. If you omit the tools: section, the agent gets all default-enabled tools. When you specify tools explicitly, it's a complete override — list everything you want.
Each tool entry can be a bare name or a {name, owner_only} object. When owner_only: true, non-owner users in the conversation cannot use that tool — useful for write/destructive tools you only want yourself to invoke.
Tool Catalog
These are the exact name values to use in self-hosted config. "Default" means the tool is enabled when you omit tools: entirely.
Workspace (file operations)
| Tool | Description | Default |
|---|---|---|
listFiles |
List files and directories in the workspace | Yes |
findFiles |
Find files by name or path pattern | Yes |
readFile |
Read a file from the workspace | Yes |
writeFile |
Create or update a file in the workspace | Yes |
searchInFiles |
Search file contents across the workspace | Yes |
viewImage |
Open an image for inspection | Yes |
viewDocument |
Open a document for inspection | Yes |
Messaging
| Tool | Description | Default |
|---|---|---|
send_message |
Send a text message | Yes |
send_voice_message |
Send a text-to-speech voice message | Yes |
send_image_message |
Generate and send an image | Yes |
edit_image_message |
Edit an image and send the result | Yes |
send_file_message |
Upload and send a file | Yes |
send_card |
Send an interactive card | Yes |
react_to_message |
Add an emoji reaction | Yes |
forward_message |
Forward a message to another conversation | Yes |
Memory and Recall
| Tool | Description | Default |
|---|---|---|
recall |
Semantically search conversation history | Yes |
recall_get |
Open a recalled item from history | Yes |
memory_get |
Read long-term memory | Yes |
memory_write |
Save to long-term memory | Yes |
working_memory_get |
Read current working memory snapshot | No |
working_memory_update |
Update current working memory snapshot | No |
Web
| Tool | Description | Default |
|---|---|---|
web_search |
Search the web, return summarized results | No |
web_fetch |
Fetch and extract content from a URL | Yes |
Scheduler
| Tool | Description | Default |
|---|---|---|
schedule_prompt_create |
Schedule a prompt to run later | Yes |
schedule_prompt_list |
List scheduled prompts | Yes |
schedule_prompt_cancel |
Cancel a scheduled prompt | Yes |
Planning
| Tool | Description | Default |
|---|---|---|
thinking |
Record private reasoning notes | No |
Skill |
Use a reusable skill | Yes |
TodoWrite |
Track task checklist | No |
Task |
Delegate to a helper agent | No |
Dangerous (owner-only by default, off by default)
| Tool | Description |
|---|---|
bash |
Run shell commands in the workspace |
process |
Inspect or control running processes |
install_skill |
Install a reusable skill package |
code |
Spawn an external coding agent (Claude Code, Codex) |
Dangerous tools bypass every containment layer. See sharing and security for the security implications of tool choices.
Per-tool family settings
Some self-hosted tools need extra configuration (API keys, providers). Put those under genie.tool_config, keyed by tool family:
tool_config is independent of the tools enable list — toggling a tool on or off does not touch its settings.
Self-hosted Tool Selection Guide
- Minimal self-hosted agent (Q&A bot): omit
tools:entirely, defaults are fine - Research agent: defaults +
web_search,web_fetch - Deep thinker: defaults +
thinking,TodoWrite,Task - Engineering manager:
code,readFile,writeFile,thinking,Task,memory_get,memory_write
Voice and Language
tts_voice— the agent's default voice when it sends a voice message via thesend_voice_messagetool. Format:{language-code}-Chirp3-HD-{voice-name}. Pick a voice from the table below and combine it with the language code you want — e.g.en-US-Chirp3-HD-Orus,pt-BR-Chirp3-HD-Callirrhoe,es-ES-Chirp3-HD-Charon. The agent can override the language per call (thesend_voice_messagetool exposes alanguageparameter), but the voice name comes from this setting.language— preferred BCP-47 language for transcribing audio messages users send to the agent. Priority: agentlanguage> client locale >en-US. The agent's text replies are not constrained by this — it can text in any language.
Voice Catalog
All 30 supported Chirp3 HD voices. Click "Play" to hear a sample.
| Voice | Gender | Sample |
|---|---|---|
Achernar |
Female | |
Achird |
Male | |
Algenib |
Male | |
Algieba |
Male | |
Alnilam |
Male | |
Aoede |
Female | |
Autonoe |
Female | |
Callirrhoe |
Female | |
Charon |
Male | |
Despina |
Female | |
Enceladus |
Male | |
Erinome |
Female | |
Fenrir |
Male | |
Gacrux |
Female | |
Iapetus |
Male | |
Kore |
Female | |
Laomedeia |
Female | |
Leda |
Female | |
Orus |
Male | |
Puck |
Male | |
Pulcherrima |
Female | |
Rasalgethi |
Male | |
Sadachbia |
Male | |
Sadaltager |
Male | |
Schedar |
Male | |
Sulafat |
Female | |
Umbriel |
Male | |
Vindemiatrix |
Female | |
Zephyr |
Female | |
Zubenelgenubi |
Male |
All voices support every Chirp3 HD language. Combine the voice name with your language choice — e.g. Zephyr + pt-BR → pt-BR-Chirp3-HD-Zephyr. Reference: https://cloud.google.com/text-to-speech/docs/chirp3-hd
Live Calling
Real-time voice calls between users and the agent.
When enabled, users can initiate voice calls from the Mobile or Desktop app. The Gemini API key is required — the daemon falls back to the GEMINI_API_KEY or GOOGLE_API_KEY environment variable if gemini_api_key is empty.
Memory and Context
history_limit— how many recent conversation messages are included when the engine assembles context for a turn. Default30.ambient_recall_enabled— whentrue, the brain proactively pulls a few traced memory snippets into context before each turn. Defaulttrue. Setfalseto disable proactive recall.working_memory_decay_after— stale working-memory items stop surfacing after this inactivity window. Default72h. Set0sto disable decay.
Scheduler Timezone
IANA timezone used by the scheduler when interpreting times in scheduled prompts (e.g. "remind me tomorrow at 8am"). If unset, the scheduler falls back to the user's client timezone, then to UTC.
Applying Changes
Runtime environment or daemon wiring changes take effect when you restart the daemon: