feat(inference): qualify llama.cpp on generic NVIDIA GPUs

.github/workflows/e2e.yaml

@@ -1923,6 +1923,7 @@ jobs:
       E2E_JOB: "1"
       E2E_TARGET_ID: "gpu-e2e"
       E2E_ARTIFACT_DIR: ${{ github.workspace }}/e2e-artifacts/live/gpu-e2e
+      E2E_LLAMA_CPP_DEDICATED_LANE: "1"
       NEMOCLAW_CLI_BIN: ${{ github.workspace }}/bin/nemoclaw.js
       NEMOCLAW_RUN_LIVE_E2E: "1"
       NEMOCLAW_NON_INTERACTIVE: "1"
@@ -1977,6 +1978,71 @@ jobs:
         shell: bash
         run: bash .github/scripts/docker-auth-cleanup.sh
 
+  llama-cpp-generic-gpu:
+    needs: generate-matrix
+    if: ${{ (github.event_name != 'workflow_dispatch' || (inputs.jobs == '' && inputs.targets == '')) || contains(format(',{0},', inputs.jobs), ',llama-cpp-generic-gpu,') || contains(format(',{0},', inputs.targets), ',llama-cpp-generic-gpu,') }}
+    runs-on: linux-amd64-gpu-rtxpro6000-latest-1
+    timeout-minutes: 120
+    env:
+      E2E_JOB: "1"
+      E2E_TARGET_ID: "llama-cpp-generic-gpu"
+      E2E_ARTIFACT_DIR: ${{ github.workspace }}/e2e-artifacts/live/llama-cpp-generic-gpu
+      NEMOCLAW_CLI_BIN: ${{ github.workspace }}/bin/nemoclaw.js
+      NEMOCLAW_RUN_LIVE_E2E: "1"
+      NEMOCLAW_E2E_EXPECTED_SHA: ${{ inputs.checkout_sha || github.sha }}
+      NEMOCLAW_NON_INTERACTIVE: "1"
+      NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE: "1"
+      NEMOCLAW_PROVIDER: "install-llama-cpp"
+      NEMOCLAW_LLAMACPP_RECIPE: "llama-cpp.nemotron-3-nano-30b-a3b.spark-single.v1"
+      NEMOCLAW_SANDBOX_NAME: "e2e-llama-cpp-generic-gpu"
+      OPENSHELL_GATEWAY: "nemoclaw"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: ${{ inputs.checkout_repository || github.repository }}
+          ref: ${{ inputs.checkout_sha || github.sha }}
+          persist-credentials: false
+
+      - *dockerhub-auth
+
+      - name: Prepare E2E workspace
+        uses: NVIDIA/NemoClaw/.github/actions/prepare-e2e@f6304bc25fc35bfaa441c8c2fbfee38f72805a75
+        with:
+          build-cli: "false"
+
+      - name: Restore exact-commit CLI artifact
+        uses: NVIDIA/NemoClaw/.github/actions/restore-e2e-cli-artifact@c246409193a31133cab10c8a3589001cc0d59eb3
+        with:
+          provenance-json: ${{ needs.generate-matrix.outputs.cli_artifact_provenance }}
+
+      - name: Install OpenShell CLI
+        run: bash scripts/install-openshell.sh
+
+      - name: Run generic NVIDIA GPU llama.cpp live test
+        run: |
+          set -euo pipefail
+          export PATH="$HOME/.local/bin:$HOME/.npm-global/bin:$PATH"
+          if command -v openshell >/dev/null 2>&1; then
+            OPENSHELL_BIN="$(command -v openshell)"
+          elif [ -x "$HOME/.local/bin/openshell" ]; then
+            OPENSHELL_BIN="$HOME/.local/bin/openshell"
+          else
+            echo "::error::OpenShell CLI not found after install"
+            exit 1
+          fi
+          export OPENSHELL_BIN
+          "$OPENSHELL_BIN" --version
+          npx tsx tools/e2e/live-vitest-invocation.mts run --test-path test/e2e/live/llama-cpp-generic-gpu.test.ts
+
+      - name: Upload generic NVIDIA GPU llama.cpp artifacts
+        if: always()
+        uses: NVIDIA/NemoClaw/.github/actions/upload-e2e-artifacts@7768e15eb90d3ee2d33432f481dfe8747e4f6d57
+
+      - name: Clean up Docker auth
+        if: always()
+        shell: bash
+        run: bash .github/scripts/docker-auth-cleanup.sh
+
   # Every main push runs this lane. Manual PR qualification also requires the
   # exact candidate activation contract.
   managed-image-multiarch-startup:
@@ -7256,6 +7322,7 @@ jobs:
         inference-routing,
         cloud-inference,
         gpu-e2e,
+        llama-cpp-generic-gpu,
         managed-image-multiarch-startup,
         llama-cpp-dgx-spark-plan,
         llama-cpp-dgx-spark-qualification,

docs/inference/choose-inference-provider.mdx

@@ -62,7 +62,7 @@ Local providers run on the host and keep inference traffic on infrastructure tha
 | Local vLLM already running | NemoClaw detects a server on `localhost:8000`. | [Set Up vLLM](../local-inference/set-up-vllm) |
 | Local vLLM managed install | The host matches a supported GPU profile and any required opt-in is present. | [Set Up vLLM](../local-inference/set-up-vllm) |
 | Local llama.cpp already running | You explicitly select an authenticated server on loopback port `8081`. | [Set Up llama.cpp](../local-inference/set-up-llama-cpp) |
-| Local llama.cpp managed install | A qualified DGX Spark host satisfies the declarative recipe requirements. | [Set Up llama.cpp](../local-inference/set-up-llama-cpp) |
+| Local llama.cpp managed install | A DGX Spark or Linux `amd64` NVIDIA GPU host matches one explicit experimental hardware preset. | [Set Up llama.cpp](../local-inference/set-up-llama-cpp) |
 | Local NVIDIA NIM | A NIM-capable NVIDIA GPU is present and experimental setup is enabled. | [Set Up NVIDIA NIM](../local-inference/set-up-nvidia-nim) |
 </AgentOnly>
 
@@ -72,7 +72,7 @@ Local providers run on the host and keep inference traffic on infrastructure tha
 | Local vLLM already running | NemoClaw detects a server on `localhost:8000`. | [Set Up vLLM](../local-inference/set-up-vllm) |
 | Local vLLM managed install | The host matches a supported GPU profile and any required opt-in is present. | [Set Up vLLM](../local-inference/set-up-vllm) |
 | Local llama.cpp already running | You explicitly select an authenticated server on loopback port `8081`. | [Set Up llama.cpp](../local-inference/set-up-llama-cpp) |
-| Local llama.cpp managed install | A qualified DGX Spark host satisfies the declarative recipe requirements. | [Set Up llama.cpp](../local-inference/set-up-llama-cpp) |
+| Local llama.cpp managed install | A DGX Spark or Linux `amd64` NVIDIA GPU host matches one explicit experimental hardware preset. | [Set Up llama.cpp](../local-inference/set-up-llama-cpp) |
 | Local NVIDIA NIM | A NIM-capable NVIDIA GPU is present and experimental setup is enabled. | [Set Up NVIDIA NIM](../local-inference/set-up-nvidia-nim) |
 </AgentOnly>
 

docs/inference/choose-local-inference-server.mdx

@@ -25,7 +25,7 @@ OpenShell intercepts that traffic and forwards it to the local endpoint configur
 | Managed vLLM | You want NemoClaw to pull an image, download model weights, and manage the server container. | Appears by default on DGX Spark and DGX Station, while generic Linux NVIDIA GPU hosts require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm`. | `/v1/chat/completions`. |
 | Fixed vLLM profile | You need the fixed catalog-selected vLLM model and serving configuration. | Requires the dedicated installer flag on DGX Spark and does not appear in the provider menu. | `/v1/chat/completions`. |
 | Existing llama.cpp | You already operate an authenticated llama.cpp server on loopback port `8081`. | Experimental. Always available for explicit selection and attaches only after cooperative fingerprinting succeeds. | `/v1/chat/completions`. |
-| Managed llama.cpp | You want NemoClaw to acquire a verified GGUF file and manage an authenticated llama.cpp container. | Experimental. Appears on a qualified DGX Spark host and supports explicit non-interactive selection. | `/v1/chat/completions`. |
+| Managed llama.cpp | You want NemoClaw to acquire a verified GGUF file and manage an authenticated llama.cpp container. | Experimental. Appears when a DGX Spark or Linux `amd64` NVIDIA GPU host matches an explicit hardware preset. | `/v1/chat/completions`. |
 | NVIDIA NIM | You want NemoClaw to pull and manage a validated NIM container on a NIM-capable NVIDIA GPU. | Experimental and requires `NEMOCLAW_EXPERIMENTAL=1`. | `/v1/chat/completions`. |
 </AgentOnly>
 
@@ -36,7 +36,7 @@ OpenShell intercepts that traffic and forwards it to the local endpoint configur
 | Managed vLLM | You want NemoClaw to pull an image, download model weights, and manage the server container. | Appears by default on DGX Spark and DGX Station, while generic Linux NVIDIA GPU hosts require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm`. | `/v1/chat/completions`. |
 | Fixed vLLM profile | You need the fixed catalog-selected vLLM model and serving configuration. | Requires the dedicated installer flag on DGX Spark and does not appear in the provider menu. | `/v1/chat/completions`. |
 | Existing llama.cpp | You already operate an authenticated llama.cpp server on loopback port `8081`. | Experimental. Always available for explicit selection and attaches only after cooperative fingerprinting succeeds. | `/v1/chat/completions`. |
-| Managed llama.cpp | You want NemoClaw to acquire a verified GGUF file and manage an authenticated llama.cpp container. | Experimental. Appears on a qualified DGX Spark host and supports explicit non-interactive selection. | `/v1/chat/completions`. |
+| Managed llama.cpp | You want NemoClaw to acquire a verified GGUF file and manage an authenticated llama.cpp container. | Experimental. Appears when a DGX Spark or Linux `amd64` NVIDIA GPU host matches an explicit hardware preset. | `/v1/chat/completions`. |
 | NVIDIA NIM | You want NemoClaw to pull and manage a validated NIM container on a NIM-capable NVIDIA GPU. | Experimental and requires `NEMOCLAW_EXPERIMENTAL=1`. | `/v1/chat/completions`. |
 </AgentOnly>
 
@@ -149,15 +149,17 @@ After a successful full uninstall, `docker container inspect nemoclaw-vllm` must
 
 ## Choose llama.cpp
 
-Choose llama.cpp when you already operate an authenticated server or want NemoClaw to materialize the experimental NVIDIA Nemotron recipe on DGX Spark.
+Choose llama.cpp when you already operate an authenticated server or want NemoClaw to materialize the experimental NVIDIA Nemotron recipe on a matching NVIDIA GPU host.
 The existing-server path owns only provider registration and routing.
 The managed path owns the exact YAML-selected model, launch, Docker lifecycle, diagnostics, and cleanup.
 
 Refer to [Set Up llama.cpp](set-up-llama-cpp).
 
-## Install Managed llama.cpp on DGX Spark
+<a id="install-managed-llamacpp-on-dgx-spark"></a>
 
-The managed procedure moved to [Set Up llama.cpp](set-up-llama-cpp#install-managed-llamacpp-on-dgx-spark).
+## Install Managed llama.cpp on an NVIDIA GPU Host
+
+The managed procedure moved to [Set Up llama.cpp](set-up-llama-cpp#install-managed-llamacpp-on-an-nvidia-gpu-host).
 
 ## Choose NVIDIA NIM
 

docs/inference/set-up-llama-cpp.mdx

@@ -3,22 +3,22 @@
 # SPDX-License-Identifier: Apache-2.0
 title: "Set Up llama.cpp"
 sidebar-title: "Set Up llama.cpp"
-description: "Attach an existing llama.cpp server or use the experimental managed NVIDIA Nemotron recipe on DGX Spark."
-description-agent: "Sets up llama.cpp for NemoClaw. Use for an authenticated existing server or the experimental declarative managed recipe on DGX Spark."
-keywords: ["nemoclaw llama.cpp", "llama.cpp dgx spark", "managed llama.cpp", "nemotron gguf"]
+description: "Attach an existing llama.cpp server or use the experimental managed NVIDIA Nemotron recipe on a matching NVIDIA GPU host."
+description-agent: "Sets up llama.cpp for NemoClaw. Use for an authenticated existing server or the experimental declarative managed recipe on DGX Spark and Linux amd64 NVIDIA GPU hosts."
+keywords: ["nemoclaw llama.cpp", "llama.cpp dgx spark", "llama.cpp nvidia gpu", "managed llama.cpp", "nemotron gguf"]
 content:
   type: "how_to"
 ---
 NemoClaw provides two first-class llama.cpp paths.
-You can attach an authenticated server that you operate, or let NemoClaw materialize one repository-owned recipe on DGX Spark.
+You can attach an authenticated server that you operate, or let NemoClaw materialize one repository-owned recipe on a matching NVIDIA GPU host.
 Both paths are experimental and use OpenAI Chat Completions through `https://inference.local/v1`.
 
 ## Choose a llama.cpp Path
 
 | Path | NemoClaw manages | You manage | Use it when |
 |---|---|---|---|
 | Existing server | Provider registration, route validation, and sandbox traffic through `inference.local`. | The server binary or container, GGUF file, launch configuration, credential, upgrades, and lifecycle. | Your authenticated server already satisfies the llama.cpp fingerprint contract on loopback port `8081`. |
-| Managed DGX Spark | The exact YAML-selected image, GGUF acquisition and verification, launch configuration, credential, Docker lifecycle, diagnostics, and cleanup. | The qualified Linux host, Docker Engine, NVIDIA runtime prerequisites, storage, and any required Hugging Face credential. | You want the experimental NVIDIA Nemotron recipe without managing llama-server directly. |
+| Managed NVIDIA GPU | The exact YAML-selected image, GGUF acquisition and verification, launch configuration, credential, Docker lifecycle, diagnostics, and cleanup. | The matching Linux host, Docker Engine, NVIDIA runtime prerequisites, storage, and any required Hugging Face credential. | You want the experimental NVIDIA Nemotron recipe without managing llama-server directly. |
 
 Compared with other local options, Ollama emphasizes a simple local model workflow, while managed vLLM provides host-specific NVIDIA GPU profiles and broader model selection.
 NVIDIA NIM provides NVIDIA-packaged inference containers for validated NIM-capable GPUs.
@@ -75,10 +75,17 @@ $$nemoclaw my-assistant doctor
 If a compatible server does not satisfy the first-class fingerprint, use [Set Up an OpenAI-Compatible Endpoint](../custom-endpoints/set-up-openai-compatible-endpoint).
 That path supports operator-selected endpoints and ports without claiming llama.cpp-specific identity or lifecycle ownership.
 
-## Install Managed llama.cpp on DGX Spark
+## Install Managed llama.cpp on an NVIDIA GPU Host
 
-Use this experimental path when you want NemoClaw to manage one declarative llama.cpp recipe on one DGX Spark.
-The default recipe serves NVIDIA Nemotron 3 Nano 30B-A3B through the OpenAI Chat Completions API.
+Use this experimental path when you want NemoClaw to manage one declarative llama.cpp recipe on one matching NVIDIA GPU host.
+The repository currently defines these experimental hardware presets:
+
+- One DGX Spark running Linux on Arm64.
+- One Linux `amd64` host with an NVIDIA GPU.
+
+Both hardware presets use `llama-cpp.nemotron-3-nano-30b-a3b.spark-single.v1`.
+That recipe serves NVIDIA Nemotron 3 Nano 30B-A3B through the OpenAI Chat Completions API.
+The Linux `amd64` preset does not define a generic GPU model default or a new recipe.
 
 <Note>
 This path is an experimental implementation.
@@ -87,10 +94,11 @@ It does not establish a supported agent, model, and runtime tuple until the prot
 
 Before you start, confirm these prerequisites:
 
-- Use a DGX Spark host with Linux on Arm64.
-- Confirm that Docker is operational on the host.
+- Use a DGX Spark with Linux on Arm64, or use a Linux `amd64` host.
+- Use Docker Engine, not Docker Desktop.
+- Provide at least one NVIDIA GPU.
 - Confirm that the NVIDIA Container Toolkit is operational.
-- Confirm that NVIDIA Container Device Interface support is healthy.
+- Confirm that NVIDIA Container Device Interface (CDI) support is healthy.
 - Use NVIDIA driver version `580.65.06` or later.
 - Stop any process that uses host port `8081`.
 - Allow capacity for the pinned images, the GGUF file, and same-filesystem download staging.
@@ -107,7 +115,7 @@ It creates an owner-only API key, a host-loopback listener on port `8081`, and a
 Only one managed llama.cpp runtime can exist per Docker authority, regardless of the owning OpenShell gateway or sandbox.
 </Warning>
 
-Run interactive onboarding on the DGX Spark and select **NVIDIA Nemotron with managed llama.cpp (DGX Spark)**:
+Run interactive onboarding on a matching host and select **NVIDIA Nemotron with managed llama.cpp**:
 
 ```bash
 $$nemoclaw onboard
@@ -125,12 +133,16 @@ NEMOCLAW_SANDBOX_NAME=my-assistant \
 When `NEMOCLAW_LLAMACPP_RECIPE` is unset, NemoClaw selects the one shipped managed llama.cpp recipe.
 Set the variable explicitly in automation so the selected recipe is visible in the invocation.
 Do not set `NEMOCLAW_MODEL` for this path.
+Host readiness selects exactly one explicit hardware preset for the recipe.
+NemoClaw stops before artifact acquisition when no preset matches or more than one preset matches.
+The recipe selects the exact model and digest-pinned runtime image for both hardware presets.
 The repository YAML recipe is authoritative for the exact model file, revision, digest, image, launch settings, resource limits, readiness probes, and disabled surfaces.
+The selected hardware preset supplies only the host requirements for that recipe.
 NemoClaw does not provide hidden model, port, image, or launch-flag overrides for the managed path.
 
 Onboarding performs these actions:
 
-- Resolves the recipe against a fresh DGX Spark readiness report.
+- Resolves the recipe against a fresh host-readiness report and requires exactly one matching hardware preset.
 - Reuses locally present pinned downloader, runtime, and probe images, and pulls only the missing digest-pinned images declared by the recipe.
 - Reuses a verified GGUF from the shared `~/.cache/huggingface/` cache, or acquires the exact file through the existing Hugging Face mechanism when it is absent or invalid.
 - Verifies the GGUF size and SHA-256 digest before it starts the runtime.
@@ -163,6 +175,20 @@ These checks do not establish agent and model qualification.
 `doctor` distinguishes identity, runtime, and route failures and provides a recovery hint.
 Refer to [CLI Commands](../../reference/commands) for complete command behavior.
 
+For Linux `amd64` release qualification, the `llama-cpp-generic-gpu` live end-to-end test provides separate candidate evidence.
+A passing exact-commit run must prove all of these results:
+
+- The host uses Linux `amd64`, Docker Engine, and an NVIDIA GPU.
+- The installer uses the exact provider and recipe shown above without `NEMOCLAW_MODEL`.
+- The managed owner state records the selected preset digest, and the receipt matches the recipe, model digest, and runtime image.
+- llama.cpp offloads every model layer to the assigned GPU.
+- An unauthenticated host request receives HTTP `401`.
+- Authenticated host inference, routed sandbox inference, and one OpenClaw agent turn succeed.
+- Owned container and network cleanup completes after sandbox destruction.
+
+The configured test does not prove these results until its exact candidate run and artifacts pass review.
+Even a passing run keeps this path experimental and does not activate a supported agent, model, and runtime tuple.
+
 ## Recover the Managed Runtime
 
 If onboarding stops, rerun the same provider and recipe selection.