# Set up MUON on this machine

> Paste this whole page into your coding agent, or tell it: "Read https://docs.getmuon.com/agent-setup.md and follow it to set up MUON."

You are the coding agent I am talking to. Install and configure MUON (https://getmuon.com), a
local-first orchestrator and shared memory for coding agents: the `muon` CLI, its MCP server
(`muon-mcp`) and the MUON desktop app. Work one step at a time, tell me what each command does
before you run it, and stop to ask me whenever a step needs my decision, my password or my browser.

## Ground rules
- Never pipe a downloaded script into a shell. Download it, verify it, then run it.
- Ask before installing anything (Node, git, an agent CLI) and before any `sudo`.
- Never print, copy or open token or credential files (anything under `~/.muon/`, vendor auth files).
- Do not disable or route around a security check (signature, Gatekeeper, sign-in). If one fails, stop and show me.
- If `muon --version` already prints a version, skip to step 5.

## 1. Check the machine
Run `uname -s`, `uname -m` and `sw_vers -productVersion`.
- macOS on Apple Silicon (`Darwin` + `arm64`) is supported. Continue.
- Intel Mac, Linux or Windows: tell me the desktop app and local brain are Apple Silicon only today, and stop.
Then check, and report a short table:
- `node --version`: REQUIRED, 20.10 or newer (24 recommended). If missing or older, offer: `brew install node@24`,
  the installer from https://nodejs.org/en/download, or `nvm install 24` / `fnm install 24` / `volta install node@24`. Ask which.
- `git --version`: REQUIRED. If missing, offer `xcode-select --install`.
- Agent CLIs, OPTIONAL but MUON needs at least one to do work: `claude`, `codex`, `cursor-agent`, `opencode`,
  `kiro-cli` (and `grok` for Grok Build, which can connect to MUON but is not a crew lane). Say which are on PATH.
  Install one only if I ask, from that vendor's official instructions; if it ships as a shell script, download it and show me first.

## 2. Download and verify the installer
Make an empty folder (`mkdir -p ~/muon-install && cd ~/muon-install`), save this as `verify.mjs`, and run `node verify.mjs`:

```js
import { createHash, createPublicKey, verify } from "node:crypto";
import { writeFileSync } from "node:fs";
// MUON release-manifest key. Cross-check the keyId at https://docs.getmuon.com/release-keys
const KEY = "MCowBQYDK2VwAyEAj38Q783SKDGtQhxTS24pOX2UMgsPipkL1RzlnJHpFxY=";
const KEY_ID = "e63d771f74c661945d3674cf633b8b07d7628536ba9783a958e13b91f341cbb6";
const get = async (url) => { const r = await fetch(url); if (!r.ok) throw new Error(`${url}: HTTP ${r.status}`); return Buffer.from(await r.arrayBuffer()); };
const der = Buffer.from(KEY, "base64");
if (createHash("sha256").update(der).digest("hex") !== KEY_ID) throw new Error("key fingerprint mismatch");
const channel = JSON.parse(await get("https://download.getmuon.com/channels/stable.signed.json"));
const { version } = JSON.parse(Buffer.from(channel.payload, "base64"));
if (!/^\d+\.\d+\.\d+$/.test(version)) throw new Error("unexpected version");
const installer = await get("https://getmuon.com/install.sh");
const signature = await get(`https://download.getmuon.com/releases/${version}/install.sh.sig`);
const key = createPublicKey({ key: der, format: "der", type: "spki" });
if (!verify(null, installer, key, signature)) { console.error("SIGNATURE INVALID. Do not run install.sh."); process.exit(1); }
writeFileSync("install.sh", installer);
console.log(`install.sh verified for MUON ${version}`);
```

Use Node for this: the `openssl` that ships with macOS cannot check this signature type.
If it prints anything other than "verified", stop and show me. Do not run an unverified installer.

## 3. Install
Run `bash install.sh`. It verifies every download itself and installs `muon`, `muon-tui`, `muon-mcp`
and, on macOS, `/Applications/MUON.app` (the app carries MUON's local brain).
- If MUON.app already exists, the installer leaves it alone. Ask me before adding `--replace-desktop`.
- Then open a new shell, or follow the PATH line the installer printed, and confirm `muon --version`.

## 4. Open the desktop app once
Ask me to open `/Applications/MUON.app`. It is not yet signed by Apple, so macOS may block the first launch:
I click System Settings, then Privacy & Security, then "Open Anyway". Do not remove quarantine flags yourself
unless I ask. Approvals for agent work are answered in this app, so it should be running.

## 5. Sign in, connect agents, start MUON
1. Run `muon setup --check --json` and summarise what is ready and what is missing.
2. Run `muon login`. It prints a URL and a one-time code. Give me both and wait while I approve in my browser.
3. Run `muon setup --yes --json --vendors <ids>`, where `<ids>` are the agent CLIs I want connected
   (always include the one you are: `claude-code`, `codex`, `cursor`, `opencode`, `kiro` or `grok`).
   This registers MUON's MCP server with them and starts the brain and runner. It installs no software.
4. If `muon setup --help` does not list `--check` or `--yes` (an older MUON), use
   `muon setup --vendors <ids> --no-interactive --json` instead.

## 6. Connect this session
- Tell me to restart this agent session: a running session keeps the MCP servers it started with.
- Optional: a coordinator seat lets one session size a crew and dispatch work, with every approval still mine.
  Ask me first; if I say yes, run `muon mcp attach <your id>` from the repository I want to work in.

## 7. Verify
Run `muon doctor`, then `muon mcp status <your id>` and `muon mcp probe <your id>`. Report the result.
If everything is ready, suggest `muon quickstart` inside a git repository as a first run.

## If something fails
- Exit code 12 or "MUON is locked": run `muon login`, then repeat step 5.3.
- "No agent CLI to set up": install one (step 1) or name it with `--vendors`.
- `muon` or `muon-mcp` not found: open a new shell, check the PATH line from the installer, run `muon doctor`.
- The brain does not start: confirm MUON.app is installed and has been opened once, run `muon start`, then `muon doctor --verbose`.
- An agent CLI is installed but not signed in: I run its own login (`claude auth login`, `codex login`,
  `cursor-agent login`, `opencode auth login`, `kiro-cli login`). Kiro first: `muon kiro doctor`.
- MUON vanished from an agent's tools later: `muon setup --repair` (or `muon doctor --fix`).
- Anything else: show me the exact output and open https://docs.getmuon.com/troubleshooting.