From 8ee4c4f72bfe4397afa600ae79ccaf0d1d1481cc Mon Sep 17 00:00:00 2001 From: Glenn-Agent Date: Tue, 16 Jun 2026 13:24:47 +0530 Subject: [PATCH] docs: clarify legacy k3s sandbox resources Signed-off-by: Glenn-Agent --- docs/reference/architecture.mdx | 8 +++++++- docs/reference/commands-nemohermes.mdx | 1 + docs/reference/commands.mdx | 1 + 3 files changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/reference/architecture.mdx b/docs/reference/architecture.mdx index b13e20a93cc..3247286e364 100644 --- a/docs/reference/architecture.mdx +++ b/docs/reference/architecture.mdx @@ -85,7 +85,13 @@ On Apple Silicon macOS, NemoClaw starts the OpenShell Docker-driver gateway and In both Docker-driver modes, the sandbox is a Docker container, not a Kubernetes pod. The in-container `/tmp/nemoclaw-gateway-local` marker is written only by the entrypoint path that actually launches `openclaw gateway run`; NemoClaw does not treat sandbox environment hints such as `OPENSHELL_DRIVERS` as authoritative for dashboard-gateway ownership. -Legacy non-Docker-driver installs still use the k3s-based gateway path; the diagram below shows the standard Docker-driver topology. +Legacy non-Docker-driver installs still use the k3s-based gateway path. +In that topology, the `openshell-cluster-nemoclaw` container runs an embedded k3s cluster that includes the OpenShell gateway, an `agent-sandbox-controller` workload, and a Kubernetes custom resource definition named `sandboxes.agents.x-k8s.io`. +Each NemoClaw sandbox appears as a `Sandbox` custom resource in the `openshell` namespace, and the controller reconciles that resource into the corresponding agent pod. +For example, `kubectl get sandboxes.agents.x-k8s.io -n openshell` inside the legacy cluster container lists the sandbox resources, and `kubectl describe pod -n openshell ` reports `Controlled By: Sandbox/`. +That Kubernetes resource path is a legacy implementation detail of the non-Docker-driver gateway; it is not present in the default Docker-driver topology. + +The diagram below shows the standard Docker-driver topology. ```mermaid graph TB diff --git a/docs/reference/commands-nemohermes.mdx b/docs/reference/commands-nemohermes.mdx index 0f60d3464f9..e98868fad11 100644 --- a/docs/reference/commands-nemohermes.mdx +++ b/docs/reference/commands-nemohermes.mdx @@ -804,6 +804,7 @@ The classifications are `blocked-by-policy`, `missing-approval`, `unsupported`, Add a host alias to the sandbox pod template. Use this when a sandbox needs a stable LAN-only name, such as a local SearXNG or internal model endpoint, without dropping to `docker exec` and `kubectl patch`. Host alias commands use the legacy Kubernetes gateway `Sandbox` resource path. +In that older topology, the `openshell-cluster-nemoclaw` container runs an embedded k3s cluster with a `sandboxes.agents.x-k8s.io` custom resource definition, and an `agent-sandbox-controller` reconciles each `Sandbox` resource into the agent pod. They are not supported on Docker-driver or VM-driver sandboxes because those drivers do not run the gateway cluster container that owns this resource. ```bash diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx index 268a2d55714..6c278722fc3 100644 --- a/docs/reference/commands.mdx +++ b/docs/reference/commands.mdx @@ -1039,6 +1039,7 @@ The classifications are `blocked-by-policy`, `missing-approval`, `unsupported`, Add a host alias to the sandbox pod template. Use this when a sandbox needs a stable LAN-only name, such as a local SearXNG or internal model endpoint, without dropping to `docker exec` and `kubectl patch`. Host alias commands use the legacy Kubernetes gateway `Sandbox` resource path. +In that older topology, the `openshell-cluster-nemoclaw` container runs an embedded k3s cluster with a `sandboxes.agents.x-k8s.io` custom resource definition, and an `agent-sandbox-controller` reconciles each `Sandbox` resource into the agent pod. They are not supported on Docker-driver or VM-driver sandboxes because those drivers do not run the gateway cluster container that owns this resource. ```bash