Manage SandboxesConfigure Sandboxes

Understand Runtime Changes

View as Markdown

Use this matrix to choose the operation that makes a sandbox change take effect. Some changes apply at runtime, while image and filesystem changes require 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 nemohermes <name> recover
Hermes plugin code, Langfuse settings, or other startup-only runtime configRuntime after Hermes or the sandbox user changes valid mutable config and the gateway restartsChange Hermes-owned config in the sandbox; use a supported host config command for settings owned by NemoClaw, 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; valid Hermes-owned changes are adopted on restart, while image, policy, and channel changes still require rebuildChange Hermes-owned settings in the sandbox; use nemohermes inference set or nemohermes <name> config set for settings owned by NemoClaw so its registry stays aligned

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. Valid changes made by Hermes or the sandbox user are authoritative. Startup and restart validate the secret boundary, safe paths, and a stable transaction snapshot, then adopt the current mutable configuration. A direct config change alone does not block lifecycle operations.

Use supported host config and inference commands for settings that NemoClaw owns so its registry stays aligned with the runtime. Those commands can report a registry mismatch for the operation they manage, but generic startup, restart, recovery, health, probe, and connect paths do not enforce registry equality.

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 mutable paths. The root-only mutation lock stays held through every host-side Hermes config write.

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.

Mutable Agent State

NemoClaw does not provide post-provisioning immutability for agent configuration or persistent state. OpenShell remains authoritative for sandbox filesystem and network policy enforcement. An agent process can change files that its sandbox identity can write.

For Hermes, direct changes to valid mutable configuration do not block restart. Lifecycle validation can still refuse raw secrets, unsafe paths, raced snapshots, or missing or malformed transaction metadata. Use supported host commands for settings owned by NemoClaw so its registry and the running Hermes projection remain aligned for those host-managed operations.

NemoClaw serializes host-side gateway recovery, config and inference writes, snapshots, policy updates, channel updates, and sandbox destruction for each sandbox. This mutation lock prevents concurrent host operations from racing on the same registered sandbox.