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. Tools come from the agent's image and are managed per agent from the agent's Tools tab.

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	`["./shared"]` in generated configs	Additional directories all users can read/write
`tts_voice`	string	—	Text-to-speech voice used by the `send_voice_message` tool
`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
`presence_enabled`	bool	`true`	Publish online presence for the agent
`reconnect_delay`	duration	`5s`	Wait between message-stream reconnect attempts
`heartbeat_interval`	duration	`30s`	Presence heartbeat interval
`chat_transport`	string	`loopback`	Internal host↔brain transport (`loopback` \| `stdio`)
`daemon.host` / `daemon.port`	string / int	auto-discovered `50050`–`50100`	Local daemon control endpoint
`path_policy`	map	—	Path rules: top-level `denied_paths`/`read_only_paths` apply to everyone; `owner:`/`user:` blocks layer on per role

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 (low = deterministic, 1 = creative); `0` is treated as unset and falls back to `0.7`
`max_tokens`	int	`28000`	Maximum response length (output cap)
`context_budget`	int	`0` (model-sized auto)	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
`top_p`	float	`0.9`	Nucleus sampling cap
`max_tool_iterations`	int	`200`	Tool-call loop limit per turn
`trace_level`	string	—	Engine tracing (`standard` \| `full`)

Root level (outside agent:):

Field	Type	Default	Purpose
`api_endpoint`	string	production API	Backend endpoint (set by `--config` environment files)
`use_tls`	bool	`true`	TLS to the backend
`debug`	bool	`false`	Verbose local logging
`sandbox.enabled`	bool	on under Desktop supervision	Kernel sandbox (Seatbelt on macOS, Landlock on Linux)
`sandbox.fail_closed`	bool	`false`	Refuse to start when the sandbox can only be partially applied; total unavailability always refuses unless `sandbox.allow_unsandboxed` is set
`live.*`	map	—	Live-call relay settings (`relay_url`, `relay_public_base_url`, `relay_tunnel_token`)

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 have no effect — the platform copies are authoritative and enforced server-side — and the profile keys are 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

Hosted agents get the tool list their image declares (the base image leaves out the git tools, the Dangerous group, and the local planning tools thinking, TodoWrite, and working_memory_*) and are configured from the agent's Tools tab in the app, not from this file.

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
`show_workspace_file`	Present an existing workspace file in this conversation	Yes
`respond_to_action`	Return a result to a workspace page	Yes
`test_handler`	Run a page's handler with a payload to test it	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 (owner only)	Yes
`conversation_read`	Read raw messages from one conversation (owner only)	Yes
`conversation_message_get`	Fetch one raw conversation message by ID (owner only)	Yes
`get_audio_transcript`	Fetch the transcript of a voice message	Yes
`conversation_search`	Search historical recall entries in one conversation (owner only)	Yes
`conversation_search_result_get`	Open a conversation search result by entry ID (owner only)	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	Yes
`web_fetch`	Fetch and extract content from a URL	Yes

web_search runs through Mutiro's search service using your agent's API key — no search-provider account or key is needed. A generous daily per-agent quota applies.

Supabase (requires an active Supabase connection)

Tool	Description	Default
`supabase_sql`	Read and write rows with SQL; requires Supabase connection	Yes
`supabase_admin_sql`	Change the schema with SQL (owner only); requires Supabase connection	Yes

The agent connects directly to Supabase using scoped credentials supplied by Mutiro. Restart the agent after changing connection or access settings.

Gmail (requires an active Gmail connection)

Tool	Description	Default
`bkper_books`	List bound books and the default. Requires Bkper connection	Yes
`bkper_accounts`	List accounts and groups in a bound book. Requires Bkper connection	Yes
`bkper_transactions`	Query a bounded page of ledger transactions. Requires Bkper connection	Yes
`bkper_balances`	Get ledger balances for a query. Requires Bkper connection	Yes
`bkper_record`	Create a draft transaction, optionally with workspace file attachments or links. Requires Bkper connection	Yes
`bkper_post`	Post an existing draft transaction. Requires Bkper connection; owner only by default; owner may open to users	Yes
`bkper_check`	Check or uncheck a transaction. Requires Bkper connection; owner only by default; owner may open to users	Yes
`bkper_trash`	Trash or recover a transaction. Requires Bkper connection; owner only by default; owner may open to users	Yes
`gmail_search`	Search email in the connected Gmail account	Yes
`gmail_read`	Read an email from the connected Gmail account	Yes
`gmail_draft`	Save a draft in the connected Gmail account without sending	Yes
`gmail_send`	Send email from the connected Gmail account (owner only)	Yes

Email (the agent's own platform email address; not yet generally available)

Tool	Description	Default
`email_send`	Send email from the agent's address	Yes
`email_reply`	Reply on an existing email thread	Yes
`email_read`	Read an email	Yes
`email_list_threads`	List email threads	Yes
`email_get_attachment`	Download an email attachment	Yes

Sheets (opt-in)

Tool	Description	Default
`sheet_create`	Create a spreadsheet	No
`sheet_list`	List the agent's spreadsheets	No
`sheet_read`	Read sheet data	No
`sheet_update`	Update sheet data	No
`sheet_export`	Export a sheet to a file	No
`sheet_import`	Import a file into a sheet	No
`share_sheet`	Share a sheet with a user	No
`sheet_delete`	Delete a spreadsheet	No
`sheet_copy`	Copy a spreadsheet	No

Gmail tools activate only when the agent has an active Gmail connection. Manage connections with mutiro agents connections or the Connections tab in the Desktop app's agent management — Mutiro brokers the authorization and holds the credentials; the agent only ever receives short-lived access tokens.

Scheduler

Tool	Description	Default
`schedule_message_create`	Schedule a message to send later (owner only)	Yes
`schedule_message_list`	List scheduled messages (owner only)	Yes
`schedule_message_cancel`	Cancel a scheduled message (owner only)	Yes

Planning

Tool	Description	Default
`thinking`	Record private reasoning notes	No
`Skill`	Use a reusable skill	Yes
`install_skill`	Install a skill from an uploaded ZIP, URL, or local directory (owner only)	Yes
`TodoWrite`	Track task checklist	No
`Task`	Delegate to a helper agent (owner only)	Yes

Owners can upload a skill ZIP and ask the agent to install it with install_skill, using its workspace path, for example Downloads/explorable.zip. The ZIP must contain SKILL.md at its root or inside one enclosing folder. Installation copies the skill and its assets into .genie/skills/<name>/; it does not run package scripts and needs no shell, Python, or unzip command. The skill is discovered on the next skill lookup or conversation turn. ZIP URLs and local skill directories are also supported; git repository sources require git on the agent's host.

Dangerous (owner-only by registry policy, off by default)

Tool	Description
`bash`	Run shell commands in the workspace
`process`	Inspect or control running processes
`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 take extra tuning. Put those under genie.tool_config, keyed by tool family:

agent: genie: tool_config: web: fetch_mode: focused max_chars: 3500 max_chunks: 3

The web family settings apply to web_fetch (page retrieval). web_search has no per-agent settings — result caps and quotas are enforced by the platform.

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