docs(security): clarify mutable-default config posture

[ericksoa]

Summary

• correct root help reconfiguration copy so fresh sandboxes are described as mutable by default, with durable config changes routed through host-side commands or re-onboard
• document that Landlock's filesystem layout is fixed at sandbox creation while shields up adds host-side DAC/chattr lockdown for sensitive workloads
• update inference/troubleshooting docs and generated skill references so openclaw.json is not described as immutable in the default sandbox
• remove stale /sandbox is Landlock read-only comments from startup/test/Hermes scaffolding

Validation

• npx vitest run test/root-help.test.ts
• npm run build:cli
• npm run typecheck:cli
• python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --dry-run
• bash test/e2e/e2e-cloud-experimental/check-docs.sh --only-links --local-only docs/security/best-practices.md docs/deployment/sandbox-hardening.md docs/inference/switch-inference-providers.md docs/reference/troubleshooting.md
• uv run --group docs sphinx-build -W -b html docs docs/_build/html
• node bin/nemoclaw.js help | rg -n 'Reconfiguration|Agent config|host-side|shields up|read-only|Landlock enforced'

Issue Notes

• Refs [Ubuntu 24.04][Security] /sandbox and openclaw.json writable by sandbox user — Landlock not enforced #3387: fresh /sandbox and .openclaw writes are expected in mutable-default mode; this PR fixes the stale docs/root-help wording that said otherwise.
• Partially addresses [All Platforms][Docs] Lack of documentation for sandbox mutability story and shields up / shields down / shields status commands #3230 by documenting shields commands and the mutable-default vs lockdown split; it does not add the full runtime mutability matrix requested there.

Summary by CodeRabbit

• Documentation

  • Clarified configuration workflow: settings must be applied via host-side commands and onboarding, not direct sandbox edits, to ensure durability.
  • Updated sandbox security guidance: writable config paths are intentional by design for runtime state management.

• New Features

  • Added shields command documentation for enabling config lockdown on sensitive workloads.

• Chores

  • Updated CLI help output and test suite to reflect configuration behavior changes.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: c5b52414-557a-4ba1-aabb-bfb44d7b6745

📥 Commits

Reviewing files that changed from the base of the PR and between edb7478 and 2d17948.

📒 Files selected for processing (14)

• .agents/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md
• .agents/skills/nemoclaw-user-configure-security/references/best-practices.md
• .agents/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md
• .agents/skills/nemoclaw-user-reference/references/troubleshooting.md
• agents/hermes/Dockerfile.base
• docs/deployment/sandbox-hardening.md
• docs/inference/switch-inference-providers.md
• docs/reference/troubleshooting.md
• docs/security/best-practices.md
• scripts/nemoclaw-start.sh
• src/lib/actions/root-help.ts
• test/e2e-gateway-isolation.sh
• test/e2e/test-sandbox-survival.sh
• test/root-help.test.ts

---

📝 Walkthrough

Walkthrough

This PR updates NemoClaw documentation and CLI help to clarify sandbox configuration behavior. The core change: /sandbox/.openclaw/openclaw.json is writable by default for runtime state; durable NemoClaw-managed settings require host-side nemoclaw onboard commands. A new shields command enables optional host-side config lockdown. Supporting comments and tests are updated for consistency.

Changes

Sandbox Configuration Behavior and Shields Feature Documentation

Layer / File(s)	Summary
Writable agent config behavior and durable settings .agents/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md, docs/inference/switch-inference-providers.md, .agents/skills/nemoclaw-user-reference/references/troubleshooting.md, docs/reference/troubleshooting.md	openclaw.json is writable for runtime agent state in fresh sandboxes; NemoClaw-managed defaults require host-side nemoclaw onboard commands, not in-sandbox openclaw config set or direct file edits. Timeouts and heartbeat intervals are written during onboarding and rebuilt on updates.
Landlock and intentional sandbox writable defaults .agents/skills/nemoclaw-user-configure-security/references/best-practices.md, .agents/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md, docs/security/best-practices.md, docs/deployment/sandbox-hardening.md	Filesystem layer documentation clarifies that /sandbox and /sandbox/.openclaw are intentionally writable by default; Landlock enforces read-only system paths and is fixed at sandbox creation, not reconfigurable without re-creation.
Shields command for host-side config lockdown .agents/skills/nemoclaw-user-configure-security/references/best-practices.md, docs/security/best-practices.md	Introduces nemoclaw <name> shields status/up/down commands for host-side optional config lockdown, layering DAC permissions and chattr +i without modifying the fixed Landlock policy.
CLI help text and test validation src/lib/actions/root-help.ts, test/root-help.test.ts	Updated root help output to describe writable agent config in default sandbox, durable settings via host-side commands, and shields lockdown option; test validates expected inclusion/exclusion of help text strings.
Supporting script and test comment updates agents/hermes/Dockerfile.base, scripts/nemoclaw-start.sh, test/e2e-gateway-isolation.sh, test/e2e/test-sandbox-survival.sh	Updated build-time and test-time documentation comments to reflect writable sandbox defaults and the role of /sandbox/.openclaw for durable agent state, removing obsolete Landlock-specific caveats.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 A sandbox grows a garden fair,
Where agent state can live and share,
Yet Landlock keeps the deep roots locked—
Host shields stand guard at every dock,
Writable by day, by shields made tight! 🛡️

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/mutable-default-help-copy

---

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

[github-actions]

E2E Advisor Recommendation

Required E2E: None
Optional E2E: None

Workflow run

Full advisor summary

Pi Semantic E2E Advisor

Failed: pi exited with status 1; see /home/runner/work/NemoClaw/NemoClaw/artifacts/e2e-advisor/e2e-advisor-pi-raw-output.txt

[ericksoa]

Superseded by #3407. The original branch was missing a DCO Signed-off-by trailer, and this repo blocks force-pushes to PR branches, so I opened a replacement branch with the signed commit.