mac-apple-silicon.json

{
 "profile": "mac-apple-silicon",
 "status": "preview",
 "description": "LocalRouter on one Apple Silicon Mac (unified memory, Metal): chat, Drama 3 speech and Whisper transcription kept warm, KnowLine decisions, Qwen-Image and Idol image to 3D on demand, each as an out-of-process server or cmd worker, served by a launchd user agent. Preview: tested on one M5 Ultra (docs/dev/MAC-PORT.md, Installing on a Mac).",
 "tested_on": "M5 Ultra (96 GiB unified memory, macOS 27), 2026-10-30: every model installed, qualified and served through the daemon; the launchd service installed, started, paired and removed on 2026-10-31",
 "hardware": {
  "arch": "arm64",
  "gpu": "Apple M",
  "unified_memory": true,
  "min_memory_gib": 64,
  "os": "macos 27"
 },
 "disk_margin_gib": 30,
 "env": {
  "LR_BIN": "$REPO/zig-out/bin/localrouter",
  "DEVELOPER_DIR": "${DEVELOPER_DIR:-/Applications/Xcode.app/Contents/Developer}",
  "STEPS": "bash $REPO/tools/install/steps.sh",
  "IMAGE_ROOT": "$J/image-mac",
  "CHAT_ROOT": "$J/chat",
  "DRAMA_ROOT": "$J/qualify-drama3/root",
  "DRAMA_MARKER": "$J/qualify-drama3/drama3-macos-qualification.json",
  "DRAMA_RESIDENT": "30870077440",
  "DRAMA_PORT": "$((PORT + 10603))"
 },
 "prereqs": [
  {
   "id": "commands",
   "title": "jq, curl, git, tar, xz, shasum, python3",
   "test": "for t in jq curl git tar xz shasum python3; do command -v $t > /dev/null || exit 1; done",
   "fix": "xcode-select --install; brew install jq xz"
  },
  {
   "id": "apple-silicon",
   "title": "an Apple Silicon Mac (arm64)",
   "test": "[ \"$(uname -s)/$(uname -m)\" = Darwin/arm64 ]",
   "fix": "none: Intel Macs have no unified memory for these models"
  },
  {
   "id": "zig",
   "title": "Zig 0.17.0 (builds LocalRouter)",
   "test": "zig version | grep -qx 0.17.0",
   "fix": "brew install zig (Homebrew ships 0.17.0), or the pinned archive in host.tools.zig"
  },
  {
   "id": "xcode-metal",
   "title": "Xcode with its licence accepted and the Metal Toolchain (xcrun metal: builds Metal kernels from source; prebuilt release archives do not need it). When xcode-select points at the Command Line Tools, builds need DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer",
   "test": "DEVELOPER_DIR=${DEVELOPER_DIR:-/Applications/Xcode.app/Contents/Developer} xcrun --find metal > /dev/null 2>&1",
   "fix": "install Xcode; sudo xcodebuild -license accept; sudo xcodebuild -runFirstLaunch; xcodebuild -downloadComponent MetalToolchain; export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer (or sudo xcode-select -s /Applications/Xcode.app)"
  },
  {
   "id": "python",
   "title": "python3 3.11 or newer (the cmd workers and the qualification scripts)",
   "test": "python3 -I -c 'import sys; sys.exit(sys.version_info < (3, 11))'",
   "fix": "brew install python@3.12"
  }
 ],
 "host": {
  "download_bytes": 14326193,
  "disk_bytes": 350000000,
  "tools": {
   "zig": {
    "url": "https://ziglang.org/download/0.17.0/zig-aarch64-macos-0.17.0.tar.xz",
    "sha256": "b607e9b9234790a008116ae5bdb71c6243b84b9fb42a53a9e70fde41c06c536a",
    "bytes": 53985220,
    "bin": [
     "zig"
    ],
    "version": "0.17.0",
    "version_cmd": "zig version"
   },
   "uv": {
    "url": "https://github.com/astral-sh/uv/releases/download/0.13.4/uv-aarch64-apple-darwin.tar.gz",
    "sha256": "e0b1d4743ce64c55d9f0f4a444afa6b81125680070ee04e853fcd0f6c1ebf8f1",
    "bytes": 14326193,
    "bin": [
     "uv",
     "uvx"
    ],
    "version": "uv 0.13.4",
    "version_cmd": "$J/bin/uv --version"
   }
  },
  "steps": [
   {
    "id": "uv",
    "download_bytes": 14326193,
    "disk_bytes": 50000000,
    "title": "uv 0.13.4 (the Python environments: the Whisper venv and the other cmd workers')",
    "run": "$STEPS tool uv",
    "done": "$STEPS tool-ok uv",
    "fix": "a failed download or checksum: run again (it resumes); a checksum that keeps differing: the pinned file changed upstream, report it"
   },
   {
    "id": "build",
    "download_bytes": 0,
    "disk_bytes": 300000000,
    "title": "LocalRouter itself, from this checkout (zig build: no CUDA engines on macOS)",
    "run": "cd $REPO && zig build -Doptimize=ReleaseSafe",
    "done": "[ -x \"$LR_BIN\" ]",
    "fix": "the build output says why; check zig version (0.17.0)"
   }
  ]
 },
 "models": [
  {
   "key": "stt",
   "id": "whisper-large-v3-turbo",
   "warm": true,
   "title": "Whisper large-v3-turbo speech to text (mlx-whisper, FP16 on Metal, Silero VAD on the CPU)",
   "licence": {
    "name": "MIT",
    "url": "https://huggingface.co/openai/whisper-large-v3-turbo"
   },
   "pins": "tools/speech/whisper/macos/uv.lock",
   "reuse": {
    "paths": [
     "models/whisper-mlx",
     "models/vad"
    ]
   },
   "download_bytes": 1876250000,
   "disk_bytes": 2800000000,
   "memory_bytes": 3489660928,
   "working_bytes": 1342177280,
   "steps": [
    {
     "id": "venv",
     "download_bytes": 260000000,
     "disk_bytes": 1200000000,
     "title": "the Whisper venv from tools/speech/whisper/macos/uv.lock (Python 3.12, mlx 0.32.4, mlx-whisper 0.4.3, torch 2.13.0 for the gate; every wheel by its locked hash)",
     "run": "UV_PROJECT_ENVIRONMENT=$J/venvs/whisper-mlx uv sync --locked --python 3.12 --project $REPO/tools/speech/whisper/macos && mkdir -p $J/install/state && shasum -a 256 $REPO/tools/speech/whisper/macos/uv.lock | cut -c1-64 > $J/install/state/whisper-mlx-venv",
     "done": "[ -x $J/venvs/whisper-mlx/bin/python ] && [ \"$(cat $J/install/state/whisper-mlx-venv 2> /dev/null)\" = \"$(shasum -a 256 $REPO/tools/speech/whisper/macos/uv.lock | cut -c1-64)\" ]",
     "fix": "uv on PATH (brew install uv); network (pypi.org): run again"
    },
    {
     "id": "model",
     "download_bytes": 1613977880,
     "reused": true,
     "disk_bytes": 1613977880,
     "title": "mlx-community/whisper-large-v3-turbo at its pinned revision (FP16, 1.6 GB), every file by sha256",
     "run": "python3 -I $REPO/tools/speech/whisper/macos/fetch_model.py --root $J/models/whisper-mlx",
     "done": "python3 -I $REPO/tools/speech/whisper/macos/fetch_model.py --verify $J/models/whisper-mlx/whisper-large-v3-turbo-mlx/a4aaeec0636e6fef84abdcbe3544cb2bf7e9f6fb > /dev/null",
     "fix": "network: run again (a file that failed its check is downloaded again)"
    },
    {
     "id": "vad",
     "download_bytes": 2272526,
     "disk_bytes": 2272526,
     "title": "the Silero VAD (silero_vad.jit at its pinned commit, by sha256)",
     "run": "mkdir -p $J/models/vad && curl -fsSL -o $J/models/vad/silero_vad.jit.part https://raw.githubusercontent.com/snakers4/silero-vad/5cd7945676eb32225748052e2e6a0580e4686a08/src/silero_vad/data/silero_vad.jit && [ \"$(shasum -a 256 $J/models/vad/silero_vad.jit.part | cut -c1-64)\" = e1122837f4154c511485fe0b9c64455f7b929c96fbb8d79fbdb336383ebd3720 ] && mv $J/models/vad/silero_vad.jit.part $J/models/vad/silero_vad.jit",
     "done": "[ \"$(shasum -a 256 $J/models/vad/silero_vad.jit 2> /dev/null | cut -c1-64)\" = e1122837f4154c511485fe0b9c64455f7b929c96fbb8d79fbdb336383ebd3720 ]",
     "fix": "network (raw.githubusercontent.com): run again"
    }
   ],
   "skip": "leave stt out of --models; the voice loop then cannot hear"
  },
  {
   "key": "decide",
   "id": "knowline-4b",
   "warm": false,
   "title": "KnowLine-4B Gen5.5 typed decisions (/v1/systemone, MCP decide): the authors' front end on MLX, bf16",
   "licence": {
    "name": "Apache-2.0",
    "url": "https://huggingface.co/PelaAI/KnowLine-4B-Gen5.5"
   },
   "pins": "tools/decide/knowline/macos/pins-macos.json",
   "download_bytes": 9342902390,
   "disk_bytes": 10000000000,
   "memory_bytes": 10724056240,
   "skip": "leave decide out of --models; /v1/systemone and MCP decide then answer that no decision model is configured",
   "steps": [
    {
     "id": "fetch",
     "download_bytes": 9342902390,
     "disk_bytes": 10000000000,
     "title": "the weights at the pinned revision (~9.3 GB, every file against SHA256SUMS) and the MLX venv from uv.lock",
     "run": "JARVIS=$J bash $REPO/tools/decide/knowline/macos/fetch.sh && $STEPS stamp decide-fetch $REPO/tools/decide/knowline/macos/pins-macos.json $REPO/tools/decide/knowline/macos/uv.lock",
     "done": "$STEPS stamped decide-fetch $REPO/tools/decide/knowline/macos/pins-macos.json $REPO/tools/decide/knowline/macos/uv.lock && [ -x $J/venvs/decide-mlx/bin/python ]",
     "fix": "network: run again (the download resumes). \"do not match SHA256SUMS\": delete $J/models/decide/knowline-4b-gen5.5 and run again"
    }
   ]
  },
  {
   "id": "qwen-image-2.1-turbo",
   "key": "image",
   "title": "Qwen-Image 2.1 Turbo text to image and edits of up to five images (MLX-Serve 4-bit, 8 steps; a cmd worker, loaded on demand)",
   "licence": {
    "name": "Qwen Research License: non-commercial research or evaluation only",
    "url": "https://huggingface.co/Qwen/Qwen-Image-2.1/blob/main/LICENSE"
   },
   "accept": [
    "the Qwen-Image 2.1 Turbo licence (link below)"
   ],
   "pins": "tools/image/qwen-mlx/pins-macos-q4.json (4-bit, installed), tools/image/qwen-mlx/pins-macos.json (the MLX-Serve binary; the 8-bit alternative), tools/image/qwen-mlx/requirements-macos.txt",
   "memory_bytes": 10200547328,
   "working_bytes": 6979321856,
   "download_bytes": 10628459115,
   "disk_bytes": 11500000000,
   "warm": false,
   "tool": "tools/image/qwen-mlx/config.example.json: cmd $IMAGE_ROOT/venv/bin/python -I $REPO/tools/image/qwen-mlx/qwen_mlx_worker.py, weights $IMAGE_ROOT/qwen-image-2.1-turbo-mlx-q4, options pack q4 and reference_working_bytes",
   "skip": "leave image out of --models; picture requests then fail with 'no image model'",
   "steps": [
    {
     "id": "fetch",
     "title": "the MLX-Serve 26.10.3 binary, the 4-bit Qwen-Image 2.1 Turbo pack (10.5 GB, every file against its pin) and the worker's Python",
     "download_bytes": 10628459115,
     "disk_bytes": 11500000000,
     "needs_accept": true,
     "run": "bash $REPO/tools/image/qwen-mlx/fetch.sh $IMAGE_ROOT --pack q4",
     "done": "[ -x $IMAGE_ROOT/venv/bin/python ] && $IMAGE_ROOT/mlx-serve-macos-arm64/mlx-serve --version 2> /dev/null | grep -qx 'mlx-serve 26.10.3' && python3 -I $REPO/tools/package/verify_assets.py --quick $REPO/tools/image/qwen-mlx/pins-macos-q4.json $IMAGE_ROOT/qwen-image-2.1-turbo-mlx-q4",
     "fix": "network: run again (finished files are kept, a partial one resumes). 'sha256 … pinned' or 'differs from': delete the named file and run again"
    }
   ],
   "reference_working_bytes": 2147483648
  },
  {
   "key": "chat",
   "id": "qwen3.8-27b",
   "warm": true,
   "title": "Qwen3.8 27B chat: TensorFold 1.1.4 native Metal server, MLX 4-bit weights with the DFlash2 drafter",
   "licence": {
    "name": "Apache-2.0 (checkpoint, drafter and TensorFold)",
    "url": "https://huggingface.co/TensorFold/Qwen3.8-27B-MLX-4bit"
   },
   "pins": "tools/chat/qwen38-27b/pins-macos.json",
   "download_bytes": 19936084561,
   "disk_bytes": 21000000000,
   "memory_bytes": 28723101696,
   "skip": "leave chat out of --models; the voice loop then has no model to answer with",
   "steps": [
    {
     "id": "fetch",
     "download_bytes": 19936084561,
     "disk_bytes": 21000000000,
     "title": "the TensorFold 1.1.4 macos-arm64 archive, the checkpoint and the drafter (~20 GB, into the shared Hugging Face cache), every file against pins-macos.json",
     "run": "bash $REPO/tools/chat/qwen38-27b/fetch-macos.sh $CHAT_ROOT",
     "done": "[ -x $CHAT_ROOT/tensorfold-1.1.4/bin/tensorfold-native ] && [ \"$(cat $CHAT_ROOT/tensorfold-1.1.4.archive-sha256)\" = \"$(jq -r '.tensorfold.archives[\"macos-arm64\"].sha256' $REPO/tools/chat/qwen38-27b/pins-macos.json)\" ]",
     "fix": "network: run again (partial files resume). \"exists with another size or hash\": delete the named file and run again. HF_TOKEN, if huggingface.co asks for one"
    },
    {
     "id": "setup",
     "title": "the binary runs here, reports Metal and sees the checkpoint; the tool config",
     "run": "bash $REPO/tools/chat/qwen38-27b/setup-macos.sh $CHAT_ROOT",
     "done": "[ -f $CHAT_ROOT/config.json ] && [ $CHAT_ROOT/config.json -nt $REPO/tools/chat/qwen38-27b/config.macos.example.json ]",
     "fix": "the log names the check that failed (backends not [\"metal\"]: the wrong archive or no Metal device; report it with the log)"
    },
    {
     "id": "bench",
     "title": "load, memory, speed and the prompts.json checks against the Mac baseline on this Mac (bench_macos.py, about 4 minutes)",
     "gpu": true,
     "min_free_gib": 32,
     "run": "d=$CHAT_ROOT/bench-1.1.4; rm -rf \"$d\"; python3 -I $REPO/tools/chat/qwen38-27b/bench_macos.py serve --config $CHAT_ROOT/config.json --out \"$d\"",
     "done": "jq -e '.error == null and .features_failed == []' $CHAT_ROOT/bench-1.1.4/summary.json > /dev/null 2>&1",
     "fix": "$CHAT_ROOT/bench-1.1.4 has server.log, bench.json and summary.json: a failed check names the prompt and field; not enough memory: unload other models first; anything else: report it with those files"
    }
   ]
  },
  {
   "key": "tts",
   "id": "fishaudio/drama-3",
   "warm": true,
   "title": "Fish Audio Drama 3 text to speech, NVFP4 pruned weights (drama-tensorfold's native TensorFold engine on Metal, six named voices, streamed 44.1 kHz)",
   "licence": {
    "name": "Fish Audio Community License v1.0 (no hosted service: keep the service on loopback or your tailnet)",
    "url": "https://huggingface.co/plotarmordev/drama-3-NVFP4-Pruned/blob/494db08481db952f834b2241bce63fb3dfa72554/LICENSE"
   },
   "accept": [
    "the Drama 3 weights' licence (FACL v1.0; link below): plotarmordev/drama-3-NVFP4-Pruned is an unofficial community quant of fishaudio/drama-3 under it",
    "the native Metal engine's numerics as this Mac's Drama 3 baseline: not bit-exact with the GB10's CUDA build or the SGLang-Omni reference (qualify_macos.py --accept-native-numerics)",
    "lossy weights: routed experts in NVFP4 and pruned to 7,369 of 10,240 (docs/dev/DRAMA3.md has their measured quality against the full model)"
   ],
   "pins": "tools/speech/drama3/pins-macos.json",
   "download_bytes": 22600000000,
   "disk_bytes": 24500000000,
   "memory_bytes": 30870077440,
   "skip": "leave tts out of --models; the Mac then has no speech model and the voice loop cannot speak",
   "steps": [
    {
     "id": "setup",
     "download_bytes": 22500000000,
     "disk_bytes": 24000000000,
     "title": "the drama-tensorfold checkout, the patched Mac launcher, the six voices converted to the Metal catalog, the NVFP4 checkpoint (22.3 GB) and the Metal engine (Zig and Xcode's Metal compiler; about 3 minutes), every file against its pins",
     "run": "ZIG=$(command -v zig) bash $REPO/tools/speech/drama3/setup-macos.sh $DRAMA_ROOT && shasum -a 256 $REPO/tools/speech/drama3/pins-macos.json > $DRAMA_ROOT/setup.stamp",
     "done": "[ -f $DRAMA_ROOT/engine-macos.json ] && shasum -a 256 -c --status $DRAMA_ROOT/setup.stamp",
     "fix": "exit 3: Xcode's Metal compiler is missing or its licence not accepted (the xcode-metal prereq); network: run again (partial files resume); anything else: the last lines say which pin differs"
    },
    {
     "id": "config",
     "title": "the qualify config: the Drama 3 tool from tools/speech/drama3/config.example-macos.json with this Mac's paths",
     "run": "mkdir -p $J/qualify-drama3 && jq --arg src $REPO --arg root $DRAMA_ROOT --arg marker $DRAMA_MARKER --arg py $(command -v python3) --argjson port $DRAMA_PORT --arg data $J/qualify-drama3/data '.data_dir = $data | .tools[0].cmd = [$py, \"-I\", ($src + \"/tools/speech/drama3/drama3_worker_macos.py\")] | .tools[0].weights = $root | .tools[0].qualification = $marker | .tools[0].options.port = $port' $REPO/tools/speech/drama3/config.example-macos.json > $J/qualify-drama3/config.json",
     "done": "[ -f $J/qualify-drama3/config.json ]",
     "fix": "report it with the log"
    },
    {
     "id": "qualify",
     "title": "the Metal qualification (assets, load, e2e, the six voices and a clone, memory; about 4 minutes), which writes the marker the service needs. Its first-audio gate is 0.55 s, not the GB10's 0.5 (guided warm first audio measures 0.52 s on an M5 Ultra; docs/dev/DRAMA3.md)",
     "gpu": true,
     "min_free_gib": 34,
     "needs_accept": true,
     "run": "python3 -I $REPO/tools/speech/drama3/qualify_macos.py $J/qualify-drama3/config.json $J/qualify-drama3/run-$(date -u +%Y%m%dT%H%M%SZ) --accept-native-numerics --first-audio-gate 0.55",
     "done": "[ -f $DRAMA_MARKER ] && jq -e --arg p \"$(shasum -a 256 $REPO/tools/speech/drama3/pins-macos.json | cut -c1-64)\" '.qualified == true and .pins_sha256 == $p' $DRAMA_MARKER > /dev/null",
     "fix": "the run directory named on the last line (under $J/qualify-drama3/) has report.json, which says which step failed: not enough free memory: stop what holds the GPU; anything else: report it with that file"
    }
   ]
  },
  {
   "key": "asset3d",
   "id": "idol",
   "warm": false,
   "title": "Idol image to 3D Gaussian splat (PyTorch cmd worker, loaded on demand; Mac baseline: PyTorch MPS eager, about 98 s an asset)",
   "licence": {
    "name": "Apache-2.0 (Idol, its BiRefNet copy, the FLUX.2 autoencoder) + DINOv3 License (the image encoder: Meta's custom licence; redistribution allowed under the Agreement)",
    "url": "https://github.com/facebookresearch/dinov3/blob/6876159a11b4df116f30f667f8c9888617df0751/LICENSE.md"
   },
   "accept": [
    "the DINOv3 License (link below; Last Updated August 19, 2025) for timm/vit_huge_plus_patch16_dinov3.lvd1689m, Idol's image encoder: use, copying, redistribution and derivatives are allowed, but redistribute the weights or anything derived from them only under the Agreement with a copy of it (kept as dinov3/LICENSE.md beside the weights); acknowledge DINOv3 in publications; no reverse engineering; laws, privacy and Trade Controls apply; no ITAR or prohibited end uses (military, nuclear, espionage, ...). Idol (speridlabs/idol) and the FLUX.2 autoencoder (black-forest-labs/FLUX.2-klein-4B vae/) are Apache-2.0; nothing here is non-commercial"
   ],
   "pins": "tools/asset3d/idol/pins.json, tools/asset3d/idol/uv.lock",
   "download_bytes": 6809205212,
   "disk_bytes": 7700000000,
   "memory_bytes": 5368709120,
   "working_bytes": 8053063680,
   "tool": "tools/asset3d/idol/config.example.json: cmd $J/venvs/asset3d-idol/bin/python -I $REPO/tools/asset3d/idol/worker.py, weights $J/models/idol",
   "skip": "leave asset3d out of --models; image to 3D requests then fail with no image_to_3d model",
   "steps": [
    {
     "id": "venv",
     "download_bytes": 200000000,
     "disk_bytes": 1000000000,
     "title": "the Idol venv from tools/asset3d/idol/uv.lock (Python 3.12, torch 2.13.0 for MPS, the idol-sdk at its pinned commit; every wheel by its locked hash)",
     "run": "UV_PROJECT_ENVIRONMENT=$J/venvs/asset3d-idol uv sync --locked --python 3.12 --project $REPO/tools/asset3d/idol && $STEPS stamp asset3d-idol-venv $REPO/tools/asset3d/idol/uv.lock",
     "done": "$STEPS stamped asset3d-idol-venv $REPO/tools/asset3d/idol/uv.lock && [ -x $J/venvs/asset3d-idol/bin/python ]",
     "fix": "uv on PATH (the uv host step); network (pypi.org, github.com for the idol-sdk): run again"
    },
    {
     "id": "fetch",
     "download_bytes": 6609205212,
     "disk_bytes": 6700000000,
     "needs_accept": true,
     "title": "the Idol, DINOv3 (timm) and FLUX.2 autoencoder weights at their pinned revisions (6.6 GB, ungated, no token), every file by sha256 against pins.json",
     "run": "bash $REPO/tools/asset3d/idol/fetch.sh $J/models/idol && $STEPS stamp asset3d-idol-fetch $REPO/tools/asset3d/idol/pins.json",
     "done": "$STEPS stamped asset3d-idol-fetch $REPO/tools/asset3d/idol/pins.json && python3 -I $REPO/tools/package/verify_assets.py --quick $REPO/tools/asset3d/idol/pins.json $J/models/idol > /dev/null",
     "fix": "network (huggingface.co): run again (finished files are kept, a partial one resumes). 'is N bytes, pinned M' or 'does not match pins.json': delete the named file and run again"
    }
   ]
  }
 ],
 "deploy": {
  "service": "launchd",
  "install": "deploy/mac/install.sh",
  "start": "deploy/mac/start.sh",
  "stop": "deploy/mac/stop.sh",
  "status": "deploy/mac/status.sh",
  "uninstall": "deploy/mac/uninstall.sh",
  "smoke": "deploy/mac/status.sh",
  "daemon": {
   "reserve_bytes": 3221225472
  }
 }
}