feat(inference): persist serving profile lifecycle provenance

ci/source-architecture-budget.json

@@ -12,7 +12,7 @@
       "src/lib/adapters/openshell/timeouts.ts": 37,
       "src/lib/agent/defs.ts": 32,
       "src/lib/cli/branding.ts": 87,
-      "src/lib/cli/nemoclaw-oclif-command.ts": 104,
+      "src/lib/cli/nemoclaw-oclif-command.ts": 105,
       "src/lib/cli/terminal-style.ts": 45,
       "src/lib/core/json-types.ts": 37,
       "src/lib/core/ports.ts": 88,

ci/test-file-size-budget.json

@@ -9,6 +9,6 @@
     "test/install-preflight.test.ts": 3921,
     "test/nemoclaw-start.test.ts": 4791,
     "test/onboard-messaging.test.ts": 2043,
-    "test/onboard-selection.test.ts": 4769
+    "test/onboard-selection.test.ts": 4767
   }
 }

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

@@ -3,13 +3,13 @@
 # SPDX-License-Identifier: Apache-2.0
 title: "Choose a Local Inference Server"
 sidebar-title: "Choose a Local Server"
-description: "Compare Ollama, vLLM, and NVIDIA NIM before choosing a local inference server for NemoClaw."
-description-agent: "Compares NemoClaw local inference server options. Use when choosing between Ollama, vLLM, and NVIDIA NIM."
-keywords: ["nemoclaw local inference", "ollama vllm nim", "local inference server"]
+description: "Compare operator-run servers and managed runtime profiles before choosing local inference for NemoClaw."
+description-agent: "Compares NemoClaw local inference options. Use when choosing Ollama, vLLM, llama.cpp, NVIDIA NIM, or a fixed local model profile."
+keywords: ["nemoclaw local inference", "ollama vllm llama.cpp nim", "local inference server"]
 content:
   type: "concept"
 ---
-NemoClaw supports Ollama, vLLM, and NVIDIA NIM as local inference servers.
+NemoClaw supports operator-run servers and NemoClaw-managed runtime profiles for local inference.
 Choose the option that matches your host, model, and operational needs.
 
 The agent inside the sandbox sends inference traffic to `inference.local`.
@@ -23,6 +23,7 @@ OpenShell intercepts that traffic and forwards it to the local endpoint configur
 | Ollama | You want the default local option and want NemoClaw to install, start, or use Ollama on supported hosts. | Appears when Ollama is installed or running, and the wizard can offer installation on supported hosts. | Ollama through the managed local route. |
 | Existing vLLM | You already run vLLM on `localhost:8000`. | Appears when NemoClaw detects the server. | `/v1/chat/completions`. |
 | 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 local model profile | You need one catalog-selected model and serving runtime combination. | Requires the dedicated installer flag on DGX Spark and does not appear in the provider menu. | `/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>
 
@@ -31,6 +32,7 @@ OpenShell intercepts that traffic and forwards it to the local endpoint configur
 |---|---|---|---|
 | Existing vLLM | You already run vLLM on `localhost:8000`. | Appears when NemoClaw detects the server. | `/v1/chat/completions`. |
 | 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 local model profile | You need one catalog-selected model and serving runtime combination. | Requires the dedicated installer flag on DGX Spark and does not appear in the provider menu. | `/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>
 
@@ -59,6 +61,119 @@ NemoClaw forces the Chat Completions API path because the vLLM Responses endpoin
 
 Refer to [Set Up vLLM](set-up-vllm).
 
+## Install a Fixed Local Model Profile
+
+Use this feature-gated path to install one catalog-selected model-and-runtime combination for vLLM or llama.cpp.
+The installer does not accept a provider or model override for this profile.
+
+Before you start, confirm these prerequisites:
+
+- Use a DGX Spark host with Linux on Arm64.
+- Confirm that Docker, the NVIDIA Container Toolkit, and the NVIDIA GPU driver are operational.
+- Stop any server that already uses port `8000` for vLLM or port `8081` for llama.cpp.
+- Allow capacity for container images, model artifacts, and same-filesystem download staging.
+- Export `HF_TOKEN` only if the configured artifact source requires Hugging Face authentication.
+
+NemoClaw uses `HF_TOKEN` only for model acquisition and does not write it to NemoClaw state.
+The value remains in the caller's environment; run `unset HF_TOKEN` after installation when no other process needs it.
+
+<Warning>
+The installer downloads a pinned container image and a fixed catalog model from external registries.
+It runs the remaining onboarding steps non-interactively and can recreate the named sandbox when its recorded inference route differs.
+The runtime stores an owner-only bearer API key and model artifacts on the host.
+</Warning>
+
+Select vLLM:
+
+```bash
+curl -fsSL https://www.nvidia.com/nemoclaw.sh | \
+<AgentOnly variant="openclaw">
+  NEMOCLAW_AGENT=openclaw \
+</AgentOnly>
+<AgentOnly variant="hermes">
+  NEMOCLAW_AGENT=hermes \
+</AgentOnly>
+<AgentOnly variant="deepagents">
+  NEMOCLAW_AGENT=langchain-deepagents-code \
+</AgentOnly>
+  NEMOCLAW_SANDBOX_NAME=my-assistant \
+  NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 \
+  bash -s -- --local-model-runtime=vllm
+```
+
+Select llama.cpp:
+
+```bash
+curl -fsSL https://www.nvidia.com/nemoclaw.sh | \
+<AgentOnly variant="openclaw">
+  NEMOCLAW_AGENT=openclaw \
+</AgentOnly>
+<AgentOnly variant="hermes">
+  NEMOCLAW_AGENT=hermes \
+</AgentOnly>
+<AgentOnly variant="deepagents">
+  NEMOCLAW_AGENT=langchain-deepagents-code \
+</AgentOnly>
+  NEMOCLAW_SANDBOX_NAME=my-assistant \
+  NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 \
+  bash -s -- --local-model-runtime=llama-cpp
+```
+
+The flag enables the dedicated profile gate, disables Express selection, and selects the matching catalog recipe.
+Do not combine this path with `NEMOCLAW_PROVIDER` or `NEMOCLAW_MODEL`.
+The vLLM profile rejects `NEMOCLAW_VLLM_MODEL`, `NEMOCLAW_VLLM_PORT`, and `NEMOCLAW_VLLM_EXTRA_ARGS_JSON` before installation.
+
+The vLLM choice performs these actions:
+
+- Uses the pinned runtime image and fixed serving command from the catalog.
+- Stores model files in the host Hugging Face cache.
+- Publishes the authenticated server only on `127.0.0.1:8000`.
+- Reuses the owner-only host-global managed-vLLM API key.
+
+The llama.cpp choice performs these actions:
+
+- Downloads one exact GGUF artifact over HTTPS.
+- Verifies the declared size and SHA-256 digest before cache publication or launch.
+- Stores the verified artifact in an owner-only content-addressed cache.
+- Publishes the authenticated server only on `127.0.0.1:8081` through a dedicated internal Docker network.
+
+After either runtime passes its readiness check, onboarding registers the provider and routes sandbox traffic through `inference.local`.
+
+Verify the sandbox route:
+
+```bash
+$$nemoclaw my-assistant status
+$$nemoclaw my-assistant doctor
+```
+
+Accept the result when `status` reports the inference route as `reachable` and `doctor` exits with status `0`.
+Route reachability does not by itself establish successful model invocation.
+
+Verify the loopback publication for the selected runtime:
+
+```bash
+docker port nemoclaw-vllm
+docker port nemoclaw-llama-cpp
+```
+
+Run only the command for the selected runtime.
+The vLLM result must contain `127.0.0.1:8000`.
+The llama.cpp result must contain `127.0.0.1:8081`.
+
+If installation stops after a model download, rerun the same installer command.
+The runtime reuses only an artifact that passes its recorded identity checks.
+If Docker reports a container-name or network-name conflict, inspect the resource labels before removing anything.
+Do not remove a resource that lacks the NemoClaw ownership label for this profile.
+Refer to [Host Files and State](../../reference/host-files-and-state) before deleting a credential or cached artifact.
+
+When you intend to remove the entire NemoClaw installation, run `$$nemoclaw uninstall`.
+Full uninstall verifies the exact managed container and network ownership before it removes those resources and deletes their state.
+It preserves the managed llama.cpp model cache by default and preserves the shared Hugging Face cache used by vLLM.
+Add `--delete-models` only when you also accept deletion of the managed llama.cpp cache and NemoClaw-pulled Ollama models.
+If cleanup reports an ownership or Docker error, leave the state files in place, resolve the reported resource, and rerun uninstall.
+After a successful full uninstall, `docker container inspect` must report no object for the selected managed container name.
+For llama.cpp, `docker network inspect nemoclaw-llama-cpp-internal` must also report no object.
+
 ## Choose NVIDIA NIM
 
 Choose NVIDIA NIM when you want a managed NIM container and your host has a NIM-capable NVIDIA GPU.

docs/inference/set-up-vllm.mdx

@@ -80,12 +80,45 @@ Without both `--enable-auto-tool-choice` and a matching parser, tool calls can a
 NemoClaw displays the **Install vLLM** or **Start vLLM** entry by default on DGX Spark and DGX Station.
 Generic Linux NVIDIA GPU hosts require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm` before the managed entry appears.
 
+### Discover Serving Profiles
+
+List the serving profiles installed with NemoClaw before you select a managed inference configuration.
+
+```bash
+$$nemoclaw profiles list
+```
+
+The command evaluates the catalog against the current host without downloading a model or changing host, gateway, inference, or sandbox resources.
+Each entry includes a stable ID, display name, backend, model, topology, selection mode, support state, estimated downloads, and an incompatibility reason when applicable.
+Add `--json` when a script needs the same fields as structured output.
+
+### Select a Serving Profile
+
+Pass a compatible profile's stable ID to onboarding.
+
+```bash
+$$nemoclaw onboard --profile <profile-id>
+```
+
+The same profile selector works with interactive and non-interactive onboarding.
+NemoClaw rejects unknown, ambiguous, disabled, incompatible, or conflicting selections before image or model downloads begin.
+Before confirmation, the review screen shows the resolved profile and recipe IDs, model, immutable runtime image, support state, and estimated image and model downloads.
+Do not combine `--profile` with `NEMOCLAW_PROVIDER`, `NEMOCLAW_MODEL`, `NEMOCLAW_VLLM_MODEL`, `NEMOCLAW_MANAGED_CLUSTER_PEERS`, or `NEMOCLAW_VLLM_EXTRA_ARGS_JSON` overrides.
+If `NEMOCLAW_SERVING_PRESET` is already set, it must select the same stable profile ID; a different ID conflicts with `--profile`.
+
+The profile selector is model-independent, so a catalog can add profiles without adding model-specific CLI flags.
+Omitting `--profile` preserves the existing provider and model defaults.
+If onboarding is interrupted, `$$nemoclaw onboard --resume` reuses the recorded catalog, preset, and recipe digests.
+It exits before runtime effects if the installed catalog changed instead of silently switching the recipe; use `$$nemoclaw onboard --fresh --profile <profile-id>` to review and start with the current definition.
+Legacy sessions that predate profile provenance still resume with their original behavior, but you cannot add `--profile` to one of those in-progress sessions.
+
 In an interactive run, the managed path lists the supported model registry for your host profile.
 Press **Enter** to use the profile default or select another validated model with its registered `vllm serve` arguments.
 
 The single-host path pulls the vLLM image, downloads model weights into `~/.cache/huggingface`, and starts the `nemoclaw-vllm` container on `localhost:8000`.
 The distributed DGX pages document their separate container names, endpoints, and lifecycle checks.
-The container carries a NemoClaw ownership label so later onboarding runs can distinguish it from a bring-your-own server without trusting the container name alone.
+The container carries NemoClaw ownership and immutable catalog labels so later onboarding, recovery, and uninstall runs can distinguish it from a bring-your-own server without trusting the container name alone.
+NemoClaw also records an owner-only, credential-free runtime receipt that binds those labels to the exact container ID and API-key fingerprint.
 
 If an existing `nemoclaw-vllm` container does not carry that label, NemoClaw preserves it and asks you to remove or rename it before installing managed vLLM.
 If another vLLM server already occupies port `8000`, NemoClaw selects the existing-server path and applies the model-identity checks described above.