Manage SandboxesConfigure Sandboxes

Understand Runtime Changes

View as Markdown

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

ItemWhen the change takes effectHow to change it
Inference providerRuntime route changes apply immediately; rebuild if you need to rebake model metadata into the imagenemohermes inference set for route changes, or nemohermes <name> rebuild after changing build-time settings
Inference model on the current providerHot-reloadable through the Hermes config sync pathnemohermes inference set
Agent runtimeRe-onboard required because the agent and state layout are baked at onboardnemohermes onboard --recreate-sandbox or nemoclaw onboard --agent openclaw --recreate-sandbox
Network policy presetRuntime on the next request; rebuild only if the preset adds bind-mounted secretsnemohermes <name> policy-add <preset> or policy-remove <preset>
Network allowlistRuntime on the next requestopenshell policy set or the interactive approval prompt at the gateway
Channel tokensRebuild required because the channel configuration and credential attachment are created during onboarding or rebuildnemohermes <name> channels add <channel>, then accept the rebuild prompt
Channel enable or disableRebuild required because /sandbox/.hermes/.env and Hermes config are baked at image build timenemohermes <name> channels stop <channel>, then rebuild
API or dashboard forward portRuntime; the host-side forward is re-resolved on the next connectnemohermes <name> connect or openshell forward start
Hermes plugin code, Langfuse settings, or other startup-only runtime configRuntime after a supported host-side update and gateway restartBake plugin code into the image or use a supported host config command, then run nemohermes <name> gateway restart
Web search providerRebuild required because onboarding bakes web.backend, the environment placeholder, and the credential attachment into the imageSet NEMOCLAW_WEB_SEARCH_PROVIDER=tavily or none, then rerun onboarding and recreate the sandbox
Filesystem layoutLocked at creationRe-onboard with nemohermes onboard --recreate-sandbox
Sandbox nameLocked at creationRe-onboard with a different --name
GPU passthrough or device selectorLocked at creationRe-onboard with --gpu or --sandbox-gpu-device
Hermes config.yaml keysMixed; inference and supported config keys can be patched by host commands, while image, policy, and channel changes still require rebuildUse nemohermes inference set or nemohermes <name> 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. 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.

Timed Shields Windows

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.