Runtime Controls and Sandbox Mutability

This page explains which parts of a running NemoClaw sandbox can change immediately and which changes require a rebuild or re-onboard.

What You Can Change at Runtime

NemoClaw applies its security posture in three layers: what onboarding writes into the sandbox image, what the running sandbox can hot-reload, and what requires a rebuild or re-onboard. The following table maps each commonly changed item to the layer that owns it and the command that changes it.

If a row above conflicts with what you observe, the runtime source of truth for Hermes is /sandbox/.hermes/config.yaml plus /sandbox/.hermes/.env; the host registry caches metadata but the image and Hermes runtime read from the in-sandbox files. Do not edit /sandbox/.hermes/config.yaml, /sandbox/.hermes/.env, or their hash files directly and then expect gateway restart to establish those bytes as trusted. Use supported host config and inference commands for intended changes because they update the managed config metadata together. In the direct root-entrypoint topology, PID 1 validates the Hermes secret boundary and runtime environment and verifies the strict root-owned hash without recomputing it. In the OpenShell-managed topology, the installed root controller validates the same secret boundary and verifies the strict hash when both config inputs are root-owned and locked. Mutable managed config has no durable root-owned hash anchor, so restart has the same trust and time-of-check/time-of-use limits as managed cold start and cannot promise a config hash mismatch for direct drift.

Hermes host-side config writes run as a sealed transaction. NemoClaw binds the write to the SHA-256 digest of the matching read, temporarily seals the mutable config paths, atomically installs fresh config inodes, refreshes the strict and compatibility hashes, and then restores the prior shields posture. shields up also publishes fresh config, environment, and compatibility-hash inodes so a descriptor opened before lockdown cannot retain write authority. The same root-only mutation lock stays held through Hermes config writes, the full shields up or shields down filesystem transition and verification, and lifecycle recovery that needs to seal those paths. If another host mutation is active, the command reports Hermes config mutation is already in progress; if another lifecycle request owns the supervisor, it reports SUPERVISOR_BUSY. Both errors are retryable. Let the active command finish, then retry instead of editing lock or seal files manually. Hermes config and inference changes are refused while shields are up; run nemohermes <name> shields down before the change, then restore lockdown with nemohermes <name> shields up.

How Timed Shields Windows Interact with Host Commands

NemoClaw serializes host-side config and inference writes, snapshot mutation, sandbox destruction, and shields transitions for each sandbox. When shields down --timeout is active, each mutation binds to that exact timer generation so a replaced or expired timer cannot race a later command or a new sandbox that reuses the same name. If the timeout expires while a mutation is still changing sandbox state, auto-restore can stop that exact process tree, reclaim the transition, and restore the restrictive policy and config posture. The ownership check includes both the process ID and process start identity so PID reuse does not grant control over an unrelated process. Retry a command that the auto-restore deadline interrupts after you open a new shields-down window.

How Gateway Lifecycle Control Works

Built-in OpenClaw and Hermes images support two direct-container lifecycle topologies.

The managed controller authenticates the host lifecycle action and prevents PID reuse from redirecting its signal. It cannot prove process provenance against a malicious process running under the same sandbox UID, and it does not create gateway and agent UID isolation. Mutable managed config retains the trust and time-of-check/time-of-use limits of managed cold start. For Hermes, the managed controller always preflights the secret boundary and verifies the strict root-owned hash when the config and environment are locked. This compatibility path remains necessary because the OpenShell-managed PID 1 topology owns the nonroot supervisor and shared gateway-agent UID. Remove it only after the minimum supported OpenShell provides a root-owned lifecycle supervisor or a gateway UID distinct from the agent, then migrate both built-in agents to that boundary.

For built-in OpenClaw and Hermes controllers, a successful recover or gateway restart response supplies the initial authenticated gateway-health proof. After the settle window, NemoClaw sends one read-only authenticated probe through the same controller before it declares success. The controller rechecks the exact managed child, listener, HTTP health, and required auxiliary processes from inside the gateway network namespace without restarting the gateway. A failed managed probe is authoritative and cannot be overridden by an outer-namespace HTTP response. Custom agents that recover through an SSH script do not use this controller probe and continue to poll ordinary gateway health.

The nonroot Hermes supervisor continuously repairs the gateway, API relay, dashboard, dashboard relay, and gateway log stream. Four consecutive gateway health failures trigger exact-child recovery. Five unexpected gateway exits or failed replacement candidates within 60 seconds quarantine relaunch until the sandbox is recreated. An authenticated host action authorizes one exit bound to the exact gateway process ID and kernel start identity while the exact root controller process remains live, so deliberate gateway restart and controller-driven replacement do not consume that crash budget. The authorization records host intent for that exact exit; it does not claim that the host signal was the only possible cause of process termination in the shared-UID topology. After the in-sandbox processes are healthy, the host repairs only the host-side OpenShell forwards.

The host selects the matching controller automatically for recover and gateway restart. Ordinary openshell sandbox exec and manual in-sandbox relaunch are not fallback paths. A current built-in image supports both the direct root-entrypoint and OpenShell-managed topologies. An arbitrary nonroot entrypoint that does not match the managed OpenShell process shape fails closed with privileged control unavailable. Kubernetes and other deployments without a matching direct container also fail closed with privileged control unavailable. Older images without the matching supervisor or managed controller helper must be updated with nemohermes <name> rebuild --yes.

Related Topics

The table above consolidates details from these topic pages:

• Manage Sandbox Lifecycle for the full rebuild, re-onboard, and upgrade workflow.
• Switch Inference Providers for the runtime route and rebuild paths for provider and model changes.
• Customize Network Policy and Approve Network Requests for runtime policy editing and operator approval flow.
• Security Best Practices for the per-attack-surface posture table that this page complements.
• CLI Commands Reference for the full flag surface for every nemohermes and nemoclaw command, including the environment variables that affect runtime behavior.