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. 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 <name> shields down before the change, then restore lockdown with nemohermes <name> 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 <name> 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.