Install the official CUDA llama.cpp build on Windows x64 NVIDIA GPUs

The official Windows installer selects its CUDA build only when the CUDA
Toolkit is installed, so NVIDIA PCs with just the driver received the
Vulkan build. When every NVIDIA GPU reports compute capability 7.5 or
newer, Install now stages the checksum-pinned b10826 CUDA 13.3 app and
CUDA runtime archives and requires a CUDA device before promotion. Any
other outcome runs the pinned vendor installer as before and records the
reason in the install receipt.

Signed-off-by: pgoode41 <pgoode41@gmail.com>

Author: pgoode41

services/nvpair-engine-manager/MANIFEST.md

@@ -149,6 +149,7 @@ and recovery. Editing `args`/`start` directly remains trusted manifest authoring
 | `archive_root` | string | no | The fixed top-level directory a tar archive wraps its files in, stripped on extraction; a single safe path component. Requires `archives`. |
 | `upstream_first` | bool | no | Windows ARM64 `llama-app` only: try the current official upstream installer first in a bounded, separate staging attempt and fall back to the pinned `archives` when it fails verification or the device check. |
 | `cpu_fetch` | fetch | no | Windows ARM64 `llama-app` only: the pinned official CPU installer used when the hardware inventory confirms a non-NVIDIA device. |
+| `cuda_archives` | fetch[] | no | Windows x64 `llama-app` only, alongside a pinned `fetch`: checksum-pinned official CUDA app and CUDA runtime archives installed when every NVIDIA GPU reports compute capability 7.5 or newer and the staged build passes the CUDA device check. Otherwise the `fetch` installer runs. Every entry needs `url` and `sha256`. |
 
 `uninstall.driver: "llama-app"` selects the driver's runtime-only removal (the
 `runtime` and `previous` slots), keeping the engine's separate model library
@@ -345,8 +346,8 @@ field is missing, `manifest_version` is unsupported, a platform key isn't
 `runtime.mode` is invalid, an action sets none or more than one of
 `http`/`cmd`/`remove_path`/`builtin`, an install `driver`, uninstall `driver`
 or action `builtin` names an unknown routine or one bundled for another
-engine, `archives`/`archive_root`/`upstream_first`/`cpu_fetch` appear without
-the `llama-app` driver or its platform policy, a `remove_path` action omits
+engine, `archives`/`archive_root`/`upstream_first`/`cpu_fetch`/`cuda_archives`
+appear without the `llama-app` driver or its platform policy, a `remove_path` action omits
 `root` or `path`, a `result` is set without both `array` and `field` (or a
 `result.match` without both `match.field` and a non-empty `match.in`), or
 a non-action templated string uses an unknown placeholder.

services/nvpair-engine-manager/README.md

@@ -430,7 +430,20 @@ The existing version/license, candidate promotion/rollback and persistent model
 cache lifecycle apply. This artifact requires macOS 13.3 or newer and does not
 provide Radeon acceleration.
 
-Ordinary Windows x64 and Linux recipes retain vendor accelerator-to-CPU selection;
+On Windows x64 the official installer selects its CUDA build only when the CUDA
+Toolkit is installed; with just the NVIDIA driver it selects Vulkan. Install
+therefore reads one compute capability per GPU from `nvidia-smi` first. When
+every NVIDIA GPU reports 7.5 (Turing) or newer, PAIR stages the checksum-pinned
+b10826 CUDA 13.3 app ZIP plus CUDA runtime ZIP declared in
+`install.cuda_archives`, which need no toolkit, and requires the same `CUDA0:`
+device check before promotion. No NVIDIA GPU, an older or unreadable one, an
+unavailable archive or a failed device check runs the pinned installer below in
+a separate stage instead, and its receipt records the reason as
+`cuda_not_used`. Parent cancellation never starts that installer. A CUDA receipt
+records `source: pinned-cuda-archives`, `acceleration_policy: cuda`, the archive
+recipe and the reported compute capabilities.
+
+Linux and the Windows x64 installer path retain vendor accelerator-to-CPU selection;
 Apple Silicon retains its Metal installer. Selection is not automatic recovery
 from a GPU hang or incorrect model answer. `install_supported` and
 `install_reason` describe recipe availability and selection requirements, not

services/nvpair-engine-manager/executor.go

@@ -86,7 +86,9 @@ type Executor struct {
 	emit             func(method string, params any)
 	client           *http.Client
 	armHardwareQuery func(context.Context, map[string]string) (string, error) // nil uses the native inventory command
-	ollamaLoadClient *http.Client
+	// nvidiaComputeQuery returns one compute capability per NVIDIA GPU; nil runs nvidia-smi.
+	nvidiaComputeQuery func(context.Context, map[string]string) (string, error)
+	ollamaLoadClient   *http.Client
 	// progress fans install/pull progress to transient subscribers (the ec
 	// streaming handlers) in addition to the local engine:install-progress
 	// notification path. See progress.go.

services/nvpair-engine-manager/llamaarchives.go

@@ -17,8 +17,8 @@ import (
 const maxLlamaArchiveEntries = 10000
 
 // Merge the pinned official app and dependency bundles into a fresh owned stage.
-// The actual ARM64 bundles are flat; relative directories are preserved, never flattened.
-func (e *Executor) stageLlamaArchives(ctx context.Context, st *engineState, candidate string) error {
+// The actual Windows bundles are flat; relative directories are preserved, never flattened.
+func (e *Executor) stageLlamaArchives(ctx context.Context, st *engineState, candidate string, archives []Fetch) error {
 	if err := validateLlamaOwnedPaths(st.installDir); err != nil {
 		return err
 	}
@@ -32,7 +32,7 @@ func (e *Executor) stageLlamaArchives(ctx context.Context, st *engineState, cand
 		return err
 	}
 	remaining, entries := maxDownloadBytes, 0
-	for _, fetch := range st.plat.Install.Archives {
+	for _, fetch := range archives {
 		if err := ctx.Err(); err != nil {
 			return err
 		}

services/nvpair-engine-manager/llamaarchives_test.go

@@ -58,7 +58,7 @@ func TestLlamaArchivesMergeAndRefuseCollision(t *testing.T) {
 				index++
 				return &http.Response{StatusCode: 200, ContentLength: int64(len(data)), Body: io.NopCloser(bytes.NewReader(data))}, nil
 			})}
-			err := e.stageLlamaArchives(context.Background(), st, candidate)
+			err := e.stageLlamaArchives(context.Background(), st, candidate, st.plat.Install.Archives)
 			if (err != nil) != collision {
 				t.Fatalf("collision=%v: %v", collision, err)
 			}

services/nvpair-engine-manager/llamaarmcpu.go

@@ -106,7 +106,7 @@ func (e *Executor) prepareLlamaARMCPU(ctx context.Context, st *engineState, stag
 		return "", nil, fmt.Errorf("official Windows ARM CPU installer: %w", err)
 	}
 	candidate := filepath.Join(home, "llama-app")
-	identity, licenses, err := e.validateLlamaARMApp(ctx, st, candidate, 10826, false)
+	identity, licenses, err := e.validateLlamaApp(ctx, st, candidate, 10826, false)
 	if err != nil {
 		return "", nil, err
 	}

services/nvpair-engine-manager/llamacuda.go

@@ -0,0 +1,96 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// The CUDA 13 llama build carries kernels for compute capability 7.5 (Turing)
+// and newer. An older GPU still enumerates as a CUDA device, so the staged
+// build's device check alone cannot reject it.
+const llamaMinCUDACapability = 7.5
+
+// llamaCUDACapabilities parses nvidia-smi's one-row-per-GPU compute capability output.
+func llamaCUDACapabilities(out string) ([]string, error) {
+	var capabilities []string
+	for _, line := range strings.Split(out, "\n") {
+		line = strings.TrimSpace(line)
+		if line == "" {
+			continue
+		}
+		if _, err := strconv.ParseFloat(line, 64); err != nil {
+			return nil, fmt.Errorf("nvidia-smi reported an unreadable compute capability %q", line)
+		}
+		capabilities = append(capabilities, line)
+	}
+	if len(capabilities) == 0 {
+		return nil, errors.New("nvidia-smi reported no NVIDIA GPU")
+	}
+	return capabilities, nil
+}
+
+// prepareLlamaWindowsCUDA stages and validates the pinned official CUDA build
+// when every NVIDIA GPU can run it. When CUDA does not apply, or the staged
+// build reports no CUDA device, it returns no candidate and the reason so the
+// caller runs the pinned vendor installer instead. Only cancellation and local
+// write failures are errors.
+func (e *Executor) prepareLlamaWindowsCUDA(ctx context.Context, st *engineState, stage string) (string, map[string]any, string, error) {
+	env, err := childEnv(st)
+	if err != nil {
+		return "", nil, "", err
+	}
+	query := e.nvidiaComputeQuery
+	if query == nil {
+		query = func(ctx context.Context, env map[string]string) (string, error) {
+			return e.runCommandOutput(ctx, []string{"nvidia-smi", "--query-gpu=compute_cap", "--format=csv,noheader"}, env)
+		}
+	}
+	queryCtx, cancel := context.WithTimeout(ctx, 15*time.Second)
+	raw, err := query(queryCtx, env)
+	cancel()
+	if ctx.Err() != nil {
+		return "", nil, "", ctx.Err()
+	}
+	if err != nil {
+		return "", nil, fmt.Sprintf("no NVIDIA GPU reported by nvidia-smi: %v", err), nil
+	}
+	capabilities, err := llamaCUDACapabilities(raw)
+	if err != nil {
+		return "", nil, err.Error(), nil
+	}
+	for _, capability := range capabilities {
+		if value, _ := strconv.ParseFloat(capability, 64); value < llamaMinCUDACapability {
+			return "", nil, fmt.Sprintf("NVIDIA compute capability %s is below the 7.5 the CUDA build requires", capability), nil
+		}
+	}
+	candidate := filepath.Join(stage, "cuda")
+	if err := e.stageLlamaArchives(ctx, st, candidate, st.plat.Install.CUDAArchives); err != nil {
+		if ctx.Err() != nil {
+			return "", nil, "", ctx.Err()
+		}
+		return "", nil, fmt.Sprintf("official CUDA archives: %v", err), nil
+	}
+	identity, licenses, err := e.validateLlamaCUDA(ctx, st, candidate, 10826)
+	if err != nil {
+		if ctx.Err() != nil {
+			return "", nil, "", ctx.Err()
+		}
+		return "", nil, fmt.Sprintf("official CUDA build: %v", err), nil
+	}
+	identity["source"], identity["acceleration_policy"] = "pinned-cuda-archives", "cuda"
+	identity["compute_capabilities"] = capabilities
+	identity["archives"], identity["recipe_sha256"] = st.plat.Install.CUDAArchives, llamaArchiveRecipeHash(st.plat.Install.CUDAArchives)
+	if err := os.WriteFile(filepath.Join(candidate, "THIRD-PARTY-LICENSES.txt"), []byte(licenses), 0600); err != nil {
+		return "", nil, "", err
+	}
+	return candidate, identity, "", ctx.Err()
+}

services/nvpair-engine-manager/llamacuda_test.go

@@ -0,0 +1,200 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+package main
+
+import (
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+type windowsCUDAFixture struct {
+	*llamaUpstreamFixture
+	vendor      *Fetch
+	failArchive bool
+	onArchive   func()
+}
+
+// newWindowsCUDAFixture shapes the recipe like the bundled Windows x64 one: a
+// pinned vendor installer plus a pinned CUDA app and runtime bundle.
+func newWindowsCUDAFixture(t *testing.T, capabilities string, queryErr error, cuda llamaRuntimeFixture) *windowsCUDAFixture {
+	t.Helper()
+	upstream := newLlamaUpstreamFixture(t, llamaRuntimeFixture{Version: "version: 0.4.0-dev (build 10826, commit fixture)", Licenses: "vendor fixture license", Devices: "Available devices:\n  Vulkan0: Fixture GPU"})
+	script := []byte(`$ErrorActionPreference='Stop'
+if ($env:LLAMA_VERSION -ne 'b10826' -or $env:SKIP_INSTALL -ne '1' -or $env:SKIP_CUDA -or $env:SKIP_VULKAN) {throw 'vendor selection was restricted'}
+$stagePath=Join-Path $env:USERPROFILE 'llama-app'
+New-Item -ItemType Directory -Path $stagePath -Force | Out-Null
+Copy-Item -LiteralPath $env:FAKE_LLAMA_BIN_SOURCE -Destination (Join-Path $stagePath 'llama.exe')
+Copy-Item -LiteralPath $env:FAKE_LLAMA_FIXTURE_SOURCE -Destination (Join-Path $stagePath '.llama-fixture.json')
+`)
+	digest := sha256.Sum256(script)
+	f := &windowsCUDAFixture{llamaUpstreamFixture: upstream, vendor: &Fetch{URL: "https://example.invalid/pinned-vendor.ps1", SHA256: hex.EncodeToString(digest[:])}}
+	bin, err := os.ReadFile(fakeEngineBin)
+	if err != nil {
+		t.Fatal(err)
+	}
+	cudaJSON, _ := json.Marshal(cuda)
+	bundles := [][]byte{llamaFixtureZip(t, map[string][]byte{"llama.exe": bin, ".llama-fixture.json": cudaJSON}), llamaFixtureZip(t, map[string][]byte{"cudart64_13.dll": []byte("fixture CUDA runtime")})}
+	install := f.st.plat.Install
+	install.UpstreamFirst, install.CPUFetch, install.Archives, install.Fetch, install.CUDAArchives = false, nil, nil, f.vendor, nil
+	for i, bundle := range bundles {
+		h := sha256.Sum256(bundle)
+		install.CUDAArchives = append(install.CUDAArchives, Fetch{URL: fmt.Sprintf("https://github.com/ggml-org/llama.cpp/releases/download/b10826/fixture-cuda-%d.zip", i), SHA256: hex.EncodeToString(h[:])})
+	}
+	f.e.nvidiaComputeQuery = func(context.Context, map[string]string) (string, error) { return capabilities, queryErr }
+	f.e.client = &http.Client{Transport: llamaFixtureTransport(func(r *http.Request) (*http.Response, error) {
+		url := r.URL.String()
+		f.requests[url]++
+		body := []byte(nil)
+		if url == f.vendor.URL {
+			body = script
+		}
+		for i, fetch := range install.CUDAArchives {
+			if fetch.URL != url {
+				continue
+			}
+			if f.onArchive != nil {
+				f.onArchive()
+			}
+			if f.failArchive {
+				return nil, errors.New("fixture CUDA archive unavailable")
+			}
+			body = bundles[i]
+		}
+		if body == nil {
+			return nil, errors.New("unexpected fixture request")
+		}
+		return &http.Response{StatusCode: http.StatusOK, ContentLength: -1, Body: io.NopCloser(bytes.NewReader(body))}, nil
+	})}
+	return f
+}
+
+func (f *windowsCUDAFixture) archiveRequests() int {
+	n := 0
+	for _, fetch := range f.st.plat.Install.CUDAArchives {
+		n += f.requests[fetch.URL]
+	}
+	return n
+}
+
+// Every NVIDIA GPU at 7.5 or newer installs the pinned CUDA build; anything that
+// rules CUDA out installs the vendor build and records why, without mixing the
+// two stages.
+func TestLlamaWindowsCUDASelection(t *testing.T) {
+	noDevice := cudaLlamaFixture(10826)
+	noDevice.Devices = "Available devices:\n  CPU0: Fixture CPU"
+	for _, tc := range []struct {
+		name, capabilities, note string
+		queryErr                 error
+		cuda                     llamaRuntimeFixture
+		failArchive              bool
+		archiveRequests          int
+	}{
+		{name: "turing-or-newer", capabilities: "8.9\n12.0\n", cuda: cudaLlamaFixture(10826), archiveRequests: 2},
+		{name: "no-nvidia", queryErr: errors.New("executable file not found"), cuda: cudaLlamaFixture(10826), note: "no NVIDIA GPU"},
+		{name: "pre-turing", capabilities: "8.9\n6.1\n", cuda: cudaLlamaFixture(10826), note: "below the 7.5"},
+		{name: "unreadable", capabilities: "[N/A]\n", cuda: cudaLlamaFixture(10826), note: "unreadable"},
+		{name: "no-cuda-device", capabilities: "8.9\n", cuda: noDevice, note: "CUDA device", archiveRequests: 2},
+		{name: "archive-unavailable", capabilities: "8.9\n", cuda: cudaLlamaFixture(10826), failArchive: true, note: "official CUDA archives", archiveRequests: 1},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			f := newWindowsCUDAFixture(t, tc.capabilities, tc.queryErr, tc.cuda)
+			f.failArchive = tc.failArchive
+			if err := f.e.installLlamaApp(context.Background(), f.st); err != nil {
+				t.Fatal(err)
+			}
+			receipt := f.receipt(t)
+			if got := f.archiveRequests(); got != tc.archiveRequests {
+				t.Fatalf("CUDA archive requests = %d, want %d", got, tc.archiveRequests)
+			}
+			_, runtimeErr := os.Stat(filepath.Join(f.st.installDir, "runtime", "cudart64_13.dll"))
+			if tc.note == "" {
+				capabilities, _ := receipt["compute_capabilities"].([]any)
+				if receipt["source"] != "pinned-cuda-archives" || receipt["acceleration_policy"] != "cuda" || receipt["cuda_device_verified"] != true ||
+					len(capabilities) != 2 || receipt["recipe_sha256"] != llamaArchiveRecipeHash(f.st.plat.Install.CUDAArchives) {
+					t.Fatalf("wrong CUDA provenance: %#v", receipt)
+				}
+				if f.requests[f.vendor.URL] != 0 || runtimeErr != nil {
+					t.Fatal("CUDA install ran the vendor installer or lost the CUDA runtime")
+				}
+				return
+			}
+			note, _ := receipt["cuda_not_used"].(string)
+			if receipt["installer_sha256"] != f.vendor.SHA256 || !strings.Contains(note, tc.note) {
+				t.Fatalf("vendor install lacks its provenance or CUDA reason: %#v", receipt)
+			}
+			if f.requests[f.vendor.URL] != 1 || !os.IsNotExist(runtimeErr) {
+				t.Fatal("vendor install skipped its installer or merged CUDA bytes")
+			}
+		})
+	}
+}
+
+// A parent cancellation during the CUDA download ends the install cancelled; it
+// never authorizes the vendor installer.
+func TestLlamaWindowsCUDACancelDoesNotFallBack(t *testing.T) {
+	f := newWindowsCUDAFixture(t, "8.9\n", nil, cudaLlamaFixture(10826))
+	model := f.retainModels(t)
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	f.onArchive = cancel
+	if err := f.e.installLlamaApp(ctx, f.st); !errors.Is(err, context.Canceled) {
+		t.Fatalf("cancellation lost: %v", err)
+	}
+	if f.requests[f.vendor.URL] != 0 {
+		t.Fatal("cancelled CUDA install ran the vendor installer")
+	}
+	f.assertNothingPromoted(t, model)
+}
+
+func TestLlamaWindowsCUDARecipe(t *testing.T) {
+	mf, _ := buildRegistry("").Get("llamacpp")
+	want := []Fetch{
+		{URL: "https://github.com/ggml-org/llama.cpp/releases/download/b10826/llama-b10826-bin-win-cuda-13.3-x64.zip", SHA256: "34549bd7c46717333277d7bfc4c8617a12be0fad33a5253748e59e1085ffda4f"},
+		{URL: "https://github.com/ggml-org/llama.cpp/releases/download/b10826/cudart-llama-bin-win-cuda-13.3-x64.zip", SHA256: "1462a050eb4c684921ba51dcc4cc488a036674c3e73e9945ee705b854808d03e"},
+	}
+	if p := mf.Platforms["windows/amd64"]; !reflect.DeepEqual(p.Install.CUDAArchives, want) || p.Install.Fetch == nil {
+		t.Fatalf("Windows x64 lost its pinned CUDA build or vendor fallback: %+v", p.Install)
+	}
+	for key, p := range mf.Platforms {
+		if key != "windows/amd64" && len(p.Install.CUDAArchives) > 0 {
+			t.Fatalf("%s acquired the Windows x64 CUDA recipe", key)
+		}
+	}
+	if _, reason := llamaInstallSupport("windows", "amd64"); !strings.Contains(reason, "CUDA") {
+		t.Fatalf("Windows x64 support reason omits the CUDA policy: %q", reason)
+	}
+	for _, mutation := range []string{"other-platform", "no-fallback", "unpinned-fallback", "unpinned-archive", "upstream-first"} {
+		t.Run(mutation, func(t *testing.T) {
+			fresh, _ := buildRegistry("").Get("llamacpp")
+			p, key := fresh.Platforms["windows/amd64"], "windows/amd64"
+			switch mutation {
+			case "other-platform":
+				key = "linux/amd64"
+			case "no-fallback":
+				p.Install.Fetch = nil
+			case "unpinned-fallback":
+				p.Install.Fetch = &Fetch{URL: p.Install.Fetch.URL}
+			case "unpinned-archive":
+				p.Install.CUDAArchives[0].SHA256 = ""
+			case "upstream-first":
+				p.Install.UpstreamFirst = true
+			}
+			if err := p.validate(key); err == nil {
+				t.Fatal("invalid Windows x64 CUDA recipe accepted")
+			}
+		})
+	}
+}