From 3bdfc92ff85edc9a2a904c460242ed3e75d1515f Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Wed, 11 Nov 2026 10:27:03 -0700 Subject: [PATCH 1/2] docs: list v1 changes since v0.1.0-rc9 and correct stale example claims --- docs/README.md | 2 +- docs/about/release-notes.md | 73 ++++++++++++++++++++++++- examples/gtc-dc/README.md | 2 +- examples/hcl/travel-team/README.md | 1 - examples/hcl/travel-team/WALKTHROUGH.md | 2 +- examples/spark/README.md | 2 +- examples/station/README.md | 2 +- 7 files changed, 76 insertions(+), 8 deletions(-) diff --git a/docs/README.md b/docs/README.md index 977a84fe055..f57642e7aed 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,7 +3,7 @@ # Documentation Index -These guides describe NemoClaw v1. The operational updates beyond the first-deployment tutorial reflect inspected implementation `origin/v1` at `86b8d94273a76a696e06b300dc29f7035b163667`; use a matched checkout and bundle when following them. The published [v1 field reference](references/v1-configuration.md) is a snapshot generated at that implementation revision. This checkout's [generator-owned reference](reference/configuration.md) has the same named-map configuration shape but differs on three optional field types; use the snapshot and schema from the bundle's source revision when checking field types. For the source-pinned first deployment, use the [tutorial](get-started/first-deployment.md). +These guides describe NemoClaw v1 at this checkout's revision; use a bundle built from the same revision when following them. This checkout's [generator-owned reference](reference/configuration.md) and schema match that revision. The published [v1 field reference](references/v1-configuration.md) is a snapshot generated at `86b8d94273a76a696e06b300dc29f7035b163667` and lacks later fields, such as `container.gpuDevices`; check fields against the reference and schema from the bundle's source revision. The [tutorial](get-started/first-deployment.md) pins its first deployment to that snapshot's revision. [Current limits](resources/limits.md) lists what v1 does not do yet or has not tested, with the issue tracking each. ## About diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index 3e583707c6f..6d612f3b496 100644 --- a/docs/about/release-notes.md +++ b/docs/about/release-notes.md @@ -12,13 +12,82 @@ The workspace package version alone does not establish that a release has been p The development branch provides desired-state YAML, a Rust SDK, the `onboard`/`plan`/`apply`/`export`/`destroy` CLI, and a bundled OpenTofu provider. Refer to [the overview](overview.md) for implemented boundaries and [the CLI reference](../references/cli.md) for commands. +### Changes Since v0.1.0-rc9 + +These changes reached `v1` after the `v0.1.0-rc9` tag; [breaking changes](#breaking-changes-and-migration) are listed separately. + +Agents and interfaces: + +- `harness.settings.interfaces` turns on OpenClaw's dashboard and Hermes's API server and dashboard; plan checks each against the image's adapter, and apply prints how to reach it, including OpenClaw's terminal UI command. See [agent interfaces](../agents-inference/interfaces.md#reach-an-agent-interface). +- A sandbox's `serviceExposures` publishes one of its ports at a URL the gateway serves; apply prints each URL and returns it as `serviceUrls` in JSON. See [service exposure](../agents-inference/interfaces.md#expose-a-service-through-the-gateway). +- Plan and apply list each agent's runtime ID and `fabric-agent-ctl invoke` command under **Agents**, and as `agents` in JSON results. See [invoking an agent](../agents-inference/interfaces.md#invoke-an-agent). +- OpenClaw and Hermes keep their native state in `/sandbox/artifacts/.fabric/state//`, which every runtime of the agent uses, so their interface tokens moved there. See [agent files](../build-deploy/state.md#agent-files). +- The Hermes image includes the API server, dashboard, and browser chat dependencies, and the Switchyard Relay plugin. +- Apply restarts an agent runtime that stopped in an unchanged sandbox. +- OpenClaw's startup has one 60-second deadline, instead of 30 seconds for each step. +- A failed agent start reports Fabric's cause. +- Hermes's `max_tokens` setting has no default, so Hermes uses its own response-token limit. +- OpenClaw stops where the sandbox denies process-group signals. +- An explicit sandbox policy accepts `network_middlewares`. See [network middleware](../security/sandbox-network.md#attach-network-middleware). + +Inference and models: + +- `container.gpuDevices` selects the GPU for a Docker-managed vLLM or Ollama service, by UUID or index; it takes one entry. See [container limits](../agents-inference/inference.md#set-container-limits-and-update-policy). +- `serving.tensorParallelSize` and `serving.pipelineParallelSize` set vLLM's parallel layout; both default to 1. See [the parallel layout](../agents-inference/models.md#set-the-parallel-layout). +- A service's GPU memory budget applies to each GPU it uses, and capacity errors name the GPU. +- On dedicated-memory GPUs, `memory.hostReserveGiB` can be as low as 6 GiB, and a vLLM recipe's GPU budget is checked against the GPU's memory. See [hardware profiles](../agents-inference/models.md#choose-a-hardware-profile). +- In hand-written HCL, the vLLM and Ollama capacity data sources take `gpu_devices`, and `vllm_runtime` and `ollama_runtime` take `gpu_count` and report it in `requirements`. See [service capacity](../references/provider.md#service-capacity). +- When vLLM exits during startup, the error includes the last 4 KiB of its output, with the service key redacted. +- Plan rejects `maxTokens`, `temperature`, and `topP` when the image's adapter doesn't accept them. See [OpenClaw route tuning](../agents-inference/inference.md#tune-openclaws-primary-route). + +Gateways and Kubernetes: + +- An external gateway's `gateway.tls` can name a CA alone; a client certificate and key must appear together. +- `gateway.kubernetes.kubeconfig` and `context` are optional; without them, NemoClaw uses the service account of the pod it runs in. See [running NemoClaw in a pod](../build-deploy/kubernetes.md#run-nemoclaw-in-a-pod). +- `gateway.kubernetes.namespace` can name an existing namespace: NemoClaw binds it by UID and never labels, changes, or deletes it, and refuses a namespace that another deployment created or that is being deleted. +- A managed OpenShift gateway lets OpenShift assign its UID and `fsGroup`. +- A managed Kubernetes or OpenShift gateway's Helm install is atomic; a release left by an unfinished install fails apply with the `helm uninstall` command to run. See [recovering an unfinished Helm install](../build-deploy/usage.md#recover-from-an-unfinished-helm-install). +- Plan fails when a managed Docker or Podman gateway's subnet or port is already in use. + +Plan, apply, and diagnostics: + +- The first interrupt lets the resource operations in progress finish; a second stops at once. See [recovering an interrupted operation](../build-deploy/usage.md#recover-an-interrupted-operation). +- Refusals name the object or setting: an ownership conflict, retained gateway storage from another state directory, a missing kubeconfig context, an image metadata bundle for another digest, and gateway TLS failures. +- The sandbox deletion warning ends with "except on mounted volumes". +- Adding a sandbox whose name sorts first leaves the other sandboxes unchanged. +- Progress no longer shows a "Creating infrastructure state" step. +- `metadata.uid` accepts uppercase hexadecimal digits. + +Onboarding: + +- `nemoclaw onboard` offers OpenClaw and Hermes, saves only the values you chose, and leaves the rest for plan to fill. +- It doesn't ask for settings it can decide, such as a named vendor's API, the only engine that answered, or the network tier; the review shows why a value can't be saved and whether each credential is set. +- Saving prints the `plan` and `apply` commands, and the page that issues a hosted provider's key. +- The Nous Research preset names `NOUS_API_KEY`. + +Examples and builds: + +- New examples: [an application container beside an agent](../../examples/application-container.yaml) and [GPU autoscaling on Kubernetes](../../examples/kubernetes/gpu-autoscaling/README.md). +- The [GTC DC](../../examples/gtc-dc/README.md) Kubernetes profile runs one OpenClaw and one Hermes agent on a managed gateway, in YAML or HCL, and keeps their files on PVCs; the local templates allow 8,192 output tokens. +- Run `cargo images fetch` before a direct `docker buildx bake` build of an agent or Ollama image. See [building images](../build-deploy/build.md). +- Dependency pins take security fixes, including rustls, webpki, tokio, and zip. +- Pinned components: OpenShell 0.1.7, OpenTofu 1.12.12, Ollama 0.40.14, Hermes Agent v0.22.5, and OpenClaw 2026.9.34. + ## Breaking Changes and Migration Earlier CLI commands, schemas, and state formats have no compatibility guarantees. See [migration](../get-started/migration.md) for where each earlier task lives now, and [state](../build-deploy/state.md) for data preservation. -Recent development changes that affect existing deployments: +Changes since the `v0.1.0-rc9` tag that affect existing deployments or documents: + +- The intent record is now version 20; `v0.1.0-rc9` wrote version 15, and the record moved to 16, 17, 18, 19, and 20 as later changes altered it. This release refuses every deployment that an earlier build created, without changing its state. Destroy each one with the bundle that created it, then create it again with this release; see [compatibility](../references/compatibility.md#deployment-state). +- `spec.sandboxes`, `spec.inferenceProviders`, and a sandbox's `inferenceProviders` are maps keyed by name; the parser rejects the earlier lists. A provider declared inline on a route still takes `name`. In the Rust SDK, these fields are `BTreeMap`s, and `InferenceProvider` has no `name`. +- `compatibility.gpuCount` is removed from vLLM recipes; the parser rejects it as an unknown field. Use `serving.tensorParallelSize` and `serving.pipelineParallelSize`. +- In `skills.paths` for OpenClaw and Hermes, a folder with a `SKILL.md` is one skill, and otherwise each direct subfolder with one is a skill. A folder without skills adds none, and a missing path or a duplicate skill name fails the agent's start. Hermes no longer loads skills more than one folder deep, and no longer skips a missing path. See [skills on a mounted volume](../agents-inference/agents.md#skills-on-a-mounted-volume). +- An endpoint must begin with its scheme and `://`. Endpoints and service addresses can't name a cloud metadata host, such as `metadata` or `fd00:ec2::254`, or an IPv6 address that embeds an IPv4 address. A `networkCIDR` must be in canonical form, without leading zeros. +- In hand-written HCL, `openshell_kubernetes_auth` has no `gateway_values` attribute, and a `vllm_runtime` recipe has no `gpu_count`. + +Earlier changes that affect existing deployments: -- The intent record is now version 20, so this release refuses every deployment that an earlier build created, without changing its state. Destroy each one with the bundle that created it, then create it again with this release; see [compatibility](../references/compatibility.md#deployment-state). - Docker-managed vLLM and Ollama services default to [`updatePolicy: Preserve`](../agents-inference/inference.md#set-container-limits-and-update-policy), which refuses an image, model, serving, or container-limit change that would replace a running container; set `spec.services..updatePolicy: Recreate` to permit the replacement and its downtime. - `spec.gateway.image` is removed: the SDK pins the managed gateway image, and defaulted and exported documents no longer name it. - Remove the field from documents; the parser rejects it as an unknown field. diff --git a/examples/gtc-dc/README.md b/examples/gtc-dc/README.md index 26c485f2718..8fc11116b8b 100644 --- a/examples/gtc-dc/README.md +++ b/examples/gtc-dc/README.md @@ -36,7 +36,7 @@ KV and SSM cache dtypes use runtime defaults; model output accuracy and tool cal Ubuntu 24.04 is the assumed Linux environment, including the WSL2 distribution. Use [the build prerequisites](../../docs/build-deploy/build.md), Docker with NVIDIA GPU access and the containerd image store, and driver major 580 or newer. -Each target requires exactly one visible NVIDIA GPU; these configurations provide neither CPU offloading nor multi-GPU serving. +Each model container must see exactly one NVIDIA GPU; on a host with more, set the service's [`container.gpuDevices`](../../docs/agents-inference/inference.md#set-container-limits-and-update-policy) to the target GPU. These configurations provide neither CPU offloading nor multi-GPU serving. | Target | Hardware requirement | Memory accounting | |---|---|---| diff --git a/examples/hcl/travel-team/README.md b/examples/hcl/travel-team/README.md index 2503940f5e3..89728d9fc31 100644 --- a/examples/hcl/travel-team/README.md +++ b/examples/hcl/travel-team/README.md @@ -85,7 +85,6 @@ The team needs a few things NemoClaw and its components don't provide yet: - Agents don't call one another directly: a person or script passes results between them ([#13311](https://github.com/NVIDIA/NemoClaw/issues/13311), [#13312](https://github.com/NVIDIA/NemoClaw/issues/13312)). - The approval step happens outside the agents ([#13314](https://github.com/NVIDIA/NemoClaw/issues/13314)). - The booking service receives no key yet ([#13313](https://github.com/NVIDIA/NemoClaw/issues/13313)). -- The scheduler runs Hermes rather than Deep Agents, whose adapter can't turn a model's reasoning off ([NVIDIA/NeMo-Fabric#433](https://github.com/NVIDIA/NeMo-Fabric/issues/433)). - Each invocation must finish within `fabric-agent-ctl`'s 320-second deadline, which bounds how much one agent can do per call. ## Tried Live diff --git a/examples/hcl/travel-team/WALKTHROUGH.md b/examples/hcl/travel-team/WALKTHROUGH.md index fb7713be8b4..5e1b80c3bfc 100644 --- a/examples/hcl/travel-team/WALKTHROUGH.md +++ b/examples/hcl/travel-team/WALKTHROUGH.md @@ -196,7 +196,7 @@ roles = merge( This table describes the team. Grants, registrations, sandboxes, and agents are all derived from it, so adding a researcher means adding one entry to `local.researchers`. -Every role runs Hermes; Fabric's Deep Agents adapter can't turn a model's reasoning off yet ([NVIDIA/NeMo-Fabric#433](https://github.com/NVIDIA/NeMo-Fabric/issues/433)), and a reasoning model there can't finish within Fabric's 320-second invocation deadline. +Every role runs Hermes. ```hcl binaries = { for role, harness in data.fabric_harness.agent : role => jsondecode(harness.launch_json).binaries } diff --git a/examples/spark/README.md b/examples/spark/README.md index f6f05316591..11bd49e131e 100644 --- a/examples/spark/README.md +++ b/examples/spark/README.md @@ -17,7 +17,7 @@ The new scenarios use managed Docker gateways and authenticated vLLM services. | [two-models.yaml](two-models.yaml) | Pi with Qwen3-4B and Qwen3.6-27B NVFP4 | Fast/smart route selection with two independently managed services | | [local-and-hosted.yaml](local-and-hosted.yaml) | OpenClaw with local Qwen3.8-27B NVFP4 and an operator-selected hosted model | Managed local inference plus a hosted model; the local route is the default | | [vllm.yaml](vllm.yaml) | OpenClaw with Qwen3-4B | The original ordinary-vLLM example | -| [remote-vllm.yaml](remote-vllm.yaml) | OpenClaw with SSH-managed Qwen3-4B and an external Podman gateway | Separate sandbox and model engines; the current OpenShell Podman pin has the [TLS initialization blocker](https://github.com/NVIDIA/OpenShell/issues/3427) | +| [remote-vllm.yaml](remote-vllm.yaml) | OpenClaw with SSH-managed Qwen3-4B and an external Podman gateway | Separate sandbox and model engines; Podman with a remote model service is [untested](../../docs/resources/limits.md#platforms-models-and-placement) | The Deep Agents researcher has `tools.allow: [read]`; the writer retains the harness's default tools. Each agent receives its own sandbox, workspace, and artifact directory. diff --git a/examples/station/README.md b/examples/station/README.md index 2b9d9bba41b..4685e70fa05 100644 --- a/examples/station/README.md +++ b/examples/station/README.md @@ -15,7 +15,7 @@ These examples cover their exact combinations and do not qualify other DGX Stati ## Check the Host The host must provide Ubuntu 24.04, ARM64, one NVIDIA GB300 with compute capability 10.3, driver major 580 or newer, and Docker with the containerd image store enabled. -The `dgx-station` profile requires observable dedicated GPU-memory counters and rejects additional visible GPUs. +The `dgx-station` profile requires observable dedicated GPU-memory counters and exactly one GPU visible in the model container; on a Station with another GPU, set the service's [`container.gpuDevices`](../../docs/agents-inference/inference.md#set-container-limits-and-update-policy) to the GB300. Confirm that the selected example's gateway and inference ports are unused and that its gateway CIDR does not overlap a host route or Docker network. Stop or resize only workloads you own before reserving GPU capacity. From 362c75fcaf6080f28f4da0bf7cadc4d65a898536 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Wed, 11 Nov 2026 10:41:35 -0700 Subject: [PATCH 2/2] docs: correct the release notes' breaking changes against v0.1.0-rc9 Drop entries for fields that v0.1.0-rc9 never had, add the recipe GPU check, model-tuning, Hermes max_tokens, and Kubernetes receipt breaks, split sentences onto their own lines, leave docs/README.md to #14412, and link the travel team's booking-key gap to #14417. --- docs/README.md | 2 +- docs/about/release-notes.md | 77 ++++++++++++++++------- examples/gtc-dc/README.md | 3 +- examples/hcl/travel-team/README.md | 4 +- examples/hcl/travel-team/WALKTHROUGH.md | 2 +- examples/hcl/travel-team/registrations.tf | 2 +- 6 files changed, 60 insertions(+), 30 deletions(-) diff --git a/docs/README.md b/docs/README.md index f57642e7aed..977a84fe055 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,7 +3,7 @@ # Documentation Index -These guides describe NemoClaw v1 at this checkout's revision; use a bundle built from the same revision when following them. This checkout's [generator-owned reference](reference/configuration.md) and schema match that revision. The published [v1 field reference](references/v1-configuration.md) is a snapshot generated at `86b8d94273a76a696e06b300dc29f7035b163667` and lacks later fields, such as `container.gpuDevices`; check fields against the reference and schema from the bundle's source revision. The [tutorial](get-started/first-deployment.md) pins its first deployment to that snapshot's revision. +These guides describe NemoClaw v1. The operational updates beyond the first-deployment tutorial reflect inspected implementation `origin/v1` at `86b8d94273a76a696e06b300dc29f7035b163667`; use a matched checkout and bundle when following them. The published [v1 field reference](references/v1-configuration.md) is a snapshot generated at that implementation revision. This checkout's [generator-owned reference](reference/configuration.md) has the same named-map configuration shape but differs on three optional field types; use the snapshot and schema from the bundle's source revision when checking field types. For the source-pinned first deployment, use the [tutorial](get-started/first-deployment.md). [Current limits](resources/limits.md) lists what v1 does not do yet or has not tested, with the issue tracking each. ## About diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index 6d612f3b496..7e5c6526b7f 100644 --- a/docs/about/release-notes.md +++ b/docs/about/release-notes.md @@ -18,58 +18,73 @@ These changes reached `v1` after the `v0.1.0-rc9` tag; [breaking changes](#break Agents and interfaces: -- `harness.settings.interfaces` turns on OpenClaw's dashboard and Hermes's API server and dashboard; plan checks each against the image's adapter, and apply prints how to reach it, including OpenClaw's terminal UI command. See [agent interfaces](../agents-inference/interfaces.md#reach-an-agent-interface). -- A sandbox's `serviceExposures` publishes one of its ports at a URL the gateway serves; apply prints each URL and returns it as `serviceUrls` in JSON. See [service exposure](../agents-inference/interfaces.md#expose-a-service-through-the-gateway). -- Plan and apply list each agent's runtime ID and `fabric-agent-ctl invoke` command under **Agents**, and as `agents` in JSON results. See [invoking an agent](../agents-inference/interfaces.md#invoke-an-agent). -- OpenClaw and Hermes keep their native state in `/sandbox/artifacts/.fabric/state//`, which every runtime of the agent uses, so their interface tokens moved there. See [agent files](../build-deploy/state.md#agent-files). +- `harness.settings.interfaces` turns on OpenClaw's dashboard and Hermes's API server and dashboard; plan checks each against the image's adapter, and apply prints how to reach it, including OpenClaw's terminal UI command. + See [agent interfaces](../agents-inference/interfaces.md#reach-an-agent-interface). +- A sandbox's `serviceExposures` publishes one of its ports at a URL the gateway serves; apply prints each URL and returns it as `serviceUrls` in JSON. + See [service exposure](../agents-inference/interfaces.md#expose-a-service-through-the-gateway). +- Plan and apply list each agent's runtime ID and `fabric-agent-ctl invoke` command under **Agents**, and as `agents` in JSON results. + See [invoking an agent](../agents-inference/interfaces.md#invoke-an-agent). +- OpenClaw and Hermes keep their native state in `/sandbox/artifacts/.fabric/state//`, which every runtime of the agent uses, so their interface tokens moved there. + See [agent files](../build-deploy/state.md#agent-files). - The Hermes image includes the API server, dashboard, and browser chat dependencies, and the Switchyard Relay plugin. - Apply restarts an agent runtime that stopped in an unchanged sandbox. - OpenClaw's startup has one 60-second deadline, instead of 30 seconds for each step. - A failed agent start reports Fabric's cause. -- Hermes's `max_tokens` setting has no default, so Hermes uses its own response-token limit. - OpenClaw stops where the sandbox denies process-group signals. -- An explicit sandbox policy accepts `network_middlewares`. See [network middleware](../security/sandbox-network.md#attach-network-middleware). +- An explicit sandbox policy accepts `network_middlewares`. + See [network middleware](../security/sandbox-network.md#attach-network-middleware). Inference and models: -- `container.gpuDevices` selects the GPU for a Docker-managed vLLM or Ollama service, by UUID or index; it takes one entry. See [container limits](../agents-inference/inference.md#set-container-limits-and-update-policy). -- `serving.tensorParallelSize` and `serving.pipelineParallelSize` set vLLM's parallel layout; both default to 1. See [the parallel layout](../agents-inference/models.md#set-the-parallel-layout). +- `container.gpuDevices` selects the GPU for a Docker-managed vLLM or Ollama service, by UUID or index; it takes one entry. + See [container limits](../agents-inference/inference.md#set-container-limits-and-update-policy). +- `serving.tensorParallelSize` and `serving.pipelineParallelSize` set vLLM's parallel layout; see [the parallel layout](../agents-inference/models.md#set-the-parallel-layout). + Until `container.gpuDevices` takes more than one GPU, vLLM refuses a layout larger than one GPU; see [current limits](../resources/limits.md#platforms-models-and-placement). - A service's GPU memory budget applies to each GPU it uses, and capacity errors name the GPU. -- On dedicated-memory GPUs, `memory.hostReserveGiB` can be as low as 6 GiB, and a vLLM recipe's GPU budget is checked against the GPU's memory. See [hardware profiles](../agents-inference/models.md#choose-a-hardware-profile). -- In hand-written HCL, the vLLM and Ollama capacity data sources take `gpu_devices`, and `vllm_runtime` and `ollama_runtime` take `gpu_count` and report it in `requirements`. See [service capacity](../references/provider.md#service-capacity). -- When vLLM exits during startup, the error includes the last 4 KiB of its output, with the service key redacted. -- Plan rejects `maxTokens`, `temperature`, and `topP` when the image's adapter doesn't accept them. See [OpenClaw route tuning](../agents-inference/inference.md#tune-openclaws-primary-route). +- On dedicated-memory GPUs, `memory.hostReserveGiB` can be as low as 6 GiB, and a vLLM recipe's GPU budget is checked against the GPU's memory. + See [hardware profiles](../agents-inference/models.md#choose-a-hardware-profile). +- In hand-written HCL, the vLLM and Ollama capacity data sources take `gpu_devices`, and `vllm_runtime` and `ollama_runtime` take `gpu_count`, which must be 1 for now, and report it in `requirements`. + See [service capacity](../references/provider.md#service-capacity). +- When vLLM exits during startup, the apply error includes the last 4 KiB of its output, with the service key redacted; an Ollama runtime's stop detail, such as a memory protection stop, also appears in its apply error. Gateways and Kubernetes: - An external gateway's `gateway.tls` can name a CA alone; a client certificate and key must appear together. -- `gateway.kubernetes.kubeconfig` and `context` are optional; without them, NemoClaw uses the service account of the pod it runs in. See [running NemoClaw in a pod](../build-deploy/kubernetes.md#run-nemoclaw-in-a-pod). +- `gateway.kubernetes.kubeconfig` and `context` can be omitted together; without them, NemoClaw uses the service account of the pod it runs in. + See [running NemoClaw in a pod](../build-deploy/kubernetes.md#run-nemoclaw-in-a-pod). - `gateway.kubernetes.namespace` can name an existing namespace: NemoClaw binds it by UID and never labels, changes, or deletes it, and refuses a namespace that another deployment created or that is being deleted. +- NemoClaw no longer reads cluster-wide objects: it doesn't check for a default StorageClass, the Agent Sandbox CRD, or `kube-system`. + Without a default StorageClass, the gateway install times out in Helm's wait. - A managed OpenShift gateway lets OpenShift assign its UID and `fsGroup`. -- A managed Kubernetes or OpenShift gateway's Helm install is atomic; a release left by an unfinished install fails apply with the `helm uninstall` command to run. See [recovering an unfinished Helm install](../build-deploy/usage.md#recover-from-an-unfinished-helm-install). +- A managed Kubernetes or OpenShift gateway's Helm install is atomic; a release left by an unfinished install fails apply with the `helm uninstall` command to run. + See [recovering an unfinished Helm install](../build-deploy/usage.md#recover-from-an-unfinished-helm-install). - Plan fails when a managed Docker or Podman gateway's subnet or port is already in use. Plan, apply, and diagnostics: -- The first interrupt lets the resource operations in progress finish; a second stops at once. See [recovering an interrupted operation](../build-deploy/usage.md#recover-an-interrupted-operation). +- The first interrupt lets the resource operations in progress finish; a second stops at once. + See [recovering an interrupted operation](../build-deploy/usage.md#recover-an-interrupted-operation). - Refusals name the object or setting: an ownership conflict, retained gateway storage from another state directory, a missing kubeconfig context, an image metadata bundle for another digest, and gateway TLS failures. - The sandbox deletion warning ends with "except on mounted volumes". - Adding a sandbox whose name sorts first leaves the other sandboxes unchanged. -- Progress no longer shows a "Creating infrastructure state" step. - `metadata.uid` accepts uppercase hexadecimal digits. Onboarding: - `nemoclaw onboard` offers OpenClaw and Hermes, saves only the values you chose, and leaves the rest for plan to fill. - It doesn't ask for settings it can decide, such as a named vendor's API, the only engine that answered, or the network tier; the review shows why a value can't be saved and whether each credential is set. -- Saving prints the `plan` and `apply` commands, and the page that issues a hosted provider's key. +- Saving prints the `nemoclaw plan` and `nemoclaw apply` commands with the saved path. +- The review explains how to set an unset credential and, for a hosted provider, names the page that issues its key. - The Nous Research preset names `NOUS_API_KEY`. Examples and builds: - New examples: [an application container beside an agent](../../examples/application-container.yaml) and [GPU autoscaling on Kubernetes](../../examples/kubernetes/gpu-autoscaling/README.md). - The [GTC DC](../../examples/gtc-dc/README.md) Kubernetes profile runs one OpenClaw and one Hermes agent on a managed gateway, in YAML or HCL, and keeps their files on PVCs; the local templates allow 8,192 output tokens. -- Run `cargo images fetch` before a direct `docker buildx bake` build of an agent or Ollama image. See [building images](../build-deploy/build.md). +- Linux bundles are built on Ubuntu 22.04 and need glibc 2.35 or newer; Ubuntu 22.04 is the oldest supported Linux. + See [prerequisites](../get-started/prerequisites.md). +- Run `cargo images fetch` before a direct `docker buildx bake` build of an agent or Ollama image. + See [building images](../build-deploy/build.md). - Dependency pins take security fixes, including rustls, webpki, tokio, and zip. - Pinned components: OpenShell 0.1.7, OpenTofu 1.12.12, Ollama 0.40.14, Hermes Agent v0.22.5, and OpenClaw 2026.9.34. @@ -79,12 +94,26 @@ Earlier CLI commands, schemas, and state formats have no compatibility guarantee See [migration](../get-started/migration.md) for where each earlier task lives now, and [state](../build-deploy/state.md) for data preservation. Changes since the `v0.1.0-rc9` tag that affect existing deployments or documents: -- The intent record is now version 20; `v0.1.0-rc9` wrote version 15, and the record moved to 16, 17, 18, 19, and 20 as later changes altered it. This release refuses every deployment that an earlier build created, without changing its state. Destroy each one with the bundle that created it, then create it again with this release; see [compatibility](../references/compatibility.md#deployment-state). -- `spec.sandboxes`, `spec.inferenceProviders`, and a sandbox's `inferenceProviders` are maps keyed by name; the parser rejects the earlier lists. A provider declared inline on a route still takes `name`. In the Rust SDK, these fields are `BTreeMap`s, and `InferenceProvider` has no `name`. -- `compatibility.gpuCount` is removed from vLLM recipes; the parser rejects it as an unknown field. Use `serving.tensorParallelSize` and `serving.pipelineParallelSize`. -- In `skills.paths` for OpenClaw and Hermes, a folder with a `SKILL.md` is one skill, and otherwise each direct subfolder with one is a skill. A folder without skills adds none, and a missing path or a duplicate skill name fails the agent's start. Hermes no longer loads skills more than one folder deep, and no longer skips a missing path. See [skills on a mounted volume](../agents-inference/agents.md#skills-on-a-mounted-volume). -- An endpoint must begin with its scheme and `://`. Endpoints and service addresses can't name a cloud metadata host, such as `metadata` or `fd00:ec2::254`, or an IPv6 address that embeds an IPv4 address. A `networkCIDR` must be in canonical form, without leading zeros. -- In hand-written HCL, `openshell_kubernetes_auth` has no `gateway_values` attribute, and a `vllm_runtime` recipe has no `gpu_count`. +- The intent record is now version 20. + `v0.1.0-rc9` wrote version 15, and the record moved to 16, 17, 18, 19, and 20 as later changes altered it. + This release refuses any deployment whose intent record is an earlier version, including every one that `v0.1.0-rc9` created, without changing its state. + Destroy each one with the bundle that created it, then create it again with this release; see [compatibility](../references/compatibility.md#deployment-state). +- `spec.sandboxes`, `spec.inferenceProviders`, and a sandbox's `inferenceProviders` are maps keyed by name; the parser rejects the earlier lists. + A provider declared inline on a route still takes `name`. + In the Rust SDK, these fields are `BTreeMap`s, and `InferenceProvider` has no `name`. +- A vLLM recipe whose `compatibility.gpu` belongs to no hardware profile's GPU family no longer parses. +- Plan rejects `maxTokens`, `temperature`, and `topP` when the image's adapter doesn't accept them; see [OpenClaw route tuning](../agents-inference/inference.md#tune-openclaws-primary-route). +- Hermes's `max_tokens` setting no longer defaults to 512, so Hermes uses its own response-token limit. +- In `skills.paths` for OpenClaw and Hermes, a folder with a `SKILL.md` is one skill, and otherwise each direct subfolder with one is a skill. + A folder without skills adds none, and a missing path or a duplicate skill name fails the agent's start. + Hermes no longer loads skills more than one folder deep, and no longer skips a missing path. + See [skills on a mounted volume](../agents-inference/agents.md#skills-on-a-mounted-volume). +- An endpoint must begin with its scheme and `://`. + Endpoints and service addresses can't name a cloud metadata host, such as `metadata` or `fd00:ec2::254`, or an IPv6 address that embeds an IPv4 address. + A `networkCIDR` must be in canonical form, without leading zeros. +- In hand-written HCL, `openshell_kubernetes_auth` has no `gateway_values` attribute. +- In hand-written HCL on Kubernetes or OpenShift, the gateway ownership receipts that `v0.1.0-rc9` wrote no longer load, and the intent record refusal above doesn't cover them. + Destroy such a deployment with the bundle that created it, then create it again with this release. Earlier changes that affect existing deployments: diff --git a/examples/gtc-dc/README.md b/examples/gtc-dc/README.md index 8fc11116b8b..455de1375d8 100644 --- a/examples/gtc-dc/README.md +++ b/examples/gtc-dc/README.md @@ -36,7 +36,8 @@ KV and SSM cache dtypes use runtime defaults; model output accuracy and tool cal Ubuntu 24.04 is the assumed Linux environment, including the WSL2 distribution. Use [the build prerequisites](../../docs/build-deploy/build.md), Docker with NVIDIA GPU access and the containerd image store, and driver major 580 or newer. -Each model container must see exactly one NVIDIA GPU; on a host with more, set the service's [`container.gpuDevices`](../../docs/agents-inference/inference.md#set-container-limits-and-update-policy) to the target GPU. These configurations provide neither CPU offloading nor multi-GPU serving. +Each model container must see exactly one NVIDIA GPU; on a host with more, set the service's [`container.gpuDevices`](../../docs/agents-inference/inference.md#set-container-limits-and-update-policy) to the target GPU. +These configurations provide neither CPU offloading nor multi-GPU serving. | Target | Hardware requirement | Memory accounting | |---|---|---| diff --git a/examples/hcl/travel-team/README.md b/examples/hcl/travel-team/README.md index 89728d9fc31..b13b0cb5ca9 100644 --- a/examples/hcl/travel-team/README.md +++ b/examples/hcl/travel-team/README.md @@ -39,7 +39,7 @@ The researchers use a fast local model, and the scheduler and buyer use a hosted 2. Set the variables in `terraform.tfvars`: at least `docker_host`, `gateway_endpoint`, `images`, `image_engine`, `ollama_image`, and `local_model`. 3. Export the keys the registrations name, which OpenShell reads during apply: by default `NVIDIA_API_KEY` for the hosted model, `BRAVE_API_KEY` for web search, and `BOOKINGS_API_KEY` for the booking service. Sandboxes see a placeholder in place of each key, and OpenShell puts the key into requests that carry the placeholder, so agents never see the keys. - Hermes doesn't send the booking key's placeholder to MCP servers yet, so the booking service receives no key ([#13313](https://github.com/NVIDIA/NemoClaw/issues/13313)). + Hermes doesn't send the booking key's placeholder to MCP servers yet, so the booking service receives no key ([#14417](https://github.com/NVIDIA/NemoClaw/issues/14417)). 4. Run `tofu init` and `tofu apply`. Hosted providers retire model names over time. If the scheduler or buyer fails with HTTP 404 or 410 from the hosted model, list the models your endpoint and key can use (`GET /v1/models`, then try one) and set `frontier.model`. @@ -84,7 +84,7 @@ The team needs a few things NemoClaw and its components don't provide yet: - Agents don't call one another directly: a person or script passes results between them ([#13311](https://github.com/NVIDIA/NemoClaw/issues/13311), [#13312](https://github.com/NVIDIA/NemoClaw/issues/13312)). - The approval step happens outside the agents ([#13314](https://github.com/NVIDIA/NemoClaw/issues/13314)). -- The booking service receives no key yet ([#13313](https://github.com/NVIDIA/NemoClaw/issues/13313)). +- The booking service receives no key yet ([#14417](https://github.com/NVIDIA/NemoClaw/issues/14417)). - Each invocation must finish within `fabric-agent-ctl`'s 320-second deadline, which bounds how much one agent can do per call. ## Tried Live diff --git a/examples/hcl/travel-team/WALKTHROUGH.md b/examples/hcl/travel-team/WALKTHROUGH.md index 5e1b80c3bfc..af000452191 100644 --- a/examples/hcl/travel-team/WALKTHROUGH.md +++ b/examples/hcl/travel-team/WALKTHROUGH.md @@ -145,7 +145,7 @@ resource "openshell_api" "bookings" { This registers the booking service's key for the buyer's executables only. OpenShell puts the key into a request in place of its placeholder, so the agent never sees the key itself. -Hermes doesn't send that placeholder to MCP servers yet, so for now the service receives no key; [#13313](https://github.com/NVIDIA/NemoClaw/issues/13313) tracks it. +Hermes doesn't send that placeholder to MCP servers yet, so for now the service receives no key; [#14417](https://github.com/NVIDIA/NemoClaw/issues/14417) tracks it. ## `policies.tf`: Network Grants diff --git a/examples/hcl/travel-team/registrations.tf b/examples/hcl/travel-team/registrations.tf index 7680b8eeaca..71678284dc1 100644 --- a/examples/hcl/travel-team/registrations.tf +++ b/examples/hcl/travel-team/registrations.tf @@ -52,7 +52,7 @@ resource "openshell_web_search" "research" { # The booking service's API key, attached to the buyer only. OpenShell puts it # into a request in place of its placeholder, so the agent never sees the key. # Hermes doesn't send the placeholder to MCP servers yet, so the service -# receives no key until it does (NVIDIA/NemoClaw#13313). +# receives no key until it does (NVIDIA/NemoClaw#14417). resource "openshell_api" "bookings" { gateway = local.gateway workspace = openshell_workspace.team.ref