offgrid-ai 0.16.0 → 0.16.3

package/README.md

@@ -2,7 +2,7 @@
 
 # offgrid-ai
 
-**Helper CLI for running local AI models on Mac with llama-server, mlx-vlm, and oMLX.**
+**Helper CLI for running local AI models on Mac with llama-server and oMLX.**
 
 [![node](https://img.shields.io/badge/node-20%2B-3c873a)](package.json)
 [![platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-blue)]()
@@ -12,7 +12,7 @@
 
 ## What is offgrid-ai?
 
-offgrid-ai is a command-line tool that lets you run AI models locally. Running local models with llama-server, mlx-vlm, or oMLX have a steep learning curve compared to cloud-based models, so offgrid-ai is designed to abstract away the complexity, while still providing a powerful and flexible way to run local models.
+offgrid-ai is a command-line tool that lets you run AI models locally. Running local models with llama-server or oMLX have a steep learning curve compared to cloud-based models, so offgrid-ai is designed to abstract away the complexity, while still providing a powerful and flexible way to run local models.
 
 This is the recommended workflow:
 
@@ -23,8 +23,8 @@ This is the recommended workflow:
 ## Core Features
 - Auto-detects available models from LM Studio, oMLX, and HuggingFace
 - Auto-detects MTP (multi-token prediction) or QAT (quantization aware training) models, and applies the correct flags for llama.cpp
-- Auto-applies the optimal flags for the model type (llama.cpp server flags, mlx-vlm APC/thinking/context flags)
-- Start / stop local servers automatically for chat sessions (llama-server and mlx-vlm)
+- Auto-applies the optimal flags for the model type (llama.cpp server flags, oMLX auto-start and cache management)
+- Start / stop local servers automatically for chat sessions (llama-server and oMLX)
 
 ## Quick start
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "offgrid-ai",
-  "version": "0.16.0",
+  "version": "0.16.3",
   "description": "Privacy-first CLI for running local LLMs — discover, configure, run, benchmark",
   "author": "Eeshan Srivastava (https://eeshans.com)",
   "type": "module",

package/src/autodetect.mjs

@@ -55,7 +55,7 @@ export function computeFlags(capabilities, modelPath, mmprojPath, draftModelPath
   const isLowMem = quant && /[Qq]4[_0]/i.test(quant);
 
   const flags = {
-    ...defaultFlagsForBackend(mtp ? "llama-cpp-mtp" : "llama-cpp"),
+    ...defaultFlagsForBackend("llama-cpp"),
     ctxSize: capabilities.ctxSize,
     flashAttention: "on",
     cacheTypeK: isLowMem ? "f16" : "bf16",

package/src/backends.mjs

@@ -7,7 +7,6 @@ import { scanOmlxModelSizes, lookupOmlxModelInfo } from "./mlx-discovery.mjs";
 
 export const LOCAL_HOST = "127.0.0.1";
 export const LLAMA_CPP_PORT = 8080;
-export const LLAMA_CPP_MTP_PORT = 8081;
 export const OMLX_PORT = 8000;
 
 export function baseUrlFor({ host = LOCAL_HOST, port, path = "/v1" }) {
@@ -30,17 +29,6 @@ export const BACKENDS = {
     needsCommandFile: true,
     scanModels: async () => (await scanGgufModels()).models,
   },
-  "llama-cpp-mtp": {
-    id: "llama-cpp-mtp",
-    label: "llama.cpp MTP",
-    type: "local-server",
-    providerId: "llama-cpp-mtp",
-    defaultHost: LOCAL_HOST,
-    defaultPort: LLAMA_CPP_MTP_PORT,
-    defaultBaseUrl: baseUrlFor({ port: LLAMA_CPP_MTP_PORT }),
-    needsCommandFile: true,
-    scanModels: async () => (await scanGgufModels()).models,
-  },
   "omlx": {
     id: "omlx",
     label: "oMLX",

package/src/benchmark/flow.mjs

@@ -15,7 +15,7 @@ import { finalizeBenchmarkRun, renderBenchmarkSummary } from "./finalize.mjs";
 
 function benchmarkModelSource(profile) {
   if (!profile) return "cloud";
-  return profile.providerId === "llama-cpp-mtp" ? "llama-cpp-mtp" : profile.backend === "omlx" ? "omlx" : "llama-cpp";
+  return profile.backend === "omlx" ? "omlx" : "llama-cpp";
 }
 
 async function chooseBenchmarkAction(prompt, canRun) {
@@ -150,16 +150,22 @@ async function selectBenchmark(prompt, repoPath) {
   return { kind, benchmark };
 }
 
-// ── Benchmark from a selected profile (from model picker) ────────────────
+// ── Shared benchmark setup ───────────────────────────────────────────────
 
-export async function benchmarkForProfile(profile) {
+async function benchmarkSetup() {
   await ensureDirs();
   const prompt = createPrompt();
-  try {
-    const repoPath = await linkBenchmarkRepo(prompt);
-    if (!repoPath) return;
+  const repoPath = await linkBenchmarkRepo(prompt);
+  if (!repoPath) return { prompt, repoPath: null, selected: null };
+  const selected = await selectBenchmark(prompt, repoPath);
+  return { prompt, repoPath, selected };
+}
+
+// ── Benchmark from a selected profile (from model picker) ────────────────
 
-    const selected = await selectBenchmark(prompt, repoPath);
+export async function benchmarkForProfile(profile) {
+  const { prompt, repoPath, selected } = await benchmarkSetup();
+  try {
     if (!selected) return;
     const { kind, benchmark: selectedBenchmark } = selected;
 
@@ -185,13 +191,8 @@ export async function benchmarkForProfile(profile) {
 // ── Standalone benchmark flow (offgrid-ai benchmark) ──────────────────────
 
 export async function benchmarkFlow() {
-  await ensureDirs();
-  const prompt = createPrompt();
+  const { prompt, repoPath, selected } = await benchmarkSetup();
   try {
-    const repoPath = await linkBenchmarkRepo(prompt);
-    if (!repoPath) return;
-
-    const selected = await selectBenchmark(prompt, repoPath);
     if (!selected) return;
     const { kind, benchmark: selectedBenchmark } = selected;
 

package/src/benchmark/metrics.mjs

@@ -9,7 +9,7 @@ const SPEED_QUERY_MAX_TOKENS = 64;
 export async function queryServerMetrics(profile) {
   const backend = backendFor(profile.backend);
 
-  if (backend.id === "llama-cpp" || backend.id === "llama-cpp-mtp") {
+  if (backend.id === "llama-cpp") {
     return await queryLlamaCppMetrics(profile);
   }
   if (backend.id === "omlx") {
@@ -19,12 +19,13 @@ export async function queryServerMetrics(profile) {
   throw new Error(`Unsupported backend for benchmark speed metrics: ${backend.id}`);
 }
 
-async function queryLlamaCppMetrics(profile) {
+async function speedQueryFetch(profile, { stream = false, streamOptions = null, errorLabel = "speed query" } = {}) {
   const body = {
     model: profile.modelAlias,
     messages: [{ role: "user", content: BENCH_SPEED_PROMPT }],
-    stream: false,
+    stream,
     max_tokens: SPEED_QUERY_MAX_TOKENS,
+    ...(streamOptions ? { stream_options: streamOptions } : {}),
   };
 
   const response = await fetch(profile.baseUrl.replace(/\/$/u, "") + "/chat/completions", {
@@ -35,9 +36,15 @@ async function queryLlamaCppMetrics(profile) {
   });
 
   if (!response.ok) {
-    throw new Error(`llama.cpp speed query failed: ${response.status} ${response.statusText}`);
+    throw new Error(`${errorLabel} failed: ${response.status} ${response.statusText}`);
   }
 
+  return response;
+}
+
+async function queryLlamaCppMetrics(profile) {
+  const response = await speedQueryFetch(profile, { errorLabel: "llama.cpp speed query" });
+
   const data = await response.json();
   const timings = data.timings;
   if (!timings || typeof timings.prompt_per_second !== "number" || typeof timings.predicted_per_second !== "number") {
@@ -60,25 +67,12 @@ async function queryLlamaCppMetrics(profile) {
 }
 
 async function queryOmlxMetrics(profile) {
-  const body = {
-    model: profile.modelAlias,
-    messages: [{ role: "user", content: BENCH_SPEED_PROMPT }],
+  const response = await speedQueryFetch(profile, {
     stream: true,
-    stream_options: { include_usage: true },
-    max_tokens: SPEED_QUERY_MAX_TOKENS,
-  };
-
-  const response = await fetch(profile.baseUrl.replace(/\/$/u, "") + "/chat/completions", {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(body),
-    signal: AbortSignal.timeout(SPEED_QUERY_TIMEOUT_MS),
+    streamOptions: { include_usage: true },
+    errorLabel: "oMLX speed query",
   });
 
-  if (!response.ok) {
-    throw new Error(`oMLX speed query failed: ${response.status} ${response.statusText}`);
-  }
-
   const text = await response.text();
   let usage = null;
   for (const line of text.split("\n").reverse()) {

package/src/commands/main.mjs

@@ -4,7 +4,8 @@ import { scanGgufModels } from "../scan.mjs";
 import { loadProfiles } from "../profiles.mjs";
 import { hasPi } from "../harness-pi.mjs";
 import { offerManagedLlamaRuntimeUpdate } from "../runtime.mjs";
-import { hasLmStudioInstalled, hasOmlxInstalled, scanManagedModels } from "../managed.mjs";
+import { offerManagedOmlxUpdate, hasOmlx } from "../omlx-runtime.mjs";
+import { hasLmStudioInstalled, scanManagedModels } from "../managed.mjs";
 import { recommendedModel } from "../recommendations.mjs";
 import { pc, startInteractive, createPrompt } from "../ui.mjs";
 import { onboardFlow } from "./onboard.mjs";
@@ -18,6 +19,7 @@ export async function mainFlow() {
     const runtimePrompt = createPrompt();
     try {
       await offerManagedLlamaRuntimeUpdate(runtimePrompt);
+      await offerManagedOmlxUpdate(runtimePrompt);
     } finally {
       runtimePrompt.close();
     }
@@ -63,7 +65,7 @@ async function printNoModelsHelp(llamaBinary) {
   console.log(pc.yellow("No models found."));
   console.log(pc.dim("You need to download a model to use offgrid-ai.\n"));
 
-  const omlxInstalled = await hasOmlxInstalled();
+  const omlxInstalled = await hasOmlx();
   const lmStudioInstalled = hasLmStudioInstalled();
   const hasBackends = llamaBinary || omlxInstalled || lmStudioInstalled;
   if (!hasBackends) {

package/src/commands/models.mjs

@@ -3,7 +3,7 @@ import { backendFor, BACKENDS } from "../backends.mjs";
 import { createProfileFromModel, readProfile, saveProfile, deleteProfile, profileJsonPath } from "../profiles.mjs";
 import { isProfileRunning, isProfileServerUp, modelAvailableOnServer, stopProfile } from "../process.mjs";
 import { syncPiConfig, removeFromPiConfig } from "../harness-pi.mjs";
-import { configureLocalProfile } from "../profile-setup.mjs";
+import { configureLocalProfile, configureManagedProfile } from "../profile-setup.mjs";
 import { pc, startInteractive, createPrompt, modelSelect } from "../ui.mjs";
 import { buildCatalogItems, createManagedProfile, itemKey, loadModelCatalog, normalizeCatalog } from "../model-catalog.mjs";
 import { modelSelectOption, modelNameWidth, inferBackendId, formatSourceLabel, discoverySourceForItem, printGgufModelDetails, printManagedModelDetails, printWorkspaceHeader, printBenchmarkLine, printProfileDetails } from "../model-presenters.mjs";
@@ -84,7 +84,6 @@ export async function modelCommandCenter(initialCatalog) {
   const groups = [];
   const backendColors = {
     "llama-cpp": pc.cyan,
-    "llama-cpp-mtp": pc.blue,
     omlx: pc.magenta,
   };
   for (const { backendId, sourceId, items } of byBackend.values()) {
@@ -195,7 +194,7 @@ async function performAction(prompt, action, item) {
     return await benchmarkFlow();
   }
   if (action === "run") return await runItem(item);
-  if (action === "reconfigure" || action === "setup") return await setupItem(prompt, item, action);
+  if (action === "reconfigure" || action === "setup") return await setupItem(prompt, item);
   if (action === "remove" && item.type === "profile") return await removeProfileInteractive(item.profile.id);
 }
 
@@ -207,26 +206,28 @@ function printProfileSaved(id) {
   console.log(pc.dim(`  Profile: ${profileJsonPath(id)}`));
 }
 
-async function setupItem(prompt, item, action) {
+async function setupItem(prompt, item) {
   if (item.type === "profile") {
     const configured = await configureLocalProfile(prompt, await readProfile(item.profile.id));
     if (!configured) return;
-    await saveProfile(configured, { writeCommand: true });
+    await saveProfile(configured);
     await syncPiConfig(configured);
     printProfileSaved(configured.id);
     return;
   }
   if (item.type === "managed") {
     const profile = createManagedProfile(item.model, item.backendId);
-    await saveProfile(profile);
-    await syncPiConfig(profile);
-    printProfileSaved(profile.id);
+    const configured = await configureManagedProfile(prompt, profile);
+    if (!configured) return;
+    await saveProfile(configured);
+    await syncPiConfig(configured);
+    printProfileSaved(configured.id);
     return;
   }
   const profile = await createProfileFromModel(item.model, null, item.drafter?.path);
   const configured = await configureLocalProfile(prompt, profile);
   if (!configured) return;
-  await saveProfile(configured, { writeCommand: action === "reconfigure" });
+  await saveProfile(configured);
   await syncPiConfig(configured);
   printProfileSaved(configured.id);
 }

package/src/commands/onboard.mjs

@@ -1,9 +1,9 @@
-import { existsSync } from "node:fs";
-import { ensureDirs, findLlamaServer, hasHomebrew, HF_HUB_DIR } from "../config.mjs";
+import { ensureDirs, findLlamaServer, ensureHomebrewFor, HF_HUB_DIR } from "../config.mjs";
 import { BACKENDS } from "../backends.mjs";
 import { scanGgufModels } from "../scan.mjs";
 import { hasPi } from "../harness-pi.mjs";
 import { offerManagedLlamaRuntimeUpdate } from "../runtime.mjs";
+import { ensureOmlxRuntime } from "../omlx-runtime.mjs";
 import { scanManagedModels } from "../managed.mjs";
 import { BACKEND_INSTALL_CHOICES, BACKEND_INSTALLERS } from "../backend-installers.mjs";
 import { recommendedModel, selectFormat, allFittingModels } from "../recommendations.mjs";
@@ -24,6 +24,7 @@ export async function onboardFlow() {
     console.log(pc.dim("Let's make sure you have everything you need to run local models.\n"));
 
     const llamaBinary = await ensureLlamaRuntime(prompt);
+    await ensureOmlxRuntime(prompt, run);
     if (!(await ensurePi(prompt, run))) return;
 
     const [{ models: ggufModels }, managedModels] = await Promise.all([
@@ -169,35 +170,6 @@ async function offerBackendInstall(prompt, run) {
   await installBackend(prompt, run, choice, model);
 }
 
-async function ensureHomebrewFor(prompt, run, label) {
-  if (await hasHomebrew()) return true;
-  const install = await prompt.yesNo(`Homebrew is needed to install ${label}. Install Homebrew now?`, true);
-  if (!install) {
-    console.log(pc.dim(`Install ${label} manually, or install Homebrew from https://brew.sh and run offgrid-ai again.`));
-    return false;
-  }
-  console.log(pc.cyan("Installing Homebrew..."));
-  try {
-    await run("/bin/bash", ["-c", "NONINTERACTIVE=1 /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\""], "Homebrew");
-    for (const path of ["/opt/homebrew/bin", "/usr/local/bin"]) {
-      if (existsSync(path)) {
-        process.env.PATH = `${path}:${process.env.PATH}`;
-        break;
-      }
-    }
-  } catch {
-    console.log(pc.red("✗ Homebrew installation failed."));
-    console.log(pc.dim("Install it manually from https://brew.sh, then run offgrid-ai again."));
-    return false;
-  }
-  if (!(await hasHomebrew())) {
-    console.log(pc.red("Homebrew was installed but not found on PATH. Restart your terminal and run offgrid-ai again."));
-    return false;
-  }
-  console.log(pc.green("✓ Homebrew found"));
-  return true;
-}
-
 async function installBackend(prompt, run, backendId, model) {
   const installer = BACKEND_INSTALLERS[backendId];
   if (!(await ensureHomebrewFor(prompt, run, installer.label))) return;

package/src/commands/run.mjs

@@ -77,7 +77,7 @@ async function ensureLocalServer(profile, backend, options) {
       console.log(pc.yellow("Vision projector is not supported by this llama.cpp build. Retrying text-only."));
       console.log(pc.dim("Update llama.cpp later to re-enable vision for this model."));
       const textOnly = textOnlyProfile(profile);
-      await saveProfile(textOnly, { writeCommand: true });
+      await saveProfile(textOnly);
       return { handled: true, result: await runProfile(textOnly, { ...options, textOnlyRetry: true }) };
     }
     throw err;

package/src/config.mjs

@@ -3,6 +3,7 @@ import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { readFile, writeFile } from "node:fs/promises";
+import { pc } from "./ui.mjs";
 
 // ── Base directories ──────────────────────────────────────────────────────
 
@@ -124,4 +125,49 @@ export async function hasHomebrew() {
   } catch {
     return false;
   }
+}
+
+/**
+ * Install Homebrew non-interactively and add it to PATH for this process.
+ * Returns true if Homebrew is available after installation.
+ */
+export async function installHomebrew(run) {
+  await run("/bin/bash", ["-c", 'NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"'], "Homebrew");
+  for (const path of ["/opt/homebrew/bin", "/usr/local/bin"]) {
+    if (existsSync(path)) {
+      process.env.PATH = `${path}:${process.env.PATH}`;
+      break;
+    }
+  }
+  return await hasHomebrew();
+}
+
+/**
+ * Ensure Homebrew is installed, prompting the user if necessary.
+ * @param {object} prompt - UI prompt interface (needs yesNo)
+ * @param {function} run - runCommand function for verbose command execution
+ * @param {string} label - what we're installing (for the prompt message)
+ * @returns {Promise<boolean>} true if Homebrew is available
+ */
+export async function ensureHomebrewFor(prompt, run, label) {
+  if (await hasHomebrew()) return true;
+  const install = await prompt.yesNo(`Homebrew is needed to install ${label}. Install Homebrew now?`, true);
+  if (!install) {
+    console.log(pc.dim(`Install ${label} manually, or install Homebrew from https://brew.sh and run offgrid-ai again.`));
+    return false;
+  }
+  console.log(pc.cyan("Installing Homebrew..."));
+  try {
+    const success = await installHomebrew(run);
+    if (!success) {
+      console.log(pc.red("Homebrew was installed but not found on PATH. Restart your terminal and run offgrid-ai again."));
+      return false;
+    }
+  } catch {
+    console.log(pc.red("✗ Homebrew installation failed."));
+    console.log(pc.dim("Install it manually from https://brew.sh, then run offgrid-ai again."));
+    return false;
+  }
+  console.log(pc.green("✓ Homebrew found"));
+  return true;
 }

package/src/harness-pi.mjs

@@ -8,10 +8,8 @@ import pc from "picocolors";
 // ── Pi model id ─────────────────────────────────────────────────────────────
 
 /**
- * The model id Pi must send in requests. mlx-vlm registers the loaded model
- * with the full --model path as its API id (verified via /v1/models); sending
- * the repo-id label instead makes mlx-vlm unload the local model and re-fetch
- * the repo from HuggingFace. Other backends use the friendly modelAlias.
+ * The model id Pi must send in requests. All backends use the friendly
+ * modelAlias as the API model id.
  */
 export function piApiModelId(profile) {
   return profile.modelAlias;
@@ -87,7 +85,7 @@ async function activeProviderProfiles(currentProfile) {
   const byAlias = new Map();
   for (const item of [...allProfiles, currentProfile]) {
     if (item.providerId !== currentProfile.providerId) continue;
-    if (item.backend !== "llama-cpp" && item.backend !== "llama-cpp-mtp") {
+    if (item.backend !== "llama-cpp") {
       byAlias.set(item.modelAlias, item);
       continue;
     }

package/src/managed.mjs

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import { BACKENDS } from "./backends.mjs";
-import { commandExists } from "./exec.mjs";
+import { hasOmlx } from "./omlx-runtime.mjs";
 
 export const MANAGED_BACKEND_IDS = ["omlx"];
 
@@ -22,6 +22,6 @@ export function hasLmStudioInstalled() {
   return existsSync("/Applications/LM Studio.app");
 }
 
-export function hasOmlxInstalled() {
-  return commandExists("omlx");
+export async function hasOmlxInstalled() {
+  return await hasOmlx();
 }

package/src/mlx-discovery.mjs

@@ -2,7 +2,7 @@
 // to compute sizes and publishers. The oMLX API doesn't return these, so we
 // read them from disk.
 
-import { readdir, stat } from "node:fs/promises";
+import { readdir, stat, readFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
@@ -65,6 +65,99 @@ export async function scanOmlxModelSizes() {
   return infoByBasename;
 }
 
+// ── MTP capability detection ─────────────────────────────────────────────
+// oMLX supports native MTP for Qwen 3.5/3.6 (dense + MoE) and DeepSeek-V4
+// models that ship MTP heads in their weights. The check mirrors oMLX's own
+// _mtp_compat_for_model: config must declare mtp_num_hidden_layers, model_type
+// must be on the whitelist, and the safetensors index must contain mtp.* keys.
+
+const MTP_MODEL_TYPES = ["qwen3_5", "qwen3_5_moe", "qwen3_6", "qwen3_6_moe", "deepseek_v4"];
+
+/**
+ * Check if an oMLX model directory supports native MTP.
+ * Returns { compatible: boolean, reason: string }.
+ */
+export async function detectOmlxMtpCapability(modelDir) {
+  const configPath = join(modelDir, "config.json");
+  if (!existsSync(configPath)) return { compatible: false, reason: "config.json not found" };
+
+  let config;
+  try {
+    config = JSON.parse(await readFile(configPath, "utf8"));
+  } catch {
+    return { compatible: false, reason: "failed to read config.json" };
+  }
+
+  const mtpLayers = config.mtp_num_hidden_layers;
+  if (!mtpLayers || mtpLayers <= 0) {
+    return { compatible: false, reason: "model has no MTP heads in config" };
+  }
+
+  const modelType = config.model_type;
+  if (!MTP_MODEL_TYPES.some((t) => modelType === t || modelType?.startsWith(t))) {
+    return { compatible: false, reason: `model_type=${modelType} is not on the MTP whitelist (supported: ${MTP_MODEL_TYPES.join(", ")})` };
+  }
+
+  // Check for mtp.* weight tensors in the safetensors index
+  const hasWeights = await modelHasMtpWeights(modelDir);
+  if (!hasWeights) {
+    return { compatible: false, reason: "Config declares MTP layers but the converted weights are missing mtp.* tensors. Re-convert from HF with a converter that preserves MTP weights." };
+  }
+
+  return { compatible: true, reason: "" };
+}
+
+async function modelHasMtpWeights(modelDir) {
+  const indexPath = join(modelDir, "model.safetensors.index.json");
+  if (existsSync(indexPath)) {
+    try {
+      const index = JSON.parse(await readFile(indexPath, "utf8"));
+      const weightMap = index.weight_map ?? {};
+      return Object.keys(weightMap).some((key) => key.includes("mtp."));
+    } catch {
+      return false;
+    }
+  }
+  // Single-shard fallback: can't easily read safetensors keys in Node without
+  // the safetensors library. Check for an mtp-specific safetensors file.
+  try {
+    const entries = await readdir(modelDir);
+    return entries.some((f) => f.endsWith(".safetensors") && /mtp/i.test(f));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Find the model directory for a given oMLX model ID.
+ * Searches ~/.omlx/models/ recursively for a directory matching the model ID.
+ */
+export async function findOmlxModelDir(modelId) {
+  if (!existsSync(OMLX_MODELS_DIR)) return null;
+  const basename = modelId.includes("/") ? modelId.slice(modelId.lastIndexOf("/") + 1)
+    : modelId.includes("--") ? modelId.slice(modelId.lastIndexOf("--") + 2)
+    : modelId;
+
+  async function walk(dir) {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return null;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const fullPath = join(dir, entry.name);
+      if (entry.name === basename && await isMlxModelDir(fullPath)) return fullPath;
+      const found = await walk(fullPath);
+      if (found) return found;
+    }
+    return null;
+  }
+
+  return await walk(OMLX_MODELS_DIR);
+}
+
 /**
  * Look up a model's info by its oMLX API id. Tries exact match, then the
  * segment after `--` (oMLX org--name format), then after `/` (HF format).

package/src/model-presenters.mjs

@@ -53,7 +53,6 @@ function optionBackendTag(backendId) {
   const label = backend?.label ?? backendId ?? "unknown";
   const colors = {
     "llama-cpp": pc.cyan,
-    "llama-cpp-mtp": pc.blue,
     omlx: pc.magenta,
   };
   return optionPad(label, colors[backendId] ?? pc.dim, OPTION_BACKEND_WIDTH);

package/src/omlx-runtime.mjs

@@ -0,0 +1,232 @@
+// oMLX runtime management — discovery, version checking, update prompts,
+// and installation. Mirrors the llama.cpp runtime pattern in runtime.mjs.
+//
+// oMLX is installed either via the macOS app (DMG from GitHub Releases, which
+// installs a ~/.omlx/bin/omlx CLI shim with in-app auto-update) or via Homebrew
+// (brew tap jundot/omlx && brew install omlx). offgrid-ai does NOT download
+// binaries directly — it uses brew for automated installs, and prompts for the
+// DMG when brew is unavailable.
+
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { compareVersions } from "./updates.mjs";
+import { hasHomebrew, ensureHomebrewFor } from "./config.mjs";
+import { commandExists } from "./exec.mjs";
+import { pc, renderCard, renderRows } from "./ui.mjs";
+
+const execFileAsync = promisify(execFile);
+
+const OMLX_CLI_SHIM = join(homedir(), ".omlx", "bin", "omlx");
+const RELEASE_API = "https://api.github.com/repos/jundot/omlx/releases/latest";
+
+// ── Discovery ──────────────────────────────────────────────────────────────
+
+/**
+ * Find the oMLX CLI binary. Checks the app-installed shim first (it shadows
+ * brew on PATH), then falls back to PATH. Returns the path or null.
+ */
+export async function findOmlx() {
+  // 1. macOS app CLI shim (shadows brew on PATH)
+  if (existsSync(OMLX_CLI_SHIM)) return OMLX_CLI_SHIM;
+
+  // 2. PATH (brew install)
+  try {
+    const { stdout } = await execFileAsync("which", ["omlx"]);
+    const path = stdout.trim();
+    if (path && existsSync(path)) return path;
+  } catch { /* not on PATH */ }
+
+  return null;
+}
+
+/**
+ * Check if oMLX is installed (app shim or on PATH).
+ */
+export async function hasOmlx() {
+  return (await findOmlx()) !== null;
+}
+
+/**
+ * Detect how oMLX was installed: "app" (macOS app CLI shim) or "brew" (on PATH
+ * but not the shim) or null (not installed).
+ */
+export async function omlxInstallMethod() {
+  if (existsSync(OMLX_CLI_SHIM)) return "app";
+  if (await commandExists("omlx")) return "brew";
+  return null;
+}
+
+// ── Version checking ───────────────────────────────────────────────────────
+
+/**
+ * Get the installed oMLX version by running `omlx --version`.
+ * Returns null if oMLX is not installed or the version can't be parsed.
+ */
+export async function installedOmlxVersion() {
+  const bin = await findOmlx();
+  if (!bin) return null;
+  try {
+    const { stdout } = await execFileAsync(bin, ["--version"], { timeout: 5000 });
+    const match = stdout.trim().match(/(\d+\.\d+\.\d+)/u);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check for the latest oMLX release on GitHub.
+ * Returns { tag, version } or null if the check fails.
+ * Callers must treat null as "check failed, skip prompt".
+ */
+export async function latestOmlxRelease(fetchImpl = globalThis.fetch) {
+  try {
+    const response = await fetchImpl(RELEASE_API, { signal: AbortSignal.timeout(5000) });
+    if (!response.ok) return null;
+    const body = await response.json();
+    const tag = typeof body?.tag_name === "string" ? body.tag_name : null;
+    if (!tag) return null;
+    const version = tag.replace(/^v/u, "");
+    return { tag, version };
+  } catch {
+    return null;
+  }
+}
+
+// ── Update prompt ──────────────────────────────────────────────────────────
+
+/**
+ * Check if an oMLX update is available and offer to install it.
+ * Returns true if an update was installed, false otherwise.
+ *
+ * For brew installs: runs `brew upgrade omlx`.
+ * For app installs: the app has in-app auto-update, so we just inform the user.
+ */
+export async function offerManagedOmlxUpdate(prompt, { fetchImpl = globalThis.fetch } = {}) {
+  const latest = await latestOmlxRelease(fetchImpl);
+  if (!latest) return false;
+
+  const installed = await installedOmlxVersion();
+  if (installed && compareVersions(installed, latest.version) >= 0) return false;
+
+  const method = await omlxInstallMethod();
+
+  console.log("\n" + renderCard("oMLX runtime", renderRows([
+    ["Installed", installed ?? pc.yellow("not installed")],
+    ["Latest", pc.green(latest.version)],
+    ["Source", method === "app" ? "macOS app (in-app auto-update)" : "Homebrew"],
+  ]), { formatBorder: pc.cyan }));
+
+  // App installs have their own auto-update — just inform the user
+  if (method === "app" && installed) {
+    console.log(pc.dim("  Update oMLX via the app's in-app updater, then restart offgrid-ai."));
+    return false;
+  }
+
+  // Not installed, or brew install — offer to install/upgrade
+  if (!installed) {
+    const shouldInstall = await prompt.yesNo("Install oMLX runtime?", false);
+    if (!shouldInstall) return false;
+    return await installOmlx(prompt);
+  }
+
+  // Brew install with an update available
+  const shouldUpdate = await prompt.yesNo("Update oMLX runtime?", false);
+  if (!shouldUpdate) return false;
+
+  try {
+    const { runCommand } = await import("./exec.mjs");
+    console.log(pc.dim("Updating oMLX via Homebrew..."));
+    await runCommand("brew", ["update"], { label: "brew update" });
+    await runCommand("brew", ["upgrade", "omlx"], { label: "brew upgrade omlx" });
+    console.log(pc.green(`✓ Updated oMLX to latest`));
+    return true;
+  } catch (err) {
+    console.log(pc.red(`✗ Update failed: ${err.message}`));
+    console.log(pc.dim("Update manually: brew update && brew upgrade omlx"));
+    return false;
+  }
+}
+
+// ── Installation ───────────────────────────────────────────────────────────
+
+/**
+ * Install oMLX. Uses Homebrew if available (automating tap + install).
+ * If Homebrew is not available, prompts to download the DMG from GitHub
+ * Releases or install Homebrew first.
+ *
+ * @param {object} prompt - UI prompt interface (yesNo, choice)
+ * @param {function} [run] - runCommand function for verbose command execution
+ * @returns {Promise<boolean>} true if installation succeeded
+ */
+export async function installOmlx(prompt, run) {
+  const hasBrew = await hasHomebrew();
+
+  if (!hasBrew) {
+    if (!(await ensureHomebrewFor(prompt, run || (async (cmd, args, label) => {
+      const { runCommand } = await import("./exec.mjs");
+      return runCommand(cmd, args, { label });
+    }), "oMLX"))) {
+      console.log(pc.dim("Install oMLX manually:"));
+      console.log(pc.dim("  brew tap jundot/omlx && brew install omlx"));
+      console.log(pc.dim("  — or download the macOS app from https://github.com/jundot/omlx/releases"));
+      return false;
+    }
+  }
+
+  // Install oMLX via Homebrew
+  const runner = run || (async (cmd, args, label) => {
+    const { runCommand } = await import("./exec.mjs");
+    return runCommand(cmd, args, { label });
+  });
+
+  console.log(pc.cyan("Installing oMLX via Homebrew..."));
+  try {
+    await runner("brew", ["tap", "jundot/omlx", "https://github.com/jundot/omlx"], "oMLX tap");
+    await runner("brew", ["install", "omlx"], "oMLX");
+    console.log(pc.green("✓ oMLX installed"));
+    return true;
+  } catch (err) {
+    console.log(pc.red(`✗ oMLX installation failed: ${err.message}`));
+    console.log(pc.dim("Install manually: brew tap jundot/omlx && brew install omlx"));
+    console.log(pc.dim("  — or download the macOS app from https://github.com/jundot/omlx/releases"));
+    return false;
+  }
+}
+
+/**
+ * Ensure oMLX runtime is available. For onboarding: if not installed, offer
+ * to install it. This is the oMLX equivalent of ensureLlamaRuntime().
+ *
+ * @param {object} prompt - UI prompt interface
+ * @param {function} [run] - runCommand function for verbose output
+ * @returns {Promise<boolean>} true if oMLX is available (installed or pre-existing)
+ */
+export async function ensureOmlxRuntime(prompt, run) {
+  let omlxBin = await findOmlx();
+  if (!omlxBin) {
+    console.log(renderCard("oMLX runtime", renderRows([
+      ["Status", pc.yellow("not installed")],
+      ["Used for", "local MLX models (Apple Silicon optimized)"],
+      ["Install", "managed by offgrid-ai via Homebrew"],
+    ]), { formatBorder: pc.cyan }));
+
+    const shouldInstall = await prompt.yesNo("Install oMLX runtime?", true);
+    if (shouldInstall) {
+      await installOmlx(prompt, run);
+      omlxBin = await findOmlx();
+    }
+
+    if (!omlxBin) {
+      console.log(pc.yellow("Skipping oMLX for now. You can still use llama.cpp, or run offgrid-ai again to install."));
+      return false;
+    }
+  }
+
+  const version = await installedOmlxVersion();
+  console.log(pc.green(`✓ oMLX: ${omlxBin}${version ? ` (v${version})` : ""}`));
+  return true;
+}

package/src/process.mjs

@@ -6,6 +6,7 @@ import { basename, join } from "node:path";
 import { LOG_DIR } from "./config.mjs";
 import { writeState, readState, profileDir } from "./profiles.mjs";
 import { backendFor, backendBinaryFor } from "./backends.mjs";
+import { pc } from "./ui.mjs";
 
 const execFileAsync = promisify(execFile);
 
@@ -21,7 +22,7 @@ export async function computeServerCommand(profile) {
   const binary = await backendBinaryFor(profile.backend);
   if (!binary) throw new Error("Server binary not found. Run offgrid-ai interactively to install.");
 
-  // llama-cpp / llama-cpp-mtp
+  // llama-cpp
   const { computeFlags } = await import("./autodetect.mjs");
   const result = computeFlags(
     profile.capabilities ?? {},
@@ -118,6 +119,10 @@ async function startLocalServer(profile) {
 
 async function startManagedServer(profile, backend) {
   if (await serverReady(profile.baseUrl)) {
+    // Apply per-model settings (MTP) even when server is already running.
+    if (backend.id === "omlx" && profile.capabilities?.mtp) {
+      await ensureOmlxMtpSetting(profile);
+    }
     return writeManagedState(profile, backend);
   }
 
@@ -126,9 +131,15 @@ async function startManagedServer(profile, backend) {
     try {
       const { execFile } = await import("node:child_process");
       const { promisify } = await import("node:util");
-      await promisify(execFile)("omlx", ["start"], { timeout: 10000 });
-    } catch {
-      throw new Error(`${backend.label} is not running and could not be auto-started. Install oMLX or run \`omlx start\` manually.`);
+      const { findOmlx } = await import("./omlx-runtime.mjs");
+      const omlxBin = await findOmlx();
+      if (!omlxBin) {
+        throw new Error(`${backend.label} is not installed. Run offgrid-ai to install it, or install manually: brew tap jundot/omlx && brew install omlx`);
+      }
+      await promisify(execFile)(omlxBin, ["start"], { timeout: 10000 });
+    } catch (err) {
+      if (err.message.includes("not installed")) throw err;
+      throw new Error(`${backend.label} could not be auto-started: ${err.message}. Run \`omlx start\` manually.`, { cause: err });
     }
   }
 
@@ -141,9 +152,48 @@ async function startManagedServer(profile, backend) {
   if (!(await serverReady(profile.baseUrl))) {
     throw new Error(`${backend.label} is not responding at ${profile.baseUrl}. Start it and try again.`);
   }
+
+  // Apply per-model settings (MTP) before the model is loaded.
+  // oMLX applies MTP patches at load time, so the setting must be in
+  // model_settings.json before any request triggers a load.
+  if (backend.id === "omlx" && profile.capabilities?.mtp) {
+    await ensureOmlxMtpSetting(profile);
+  }
+
   return writeManagedState(profile, backend);
 }
 
+/**
+ * Enable MTP on an oMLX model via the admin API before loading.
+ * oMLX applies MTP patches at model load time, so the setting must be
+ * persisted to model_settings.json before any request triggers a load.
+ * If the model is already loaded, oMLX will use the setting on next reload.
+ */
+async function ensureOmlxMtpSetting(profile) {
+  const baseUrl = profile.baseUrl?.replace(/\/v1\/?$/u, "") || "";
+  const modelId = profile.omlxModel ?? profile.modelAlias ?? profile.id;
+  try {
+    const response = await fetch(`${baseUrl}/admin/api/models/${encodeURIComponent(modelId)}/settings`, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ mtp_enabled: true }),
+      signal: AbortSignal.timeout(5000),
+    });
+    if (response.ok) {
+      console.log(pc.green(`[mtp] Enabled MTP speculative decoding for ${modelId}`));
+    } else if (response.status === 401 || response.status === 403) {
+      console.log(pc.yellow(`[mtp] Could not enable MTP: oMLX admin authentication required. Enable skip_api_key_verification in oMLX settings, or enable MTP manually from the admin panel.`));
+    } else if (response.status === 404) {
+      console.log(pc.yellow(`[mtp] Model ${modelId} not found on oMLX server. MTP setting not applied.`));
+    } else {
+      const detail = await response.text().catch(() => "");
+      console.log(pc.yellow(`[mtp] Could not enable MTP: HTTP ${response.status} ${detail}`));
+    }
+  } catch (err) {
+    console.log(pc.yellow(`[mtp] Could not enable MTP: ${err.message}`));
+  }
+}
+
 async function writeManagedState(profile, backend) {
   const state = {
     pid: null,
@@ -223,7 +273,7 @@ async function processGone(pid) {
 export async function unloadModelFromServer(profile) {
   const backend = backendFor(profile.backend);
 
-  if (backend.id === "llama-cpp" || backend.id === "llama-cpp-mtp") {
+  if (backend.id === "llama-cpp") {
     return { unloaded: false, backend: backend.id, reason: "stop server to unload" };
   }
 

package/src/profile-setup.mjs

@@ -3,12 +3,13 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { estimateMemory } from "./estimate.mjs";
 import { findLlamaServer } from "./config.mjs";
-import { baseUrlForFlags, LLAMA_CPP_PORT, LLAMA_CPP_MTP_PORT } from "./backends.mjs";
+import { baseUrlForFlags } from "./backends.mjs";
 import { pc, formatBytes, renderRows, renderSection } from "./ui.mjs";
 import { detectCapabilities } from "./autodetect.mjs";
 import { matchDrafter } from "./scan.mjs";
 import { scanGgufModels } from "./scan.mjs";
 import { capabilitySummary } from "./model-summary.mjs";
+import { detectOmlxMtpCapability, findOmlxModelDir } from "./mlx-discovery.mjs";
 
 const execFileAsync = promisify(execFile);
 
@@ -49,19 +50,9 @@ export async function configureLocalProfile(prompt, profile) {
   }
   const hasMtp = freshCaps.mtp || Boolean(drafterPath);
   const caps = { ...freshCaps, mtp: hasMtp };
-  // If MTP is newly available, switch backend and add drafter path
-  if (hasMtp && configured.backend !== "llama-cpp-mtp") {
-    configured = { ...configured, backend: "llama-cpp-mtp", providerId: "llama-cpp-mtp", drafterPath, capabilities: { ...configured.capabilities, mtp: true } };
-  }
-  // If the profile was MTP but the drafter is now gone (and the model isn't
-  // natively MTP), switch back to plain llama.cpp so the server can start.
-  if (!hasMtp && configured.backend === "llama-cpp-mtp") {
-    console.log(pc.yellow("MTP drafter no longer found — switching to llama.cpp without speculative decoding."));
-    configured = removeMtpDefaults(configured);
-  }
-  if (drafterPath && !configured.drafterPath) {
-    configured = { ...configured, drafterPath };
-  }
+  // MTP is a capability, not a separate backend. Just update the profile's
+  // capabilities and drafter path — flag computation handles the rest.
+  configured = { ...configured, drafterPath: drafterPath ?? null, capabilities: { ...configured.capabilities, mtp: hasMtp } };
   // If vision was previously disabled but mmproj is back, re-enable
   if (configured.disabledMmprojPath && configured.mmprojPath === null && freshCaps.vision) {
     configured = { ...configured, mmprojPath: configured.disabledMmprojPath, disabledMmprojPath: undefined, capabilities: { ...configured.capabilities, vision: true, visionDisabledReason: undefined } };
@@ -81,8 +72,7 @@ export async function configureLocalProfile(prompt, profile) {
   if (caps.mtp) {
     const drafterInfo = configured.drafterPath ? `\n  Drafter: ${configured.drafterPath}` : "";
     console.log(renderSection("MTP detected", renderRows([
-      ["Backend", "llama.cpp MTP"],
-      ["Port", String(LLAMA_CPP_MTP_PORT)],
+      ["Feature", "Multi-Token Prediction (speculative decoding)"],
       ["Flags", `--spec-type draft-mtp --spec-draft-n-max 4${configured.drafterPath ? " --spec-draft-model <drafter>" : ""}`],
     ])));
     if (drafterInfo) console.log(pc.dim(drafterInfo));
@@ -150,24 +140,60 @@ export function applyRuntimeFlagOverrides(profile, overrides) {
 }
 
 export function applyMtpDefaults(profile) {
-  const flags = { ...profile.flags, port: LLAMA_CPP_MTP_PORT };
   return applyProfileFlags({
     ...profile,
-    backend: "llama-cpp-mtp",
-    providerId: "llama-cpp-mtp",
     capabilities: { ...(profile.capabilities ?? {}), mtp: true },
-  }, flags);
+  }, profile.flags);
 }
 
 export function removeMtpDefaults(profile) {
-  const flags = { ...profile.flags, port: LLAMA_CPP_PORT };
   return applyProfileFlags({
     ...profile,
-    backend: "llama-cpp",
-    providerId: "llama-cpp",
     drafterPath: null,
     capabilities: { ...(profile.capabilities ?? {}), mtp: false },
-  }, flags);
+  }, profile.flags);
+}
+
+// ── oMLX (managed server) profile configuration ───────────────────────────
+
+export async function configureManagedProfile(prompt, profile) {
+  let configured = profile;
+  const modelId = profile.omlxModel ?? profile.modelAlias ?? profile.id;
+
+  // Detect MTP capability from the model's config.json
+  const modelDir = await findOmlxModelDir(modelId);
+  if (modelDir) {
+    const mtpResult = await detectOmlxMtpCapability(modelDir);
+    if (mtpResult.compatible) {
+      console.log("");
+      console.log(renderSection("MTP detected", renderRows([
+        ["Feature", "Multi-Token Prediction (speculative decoding)"],
+        ["Mechanism", "oMLX native MTP (enabled via admin API at load time)"],
+      ])));
+      const useMtp = await prompt.yesNo("Use MTP speculative decoding?", true);
+      configured = { ...configured, capabilities: { ...(configured.capabilities ?? {}), mtp: useMtp } };
+    } else if (mtpResult.reason !== "model has no MTP heads in config") {
+      // Model declares MTP but can't use it — surface the reason
+      console.log("");
+      console.log(renderSection("MTP not available", renderRows([
+        ["Feature", "Multi-Token Prediction (speculative decoding)"],
+        ["Reason", pc.yellow(mtpResult.reason)],
+      ])));
+    }
+    // If reason is "no MTP heads in config", don't surface anything —
+    // most models don't have MTP, and showing a card for every non-MTP
+    // model would be noise.
+  }
+
+  console.log("");
+  console.log(renderSection("Model setup", renderRows([
+    ["Model", pc.bold(profile.label)],
+    ["Backend", "oMLX"],
+    ...(configured.capabilities?.mtp ? [["MTP", "enabled"]] : []),
+  ])));
+
+  if (!(await prompt.yesNo("Save profile with these settings?", true))) return null;
+  return configured;
 }
 
 function applyVisionDefaults(profile) {

package/src/profiles.mjs

@@ -40,7 +40,15 @@ export async function loadProfiles() {
     .filter((e) => e.isDirectory() && existsSync(profileJsonPath(e.name)))
     .map((e) => e.name)
     .sort();
-  return (await Promise.all(ids.map((id) => readProfile(id)))).filter((p) => BACKENDS[p.backend]);
+  return (await Promise.all(ids.map((id) => readProfile(id))))
+    .map((p) => {
+      // Migrate legacy llama-cpp-mtp backend → llama-cpp with mtp capability
+      if (p.backend === "llama-cpp-mtp") {
+        return { ...p, backend: "llama-cpp", providerId: "llama-cpp", capabilities: { ...(p.capabilities ?? {}), mtp: true } };
+      }
+      return p;
+    })
+    .filter((p) => BACKENDS[p.backend]);
 }
 
 export async function readProfile(id) {
@@ -49,7 +57,7 @@ export async function readProfile(id) {
   return JSON.parse(await readFile(path, "utf8"));
 }
 
-export async function saveProfile(profile, options = {}) {
+export async function saveProfile(profile) {
   const id = sanitizeProfileId(profile.id);
   const dir = profileDir(id);
   await mkdir(dir, { recursive: true });
@@ -126,7 +134,7 @@ export async function createProfileFromModel(model, backendId, drafterPath) {
   const caps = detectCapabilities(model.path, model.mmprojPath);
   // If a drafter is provided, this model supports MTP regardless of filename
   const hasMtp = caps.mtp || Boolean(drafterPath);
-  const backend = backendId ?? (hasMtp ? "llama-cpp-mtp" : "llama-cpp");
+  const backend = backendId ?? "llama-cpp";
   const { flags } = computeFlags(
     { ...caps, mtp: hasMtp },
     model.path,

package/src/ui.mjs

@@ -106,25 +106,7 @@ export function renderCard(title, body, options = {}) {
 }
 
 function wrapVisible(text, width) {
-  const words = String(text).split(/(\s+)/u);
-  const lines = [];
-  let current = "";
-  for (let word of words) {
-    // If a single word exceeds the width, hard-break it
-    while (visibleLen(word) > width) {
-      if (current.trim()) { lines.push(current.trimEnd()); current = ""; }
-      lines.push(word.slice(0, width));
-      word = word.slice(width);
-    }
-    if (visibleLen(current + word) > width && current.trim()) {
-      lines.push(current.trimEnd());
-      current = word.trimStart();
-    } else {
-      current += word;
-    }
-  }
-  if (current.trim()) lines.push(current.trimEnd());
-  return lines.length > 0 ? lines : [text];
+  return wrapText(text, width);
 }
 
 export function renderSectionRows(title, rows, options = {}) {
@@ -221,6 +203,7 @@ export function createPrompt() {
           if (!Number.isFinite(input) || input < min || input > max) {
             return `Enter a number from ${min} to ${max}.`;
           }
+          return true;
         },
       });
       return Number(value);