offgrid-ai 0.9.5 → 0.10.0

package/src/benchmark/metrics.mjs

@@ -1,9 +1,10 @@
 // ── Backend-aware server speed metrics ───────────────────────────────────────
 
 import { backendFor } from "../backends.mjs";
-import { apiRootUrl } from "../process.mjs";
 
 const BENCH_SPEED_PROMPT = "Write a one-sentence summary of machine learning.";
+const SPEED_QUERY_TIMEOUT_MS = 120_000;
+const SPEED_QUERY_MAX_TOKENS = 64;
 
 export async function queryServerMetrics(profile) {
   const backend = backendFor(profile.backend);
@@ -14,9 +15,6 @@ export async function queryServerMetrics(profile) {
   if (backend.id === "omlx") {
     return await queryOmlxMetrics(profile);
   }
-  if (backend.id === "ollama") {
-    return await queryOllamaMetrics(profile);
-  }
 
   throw new Error(`Unsupported backend for benchmark speed metrics: ${backend.id}`);
 }
@@ -26,13 +24,14 @@ async function queryLlamaCppMetrics(profile) {
     model: profile.modelAlias,
     messages: [{ role: "user", content: BENCH_SPEED_PROMPT }],
     stream: false,
+    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(60000),
+    signal: AbortSignal.timeout(SPEED_QUERY_TIMEOUT_MS),
   });
 
   if (!response.ok) {
@@ -66,13 +65,14 @@ async function queryOmlxMetrics(profile) {
     messages: [{ role: "user", content: BENCH_SPEED_PROMPT }],
     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(60000),
+    signal: AbortSignal.timeout(SPEED_QUERY_TIMEOUT_MS),
   });
 
   if (!response.ok) {
@@ -111,42 +111,3 @@ async function queryOmlxMetrics(profile) {
     metricSource: "oMLX /v1/chat/completions streaming include_usage",
   };
 }
-
-async function queryOllamaMetrics(profile) {
-  const body = {
-    model: profile.modelAlias,
-    prompt: BENCH_SPEED_PROMPT,
-    stream: false,
-  };
-
-  const apiBaseUrl = apiRootUrl(profile.baseUrl || backendFor(profile.backend).apiBaseUrl || "");
-
-  const response = await fetch(`${apiBaseUrl}/api/generate`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(body),
-    signal: AbortSignal.timeout(60000),
-  });
-
-  if (!response.ok) {
-    throw new Error(`Ollama speed query failed: ${response.status} ${response.statusText}`);
-  }
-
-  const data = await response.json();
-  const promptEvalNs = data.prompt_eval_duration ?? 0;
-  const evalNs = data.eval_duration ?? 0;
-  const loadNs = data.load_duration ?? 0;
-
-  const promptEvalCount = data.prompt_eval_count ?? 0;
-  const evalCount = data.eval_count ?? 0;
-
-  return {
-    prefillTokensPerSecond: promptEvalNs > 0 ? (promptEvalCount / (promptEvalNs / 1e9)) : null,
-    generationTokensPerSecond: evalNs > 0 ? (evalCount / (evalNs / 1e9)) : null,
-    ttftMs: promptEvalNs / 1e6,
-    modelLoadMs: loadNs / 1e6,
-    speculativeDecodeAcceptance: null,
-    kvCacheTokens: null,
-    metricSource: "Ollama /api/generate",
-  };
-}

package/src/benchmark/pi-runner.mjs

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { spawn } from "node:child_process";
 import {
   BENCH_COLORS, renderStreamEvent,
-  formatToolCall, printFinalLine,
+  formatToolCall, printFinalLine, stopExecTimer,
 } from "./stream-renderer.mjs";
 import { piModelString } from "./shared.mjs";
 
@@ -58,7 +58,8 @@ export async function runBenchmarkInPi(profile, runDirectory, { signal } = {}) {
     turnHadToolError: false,
     modelPrinted: false,
     activeTool: null,
-    status: { mode: "idle", toolName: null, bytes: 0, tokens: 0 },
+    execTimer: null,
+    status: { mode: "idle", toolName: null, bytes: 0, tokens: 0, execStartedAt: null },
   };
 
   function appendResponse(text) {
@@ -193,6 +194,7 @@ export async function runBenchmarkInPi(profile, runDirectory, { signal } = {}) {
   return new Promise((resolve) => {
     child.on("exit", async (code) => {
       if (signal) signal.removeEventListener("abort", abortListener);
+      stopExecTimer(renderState);
       if (streamBuffer.trim()) {
         processLine(streamBuffer);
       }
@@ -225,6 +227,7 @@ export async function runBenchmarkInPi(profile, runDirectory, { signal } = {}) {
 
     child.on("error", async (err) => {
       if (signal) signal.removeEventListener("abort", abortListener);
+      stopExecTimer(renderState);
       await streamHandle.close();
       await stderrHandle.close();
       runResult.error = { message: err.message };

package/src/benchmark/prepare.mjs

@@ -55,7 +55,7 @@ export async function prepareBenchmarkRun({ repoPath, benchmark, kind, modelId,
     kind,
     runId,
     benchmark: { id: benchmark.id, title: benchmark.title, description: benchmark.description, prompt: benchmark.prompt },
-    model: { id: modelId, slug: modelSlug, displayName: parseModelName(modelId, modelSource === "ollama" ? "ollama" : modelSource === "omlx" ? "omlx" : "local-gguf").display },
+    model: { id: modelId, slug: modelSlug, displayName: parseModelName(modelId, modelSource === "omlx" ? "omlx" : "local-gguf").display },
     status: "prepared",
     createdAt: now.toISOString(),
     updatedAt: now.toISOString(),

package/src/benchmark/stream-renderer.mjs

@@ -107,6 +107,7 @@ export function renderStreamEvent(parsed, state, opts = {}) {
       };
       resetStatus(state, "exec", parsed.toolName);
       printFinalLine(BENCH_COLORS.tool(formatToolStart(parsed.toolName, parsed.args ?? {}, state)));
+      startExecTimer(state);
       break;
     }
     case "tool_execution_update": {
@@ -114,11 +115,13 @@ export function renderStreamEvent(parsed, state, opts = {}) {
       if (text) {
         if (verbose) process.stdout.write(BENCH_COLORS.toolOutput(text));
         if (state.activeTool) state.activeTool.outputText = text;
-        updateStatusFromDelta(state, text, "exec");
+        state.status.bytes += Buffer.byteLength(text, "utf8");
+        printExecStatus(state);
       }
       break;
     }
     case "tool_execution_end": {
+      stopExecTimer(state);
       const lines = formatToolEnd(parsed, state);
       if (parsed.isError) state.turnHadToolError = true;
       for (const line of lines) printFinalLine(line);
@@ -133,6 +136,7 @@ export function renderStreamEvent(parsed, state, opts = {}) {
       break;
     }
     case "turn_end": {
+      stopExecTimer(state);
       const usage = parsed.message?.usage;
       const tokenPart = usage ? ` · ${formatTokens(usage.output ?? usage.totalTokens ?? 0)} tokens` : "";
       const marker = state.turnHadToolError ? BENCH_COLORS.warning("⚠") : BENCH_COLORS.success("✓");
@@ -141,7 +145,7 @@ export function renderStreamEvent(parsed, state, opts = {}) {
       break;
     }
     case "agent_end":
-      clearStatusLine();
+      stopExecTimer(state);
       break;
     default:
       break;
@@ -172,6 +176,31 @@ export function updateStatusFromDelta(state, delta, mode = state.status.mode) {
   printStatusLine(BENCH_COLORS.dim(`Turn ${state.turn} ${modeLabel}${label} · ${bytes} (~${tokens} tokens)`));
 }
 
+export function startExecTimer(state) {
+  stopExecTimer(state);
+  state.status.execStartedAt = Date.now();
+  state.status.bytes = 0;
+  if (!process.stdout.isTTY) return;
+  printExecStatus(state);
+  state.execTimer = setInterval(() => printExecStatus(state), 1000);
+}
+
+export function stopExecTimer(state) {
+  if (state.execTimer) {
+    clearInterval(state.execTimer);
+    state.execTimer = null;
+  }
+  clearStatusLine();
+}
+
+export function printExecStatus(state) {
+  if (!process.stdout.isTTY) return;
+  const elapsed = state.status.execStartedAt ? Math.floor((Date.now() - state.status.execStartedAt) / 1000) : 0;
+  const tool = state.status.toolName ?? "tool";
+  const bytes = formatBytes(state.status.bytes);
+  printStatusLine(BENCH_COLORS.dim(`Turn ${state.turn} running ${tool}… ${elapsed}s · ${bytes}`));
+}
+
 export function formatToolStart(toolName, args, state) {
   if (toolName === "read") return `→ read ${displayPath(args.path, state)}`;
   if (toolName === "write") {

package/src/benchmark.mjs

@@ -6,5 +6,7 @@ export { findBenchmarkRepo, linkBenchmarkRepo } from "./benchmark/repo.mjs";
 export { prepareBenchmarkRun } from "./benchmark/prepare.mjs";
 export { runBenchmarkInPi } from "./benchmark/pi-runner.mjs";
 export { queryServerMetrics } from "./benchmark/metrics.mjs";
-export { unloadModelFromServer, finalizeBenchmarkRun, renderBenchmarkSummary } from "./benchmark/finalize.mjs";
+// unloadModelFromServer now lives in src/process.mjs (managed-server counterpart to stopProfile).
+export { unloadModelFromServer } from "./process.mjs";
+export { finalizeBenchmarkRun, renderBenchmarkSummary } from "./benchmark/finalize.mjs";
 export { benchmarkForProfile, benchmarkFlow } from "./benchmark/flow.mjs";

package/src/commands/main.mjs

@@ -4,7 +4,7 @@ import { scanGgufModels } from "../scan.mjs";
 import { loadProfiles } from "../profiles.mjs";
 import { hasPi } from "../harness-pi.mjs";
 import { offerManagedLlamaRuntimeUpdate } from "../runtime.mjs";
-import { hasLmStudioInstalled, hasOllamaInstalled, hasOmlxInstalled, scanManagedModels } from "../managed.mjs";
+import { hasLmStudioInstalled, hasOmlxInstalled, scanManagedModels } from "../managed.mjs";
 import { recommendedModel } from "../recommendations.mjs";
 import { pc, startInteractive, createPrompt } from "../ui.mjs";
 import { onboardFlow } from "./onboard.mjs";
@@ -63,9 +63,9 @@ 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 [ollamaInstalled, omlxInstalled] = await Promise.all([hasOllamaInstalled(), hasOmlxInstalled()]);
+  const omlxInstalled = await hasOmlxInstalled();
   const lmStudioInstalled = hasLmStudioInstalled();
-  const hasBackends = llamaBinary || ollamaInstalled || omlxInstalled || lmStudioInstalled;
+  const hasBackends = llamaBinary || omlxInstalled || lmStudioInstalled;
   if (!hasBackends) {
     console.log(pc.dim("Run offgrid-ai to install a backend and download a model."));
     return;
@@ -73,7 +73,6 @@ async function printNoModelsHelp(llamaBinary) {
 
   console.log(pc.bold("Backend status:"));
   console.log(`  ${lmStudioInstalled ? pc.green("✓") : pc.red("✗")} LM Studio ${lmStudioInstalled ? "— installed" : "— not installed"}`);
-  console.log(`  ${ollamaInstalled ? pc.green("✓") : pc.red("✗")} Ollama ${ollamaInstalled ? "— installed" : "— not installed"}`);
   console.log(`  ${omlxInstalled ? pc.green("✓") : pc.red("✗")} oMLX ${omlxInstalled ? "— installed" : "— not installed"}`);
   console.log(`  ${llamaBinary ? pc.green("✓") : pc.red("✗")} llama-server ${llamaBinary ? "— installed" : "— not installed"}`);
   console.log();
@@ -84,6 +83,5 @@ async function printNoModelsHelp(llamaBinary) {
     console.log("  Open LM Studio → browse models → download");
     console.log(pc.dim(`  Recommended: ${model.label}`));
   }
-  if (ollamaInstalled) console.log(pc.bold(`  ollama pull ${model.ollama}`));
   if (omlxInstalled) console.log(pc.bold("  omlx start"));
 }

package/src/commands/models.mjs

@@ -1,12 +1,12 @@
 import { ensureDirs } from "../config.mjs";
 import { backendFor, BACKENDS } from "../backends.mjs";
 import { createProfileFromModel, readProfile, saveProfile, deleteProfile, profileJsonPath } from "../profiles.mjs";
-import { isProfileRunning, isProfileServerUp, stopProfile } from "../process.mjs";
+import { isProfileRunning, isProfileServerUp, modelAvailableOnServer, stopProfile } from "../process.mjs";
 import { syncPiConfig, removeFromPiConfig } from "../harness-pi.mjs";
 import { configureLocalProfile } from "../profile-setup.mjs";
 import { pc, startInteractive, createPrompt } from "../ui.mjs";
 import { buildCatalogItems, createManagedProfile, itemKey, loadModelCatalog, normalizeCatalog } from "../model-catalog.mjs";
-import { modelSelectOption, modelNameWidth, printGgufModelDetails, printManagedModelDetails, printWorkspaceHeader, printBenchmarkLine, printProfileDetails } from "../model-presenters.mjs";
+import { modelSelectOption, modelNameWidth, printGgufModelDetails, printMlxModelDetails, printManagedModelDetails, printWorkspaceHeader, printBenchmarkLine, printProfileDetails } from "../model-presenters.mjs";
 import { runProfile } from "./run.mjs";
 
 const { stripVTControlCharacters } = await import("node:util");
@@ -40,15 +40,17 @@ export async function modelCommandCenter(initialCatalog) {
   }
 
   const runningProfilesNow = [];
-  const serverUpIds = new Set();
+  const modelMissingIds = new Set();
   for (const profile of normalized.profiles) {
     if (await isProfileRunning(profile)) {
       runningProfilesNow.push(profile);
       continue;
     }
-    if (backendFor(profile.backend).type === "managed-server" && await isProfileServerUp(profile)) serverUpIds.add(profile.id);
+    if (backendFor(profile.backend).type === "managed-server" && await isProfileServerUp(profile)) {
+      if (!(await modelAvailableOnServer(profile))) modelMissingIds.add(profile.id);
+    }
   }
-  printWorkspaceHeader(normalized, runningProfilesNow, serverUpIds);
+  printWorkspaceHeader(normalized, runningProfilesNow, modelMissingIds);
   await printBenchmarkLine();
 
   const nameWidth = modelNameWidth(allItems);
@@ -57,13 +59,13 @@ export async function modelCommandCenter(initialCatalog) {
     if (item.type === "profile") {
       if (item.fileMissing) return "missing";
       if (runningProfilesNow.some((profile) => profile.id === item.profile.id)) return "running";
-      if (serverUpIds.has(item.profile.id)) return "serverup";
+      if (modelMissingIds.has(item.profile.id)) return "missing";
       return "ready";
     }
     return "setup";
   };
 
-  const groupOrder = ["running", "serverup", "ready", "setup", "missing"];
+  const groupOrder = ["running", "ready", "setup", "missing"];
   const grouped = new Map(groupOrder.map((key) => [key, []]));
   for (const item of allItems) grouped.get(statusFor(item)).push(item);
 
@@ -72,8 +74,8 @@ export async function modelCommandCenter(initialCatalog) {
     const bucket = grouped.get(group);
     if (!bucket || bucket.length === 0) continue;
     for (const item of bucket) {
-      const opt = modelSelectOption(item, { runningProfilesNow, serverUpIds, nameWidth });
-      choices.push({ value: opt.value, label: opt.label });
+      const opt = modelSelectOption(item, { runningProfilesNow, modelMissingIds, nameWidth, managedModels: catalog.managedModels });
+      choices.push({ value: opt.value, label: opt.label, hint: opt.hint });
     }
   }
 
@@ -154,6 +156,7 @@ async function performAction(prompt, action, item) {
   if (action === "inspect") {
     if (item.type === "profile") return await printProfileDetails(await readProfile(item.profile.id));
     if (item.type === "managed") return printManagedModelDetails(item.model, BACKENDS[item.backendId]);
+    if (item.model?.format === "mlx") return await printMlxModelDetails(item.model);
     return printGgufModelDetails(item.model, item.drafter);
   }
   if (action === "benchmark") {
@@ -164,20 +167,13 @@ async function performAction(prompt, action, item) {
     const { benchmarkFlow } = await import("../benchmark.mjs");
     return await benchmarkFlow();
   }
-  if (action === "run") return await runItem(prompt, item);
+  if (action === "run") return await runItem(item);
   if (action === "reconfigure" || action === "setup") return await setupItem(prompt, item, action);
   if (action === "remove" && item.type === "profile") return await removeProfileInteractive(item.profile.id);
 }
 
-async function runItem(prompt, item) {
-  if (item.type === "profile") return await runProfile(await readProfile(item.profile.id));
-  const profile = await createProfileFromModel(item.model, null, item.drafter?.path);
-  const configured = await configureLocalProfile(prompt, profile);
-  if (!configured) return;
-  await saveProfile(configured);
-  await syncPiConfig(configured);
-  printProfileSaved(configured.id);
-  return await runProfile(configured);
+async function runItem(item) {
+  return await runProfile(await readProfile(item.profile.id));
 }
 
 function printProfileSaved(id) {
@@ -200,6 +196,18 @@ async function setupItem(prompt, item, action) {
     printProfileSaved(profile.id);
     return;
   }
+  // MLX models: build a mlx-vlm profile and run interactive config.
+  if (item.model.format === "mlx") {
+    const { createProfileFromMlxModel } = await import("../profiles.mjs");
+    const { configureMlxProfile } = await import("../profile-setup.mjs");
+    const profile = await createProfileFromMlxModel(item.model);
+    const configured = await configureMlxProfile(prompt, profile);
+    if (!configured) return;
+    await saveProfile(configured, { writeCommand: true });
+    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;

package/src/commands/onboard.mjs

@@ -1,14 +1,17 @@
 import { existsSync } from "node:fs";
-import { ensureDirs, findLlamaServer, hasHomebrew } from "../config.mjs";
+import { ensureDirs, findLlamaServer, hasHomebrew, HF_HUB_DIR } from "../config.mjs";
 import { BACKENDS } from "../backends.mjs";
 import { scanGgufModels } from "../scan.mjs";
+import { scanMlxModels } from "../mlx-discovery.mjs";
 import { hasPi } from "../harness-pi.mjs";
 import { offerManagedLlamaRuntimeUpdate } from "../runtime.mjs";
 import { scanManagedModels } from "../managed.mjs";
 import { BACKEND_INSTALL_CHOICES, BACKEND_INSTALLERS } from "../backend-installers.mjs";
-import { installedRamGB, recommendedModel } from "../recommendations.mjs";
+import { recommendedModel, selectFormat, allFittingModels } from "../recommendations.mjs";
+import { hasHuggingfaceHub, resolveHfDownload, downloadToHfCache } from "../huggingface.mjs";
+import { detectHardware, getFreeDiskBytes, installedRamGB } from "../hardware.mjs";
 import { runCommand } from "../exec.mjs";
-import { pc, renderRows, renderSection, startInteractive, createPrompt } from "../ui.mjs";
+import { pc, formatBytes, renderRows, renderSection, startInteractive, createPrompt } from "../ui.mjs";
 
 export async function onboardFlow() {
   await ensureDirs();
@@ -24,14 +27,22 @@ export async function onboardFlow() {
     const llamaBinary = await ensureLlamaRuntime(prompt);
     if (!(await ensurePi(prompt, run))) return;
 
-    const { models: ggufModels } = await scanGgufModels();
-    const managedModels = await scanManagedModels();
+    const [{ models: ggufModels }, managedModels, mlxModels] = await Promise.all([
+      scanGgufModels(),
+      scanManagedModels(),
+      scanMlxModels(),
+    ]);
     const totalManaged = managedModels.reduce((sum, item) => sum + item.models.length, 0);
-    const hasModels = ggufModels.length > 0 || totalManaged > 0;
+    const hasModels = ggufModels.length > 0 || totalManaged > 0 || mlxModels.length > 0;
 
     if (hasModels) {
-      printFoundModels(ggufModels, managedModels, llamaBinary);
+      printFoundModels(ggufModels, managedModels, mlxModels, llamaBinary);
     } else {
+      const canDownload = await hasHuggingfaceHub();
+      if (canDownload) {
+        const downloaded = await offerModelDownload(prompt);
+        if (downloaded) return;
+      }
       await offerBackendInstall(prompt, run);
       return;
     }
@@ -52,7 +63,7 @@ async function ensureLlamaRuntime(prompt) {
     ]), { formatBorder: pc.cyan }));
     await offerManagedLlamaRuntimeUpdate(prompt);
     llamaBinary = await findLlamaServer();
-    if (!llamaBinary) console.log(pc.yellow("Skipping llama.cpp for now. You can still use Ollama/oMLX, or run offgrid-ai again to install the managed runtime."));
+    if (!llamaBinary) console.log(pc.yellow("Skipping llama.cpp for now. You can still use oMLX, or run offgrid-ai again to install the managed runtime."));
   }
   if (llamaBinary) console.log(pc.green(`✓ llama-server: ${llamaBinary}`));
   return llamaBinary;
@@ -85,11 +96,14 @@ async function ensurePi(prompt, run) {
   return true;
 }
 
-function printFoundModels(ggufModels, managedModels, llamaBinary) {
+function printFoundModels(ggufModels, managedModels, mlxModels, llamaBinary) {
   if (ggufModels.length > 0) {
     console.log(pc.green(`✓ Found ${ggufModels.length} GGUF model${ggufModels.length === 1 ? "" : "s"}`));
     if (!llamaBinary) console.log(pc.yellow("Install the managed llama.cpp runtime to run these GGUF models."));
   }
+  if (mlxModels.length > 0) {
+    console.log(pc.green(`✓ Found ${mlxModels.length} MLX model${mlxModels.length === 1 ? "" : "s"}`));
+  }
   for (const { backendId, models, status, reason } of managedModels) {
     if (status === "unavailable") {
       console.log(pc.yellow(`${BACKENDS[backendId].label}: unavailable${reason ? ` — ${reason}` : ""}`));
@@ -99,6 +113,50 @@ function printFoundModels(ggufModels, managedModels, llamaBinary) {
   }
 }
 
+async function offerModelDownload(prompt) {
+  const hardware = detectHardware();
+  const candidates = allFittingModels(hardware)
+    .map((entry) => ({ entry, format: selectFormat(entry, hardware) }))
+    .filter((item) => item.format != null);
+  if (candidates.length === 0) {
+    console.log(pc.yellow("No curated models fit your hardware."));
+    return false;
+  }
+
+  const primary = candidates[0];
+  console.log(renderSection("Download a recommended model", renderRows([
+    ["Model", pc.bold(primary.entry.label)],
+    ["Format", primary.format],
+    ["Minimum RAM", String(primary.entry.minRamGb) + " GB"],
+    ["Your RAM", installedRamGB() + " GB"],
+  ]), { formatBorder: pc.cyan }));
+
+  const shouldDownload = await prompt.yesNo("Download " + primary.entry.label + " (" + primary.format + ")?", true);
+  if (!shouldDownload) return false;
+
+  const hfRef = primary.format === "mlx" ? primary.entry.mlx : primary.entry.gguf;
+  try {
+    const plan = await resolveHfDownload(hfRef);
+    console.log(pc.dim("Total size: " + formatBytes(plan.totalSizeBytes)));
+    const freeBytes = getFreeDiskBytes(HF_HUB_DIR);
+    if (plan.totalSizeBytes > 0 && freeBytes < plan.totalSizeBytes * 1.1) {
+      console.log(pc.red(`Not enough disk space in ${HF_HUB_DIR}: need ~${formatBytes(plan.totalSizeBytes)}, only ${formatBytes(freeBytes)} free.`));
+      return false;
+    }
+    await downloadToHfCache(plan, {
+      onProgress({ percentage }) {
+        process.stdout.write(pc.cyan("\r  " + percentage + "% downloaded"));
+      },
+    });
+    process.stdout.write("\n");
+    console.log(pc.green("✓ Download complete. Run offgrid-ai to use the model."));
+    return true;
+  } catch (err) {
+    console.log(pc.red("Download failed: " + err.message));
+    return false;
+  }
+}
+
 async function offerBackendInstall(prompt, run) {
   console.log(pc.yellow("\nNo models found."));
   console.log(pc.dim("You need at least one model backend to use offgrid-ai.\n"));

package/src/commands/run.mjs

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import { ensureDirs } from "../config.mjs";
 import { backendFor } from "../backends.mjs";
 import { normalizeProfile, readProfile, saveProfile } from "../profiles.mjs";
-import { startServer, stopProfile, waitForReady, serverReady, serverMatchesProfile, modelAvailableOnServer } from "../process.mjs";
+import { startServer, stopProfile, waitForReady, serverReady, serverMatchesProfile, modelAvailableOnServer, unloadModelFromServer } from "../process.mjs";
 import { syncPiConfig, hasPiModel, launchPi, hasPi } from "../harness-pi.mjs";
 import { tailFriendly } from "../logs.mjs";
 import { estimateMemory } from "../estimate.mjs";
@@ -35,7 +35,7 @@ export async function runProfile(profile, options = {}) {
     }
     const available = await modelAvailableOnServer(profile);
     if (!available) {
-      const modelId = profile.omlxModel ?? profile.ollamaModel ?? profile.modelAlias ?? profile.label;
+      const modelId = profile.omlxModel ?? profile.modelAlias ?? profile.label;
       throw new Error(`${modelId} is not available on ${backend.label} at ${profile.baseUrl}.`);
     }
     console.log(pc.green(`[ready] ${backend.label} at ${profile.baseUrl}`));
@@ -116,9 +116,24 @@ async function launchHarness(profile, options, isManaged, withHarness, backend)
   try {
     await launchPi(profile);
   } finally {
-    if (!isManaged && !options["keep-server"]) {
-      const result = await stopProfile(profile);
-      console.log(result.stopped ? pc.green(`[stop] ${result.message}`) : pc.dim(`[stop] ${result.message}`));
+    if (!options["keep-server"]) {
+      if (!isManaged) {
+        const result = await stopProfile(profile);
+        console.log(result.stopped ? pc.green(`[stop] ${result.message}`) : pc.dim(`[stop] ${result.message}`));
+      } else {
+        // Managed-server backends (oMLX): unload the model from the
+        // server's memory via its HTTP API. The server itself stays running
+        // (offgrid-ai doesn't manage it), but the model is released — same UX
+        // as local-server backends where stopProfile kills the process.
+        const result = await unloadModelFromServer(profile);
+        if (result.unloaded) {
+          console.log(pc.green(`[unload] ${backend.label}: model unloaded`));
+        } else if (result.reason) {
+          console.log(pc.dim(`[unload] ${backend.label}: ${result.reason}`));
+        } else if (result.error) {
+          console.log(pc.yellow(`[unload] ${backend.label}: ${result.error}`));
+        }
+      }
     }
   }
 }

package/src/commands/status.mjs

@@ -42,7 +42,7 @@ export async function statusCommand() {
     const detailRows = [];
     for (const { profile, status } of [...managedUpMissing, ...managedUpNotLoaded]) {
       const backend = backendFor(profile.backend);
-      const modelId = profile.omlxModel ?? profile.ollamaModel ?? profile.modelAlias ?? profile.id;
+      const modelId = profile.omlxModel ?? profile.modelAlias ?? profile.id;
       const state = status.modelAvailable
         ? pc.yellow("server up · model not loaded")
         : pc.red("server up · model missing");

package/src/config.mjs

@@ -15,9 +15,17 @@ export const MANAGED_LLAMA_SERVER = join(RUNTIME_DIR, "bin", "llama-server");
 
 // ── Default scan directories ──────────────────────────────────────────────
 
+// HuggingFace hub cache: $HF_HUB_CACHE, else $HF_HOME/hub, else
+// ~/.cache/huggingface/hub. This is where huggingface_hub stores
+// models--org--name/... and where offgrid-ai scans + downloads. Pointing at the
+// hub (not the HF root) keeps the HF-hub MLX/GGUF scanners and the downloader
+// on the same layout.
+export const HF_HUB_DIR = process.env.HF_HUB_CACHE
+  || (process.env.HF_HOME ? join(process.env.HF_HOME, "hub") : join(homedir(), ".cache", "huggingface", "hub"));
+
 export const DEFAULT_MODEL_DIRS = [
   join(homedir(), ".lmstudio", "models"),
-  join(homedir(), ".cache", "huggingface", "hub"),
+  HF_HUB_DIR,
 ];
 
 // ── External config paths ─────────────────────────────────────────────────
@@ -65,7 +73,8 @@ export async function saveConfig(config) {
 
 export async function getModelScanDirs() {
   const config = await loadConfig();
-  return [...DEFAULT_MODEL_DIRS, ...config.modelScanDirs];
+  // Dedupe (a user may list a default dir explicitly) so we never scan twice.
+  return [...DEFAULT_MODEL_DIRS, ...config.modelScanDirs].filter((dir, i, arr) => arr.indexOf(dir) === i);
 }
 
 // ── Binary discovery ──────────────────────────────────────────────────────

package/src/discovery-shared.mjs

@@ -0,0 +1,44 @@
+// Shared discovery helpers used by both the GGUF scanner (scan.mjs) and the
+// MLX scanner (mlx-discovery.mjs). Keeping these here avoids a cross-dependency
+// between the two format-specific scanners.
+
+import { basename, dirname } from "node:path";
+
+/** Minimum on-disk size for a model to count as real (skips tiny test/embedding files). */
+export const MIN_MODEL_SIZE_BYTES = 10 * 1024 * 1024; // 10 MB
+
+/**
+ * Model-type / architecture names that indicate an embedding model. Shared by
+ * GGUF filtering (general.architecture) and MLX filtering (config.model_type /
+ * architectures[0]). Format-specific heuristics (e.g. GGUF filename patterns)
+ * live alongside this set in each scanner.
+ */
+export const EMBEDDING_MODEL_TYPES = new Set([
+  "bert",
+  "roberta",
+  "mpnet",
+  "nomic_bert",
+  "nomic-bert",
+  "jina",
+  "e5",
+  "gte",
+  "bge",
+  "all_minilm",
+  "all-minilm",
+  "sentence_transformers",
+  "sentence-transformers",
+]);
+
+/**
+ * Infer a human-readable source label from a model scan path.
+ * Generic container folders (models, hub, cache) defer to their parent name
+ * (e.g. ~/.cache/huggingface/hub -> "huggingface"; ~/.lmstudio/models -> "lmstudio").
+ */
+export function inferSourceLabel(scanPath) {
+  const name = basename(scanPath).replace(/^\./, "");
+  const parent = basename(dirname(scanPath));
+  if (name === "models" || name === "hub" || name === "cache") {
+    return parent.replace(/^\./, "");
+  }
+  return name;
+}