Skip to content

docs: clarify legacy k3s sandbox resources #5506

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
apurvvkumaria merged 4 commits into from
Jul 9, 2026
Merged

docs: clarify legacy k3s sandbox resources #5506

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8ee4c4f
docs: clarify legacy k3s sandbox resources
glenn-agent Jun 16, 2026
0fc7bd7
merge(docs): refresh legacy k3s guidance
apurvvkumaria Jul 8, 2026
eec7281
merge(docs): sync legacy k3s guidance with main
apurvvkumaria Jul 8, 2026
59ef317
merge(main): sync PR #5506 with latest main
cv Jul 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion docs/reference/architecture.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,13 @@ In both Docker-driver modes, the sandbox is a Docker container, not a Kubernetes
The in-container `/tmp/nemoclaw-gateway-local` marker is written only by entrypoint paths that actually launch an in-container gateway.
Terminal runtimes may not write it.
NemoClaw does not treat sandbox environment hints such as `OPENSHELL_DRIVERS` as authoritative for 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 <sandbox-pod>` reports `Controlled By: Sandbox/<name>`.
That Kubernetes resource path is a legacy implementation detail of the non-Docker-driver gateway, and it is not present in the default Docker-driver topology.

The diagram below shows the standard Docker-driver topology.

```mermaid
graph TB
Expand Down
1 change: 1 addition & 0 deletions docs/reference/commands.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1650,6 +1650,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
Expand Down
Loading