@@ -187,8 +187,11 @@ rather than driver-aware or offline-repacked.
 
 The bundled `vllm` manifest covers Linux (NVIDIA GPU) and Apple Silicon macOS
 (vLLM-Metal). It installs a pinned vLLM release into a private virtualenv
-through a checksum-pinned `uv` bootstrap, or adopts a `vllm` already installed
-at a detected path. The engine's PAIR gateway listens on `8001`, with the
+at the space-free managed path `~/.nvpair/engine-bin/vllm` through a
+checksum-pinned `uv` bootstrap, or adopts a `vllm` already installed at a
+detected path. The space-free physical path lets FlashInfer and DeepGEMM compile
+load-time GPU kernels; reset and uninstall include the path while preserving the
+model cache. The engine's PAIR gateway listens on `8001`, with the
 `vllm serve` process on loopback `18001`, behind the proxy facade on `8000`. vLLM serves one model per process and has no
 load or unload API, so the engine manager puts a gateway on its port (`front`):
 Start and the restore after a restart bring it up idle with nothing loaded, the
@@ -213,7 +216,9 @@ restart, so the desktop marks the engine as switching: its card shows starting
 rather than stopped, and its model list is kept, until the load request finishes
 (success, or failure with the previous model restored). Weights live in the shared
 Hugging Face cache (`~/.cache/huggingface`), which uninstall and app-data reset
-never remove.
+never remove. On macOS the manager rejects NVIDIA ModelOpt FP8 weight
+checkpoints before launch because vLLM-Metal cannot load that tensor layout;
+the NVIDIA Linux path remains unchanged.
 
 Current limits are explicit: the manual-node worker does not probe vLLM, the
 Inference Demo does not use it, and the icon is a placeholder lettermark rather
 
@@ -97,9 +97,16 @@ When you install an engine, consider the following:
   several GiB because it includes PyTorch and the CUDA libraries, and PAIR first
   checks for an NVIDIA driver that supports CUDA 13 or newer and about 25 GB of
   free disk, enough for the engine and its default model. On macOS it installs
-  checksum-pinned vLLM and vLLM-Metal wheels and needs about 20 GB of free disk. Either way PAIR stops with a clear message if a
-  requirement is missing.
-  Nothing is compiled. vLLM serves a single model per process. Until you choose
+  checksum-pinned vLLM and vLLM-Metal wheels and needs about 20 GB of free disk.
+  Either way PAIR stops with a clear message if a requirement is missing.
+  NVIDIA ModelOpt FP8 weight checkpoints run on the NVIDIA path but are not
+  loadable by vLLM-Metal; on macOS PAIR rejects them before launch and asks for
+  a BF16, FP16, or MLX-compatible quantized checkpoint.
+  PAIR's private environment lives at
+  `~/.nvpair/engine-bin/vllm`, outside the app-data path whose spaces break the
+  load-time GPU builds used by some models. Reset and uninstall still remove it.
+  Installation uses prebuilt wheels; loading a model may compile FlashInfer or
+  DeepGEMM GPU kernels. vLLM serves a single model per process. Until you choose
   one it serves Qwen3.5-4B, downloaded on the first start (about 9.3 GB, and a GPU
   with at least 16 GB of memory); on a smaller GPU, add and load a smaller model
   first. Its model list
 
@@ -97,13 +97,34 @@ answers in plain text instead of failing with HTTP 400. The response carries
 `X-PAIR-Tool-Calls: removed: …`. A request with `tool_choice: "required"` or a
 named function is forwarded unchanged and gets vLLM's own error. A parser named
 in the launch arguments is always used as given.
-The environment sets `VLLM_USE_FLASHINFER_SAMPLER=0`. vLLM's FlashInfer sampler
-compiles GPU kernels on first start, and that build cannot handle the spaces in
-PAIR's app-data folder (`Nvidia Corporation/Personal AI Router`), so the
-built-in sampler is used instead. As a side effect no CUDA toolkit or C++
-compiler is needed. The same limit means anything that forces a FlashInfer
-kernel build (for example choosing a FlashInfer attention backend) fails until
-the install can live on a path without spaces.
+PAIR installs its managed vLLM payload under `~/.nvpair/engine-bin/vllm`, rather
+than under the app-data folder whose `Nvidia Corporation/Personal AI Router`
+segments contain spaces. FlashInfer and DeepGEMM write unescaped source and
+include paths into load-time GPU builds, so the space-free physical location lets
+their attention and FP8/FP4 kernels compile normally. The engine's virtualenv is
+put first on `PATH` so those builds find its bundled `ninja`. Engine uninstall,
+Reset app data, and the platform uninstallers all remove this managed directory;
+downloaded Hugging Face models remain in `~/.cache/huggingface`.
+
+The environment still sets `VLLM_USE_FLASHINFER_SAMPLER=0`, so an ordinary model
+does not need a CUDA toolkit solely for the optional FlashInfer sampler. Other
+FlashInfer and DeepGEMM kernels are not disabled, and vLLM chooses their attention
+backend normally.
+
+Before choosing a context window and `--gpu-memory-utilization`, PAIR reads
+device memory from `nvidia-smi` when available and otherwise asks the installed
+vLLM platform. This covers CUDA/ROCm, Intel XPU, Apple Metal, CPU, and
+out-of-tree backends that expose vLLM's memory API. Shared-memory platforms keep
+3 GiB for runtime startup in addition to the normal 1 GiB free margin. If neither
+provider can measure free memory, PAIR does not invent a limit and leaves memory
+sizing to vLLM. On Apple Metal, a checkpoint whose weights are Metal-compatible
+but which declares an FP8 KV cache is launched with a dense KV cache matching its
+`bfloat16` or `float16` model dtype, because vLLM Metal stores paged KV data in
+the model dtype and rejects FP8 KV cache storage. An explicit launch option
+always wins. NVIDIA ModelOpt FP8 weight checkpoints are rejected before launch:
+vLLM Metal cannot load that tensor layout, so macOS needs a BF16, FP16, or
+MLX-compatible quantized checkpoint instead.
+
 Readiness polls `/health` for up to eight minutes while weights load.
 
 The model list is the Hugging Face cache (`~/.cache/huggingface/hub`), not what
 
@@ -12,6 +12,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"runtime"
 	"strconv"
 	"strings"
 	"time"
@@ -126,6 +127,10 @@ func applyAutoLaunch(engine string, rt Runtime, command launchCommand, modelsDir
 	}
 	hub := filepath.Join(expandPath(modelsDir), "hub")
 	extra, note := planHFContext(command.Args, hub, int64(rt.AutoLaunch.ContextTokens), command.Bin)
+	if kvCache, reason := planMetalKVCache(command.Args, hub, runtime.GOOS); len(kvCache) > 0 {
+		extra = append(extra, kvCache...)
+		note = strings.TrimPrefix(note+"; "+reason, "; ")
+	}
 	if tools, parser := planToolCalling(command.Args, hub, command.Bin); len(tools) > 0 {
 		extra = append(extra, tools...)
 		note = strings.TrimPrefix(note+"; tool calls parsed with "+parser, "; ")
@@ -138,6 +143,14 @@ func applyAutoLaunch(engine string, rt Runtime, command launchCommand, modelsDir
 	return command
 }
 
+func validateAutoLaunch(rt Runtime, command launchCommand, modelsDir string) error {
+	if rt.AutoLaunch == nil || rt.AutoLaunch.Kind != autoLaunchHFContext {
+		return nil
+	}
+	hub := filepath.Join(expandPath(modelsDir), "hub")
+	return validateMetalModel(command.Args, hub, runtime.GOOS)
+}
+
 // launchFlagValue returns the value of a flag in either "--flag value" or
 // "--flag=value" form, and whether the flag is present at all.
 func launchFlagValue(args []string, flag string) (string, bool) {
 
@@ -0,0 +1,111 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+type modelOptConfig struct {
+	Producer struct {
+		Name string `json:"name"`
+	} `json:"producer"`
+	Quantization struct {
+		QuantAlgo        string `json:"quant_algo"`
+		KVCacheQuantAlgo string `json:"kv_cache_quant_algo"`
+	} `json:"quantization"`
+}
+
+func planMetalKVCache(args []string, hubDir, goos string) (extra []string, note string) {
+	if goos != "darwin" {
+		return nil, ""
+	}
+	if _, set := launchFlagValue(args, "--kv-cache-dtype"); set {
+		return nil, ""
+	}
+	model, ok := launchFlagValue(args, "--model")
+	if !ok || model == "" {
+		return nil, ""
+	}
+	snapshot, cfg, _, cached := findHFSnapshot(hubDir, model)
+	if !cached || modelOptFP8Weights(snapshot) || !quantizedKVCache(snapshot) {
+		return nil, ""
+	}
+	dtype := metalDenseKVCacheDtype(cfg)
+	if dtype == "" {
+		return nil, ""
+	}
+	return []string{"--kv-cache-dtype", dtype}, "Metal requires the KV cache to use the model dtype " + dtype
+}
+
+func validateMetalModel(args []string, hubDir, goos string) error {
+	if goos != "darwin" {
+		return nil
+	}
+	model, ok := launchFlagValue(args, "--model")
+	if !ok || model == "" {
+		return nil
+	}
+	snapshot, _, _, cached := findHFSnapshot(hubDir, model)
+	if !cached || !modelOptFP8Weights(snapshot) {
+		return nil
+	}
+	return fmt.Errorf("model %q uses NVIDIA ModelOpt FP8 weights, which vLLM Metal cannot load on macOS; use a BF16, FP16, or MLX-compatible quantized checkpoint", model)
+}
+
+func metalDenseKVCacheDtype(cfg hfModelConfig) string {
+	text := cfg
+	if cfg.TextConfig != nil {
+		text = *cfg.TextConfig
+	}
+	for _, value := range []string{text.Dtype, text.TorchDtype, cfg.Dtype, cfg.TorchDtype} {
+		switch strings.TrimPrefix(strings.ToLower(value), "torch.") {
+		case "bfloat16", "bf16":
+			return "bfloat16"
+		case "float16", "fp16", "half":
+			return "float16"
+		}
+	}
+	return ""
+}
+
+func quantizedKVCache(snapshot string) bool {
+	if modelOpt, ok := readModelOptConfig(snapshot); ok && kvAlgorithmSet(modelOpt.Quantization.KVCacheQuantAlgo) {
+		return true
+	}
+	var config struct {
+		Quantization struct {
+			KVCacheQuantAlgo string          `json:"kv_cache_quant_algo"`
+			KVCacheScheme    json.RawMessage `json:"kv_cache_scheme"`
+		} `json:"quantization_config"`
+	}
+	if !readJSONFile(filepath.Join(snapshot, "config.json"), &config) {
+		return false
+	}
+	scheme := strings.TrimSpace(string(config.Quantization.KVCacheScheme))
+	return kvAlgorithmSet(config.Quantization.KVCacheQuantAlgo) || (scheme != "" && scheme != "null")
+}
+
+func modelOptFP8Weights(snapshot string) bool {
+	modelOpt, ok := readModelOptConfig(snapshot)
+	return ok && strings.EqualFold(modelOpt.Producer.Name, "modelopt") && strings.EqualFold(modelOpt.Quantization.QuantAlgo, "fp8")
+}
+
+func readModelOptConfig(snapshot string) (modelOptConfig, bool) {
+	var config modelOptConfig
+	return config, readJSONFile(filepath.Join(snapshot, "hf_quant_config.json"), &config)
+}
+
+func kvAlgorithmSet(algorithm string) bool {
+	return algorithm != "" && !strings.EqualFold(algorithm, "none")
+}
+
+func readJSONFile(path string, into any) bool {
+	raw, err := os.ReadFile(path)
+	return err == nil && json.Unmarshal(raw, into) == nil
+}
@@ -0,0 +1,124 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+const (
+	modelOptFP8KVOnly      = `{"producer":{"name":"modelopt"},"quantization":{"kv_cache_quant_algo":"FP8"}}`
+	modelOptFP8WeightsJSON = `{"producer":{"name":"modelopt"},"quantization":{"quant_algo":"FP8","kv_cache_quant_algo":"FP8"}}`
+)
+
+func cachedModelWithFile(t *testing.T, id, config, name, contents string) string {
+	t.Helper()
+	cache := cachedModel(t, id, config, 1_000_000)
+	snapshot, _, _, ok := findHFSnapshot(cache, id)
+	if !ok {
+		t.Fatal("cached model has no complete snapshot")
+	}
+	if err := os.WriteFile(filepath.Join(snapshot, name), []byte(contents), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return cache
+}
+
+func TestPlanMetalKVCache_UsesBFloat16ForModelOptFP8KVCache(t *testing.T) {
+	cache := cachedModelWithFile(t, "org/Llama-KV-FP8", llama8BFP8Config, "hf_quant_config.json", modelOptFP8KVOnly)
+
+	extra, note := planMetalKVCache([]string{"serve", "--model", "org/Llama-KV-FP8"}, cache, "darwin")
+
+	if got := flagOf(t, extra, "--kv-cache-dtype"); got != "bfloat16" {
+		t.Fatalf("kv-cache-dtype = %q, want bfloat16: %v", got, extra)
+	}
+	if !strings.Contains(note, "model dtype bfloat16") {
+		t.Fatalf("note = %q", note)
+	}
+}
+
+func TestPlanMetalKVCache_UsesFloat16ForCompressedKVCache(t *testing.T) {
+	config := `{"max_position_embeddings":40960,"num_hidden_layers":32,"num_attention_heads":32,"num_key_value_heads":8,"head_dim":128,"torch_dtype":"float16","quantization_config":{"quant_method":"compressed-tensors","kv_cache_scheme":{"type":"float","num_bits":8}}}`
+	cache := cachedModel(t, "org/compressed", config, 1_000_000)
+
+	extra, _ := planMetalKVCache([]string{"--model", "org/compressed"}, cache, "darwin")
+
+	if got := flagOf(t, extra, "--kv-cache-dtype"); got != "float16" {
+		t.Fatalf("kv-cache-dtype = %q, want float16: %v", got, extra)
+	}
+}
+
+func TestPlanMetalKVCache_PreservesAnExplicitUserChoice(t *testing.T) {
+	cache := cachedModelWithFile(t, "org/Llama-KV-FP8", llama8BFP8Config, "hf_quant_config.json", modelOptFP8KVOnly)
+	args := []string{"--model", "org/Llama-KV-FP8", "--kv-cache-dtype=auto"}
+
+	extra, _ := planMetalKVCache(args, cache, "darwin")
+
+	if len(extra) != 0 {
+		t.Fatalf("the user's KV cache choice must stand untouched: %v", extra)
+	}
+}
+
+func TestPlanMetalKVCache_AddsNothingWithoutAPlatformConflict(t *testing.T) {
+	quantized := cachedModelWithFile(t, "org/Llama-KV-FP8", llama8BFP8Config, "hf_quant_config.json", modelOptFP8KVOnly)
+	plain := cachedModel(t, "org/plain", llama8BFP8Config, 1_000_000)
+	unsupportedDtype := cachedModelWithFile(t, "org/fp32-kv", strings.Replace(llama8BFP8Config, "bfloat16", "float32", 1), "hf_quant_config.json", modelOptFP8KVOnly)
+
+	cases := []struct {
+		name  string
+		args  []string
+		cache string
+		goos  string
+	}{
+		{"non-Metal platform", []string{"--model", "org/Llama-KV-FP8"}, quantized, "linux"},
+		{"dense checkpoint", []string{"--model", "org/plain"}, plain, "darwin"},
+		{"dtype unsupported by Metal", []string{"--model", "org/fp32-kv"}, unsupportedDtype, "darwin"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			extra, _ := planMetalKVCache(tc.args, tc.cache, tc.goos)
+			if len(extra) != 0 {
+				t.Fatalf("got %v, want no automatic KV cache override", extra)
+			}
+		})
+	}
+}
+
+func TestPlanMetalKVCache_SkipsModelOptFP8Weights(t *testing.T) {
+	cache := cachedModelWithFile(t, "nvidia/Llama-FP8", llama8BFP8Config, "hf_quant_config.json", modelOptFP8WeightsJSON)
+
+	extra, _ := planMetalKVCache([]string{"--model", "nvidia/Llama-FP8"}, cache, "darwin")
+
+	if len(extra) != 0 {
+		t.Fatalf("an unsupported checkpoint must not receive a misleading KV-cache fallback: %v", extra)
+	}
+}
+
+func TestValidateMetalModel_RejectsModelOptFP8WeightsOnMacOS(t *testing.T) {
+	cache := cachedModelWithFile(t, "nvidia/Llama-FP8", llama8BFP8Config, "hf_quant_config.json", modelOptFP8WeightsJSON)
+
+	err := validateMetalModel([]string{"--model", "nvidia/Llama-FP8"}, cache, "darwin")
+
+	if err == nil {
+		t.Fatal("ModelOpt FP8 weights must be rejected before vLLM Metal starts")
+	}
+	for _, want := range []string{"nvidia/Llama-FP8", "ModelOpt FP8", "BF16", "MLX-compatible"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Fatalf("error = %q, want %q", err, want)
+		}
+	}
+}
+
+func TestValidateMetalModel_AllowsModelOptFP8WeightsOutsideMacOS(t *testing.T) {
+	cache := cachedModelWithFile(t, "nvidia/Llama-FP8", llama8BFP8Config, "hf_quant_config.json", modelOptFP8WeightsJSON)
+
+	err := validateMetalModel([]string{"--model", "nvidia/Llama-FP8"}, cache, "linux")
+
+	if err != nil {
+		t.Fatalf("non-Metal platforms keep their native FP8 support: %v", err)
+	}
+}
@@ -283,6 +283,9 @@ func (e *Executor) bringUpProcess(ctx context.Context, st *engineState, engine s
 	if err := validateEffectiveLaunch(rt, launch, vars["host"], vars["port"]); err != nil {
 		return err
 	}
+	if err := validateAutoLaunch(rt, launch, vars["models_dir"]); err != nil {
+		return err
+	}
 	launch = applyAutoLaunch(engine, rt, launch, vars["models_dir"])
 	if launch, err = applyFrontBackend(rt, launch, port); err != nil {
 		return err