# M1K3 — install recipe
# https://m1k3.app/install.txt · the text version of https://m1k3.app/install
# Updated 2026-10-02. 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, API 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, LOG IN, 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.

  Every request needs the server's access token (Authorization: Bearer m1k3_…);
  without it the answer is 401. The same Settings pane has it, masked, with a
  Copy button. Ask the user to Copy it and run, in their own terminal:
    m1k3 login
  and paste it there. `login` reads it with echo off (or from a pipe:
  pbpaste | m1k3 login), never from argv, checks it against the app when the
  app is running, and keeps it in the login keychain. An agent should not handle the token.

  Then wire your client (one of: claude | codex | cursor | vscode | zed):
    m1k3 connect claude
  What each does (every entry carries the token as an Authorization header):
    claude  runs `claude mcp add --transport http -s user m1k3 http://127.0.0.1:4242/mcp --header "Authorization: Bearer m1k3_…"`
    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,
  with the header "Authorization: Bearer <token from Settings>".

  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, either the
  switch in Settings ▸ Privacy ▸ MCP server is off, or the token is missing or
  stale (m1k3 says so; the user runs m1k3 login again, then connect).

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 seven 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
  Private by design. The documented network crossings: the app download, an
  optional one-time model download, and web search, which is on by default
  (one switch in Settings ▸ Privacy turns it off). Documents, memories and
  voice stay on the Mac; with web search on, a question M1K3 looks up goes out
  as a search. https://m1k3.app/privacy