Quickstart: Self-Hosted Agents

Use this guide when you want to run the Mutiro agent daemon yourself while keeping Mutiro's built-in Genie brain. If you want Mutiro to run the runtime for you, use the hosted quickstart. If you want to replace Genie with a different brain process, see swap the brain.

Prerequisites

macOS, Linux, or WSL
Mutiro CLI
A model provider key such as GEMINI_API_KEY, ANTHROPIC_API_KEY, or OPENAI_API_KEY, unless you use a local provider such as Ollama or LM Studio

Install the CLI:

curl -sSL https://mutiro.com/downloads/install.sh | bash mutiro version

mutiro auth signup <email> <username> "<display_name>"

Already have an account?

mutiro auth login <email>

2. Create a Self-Hosted Agent

Create the agent from the directory where you want its local runtime config to live:

mkdir -p ~/agents/my-assistant cd ~/agents/my-assistant mutiro agents create my_assistant "My Assistant" --objective "Help me stay organized and move daily work forward" --self-hosted

Save the generated API key immediately. It is shown once and starts with mut_key_.

echo 'MUTIRO_AGENT_API_KEY=mut_key_...' > .env

The create command also writes .mutiro-agent.yaml with hosting_mode: self_hosted.

3. Configure a Model Provider

The generated config uses Genie. By default, Genie uses genai with gemini-3.5-flash.

For Gemini, put the provider key in .env:

echo 'GEMINI_API_KEY=your_key_here' >> .env

Genie can also use Anthropic, OpenAI, Ollama, and LM Studio through .mutiro-agent.yaml:

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

Use ANTHROPIC_API_KEY or OPENAI_API_KEY for hosted providers. Local providers such as Ollama and LM Studio do not require a Mutiro-side model API key.

4. Configure Tools if Needed

For a first self-hosted Genie agent, you can omit tools: and use the default self-hosted tool set.

Add an explicit tools: list only when you want to restrict tools or enable opt-in tools such as web_search, thinking, TodoWrite, working_memory_get, working_memory_update, bash, process, install_skill, or code.

agent: genie: tools: - name: readFile - name: writeFile - name: send_message - name: web_search - name: code owner_only: true

When tools: is present, it is the complete enabled list. Include every tool you still want available.

5. Start the Agent

source .env mutiro start

Keep the process running. Your agent is online while the daemon is connected to Mutiro.

6. Send a Test Message

In another terminal:

mutiro user message send <agent-username> "Hello! Who are you?"

You can also use the web app, desktop app, mobile apps, or mutiro chat.