Set up Kiro for MUON

• kiro-cli installed, with kiro-cli-chat beside it. The installer puts both in ~/.local/bin.
• A kiro-cli recent enough to have --agent-engine v2. MUON needs it to stream the agent's work. MUON was verified with 2.23.1 and 2.24.0, and muon kiro doctor checks your copy.
• A way to sign in: a Kiro API key (recommended), or kiro-cli login.
• A MUON fleet with at least one Kiro seat.

curl -fsSL https://cli.kiro.dev/install | bash
# then open a new terminal so ~/.local/bin is on your PATH
kiro-cli --version

Already installed but older? Run kiro-cli update.

1. 01

   Recommended: an API key

   Create a key in your Kiro account (headless runs need a key on a paid plan). Put it in your login shell, so every terminal and the MUON app can find it:

   # ~/.zshenv (or ~/.bash_profile)
   export KIRO_API_KEY=<your Kiro API key>

   Then open a new terminal. MUON reads the key from its own environment or your login shell, passes it only to the Kiro process it starts, and hides it in any output. When a key is set, MUON runs Kiro in a private home, so an older kiro-cli login cannot override it.

2. 02

   Or: kiro-cli login

   kiro-cli login

   If you sign in with IAM Identity Center, your login must carry a Kiro profile. Without one, every request fails with profileArn is required for this request and only the auto model is listed. The profile is chosen while you sign in, so sign in again with your organisation's details and choose your profile when Kiro asks:

   kiro-cli logout
   kiro-cli login --license pro --identity-provider <your start URL> --region <your region>
   kiro-cli profile   # shows which profile is active (it does not change it)

   If that does not give you a profile, use the API key route above instead.

kiro-cli whoami
# "Authenticated with API key"          → the key route works
# "Logged in with IAM Identity Center"  → login route; check the profile below

kiro-cli chat --list-models --format json
# a list of models and a default_model → ready
# only "auto", or a profileArn error    → use an API key, or sign in again and choose a profile

muon kiro doctor runs these same read-only commands (it never logs you in or changes your profile) and reports the model count and default.

Kiro loads a project's own .kiro agents, hooks and MCP servers even when MUON pins its own agent. So MUON will not run Kiro in a folder that has any of:

• .kiro/settings/mcp.json
• a non-empty .kiro/hooks/
• a non-empty .kiro/agents/

Empty hooks or agents folders are fine. A symlinked or unreadable .kiro is refused. Move a file out of the way to use Kiro there, for example mv .kiro/settings/mcp.json .kiro/settings/mcp.json.off.

MUON can only send work to Kiro when Kiro has seats in the fleet. If Kiro shows 0 seats (for example on an install set up before Kiro was added), give it one to three:

muon fleet set --kiro 2
muon fleet               # check the counts

muon mcp install kiro                      # checks, then writes the user-scope file
muon mcp attach kiro --workspace <dir>     # optional: let your own kiro-cli chat coordinate a crew

muon mcp install kiro runs the setup check first and prints a checklist. If a step is blocking, it installs nothing and tells you what to fix. --force installs anyway. By default MUON writes the user-scope file (~/.kiro/settings/mcp.json, or under KIRO_HOME) directly, and it never calls kiro-cli mcp add. Avoid --scope project: it writes the repository's .kiro/settings/mcp.json, which MUON then refuses to run Kiro in.