# M1K3 — install recipe
# https://m1k3.app/install.txt · the text version of https://m1k3.app/install
# Updated 2026-09-15. For coding agents, and for people who prefer text.

M1K3 is a private, on-device AI for macOS: local brains (MLX + Apple
Foundation Models), live voice, a knowledge graph over the user's documents,
a memory graph, and an MCP server on loopback. Free for humans, no account,
no telemetry. Source: https://github.com/Round-Tower/M1K3 (FSL-1.1-ALv2).

REQUIREMENTS
  An Apple Silicon Mac on macOS 26 (Tahoe) or later. Intel Macs cannot run it
  (arm64 only; every brain runs on Metal). No account, key, or subscription.

STEP 1 — GET THE APP
  Homebrew (also puts the `m1k3` command on PATH; Homebrew 6 needs the trust
  line first):
    brew trust round-tower/tap
    brew install --cask round-tower/tap/m1k3
  Without Homebrew: download the signed, notarized DMG and drag it to
  /Applications —
    https://github.com/Round-Tower/M1K3/releases/latest/download/M1K3.dmg
  The command-line client then lives at
    /Applications/M1K3.app/Contents/Helpers/m1k3
  Mac App Store: 1.0 was submitted to App Review on 2026-09-15; until it is
  live the TestFlight beta is the same lane — https://testflight.apple.com/join/Fxp2F5Je
  Note: the App Store copy of `m1k3` is sandboxed, so its `connect` prints
  the config instead of writing it. Prefer Homebrew or the DMG for agents.

STEP 2 — OPEN IT ONCE
    open -a M1K3
  First run picks Mini, Apple's on-device model: instant, nothing to download.
  The upgrade to Lil (Qwen 3, about 2.2 GB, downloaded once from Hugging Face)
  is offered after the first answer and in Settings. Big (Gemma 4 12B) is
  offered on 16 GB Macs and up. These are the user's clicks: an agent should
  ask, not start a 2 GB download on its own.

STEP 3 — TURN THE SERVER ON, THEN CONNECT
  The MCP server is OFF by default and lives inside the app. Ask the user to
  turn it on once: M1K3 ▸ Settings ▸ Privacy ▸ MCP server → On. It then serves
    http://127.0.0.1:4242/mcp
  while the app is open, bound to loopback only, one client at a time. There
  is no flag or defaults key that flips it from a shell; that is deliberate.

  Then wire your client (one of: claude | codex | cursor | vscode | zed):
    m1k3 connect claude
  What each does:
    claude  runs `claude mcp add --transport http -s user m1k3 http://127.0.0.1:4242/mcp`
    cursor  edits ~/.cursor/mcp.json (keeps other servers; one .bak the first time)
    vscode  edits ~/Library/Application Support/Code/User/mcp.json (same rules)
    codex   prints the [mcp_servers.m1k3] TOML for ~/.codex/config.toml
    zed     prints the "context_servers" entry for ~/.config/zed/settings.json
  Add --print to see the config without touching a file. Without the CLI, any
  MCP client that speaks streamable HTTP can point at the URL above directly.

  Tell the agent it is there — folds a marker-fenced "M1K3 is the resident"
  block into the project's AGENTS.md (or --write PATH; re-running replaces it):
    m1k3 agent-notes --write

STEP 4 — VERIFY
    m1k3 status                      # JSON: brain, provider, speaking, queued …
    m1k3 speak "hello from the terminal"
    m1k3 ask "what can you do?"      # a real turn on the local brain
  A "disconnected" server almost always means the app is closed; `m1k3` opens
  it and waits up to 20 s for the port. If status still fails, the switch in
  Settings ▸ Privacy ▸ MCP server is off.

WHAT THE AGENT GETS (18 tools)
  ask_m1k3, get_answer, list_jobs — ask the local brain (long asks poll by job id)
  search_knowledge, list_documents, get_document — the user's own documents
  remember, recall_memory, related_memory, forget_memory, memory_stats — memory graph
  speak, stop_speaking, listen — voice in and out
  list_todos, propose_todo — read the list; propose only (the user accepts)
  get_status, open_link
  Details and the six things the server will not do: https://m1k3.app/agents

UNINSTALL
  brew uninstall --cask m1k3       (add --zap to remove its data)
  or drag M1K3 out of /Applications. All data, including downloaded weights,
  lives in ~/Library/Containers/app.m1k3 — remove that and nothing remains.
  `m1k3 connect <client> --print` shows the one config entry to take out.

PRIVACY
  Three documented network crossings, all user-started: the app download, an
  optional one-time model download, and web-search tools that are off by
  default. Nothing said to M1K3 leaves the Mac. https://m1k3.app/privacy