docs: add known issues, hardware details, and NIM warnings to spark-install guide

[cluster2600]

Summary

Cherry-picks the documentation improvements from #304 that reviewers confirmed are worth merging:

• Three known issues: pip system packages error, port 3000 AI Workbench conflict, NVIDIA cloud API egress
• Web Dashboard access section
• NIM arm64 compatibility warning
• Hardware details (aarch64, 128 GB unified memory, Docker 29.x)

Excludes the install-flow change (handled in #696) and manual openclaw.json editing (needs validation against current gateway config flow).

Supersedes #304.

Test plan

• Documentation renders correctly
• No broken links

Summary by CodeRabbit

• Documentation
  • Updated DGX Spark hardware specifications and Docker version details.
  • Extended Known Issues section with troubleshooting for pip install failures, port 3000 conflicts, and network policy configurations.
  • Added Technical Reference section with OpenClaw gateway setup guidance.
  • Added NIM Compatibility notes for arm64 architecture limitations.
  • Updated architecture diagram to reflect current specifications.

[prekshivyas]

Good additions — the new known issues (pip, port 3000, network policy), web dashboard section, and NIM arm64 compatibility warning are all practical, hardware-tested findings.

This needs a rebase on main since #857 (structural restructure of spark-install.md) was just merged. The new sections should slot into #857's structure:

• Known issues rows → Troubleshooting section
• Web dashboard + NIM arm64 → Technical Reference section

[coderabbitai]

📝 Walkthrough

Walkthrough

Updated spark-install.md to specify Docker versions 28.x/29.x, document DGX Spark hardware specifications (Ubuntu 24.04, aarch64, Grace CPU + GB10 GPU, 128 GB unified memory), and add new sections covering known issues, technical reference guidance, and NIM arm64 compatibility constraints.

Changes

Cohort / File(s)	Summary
Documentation Updates spark-install.md	Added Docker version specifications, extended Known Issues table with pip install failures, port 3000 conflicts, and network policy blocking; introduced Technical Reference section with OpenClaw gateway details and explicit IP guidance; added NIM Compatibility on arm64 section documenting amd64-only image failures and alternatives.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐰 A doc update hops along,
With Docker specs and fixes strong,
DGX Spark shines in noble light,
arm64 paths made crystal bright! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title directly and accurately reflects the main changes: adding known issues, hardware details, and NIM compatibility warnings to the spark-install documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ 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

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@spark-install.md`:
- Around line 211-213: The doc currently references "~/.openclaw/openclaw.json
inside the sandbox" without showing how to fetch the gateway token; update the
text to explicitly tell users how to retrieve gateway.auth.token by (a) running
jq against /sandbox/.openclaw/openclaw.json from inside the sandbox to extract
gateway.auth.token, or (b) from the host using the sandbox download command
(e.g. openshell sandbox download) to fetch /sandbox/.openclaw/openclaw.json and
then extract gateway.auth.token; retain the note to use 127.0.0.1 for origin
checks.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: fe549f0b-7f5b-49b1-9042-34666955a8a7

📥 Commits

Reviewing files that changed from the base of the PR and between 2804eae and c1cb961.

📒 Files selected for processing (1)

• spark-install.md

[coderabbitai]

🛠️ Refactor suggestion | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify how token/config location is documented elsewhere in the repo.
# Expected: consistent guidance for openclaw.json location and token retrieval context.

rg -n -C2 'openclaw\.json|gateway\.auth\.token|127\.0\.0\.1:18789|Web Dashboard|Mission Control'

Repository: NVIDIA/NemoClaw

Length of output: 46323

---

Specify the command or method to retrieve the gateway token for host users.

Line 211 mixes host path notation (~/.openclaw/) with "inside the sandbox," leaving users unclear on how to actually obtain the token for the Web Dashboard URL. Replace the vague reference with an explicit retrieval method. For example:

To retrieve your gateway token, run this command inside the sandbox:
jq -r '.gateway.auth.token' /sandbox/.openclaw/openclaw.json

Or use openshell sandbox download /sandbox/.openclaw/openclaw.json from the host if the sandbox supports it.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@spark-install.md` around lines 211 - 213, The doc currently references
"~/.openclaw/openclaw.json inside the sandbox" without showing how to fetch the
gateway token; update the text to explicitly tell users how to retrieve
gateway.auth.token by (a) running jq against /sandbox/.openclaw/openclaw.json
from inside the sandbox to extract gateway.auth.token, or (b) from the host
using the sandbox download command (e.g. openshell sandbox download) to fetch
/sandbox/.openclaw/openclaw.json and then extract gateway.auth.token; retain the
note to use 127.0.0.1 for origin checks.

[cluster2600]

Good point — updated to show the explicit jq command for extracting the token from inside the sandbox. The ~/.openclaw/ path was misleading since the config lives at /sandbox/.openclaw/openclaw.json inside the container.