> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemoclaw/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemoclaw/_mcp/server. # Understand Runtime Changes > Determine which NemoClaw sandbox changes apply at runtime and which require a rebuild or re-onboard. Use this matrix to choose the operation that makes a sandbox change take effect. 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. ## Hermes Runtime Changes | Item | When the change takes effect | How to change it | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | | Inference provider | Runtime route changes apply immediately; rebuild if you need to rebake model metadata into the image | `nemohermes inference set` for route changes, or `nemohermes rebuild` after changing build-time settings | | Inference model on the current provider | Hot-reloadable through the Hermes config sync path | `nemohermes inference set` | | Agent runtime | Re-onboard required because the agent and state layout are baked at onboard | `nemohermes onboard --recreate-sandbox` or `nemoclaw onboard --agent openclaw --recreate-sandbox` | | Network policy preset | Runtime on the next request; rebuild only if the preset adds bind-mounted secrets | `nemohermes policy add ` or `policy remove ` | | Network allowlist | Runtime on the next request | `openshell policy set` or the interactive approval prompt at the gateway | | Channel tokens | Rebuild required because the channel configuration and credential attachment are created during onboarding or rebuild | `nemohermes channels add `, then accept the rebuild prompt | | Channel enable or disable | Rebuild required because `/sandbox/.hermes/.env` and Hermes config are baked at image build time | `nemohermes channels stop `, then rebuild | | API or dashboard forward port | Runtime; the host-side forward is re-resolved on the next `connect` | `nemohermes connect` or `openshell forward start` | | Hermes plugin code, Langfuse settings, or other startup-only runtime config | Runtime after a supported host-side update and gateway restart | Bake plugin code into the image or use a supported host config command, then run `nemohermes gateway restart` | | Web search provider | Rebuild required because onboarding bakes `web.backend`, the environment placeholder, and the credential attachment into the image | Set `NEMOCLAW_WEB_SEARCH_PROVIDER=tavily` or `none`, then rerun onboarding and recreate the sandbox | | Filesystem layout | Locked at creation | Re-onboard with `nemohermes onboard --recreate-sandbox` | | Sandbox name | Locked at creation | Re-onboard with a different `--name` | | GPU passthrough or device selector | Locked at creation | Re-onboard with `--gpu` or `--sandbox-gpu-device` | | Hermes `config.yaml` keys | Mixed; inference and supported config keys can be patched by host commands, while image, policy, and channel changes still require rebuild | Use `nemohermes inference set` or `nemohermes config set` so the config and root-owned trust anchor change together | The runtime source of truth 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 those files or their hash files directly and then expect `gateway restart` to establish the bytes as trusted. Use supported host config and inference commands so NemoClaw updates the managed config metadata together. 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. Shields up keeps `/sandbox/.hermes/profiles/dashboard-home/` sandbox-owned at mode `0700` so the dashboard can update its isolated profile. Other Hermes profiles remain read-only during lockdown. The root-only mutation lock stays held through every Hermes host-side config write. On the sealed-plan and compatibility Shields paths, it also stays held through the full `shields up` or `shields down` filesystem transition and verification, and lifecycle recovery that needs to seal those paths. Current NemoClaw-managed Hermes images on the Docker driver use the `provider-state-mutation-v2` runtime provider state mutation contract for Shields filesystem transitions. NemoClaw selects this contract only when all these conditions apply: * The registered sandbox is a managed Hermes image. * The sandbox registry records its lifecycle generation. * The image exposes the exact root-owned capability installed by NemoClaw. An older managed image uses the sealed-plan transition only after NemoClaw proves that the capability is absent. A custom image, including a legacy Dockerfile workflow, remains on its existing sealed-plan or compatibility contract and cannot opt in by adding a similarly named file. An invalid capability that is present fails closed and requires a rebuild with a current managed image. The Docker provider binds each transition to the registered lifecycle generation, exact container, qualified Docker engine authority, mount namespace, `/sandbox/.hermes` inode, AgentDefinition-derived plan and projection, target posture, rollback posture, and fresh nonce. Before the provider fence becomes active, NemoClaw drains any earlier privileged sandbox execution lease. While the fence is active, new direct-container, SSH, and OpenShell command transports are rejected before a sandbox command starts. The installed root-owned controller and Hermes publisher apply and verify the exact target posture, then the provider starts only the bound Hermes entrypoint and proves the replacement gateway and startup checkpoint before it releases the fence. The owner-only ledger under `~/.nemoclaw/state/runtime-provider-lifecycle/` survives a host controller restart and remains authoritative for recovery of the exact target. The next Shields command, including `shields status`, must recover a retained fence before it can report or change posture. Hermes startup also checks the image-owned startup gate before it reads mutable state and remains held when the runtime provider state mutation is active or cannot be authenticated. While recovery is incomplete, do not: * Delete the ledger. * Kill a held entrypoint. * Use a manual container command to bypass the fence. 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 shields down` before the change, then restore lockdown with `nemohermes shields up`. ## Timed Shields Windows NemoClaw serializes host-side gateway recovery, 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. ### Restore Lockdown After Expiration If the timeout expires while a mutation is changing sandbox state, auto-restore closes the per-sandbox lifecycle deadline gate. The gate blocks new mutations and waits for the recorded live owner to release its exact lock generation. NemoClaw does not signal that process because portable process inspection cannot prove that all descendants stopped. After the owner releases the lock, auto-restore restores the restrictive policy and configuration posture. The ownership check includes both the process ID and process start identity so PID reuse does not grant control over an unrelated process. ### Complete Exact-Generation Recovery An interactive command can take over an expired timer. Interactive recovery has separate transition-takeover and restoration phases. Each phase makes up to 7 attempts and waits 5 seconds between failures, for up to 30 seconds of retry delay per phase. Detached recovery uses one 7-attempt budget across deadline setup, main-generation publication, and restoration. The deadline gate remains closed during those attempts. If restoration cannot commit, NemoClaw attempts to record durable containment. If that containment commit also fails, NemoClaw retains any exact lifecycle and deadline gates it already owns. A state-directory failure that prevented gate publication also prevents normal mutation-lock acquisition. Correct the reported state-directory write failure, then run `nemohermes shields status` to resume recovery or receive exact-generation recovery guidance. When recovery cannot complete, an interactive command returns an error, or the detached timer exits with a failure status. NemoClaw also records durable containment when an owner exits before it can prove that the owner's descendants stopped, or when ownership becomes ambiguous. Durable containment, retained exact gates, or the fail-closed state-directory error keeps new mutations blocked until you complete exact-generation operator recovery. A `--dry-run` run of a `channels` or `policy` command takes no mutation lock, so you can still preview the change while mutations are blocked. Stop all NemoClaw processes for the sandbox, then follow the paths, identities, tokens, and removal order in the reported error. Verify each recorded generation is unchanged, remove only the exact stale generations first, and remove the exact containment generation last. ### Preserve Managed MCP Policy Before a manual Shields transition replaces a policy, NemoClaw requires exact Model Context Protocol (MCP) agreement among the sandbox registry, generated-policy record, and live gateway policy. `shields down` carries the proven managed MCP policy entries into the relaxed policy. Restoration removes snapshot-time managed MCP entries before it overlays current exact entries. If exact agreement is absent, a manual Shields transition refuses the replacement policy. At an expired deadline, auto-restore omits unproven managed MCP policy entries, restores lockdown, and records the omission count in its audit entry. An MCP server removed during the shields-down window stays removed. A surviving server keeps its recorded endpoint and address pins while its policy ownership remains exact. ## Related Topics * [Understand Gateway Lifecycle Control](understand-gateway-lifecycle-control) for `recover` and `gateway restart` trust boundaries. * [Recover and Rebuild Sandboxes](../operate-sandboxes/recover-and-rebuild-sandboxes) for the operational recovery workflow. * [Switch Inference Providers](../../inference/manage-inference/switch-providers) for model and provider changes. * [Customize Network Policy](../../network-policy/customize-network-policy) for runtime policy editing. * [Security Best Practices](../../security/best-practices) for the broader security posture. * [CLI Commands Reference](../../reference/commands) for command flags and environment variables.