Self-hosted Agent Configuration

This page is the file reference for self-hosted agents using Mutiro's built-in Genie brain. Mutiro-hosted agents do not expose .mutiro-agent.yaml; their runtime config is platform-managed, and creation is intentionally simple:

mutiro agents create my_assistant "My Assistant" --objective "Help me stay organized and move daily work forward"

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 Genie 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 provider, 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.

If you want to replace Genie entirely with another brain process, this is not the page to start from. See swap the brain.

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.5-flash`	Model identifier
`temperature`	float	`0.7`	Sampling temperature (0 = deterministic, 1 = creative)
`max_tokens`	int	`28000`	Maximum response length (output cap)
`context_budget`	int	`100000`	Maximum tokens of conversation history kept in each prompt (input cap); use `0` for model-sized auto
`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

agent: username: "alice_helper" api_key: "${MUTIRO_AGENT_API_KEY}" hosting_mode: "self_hosted" engine: "genie"

username — the agent's Mutiro handle. Set when you ran mutiro agents create. Don't change it manually.
api_key — leave it as ${MUTIRO_AGENT_API_KEY}. Put the actual key in a .env file 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 — genie is the default and the engine wired to LLM providers and the tool catalog below. If you want to drive the agent from a different brain process instead of Genie, 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:

mutiro agents update-profile <agent> --display-name "..." --bio "..." --avatar-url "..." mutiro agents allowlist set <agent> alice bob # explicit allowlist mutiro agents allowlist set <agent> "*" # open access mutiro agents allowlist set <agent> # owner-only (default)

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

agent: genie: llm_provider: "genai" # genai | anthropic | openai | ollama | lmstudio model_name: "gemini-3.5-flash" temperature: 0.7 # 0 = deterministic, 1 = creative max_tokens: 28000 # maximum response length (output cap) max_tool_iterations: 200 context_budget: 100000 # dynamic context cap; set 0 for model-sized auto auto_approve: true # auto-approve tool actions

genai with gemini-3.5-flash is the default. Swap llm_provider and model_name together if you want a different provider. Hosted providers need their API key in the daemon environment, such as GEMINI_API_KEY, ANTHROPIC_API_KEY, or OPENAI_API_KEY. Local providers such as ollama and lmstudio do not require an API key from Mutiro.

Local models with Genie

You do not need to swap the brain to use a local model. Keep engine: "genie" and change the Genie provider.

For Ollama:

agent: engine: "genie" genie: llm_provider: "ollama" model_name: "llama3.1"

For LM Studio:

agent: engine: "genie" genie: llm_provider: "lmstudio" model_name: "openai/gpt-oss-20b"

The exact model name must match what your local provider exposes.

Input vs output limits

Two independent caps shape each turn:

max_tokens caps the agent's reply — how long a single response can run.
context_budget caps 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.yaml lives. The owner always operates here.
user_workspace — the working directory for non-owner users. New agents ship with user_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:

workspace_init: "mkdir -p ${WORKSPACE}" workspace_init: "mkdir -p ${WORKSPACE} && cp -r ~/.agent/template/* ${WORKSPACE}" workspace_init: "git clone https://github.com/user/template ${WORKSPACE}"

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:

agent: user_workspace: "./users/${USERNAME}" # students stay isolated from each other allowed_dirs: - "./materiais" # everyone reaches the shared folder

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}:

agent: workspace: "./workspaces/${CONVERSATION_ID}" workspace_init: "mkdir -p ${WORKSPACE}"

This works for the owner. Combine with user_workspace to also isolate per-user.

Tools

tools: defines what self-hosted Genie can expose. If you omit the tools: section, the agent gets all default-enabled tools from the registry. When you specify tools explicitly, it is a complete override — list every tool you want enabled.

agent: genie: tools: - name: readFile - name: writeFile owner_only: true # only the agent owner can use this tool - name: send_message - name: web_search

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 powerful 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
`appendFile`	Append text to a file in the workspace	Yes
`editFile`	Edit a file in place using line ranges	Yes
`copyFile`	Copy a file within the workspace	Yes
`moveFile`	Rename or move a file within the workspace	Yes
`removeFile`	Delete a file from the workspace	Yes
`makeDirectory`	Create a directory 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

Git

Tool	Description	Default
`gitStatus`	Show the workspace git status	Yes
`gitLog`	Show commit history	Yes
`gitDiff`	Show workspace or commit diffs	Yes
`gitShow`	Read file content at a commit	Yes
`gitCommit`	Commit workspace changes	Yes
`gitRestore`	Restore file content from a commit	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
`update_card`	Update an existing interactive card	Yes
`react_to_message`	Add an emoji reaction	Yes
`forward_message`	Forward a message to another conversation	Yes

Conversations

Tool	Description	Default
`conversations_list`	List conversations visible to the agent account	Yes
`conversation_read`	Read raw messages from one conversation	Yes
`conversation_message_get`	Fetch one raw conversation message by ID	Yes
`conversation_search`	Search historical recall entries in one conversation	Yes
`conversation_search_result_get`	Open a conversation search result by entry ID	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_message_create`	Schedule a message to send later	Yes
`schedule_message_list`	List scheduled messages	Yes
`schedule_message_cancel`	Cancel a scheduled message	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 registry policy, 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)

These tools are not enabled by default. Enable them only when you understand the runtime you are giving the agent access to. 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:

agent: genie: tool_config: web: provider: auto max_results: 5 fetch_mode: focused providers: brave: api_key_secret: BRAVE_API_KEY exa: api_key_secret: EXA_API_KEY google_cse: api_key_secret: GOOGLE_API_KEY cx_secret: GOOGLE_CSE_ID

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

Default self-hosted Genie agent: omit tools: entirely
Research agent: default tools plus web_search
Planning-heavy agent: default tools plus thinking and TodoWrite
Coding agent: include the file/git tools it needs plus code, or use bash / process only when the agent should directly run commands

If you add tools: for any of these, remember that the list is explicit. Include the defaults you still want.

Voice and Language

agent: tts_voice: "en-US-Chirp3-HD-Orus" language: "en-US"

tts_voice — the agent's default voice when it sends a voice message via the send_voice_message tool. 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 (the send_voice_message tool exposes a language parameter), but the voice name comes from this setting.
language — preferred BCP-47 language for transcribing audio messages users send to the agent. Priority: agent language > 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.

agent: live_calling_enabled: true live: gemini_api_key: "${GEMINI_API_KEY}" model: "gemini-2.5-flash-native-audio-preview-12-2025"

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

agent: history_limit: 30 ambient_recall_enabled: true working_memory_decay_after: 72h

history_limit — how many recent conversation messages are included when the engine assembles context for a turn. Default 30.
ambient_recall_enabled — when true, the brain proactively pulls a few traced memory snippets into context before each turn. Default true. Set false to disable proactive recall.
working_memory_decay_after — stale working-memory items stop surfacing after this inactivity window. Default 72h. Set 0s to disable decay.

Scheduler Timezone

agent: timezone: "America/Sao_Paulo"

IANA timezone used by the scheduler when interpreting times in scheduled messages (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:

mutiro start

Useful Commands

mutiro agents list # see all your agents mutiro agents get <agent-username> # agent details mutiro agents update-profile <agent-username> # change display name or bio mutiro agents regenerate-key <agent-username> # new API key mutiro agents delete <agent-username> # delete an agent mutiro agent doctor # diagnose issues