docs(reference): document Docker-driver compute path alongside legacy k3s#3433
Open
latenighthackathon wants to merge 2 commits into
Open
docs(reference): document Docker-driver compute path alongside legacy k3s#3433latenighthackathon wants to merge 2 commits into
latenighthackathon wants to merge 2 commits into
Conversation
… k3s Clarifies that the OpenShell sandbox runs as a sibling Docker container on Linux and macOS Apple Silicon (Docker-driver path, default since 0.0.39 via NVIDIA#3001 and NVIDIA#3383) or as a pod in the embedded k3s cluster on macOS Intel, Windows, and WSL2 (legacy path). architecture.md gets a new platform/compute-path table at the top of Deployment Topology, the existing Mermaid diagram is identified as the legacy k3s path, and the layering table now lists both Sandbox container and Sandbox pod variants. prerequisites.md drops k3s from the RAM-pressure sentence (k3s is an internal detail of the gateway container, not a separate process the user budgets for) and rewords the fuse-overlayfs note to refer to the OpenShell gateway image rather than k3s directly. Refs NVIDIA#3432. Signed-off-by: latenighthackathon <latenighthackathon@users.noreply.github.com>
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Enterprise Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthroughDocumentation updated to reflect a split sandbox runtime topology: the Docker-driver path runs the sandbox as a sibling Docker container, while the legacy k3s path runs the sandbox as a pod inside the gateway-embedded cluster. Prerequisites updated to reference the OpenShell gateway and sandbox runtime. ChangesSplit Sandbox Topology Documentation
🎯 2 (Simple) | ⏱️ ~10 minutes
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
docs/reference/architecture.md (3)
156-159: ⚡ Quick winApply code formatting to technical terms in table.
Technical identifiers like
k3s,Landlock,seccomp, andnetnsshould use inline code formatting even within table cells for consistency.Suggested fix
-| Gateway container | Docker container | Hosts the credential store and the L7 proxy. On the legacy k3s path, also hosts the embedded k3s control plane. | -| k3s (legacy path only) | Process tree inside the gateway container | Kubernetes control plane that schedules the sandbox pod. | -| Sandbox container (Docker driver path) | Sibling Docker container managed by the gateway | Runs the OpenClaw agent and the NemoClaw plugin under Landlock + seccomp + netns. | -| Sandbox pod (legacy k3s path) | Pod in the embedded k3s cluster | Runs the OpenClaw agent and the NemoClaw plugin under Landlock + seccomp + netns. | +| Gateway container | Docker container | Hosts the credential store and the L7 proxy. On the legacy `k3s` path, also hosts the embedded `k3s` control plane. | +| `k3s` (legacy path only) | Process tree inside the gateway container | Kubernetes control plane that schedules the sandbox pod. | +| Sandbox container (Docker driver path) | Sibling Docker container managed by the gateway | Runs the OpenClaw agent and the NemoClaw plugin under `Landlock` + `seccomp` + `netns`. | +| Sandbox pod (legacy `k3s` path) | Pod in the embedded `k3s` cluster | Runs the OpenClaw agent and the NemoClaw plugin under `Landlock` + `seccomp` + `netns`. |As per coding guidelines, CLI commands, file paths, flags, parameter names, and values must use inline code formatting.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/reference/architecture.md` around lines 156 - 159, Update the table rows so all technical identifiers are formatted as inline code: wrap terms like `Gateway container` entries' `k3s` (in "k3s (legacy path only)"), `Landlock`, `seccomp`, and `netns` in backticks within their respective table cells (also apply to any CLI commands, file paths, flags, parameter names, or values present in the same rows), e.g., modify the "k3s (legacy path only)" row and both "Sandbox container (Docker driver path)" and "Sandbox pod (legacy k3s path)" descriptions to use inline code formatting for those terms to meet the coding guidelines.
93-93: ⚡ Quick winApply code formatting to technical term.
The term
k3sshould use inline code formatting for consistency with other technical identifiers in the documentation.Suggested fix
-The sandbox runs as a sibling Docker container or as a pod inside an embedded k3s cluster, depending on the host platform. +The sandbox runs as a sibling Docker container or as a pod inside an embedded `k3s` cluster, depending on the host platform.As per coding guidelines, CLI commands, file paths, flags, parameter names, and values must use inline code formatting.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/reference/architecture.md` at line 93, Replace the plain text occurrence of the technical term k3s in the sentence inside the architecture doc with inline code formatting (e.g., `k3s`) so it matches the project's guideline for CLI/technical identifiers; update the phrase "embedded k3s cluster" to "embedded `k3s` cluster" where it appears.
101-102: ⚡ Quick winFix passive voice and apply code formatting to technical terms.
Line 102 uses passive voice ("are replaced by"), which violates the active voice requirement. Additionally,
k3sand the technical security terms should use inline code formatting.Suggested fix
-The diagram below shows the legacy k3s path. -On the Docker driver path, the embedded k3s cluster and the sandbox pod are replaced by a sibling Docker container that hosts the OpenClaw agent under the same Landlock, seccomp, and netns confinement. +The diagram below shows the legacy `k3s` path. +On the Docker driver path, a sibling Docker container replaces the embedded `k3s` cluster and sandbox pod, hosting the OpenClaw agent under the same `Landlock`, `seccomp`, and `netns` confinement.As per coding guidelines, active voice is required, and CLI commands, file paths, flags, parameter names, and values must use inline code formatting.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/reference/architecture.md` around lines 101 - 102, Rewrite the sentence to use active voice and apply inline code formatting to technical terms: change "On the Docker driver path, the embedded k3s cluster and the sandbox pod are replaced by a sibling Docker container that hosts the OpenClaw agent under the same Landlock, seccomp, and netns confinement." to an active construction that explicitly names the actor (e.g., "The Docker driver replaces the embedded `k3s` cluster and the sandbox pod with a sibling Docker container that hosts the `OpenClaw` agent under the same `Landlock`, `seccomp`, and `netns` confinement.")—ensure `k3s`, `OpenClaw`, `Landlock`, `seccomp`, and `netns` are formatted as inline code and prefer "replaces" (active verb) instead of passive phrasing.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/get-started/prerequisites.md`:
- Line 35: The paragraph on sandbox image memory should be rewritten so each
sentence is on its own line: split the existing six-sentence block into six
separate lines, preserving the original wording and order (sentences about image
size, concurrent processes: Docker daemon/OpenShell gateway/sandbox runtime,
pipeline buffering decompressed layers in memory, OOM killer on machines <8 GB,
recommendation to configure at least 8 GB swap if memory cannot be increased,
and note about slower performance), ensuring one sentence per line to satisfy
the one-sentence-per-line style requirement.
---
Nitpick comments:
In `@docs/reference/architecture.md`:
- Around line 156-159: Update the table rows so all technical identifiers are
formatted as inline code: wrap terms like `Gateway container` entries' `k3s` (in
"k3s (legacy path only)"), `Landlock`, `seccomp`, and `netns` in backticks
within their respective table cells (also apply to any CLI commands, file paths,
flags, parameter names, or values present in the same rows), e.g., modify the
"k3s (legacy path only)" row and both "Sandbox container (Docker driver path)"
and "Sandbox pod (legacy k3s path)" descriptions to use inline code formatting
for those terms to meet the coding guidelines.
- Line 93: Replace the plain text occurrence of the technical term k3s in the
sentence inside the architecture doc with inline code formatting (e.g., `k3s`)
so it matches the project's guideline for CLI/technical identifiers; update the
phrase "embedded k3s cluster" to "embedded `k3s` cluster" where it appears.
- Around line 101-102: Rewrite the sentence to use active voice and apply inline
code formatting to technical terms: change "On the Docker driver path, the
embedded k3s cluster and the sandbox pod are replaced by a sibling Docker
container that hosts the OpenClaw agent under the same Landlock, seccomp, and
netns confinement." to an active construction that explicitly names the actor
(e.g., "The Docker driver replaces the embedded `k3s` cluster and the sandbox
pod with a sibling Docker container that hosts the `OpenClaw` agent under the
same `Landlock`, `seccomp`, and `netns` confinement.")—ensure `k3s`, `OpenClaw`,
`Landlock`, `seccomp`, and `netns` are formatted as inline code and prefer
"replaces" (active verb) instead of passive phrasing.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 302cd111-35e8-4909-8787-e9636926e59e
📒 Files selected for processing (2)
docs/get-started/prerequisites.mddocs/reference/architecture.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Refresh
docs/reference/architecture.mdanddocs/get-started/prerequisites.mdso they reflect the dual-path compute model that landed in 0.0.39 via #3001 (Linux) and #3383 (macOS Apple Silicon). Both pages currently describe the OpenShell sandbox exclusively as a Kubernetes pod inside a gateway-embedded k3s cluster, which is no longer accurate for the platforms most NemoClaw users run on.Problem
Per
src/lib/onboard.ts:3411-3416,isLinuxDockerDriverGatewayEnabledreturnstrueforplatform === "linux"and forplatform === "darwin" && arch === "arm64", so the Docker-driver path is the default with no opt-in on those platforms. The legacy k3s path still applies to macOS Intel, Windows, and WSL2.The release notes for 0.0.39 in
docs/about/release-notes.mdcall out the Docker-driver migration, but architecture.md and prerequisites.md were not refreshed in #3375 (release-prep PR) and still tell readers the sandbox is always a Kubernetes pod. New users reading the architecture page form the wrong mental model on day one.See #3432 for the full gap analysis with verified-against-code reproduction steps.
Changes
docs/reference/architecture.md:docs/get-started/prerequisites.md:platform === "linux" && !isWslHost && runtime === "docker" && dockerStorageDriver === "overlayfs" && dockerUsesContainerdSnapshotter(seesrc/lib/onboard/preflight.ts:478), so referring to the gateway image rather than k3s directly is more accurate now that Linux uses the Docker driver.No diagram is added or replaced. The existing legacy-k3s diagram is preserved verbatim and re-labelled by the surrounding prose.
Test plan
npx prek run --files docs/get-started/prerequisites.md docs/reference/architecture.mdpasses (gitleaks, markdownlint, docs-to-skills dry-run, skills YAML)commitlintpassesmake docs(no Sphinx in container; rendered preview will appear via NemoClaw's docs build job)Type of Change
Refs #3432.
Signed-off-by: latenighthackathon latenighthackathon@users.noreply.github.com
Summary by CodeRabbit