Examples

Ready-to-use samples for configuring and extending muaz. See Providers & models and Plugins for the full reference.

Provider profiles (models.yaml)

Everything about model routing lives in one file, ~/.muaz/models.yaml: named connection profiles, the global default, and per-agent agents overrides. Agents are model-agnostic — they never name a provider — so this file is the single source of an agent’s model. Use ${ENV_VAR} for keys; the value is stored in your OS keychain (via muaz auth <profile> or the UI Providers page), never in the file.

~/.muaz/models.yaml

profiles:
  anthropic-main:
    type: anthropic          # native Anthropic provider (prompt caching on)
    default_model: claude-opus-4-8
    api_key: ${ANTHROPIC_API_KEY}
  openai-main:
    type: openai-compatible
    base_url: https://api.openai.com
    default_model: gpt-4o
    api_key: ${OPENAI_API_KEY}
  bedrock-work:
    type: bedrock
    region: us-east-1
    default_model: anthropic.claude-3-5-sonnet-20241022-v2:0
    profile: work
  local:
    type: ollama
    default_model: qwen3

# The global default points every agent (incl. the built-in `default`) here…
default: anthropic-main

# …and per-agent overrides bind one agent to a different profile (+ optional model).
agents:
  coding:
    profile: bedrock-work

Manage it from the CLI (muaz models list/set/default/bind), the UI Providers + Agents pages, or by editing the file. It’s re-read on every resolution, so changes take effect without a restart.

A complete sample plugin

A web-research plugin: a provider-agnostic agent, a skill, and a pipeline. The layout below is exactly what you’d zip and muaz plugins install.

web-research/
├── manifest.yaml
├── agents/
│   ├── researcher.yaml
│   └── researcher.md
├── skills/
│   └── web-digger/SKILL.md
└── pipelines/
    └── research-and-write.yaml

manifest.yaml — manifest v2 (manifest_version: 2 is required). This plugin declares only the built-in tools its agent needs; a richer manifest can also carry typed config:, hooks:, command-backed tools:, and knowledge: sources (see Plugins).

manifest_version: 2
name: Web Research
version: 0.1.0
description: Research agents + browsing skills
author: you
muaz: ">=0.2"
permissions:
  tools: [fetch_webpage, search, read_file]

agents/researcher.yaml — provider-agnostic, so it adopts the installing user’s default model (or a binding they set for it). Its prompt is co-located and referenced with a relative path, keeping the plugin portable.

name: researcher
description: "Researches a topic with web browsing and reports findings"
system_prompt: "./researcher.md"
streaming: true
max_iterations: 15
skills:
  allow:
    - web-digger
# One access level per tool (off | ask | auto). Anything not listed falls back
# to `default`; the browsing/read tools run without prompting.
tools:
  default: off             # this agent only needs the three tools below
  built_in:
    fetch_webpage: auto
    search: auto
    read_file: auto

agents/researcher.md

You are a meticulous research assistant.

Given a topic or question, plan a short set of queries, browse the web with
`fetch_webpage`, and corroborate claims across multiple independent sources.
Attribute every non-obvious fact to a source URL, then write a concise brief:
a one-line answer, key findings as bullets, and a "Sources" list.

Load the `web-digger` skill for the detailed browsing-and-extraction playbook.

skills/web-digger/SKILL.md

---
name: web-digger
description: Systematic web research — query planning, source triage, and extraction.
allowed-tools: fetch_webpage:* search:*
---

# web-digger

1. **Plan** — break the question into sub-questions and draft specific queries.
2. **Triage** — favour primary/authoritative sources; corroborate surprising claims.
3. **Extract** — pull only the facts that answer a sub-question, with their URLs.
4. **Synthesize** — one-line answer, cited findings, caveats, and a Sources list.

pipelines/research-and-write.yaml — agent names resolve across namespaces, so the plugin’s own agent is referenced with its qualified @web-research/ name.

name: research-and-write
description: "Research a topic, then draft from the sourced notes"
steps:
  - name: research
    agent: "@web-research/researcher"
    input: "Research this topic and produce sourced notes:\n\n${input}"
  - name: write
    agent: default
    input: |
      Write a clear piece on the request below, using only the research notes.

      Request:
      ${input}

      Research notes:
      ${steps.research.output}

Install it

zip -r web-research.zip web-research
muaz plugins install ./web-research.zip
muaz chat --agent @web-research/researcher

A registry index

The JSON index that muaz plugins install <name> / search fetch. Host your own and point muaz at it with plugin_registry in config.yaml or $MUAZ_PLUGIN_REGISTRY. sha256 is verified for integrity; an optional minisign_sig against muaz’s embedded publisher key sets the trust tier — a valid signature installs as verified, an unsigned entry as community (warned), and a present-but-invalid signature is rejected as tampered.

{
  "plugins": [
    {
      "name": "web-research",
      "version": "0.1.0",
      "description": "Research agents + browsing skills",
      "url": "https://example.com/muaz-plugins/web-research-0.1.0.zip",
      "sha256": "<sha256-of-the-zip>",
      "minisign_sig": "<optional minisign signature; unsigned → community tier>",
      "publisher_key_id": "E7620F1842B4E81F"
    }
  ]
}

export MUAZ_PLUGIN_REGISTRY="https://example.com/muaz-plugins/index.json"
muaz plugins search research
muaz plugins install web-research