offgrid-ai 0.3.29 → 0.3.31

package/README.md

@@ -19,7 +19,7 @@ curl -fsSL https://raw.githubusercontent.com/eeshansrivastava89/offgrid-ai/main/
 
 You run `offgrid-ai`. It finds your local models, auto-configures everything, starts the server, and launches Pi. Zero configuration. No parameter tuning. No presets.
 
-**First run** walks you through installing anything missing (Homebrew, llama-server). After that, just run it.
+**First run** walks you through installing anything missing. For GGUF models, offgrid-ai installs a managed `llama.cpp` runtime under `~/.offgrid-ai/runtime`; Homebrew is only used if you choose Homebrew-installed apps like LM Studio, Ollama, or oMLX.
 
 ```bash
 offgrid-ai          # pick a model and run it
@@ -49,7 +49,7 @@ curl -fsSL https://raw.githubusercontent.com/eeshansrivastava89/offgrid-ai/main/
 
 ## How it works
 
-1. **Auto-detect everything.** Scans for GGUF models in LM Studio, HuggingFace, and Ollama directories. Reads model metadata (quantization, context size, vision, thinking mode) directly from the GGUF file. No presets, no manual configuration.
+1. **Auto-detect everything.** Scans for GGUF models in LM Studio and Hugging Face cache directories, and checks managed backends like Ollama/oMLX through their local APIs. Reads model metadata (quantization, context size, vision, thinking mode) directly from GGUF files. No presets, no manual configuration.
 
 2. **One command to run.** `offgrid-ai` → pick a model → confirm context/KV memory settings on first setup → it starts llama-server, syncs Pi config, and launches Pi.
 
@@ -60,8 +60,8 @@ curl -fsSL https://raw.githubusercontent.com/eeshansrivastava89/offgrid-ai/main/
 | Backend | Type | Auto-detected |
 |---|---|---|
 | **LM Studio** | Visual model browser + CLI (`lms`) | ✓ models in `~/.lmstudio/models/` |
-| **llama.cpp** | Local server | ✓ GGUF models in `~/.lmstudio/models/` |
-| **llama.cpp MTP** | Local server (speculative decoding) | ✓ MTP detected from model metadata |
+| **llama.cpp** | Managed local runtime | ✓ GGUF models in `~/.lmstudio/models/` and Hugging Face cache |
+| **llama.cpp MTP** | Managed local runtime (speculative decoding) | ✓ MTP detected from model metadata |
 | **Ollama** | Managed server | ✓ via `localhost:11434` |
 | **oMLX** | Managed server | ✓ via `127.0.0.1:8000` |
 
@@ -69,15 +69,15 @@ curl -fsSL https://raw.githubusercontent.com/eeshansrivastava89/offgrid-ai/main/
 
 When you run `offgrid-ai` for the first time on a fresh machine:
 
-1. **Homebrew** — Required. Offered to install if missing.
-2. **llama-server** — Required for GGUF models. Offered to install via Homebrew.
+1. **llama.cpp runtime** — Required for GGUF models. Offered as an offgrid-ai managed runtime from official `llama.cpp` release binaries.
+2. **Pi** — Required to chat from the Pi coding agent. Offered to install via npm if missing.
 3. **Model backend** — At least one is needed (LM Studio recommended):
    - **LM Studio** — visual model browser + `lms` CLI, download models with `lms get qwen/qwen3.5-9b`
    - **Ollama** — models download on demand with `ollama pull`
    - **oMLX** — Apple Silicon optimized
 4. **Models** — If no models found, tells you where to get them.
 
-Subsequent runs skip everything that's already installed. When a GGUF model is set up for the first time, offgrid-ai asks only for the memory-impacting choices: context window and KV cache precision. Sampling defaults are shown but not forced into a tuning wizard.
+Homebrew is optional and only prompted when you choose a Homebrew-based backend install. Subsequent runs skip everything that's already installed. When a GGUF model is set up for the first time, offgrid-ai asks only for the memory-impacting choices: context window and KV cache precision. Sampling defaults are shown but not forced into a tuning wizard.
 
 ## Data directory
 
@@ -91,6 +91,7 @@ Subsequent runs skip everything that's already installed. When a GGUF model is s
       notes.md         # scratch notes
   logs/
   run/                 # PID state files
+  runtime/             # managed llama.cpp binaries
 ```
 
 ## Benchmark (coming soon)

package/install.sh

@@ -205,7 +205,7 @@ printf "${BOLD}${GREEN}  offgrid-ai ${INSTALLED_VERSION:+v${INSTALLED_VERSION} }
 printf "${BOLD}${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}\n"
 echo ""
 echo "  First run will walk you through setting up everything you need"
-echo "  (llama-server, model backends, Pi)."
+echo "  (managed llama.cpp runtime for GGUF models, model backends, Pi)."
 echo ""
 if command -v offgrid-ai &>/dev/null; then
   echo "  Run: offgrid-ai"

package/package.json

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

package/src/autodetect.mjs

@@ -1,6 +1,7 @@
 import { basename } from "node:path";
 import { existsSync } from "node:fs";
 import { readGgufMetadata } from "./gguf.mjs";
+import { defaultFlagsForBackend } from "./backends.mjs";
 
 // ── Detect model capabilities from GGUF metadata ──────────────────────────
 
@@ -51,8 +52,7 @@ export function computeFlags(capabilities, modelPath, mmprojPath, draftModelPath
   const isLowMem = quant && /[Qq]4[_0]/i.test(quant);
 
   const flags = {
-    host: "127.0.0.1",
-    port: mtp ? 8081 : 8080,
+    ...defaultFlagsForBackend(mtp ? "llama-cpp-mtp" : "llama-cpp"),
     ctxSize: capabilities.ctxSize,
     flashAttention: "on",
     cacheTypeK: isLowMem ? "f16" : "bf16",

package/src/backends.mjs

@@ -3,16 +3,30 @@ import { scanGgufModels } from "./scan.mjs";
 
 // ── Backend definitions ────────────────────────────────────────────────────
 
+export const LOCAL_HOST = "127.0.0.1";
+export const LLAMA_CPP_PORT = 8080;
+export const LLAMA_CPP_MTP_PORT = 8081;
+export const OLLAMA_PORT = 11434;
+export const OMLX_PORT = 8000;
+
+export function baseUrlFor({ host = LOCAL_HOST, port, path = "/v1" }) {
+  return `http://${host}:${port}${path}`;
+}
+
+export function baseUrlForFlags(flags) {
+  return baseUrlFor({ host: flags.host, port: flags.port });
+}
+
 export const BACKENDS = {
   "llama-cpp": {
     id: "llama-cpp",
     label: "llama.cpp",
     type: "local-server",
     providerId: "llama-cpp",
-    defaultPort: 8080,
-    defaultBaseUrl: "http://127.0.0.1:8080/v1",
+    defaultHost: LOCAL_HOST,
+    defaultPort: LLAMA_CPP_PORT,
+    defaultBaseUrl: baseUrlFor({ port: LLAMA_CPP_PORT }),
     needsCommandFile: true,
-    needsModelFile: true,
     scanModels: () => scanGgufModels(),
   },
   "llama-cpp-mtp": {
@@ -20,11 +34,10 @@ export const BACKENDS = {
     label: "llama.cpp MTP",
     type: "local-server",
     providerId: "llama-cpp-mtp",
-    defaultPort: 8081,
-    defaultBaseUrl: "http://127.0.0.1:8081/v1",
+    defaultHost: LOCAL_HOST,
+    defaultPort: LLAMA_CPP_MTP_PORT,
+    defaultBaseUrl: baseUrlFor({ port: LLAMA_CPP_MTP_PORT }),
     needsCommandFile: true,
-    needsModelFile: true,
-    extraArgs: ["--spec-type", "draft-mtp", "--spec-draft-n-max", "2"],
     scanModels: () => scanGgufModels(),
   },
   "ollama": {
@@ -32,10 +45,11 @@ export const BACKENDS = {
     label: "Ollama",
     type: "managed-server",
     providerId: "ollama",
-    defaultPort: 11434,
-    defaultBaseUrl: "http://localhost:11434/v1",
+    defaultHost: "localhost",
+    defaultPort: OLLAMA_PORT,
+    defaultBaseUrl: baseUrlFor({ host: "localhost", port: OLLAMA_PORT }),
+    apiBaseUrl: baseUrlFor({ host: "localhost", port: OLLAMA_PORT, path: "" }),
     needsCommandFile: false,
-    needsModelFile: false,
     scanModels: () => scanOllamaModels(),
   },
   "omlx": {
@@ -43,10 +57,11 @@ export const BACKENDS = {
     label: "oMLX",
     type: "managed-server",
     providerId: "omlx",
-    defaultPort: 8000,
-    defaultBaseUrl: "http://127.0.0.1:8000/v1",
+    defaultHost: LOCAL_HOST,
+    defaultPort: OMLX_PORT,
+    defaultBaseUrl: baseUrlFor({ port: OMLX_PORT }),
+    apiBaseUrl: baseUrlFor({ port: OMLX_PORT, path: "" }),
     needsCommandFile: false,
-    needsModelFile: false,
     scanModels: () => scanOmlxModels(),
   },
 };
@@ -64,11 +79,16 @@ export async function backendBinaryFor(backendId) {
   return discovered; // null means "not found — trigger onboarding"
 }
 
+export function defaultFlagsForBackend(backendId) {
+  const backend = backendFor(backendId);
+  return { host: backend.defaultHost ?? LOCAL_HOST, port: backend.defaultPort };
+}
+
 // ── Ollama model discovery ──────────────────────────────────────────────
 
 async function scanOllamaModels() {
   try {
-    const response = await fetch("http://localhost:11434/api/tags", { signal: AbortSignal.timeout(3000) });
+    const response = await fetch(`${BACKENDS.ollama.apiBaseUrl}/api/tags`, { signal: AbortSignal.timeout(3000) });
     if (!response.ok) return [];
     const body = await response.json();
     if (!Array.isArray(body?.models)) return [];
@@ -93,7 +113,7 @@ async function scanOllamaModels() {
 
 async function scanOmlxModels() {
   try {
-    const response = await fetch("http://127.0.0.1:8000/v1/models", { signal: AbortSignal.timeout(3000) });
+    const response = await fetch(`${BACKENDS.omlx.defaultBaseUrl}/models`, { signal: AbortSignal.timeout(3000) });
     if (!response.ok) return [];
     const body = await response.json();
     if (!Array.isArray(body?.data)) return [];

package/src/cli.mjs

@@ -2,10 +2,10 @@ import { totalmem } from "node:os";
 import { existsSync, statSync, rmSync } from "node:fs";
 import { ensureDirs, findLlamaServer, hasHomebrew, DATA_DIR } from "./config.mjs";
 import { scanGgufModels } from "./scan.mjs";
-import { createProfileFromModel, normalizeProfile } from "./profiles.mjs";
-import { readProfile, saveProfile, deleteProfile, loadProfiles } from "./profiles.mjs";
+import { createProfileFromModel, normalizeProfile, sanitizeProfileId } from "./profiles.mjs";
+import { readProfile, saveProfile, deleteProfile, loadProfiles, readCommandArgv } from "./profiles.mjs";
 import { backendFor, BACKENDS } from "./backends.mjs";
-import { startServer, stopProfile, waitForReady, serverReady, isProfileRunning, profileRuntimeStatus } from "./process.mjs";
+import { startServer, stopProfile, waitForReady, serverReady, serverMatchesProfile, isProfileRunning, profileRuntimeStatus } from "./process.mjs";
 import { syncPiConfig, removeFromPiConfig, hasPiModel, launchPi, hasPi } from "./harness-pi.mjs";
 import { tailFriendly } from "./logs.mjs";
 import { estimateMemory } from "./estimate.mjs";
@@ -21,7 +21,7 @@ import { offerManagedLlamaRuntimeUpdate } from "./runtime.mjs";
 
 async function offerUpdate(argv) {
   const invocation = detectInvocation();
-  const update = await checkForUpdate({ force: invocation === "npx" });
+  const update = await checkForUpdate({ force: true });
   if (!update) return false;
 
   const plan = updateCommand(invocation, argv);
@@ -83,14 +83,12 @@ export async function mainFlow() {
   const profiles = await loadProfiles();
   const hasAnyBackend = llamaBinary || managedModels.some((m) => m.models.length > 0);
   const hasAnyModels = ggufModels.length > 0 || managedModels.some((m) => m.models.length > 0);
-  const totalManaged = managedModels.reduce((sum, m) => sum + m.models.length, 0);
 
   // 2. Check mandatory deps — if anything essential is missing, re-offer onboarding
   const piInstalled = await hasPi();
-  const brewInstalled = await hasHomebrew();
+  const needsLlama = ggufModels.length > 0 || profiles.some((profile) => backendFor(profile.backend).type === "local-server");
   const missingDeps = [];
-  if (!brewInstalled) missingDeps.push("Homebrew");
-  if (!llamaBinary) missingDeps.push("llama-server");
+  if (needsLlama && !llamaBinary) missingDeps.push("llama-server");
   if (!piInstalled) missingDeps.push("Pi");
   if (missingDeps.length > 0) {
     if (!process.stdin.isTTY) {
@@ -109,18 +107,6 @@ export async function mainFlow() {
     return await onboardFlow();
   }
 
-  // 3. Has models but no llama-server (managed backends only)
-  if (!llamaBinary && ggufModels.length > 0) {
-    // They have GGUF files but can't run them — tell them about llama-server
-    console.log(pc.yellow(`${ggufModels.length} GGUF model${ggufModels.length === 1 ? "" : "s"} found, but llama-server is not installed.`));
-    console.log(pc.dim("Install it with: brew install llama.cpp"));
-    console.log(pc.dim("Or use Ollama/oMLX for managed model backends."));
-    if (totalManaged === 0 && profiles.length === 0) {
-      return; // Nothing to do without llama-server
-    }
-    // Fall through — they can still use managed backends
-  }
-
   // 4. No models found at all (but backends may exist)
   if (!hasAnyModels && profiles.length === 0) {
     if (!process.stdin.isTTY) {
@@ -213,10 +199,10 @@ async function modelCommandCenter(catalog) {
 
 async function runCommand(argv) {
   await ensureDirs();
-  const { positional } = parseOptions(argv);
+  const { positional, options } = parseOptions(argv);
   if (!positional[0]) return await mainFlow();
   const profile = await readProfile(positional[0]);
-  return await runProfile(profile);
+  return await runProfile(profile, options);
 }
 
 async function loadModelCatalog() {
@@ -424,7 +410,8 @@ async function printProfileDetails(profile) {
   ]), { columns: 110 }));
 
   if (!isManaged && profile.commandArgv) {
-    console.log("\n" + renderSection("llama-server command", pc.dim(buildPrettyCommand(profile)), { columns: 120 }));
+    const commandArgv = await readCommandArgv(profile);
+    console.log("\n" + renderSection("llama-server command", pc.dim(buildPrettyCommand({ ...profile, commandArgv })), { columns: 120 }));
   }
 }
 
@@ -495,7 +482,7 @@ function removeCommandOption(argv, flag) {
 
 function createManagedProfile(model, backendId) {
   return normalizeProfile({
-    id: model.id.replace(/[^a-z0-9._-]+/gi, "-").toLowerCase(),
+    id: `${backendId}-${sanitizeProfileId(model.id)}`,
     label: model.label,
     backend: backendId,
     modelAlias: model.aliasSuggestion,
@@ -529,6 +516,10 @@ async function runProfile(profile, options = {}) {
   } else {
     const ready = await serverReady(profile.baseUrl);
     if (ready) {
+      const match = await serverMatchesProfile(profile);
+      if (!match.matches) {
+        throw new Error(`A different server is already responding at ${profile.baseUrl}. ${match.reason}. Stop it with offgrid-ai stop --all, or choose a different port.`);
+      }
       console.log(pc.green(`[ready] Reusing server at ${profile.baseUrl}`));
     } else {
       console.log(pc.dim(`Starting ${backend.label} for ${profile.label}...`));
@@ -551,7 +542,7 @@ async function runProfile(profile, 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);
+          await saveProfile(textOnly, { writeCommand: true });
           return await runProfile(textOnly, { ...options, textOnlyRetry: true });
         }
         throw err;
@@ -782,19 +773,32 @@ async function onboardFlow() {
     console.log(pc.bold("Welcome to offgrid-ai!"));
     console.log(pc.dim("Let's make sure you have everything you need to run local models.\n"));
 
-    // 1. Homebrew
-    const hasBrew = await hasHomebrew();
-    if (!hasBrew) {
-      const install = await prompt.yesNo("Homebrew is required. Install it now?", true);
+    // 1. llama.cpp runtime for local GGUF models
+    let llamaBinary = await findLlamaServer();
+    if (!llamaBinary) {
+      console.log(renderSection("llama.cpp runtime", renderRows([
+        ["Status", pc.yellow("not installed")],
+        ["Used for", "local GGUF models"],
+        ["Install", "managed by offgrid-ai under ~/.offgrid-ai/runtime"],
+      ]), { 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.green(`✓ llama-server: ${llamaBinary}`));
+
+    const ensureHomebrewFor = async (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.red("offgrid-ai needs Homebrew to install dependencies."));
-        console.log(pc.dim("Install it from https://brew.sh, then run offgrid-ai again."));
-        return;
+        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");
-        // Add brew to PATH for this session
         const brewPaths = ["/opt/homebrew/bin", "/usr/local/bin"];
         for (const p of brewPaths) {
           if (existsSync(p)) {
@@ -803,43 +807,19 @@ async function onboardFlow() {
           }
         }
       } catch {
-        console.log(pc.red(`✗ Homebrew installation failed.`));
+        console.log(pc.red("✗ Homebrew installation failed."));
         console.log(pc.dim("Install it manually from https://brew.sh, then run offgrid-ai again."));
-        return;
+        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;
+        return false;
       }
-    }
-    console.log(pc.green("✓ Homebrew found"));
-
-    // 2. llama-server
-    let llamaBinary = await findLlamaServer();
-    if (!llamaBinary) {
-      const install = await prompt.yesNo("llama-server is required to run local models. Install via Homebrew?", true);
-      if (!install) {
-        console.log(pc.red("offgrid-ai needs llama-server to run local models."));
-        console.log(pc.dim("Install it manually: brew install llama.cpp"));
-        return;
-      }
-      console.log(pc.cyan("Installing llama.cpp..."));
-      try {
-        await run("brew", ["install", "llama.cpp"], "llama.cpp");
-        llamaBinary = await findLlamaServer();
-      } catch {
-        console.log(pc.red("✗ Failed to install llama.cpp."));
-        console.log(pc.dim("Install it manually: brew install llama.cpp"));
-        return;
-      }
-      if (!llamaBinary) {
-        console.log(pc.yellow("llama.cpp installed but llama-server not found. You may need to restart your terminal."));
-        return;
-      }
-    }
-    console.log(pc.green(`✓ llama-server: ${llamaBinary}`));
+      console.log(pc.green("✓ Homebrew found"));
+      return true;
+    };
 
-    // 3. Pi coding agent
+    // 2. Pi coding agent
     const piInstalled = await hasPi();
     if (!piInstalled) {
       const install = await prompt.yesNo("Pi coding agent is required to chat with models. Install via npm?", true);
@@ -873,6 +853,7 @@ async function onboardFlow() {
       // They already have models — show what was found
       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."));
       }
       for (const { backendId, models } of managedModels) {
         if (models.length > 0) {
@@ -895,6 +876,7 @@ async function onboardFlow() {
       const model = recommendedModel();
 
       if (backendChoice === "lmstudio") {
+        if (!(await ensureHomebrewFor("LM Studio"))) return;
         console.log(pc.cyan("Installing LM Studio via Homebrew..."));
         try {
           await run("brew", ["install", "--cask", "lm-studio"], "LM Studio");
@@ -907,6 +889,7 @@ async function onboardFlow() {
           console.log(pc.dim("Download it manually from https://lmstudio.ai"));
         }
       } else if (backendChoice === "ollama") {
+        if (!(await ensureHomebrewFor("Ollama"))) return;
         console.log(pc.cyan("Installing Ollama via Homebrew..."));
         try {
           await run("brew", ["install", "ollama"], "Ollama");
@@ -920,6 +903,7 @@ async function onboardFlow() {
           console.log(pc.dim("Install it manually from https://ollama.com"));
         }
       } else if (backendChoice === "omlx") {
+        if (!(await ensureHomebrewFor("oMLX"))) return;
         console.log(pc.cyan("Installing oMLX via Homebrew..."));
         try {
           await run("brew", ["tap", "jundot/omlx", "https://github.com/jundot/omlx"], "oMLX tap");
@@ -934,6 +918,7 @@ async function onboardFlow() {
           console.log(pc.dim("Install manually: brew tap jundot/omlx && brew install omlx"));
         }
       } else if (backendChoice === "all") {
+        if (!(await ensureHomebrewFor("model backends"))) return;
         let installed = [];
         // LM Studio
         console.log(pc.cyan("Installing LM Studio via Homebrew..."));
@@ -1132,7 +1117,7 @@ async function printVersion() {
   const version = currentPackageVersion();
   console.log(`offgrid-ai v${version}`);
   const invocation = detectInvocation();
-  const update = await checkForUpdate({ force: invocation === "npx" });
+  const update = await checkForUpdate({ force: true });
   if (update) {
     const plan = updateCommand(invocation, ["version"]);
     console.log(pc.yellow(`Update available: v${update.latest}. Run: ${plan.display}`));

package/src/config.mjs

@@ -76,17 +76,22 @@ export async function findLlamaServer() {
     return process.env.LLAMA_SERVER_BINARY;
   }
 
-  // 2. offgrid-ai managed runtime
+  // 2. User config override
+  const config = await loadConfig();
+  const configured = config.binaryOverrides?.llamaServer ?? config.binaryOverrides?.["llama-server"];
+  if (configured && existsSync(configured)) return configured;
+
+  // 3. offgrid-ai managed runtime
   if (existsSync(MANAGED_LLAMA_SERVER)) return MANAGED_LLAMA_SERVER;
 
-  // 3. which/where
+  // 4. PATH
   try {
     const { stdout } = await execFileAsync("which", ["llama-server"]);
     const path = stdout.trim();
     if (path && existsSync(path)) return path;
   } catch { /* not on PATH */ }
 
-  // 4. Homebrew
+  // 5. Homebrew fallback
   try {
     const { stdout } = await execFileAsync("brew", ["--prefix", "llama.cpp"]);
     const prefix = stdout.trim();

package/src/gguf.mjs

@@ -3,21 +3,30 @@ import { openSync, readSync, closeSync, statSync } from "node:fs";
 export function readGgufMetadata(path) {
   const buffer = readFilePrefix(path, 64 * 1024 * 1024);
   let offset = 0;
-  if (buffer.toString("utf8", 0, 4) !== "GGUF") return {};
+  const meta = {};
+  if (buffer.length < 24 || buffer.toString("utf8", 0, 4) !== "GGUF") return meta;
   offset += 4;
   offset += 4; // version
   offset += 8; // tensor count
+  if (offset + 8 > buffer.length) return meta;
   const kvCount = Number(buffer.readBigUInt64LE(offset));
   offset += 8;
-  const meta = {};
   for (let i = 0; i < kvCount; i++) {
+    if (offset + 8 > buffer.length) return meta;
     const keyLen = Number(buffer.readBigUInt64LE(offset));
     offset += 8;
+    if (offset + keyLen + 4 > buffer.length) return meta;
     const key = buffer.toString("utf8", offset, offset + keyLen);
     offset += keyLen;
     const type = buffer.readUInt32LE(offset);
     offset += 4;
-    const read = readValue(buffer, offset, type);
+    let read;
+    try {
+      read = readValue(buffer, offset, type);
+    } catch {
+      return meta;
+    }
+    if (read.offset > buffer.length) return meta;
     offset = read.offset;
     meta[key] = read.value;
   }

package/src/process.mjs

@@ -1,10 +1,10 @@
 import { execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
-import { openSync } from "node:fs";
+import { closeSync, openSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { LOG_DIR } from "./config.mjs";
-import { writeState, readState } from "./profiles.mjs";
+import { writeState, readState, readCommandArgv } from "./profiles.mjs";
 import { backendFor, backendBinaryFor } from "./backends.mjs";
 
 const execFileAsync = promisify(execFile);
@@ -22,22 +22,27 @@ export async function startServer(profile) {
 async function startLocalServer(profile) {
   const binary = await backendBinaryFor(profile.backend);
   if (!binary) {
-    throw new Error("llama-server not found. Install it via Homebrew: brew install llama.cpp");
+    throw new Error("llama-server not found. Install the managed llama.cpp runtime by running offgrid-ai interactively.");
   }
 
   const timestamp = timestampForFile();
   const rawLogPath = join(LOG_DIR, `${profile.id}-${timestamp}.raw.log`);
   const friendlyLogPath = join(LOG_DIR, `${profile.id}-${timestamp}.friendly.log`);
-  const commandJson = profile.commandArgv ?? [];
+  const commandArgv = await readCommandArgv(profile);
 
-  await writeFile(rawLogPath, `[offgrid-ai] ${new Date().toISOString()}\n[binary] ${binary}\n[argv]\n${commandJson.join(" ")}\n`, "utf8");
+  await writeFile(rawLogPath, `[offgrid-ai] ${new Date().toISOString()}\n[binary] ${binary}\n[argv]\n${commandArgv.join(" ")}\n`, "utf8");
   await writeFile(friendlyLogPath, `[launch] starting llama-server for ${profile.label}\n`, "utf8");
 
   // Build argv: binary + command.json args
-  const argv = [...commandJson];
+  const argv = [...commandArgv];
 
   const rawFd = openSync(rawLogPath, "a");
-  const child = spawn(binary, argv, { detached: true, stdio: ["ignore", rawFd, rawFd] });
+  let child;
+  try {
+    child = spawn(binary, argv, { detached: true, stdio: ["ignore", rawFd, rawFd] });
+  } finally {
+    closeSync(rawFd);
+  }
   child.unref();
 
   const state = {
@@ -137,6 +142,27 @@ export async function serverReady(baseUrl) {
   }
 }
 
+export async function serverMatchesProfile(profile) {
+  const state = await readState(profile.id);
+  if (state?.pid && pidAlive(state.pid) && state.baseUrl === profile.baseUrl) {
+    return { matches: true, reason: "tracked offgrid-ai server" };
+  }
+
+  const ids = await serverModelIds(profile.baseUrl);
+  const expected = expectedModelIds(profile);
+  const normalizedIds = new Set(ids.map((id) => id.toLowerCase()));
+  if (ids.length > 0 && expected.some((id) => normalizedIds.has(id.toLowerCase()))) {
+    return { matches: true, reason: `server reports ${ids.join(", ")}` };
+  }
+
+  return {
+    matches: false,
+    reason: ids.length > 0
+      ? `server reports ${ids.join(", ")}; expected ${expected.join(" or ")}`
+      : "server is untracked and did not report a recognizable model id",
+  };
+}
+
 export async function waitForReady(profile, pid, rawLogPath) {
   const backend = backendFor(profile.backend);
   if (backend.type === "managed-server") return;
@@ -153,6 +179,32 @@ export async function waitForReady(profile, pid, rawLogPath) {
 
 // ── Internals ──────────────────────────────────────────────────────────────
 
+async function serverModelIds(baseUrl) {
+  try {
+    const response = await fetch(`${baseUrl.replace(/\/$/, "")}/models`, { signal: AbortSignal.timeout(1000) });
+    if (!response.ok) return [];
+    const body = await response.json();
+    return (Array.isArray(body?.data) ? body.data : [])
+      .map((model) => String(model?.id ?? "").trim())
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function expectedModelIds(profile) {
+  const fileName = profile.modelPath ? basename(profile.modelPath) : null;
+  return [
+    profile.modelAlias,
+    profile.label,
+    profile.ollamaModel,
+    profile.omlxModel,
+    profile.modelPath,
+    fileName,
+    fileName ? fileName.replace(/\.gguf$/iu, "") : null,
+  ].filter(Boolean).map(String);
+}
+
 function pidAlive(pid) {
   try { process.kill(pid, 0); return true; }
   catch { return false; }

package/src/profile-setup.mjs

@@ -2,6 +2,7 @@ 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 { pc, formatBytes, renderRows, renderSection } from "./ui.mjs";
 
 const execFileAsync = promisify(execFile);
@@ -44,7 +45,7 @@ export async function configureLocalProfile(prompt, profile) {
   if (caps.mtp) {
     console.log(renderSection("MTP detected", renderRows([
       ["Backend", "llama.cpp MTP"],
-      ["Port", "8081"],
+      ["Port", String(LLAMA_CPP_MTP_PORT)],
       ["Flags", "--spec-type draft-mtp --spec-draft-n-max 2"],
     ])));
     const useMtp = await prompt.yesNo("Use MTP speculative decoding flags?", true);
@@ -111,14 +112,14 @@ export function applyRuntimeFlagOverrides(profile, overrides) {
 }
 
 function applyMtpDefaults(profile) {
-  const flags = { ...profile.flags, port: 8081 };
+  const flags = { ...profile.flags, port: LLAMA_CPP_MTP_PORT };
   return applyProfileFlags({ ...profile, backend: "llama-cpp-mtp", providerId: "llama-cpp-mtp" }, flags, {
     values: { "--spec-type": "draft-mtp", "--spec-draft-n-max": 2 },
   });
 }
 
 function removeMtpDefaults(profile) {
-  const flags = { ...profile.flags, port: 8080 };
+  const flags = { ...profile.flags, port: LLAMA_CPP_PORT };
   return applyProfileFlags({ ...profile, backend: "llama-cpp", providerId: "llama-cpp" }, flags, {
     remove: ["--spec-type", "--spec-draft-n-max"],
   });
@@ -156,7 +157,7 @@ function applyProfileFlags(profile, flags, edits = {}) {
   const next = {
     ...profile,
     flags,
-    baseUrl: `http://${flags.host}:${flags.port}/v1`,
+    baseUrl: baseUrlForFlags(flags),
     harnesses: {
       ...(profile.harnesses ?? {}),
       pi: { ...(profile.harnesses?.pi ?? {}), enabled: true, model: `${profile.providerId ?? profile.backend}/${profile.modelAlias ?? profile.id}` },

package/src/profiles.mjs

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import { mkdir, readdir, rm, unlink, writeFile, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { PROFILE_DIR, RUN_DIR, LOG_DIR } from "./config.mjs";
-import { backendFor } from "./backends.mjs";
+import { backendFor, baseUrlForFlags, defaultFlagsForBackend } from "./backends.mjs";
 import { computeFlags } from "./autodetect.mjs";
 import { readJson, writeJson } from "./json.mjs";
 
@@ -28,10 +28,6 @@ export function statePath(id) {
   return join(RUN_DIR, `${sanitizeProfileId(id)}.state.json`);
 }
 
-export function profileExists(id) {
-  return existsSync(profileJsonPath(id));
-}
-
 export function sanitizeProfileId(value) {
   return String(value).trim().toLowerCase().replace(/[^a-z0-9._-]+/gu, "-").replace(/^-|-$/gu, "") || "profile";
 }
@@ -57,7 +53,7 @@ export async function readProfile(id) {
   return JSON.parse(await readFile(path, "utf8"));
 }
 
-export async function saveProfile(profile) {
+export async function saveProfile(profile, options = {}) {
   const id = sanitizeProfileId(profile.id);
   const dir = profileDir(id);
   await mkdir(dir, { recursive: true });
@@ -75,8 +71,8 @@ export async function saveProfile(profile) {
   const backend = backendFor(saved.backend);
   if (backend.needsCommandFile) {
     const cmdPath = commandJsonPath(id);
-    if (!existsSync(cmdPath)) {
-      await writeJson(cmdPath, { argv: saved.commandArgv ?? saved.flags ?? [] });
+    if (options.writeCommand || !existsSync(cmdPath)) {
+      await writeJson(cmdPath, { argv: saved.commandArgv ?? [] });
     }
   }
 
@@ -116,12 +112,11 @@ export async function deleteProfile(id, options = {}) {
 export function normalizeProfile(profile) {
   const backend = backendFor(profile.backend);
   const flags = {
-    host: "127.0.0.1",
-    port: backend.defaultPort,
+    ...defaultFlagsForBackend(backend.id),
     ...profile.flags,
   };
   if (!profile.baseUrl) {
-    profile.baseUrl = `http://${flags.host}:${flags.port}/v1`;
+    profile.baseUrl = baseUrlForFlags(flags);
   }
 
   return {
@@ -175,6 +170,11 @@ function summarizeCapabilities(caps) {
 
 // ── State files (for running servers) ──────────────────────────────────────
 
+export async function readCommandArgv(profile) {
+  const command = await readJson(commandJsonPath(profile.id), null);
+  return Array.isArray(command?.argv) ? command.argv.map(String) : (profile.commandArgv ?? []).map(String);
+}
+
 export async function readState(id) {
   return readJson(statePath(id), null);
 }

package/src/runtime.mjs

@@ -29,7 +29,7 @@ export async function offerManagedLlamaRuntimeUpdate(prompt, { fetchImpl = globa
   const shouldInstall = await prompt.yesNo(installed ? "Update llama.cpp runtime?" : "Install llama.cpp runtime?", true);
   if (!shouldInstall) return false;
 
-  await installLlamaRelease(latest);
+  await installLlamaRelease(latest, { fetchImpl });
   return true;
 }
 
@@ -55,7 +55,7 @@ export async function installedRuntime() {
   }
 }
 
-export async function installLlamaRelease(release) {
+export async function installLlamaRelease(release, { fetchImpl = globalThis.fetch } = {}) {
   const tmp = await mkdtemp(join(tmpdir(), "offgrid-llama-"));
   const archive = join(tmp, release.asset.name);
   const releaseDir = join(RUNTIME_DIR, "llama.cpp", "releases", release.tag);
@@ -63,7 +63,7 @@ export async function installLlamaRelease(release) {
 
   try {
     console.log(pc.dim(`Downloading ${release.asset.name}...`));
-    const response = await fetch(release.asset.url);
+    const response = await fetchImpl(release.asset.url);
     if (!response.ok) throw new Error(`Download failed: HTTP ${response.status}`);
     const bytes = Buffer.from(await response.arrayBuffer());
     verifyDigest(bytes, release.asset.digest);

package/src/ui.mjs

@@ -3,8 +3,6 @@ import pc from "picocolors";
 import { stripVTControlCharacters } from "node:util";
 
 export { pc };
-export { pc as colors };
-
 export function formatBytes(bytes) {
   if (!Number.isFinite(bytes)) return "unknown";
   const units = ["B", "KB", "MB", "GB", "TB"];