When something looks wrong

MUON checks two things separately per vendor — installed and authenticated — and both muon doctor and muon onboard name which one is missing rather than a generic “not ready.”

Kiro has its own guided check: muon kiro doctor. The common Kiro problems (profileArn errors, only auto listed, 0 seats, a refused folder) and their fixes are on the Set up Kiro page.

Every lane can hold every role; the role decides the posture, not a shorter capability list. A write role (implementer, docs) runs the vendor's write shape inside MUON's own per-child sandbox; a read-only role (reviewer, QA, scout) is held to reads. If a dispatch is refused for a role, read the reason: on a host where MUON's sandbox profile is unavailable, Cursor and OpenCode are narrowed to their read-only roles and muon doctor names that, rather than promising a write dispatch it cannot start. That is the role model working, not a fault.

The v1 build is not signed with an Apple Developer ID certificate, so macOS quarantines MUON.app and calls it an app from an “unidentified developer” the first time you open it. You clear this once:

1. 01

   System Settings → Privacy & Security → “Open Anyway”

   Double-click MUON.app once. When macOS blocks it, open System Settings → Privacy & Security, scroll to the “MUON was blocked” notice and click Open Anyway. This is the path on current macOS. On older releases, Control-click (right-click) MUON.app, choose Open, then confirm.

There is no other behavioural difference — MUON still runs entirely on your machine. The Install page has the full first-launch walkthrough.

A distributed install stays locked until it is registered to your verified GitHub identity. Until then, every command except login, logout, doctor, version and a few others refuses, and muon setup and muon start print “MUON is locked” and exit with code 12.

muon login             # opens getmuon.com with a one-time code
muon setup             # run it again once sign-in succeeds

A checkout of the source repository is never gated — there is nothing to unlock there.

If a browser sign-in code expired, run muon login again and use the new code. Finish that flow before retrying setup. A successful GitHub connection and a registered MUON install are separate states; one can work while the other is still pending.

After a successful login, quit and reopen the desktop app, then run muon doctor --verbose to check the current state. If it reports registration pending, restore connectivity and let registration retry. If it reports an install grant issued in the future, correct your machine's clock first. Do not delete your memory or settings to clear a sign-in prompt.

If an agent CLI no longer lists MUON's tools, its MCP registration has usually drifted — an upgrade rewrote the config, a profile moved, or a claude mcp remove dropped it. muon doctor checks whether you are still registered where you asked to be, and both commands below re-apply the choice already recorded on this machine; neither invents a new one.

muon setup --repair    # re-register MUON in the agent CLIs you already chose
muon doctor --fix      # the same repair, from the doctor report

muon setup --check is a read-only pass over the prerequisites, your MUON registration and the brain — it changes nothing and tells you exactly what is missing.

muon setup --check

One common line it surfaces: an agent CLI that is installed but not signed in. MUON drives your own login, so re-authenticate with the vendor's own CLI (claude, codex login, cursor-agent login, opencode auth login, kiro-cli login) — MUON never logs you in.

MUON's embedded code graph indexes your workspace in the background as you commit. Check whether it has fallen behind HEAD:

muon version

The JSON includes brainCommit (what the graph is indexed at), headCommit (your actual HEAD) and stale (whether they disagree).

• From a terminal, muon graph reindex rebuilds the code graph for the workspace. Indexing is exclusive per repository, so it refuses to start a second run while one is already in progress.
• In the desktop app, open the graph/code panel and use Re-index — it's disabled while an index is already running, since indexing is exclusive per repository.
• The MCP server opportunistically refreshes freshness on certain reads (code_impact), so a short lag often clears on its own.
• A stale index degrades gracefully rather than lying: the orchestrator treats a stale or unindexed file as review-blind and routes it to a human rather than certifying a diff it can't see.

“The brain” is MUON's embedded local backend. The desktop app supervises its own; the CLI auto-spawns one on first use for every command except version, shutdown, custom-agents and most mcp subcommands, which are deliberately brain-independent.

muon start           # start the local brain and one persistent runner, then report readiness
muon doctor          # reports connectivity honestly, even if the brain is down
muon doctor --verbose # the full diagnostic JSON report
muon mcp status      # whether a brain is running, and its port/pid
muon shutdown        # stop the CLI-spawned brain + runner cleanly
muon chat            # any ordinary command re-spawns one if none is found

If the desktop app and a CLI-spawned brain both start, MUON detects and adopts the already-running one rather than starting a second — muon doctor tells you which profile you're actually talking to.

~/.muon/release/channel-state.json records the newest signed release this Mac accepted. That record blocks rollbacks.

If MUON reports that this file is corrupt, quit MUON.app, then move the file aside and run the updater:

mv ~/.muon/release/channel-state.json ~/.muon/release/channel-state.json.bad
muon update

The accepted-sequence history restarts. The version floor still applies: MUON will never accept a version older than the installed MUON.

Never delete this file to get past a “rollback refused” or “verification failed” message. Those are protections, not corruption.

1. 01

   Stop everything cleanly first

   Quit the desktop app, then run muon shutdown to stop any CLI-spawned brain and runner. Confirm nothing is left with muon doctor.

2. 02

   Wipe local state

   Delete ~/Library/Application Support/MUON/. This removes the embedded brain, the graph store, the lockfile and settings — including unconfirmed memory proposals. Export first with muon memory pack export --out <dir> if you want confirmed decisions back afterwards.

   Removing the data directory by hand is the current reset path — there is no muon reset command in v1.

3. 03

   Relaunch

   Reopen the app or run any muon command; MUON reinitializes a fresh brain and re-indexes the workspace the next time it needs to.

Send a mail with your muon doctor --json output attached — it never includes a credential value, only readiness booleans and reasons — to abhinavpandey1230@gmail.com.