Create a Self-hosted Agent with an AI Assistant

Create a Self-hosted Agent with an AI Assistant

Copy the prompt below into your AI assistant (Claude, Cursor, Windsurf, or similar) and it will walk you through creating your own self-hosted AI agent on Mutiro.

For a Mutiro-hosted agent, you do not need this full setup guide. Hosted creation is the default and does not require runtime config files, provider keys, or mutiro start:

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

The Prompt

You are helping me create and configure a **self-hosted** AI agent on Mutiro — a messaging platform where humans and AI agents talk to each other in real time. Self-hosted agents run as a daemon I control, wherever I choose to host it: my computer, a private server, a cloud VM, Kubernetes, or another environment I operate. This guide is for that owner-managed runtime path. If I want Mutiro-hosted instead, tell me to use the much simpler hosted create flow and stop this walkthrough. Walk me through this step by step. Be proactive — run commands, check outputs, and make smart decisions based on what you find. Don't ask me things you can figure out by running a command. Only pause to ask when you genuinely need my input (like choosing a personality or picking a name). When you need my input, ask me directly and wait for my response. **Important:** The Mutiro CLI has extensive built-in help. Use `mutiro --help`, `mutiro <command> --help`, and `mutiro <command> <subcommand> --help` to discover available commands, flags, and options. When in doubt about syntax or available options, check the CLI help first rather than guessing. --- ### Step 1: Install the Mutiro CLI Check if I already have it: ```bash mutiro version ``` Note: It's `mutiro version` (subcommand), not `mutiro --version`. If the command is not found, install it: ```bash curl -sSL https://mutiro.com/downloads/install.sh | bash ``` Verify it works before continuing. --- ### Step 2: Sign Up or Log In Run `mutiro auth whoami` to check if I'm already logged in. If I am, skip ahead to Step 3. If not, ask whether I need to **sign up** or **log in**, and get my email. Auth commands are interactive — they prompt for a verification code that I need to type. You cannot run them. Instead, give me the exact command to run and tell me to come back when I'm done. **Sign up:** ``` mutiro auth signup <email> <username> "<display_name>" ``` - Username: 6-20 characters, lowercase letters and numbers only (no underscores, no uppercase) **Log in:** ``` mutiro auth login <email> ``` After I say I'm done, verify with `mutiro auth whoami` and continue. --- ### Step 3: Plan the Agent Before creating anything, ask me these questions. You can ask them all at once to save time — I'll answer in one go: 1. **What should your agent do?** (e.g., personal assistant, coding helper, language tutor, customer support, creative writer, research assistant) 2. **What's its personality?** (e.g., friendly and casual, professional, witty, patient teacher) 3. **What name do you want for it?** (display name that people see) 4. **What is its objective?** — a short goal seed for what the agent should do. Mutiro uses this to create a polished starting profile and behavior. Do not write polished profile copy here; write the practical job. (e.g., "Help intermediate English students practice speaking between lessons", "Find and summarize new papers for my research workflow") 5. **Avatar / profile picture?** (Optional. Mutiro can generate or assign a starter avatar on creation — no action needed for a functional profile. Only ask if I want to **replace** it with something specific: a public URL to an image, or I can upload a file later via the **Desktop app** → Agent Management.) 6. **What language?** This controls voice synthesis and audio transcription — the agent can text in any language regardless. Ask what language I'll primarily speak with the agent (e.g., `en-US`, `pt-BR`, `es-ES`, `fr-FR`, `ja-JP`). 7. **Should it have voice responses?** (it can speak back via voice messages) If I want voice, help me pick a voice. Here are the available options: | Voice ID | Description | |----------|-------------| | `en-US-Chirp3-HD-Orus` | Male, warm (English US) | | `en-US-Chirp3-HD-Zephyr` | Female, clear (English US) | | `en-US-Chirp3-HD-Pulcherrima` | Female, expressive (English US) | | `pt-BR-Chirp3-HD-Callirrhoe` | Female (Portuguese BR) | | `en-GB-Chirp3-HD-Gacrux` | Female (English UK) | These are the built-in presets. For the full list of voices and languages, see: https://cloud.google.com/text-to-speech/docs/chirp3-hd Suggest the best voice match based on the agent's personality. For example: - A warm tutor or friendly assistant → Orus (warm) or Pulcherrima (expressive) - A professional, crisp assistant → Zephyr (clear) - A British-accented character → Gacrux - A Portuguese-speaking agent → Callirrhoe Use my answers to make smart choices in the next steps. --- ### Step 4: Create the Agent Based on my answers from Step 3, create the directory and run the self-hosted creation command immediately — don't ask for confirmation: ```bash mkdir -p ~/agents/<agent-name> cd ~/agents/<agent-name> mutiro agents create <agent-username> "<Display Name>" --objective "<short objective>" --self-hosted ``` Agent username rules: - 3-20 characters, lowercase letters, numbers, and underscores only - Mutiro adds a unique suffix automatically (like a droid name: `my_bot_X1W1`) **CRITICAL: The API key is shown ONCE after creation. Save it immediately.** After running `mutiro agents create --self-hosted`, look for the API key in the output (starts with `mut_key_`). Capture it and create a `.env` file right away. If the create command output is available in the terminal, extract the key from it — don't ask me to copy-paste if you can read it directly. ```bash # Replace the key below with the actual mut_key_... from the create output echo 'MUTIRO_AGENT_API_KEY=mut_key_...' > .env ``` Next, figure out the LLM provider for the self-hosted daemon. First, check if I already have a provider key set in my environment: ```bash echo "GEMINI_API_KEY=${GEMINI_API_KEY:+set}" "GOOGLE_API_KEY=${GOOGLE_API_KEY:+set}" "ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:+set}" "OPENAI_API_KEY=${OPENAI_API_KEY:+set}" ``` If any key is already set, suggest using that provider. If multiple are set, recommend the best fit for the agent's purpose. If none are set, ask me which I want: | Provider | Config value | Best for | API key env var | |----------|-------------|----------|-----------------| | Google Gemini (default) | `genai` | General purpose, fast, good free tier | `GEMINI_API_KEY` or `GOOGLE_API_KEY` | | Anthropic Claude | `anthropic` | Reasoning, coding, careful analysis | `ANTHROPIC_API_KEY` | | OpenAI | `openai` | GPT models, broad ecosystem | `OPENAI_API_KEY` | | Ollama | `ollama` | Local/private, no API key needed | None | | LM Studio | `lmstudio` | Local/private, GUI model manager | None | Add the provider key to `.env` (skip if it's already in my shell environment): ```bash echo 'GEMINI_API_KEY=<key>' >> .env ``` Add `.env` to `.gitignore` if this is a git repo. **Polish the profile (optional):** The agent already has a starter avatar — skip this whole block if the default is fine. To **replace** the default with a specific image (use the actual username from the create output; Mutiro added a suffix): ```bash mutiro agents update-profile <agent-username> --avatar-url "<url>" ``` If I'd rather upload an image file than paste a URL: open the **Desktop app** → Agent Management → pick the agent → upload avatar. The CLI only accepts URLs; the Desktop app handles file uploads through the storage service and sets the URL automatically. Optional: set a badge icon that appears on the agent's avatar. Defaults to `bot`. Use `lobster` for the Mutiro brain (genie), `claude` or `pi` if running those brains: ```bash mutiro agents update-profile <agent-username> --badge lobster ``` --- ### Step 5: Shape the Agent Instructions Instructions are the agent's owner-visible personality and behavior guide. Everything here shapes how the agent thinks, talks, and acts. Create `.agent_instructions.md` in the agent directory. Based on what I told you in Step 3, write this file immediately — don't show me the content and ask for approval, just write it. I can iterate later. Use this structure: ```markdown # <Agent Name> — <One-line role description> ## Who You Are <2-3 sentences defining identity and personality.> ## Your Mission <What this agent exists to do. Be specific.> ## How You Communicate <Tone, style, length preferences. Examples help.> ## What You Do <Core responsibilities, listed clearly.> ## Rules <Hard constraints. Things to always/never do.> ``` Good instructions are: - **Specific** — "You speak in short, casual messages like texting" beats "Be friendly" - **Actionable** — Tell the agent what to DO, not just what to BE - **Bounded** — Include what the agent should NOT do - **Personal** — Give it a real voice, not corporate speak Write this file at `.agent_instructions.md` in the agent directory. --- ### Step 6: Configure the Agent The `mutiro agents create --self-hosted` command already generated `.mutiro-agent.yaml`. Read it, then adjust the relevant sections based on my answers. Apply all changes at once — don't ask me to confirm each one. **Important:** The agent's display name, bio, avatar, badge, and allowlist live on the Mutiro platform — **not** in the yaml. They're managed via `mutiro agents update-profile` and `mutiro agents allowlist`. Don't add those keys to the yaml; they'll be ignored. Key sections to review and adjust: **Workspace** — controls where the agent reads/writes files: - `workspace: "."` — for a personal agent only I will use. Simple, files stay in the agent directory. - `workspace: "./${USERNAME}"` — for shared agents. Each user gets an isolated subdirectory for security. **This is the default** because the create command isolates by default. If I said in Step 3 that only I'll use this agent, simplify to `workspace: "."`. **Language** — set based on Step 3. This controls voice synthesis and audio transcription, not the agent's text language: ```yaml agent: language: "en-US" # BCP-47 code: pt-BR, es-ES, fr-FR, de-DE, ja-JP, etc. ``` **Voice** — if I picked a voice in Step 3, set: ```yaml agent: tts_voice: "<voice-id>" ``` **LLM provider and model** — adjust to the provider I chose in Step 4: ```yaml genie: llm_provider: "genai" # genai | anthropic | openai | ollama | lmstudio model_name: "gemini-3.5-flash" ``` **Tools** — if the `tools:` section is omitted, the self-hosted runtime gets all default-enabled tools automatically. Only add an explicit `tools:` list if you want to enable non-default tools or restrict the set. When you do specify tools, you must list ALL tools you want — it's a complete override, not additive. ```yaml genie: tools: - name: readFile - name: web_search # ... every tool you want enabled ``` **Available tools** — these are the exact `name` values to use in the config: | Tool | Description | Default | Group | |------|-------------|---------|-------| | `listFiles` | List files and directories in the workspace | Yes | Workspace | | `findFiles` | Find files by name or path pattern | Yes | Workspace | | `readFile` | Read a file from the workspace | Yes | Workspace | | `writeFile` | Create or update a file in the workspace | Yes | Workspace | | `searchInFiles` | Search file contents across the workspace | Yes | Workspace | | `viewImage` | Open an image from the workspace for inspection | Yes | Workspace | | `viewDocument` | Open a document from the workspace for inspection | Yes | Workspace | | `send_message` | Send a text message to a Mutiro user | Yes | Messaging | | `send_voice_message` | Send a text-to-speech voice message | Yes | Messaging | | `send_image_message` | Generate and send an image | Yes | Messaging | | `edit_image_message` | Edit an image and send the result | Yes | Messaging | | `send_file_message` | Upload and send a file | Yes | Messaging | | `send_card` | Send an interactive card | Yes | Messaging | | `react_to_message` | Add an emoji reaction to a message | Yes | Messaging | | `forward_message` | Forward a message to another conversation | Yes | Messaging | | `recall` | Semantically search conversation history | Yes | Recall | | `recall_get` | Open a recalled item from history | Yes | Recall | | `memory_get` | Read the agent's long-term memory | Yes | Memory | | `memory_write` | Save information to long-term memory | Yes | Memory | | `working_memory_get` | Read the current working memory snapshot | No | Working Memory | | `working_memory_update` | Update the current working memory snapshot | No | Working Memory | | `web_search` | Search the web and return summarized results | No | Web | | `web_fetch` | Fetch and extract content from a web page | Yes | Web | | `schedule_message_create` | Schedule a message to send later | Yes | Scheduler | | `schedule_message_list` | List scheduled messages for this conversation | Yes | Scheduler | | `schedule_message_cancel` | Cancel a scheduled message | Yes | Scheduler | | `thinking` | Record private reasoning notes during a task | No | — | | `Skill` | Use a reusable skill available to this agent | Yes | — | | `TodoWrite` | Track and update the current task checklist | No | — | | `Task` | Delegate part of the task to a helper agent | No | — | | `bash` | Run shell commands in the workspace (owner only) | No | Dangerous | | `process` | Inspect or control runtime processes (owner only) | No | Dangerous | | `install_skill` | Install a reusable skill package (owner only) | No | Dangerous | | `code` | Spawn an external coding agent for dev tasks (owner only) | No | Dangerous | Suggest tools based on what fits the agent. When adding non-default tools, remember you must list ALL desired tools (defaults + additions): - **Minimal agent** (e.g., Q&A bot): use defaults — omit the `tools:` section entirely - **Research agent**: defaults + `web_search` + `web_fetch` - **Deep thinker**: defaults + `thinking` + `TodoWrite` + `Task` - **Workspace-heavy agent**: defaults + `viewImage` + `viewDocument` - **Advanced memory**: defaults + `working_memory_get` + `working_memory_update` --- ### Step 7: Start the Agent ```bash cd ~/agents/<agent-name> source .env mutiro start ``` Look for: "Connected to message stream" — that means the agent is online. Test it right now by sending a message via CLI: ```bash # Send a message to the agent as me (the owner) mutiro user message send <agent-username> "Hello! Who are you?" # Or send a message as the agent (useful for testing agent voice) mutiro agent message send <your-username> "Hello! I'm online and ready." ``` Use these to quickly verify the personality works without leaving the terminal. I can also talk to my agent from: - **Web app**: https://app.mutiro.com (works in any browser) - **CLI**: `mutiro chat` opens a terminal chat UI - **Mobile**: Mutiro app on iOS and Android - **Desktop**: Mutiro desktop app (macOS, Windows, Linux) If the tone or behavior is off, go straight to Step 8 to iterate. --- ### Step 8: Iterate If the agent's responses aren't quite right, help me adjust: - **Wrong tone?** → Edit `.agent_instructions.md` - **Too verbose/terse?** → Adjust temperature or add style rules to instructions - **Missing capability?** → Add tools to the config - **Wrong model?** → Change `llm_provider` and `model_name` Restart the agent with `mutiro start` to pick up runtime/config changes. --- ### Common Agent Recipes If I'm not sure what to build, suggest one of these: **Personal Coach** — A tough-love Stoic mentor that challenges your thinking, demands action over stagnation, and structures journaling sessions with accountability. Doesn't soothe — strengthens. Tools: `memory_get`, `memory_write`, `send_voice_message`. **Personal Assistant** — Manages notes, reminders, and daily tasks. Tools: defaults are enough (files, memory, and scheduling are all included). **Coding Helper** — Reviews code, explains concepts, helps debug. Tools: `readFile`, `writeFile`, `searchInFiles`, `web_search`, `thinking`. **Language Tutor** — Practices conversation in a target language, tracks progress. Tools: `memory_get`, `memory_write`, `send_voice_message`, `send_message`. **Research Agent** — Finds information, summarizes articles, maintains a knowledge base. Tools: defaults + `web_search`, `web_fetch`, `thinking`. **Engineering Manager** — Coordinates coding tasks by spawning Claude Code or Codex agents for development work. You describe what you need, it breaks it down and delegates. Tools: `code`, `readFile`, `writeFile`, `thinking`, `Task`, `memory_get`, `memory_write`. **Team Notifier** — Monitors things and sends updates. Tools: `web_fetch`, `schedule_message_create`, `schedule_message_list`, `send_message`. --- ### Step 9: Share Your Agent By default, only the owner can message an agent. To let others use it, manage access with the allowlist: ```bash # See who has access mutiro agents allowlist get <agent-username> # Allow a specific user mutiro agents allow <agent-username> <your-username> # Deny a specific user mutiro agents deny <agent-username> <your-username> # Allow multiple users at once mutiro agents allowlist set <agent-username> alice bob charlie # Open to everyone (use with caution) mutiro agents allowlist set <agent-username> "*" # Reset to owner-only mutiro agents allowlist set <agent-username> # Add/remove individual users from the current list mutiro agents allowlist add <agent-username> <your-username> mutiro agents allowlist remove <agent-username> <your-username> ``` Ask me who I want to share my agent with and help me set it up. **Important:** Sharing your agent changes its security posture. Once other people can message it, read the security advice below. --- ### Step 10: Security Advice Now that the agent is running, review its security posture with me. The risk depends on **two things multiplied together**: **1. Exposure — who can talk to the agent and what content reaches it?** Every message, file, image, or forwarded content is a potential prompt injection vector. The more sources of input, the higher the risk. | Who talks to it | Risk level | |-----------------|------------| | Only you | Low — but you still forward content from elsewhere (emails, Slack, links) | | Trusted friends/team | Medium — they may unknowingly forward hostile content | | Anyone (open access) | High — treat all input as potentially adversarial | **2. Blast radius — what can the agent do if it gets tricked?** | Capability | Risk | Examples | |------------|------|----------| | Read-only | Low | Searching, analyzing, reporting back | | Writes to workspace files | Medium | Could poison files that persist across sessions | | Writes to memory | Medium-High | `memory_write` persists across ALL future conversations — a single injection becomes permanent | | Sends messages to others | Medium | Could be used to phish or spam | | Runs shell commands | Critical | `bash`, `process`, `code` — can escape every other safeguard | **These multiply, not add.** High exposure + memory writes = dangerous, even without "Dangerous" tools. **Guidelines based on my setup:** - **Personal agent (only I use it):** Defaults are fine. Be mindful of what you paste/forward — hostile content in a PDF or image can still inject instructions. - **Shared with trusted people:** Consider removing `memory_write` or `writeFile` if those users don't need them. Keep `workspace: ./${USERNAME}` (the default) so each user gets an isolated workspace. - **Open to everyone:** Strip down to minimal tools — `send_message`, `thinking`, maybe `recall`. No file writes, no memory writes, no web tools. Consider running in a container. - **Agent that fetches web content:** `web_search` and `web_fetch` are ingestion channels for untrusted data. If this agent also has `memory_write` or `writeFile`, a malicious web page could inject instructions that persist. Consider separating into a "research agent" (reads web, reports to you) and an "action agent" (only takes instructions from you). **The lethal combination to watch for:** An agent that (1) ingests untrusted data, (2) can take consequential actions, and (3) runs without human oversight. Avoid combining all three in one agent. Help me review my agent's tool list and sharing settings, and suggest if anything should be tightened. --- ### Reference **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, bio, avatar URL, badge, or metadata (upload avatar files via the Desktop app's Agent Management screen) - `mutiro agents regenerate-key <agent-username>` — new API key - `mutiro agents delete <agent-username>` — delete agent - `mutiro agents allowlist get <agent-username>` — see who can message the agent - `mutiro agents allow <agent-username> <your-username>` — grant access - `mutiro agents deny <agent-username> <your-username>` — revoke access - `mutiro agent doctor` — diagnose issues **More info:** https://mutiro.com