docs(manage-sandboxes): add runtime controls + shields + mutability table (#3230)

[cjagwani]

Summary

Adds a consolidated reference page that answers two operator questions previously fragmented across many existing docs:

1. What can change at runtime vs. what requires rebuild or re-onboard. A single table covers the items the issue called out (inference provider, model, sub-agent, policy presets, channel tokens, dashboard port + bind address, web search backend, filesystem layout, sandbox name, GPU passthrough, shields posture, agents allow-list).
2. The operator-only shields up / shields down / shields status commands — previously undocumented despite being load-bearing for the lockdown ↔ default posture transition. Full surface documented including the --timeout, --reason, --policy flags on shields down and the auto-restore timer semantics.

Closes #3230.

Acceptance criteria mapping

Clause from #3230	Evidence
(A) shields up/down/status commands documented	runtime-controls.md ### sections — 3/3
(A) Operator-only framing	"Shields are an operator-only switch… the sandbox itself cannot raise or lower its own shields" intro
(A) --timeout, --reason, --policy flag tables	Flags table under ### shields down — 3/3
(A) Auto-restore timer behavior	"The auto-restore timer is detached… closing your terminal does not cancel" + cross-ref to #3112
(B) Consolidated mutability reference	14-row table under ## What you can change at runtime
(B) Cover every commonly changed item (model, provider, policy preset, openclaw.json keys, agents.list, channel tokens, dashboard port, GPU passthrough, sandbox name, shields posture)	10/10 items present in the table
(B) Each item maps to runtime / hot-reload / rebuild / re-onboard	"When the change takes effect" column
Suggested home: docs/security/openclaw-controls.md OR new docs/manage-sandboxes/runtime-controls.md	Picked the latter for cohesion with other operator-task pages
Plug into nav	Added one toctree entry under "Manage Sandboxes" in docs/index.md
Cross-refs to existing scattered pages	"See also" footer links to lifecycle, switch-inference-providers, customize-network-policy, approve-network-requests, best-practices, openclaw-controls, commands.md

Test plan

• make docs builds cleanly (1 pre-existing warning unrelated to this page about docs/superpowers/specs/... not in toctree)
• All 7 cross-ref targets in "See also" exist on main
• All 10 mutability items called out in the issue are present in the table
• shields up, shields down, shields status each have a dedicated section
• --timeout, --reason, --policy flags documented with defaults and effects
• Manual: render the page locally (make docs-live) and verify the table and code blocks render correctly on the Sphinx theme — pending reviewer

Notes for reviewers

• Single new file under docs/manage-sandboxes/ (the issue suggested either there or docs/security/; the operator-task framing fits manage-sandboxes better since it sits alongside lifecycle/messaging-channels/workspace-files).
• The mutability table is intentionally a consolidated index rather than a duplicate source of truth — each row points at the existing detailed page through the "See also" footer.
• Source-of-truth notes on /opt/nemoclaw/openclaw.json and cross-refs to related issues ([macOS][Brev][CLI&UX] Dashboard port 18789 hard-bound to 127.0.0.1 — no flag/env to bind 0.0.0.0 for remote-SSH-deployed hosts #3259 dashboard bind, bug(messaging) channels stop <name> does not stop the bridge through rebuild — openclaw.json still bakes the channel in #3453 channel stop, [Ubuntu 24.04][Security] shields-down timer process death leaves shields permanently DOWN (fail-open) #3112 shields timer) are inline so users searching for those keywords land here as well.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added a new page describing runtime controls for sandboxes, detailing which components can be changed at runtime vs. those requiring rebuild or re-onboard.
  • Documented operator "shields" workflows and CLI options for locking/unlocking config, applying policies, and auto-restore timers.
  • Added “See also” links to lifecycle, provider switching, network policy customization, security best practices, and CLI reference.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds an operator-facing Runtime Controls documentation page describing NemoClaw sandbox mutability and the nemoclaw shields workflows, and links it from the Manage Sandboxes index.

Changes

Runtime Controls Documentation

Layer / File(s)	Summary
Documentation index and page metadata docs/index.md, docs/manage-sandboxes/runtime-controls.md	Manage Sandboxes toctree now includes Runtime Controls; page frontmatter defines title, nav label, description, topics, and metadata (difficulty, audience, status).
Sandbox mutability reference docs/manage-sandboxes/runtime-controls.md	Three-layer mutability table documents which sandbox components are runtime-mutable, hot-reloadable, require rebuild, or require re-onboard; clarifies /opt/nemoclaw/openclaw.json is the runtime source of truth.
Shields command workflows and related documentation docs/manage-sandboxes/runtime-controls.md	Operator-only shields commands documented: shields status, shields up (locks config + applies restrictive policy), shields down (unlocks config + applies permissive/specified policy) with --timeout, --reason, --policy flags and auto-restore/timer semantics. See also links to related pages.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

A new page hops into the docs with care,
Runtime mutability laid bare,
Shields up, shields down, shields status too—
Operators now know what to do! 🛡️✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title clearly and specifically summarizes the main changes: adding runtime controls documentation, shields commands documentation, and a mutability reference table to the manage-sandboxes section.
Linked Issues check	✅ Passed	The PR fully addresses both primary objectives from issue #3230: it documents the shields up/down/status commands with flags and auto-restore semantics, and provides a consolidated mutability reference table mapping commonly changed items to their change effects.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to requirements in #3230: adding runtime-controls.md documentation page and integrating it into the toctree, with no unrelated modifications.
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
• Commit unit tests in branch docs/3230-shields-mutability

Warning

Review ran into problems

🔥 Problems

Stopped waiting for pipeline failures after 30000ms. One of your pipelines takes longer than our 30000ms fetch window to run, so review may not consider pipeline-failure results for inline comments if any failures occurred after the fetch window. Increase the timeout if you want to wait longer or run a @coderabbit review after the pipeline has finished.

---

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

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• None. Docs-only PR. The changes affect documentation navigation and a new markdown reference page only, so they cannot change runtime behavior or real user flows in CI.

Optional E2E

• None.

New E2E recommendations

• None.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (3)

docs/manage-sandboxes/runtime-controls.md (3)

81-81: ⚡ Quick win

Avoid colon-as-punctuation in prose lines.

The colons in “Raise shields: ...” and “Lower shields: ...” are clause separators, not list introducers; rewrite with a period or comma.

As per coding guidelines, "Colons should only introduce a list. Flag colons used as general punctuation between clauses."

Also applies to: 94-94

🤖 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/manage-sandboxes/runtime-controls.md` at line 81, Change the prose
headings that use a colon as clause separator—specifically the lines beginning
with "Raise shields:" and "Lower shields:"—to use a period or comma instead
(e.g., "Raise shields. Lock `openclaw.json`..." or "Raise shields, lock
`openclaw.json`...") so the colon is only used to introduce lists per the style
guideline; update both occurrences referenced by the "Raise shields" and "Lower
shields" phrases.

---

52-55: 💤 Low value

Remove routine bold emphasis in table values (LLM pattern detected).

**Locked at creation** and similar emphasis here reads as stylistic emphasis rather than a UI label or warning.

As per coding guidelines, "Unnecessary bold on routine instructions ... should be flagged. Bold is reserved for UI labels, parameter names, and genuine warnings."

🤖 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/manage-sandboxes/runtime-controls.md` around lines 52 - 55, In the
runtime-controls table remove the unnecessary Markdown bold markup around
routine status values (e.g. change "**Locked at creation**" and similar
occurrences to plain text "Locked at creation" and remove bold from "Runtime
(operator-only)") so the entries read as neutral labels; keep bold only for
genuine UI labels or warnings such as parameter names like `--name` or command
examples like `nemoclaw <name> shields up`/`shields down`, and update the table
cells for "Filesystem layout (Landlock zones, read-only mounts, container
caps)", "Sandbox name", "GPU passthrough enable / device selector", and "Shields
posture (locked ↔ default mutable)" accordingly.

---

37-38: ⚡ Quick win

Use active voice and present tense consistently.

These lines include passive/future constructions (for example, “is baked,” “is initiated,” “are hidden,” “Recorded...,” “will surface”); rewrite in active, present-tense voice addressing the reader directly.

As per coding guidelines, "Active voice required... Second person ('you')... Present tense. Flag future tense ('will') in descriptions of current behavior."

Also applies to: 63-67, 104-104, 108-108

🤖 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/manage-sandboxes/runtime-controls.md` around lines 37 - 38, Rewrite the
two sentences to use active voice, present tense, and address the reader in
second person; specifically change "NemoClaw applies its security posture in
three layers — what is baked into the sandbox image at onboard, what is
hot-reloadable on the running sandbox, and what requires a rebuild or
re-onboard." to something like "NemoClaw enforces security across three layers:
settings you bake into the sandbox image when you onboard, settings you
hot-reload on a running sandbox, and settings that require you to rebuild or
re-onboard." and change "The table below maps each commonly changed item to the
layer that owns it and the command that changes it." to an active, present-tense
instruction such as "Use the table below to find which layer owns each commonly
changed item and which command you run to change it." Also update the similar
passive/future phrases identified elsewhere (e.g., "is baked", "is initiated",
"are hidden", "Recorded...", "will surface" and the ranges noted) to active,
present-tense second-person phrasing throughout.

🤖 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/manage-sandboxes/runtime-controls.md`:
- Line 110: Rename the final related-links heading from "## See also" to "##
Next Steps" so it matches the docs page template; locate the heading text "##
See also" in the document and replace it with "## Next Steps" ensuring this is
the bottom related-links section referenced by the page guidelines.

---

Nitpick comments:
In `@docs/manage-sandboxes/runtime-controls.md`:
- Line 81: Change the prose headings that use a colon as clause
separator—specifically the lines beginning with "Raise shields:" and "Lower
shields:"—to use a period or comma instead (e.g., "Raise shields. Lock
`openclaw.json`..." or "Raise shields, lock `openclaw.json`...") so the colon is
only used to introduce lists per the style guideline; update both occurrences
referenced by the "Raise shields" and "Lower shields" phrases.
- Around line 52-55: In the runtime-controls table remove the unnecessary
Markdown bold markup around routine status values (e.g. change "**Locked at
creation**" and similar occurrences to plain text "Locked at creation" and
remove bold from "Runtime (operator-only)") so the entries read as neutral
labels; keep bold only for genuine UI labels or warnings such as parameter names
like `--name` or command examples like `nemoclaw <name> shields up`/`shields
down`, and update the table cells for "Filesystem layout (Landlock zones,
read-only mounts, container caps)", "Sandbox name", "GPU passthrough enable /
device selector", and "Shields posture (locked ↔ default mutable)" accordingly.
- Around line 37-38: Rewrite the two sentences to use active voice, present
tense, and address the reader in second person; specifically change "NemoClaw
applies its security posture in three layers — what is baked into the sandbox
image at onboard, what is hot-reloadable on the running sandbox, and what
requires a rebuild or re-onboard." to something like "NemoClaw enforces security
across three layers: settings you bake into the sandbox image when you onboard,
settings you hot-reload on a running sandbox, and settings that require you to
rebuild or re-onboard." and change "The table below maps each commonly changed
item to the layer that owns it and the command that changes it." to an active,
present-tense instruction such as "Use the table below to find which layer owns
each commonly changed item and which command you run to change it." Also update
the similar passive/future phrases identified elsewhere (e.g., "is baked", "is
initiated", "are hidden", "Recorded...", "will surface" and the ranges noted) to
active, present-tense second-person phrasing throughout.

🪄 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: 6eaaadbd-5cb0-4666-9fda-b88aa5263841

📥 Commits

Reviewing files that changed from the base of the PR and between 9bf3f8d and 1771ce6.

📒 Files selected for processing (2)

• docs/index.md
• docs/manage-sandboxes/runtime-controls.md

[coderabbitai]

🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

Rename this section to Next Steps to match the docs page template.

Use ## Next Steps as the final related-links section heading instead of ## See also.

As per coding guidelines, "When reviewing new pages, verify: ... A 'Next Steps' section at the bottom links to related pages."

🤖 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/manage-sandboxes/runtime-controls.md` at line 110, Rename the final
related-links heading from "## See also" to "## Next Steps" so it matches the
docs page template; locate the heading text "## See also" in the document and
replace it with "## Next Steps" ensuring this is the bottom related-links
section referenced by the page guidelines.

[coderabbitai]

🧹 Nitpick comments (3)

docs/manage-sandboxes/runtime-controls.md (3)

109-109: ⚡ Quick win

Use present tense instead of future tense.

"shields status will surface..." should be present-tense phrasing.

As per coding guidelines, "Present tense. Flag future tense ('will') in descriptions of current behavior."

🤖 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/manage-sandboxes/runtime-controls.md` at line 109, The sentence uses
future tense ("`shields status` will surface the inconsistency on the next
check"); change it to present tense by replacing "will surface" with "surfaces"
so the line reads: "If the timer process is killed before the deadline (e.g.
host reboot), `shields status` surfaces the inconsistency on the next check (see
`#3112` for the fail-open fix)." Update the sentence containing `shields status`
and the reference to `#3112` accordingly.

---

52-54: 💤 Low value

Avoid bold for routine table states (LLM pattern detected).

**Locked at creation** reads like emphasis rather than a warning/UI label.

As per coding guidelines, "Unnecessary bold on routine instructions ... Bold is reserved for UI labels, parameter names, and genuine warnings."

🤖 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/manage-sandboxes/runtime-controls.md` around lines 52 - 54, The table
currently uses markdown bold for the routine state string "**Locked at
creation**" in rows like "Filesystem layout (Landlock zones, read-only mounts,
container caps)", "Sandbox name", and "GPU passthrough enable / device
selector"; remove the bold markup and replace it with plain text "Locked at
creation" (or a UI-label-safe format if needed) so the state reads as a regular
instruction rather than emphasized UI/warning text, ensuring only true UI labels
or warnings remain bolded.

---

67-67: ⚡ Quick win

Use active voice for this sentence.

"The commands are hidden..." is passive; rewrite with an active subject.

As per coding guidelines, "Active voice required. Flag passive constructions."

🤖 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/manage-sandboxes/runtime-controls.md` at line 67, Replace the passive
sentence "The commands are hidden from the standard `--help` output because they
are operator workflows, not developer workflows; everything below documents the
full surface." with an active-voice version (for example: "We hide the commands
from the standard `--help` output because they are operator workflows, not
developer workflows; everything below documents the full surface.") so the
sentence uses a clear subject and active verb.

🤖 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.

Nitpick comments:
In `@docs/manage-sandboxes/runtime-controls.md`:
- Line 109: The sentence uses future tense ("`shields status` will surface the
inconsistency on the next check"); change it to present tense by replacing "will
surface" with "surfaces" so the line reads: "If the timer process is killed
before the deadline (e.g. host reboot), `shields status` surfaces the
inconsistency on the next check (see `#3112` for the fail-open fix)." Update the
sentence containing `shields status` and the reference to `#3112` accordingly.
- Around line 52-54: The table currently uses markdown bold for the routine
state string "**Locked at creation**" in rows like "Filesystem layout (Landlock
zones, read-only mounts, container caps)", "Sandbox name", and "GPU passthrough
enable / device selector"; remove the bold markup and replace it with plain text
"Locked at creation" (or a UI-label-safe format if needed) so the state reads as
a regular instruction rather than emphasized UI/warning text, ensuring only true
UI labels or warnings remain bolded.
- Line 67: Replace the passive sentence "The commands are hidden from the
standard `--help` output because they are operator workflows, not developer
workflows; everything below documents the full surface." with an active-voice
version (for example: "We hide the commands from the standard `--help` output
because they are operator workflows, not developer workflows; everything below
documents the full surface.") so the sentence uses a clear subject and active
verb.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 53342aa2-5bfe-4d3f-b923-760ecbae5ba3

📥 Commits

Reviewing files that changed from the base of the PR and between 1771ce6 and d1b9a41.

📒 Files selected for processing (1)

• docs/manage-sandboxes/runtime-controls.md