docs(reference): document Docker-driver compute path alongside legacy k3s

[latenighthackathon]

Summary

Refresh docs/reference/architecture.mdx so it reflects the dual-path compute model that landed in 0.0.39 (Linux via #3001, macOS Apple Silicon via #3383). The page previously described 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

isLinuxDockerDriverGatewayEnabled returns true for platform === "linux" and for platform === "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 and a few other fallback cases. The 0.0.39 release notes call out the Docker-driver migration, but architecture.mdx was not refreshed at the time and still told readers the sandbox is always a Kubernetes pod. New users reading the architecture page formed the wrong mental model on day one.

See #3432 for the original gap analysis with verified-against-code reproduction steps.

Changes

docs/reference/architecture.mdx:

• Replace the universal "embeds a k3s cluster" prose at the top of Deployment Topology with a paragraph that names both compute paths.
• Add a platform table mapping each platform to its compute path:
  • Linux (any arch, including DGX Spark / Station): Docker driver, sibling Docker container
  • Windows WSL2 (Docker Desktop, WSL backend): Docker driver, sibling Docker container (WSL2 reports platform === "linux")
  • macOS Apple Silicon (Colima or Docker Desktop): Docker driver, sibling Docker container
• Update the layer-by-layer table to call out both the legacy k3s sandbox-pod row and the Docker-driver sandbox-container row.
• Keep the legacy k3s diagram for historical context with a clear "legacy path" frame.

docs/get-started/prerequisites.mdx:

• After rebasing past the Fern MDX migration, the only relevant edit upstream already had landed in the <Note> form; no additional change carried in this PR.

Related Issue

Closes #3432.

Test plan

• prek run clean
• Platform table cross-checked against src/lib/onboard/docker-driver-platform.ts dispatch (platform === "linux" || (platform === "darwin" && arch === "arm64"))
• Rendered locally; tables render correctly under Fern

Signed-off-by: latenighthackathon latenighthackathon@users.noreply.github.com

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Docs updated to describe a split sandbox runtime topology: on the Docker-driver path the sandbox runs as a sibling Docker container alongside the gateway and export pipeline; on the legacy embedded k3s path the sandbox runs as a pod inside the gateway-embedded k3s cluster. Prerequisites text and storage-driver note adjusted accordingly.

Changes

Split Sandbox Topology Documentation

Layer / File(s)	Summary
Architecture topology and layering table docs/reference/architecture.md	Replaced the prior "gateway embeds k3s + sandbox pod" narrative with a platform/compute-path description distinguishing Docker-driver (sandbox as sibling Docker container) and legacy k3s (sandbox as pod) paths; updated Docker-driver confinement wording and refined the layering table to separate sandbox container vs. sandbox pod and to scope embedded k3s hosting to the legacy path.
Prerequisites component references and storage-driver note docs/get-started/prerequisites.md	Reworded sandbox image-push prerequisites to state the Docker daemon, OpenShell gateway container, and sandbox runtime run alongside the export pipeline; retained decompressed-layer buffering, <8 GB RAM OOM risk, and swap guidance; updated Docker 26+ storage-driver note to reference nested-overlay limitation targeting the OpenShell gateway image.

🎯 2 (Simple) | ⏱️ ~10 minutes

• [Docs] architecture.md and prerequisites.md still describe only the legacy k3s path; Docker driver default landed in 0.0.39 #3432: Mirrors the same docs updates to reflect the Docker-driver sandbox-as-sibling-container path and replace k3s-specific wording; this PR appears to implement that objective.

"I’m a rabbit in the docs so bright,
I nudged the sandbox into clearer light.
Gateway and container now side-by-side,
I hop, I nibble, and then I hide. 🥕📘"

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly and accurately summarizes the main changes: documenting the Docker-driver compute path alongside the legacy k3s path in the architecture reference documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (3)

docs/reference/architecture.md (3)

156-159: ⚡ Quick win

Apply code formatting to technical terms in table.

Technical identifiers like k3s, Landlock, seccomp, and netns should 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 win

Apply code formatting to technical term.

The term k3s should 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 win

Fix passive voice and apply code formatting to technical terms.

Line 102 uses passive voice ("are replaced by"), which violates the active voice requirement. Additionally, k3s and 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

📥 Commits

Reviewing files that changed from the base of the PR and between 904ea58 and 9f381df.

📒 Files selected for processing (2)

• docs/get-started/prerequisites.md
• docs/reference/architecture.md

[wscurran]

✨ Thanks for submitting this detailed PR to document the Docker-driver compute path alongside the legacy k3s path. This change aims to improve the accuracy of the documentation by reflecting the dual-path compute model that landed in 0.0.39.

---

Related open PRs:

• #3001 feat(onboard): use OpenShell Docker GPU sandboxes
• #3375 docs: refresh 0.0.39 release prep
• #3383 fix(onboard): use Docker-driver gateway on macOS OpenShell 0.0.37

---

Related open issues:

• #3432 [Docs] architecture.md and prerequisites.md still describe only the legacy k3s path; Docker driver default landed in 0.0.39